Skip to main content

$ETRAP (ObjectScript)

Contains a string of ObjectScript commands to be executed when an error occurs.

Synopsis

$ETRAP
$ET

SET $ETRAP="cmdline"
SET $ET="cmdline"

Description

$ETRAP contains a string that specifies one or more ObjectScript commands that are executed when an error occurs.

Note:

For error handling in new application code, InterSystems strongly recommends using the TRY and CATCH commands. $ETRAP is documented here to provide support for maintenance and migration of existing code. For more information, see Error Handling in Using ObjectScript.

You use the SET command to give $ETRAP the value of a cmdline string that contains one or more ObjectScript commands. Then, when an error occurs, InterSystems IRIS executes the commands you entered into $ETRAP. For example, suppose you set $ETRAP to a string that contains a GOTO command to transfer control to an error-handling routine:

   SET $ETRAP="GOTO LOGERR^ERRROU"

InterSystems IRIS then executes this command in $ETRAP immediately following any ObjectScript command that generates an error condition. InterSystems IRIS executes the $ETRAP command at the same context level in which the error condition occurs. InterSystems IRIS saves the $ROLES value in effect when $ETRAP is set; when the $ETRAP code is executed, InterSystems IRIS sets $ROLES to that saved value. This prevents the $ETRAP error handler from using elevated privileges that were granted to the routine after establishing the error handler.

When setting $ETRAP to execute an error handler (for example, with a GOTO command) you can specify the error handler as label (a label in the current routine), ^routine (the beginning of a specified external routine), or label^routine (a specified label in a specified external routine).

$ETRAP supports label+offset in some contexts (but not in procedures). This optional +offset is an integer specifying the number of lines to offset from label. InterSystems recommends that you avoid the use of a line offset when specifying an error handler location.

Because the cmdline string value of $ETRAP is executable ObjectScript commands, the length of the string cannot be longer than the maximum length of an ObjectScript routine line: 32,741 characters. Setting $ETRAP to a longer string may result in a <MAXSTRING> error. Refer to the XECUTE command for further details on specifying a cmdline string.

Use NEW Before Setting $ETRAP to a New Value

If you assign a new value to $ETRAP in a context without first creating a new copy of $ETRAP with the NEW command, InterSystems IRIS establishes that new value as the value of $ETRAP not only for the current context but also for all previous contexts. Therefore, InterSystems strongly recommends that you use the NEW $ETRAP command to create a new copy of $ETRAP before you set $ETRAP with a new value.

$ETRAP Commands Compared with XECUTE Commands

The commands in a $ETRAP string are not executed in a new context level, unlike the commands in an XECUTE string. In addition, the $ETRAP command string is always terminated by an implicit QUIT command. The implicit QUIT command quits with a null-string argument when the $ETRAP error-handling commands are invoked in a user-defined function context where an argumented QUIT command is required.

Setting $ETRAP Values in Different Context Levels

By default, InterSystems IRIS carries the value of the $ETRAP special variable forward into new DO, XECUTE, and user-defined function contexts. However, you can create a new copy of $ETRAP in a context by issuing the NEW command, as follows:

   NEW $ETRAP

Whenever you issue a NEW for $ETRAP, InterSystems IRIS performs the following actions:

  1. Saves the copy of $ETRAP that was in use at that point.

  2. Creates a new copy of $ETRAP.

  3. Assigns the new copy of $ETRAP the same value as the old, saved copy of $ETRAP.

You then use the SET command to assign a different value to the new copy of $ETRAP. In this way, you can establish new $ETRAP error-handling commands for the current context.

You can also clear $ETRAP by setting it to the null string. InterSystems IRIS then executes no $ETRAP commands at the context level in the event of an error.

When a QUIT command causes the current context to be exited, InterSystems IRIS restores the old, saved value of $ETRAP.

Examples

