$ETRAP (ObjectScript)
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.
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 Using Try-Catch.
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:
-
Saves the copy of $ETRAP that was in use at that point.
-
Creates a new copy of $ETRAP.
-
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 Using Try-Catch 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.
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.