For traditional error processing, InterSystems IRIS® data platform enables your application to have an error handler. An error handler processes any error that may occur while the application is running. A special variable specifies the ObjectScript commands to be executed when an error occurs. These commands may handle the error directly or may call a routine to handle it.
If an error occurs and no error handler has been established, the behavior depends on how the InterSystems IRIS session was started:
Internal Error-Trapping Behavior
To get the full benefit of InterSystems IRIS error processing and the scoping issues surrounding the $ZTRAP special variable (as well as $ETRAP), it is helpful to understand how InterSystems IRIS transfers control from one routine to another.
InterSystems IRIS builds a data structure called a “context frame” each time any of the following occurs:
A routine calls another routine with a DO command. (This kind of frame is also known as a “DO frame.”)
An XECUTE command argument causes ObjectScript code to execute. (This kind of frame is also known as a “XECUTE frame.”)
A user-defined function is executed.
The frame is built on the call stack, one of the private data structures in the address space of your process. InterSystems IRIS stores the following elements in the frame for a routine:
The value of the $ZTRAP special variable (if any)
The value of the $ETRAP special variable (if any)
The position to return from the subroutine
When routine A calls routine B with DO ^B, InterSystems IRIS builds a DO frame on the call stack to preserve the context of A. When routine B calls routine C, InterSystems IRIS adds a DO frame to the call stack to preserve the context of B, and so forth.
Frames on a Call Stack
If routine A in the figure above is invoked at the Terminal prompt using the DO command, then an extra DO frame, not described in the figure, exists at the base of the call stack.
Current Context Level
You can use the following to return information about the current context level:
The $STACK special variable contains the current relative stack level.
The $ESTACK special variable contains the current stack level. It can be initialized to 0 (level zero) at any user-specified point.
The $STACK function returns information about the current context and contexts that have been saved on the call stack
The $STACK Special Variable
The $STACK special variable contains the number of frames currently saved on the call stack for your process. The $STACK value is essentially the context level number (zero based) of the currently executing context. Therefore, when an image is started, but before any commands are processed, the value of $STACK is 0.
See the $STACK special variable in the ObjectScript Reference for details.
The $ESTACK Special Variable
The $ESTACK special variable is similar to the $STACK special variable, but is more useful in error handling because you can reset it to 0 (and save its previous value) with the NEW command. Thus, a process can reset $ESTACK in a particular context to mark it as a $ESTACK level 0 context. Later, if an error occurs, error handlers can test the value of $ESTACK to unwind the call stack back to that context.
See the $ESTACK special variable in the ObjectScript Reference for details.
The $STACK Function
The $STACK function returns information about the current context and contexts that have been saved on the call stack. For each context, the $STACK function provides the following information:
The type of context (DO, XECUTE, or user-defined function)
The entry reference and command number of the last command processed in the context
The source routine line or XECUTE string that contains the last command processed in the context
The $ECODE value of any error that occurred in the context (available only during error processing when $ECODE is non-null)
When an error occurs, all context information is immediately saved on your process error stack. The context information is then accessible by the $STACK function until the value of $ECODE is cleared by an error handler. In other words, while the value of $ECODE is non-null, the $STACK function returns information about a context saved on the error stack rather than an active context at the same specified context level.
See the $STACK function in the ObjectScript Reference for details.
When an error occurs and an error stack already exists, InterSystems IRIS records information about the new error at the context level where the error occurred, unless information about another error already exists at that context level on the error stack. In this case, the information is placed at the next level on the error stack (regardless of the information that may already be recorded there).
Therefore, depending on the context level of the new error, the error stack may extend (one or more context levels added) or information at an existing error stack context level may be overwritten to accommodate information about the new error.
Keep in mind that you clear your process error stack by clearing the $ECODE special variable.
When an error occurs, InterSystems IRIS sets the $ZERROR and $ECODE special variables to a value describing the error. The $ZERROR and $ECODE values are intended for use immediately following an error. Because these values may not be preserved across routine calls, users who wish to preserve a value for later use should copy it to a variable.
InterSystems IRIS sets $ZERROR to a string containing:
The InterSystems IRIS error code, enclosed in angle brackets.
The label, offset, and routine name where the error occurred.
(For some errors): Additional information, such as the name of the item that caused the error.
The AsSystemError()Opens in a new tab method of the %Exception.SystemExceptionOpens in a new tab class returns the same values in the same format as $ZERROR.
The following examples show the type of messages to which $ZERROR is set when InterSystems IRIS encounters an error. In the following example, the undefined local variable abc is invoked at line offset 2 from label PrintResult of routine MyTest. $ZERROR contains:
The following error occurred when a non-existent class is invoked at line offset 3:
<CLASS DOES NOT EXIST>PrintResult+3^MyTest *%SYSTEM.XXQL
The following error occurred when a non-existent method of an existing class is invoked at line offset 4:
<METHOD DOES NOT EXIST>PrintResult+4^MyTest *BadMethod,%SYSTEM.SQL
You can also explicitly set the special variable $ZERROR as any string up to 128 characters; for example:
The $ZERROR value is intended for use immediately following an error. Because a $ZERROR value may not be preserved across routine calls, users that wish to preserve a $ZERROR value for later use should copy it to a variable. It is strongly recommended that users set $ZERROR to the null string ("") immediately after use. See the $ZERROR special variable in the ObjectScript Reference for details. For further information on handling $ZERROR errors, refer to the %SYSTEM.ErrorOpens in a new tab class methods in the InterSystems Class Reference.
When an error occurs, InterSystems IRIS sets $ECODE to the value of a comma-surrounded string containing the ANSI Standard error code that corresponds to the error. For example, when you make a reference to an undefined global variable, InterSystems IRIS sets $ECODE set to the following string:
If the error has no corresponding ANSI Standard error code, InterSystems IRIS sets $ECODE to the value of a comma-surrounded string containing the InterSystems IRIS error code preceded by the letter Z. For example, if a process has exhausted its symbol table space, InterSystems IRIS places the error code <STORE> in the $ZERROR special variable and sets $ECODE to this string:
After an error occurs, your error handlers can test for specific error codes by examining the value of the $ZERROR special variable or the $ECODE special variable.
Error handlers should examine $ZERROR rather than $ECODE special variable for specific errors.
See the $ECODE special variable in the ObjectScript Reference for details.