Skip to main content
Previous sectionNext section

ZTRAP

Forces an error with a specified error code.

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

  • With $ZERROR

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 in Using ObjectScript.

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">
    Copy code to clipboard
  • 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">
    Copy code to clipboard

The ZTRAP command accepts argument indirection. For more information, refer to Indirection in Using 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.

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"
   ...
Copy code to clipboard

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"
   ;
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

See Also