An ERROR condition happens when there is some error that an add-on Function you call in a DLL, or (non-REXX) program that you run, encounters as a result of doing its work. For example, if you run some program that downloads a web page to a file, and it encounters a problem, an ERROR condition may occur.

Note: If your script is not trapping FAILURE, but is trapping ERROR, then REXX will raise ERROR whenever it would otherwise raise FAILURE. In other words, if you want reported only critical errors with add-on DLLs or EXEs you run (but not other errors), then trap only FAILURE (not ERROR). If you want reported both critical and all other errors with add-on DLLs and EXEs, then you need trap only ERROR (not FAILURE).


ERROR error/sub-error numbers

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.
40 An error in launching an executable.
  1 An environment raised an ERROR condition when it was passed a command.
  2 Your script tried to pass a command to an environment that does not exist and can't be autoloaded.
  3 An executable (EXE) run by your script raised a FAILURE condition.
  4 An exit handler raised an ERROR condition when you tried to pass a command to an Environment.
70 A FUNCDEF registered function was defined to return a str, char[], or struct, but it did not return the expected item. This happens only if you ask to be informed of errors via the ERROR condition when you FUNCDEF the function.

For the four errors under category 40, the RXFUNCERRMSG() built-in may return a more informative error message than CONDITION('D').


Trapping ERROR in a child script

The Reginald interpreter allows you to trap an ERROR condition raised in any child script you call (as well as any other child script that the first child calls), if that script doesn't trap ERROR for itself.

Your script must use a CATCH ERROR instruction where you call the child script. If ERROR is then raised by the child script, the child script will abort on the line where ERROR occurs, and Reginald will raise ERROR in your script (on the line where you called the script). In this case, CONDITION('E') returns an error number of 65 to indicate that it was a child script (as opposed to your script) in which ERROR was raised. CONDITION('D') will return an error message that reports the name of the child script in which ERROR was raised, the line number where it occurred in the child script, and a reason why the condition was raised.

What this means is that, using the CATCH ERROR, if a child script doesn't handle ERROR for itself, you can force that child script to be aborted and have that ERROR automatically reported back to you by REXX.

Here is an example handler that would differentiate between ERROR raised in your script versus another script that you called:

CATCH ERROR
   IF CONDITION('E') == '65' THEN DO

      PARSE VALUE CONDITION('D') WITH . '"' scriptname '"' . 'line ' linenum ': ' reason

      /* CONDITION('M') is preferable to this SAY. */
      SAY 'ERROR condition raised in "'|| scriptname ||'" at line' linenum ':' reason

   END

   ELSE

      /* CONDITION('M') is preferable to this SAY. */
      SAY 'ERROR condition raised in this script:' CONDITION('D')

   RETURN