Open topic with navigation

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.  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 50: 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 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