This is a non-simple vector. An item of ⎕TRAP specifies an action to be taken when one of a set of events occurs. ⎕TRAP has workspace scope.
An item of ⎕TRAP is a 2 or 3 element vector whose items are simple scalars or vectors in the following order:
- an integer vector whose value is one or more event codes selected from the list in the Figure on the following two pages.
- a character scalar whose value is an action code selected from the letters C, E, N or S.
- if element 2 is the letter C or E, this item is a character vector forming a valid APL expression or series of expressions separated by ⋄. Otherwise, this element is omitted.
An EVENT may be an APL execution error, an interrupt by the user or the system, a control interrupt caused by the ⎕STOP system function, or an event generated by the ⎕SIGNAL system function.
When an event occurs, the system searches for a trap definition for that event. The most local ⎕TRAP value is searched first, followed by successive shadowed values of ⎕TRAP, and finally the global ⎕TRAP value. Separate actions defined in a single ⎕TRAP value are searched from left to right. If a trap definition for the event is found, the defined action is taken. Otherwise, the normal system action is followed.
The ACTION code identifies the nature of the action to be taken when an associated event occurs. Permitted codes are interpreted as follows:
Table 27: Trappable Event Codes
| Code | Event |
|---|---|
| 0 | Any event in range 1-999 |
| 1 | WS FULL |
| 2 | SYNTAX ERROR |
| 3 | INDEX ERROR |
| 4 | RANK ERROR |
| 5 | LENGTH ERROR |
| 6 | VALUE ERROR |
| 7 | FORMAT ERROR |
| 10 | LIMIT ERROR |
| 11 | DOMAIN ERROR |
| 12 | HOLD ERROR |
| 16 | NONCE ERROR |
| 18 | FILE TIE ERROR |
| 19 | FILE ACCESS ERROR |
| 20 | FILE INDEX ERROR |
| 21 | FILE FULL |
| 22 | FILE NAME ERROR |
| 23 | FILE DAMAGED |
| 24 | FILE TIED |
| 25 | FILE TIED REMOTELY |
| 26 | FILE SYSTEM ERROR |
| 28 | FILE SYSTEM NOT AVAILABLE |
| 30 | FILE SYSTEM TIES USED UP |
| 31 | FILE TIE QUOTA USED UP |
| 32 | FILE NAME QUOTA USED UP |
| 34 | FILE SYSTEM NO SPACE |
| 35 | FILE ACCESS ERROR - CONVERTING FILE |
| 38 | FILE COMPONENT DAMAGED |
| 52 | FIELD CONTENTS RANK ERROR |
| 53 | FIELD CONTENTS TOO MANY COLUMNS |
| 54 | FIELD POSITION ERROR |
| 55 | FIELD SIZE ERROR |
| 56 | FIELD CONTENTS/TYPE MISMATCH |
| 57 | FIELD TYPE/BEHAVIOUR UNRECOGNISED |
| 58 | FIELD ATTRIBUTES RANK ERROR |
| 59 | FIELD ATTRIBUTES LENGTH ERROR |
| 60 | FULL-SCREEN ERROR |
| 61 | KEY CODE UNRECOGNISED |
| 62 | KEY CODE RANK ERROR |
| 63 | KEY CODE TYPE ERROR |
| 70 | FORMAT FILE ACCESS ERROR |
| 71 | FORMAT FILE ERROR |
| 72 | NO PIPES |
| 76 | PROCESSOR TABLE FULL |
| 84 | TRAP ERROR |
| 90 | EXCEPTION |
| 92 | TRANSLATION ERROR |
| 200-499 | Reserved for distributed auxiliary processors |
| 500-999 | User-defined events |
| 1000 | Any event in range 1001-1008 |
| 1001 | Stop vector |
| 1002 | Weak interrupt |
| 1003 | INTERRUPT |
| 1005 | EOF INTERRUPT |
| 1006 | TIMEOUT |
| 1007 | RESIZE (Dyalog APL/X, Dyalog APL/W) |
| 1008 | DEADLOCK |
See Trap Statement for an alternative 'control structured' error trapping mechanism.
Examples
⎕TRAP←⊂(3 4 5) 'E' 'ERROR' ⋄ ⍴⎕TRAP 1 ⎕TRAP 3 4 5 E ERROR
Items may be specified as scalars. If there is only a single trap definition, it need not be enclosed. However, the value of ⎕TRAP will be rigorously correct:
⎕TRAP←11 'E' '→LAB' ⎕TRAP 11 E →ERR ⍴⎕TRAP 1
The value of ⎕TRAP in a clear workspace is an empty vector whose prototype is
0⍴(⍬ '' ''). A convenient way of cancelling a ⎕TRAP definition is:
⎕TRAP←0⍴⎕TRAP
Event codes 0 and 1000 allow all events in the respective ranges 1-999 and 1000-1006 to be trapped. Specific event codes may be excluded by the N action (which must precede the general event action):
⎕TRAP←(1 'N')(0 'E' '→GENERR')
The 'stop' action is a useful mechanism for cancelling trap definitions during development of applications.
The 'cut-back' action is useful for returning control to a known point in the application system when errors occur. The following example shows a function that selects and executes an option with a general trap to return control to the function when an untrapped event occurs:
∇ SELECT;OPT;⎕TRAP [1] ⍝ Option selection and execution [2] ⍝ A general cut-back trap [3] ⎕TRAP←(0 1000)'C' '→ERR' [4] INP:⍞←'OPTION : ' ⋄ OPT←(OPT≠' ')/OPT←9↓⍞ [5] →EX⍴⍨(⊂OPT)∊Options ⋄ 'INVALID OPTION' ⋄ →INP [6] EX:⍎OPT ⋄ →INP [7] ERR:ERROR∆ACTION ⋄ →INP [8] END: ∇
User-defined events may be signalled through the ⎕SIGNAL system function. A user-defined event (in the range 500-999) may be trapped explicitly or implicitly by the event code 0.
Example
⎕TRAP←500 'E' '''USER EVENT 500 - TRAPPED''' ⎕SIGNAL 500 USER EVENT 500 - TRAPPED