When an error occurs, Caché 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, Caché sets the $ECODE special variable to the following string:
$ECODE can also contain error codes that are the same as Caché 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 Caché error codes, see $ZERROR; for a complete list, see General System Error Messages in the Caché 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, Caché 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:
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 Caché sets $ECODE to the non-null value that you specify, Caché 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 Caché ObjectScript for more information about the maximum string data length.
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 Caché.
Userdefined $ECODE values should be distinguishable from the values Caché 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: