Error Trapping (⎕EA, ⎕EC)

Note: The use of ⎕EA is now deprecated, unless you need to retain compatibility with IBM's APL2. For most cases, we recommend that you use the structured-control error trapping mechanism (:Try :CatchIf :CatchAll :EndTry) instead.

⎕EA and ⎕EC provide statement-level error trapping, using a syntax which is compatible with IBM's APL2.

⎕EA allows an APL expression to be executed under error trapped conditions. The right argument is a character vector containing an expression to be executed. The left argument is a character vector containing the APL expression to be executed if the right argument encounters an error or is interrupted.

If an error occurs in the alternate code of a ⎕EA call this is not trapped but is handled in the default (or non-trapped) manner.

⎕EC allows an APL expression to be executed under error trapped conditions. The right argument is a character vector containing the line of code. If the expression contains an error or is interrupted then ⎕EC returns a return code plus the error code given by ⎕ET.

⎕ET is a numeric vector containing the error code associated with the last error that occurred. The first integer indicates the general class of the error. The second integer indicates the specific nature of the error. ⎕ET can be used to identify the possible source of an error.

⎕EM is a character matrix containing the error message associated with the last error which occurred. The message contains the error description, the function name and line number where the exception occurred, the line of APL code where execution stopped, with a caret (^) pointing to the last character interpreted.

⎕ES is a function which simulates an error and causes execution of the active function or operator to stop. In the monadic form, the right argument is a two element numeric vector containing the error code. If the code is defined then the appropriate error description is displayed. If the code is undefined then no error description is displayed in the error message. If the right argument is zero or empty then no error is signalled. If the right argument is a character vector then that vector is displayed as the error description. In the dyadic form the left argument is the character vector error description and the right argument is the integer error vector.

If an error occurs in a locked function then the error message just gives the name of the function, with no internal details. The error description will usually be DOMAIN ERROR (sometimes WS FULL or INTERRUPT). ⎕ET similarly gives no indication of the true nature of the error. The same is true if a locked function calls an unlocked function which encounters an error. No internal details of the error are given. If a function containing a ⎕EA or ⎕EC statement is locked this does not affect the behaviour of the error handling internal to the function.

In the first example, ⎕EA is used to handle the error:

             ∇R←A DIVIDE B
       [1]   R←'A' ⎕EA 'A÷B'
             ∇   
             3 DIVIDE 2
       1.5
             3 DIVIDE 0              (Alternate execution invoked - returns
       3                              left argument)

As an alternative, ⎕ES is used:

             ∇R←A DIVIDE B
       [1]   'ATTEMPT TO DIVIDE BY ZERO ERROR' ⎕ES(B=0)/5 4
       [2]   R←A÷B
             ∇   
             3 DIVIDE 4
       0.75
             3 DIVIDE 0              (Error signalled)
       ATTEMPT TO DIVIDE BY ZERO ERROR
             3 DIVIDE 0
             ^
             ⎕EM                     (⎕EM contains the message matrix)
       ATTEMPT TO DIVIDE BY ZERO ERROR
             3 DIVIDE 0
             ^
             ⍴⎕EM
       3 31
             ⎕ET                     (⎕ET contains the appropriate codes)
       5 4

Finally, controlled execution allows the results and error messages (if any) to be studied:

             ⎕EC '3÷4'
       1  0 0  0.75
             ⎕EC '3÷0'
       0  5 4  DOMAIN ERROR          (Three element nested vector result)
                     3÷0
                     ^
             ⍴⎕EC '3÷0'
       3