Contains the current error code string.
When an error occurs, InterSystems IRIS sets the $ECODE
special variable to a comma-surrounded string containing the error code corresponding to the error. For example, when a reference is made to an undefined global variable, InterSystems IRIS sets the $ECODE
special variable to the following string:
can also contain error codes that are the same as General System error codes (the error codes returned at the terminal prompt and to the $ZERROR
special variable). However, $ECODE
prepends a Z to these error codes, and removes the angle brackets. Thus the $ECODE
error ZSYNTAX is a <SYNTAX> error, ZILLEGAL VALUE is an <ILLEGAL VALUE> error, and ZFUNCTION is a <FUNCTION> error. $ECODE
does not retain any additional error info for those error codes that provide it; thus ZPROTECT is a <PROTECT> error; the additional info component is kept in $ZERROR
, but not in $ECODE
. For more information about InterSystems IRIS error codes, see $ZERROR
; for a complete list, see General System Error Messages
in the InterSystems IRIS Error Reference
If an error occurs when $ECODE
already contains previous error codes, the existing error stack is cleared when the new error occurs. The new error stack will contain only entries that show the state at the time of the current error. (This is a change from earlier $ECODE
behavior, where the old error stack would persist until explicitly cleared.)
If there are multiple error codes, InterSystems IRIS appends the code for each error, in the order received, at the end of the current $ECODE
value. Each error in the resulting $ECODE
string is delimited by commas, as follows:
In the above case, the most recent error is a <PROTECT> error.
You can also explicitly clear or set $ECODE
is always cleared when you terminate the current process.
You can clear $ECODE
by setting it to the empty string (""), as follows:
to the empty string has the following effects:
It clears all existing $ECODE
values. It has no effect on an existing $ZERROR
It clears the error stack for your job. This means that a subsequent call to the $STACK
function returns the current execution stack, rather than the last error stack.
You cannot NEW
special variable. Attempting to do so generates a <SYNTAX> error.
You can force an error by setting $ECODE
to an value other than the empty string. Setting $ECODE
to any non-null value forces an interpreter error during the execution of an ObjectScript routine. After InterSystems IRIS sets $ECODE
to the non-null value that you specify, InterSystems IRIS takes the following steps:
Writes the specified value to $ECODE
, overwriting any previous values.
Generates an <ECODETRAP> error. (This sets $ZERROR
to the value <ECODETRAP>).
Passes control to any error handlers you have established. Your error handlers can check for the $ECODE
string value you chose and take steps to handle the condition appropriately.
If the length of the accumulated string in $ECODE
exceeds 512 characters, the error code that causes the string overflow clears and replaces the current list of error codes in $ECODE
. In this case, the list of errors in $ECODE
is the list of errors since the most recent string overflow, beginning with the error that caused the overflow. See Using ObjectScript
for more information about the maximum string data length.
Creating Your Own Error Codes
The format for the $ECODE
special variable is a comma-surrounded list of one or more error codes. Error codes starting with the letter U are reserved for the user. All other error codes are reserved for InterSystems IRIS.
values should be distinguishable from the values InterSystems IRIS automatically generates. To ensure this, always prefix your error text with the letter U. Also remember to delineate your error code with commas. For example:
SET $ECODE=",Upassword expired!,"
Check $ZERROR Rather Than $ECODE for InterSystems IRIS Errors
Your error handlers should check $ZERROR
rather than $ECODE
for the most recent InterSystems IRIS error.