CONDITION | Returns information about the currently trapped condition. |
ERRORTEXT | Returns an error message associated with a REXX error number. |
TRACE | Returns the current trace setting. |
UNIXERROR | Returns an error message associated with an operating-system-specific error number. |
Returns information about the currently trapped condition (ie, the condition currently being handled by your script). Normally, this would be called from your SYNTAX, HALT, NOVALUE, ERROR, FAILURE, or NOTREADY condition handler, in order to retrieve some more information about what caused the error. For example, you can retrieve an informative error message to display to the user or parse. Or, you can retrieve an error number and sub-error number that can help identify the reason for the error.
info = CONDITION(option)
option is one of the desired options as so:
Option Meaning C (Condition) Returns the name of the condition that is being handled. This would be the string 'SYNTAX', 'HALT', 'NOVALUE', 'ERROR', 'FAILURE', or 'NOTREADY'. D (Description) Returns an error message describing the cause of the error. If no error message is available, CONDITION('D') returns an empty string. For a NOTREADY condition, this will be the name of the stream in error, and you can then use STREAM's 'D' option to retrieve a specific error message, or reset the stream's error state with STREAM's RESET command.
For a HALT condition, this will be the name of the signal that was used to raise HALT, for example 'SIGINT' to indicate the user pressing CTRL-C.
For a NOVALUE condition, this will be the name of the variable whose value has not been set.
E (Error) Returns the Error, and possibly Sub-error, numbers. They are separated by a dot. Each condition may have a different interpretation of this error number. I (Instruction) Returns the string 'CALL' if your handler was called via a CALL ON, or 'SIGNAL' if your handler was called via a SIGNAL ON. M (Message) Displays a pop-up message box with the error message, the line number upon which the error occurred, the source line, and perhaps a "Help" button to bring up an online help page for the error. This is a Reginald-only extension. S (State) Returns the string 'ON' if the condition is still enabled, or 'OFF' if disabled (which is usually the case in a handler invoked by SIGNAL ON), or 'DELAY' if delayed (which is usually the case in a handler invoked by CALL ON).
If option is omitted, it defaults to 'I'.
Information as described above.
If a FAILURE condition was raised as a result of RXFUNCADD() failing (ie, CONDITION('E') called from your FAILURE handler returns 81.10, 81.20, 81.40, or 81.50), then you can get a more informative error message via RXFUNCERRMSG.
For errors that raise the NOTREADY condition (ie, errors with CHARIN(), CHAROUT(), LINEIN(), LINEOUT(), and STREAM()), the STREAM 'D' option may be useful for retrieving a specific error message.
See Error trapping.
Returns an error message associated with a REXX error number.
message = ERRORTEXT(errornum)
errornum are the Error and Sub-error numbers. They are separated by a dot. For example, '25.4' indicates an Error number of 25 and a Sub-error number of 4. Each condition may have a different interpretation of these numbers. See the individual descriptions of each condition (ie, SYNTAX, NOTREADY, etc, under Error trapping.
The error message associated with the error/sub-error numbers, or an empty string if there is no such message.
The Error and Sub-Error numbers would typically be gotten from within some condition handler that called CONDITION('E'). But the error message that is returned from ERRORTEXT() may have "insert markers" in it. (ie, Markers that indicate where some phrase should be inserted). The error message returned by CONDITION('D') would be the same error message with those insert markers resolved with appropriate phrases. So, ERRORTEXT() is of questionable value.
ERRORTEXT('40.1') |
'External function failed' |
Returns the current trace setting, and perhaps sets tracing to a new setting.
setting = TRACE(new_setting)
new_setting is the new setting for tracing. It may be one of the modes listed in Tracing. If new_setting is omitted, then the current trace setting is not changed. (ie, TRACE() merely queries the current setting without changing it).
Prefixing new_setting with a ? character will activate interactive tracing.
The current trace setting.
TRACE() can change the trace setting even if interactive tracing is active (unlike the TRACE instruction).
The trace setting can not be a number. This is different than the TRACE instruction.
TRACE('O') |
/* Turns tracing off */ |
TRACE('?R') |
/* Turns on interactive tracing with 'R' setting */ |
Returns an error message associated with an operating-system-specific error number.
message = UNIXERROR(errornum)
errornum is the error number supplied by the operating system.
Some interpreters do not implement this function.
An error message associated with an operating-system-specific error number, or an empty string if no such message.
This function is very dependent upon the operating system of your computer. It should be passed only an error number that has specifically been returned by the operating system, not an ANSI error number, nor an error number returned by a REXX built-in function such as RXFUNCADD().