1 Trace instruction

The trace instruction controls trace activities associated with the current procedure.

The trace instruction has the following syntax variations:

1. trace setting

2. trace [ VALUE ] settingExpression

3. trace

1.1 1. trace setting

This establishes setting as the current setting of trace activities.

Observe: you should use quotes to establish an explicit trace setting; i.e. TRACE 'I'. setting can be a symbol or a literal. When it is a symbol, the symbol's value is used as the trace setting. Consider the following:

do i=1 to 3 end trace I

The trace instruction above is equivalent to trace '4', instead of trace 'I'.

1.2 2. trace [ VALUE ] settingExpression

This establishes the value of settingExpression as the current setting of trace activities. The value keyword can be omitted if settingExpression does not begin with a symbol or literal string -- i.e. it could start with a parenthesis.

1.3 3. trace

When the trace instruction is entered without any additional text, trace activities are reset to default settings:

• trace normal -- traces commands that have failure completions
• interactive tracing is deactivated

1.4 Trace settings

The following trace settings are supported:

1.4.1 Interactive trace setting prefix -- '?'

A requested trace setting can begin with a '?' prefix. This toggles the activation of interactive tracing. If interactive tracing was previously inactive it is activated. If interactive tracing was previously active it is deactivated.

nnn	skips nnn interactive pauses (see interactive tracing)
-nnn	skips the display of nnn instructions that would normally be traced
All	all instructions are traced before execution
Commands	all commands are traced before execution. Return codes are also traced for commands that complete with error or failure status.
Error	Commands that complete with error status are traced after execution, along with their return codes.
Failure	Commands that complete with failure status are traced after execution, along with their return codes.
Intermediates	All instructions are traced before execution. All terms and intermediate results, and substituted variable names, are traced during expression evaluation. The final result of any expression that is evaluated is also displayed. Values assigned by arg, parse, or pull instructions are also traced.
Labels	shows all labels as execution passes through them.
Normal	Commands that complete with failure status are traced after execution, along with their return codes. (default trace setting)
Off	all trace activities are deactivated, including interactive tracing.
Results	All instructions are traced before execution. The final result of any expression that is evaluated is also displayed. Values assigned by arg, parse, or pull instructions are also traced. (recommended debugging setting)

Note: the trace setting is saved when procedures are invoked as a subroutine or function. Thus, invoked procedures can alter the trace setting for their procedure context, without affecting the prevailing trace setting of the calling procedure's context.

1.5 Interactive tracing

When interactive tracing is active, execution pauses after each instruction is processed. Trace instructions that are encountered during instruction execution are ignored.

While execution is paused, the interactive trace facility prompts for a continuation response, on the associated execution console. The following responses are supported.

1. a completely empty line -- without any spaces

continues execution until the next pause is reached.

2. an isolated equal sign -- '=' -- without any spaces

re-executes the prior instruction.

3. a sequence of Rexx instructions (separated by semicolons)

These are processed as though an interpret instruction were performed at the current program position. The sequence of instructions are performed in the context of the current procedure. Variables can be referenced, assigned, or dropped. The same rules that apply to the interpret instruction apply to the instructions that are entered at the interactive trace pause.

An exit instruction causes processing to be discontinued.

trace instructions can be entered at an interactive trace pause. These are processed as though they existed in the current program at tihs point. Alternative trace settings can be activated. All tracing can be deactivated, including interactive tracing. Leading '?' prefixes in a trace instruction toggles the activation of the interactive trace facility in the normal way.

Note: the state of interactive tracing is saved when procedures are invoked as a subroutine or function. Thus, invoked procedures can alter the trace setting for their procedure context, without affecting the prevailing interactive tracing state of the calling procedure's context.

1.6 Trace output format

When an instruction is traced, it is optionally preceded by leading spaces. These spaces indicate the indentation of the instruction within containing instruction groups -- if, do, or select. Each instruction is preceded by its line number within the source file.

Results are enclosed with leading and trailing double-quotes, so that spaces within the values can be clearly identified.

All lines that are displayed have an additional three character prefix. This prefix helps you determine the type of trace information. The following is a description of trace prefixes.

*-*	instruction source
+++	trace message -- used with command error and failure completions
>>>	expression result -- when trace results is active
>.>	value assigned to a placeholder (.) during parsing

The following prefixes are used when trace intermediates is active.

>V>	variable value
>L>	literal string, constant, or unassigned variable
>F>	function call result
>P>	prefix operator result
>O>	result of operator with two terms
>C>	derived name of a compound symbol -- if a variable value was substituted