Whenever an ERROR condition is raised, an error number, and possibly a sub-error number as well, is associated with that instance of the condition being raised. Each one of the numerous reasons for ERROR being raised will produce a different combination of error/sub-error numbers. So, by checking the error/sub-error numbers, you can deduce exactly what went wrong in your script (ie, why the ERROR condition was raised).
Your handler can use the CONDITION() built-in function's 'E' option to fetch the error and sub-error numbers associated with a given instance of that condition. CONDITION('E') will return the two numbers separated by a dot. For example, 80.81 will be returned for an ERROR condition raised because an environment chose to raise this condition when you passed the environment a particular command. You'd have to consult the documentation with the environment to determine why it may have reacted this way to that particular command.
The error number can be thought of as a "general category number". And the sub-error number is a specific error within that category.
The following chart lists the error and sub-error numbers associated with the ERROR condition, and what is the meaning of each combination of error/sub-error number.
| 65 | Category: An untrapped ERROR condition occurred in a child script. Reginald-only. CONDITION('D') reports the script name, exact error, and line number |
| 80 | Category: An error in an environment. Reginald-only |
| 80.1 | An environment raised an ERROR condition when it was passed a command |
| 80.2 | Your script referenced an environment that isn't registered or auto-loaded |
| 80.3 | An executable (EXE) launched by your script raised an ERROR condition |
| 80.4 | An exit handler raised an ERROR condition when you tried to pass a command to an environment |
An ERROR condition can also be raised if you've issued an OPTIONS 'TRAP' instruction and are trapping ERROR, and then you call some other script in which ERROR is raised, but not trapped, in that child script. In this case, CONDITION('E') returns an error number of 65. (This is a Reginald-only feature). CONDITION('D') will return an error message that reports the name of the script in which ERROR was raised, the line number where it occurred, and a reason why the condition was raised. Here is an example handler that would differentiate between ERROR raised in your script versus another script that you called:
MyHandler:
IF CONDITION('E') == '65' THEN DO
PARSE VALUE CONDITION('D') WITH . '"' scriptname '"' . 'line ' linenum ': ' reason
SAY 'ERROR condition raised in "'|| scriptname ||'" at line' linenum ':' reason
END
ELSE DO
SAY 'ERROR condition raised at line' SIGL ':' CONDITION('D')
END
RETURN
Note: Reginald's CONDITION() function has an additional option.
CONDITION('M') will present a pop-up message box containing the error message, the name of the script in which ERROR was raised, the source line and line number upon which ERROR was raised, and a Help button to bring up a help page for that error. This is preferable to trying to create your own message to present to the person running your script, since the online help may be supplied by the entity raising the condition.
When you're passing a command to some environment, or telling the operating system (ie, 'CMD' environment) to launch some program, the special variable RC will be set to any error message or number returned by the program you launch, or by the environment to which you pass a command. This variable is set regardless of whether you have your own ERROR handler, so you can always check the RC variable to see what error message or number a program or environment has returned. Often, the number 0 will be returned to indicate success, but this is just a guideline.
Note: The RC variable is created by the REXX interpreter, which assigns it a value when a condition is raised. You should never name your own variable RC, but may reference this variable.