Overview of error handling and the State Indicator

Errors in calculator mode

If you enter a statement containing an error in calculator mode, APL responds with an error message. For example, if you attempt an operation on unsuitable data, you normally get a domain error:

      1 1 0 11 ∨ 1 1 0 0
DOMAIN ERROR
      1 1 0 11 ∨ 1 1 0 0
      ^

This error has occurred because the OR primitive function operates only on values 0 and 1, not 11 as supplied in the left argument. As the example shows, the statement containing the error is displayed with an error indicator (^) marking the point at which the APL interpreter detected the error. Depending on the version of APLX you are running, and your system preference settings, error messages are usually displayed in red, as shown above.

To correct an error in calculator mode, simply retype the statement correctly, or alternatively use the recall-line key (usually Ctrl-Up Arrow, or Cmd-Up Arrow on the Macintosh) to recal1 the statement, then edit it and re-enter it. In most versions of APLX, you can also correct it directly in the window, and then press Return or Enter to re-evaluate it.

Errors in user-defined functions or operators

If an error is encountered during execution of a user-defined function or operator, execution stops at that point. The appropriate error message is displayed in the session window, followed on a separate line, by the name of the function containing the error, the line number at which execution stopped and the statement itself:

LENGTH ERROR
CALC[2] R←(X,Y)-1 2 3
          ^

The above example shows that execution stopped in function CALC at line 2.

The Debug Window

As well as displaying the error in the Session Window, desktop editions of APLX will normally display the Debug Window if an error occurs in a user-defined function, operator, or class method. This shows the function or operator in which the error occurred, and allows you to edit the line immediately and continue:

In this example, an error has occurred on line 13 of the function, so execution has stopped there. Normally you would edit the incorrect line in situ (in this case correcting the spelling mistake 'jeva' instead of 'java'), and then press the Run button (the solid triangular arrow) to continue execution. You can also resume at a different line (by dragging the small green position indicator, currently on line 13, or by using the 'Resume at line' control), or abandon the function by pressing the Quit (red cross) button.

Interrupts

A function or operator can also be halted by the user hitting the interrupt key (usually Ctrl-Break on Windows, Cmd-Period on the Macintosh, or Ctrl-C under Linux). A single interrupt causes APLX to complete the line of code it is executing before stopping. Two interrupts in quick succession cause it to stop as soon as it can, even if it is executing a single calculation which takes a long time (for example inverting a matrix with ⌹). The ⎕CONF system function allows interrupts to be disabled.

Again, on desktop editions of APLX, the Debug window will appear if you interrupt a user-defined function, operator or method.

The State Indicator

It may be that the function at which execution halted was called by another function. You can inspect a system variable called ⎕SI, the State Indicator, or use the system command )SI, to see the state of play:

      ⎕SI
C[2] *
B[8]
A[5]

This display (often referred to as the 'SI Stack') tells you that function C was called from line 8 of function B which was itself called from line 5 of function A.

The asterisk on the first line means that the function named on that line is 'suspended'. The other functions are 'pendent'; their execution cannot be resumed till execution of function C is completed.

If at this point you executed another function, D, which called function E, and at line 3 of E a further error occurred, the state indicator would look like this;

E[3] *
D[6]
C[2] *
B[8]
A[5]

Effectively it contains records of two separate sequences of events;

E[3] *
D[6]
-------------------
C[2] *
B[8]
A[5]

You can clear the top level of the state indicator (i.e. the record of the most recent sequence) by entering the branch symbol → on its own;

      →
      ⎕SI
C[2] *
B[8]
A[5]

In this example, another → would clear the remaining level (now the top level) and restore the state indicator to its original (empty) state.

Alternatively, you can clear the entire state indicator at any stage by using the system command )SICL.

Action after suspended execution

If you want to resume execution at the point where it stopped you can do so from the Debug Window as described above, or by using the symbol → followed by the line number. If, for example, execution halted at line 3 of E, to resume at that point you could type:

      →3

A system variable ⎕CL contains the current line number, so you could achieve the same effect by typing:

      →⎕CL

You don't have to continue from the point where execution was suspended. You can specify a line other than the current line:

      →4

or

      →⎕CL+1

Equally, you can specify execution of a different function.

Editing suspended and pendent functions

What's perhaps most likely after an error in execution of a function is that you'll want to edit the function containing the error. (It's marked with * in the SI display and, as you may remember, is described as a suspended function.) This is done in the normal way by using )EDIT (or using ∇ and the function name to enter the del editor), and then making the required correction, or directly in the Debug Window.

It is possible that after editing the function you may get this message:

      SI DAMAGE

This indicates that you've done something which makes it impossible for the original sequence of execution to be resumed. No action is necessary other than to use the system command )SICL to clear the state indicator.

What you cannot do after a halt in execution is to edit any of the pendent functions. They are the functions in the state indicator display that are not marked with an asterisk:

      ⎕SI
E[3] *
D[6]
C[2] *
B[8]
A[5]

An attempt to edit a pendent function using the Del editor will produce a DEFN ERROR:

      ∇A
DEFN ERROR
      ∇A
       ^

Similarly, you can edit the function using )EDIT A but APLX will not let you save the changes because the function is pendent. You will get the error message "Cannot fix object - Function is on )SI stack"

If you want to edit a pendent function, simply clear the state indicator using )SICL.

Error trapping

You can specify in advance what should happen if an error occurs during execution, in which case that error will not cause execution to stop. For example, if you wrote a function which invited the user to type in some numeric data, you might foresee the possibility that he or she would type non-numeric data instead. This would cause an error. APLX allows you to 'trap' the error at runtime. There are two main ways of doing this:

• A block of code (including any functions called from within the block) can be executed under error-trapped conditions using :Try..:EndTry. If an error occurs, control passes to the :CatchIf or :CatchAll sections.

• Simple error trapping on a single line or expression can be achieved using ⎕EA, which allows an alternate line of code to be executed in the event of an error, or ⎕EC, which executes code under error trapped conditions and returns a series of result codes. These are compatible with IBM's APL2.

APLX also implements the older ⎕ERX style of error-trapping, which specifies a line to be branched to if an error occurs. Use of ⎕ERX is not recommended for new applications.

In general, it is probably best not to mix different styles of error-trapping in a single function. However, if you do, and an error occurs in a line where more than one error trap is live, then the error trap which will take effect is the first of:

1. ⎕EA
2. ⎕EC
3. :Try... :EndTry
4. ⎕ERX

Error-related system functions

A number of system functions are available for finding out where an error occurred and why, or for simulating an error. These include:

• ⎕ERS which can be used to signal an error (see also the APL2-compatible equivalent ⎕ES).

• ⎕ERM which displays the current error message (see also the APL2-compatible equivalent ⎕EM).

• ⎕LER which contains the error code and line number for the most recent error. Each kind of event that can be trapped has an error code. A DOMAIN ERROR, for example, is number 11. (See also ⎕ET which holds the last error code in a format compatible with APL2).

Other debugging aids

• ⎕STOP allows you to set 'breakpoints', i.e. specify that a function should stop at a given line. (Normally, the Debug Window will then be invoked). On desktop editions of APLX, you can also set or clear breakpoints by clicking in the line-number area of an Edit, Debug or WS Explorer window.

• ⎕TRACE can be used to display a record of the results when certain 'traced' lines are executed.