Forces an error with a specified error code.
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.
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 ...
When the routine is run and it discovers the anticipated error condition, the output appears as follows:
This example shows how the use of a postconditional affects the ZTRAP command:
When the routine is run and y is negative, the output is:
This example shows how you use argument indirection in the ZTRAP command:
The output is:
The following example shows a ZTRAP command that invokes a $ZTRAP error trap handler defined at a previous context level.
WRITE !,"$ZTRAP set to: ",$ZTRAP
WRITE !,"Main $ESTACK= ",$ESTACK // 0
WRITE !,"Main $ECODE= ",$ECODE," $ZERROR=",$ZERROR
WRITE !,"Returned from SubA" // not executed
WRITE !,"MainReturn $ECODE= ",$ECODE," $ZERROR=",$ZERROR
WRITE !,"SubA $ESTACK= ",$ESTACK // 1
WRITE !,"SubA $ECODE= ",$ECODE," $ZERROR=",$ZERROR
WRITE !,"OnErr $ESTACK= ",$ESTACK // 0
WRITE !,"OnErr $ECODE= ",$ECODE," $ZERROR=",$ZERROR