Location

Using the SET command you can specify location as a quoted string.

In a routine, you can specify location as label (a line label in the current routine), ^routine (the beginning of a specified external routine), or label^routine (a specified label in a specified external routine). Do not specify a location in a routine that references a procedure or a label within a procedure. This is a invalid location; it results in a runtime error when InterSystems IRIS attempts to execute $ZTRAP.
In a procedure, you can specify location as label; a private label within that procedure block. $ZTRAP in a procedure block cannot be used to go to a location that is outside the body of the procedure; $ZTRAP in a procedure block can only reference a location within that procedure block. Therefore, in a procedure you cannot set $ZTRAP to ^routine or label^routine. Attempted to do so results in a <SYNTAX> error.
In a procedure, you set $ZTRAP to a private label name, but the $ZTRAP value is not the private label name; it is the offset from the procedure label (the top of the procedure) to the line location of the private label. For example, +17^myproc.

Note:

$ZTRAP provides legacy support for label+offset in some contexts (but not in procedures). This optional +offset is an integer specifying the number of lines to offset from label. The label must be in the same routine. The use of +offset is deprecated, and may result in a compilation warning error. InterSystems recommends that you avoid the use of a line offset when specifying location.

You cannot specify an +offset when calling a procedure or a IRISSYS % routine. If you attempt to do so, InterSystems IRIS issues a <NOLINE> error.

The $ZTRAP location must be in the current namespace. $ZTRAP does not support extended routine reference.

If you specify a nonexistent line label, a location that does not exist in the current routine, the following occurs:

Displaying $ZTRAP: In a routine, $ZTRAP contains label^routine. For example, DummyLabel^MyRou. In a procedure, $ZTRAP contains the maximum possible offset: +34463^MyProc.
Invoking $ZTRAP: InterSystems IRIS issues a <NOLINE> error message.

Each stack level can have its own $ZTRAP value. When you set $ZTRAP, the system saves the value of $ZTRAP for the previous stack level. InterSystems IRIS restores this value when the current stack level ends. To enable error trapping at the current stack level, set $ZTRAP to the error trap handler by specifying its location. For example:

   IF $ZTRAP="" {WRITE !,"$ZTRAP not set" }
   ELSE {WRITE !,"$ZTRAP already set: ",$ZTRAP
         SET oldtrap=$ZTRAP }
   SET $ZTRAP="Etrap1^Handler"
   WRITE !,"$ZTRAP set to: ",$ZTRAP
   //  program code
   SET $ZTRAP=oldtrap
   WRITE !,"$ZTRAP restored to: ",$ZTRAP

When an error occurs, this format unwinds the call stack and transfers control to the specified error trap handler.

In SqlComputeCode, do not set $ZTRAP=$ZTRAP. This can result in significant problems with transactional processing and error reporting.

To disable error trapping, set $ZTRAP to the null string (""). This clears any error trap set at the current DO stack level.

When you set an error handler using $ZTRAP, this handler takes precedence over any existing $ETRAP error handler. InterSystems IRIS implicitly performs a NEW $ETRAP command and sets $ETRAP to the null string ("").

Note:

Use of $ZTRAP from the Terminal prompt is limited to the current line of code. The SET $ZTRAP command and the command generating the error must be in the same line of code. The Terminal restores $ZTRAP to the system default at the beginning of each command line.

*Location