>>-TRACE--+-+--------+-----------------------+--;--------------><
| +-number-+ |
| +-Normal--------+ |
+-+-----------+--+---------------+-+
| +-------+ | +-All-----------+
| V | | +-Commands------+
+-----?---+-+ +-Error---------+
+-Failure-------+
+-Intermediates-+
+-Labels--------+
+-Off-----------+
+-Results-------+
Or, alternatively:
>>-TRACE--+-----------------------+--;-------------------------><
+-string----------------+
+-symbol----------------+
+-+-------+--expression-+
+-VALUE-+
TRACE controls the tracing action (that is, how much is displayed to the user) during the processing of a Rexx program. Tracing describes some or all of the clauses in a program, producing descriptions of clauses as they are processed. TRACE is mainly used for debugging. Its syntax is more concise than that of other Rexx instructions because TRACE is usually entered manually during interactive debugging. (This is a form of tracing in which the user can interact with the language processor while the program is running.)
If specified, the number must be a whole number.
The string or expression evaluates to:
The symbol is taken as a constant and is therefore:
The option that follows TRACE or the character string that is the result of evaluating expression determines the tracing action. You can omit the subkeyword VALUE if expression does not begin with a symbol or a literal string, that is, if it starts with a special character, such as an operator or parenthesis.
2.29.1. Trace Alphabetic Character (Word) Options
Although you can enter the word in full, only the first capitalized letter is needed; all following characters are ignored. That is why these are referred to as alphabetic character options.
TRACE actions correspond to the alphabetic character options as follows:
- All
Traces (that is, displays) all clauses before execution.
- Commands
Traces all commands before execution. If the command results in an error or failure (see
Section 1.15.2, “Commands”), tracing also displays the return code from the command.
- Error
Traces any command resulting in an error or failure after execution (see
Section 1.15.2, “Commands”), together with the return code from the command.
- Failure
Traces any command resulting in a failure after execution (see
Section 1.15.2, “Commands”), together with the return code from the command. This is the same as the
Normal option.
- Intermediates
Traces all clauses before execution. Also traces intermediate results during the evaluation of expressions and substituted names.
- Labels
Traces only labels passed during execution. This is especially useful with debug mode, when the language processor pauses after each label. It also helps the user to note all internal subroutine calls and transfers of control because of the SIGNAL instruction.
- Normal
Traces any failing command after execution, together with the return code from the command. This is the default setting.
For the default Windows command processor, an attempt to enter an unknown command raises a FAILURE condition. The CMD return code for an unknown command is 1. An attempt to enter a command in an unknown command environment also raises a FAILURE condition; in such a case, the variable RC is set to 30.
- Off
Traces nothing and resets the special prefix option (described later) to OFF.
- Results
Traces all clauses before execution. Displays the final results (in contrast with Intermediates option) of the expression evaluation. Also displays values assigned during PULL, ARG, PARSE, and USE instructions. This setting is recommended for general debugging.
