>>-TRACE--+----------------------------------+--;-------------->< +-number---------------------------+ | .-Normal--------. | '-+-----------+--+---------------+-' | .-------. | +-All-----------+ | V | | +-Commands------+ '---+-?-+-+-' +-Error---------+ '-!-' +-Failure-------+ +-Intermediates-+ +-Labels--------+ +-Off-----------+ +-Results-------+ '-Scan----------'
Or, alternatively:
>>-TRACE--+-----------------------+--;------------------------->< +-string----------------+ +-symbol----------------+ '-+-------+--expression-' '-VALUE-'
TRACE controls the tracing action (that is, how much is displayed to the user) during 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.) 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:
The symbol is taken as a constant, and is, therefore:
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).
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.
TRACE actions correspond to the alphabetic character options as follows:
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, if desired. 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:
Any TRACE instructions in the program being traced are ignored. (This is so that you are not taken out of interactive debug unexpectedly.)
You can switch off interactive debug in several ways:
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.)
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.
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 separate section in Interactive Debugging of Programs, 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, in fact, displayed. After that, tracing resumes as before.
One of the most common traces you will use is:
TRACE ?R
/* Interactive debug 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 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:
The following prefixes are used only if TRACE Intermediates is in effect:
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.