Contains a string of ObjectScript commands to be executed when an error occurs.
contains a string that specifies one or more ObjectScript commands that are executed when an error occurs.
You use the SET
command to give $ETRAP
the value of a string that contains one or more ObjectScript commands. Then, when an error occurs, Caché 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"
Caché then executes this command in $ETRAP
immediately following any ObjectScript command that generates an error condition. Caché executes the $ETRAP
command at the same context level in which the error condition occurs. Caché saves the $ROLES
value in effect when $ETRAP
is set; when the $ETRAP
code is executed, Caché 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
in the current routine), ^routine
(the beginning of a specified external routine), or label^routine
(a specified label in a specified external routine).
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.
The maximum length of a SET $ETRAP
string is 32,741 characters. Setting $ETRAP
to a longer string may result in a <MAXSTRING> error.
$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, Caché carries the value of the $ETRAP
special variable forward into new DO
, and user-defined function contexts. However, you can create a new copy of $ETRAP
in a context by issuing the NEW
command, as follows:
Whenever you issue a NEW
, Caché performs the following actions:
Saves the copy of $ETRAP
that was in use at that point.
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. Caché 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, Caché restores the old, saved value of $ETRAP
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:
SET $ETRAP="WRITE !,""$ETRAP invoked at Context Level "",$STACK"
; Initiate an XECUTE context that initiates a DO context
XECUTE "DO A"
; Initiate a user-defined function context
; A User-defined function that generates an error
A sample session using this code might run as follows:
$ETRAP invoked at context level 4
$ETRAP invoked at context level 3
$ETRAP invoked at context level 2
$ETRAP invoked at context level 1
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, Caché 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 Value is a Line of ObjectScript Code
Because the 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. See Using Caché ObjectScript
for more information.
Caché Error Handling Facilities
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 Caché features for error handling are the block-structured TRY
will continue to be a supported feature of Caché. However, use of $ETRAP
in new code should generally be avoided in preference to the other error handling facilities.
When you set an error handler using $ZTRAP
, this handler takes precedence over any existing $ETRAP
error handler. Caché implicitly performs a NEW $ETRAP
command and sets $ETRAP
to the null string ("").
commands perform error handling within an execution level. When an exception occurs within a TRY
block, Caché normally executes the CATCH
block of exception handler code that immediately follows the TRY
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
was previously set and an exception occurs in a TRY
block, Caché may take $ETRAP
rather than CATCH
unless you forestall this possibility. If both $ETRAP
are present when an exception occurs, Caché executes the error code (CATCH
) that applies to the current execution level. Because $ETRAP
is intrinsically not associated with an execution level, Caché 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 Caché 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
An exception that occurs within a CATCH
block is handled by the current error trap handler.