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] ’
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)
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)