Error Trapping (⎕ERX)

Note: The use of ⎕ERX is now deprecated. We recommend that you use the structured-control error trapping mechanism (:Try :CatchIf :CatchAll :EndTry) instead.

The system function ⎕ERX allows you to set an error trap which will cause control to pass to a given line in a function, if an error occurs:

             ∇FOO;Z
       [1]   Z←⎕ERX LABEL        Z will contain the previous value of ⎕ERX

Control will pass to LABEL when an error occurs in this function, (or a called function which does not have error trapping set). ⎕ERX returns the previous trap value. When an error occurs the normal error display of error message and line number is suppressed. A right argument of 0 to ⎕ERX suppresses the trap.

A non-error trapped function, called by an error trapped function, will behave as if it is locked. A branch will again take place to the designated line in the calling function.

Having transferred execution to an error handling routine, it is important to know the type of error that has occurred and also where it occurred. Sometimes the APL function can attempt some sort of corrective action, but often the error is logged and some message passed to the user.

The function ⎕LER returns the error code number (see below) and the line where the error took place, as a two element vector. If, when error trapping is active, an error occurs, the line number will refer to the most recent function to which the error has been propagated (i.e. the error trapped function).

To read the error message, the system function ⎕ERM shows the character vector that APLX would normally print with a Carriage Return (⎕R) between lines. Inside a locked function, ⎕ERM will show the error message that would be displayed if the function were unlocked. Outside a locked function, however, ⎕ERM is set to be an empty vector for security reasons.

             ∇FOO;Z;ER
       [1]   Z←⎕ERX ERR
       [2]   100×'A'
       [3]   'THIS LINE WILL NOT BE REACHED'
       [4]   ERR: 'INTERNAL PROGRAM ERROR'
       [5]   ER←⎕R ⎕BOX ⎕ERM ⍝ FORM THE ⎕ERM VECTOR INTO A MATRIX
       [6]   'ERROR MESSAGE:  ',(ER[1;]),' ON FUNCTION LINE ',⍕⎕LER[2]
             ∇

Example of Error Trapping

It is possible to encounter the error message WS FULL if you try to carry out operations using large arrays. Rather than have your function stop, you might like to check for this error state and undertake corrective action.

             ∇ADDUP;X;DATA
       [1]  ⍝ADDS UP ALL THE NUMBERS UP TO THAT ENTERED
       [2]  X←⎕ERX ERR ⍝              X IS USED TO HIDE THE RETURN FROM ⎕ERX
       [3]  START:'ENTER A NUMBER'
       [4]  DATA←⌊⎕  ⍝                MAKE IT THE NEXT LOWEST INTEGER
       [5]  'THE SUM OF THE FIRST ',(⍕DATA),' NUMBERS IS: '
       [6]  +/⍳DATA
       [7]  →0   ⍝                    END OF THE FUNCTION
       [8]  ERR:→(1≠1↑⎕LER)/REALERR ⍝ ERR CODE 1 IS WS FULL
       [9]  'THE NUMBER YOU ENTERED WAS TOO BIG TO USE, TRY AGAIN'
       [10] →START
       [11] REALERR: ⍝                AN ERROR HAS OCCURRED WHICH IS NOT WS FULL
       [12] 'ERROR TYPE ',(⍕1↑⎕LER),' ON LINE ',⍕1↓⎕LER
       [13] 'MESSAGE IS:'
       [14] ⎕ERM
       [15] ∇

Make sure that you have some escape route from the error trap routine, otherwise any error within that section of the function will cause an uninterruptible loop. (The Interrupt key or menu item also causes an error - type 13)

Error Signalling

If some error report is to be made to the user of the system, it is useful to be able to modify the usual APL error messages, which may not be very meaningful to the end user. This can be carried out by the function ⎕ERS. ⎕ERS can be used to force a standard APL error report, or, if used with a character left argument, it will display those characters and assign the error code in its right argument to ⎕LER.

Here is an example where ⎕ERS is used to make sure that the user hasn't hit the interrupt key accidentally:

             ∇FOO;DATA
       [1]   ⎕ERX ERR ⍝                  SET ERROR TRAP
       [2]   L:'ENTER YOUR EXPRESSION'
       [3]   DATA←⍞
       [4]   'THE RESULT IS:'
       [5]   ⍎ DATA
       [6]   →L
       [7]   ERR: →(13≠1↑⎕LER)/NOTINT⍝   NOT INTERRUPT
       [8]   'DID YOU MEAN TO HIT INTERRUPT? (Y/N)'
       [9]   →('Y'≠1↑⍞)/L ⋄ ⎕ERS 13 ⍝ SIGNAL IF CONFIRMED
       [10]  NOTINT: ⎕ERS 1↑⎕LER ⍝       SIGNAL OTHER ERRORS
             ∇

If the right argument is a number in the range 1 to 51, ⎕ERS will display the standard APLX error message. As you will see later in the chapter, some error numbers are undefined, and in these cases ⎕ERS will display UNKNOWN ERROR TYPE SIGNALLED. If the right argument is an empty vector, no error is signalled. Used with a character left argument, the error message may be altered. An empty vector left argument ('') will suppress the error message.

             ∇R←AV B
       [1]   'NUMERIC ARGUMENT PLEASE' ⎕ERS (4=⎕DR B)/8
       [2]   R←(+/B)÷⍴B
             ∇

             AV 1 2 3
       2
             AV 'ABC'
       NUMERIC ARGUMENT PLEASE
             AV
             ^
             ⎕LER
       8 0
             ⎕SI
       (empty response)              (the function has been halted)