Error Trapping Tutorial for APL.68000

Transcribed from the printed issue; not yet reviewed. Read it in the PDF of the issue, page 96

Background¶

When developing functions, or indeed running programs that one has written oneself, the ability to examine suspended functions and alter them before resuming execution is one of the major attractions of APL as a programming environment. When a system has been handed over to end-users (even other programmers) or indeed has been transformed into a packaged piece of software it is then unsatisfactory to report an APL error message and exit to calculator mode. It is almost certainly preferable to issue some helpful message and either attempt to correct or record the exact source of the error.

Trapping Simple Errors¶

APL.68000 has a simple but highly effective scheme to modify or control standard APL error reporting. A group of system functions are defined which allow the programmer to specify what actions to take in the event of an error, and which pass information to the programmer about the source and nature of an error. In addition the usual error messages may be altered or new ones introduced. The functions are:

The functions are complementary in the sense that a programmer will probably need to use them all to implement an effective scheme of error trapping.

The error trap is set via the system function ⎕ERX:

    ∇FOO
[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, and the function returns the previous trap value. When an error occurs, the normal error display of error message and line number is suppressed. A line number of 0 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 appendix) 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 APL.68000 would normally print with a Carriage Return (⎕R) between lines. ⎕ERM only works if error trapping is set. If error trapping is not set, ⎕ERM returns an empty vector. 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 quite common 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
      ∇

WARNING¶

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, CTRL-C, 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 an 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 APL.68000 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              .... no response (the function has been halted)

Appendix: Error Code Numbers¶

Errors within APL.68000 are allocated codes in the range 1 to 51. Some are undefined, but may still be used by ⎕ERS.