$ZTrap

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

[Note] 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] 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:

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