TRACE

─ TRACE ─┬──────────────────┬──────────┬────────┬─;─
           │ ┌───────────┐    └─ number ─┘        │

           │            │                        │

           └─┴─┬───────┬─┴─┬────────────────────┬─┘
               └───?───┘   ├── All ─────────────┤
                           ├── Commands ────────┤

                           ├── Error ───────────┤
                           ├── Failure ─────────┤
                           ├── Intermediates ───┤
                           ├── Labels ──────────┤

                           ├── Normal ──────────┤

                           ├── Off ─────────────┤
                           └── Results ─────────┘

Or, alternatively:

──TRACE───┬──────────────────────────┬───;───────
            ├──────string──────────────┤

            ├──────symbol──────────────┤

            └──┬───────┬──expression───┘
               └─VALUE─┘

TRACE is used for debugging. It controls the tracing action taken (that is, how much is displayed to the user) during execution of a REXX program. The syntax of TRACE is more concise than other REXX instructions. The economy of key strokes for this instruction is especially convenient since TRACE is usually entered manually during interactive debugging.

The number is a whole number.

The string or expression evaluates to:

o

A number option
o
One of the valid prefix, alphabetic character (word) options, or both, shown in this panel
o
Null.

The symbol is taken as a constant and is:

o

A number option
o
One of the valid prefix, alphabetic character (word) options, or both, shown in this panel.

The tracing action is determined from the option specified following TRACE or from the result of evaluating expression. If expression is used, you can omit the subkeyword VALUE as long as expression starts with a special character or operator (so it is not mistaken for a symbol or string).

Alphabetic Character (Word) Options

Although it is acceptable to enter the word in full, only the uppercase letter is significant; all other letters are ignored. That is why these are referred to as alphabetic character options.

TRACE actions correspond to the alphabetic character options as follows:

All

All clauses are traced (that is, displayed) before execution.
Commands
All host commands are traced before execution, and any error return code is displayed.
Error
Any host command resulting in an error return code is traced after execution.
Failure
Any host command resulting in a failure is traced after execution. This is the same as the Normal option.
Intermediates
All clauses are traced before execution. Intermediate results during evaluation of expressions and substituted names are also traced.
Labels
Labels passed during execution are traced. This is especially useful with debug mode, when the language processor pauses after each label. It is also convenient for the user to make note of all subroutine calls and signals.
Normal
Any failing host command is traced after execution. This is the default setting.

For the default CMD processor in the OS/2 operating system, an attempt to issue an unknown command raises a FAILURE condition. An attempt to issue a command to an unknown subcommand environment also raises a FAILURE condition; in such a case, the variable RC is set to 2, the OS/2 return code for "file not found".

Off
Nothing is traced, and the special prefix actions (see below) are reset to OFF.
Results
All clauses are traced before execution. Final results (contrast with Intermediates, above) of evaluating an expression are traced. Values assigned during PULL, ARG, and PARSE instructions are also displayed. This setting is recommended for general debugging.

Prefix Option

The prefix ? is valid either 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 ? modifies tracing and execution. ? is used to control interactive debug. During normal execution, a TRACE instruction prefixed with ? causes interactive debug to be switched on.

When interactive debug is in effect, you can switch it off by issuing a TRACE instruction with a prefix ?. Repeated use of the ? prefix, therefore, switchs you alternately in and out of interactive debug. Or, interactive debug can be turned off 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. 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.

If interactive debug is not active, numeric options are ignored.

Format of TRACE Output

Every clause traced will be displayed with automatic formatting (indentation) according to its logical depth of nesting and so on, and the results (if requested) are indented an extra two spaces and are enclosed in double quotation marks so that leading and trailing blanks are apparent.

All lines displayed during tracing have a three-character prefix to identify the type of data being traced. The prefixes and their definitions are the following:

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

  The following prefixes are only used if Intermediates (TRACE I) are being traced:

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

  ---

  [Back: SIGNAL]
  [Next: Functions]