Forces an error with a specified error code.
Description
The ZTRAP command accepts both a command postconditional and argument indirection. ZTRAP has three forms:
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.
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 @ERPTR
The 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