ARexx provides a tracing mode called command inhibition that suppresses host commands. In this mode command clauses are evaluated in the normal manner, but the command is not actually sent to the external host, and the return code is set to zero. This provides a way to test programs that issue potentially destructive commands, such as erasing files or formatting disks. Command inhibition does not apply to command clauses that are entered interactively. These commands are always performed, but the value of the special variable RC is left unchanged.
Command inhibition may be used in conjunction with any trace option. It is controlled by the "!" character, which may appear by itself or may precede any of the alphabetic options in a TRACE instruction. Each occurrence of the "!" character "toggles" the inhibition mode currently in effect. Command inhibition is cleared when tracing is set to OFF.
Interactive tracing is a debugging facility that allows the user to enter source statements while a program is executing. These statements may be used to examine or modify variable values, issue commands, or otherwise interact with the program. Any valid language statements can be entered interactively, with the same rules and restrictions that apply to the INTERPRET instruction. In particular, compound statements such as DO and SELECT must be complete within the entered line.
Interactive tracing can be used with any of the trace options. While in interactive tracing mode, the interpreter pauses after each traced clause and prompts for input with the code "+++". At each pause, three types of user responses are possible:
The interpreter pauses after traceable clauses. Tracing options determine the location of the pauses. The interpreter does not pause after the instructions CALL, DO, ELSE, IF, THEN, and OTHERWISE. When any clause generates an execution error, the interpreter exits the program.
Interactive tracing is controlled by the "?" character, either by itself or in combination with an alphabetic trace option. Any number of "?" characters may precede an option. Each occurrence toggles the mode currently in effect. For example, if the current trace option was NORMAL, "TRACE ?R" would set the option to RESULTS and select interactive tracing mode. A subsequent "TRACE ?" would turn off interactive tracing.
The ARexx interpreter provides error processing during debugging. Errors found during interactive debugging are reported, but do not terminate the program. This special processing only applies to statements entered interactively.
ARexx also disables the internal interrupt flags during interactive debugging. This prevents an accidental transfer of control due to an error or uninitialized variable. However, if a "SIGNAL label" instruction is entered, the transfer will take place and any remaining interactive input will be abandoned. The SIGNAL instruction can still be used to alter the interrupt flags, and the new setting will take effect when the interpreter returns to normal processing.
Each ARexx task initializes its command failure level to the client's failure level (usually 10) to suppress printing of nuisance command errors. The failure level can be changed using OPTIONS FAILAT. Command errors (RC > 0) and failure (RC >= FAILAT) can be separately trapped using SIGNAL ON ERROR and SIGNAL ON FAILURE.
ARexx has an external tracing flag used to force programs into interactive tracing mode. When this tracing flag is set, using the TS command utility, any program not already in interactive tracing mode will enter it immediately. The internal trace option is set to RESULTS unless it is currently set to INTERMEDIATES or SCAN, in which case it remains unchanged. Programs invoked while the external tracing flags is set will begin executing in interactive tracing mode.
The external tracing flag provides a way to regain control over looping or unresponsive programs. Once a program enters interactive tracing mode, the user can step through the program statements and diagnose the problem. External tracing is a global flag, so all currently-active programs are affected by it. The tracing flag remains set until it is cleared using the TE command utility. Each program maintains an internal copy of the last state of the tracing flag and sets its tracing option to OFF when it observes that the tracing flag has been cleared. Programs in BACKGROUND tracing mode do not respond to the external tracing flag.
