$ZT[RAP] contains a string value that GT.M XECUTEs when an error occurs during routine execution.
![[Note]](images/note.png)
|
|
|
The following discussion assumes that $ETRAP error handling is simultaneously not in effect (that is, $ETRAP=""). Refer to "Error Processing" chapter in this manual for more information on the interaction between $ETRAP and $ZTRAP. |
When the $ZTRAP variable is not null, GT.M executes $ZTRAP at the current level. The $ZTRAP variable has the initial value of "B," and puts the process in Direct Mode when an error condition occurs. If the value of $ZTRAP is null (""), an exception causes the image to run-down with the condition code associated with the exception. If $ZTRAP contains invalid source code, GT.M displays an error message and puts the process into Direct Mode.
$ZTRAP is a read-write Intrinsic Special Variable, (i.e., it can appear on the left side of the equal sign (=) in the argument to the SET command).
$ZTRAP may also appear as an argument to an inclusive NEW command. NEW $ZTRAP causes GT.M to set $ZTRAP to null ($ZTRAP="") and to stack the old value of $ZTRAP. When the program QUITs from the invocation level where the NEW occurred, GT.M restores the value previously stacked by the NEW. NEW $ZTRAP provides nesting of $ZTRAP. Because $ZTRAP="" terminates the image when an error occurs, SET $ZTRAP= generally follows immediately after NEW $ZTRAP. You may use this technique to construct error handling strategies corresponding to the nesting of your programs. If the logical name gtm_ztrap_new evaluates to boolean TRUE (case insensitive string "TRUE", or case insensitive string "YES", or a non-zero number), $ZTRAP is NEWed when $ZTRAP is SET; otherwise $ZTRAP is not stacked when it is SET.
|
|
|
|
QUIT from a $ZTRAP terminates the level at which the $ZTRAP was activated. |
Keep $ZTRAP simple and put complicated logic in another routine. If the action specified by $ZTRAP results in another run-time error before changing the value of $ZTRAP, GT.M invokes $ZTRAP until it exhausts the process stack space, terminating the image. Carefully debug exception handling. For more information on error handling, refer "Error Processing".
Example:
GTM> S $ZTRAP="ZP @$ZPOS B"
This example modifies $ZTRAP to display source code for the line where GT.M encounters an error before entering Direct Mode.
There are four accepted behavioural forms of $ZTRAP controlled by the VMS logical name gtm_ztrap_form. If gtm_ztrap_form is defined to "code" (or not defined to one of the subsequently described values), then GT.M treats $ZTRAP as code and handles it as previously described in the documentation.
The four different behavioural forms of gtm_ztrap_form are:
-
entryref - If gtm_ztrap_form evaluates to "entryref" then GT.M treats it as an entryref argument to an implicit GOTO command.
-
adaptive - If gtm_ztrap_form evaluates to "adaptive" then if $ZTRAP does not compile to valid M code, then $ZTRAP is treated as just described for "entryref." Since there is little ambiguity, code and entryref forms of $ZTRAP can be intermixed in the same application.
Note that GT.M attempts to compile $ZTRAP before evaluating $ZTRAP as an entryref. Since GT.M allows commands without arguments such as QUIT, ZGOTO, or HANG as valid labels, be careful not to use such keywords as labels for error handling code in "adaptive" mode.
-
pope[ntryref] / popa[daptive] - If gtm_ztrap_form evaluates to "POPE[NTRYREF]" or "POPA[DAPTIVE]" (case insensitive) and $ZTRAP value is in the form of entryref, GT.M unwinds the M stack from the level at which an error occurred to (but not including) the level at which $ZTRAP was last SET. Then, GT.M transfers control to the entryref in $ZTRAP at the level where the $ZTRAP value was SET. If the VMS logical name gtm_zyerror is defined to a valid entryref, GT.M transfers control to the entryref specified by GTM_ZYERROR (with an implicit DO) after unwinding the stack and before transferring control to the entyref specified in $ZTRAP.