ZTRAP (ObjectScript)
Synopsis
ZTRAP:pc ztraparg
ZTRAP:pc $ZERROR
ZTRAP:pc $ZE
Arguments
| Argument | Description |
|---|---|
| pc | Optional — A postconditional expression. |
| ztraparg | Optional — An error code string. An error code string is specified as a string literal or an expression that evaluates to a string; only the first four characters of the string are used. |
| $ZERROR | The special variable $ZERROR, which can be abbreviated $ZE. |
Description
The ZTRAP command accepts both a command postconditional and argument indirection. ZTRAP has three forms:
-
Without an argument
-
With a string argument
ZTRAP without an argument forces an error with the error code <ZTRAP>.
ZTRAP ztraparg forces an error with the error code <Zxxxx>, where xxxx is the first four characters of the string specified by ztraparg. If you specify an expression, rather than a quoted string literal, the compiler evaluates the expression and uses the first four characters of the resulting string. When evaluating an expression, InterSystems IRIS strips the plus sign and leading and trailing zeros from numbers. All remaining characters of ztraparg are ignored.
ZTRAP $ZERROR does not force a new error. It stops execution at the current program stack level and pops stack levels until another error handler is found. Execution then continues in that error handler with the current error code.
Arguments
pc
An optional postconditional expression. InterSystems IRIS executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions.
ztraparg
A string literal or an expression that evaluates to a string. Any of the following values can be specified for ztraparg:
-
A quoted string of any length containing any characters. ZTRAP uses only the first four characters to generate an error code; if there are fewer than four characters, it uses the characters provided. Unlike system error codes, which are always uppercase, case is preserved. Thus:
ZTRAP "FRED" ; generates <ZFRED> ZTRAP "Fred" ; generates <ZFred> ZTRAP "Freddy" ; generates <ZFred> ZTRAP "foo" ; generates <Zfoo> ZTRAP " foo" ; generates <Z foo> ZTRAP "@#$%" ; generates <Z@#$%> ZTRAP "" ; generates <Z> ZTRAP """" ; generates <Z"> -
An expression that evaluates to a string.
ZTRAP 1234 ; generates <Z1234> ZTRAP 2+2 ; generates <Z4> ZTRAP 10/3 ; generates <Z3.33> ZTRAP +0.700 ; generates <Z.7> ZTRAP $ZPI ; generates <Z3.14> ZTRAP $CHAR(64)_$CHAR(37) ; generates <Z@%> ZTRAP "" ; generates <Z> ZTRAP """" ; generates <Z">
The ZTRAP command accepts argument indirection. For more information, refer to the Indirection Operator reference page.
Passing Control to an Error Handler with $ZERROR
When the ZTRAP argument is the special variable $ZERROR, special processing is performed which is useful in $ZTRAP error handlers. ZTRAP $ZERROR does not force a new error. It stops execution at the current program stack level and pops stack levels until another error handler is found. Execution then continues in that error handler with the current error code. This error handler may be located in a different namespace.
Examples
This example shows how you use the ZTRAP command with an expression to produce an error code:
; at this point the routine discovers an error ...
ZTRAP "ER23"
...When the routine is run and it discovers the anticipated error condition, the output appears as follows:
<ZER23>label+offset^routine
This example shows how the use of a postconditional affects the ZTRAP command:
;
ZTRAP:y<0 "yNEG"
;When the routine is run and y is negative, the output is:
<ZyNEG>label+offset^routine
This example shows how you use argument indirection in the ZTRAP command:
;
SET ERPTR="ERMSG"
SET ERMSG="WXYZ"
;
;
ZTRAP @ERPTRThe output is:
<ZWXYZ>label+offset^routine
The following example shows a ZTRAP command that invokes a $ZTRAP error trap handler defined at a previous context level.
Main
NEW $ESTACK
SET $ZTRAP="OnErr"
WRITE !,"$ZTRAP set to: ",$ZTRAP
WRITE !,"Main $ESTACK= ",$ESTACK // 0
WRITE !,"Main $ECODE= ",$ECODE," $ZERROR=",$ZERROR
DO SubA
WRITE !,"Returned from SubA" // not executed
WRITE !,"MainReturn $ECODE= ",$ECODE," $ZERROR=",$ZERROR
QUIT
SubA
WRITE !,"SubA $ESTACK= ",$ESTACK // 1
ZTRAP
WRITE !,"SubA $ECODE= ",$ECODE," $ZERROR=",$ZERROR
QUIT
OnErr
WRITE !,"OnErr $ESTACK= ",$ESTACK // 0
WRITE !,"OnErr $ECODE= ",$ECODE," $ZERROR=",$ZERROR
QUIT
