TRACE

TRACE controls the tracing action (that is, how much is displayed to the user) during processing of a REXX program.

Alternatively:

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.) For this use, economy of key strokes is especially convenient.

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 later
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 later.

The option that follows TRACE or 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).

Alphabetic character (word) options

Although you can enter the word in full, only the capitalized and highlighted letter is needed; all characters following it are ignored. That is why these are referred to as alphabetic character options. See Commands to External Environments for definitions of ERROR and FAILURE.

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,tracing also displays the return code from the command.
Error: Traces any command resulting in an error or failure after execution, together with the return code from the command.
Failure: Traces any command resulting in a failure after execution, 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 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 command resulting in a negative return code after execution, together with the return code from the command. This is the default setting.
Off: Traces nothing and resets the special prefix options (described later) to OFF.
Results: Traces all clauses before execution. Displays final results (contrast with Intermediates, preceding) of evaluating an expression. Also displays values assigned during PULL, ARG, and PARSE instructions. This setting is recommended for general debugging.
Scan: Traces all remaining clauses in the data without them being processed. Basic checking (for missing ENDs and so forth) is carried out, and the trace is formatted as usual. This is valid only if the TRACE S clause itself is not nested in any other instruction (including INTERPRET or interactive debug) or in an internal routine.

Prefix options

The prefixes ! and ? are valid either alone or with one of the alphabetic character options. You can specify both prefixes, in any order, on one TRACE instruction. You can specify a prefix more than one time. Each occurrence of a prefix on an instruction reverses the action of the previous prefix. The prefix(es) must immediately precede the option (no intervening blanks).

The prefixes ! and ? modify tracing and execution as follows:

?

Controls interactive debug. During usual execution, a TRACE option with a prefix of ? causes interactive debug to be switched on. See Interactive debugging of programs. While interactive debug 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).

Any TRACE instructions in the program being traced are ignored. (This is so that you do not exit from interactive debug unexpectedly.)

You can switch off interactive debug in several ways:

Entering TRACE O turns off all tracing.
Entering TRACE with no options restores the defaults. It turns off interactive debug but continues tracing with TRACE Normal (which traces any failing command after execution) in effect.
Entering TRACE ? turns off interactive debug and continues tracing with the current option.
Entering a TRACE instruction with a ? prefix before the option turns off interactive debug and continues tracing with the new option.

Using the ? prefix, therefore, switches you alternately in or out of interactive debug. (Because the language processor ignores any further TRACE statements in your program after you are in interactive debug, use CALL TRACE '?' to turn off interactive debug.)

!

Inhibits host command execution. During regular execution, a TRACE instruction with a prefix of ! suspends execution of all subsequent host commands. For example,

TRACE
!C

causes commands to be traced but not processed. As each command is bypassed, the REXX special variable RC is set to 0. You can use this action for debugging potentially destructive programs. This does not inhibit any commands entered manually while in interactive debug. These are always processed.

You can switch off command inhibition, when it is in effect, by issuing a TRACE instruction with a prefix !. Repeated use of the ! prefix, therefore, switches you alternately in or out of command inhibition mode. Or, you can turn off command inhibition at any time by issuing TRACE O or TRACE with no options.

Numeric options

If interactive debug is active and if 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 over. (See Interactive debugging of programs.) 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, in fact, displayed. After that, tracing resumes as before.

Tracing tips

When a loop is being 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).
If available at the time of execution, comments associated with a traced clause are included in the trace, as are comments in a null clause, if you specify TRACE A, R, I, or S.
Commands traced before execution always have the final value of the command (that is, the string passed to the environment), and the clause generating it produced in the traced output.
Trace actions are automatically saved across subroutine and function calls. See CALL.

Example

One of the most common traces to use is:

TRACE ?R
/* Interactive debug is switched on if it was off, */
/*  and tracing Results of expressions begins.     */

Format of TRACE output

Every clause traced appears with automatic formatting (indentation) according to its logical depth of nesting and so forth. The language processor may replace any control codes in the encoding of data (for example, EBCDIC values less than '40'x) with a question mark (?) to avoid console interference. Results (if requested) are indented an extra two spaces and are enclosed in double quotation marks so that leading and trailing blanks are apparent.

A line number precedes the first clause traced on any line. If the line number is greater than 99999, the language processor truncates it on the left, and the ? prefix indicates the truncation. For example, the line number 100354 appears as ?00354. 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 may be the nonzero return code from a command, the prompt message when interactive debug is entered, an indication of a syntax error when in interactive debug, or the traceback clauses after a syntax error in the program.
>>>: Identifies the result of an expression (for TRACE R) or the value assigned to a variable during parsing, or the value returned from a subroutine call.
>.>: Identifies the value assigned to a placeholder during parsing (see The period as placeholder ).

The following prefixes are used only if

TRACE
Intermediates

is in effect:

>C>: The data traced is the name of a compound variable, traced after substitution and before use, provided that the name had the value of a variable substituted into it.
>F>: The data traced is the result of a function call.
>L>: The data traced is a literal (string, uninitialized variable, or constant symbol).
>O>: The data traced is the result of an operation on two terms.
>P>: The data traced is the result of a prefix operation.
>V>: The data traced is the contents of a variable.

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 , command inhibition (!) off, and interactive debug (?) off.

Following a syntax error that SIGNAL ON SYNTAX does not trap, the clause in error is always traced. Any CALL or INTERPRET or function invocations active at the time of the error are also traced. If an attempt to transfer control to a label that could not be found caused the error, that label is also traced. The special trace prefix +++ identifies these traceback lines.