Trap Event ⎕TRAP

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:

1. an integer vector whose value is one or more event codes selected from the list in the Figure on the following two pages.
2. a character scalar whose value is an action code selected from the letters C, E, N or S.
3. 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 1: Trappable Event Codes

C	Cutback	The state indicator is 'cut back' to the environment in which the ⎕TRAP is locally defined (or to immediate execution level).  The APL expression in element 3 of the same ⎕TRAP item is then executed.
E	Execute	The APL expression in element 3 of the same ⎕TRAP item is executed in the environment in which the event occurred.
N	Next	The event is excluded from the current ⎕TRAP definition.  The search will continue through further localised definitions of ⎕TRAP .
S	Stop	Stops the search and causes the normal APL action to be taken in the environment in which the event occurred.

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 Programmer's Guide: "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