$ZTrap

$ZTrap
Prev	Chapter 8. Intrinsic Special Variables	Next

$ZT[RAP] contains a string value that GT.M XECUTEs when an error occurs during routine execution.

	Note
	The following discussion assumes that $ETRAP error handling is simultaneously not in effect (that is, $ETRAP=""). See Chapter 13: “Error Processing” 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, (that is, 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 stack the current $ZTRAP value, and set its value to the empty string ($ZTRAP=""). The NEW command puts the $ZTRAP in control for error handling. 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 environment variable 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.

	Note
	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.

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 settings of $ZTRAP controlled by the UNIX environment variable gtm_ztrap_form.

The four settings of gtm_ztrap_form are:

code - If gtm_ztrap_form evaluates to "code" (or a value that is not one of the subsequently described values), then GT.M treats $ZTRAP as code and handles it as previously described in the documentation.
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.

	Important
	GT.M attempts to compile $ZTRAP before evaluating $ZTRAP as an entryref. Because 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 UNIX environment variable 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.

	Note
	Like $ZTRAP values, invocation of device EXCEPTION values follow the pattern specified by the current gtm_ztrap_form setting except that there is never any implicit popping with EXCEPTION action.

Prev	Up	Next
$ZTIMeout	Home	$ZUSedstor