AmigaOS Manual: ARexx Debugging

ARexx provides tracing and source-level debugging facilities. Tracing displays selected statements in a program as the program executes. When a clause is traced, its line number, source text, and related information are displayed on the console.

The internal interrupt system enables an ARexx program to detect certain synchronous or asynchronous events and to take special actions when they occur. Events such as a syntax error or an external halt request that would normally cause the program to exit can instead be trapped so that corrective actions can be taken.

Tracing

The tracing action selects which source clauses will be traced and has two modifier flags that control command inhibition and interactive tracing. Trace options can be shortened to one letter. The Trace options are:

ALL

All clauses are traced.

BACKGROUND

No tracing is performed and the program cannot be forced into interactive tracing.

COMMANDS

All command clauses are traced before being sent to the external host. Non-zero return codes are displayed on the console.

ERRORS

Commands that generate a non-zero return code are traced after the clause is executed.

INTERMEDIATES

All clauses are traced and intermediate results are displayed during expression evaluation. These include the values retrieved for variables, expanded compound names, and the results of function calls.

LABELS

All label clauses are traced as they are executed. A label will be displayed each time a transfer of control takes place

NORMAL (Default)

Command clauses with return codes that exceed the current error failure level are traced after execution and an error message is displayed.

OFF

Tracing is turned off.

RESULTS

All clauses are traced before execution and the final result of each expression is displayed. Values assigned to variables by ARG, PARSE or PULL instructions are also displayed. This option is recommended for general-purpose testing.

SCAN

This is a special option that traces all clauses and checks for errors, but suppresses the actual execution of the statements. If is helpful as a preliminary screening step for a newly-created program.

The tracing mode can be set using either the TRACE instruction or the TRACE() built-in function. Tracing can be selectively disabled from within a program to skip previously tested parts of a program.

Each trace line displayed on the console is indented to show the effective control (nesting) level at that clause and is identified by a special three-character code, as shown in Table 6-1. The source for each clause is preceded by its line number in the program.

Expression results or intermediates are enclosed in double quotes so that leading and trailing blanks will be apparent.

Table 6-1. Special Three Character Codes

Code	Displayed Values
+++	Command or syntax error
>C>	Expanded compound name
>F>	Result of a function call
>L>	Label clause
>O>	Result of a dyadic operation
>P>	Result of a prefix operation
>U>	Uninitialized variable
>V>	Value of a variable
>>>	Expression or template result
>.>	"Place holder" token value