Caché ObjectScript Reference
ZTRAP
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Forces an error with a specified error code.
Synopsis
ZTRAP:pc ztraparg

ZTRAP:pc $ZERROR
ZTRAP:pc $ZE
Arguments
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:
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, Caché 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. Caché executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). Caché does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions in Using Caché ObjectScript.
ztraparg
A string literal or an expression that evaluates to a string. Any of the following values can be specified for ztraparg:
The ZTRAP command accepts argument indirection. For more information, refer to Indirection in Using Caché ObjectScript.
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.
This way of passing control to an error handler is preferable to use of the legacy ZQUIT command.
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
 
See Also