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:
$ECODE can contain ISO 11756-1999 standard error codes, with the form M#, where # is an integer. For example, M6 and M7 are “undefined local variable” and “undefined global variable,” respectively. (M7 is issued for both globals and process-private globals.) For a complete list, see ISO 11756-1999 standard error messages in the InterSystems IRIS Error Reference.
$ECODE 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 should not assume that $ECODE is preserved when you call any other routine or library function. It may catch an error and handle it, leaving a different value in $ECODE. If you need a persistent copy of it, you should save it within the $ETRAP code.
You can also explicitly clear or set $ECODE.
You can clear $ECODE by setting it to the empty string (""), as follows:
Setting $ECODE to the empty string has the following effects:
It clears all existing $ECODE values. It has no effect on an existing $ZERROR value.
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.
It affects error processing flow of control for $ETRAP error handlers. See Error Processing in Using ObjectScript for more details.
You cannot NEW the $ECODE 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.
$ECODE String Overflow
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.
User–defined $ECODE 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
Your error handlers should check $ZERROR rather than $ECODE for the most recent InterSystems IRIS error.