The following example uses either $ETRAP or $ZTRAP to perform the same operation: go to ErrMod when a <DIVIDE> error occurs. The $RANDOM function randomly invokes one or the other error handler:

MainMod
  WRITE "MainMod stack:",$STACK,!
  SET x=$RANDOM(2)
   IF x=0 {WRITE "$ETRAP",!
           NEW $ETRAP
           SET $ETRAP="GOTO ErrMod"  
           WRITE 5/0}
   IF x=1 {WRITE "$ZTRAP",!
           SET $ZTRAP="ErrMod"
           WRITE 5/0}
   QUIT
ModuleA
    /* code not executed */
    QUIT
ErrMod
   WRITE !,"in ErrMod",!
   WRITE "ErrMod stack:",$STACK
   QUIT

The following example demonstrates how the value of $ETRAP is carried forward into new contexts and how you can invoke $ETRAP error-handling commands again in each context after an error occurs. The $ETRAP commands in this example make no attempt to dismiss the error. Rather, control by default is passed back to $ETRAP error-handling commands at each previous context level.

The sample code is as follows:

ETR    
  NEW $ETRAP
  SET $ETRAP="WRITE !,""$ETRAP invoked at Context Level "",$STACK"
    ; Initiate an XECUTE context that initiates a DO context
  XECUTE "DO A"
  QUIT
    ; Initiate a user-defined function context
A
  WRITE "In A",!
  SET A=$$B
  QUIT
B()    
    ; User-defined function that generates an error
  WRITE "In B",!
  WRITE "impossible division ",5/0
  QUIT 1

A sample Terminal session using this code might run as follows:

USER>DO ^ETR
In A
In B
impossible division
$ETRAP invoked at context level 4 
$ETRAP invoked at context level 3 
$ETRAP invoked at context level 2 
$ETRAP invoked at context level 1 
USER>

$ETRAP and Other ObjectScript Error Handling Facilities

The $ETRAP special variable is one of several ObjectScript language facilities that enable you to control the handling and logging of errors that occur in your applications.

  • The preferred InterSystems IRIS features for error handling are the block-structured TRY and CATCH commands.

  • The $ZTRAP special variable is preferable to $ETRAP.

  • $ETRAP will continue to be a supported feature of InterSystems IRIS. However, use of $ETRAP in new code should generally be avoided in preference to the other error handling facilities.

See Error Handling in Using ObjectScript for more information about error handling.

$ETRAP and $ZTRAP

When you set an error handler using $ZTRAP, this handler takes precedence over any existing $ETRAP error handler. InterSystems IRIS implicitly performs a NEW $ETRAP command and sets $ETRAP to the null string ("").

$ETRAP and TRY / CATCH

The TRY and CATCH commands perform error handling within an execution level. When an exception occurs within a TRY block, InterSystems IRIS normally executes the CATCH block of exception handler code that immediately follows the TRY block.

Note:

Use of $ETRAP within a program structured with TRY blocks is strongly discouraged.

You cannot set $ETRAP within a TRY block. Attempting to do so generates a compilation error. You can set $ETRAP prior to the TRY block, or within the CATCH block.

If $ETRAP was previously set and an exception occurs in a TRY block, InterSystems IRIS may take $ETRAP rather than CATCH unless you forestall this possibility. If both $ETRAP and CATCH are present when an exception occurs, InterSystems IRIS executes the error code (CATCH or $ETRAP) that applies to the current execution level. Because $ETRAP is intrinsically not associated with an execution level, InterSystems IRIS assumes that it is associated with the current execution level unless you specify otherwise. You must NEW $ETRAP before setting $ETRAP to establish a level marker for $ETRAP, so that InterSystems IRIS will correctly take CATCH as the current level exception handler, rather than $ETRAP. Otherwise, a system error (including a system error thrown by the THROW command) may take the $ETRAP exception handler.

An exception that occurs within a CATCH block is handled by the current error trap handler.

See Also

Feedback