TRAP

ANSI

The TRAP instruction is similar to the CALL instruction except that it only initiates the specified subroutine if a defined event occurs after the TRAP was executed. Some of the defined events normally result in program termination. It uses one of the following formats:

(1)	[label]	TRAP	{routine} [GIVING {message}] [NORESET] IF {event}
(2)	[label]	TRAP	{routine} [PRIOR] [NORESET] IF {event}
(3)	[label]	TRAP	{routine} [PRIOR] [NORESET] IF CHAR {char}
(4)	[label]	TRAP	{routine} IF TIMER= {value}

Where:

label

Optional. A Program Execution Label.

routine

Required. A Program Execution Label assigned to the entry point of the subroutine called should the TRAP occur.

message

Optional. A previously defined Character String Variable that receives the system generated error message.

event

Required. One of the trappable program Events.

char

Required. A single character Literal.

value

Required. A previously defined Numeric Variable, Literal, or Expression that defines the time interval.

Flags Affected: NONE

Note the following:

The event IO indicates a disk I/O error has occurred. This event is useful in testing whether a disk file already exists or not. Trying to OPEN a non-existent file causes an IO error.
If a TRAP event is set and the same exception program event is set in a program, the exception program event operation takes precedence and is executed.
The event CFAIL indicates an error occurred while attempting to CHAIN to another program. This usually only occurs if the CHAINed program does not exist as specified, was an invalid format (bad load module) or there is insufficient system resources to load it.
The DBFAIL event indicates an error occurred while attempting a database access instruction. After this event occurs, the DBCLEAR instruction should be executed to clear the query string that caused the error.
The event FORMAT indicates an attempt was made to READ non-numeric data into a numeric variable. The READ stops at the list item in error without changing the remaining list items.
The event RANGE indicates the record number was out of range. This generally occurs only when an attempt is made to read a sector that has not yet been written.
The event PARITY indicates a disk CRC error occurred during a READ or during the verification after a WRITE.
The event SPOOL indicates an error occurred during an attempt to route the print output to the designated or default printer device or file. This type of error may occur if the spool file or device is already in use by another terminal (i.e., a lock has been placed on it), if there is insufficient access rights to the device or file, if the disk is out of space or other such disk errors.
The event INTERRUPT (INT) indicates the operating system interrupt sequence was entered.
The event ESCAPE indicates the ESCAPE (ESC) key was struck. Due to the lack of sub-second support by some Linux and compatible operating systems, the TRAP for ESCAPE may take up to one second after actual depression of the key.
The event {char} or CHAR {char} indicates the specified character was entered. {char} may be a one byte literal or variable from octal 0 to octal 377. When the CHAR {char} form is used, {char} may be specified as an equated value, decimal constant, hex constant, or octal constant. If a variable is used, the form pointed character at the time the TRAP instruction is issued is used. Multiple {char} traps may be used if the -ZM option mode is specified for the compiler. Otherwise, setting a {char} trap clears the previous {char} trap.
The event MOUSE indicates that one of the buttons on the mouse was pressed. The NORESET clause is invalid with this event. This event is only valid with SUNDB86x.
The Function Flags event indicates that a specified function or special key was entered. Any function key defined within the screen definition file, up to the supported maximum of 40, may be trapped. It is even possible to set a different TRAP for each function key. In addition, any special key defined within the screen definition file (UP, DOWN, LEFT, RIGHT, INS, DEL, PGUP, PGDN, HOME or END) may have a TRAP set for each.
The event FKEY indicates a previously untested function key, special key or the ESCAPE key was entered. FKEY only supports those keys defined within the screen definition file.
Any system error messages are placed in S$ERROR$ unless the GIVING option is used. The GIVING option designates that {message} receives the system error message. GIVING is not valid with the INTERRUPT (INT), Function Flags, FKEY, CHAR {char} or {char} traps.
Once a TRAP has been taken, it is cleared (potentially eliminating the protection from program termination) and must be reset unless the NORESET option is specified. The NORESET option indicates the TRAP is not cleared, remaining set until an appropriate TRAPCLR instruction or program termination.
The PRIOR option applies only to a trap taken during a KEYIN instruction. If a trap is taken during a KEYIN instruction and the PRIOR option was specified, a RETURN from the trap logic positions to the beginning of the KEYIN instruction.
The GIVING, NORESET and PRIOR options may be specified in any order but must precede the IF {event}.
An EVENT trap signals that an object event has occurred. A program must still execute an EVENTCHECK or EVENTWAIT instruction to actually process the event. The EVENT trap is only available with PLBCMP when operating in a GUI environment.
An OBJECT trap is taken if an error occurs in an object instruction. The OBJECT trap is only available with PLBCMP when operating in a GUI environment.
A TIMER trap is taken when the specified time interval has expired. The TIMER trap is only available with the SUNDBSYS runtime. The instruction uses format (4) above. The NORESET, PRIOR and GIVING clauses are not available with TIMER. {value} is a time-out specification in seconds and can have a fractional portion. The granularity is limited to the MS-DOS clock that is accurate to 1/18th of a second.
When executing a PL/B program using a GUI runtime, the keyboard events for the TRAP instruction including CHAR {char], F1-F40, FKEY, ESCAPE, and the special keys are only processed for KEYIN instructions. This means that the keyboard traps are only processed for the runtime main window since it is the only window that supports the KEYIN instructions. Also, the keyboard event TRAPs aret dispatched unless the runtime main window has the focus to accept the Windows key stroke messages.