>>-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.)
Note: TRACE cannot be used in the Rexx macrospace. See Trace in Macrospace.
If specified, the number must be a whole number.
The string or expression evaluates to:
A numeric option
One of the valid prefix or alphabetic character (word) options described in Alphabetic Character (Word) Options
Null
The symbol is taken as a constant and is therefore:
A numeric option
One of the valid prefix or alphabetic character (word) options described in Alphabetic Character (Word) Options
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.
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:
Traces (that is, displays) all clauses before execution.
Traces all commands before execution. If the command results in an error or failure (see Commands), tracing also displays the return code from the command.
Traces any command resulting in an error or failure after execution (see Commands), together with the return code from the command.
Traces any command resulting in a failure after execution (see Commands), together with the return code from the command. This is the same as the Normal option.
Traces all clauses before execution. Also traces intermediate results during the evaluation of expressions and substituted names.
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.
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.
Traces nothing and resets the special prefix option (described later) to OFF.
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.
The prefix ? is valid alone or with one of the alphabetic character options. You can specify the prefix more than once, if desired. Each occurrence of a prefix on an instruction reverses the action of the previous prefix. The prefix must immediately precede the option (no intervening blanks).
The prefix ? controls interactive debugging. During normal execution, a TRACE option with a prefix of ? causes interactive debugging to be switched on. (See Debugging Aids for full details of this facility.) When interactive debugging is on, interpretation pauses after most clauses that are traced. For example, the instruction TRACE ?E makes the language processor pause for input after executing any command that returns an error, that is, a nonzero return code or explicit setting of the error condition by the command handler.
Any TRACE instructions in the program being traced are ignored to ensure that you are not taken out of interactive debugging unexpectedly.
You can switch off interactive debugging in several ways:
Entering TRACE O turns off all tracing.
Entering TRACE with no options restores the defaults--it turns off interactive debugging but continues tracing with TRACE Normal (which traces any failing command after execution).
Entering TRACE ? turns off interactive debugging and continues tracing with the current option.
Entering a TRACE instruction with a ? prefix before the option turns off interactive debugging and continues tracing with the new option.
Using the ? prefix, therefore, switches you in or out of interactive debugging. Because the language processor ignores any further TRACE statements in your program after you are in interactive debug mode, use CALL TRACE "?" to turn off interactive debugging.
If interactive debugging is active and the option specified is a positive whole number (or an expression that evaluates to a positive whole number), that number indicates the number of debug pauses to be skipped. (See Debugging Aids for further information.) However, if the option is a negative whole number (or an expression that evaluates to a negative whole number), all tracing, including debug pauses, is temporarily inhibited for the specified number of clauses. For example, TRACE -100 means that the next 100 clauses that would usually be traced are not displayed. After that, tracing resumes as before.
When a loop is traced, the DO clause itself is traced on every iteration of the loop.
You can retrieve the trace actions currently in effect by using the TRACE built-in function (see TRACE).
The trace output of commands traced before execution always contains the final value of the command, that is, the string passed to the environment, and the clause generating it.
Trace actions are automatically saved across subroutine, function, and method calls. See CALL for more details.
One of the most common traces you will use is:
TRACE ?R /* Interactive debugging is switched on if it was off, */ /* and tracing results of expressions begins. */
Every clause traced appears with automatic formatting (indentation) according to its logical depth of nesting, for example. Results, if requested, are indented by two extra spaces and are enclosed in double quotation marks so that leading and trailing blanks are apparent. Any control codes in the data encoding (ASCII values less than "20"x) are replaced by a question mark (?) to avoid screen interference. Results other than strings appear in the string representation obtained by sending them a STRING message. The resulting string is enclosed in parentheses. The line number in the program precedes the first clause traced on any line. All lines displayed during tracing have a three-character prefix to identify the type of data being traced. These can be:
Identifies the source of a single clause, that is, the data actually in the program.
Identifies a trace message. This can be the nonzero return code from a command, the prompt message when interactive debugging is entered, an indication of a syntax error when in interactive debugging.
Identifies the result of an expression (for TRACE R) or the value assigned to a variable during parsing, the value returned from a subroutine call, or a value evaluated by execution of a DO loop.
Identifies the value assigned to a placeholder during parsing (see The Period as a Placeholder).
The following prefixes are used only if TRACE Intermediates is in effect:
Identifies a value used as a function, subroutine, or message argument.
The data traced is the orignal name of the compound variable and the name of a compound variable, after the name has been replaced by the value of the variable but before the variable is used. If no value was assigned to the variable, the trace shows the variable in uppercase characters.
The data traced is the name and value of an environment symbol.
The data traced is the name and result of a function call.
The data traced is a literal (string, uninitialized variable, or constant symbol).
The data traced is the name and result of an object message.
The data traced is the name and result of an operation on two terms.
The data traced is the name and result of a prefix operation.
The data traced is the name and contents of a variable.
Note: The characters => indicate the value of a variable or the result of an operation.
The character ? could indicate a non-printable character in the output.
If no option is specified on a TRACE instruction, or if the result of evaluating the expression is null, the default tracing actions are restored. The defaults are TRACE N and interactive debugging (?) off.
Following a syntax error that SIGNAL ON SYNTAX does not trap, the clause in error is always traced.