Interrupting Execution and Controlling Tracing
- The HI (Halt Interpretation) immediate command causes all currently executing REXX programs to stop, as though there has been a syntax error. This is especially useful when an editor macro gets into a loop, and it is desirable to halt it without destroying the whole environment (as HX, Halt Execution, would do). When an HI interrupt causes a REXX program to stop, the program stack is cleared. An HI interrupt may be trapped by using SIGNAL ON HALT (SIGNAL).
- The TS (Trace Start) immediate command turns on the external tracing bit. If the bit is not already on, TS puts the program into usual interactive debug and you can then run REXX instructions and so forth as usual (for example, to display variables, EXIT, and so forth). This too is useful when you suspect that a REXX program is looping—you can enter TS, and inspect and step the program before deciding whether to allow the program to continue or not.
- The TE (Trace End) immediate command turns off the external tracing
bit. If it is not already off, this has the effect of executing a
TRACE O instruction. This can be useful to stop tracing when not in
interactive debug (as when tracing was started by issuing SET EXECTRAC
ON and interactive debug was subsequently stopped by issuing
TRACE ?).
The System External Trace Bit:
Before each clause is run, an external trace bit, owned by CMS, is inspected. You can turn the bit on with the TS immediate command, and turn it off with the TE immediate command. You can also alter the bit by using the SET EXECTRAC command (described later). CMS itself never alters this bit, except that it is cleared on return to CMS command level.
The language processor maintains an internal shadow of the external bit, which therefore allows it to detect when the external bit changes from a 0 to a 1, or vice-versa. If the language processor sees the bit change from 0 to 1, ? (interactive debug) is forced on and the tracing action is forced to R if it is A, C, E, F, L, N, or O. The tracing action is left unchanged if it is I, R, or S.
Similarly, if the shadow bit changes from 1 to 0, all tracing is
forced off. This means that tracing may be controlled externally to
the REXX program: you can switch on interactive debug at any time
without modifying the program. The TE command can be useful if a program
is tracing clauses without being in interactive debug (that is, after
SET EXECTRAC ON, TRACE ? was issued). You can use
TE to switch off the tracing without affecting any other output from
the program.
If the external bit is on upon entry to a REXX program, the SOURCE string is traced (see PARSE) and interactive debug is switched on as usual—hence with use of the system trace bit, tracing of a program and all programs called from it, can be easily controlled.
The internal shadow bit is saved and restored across internal routine calls. This means that (as with internally controlled tracing) it is possible to turn tracing on or off locally within a subroutine. It also means that if a TS interrupt occurs during execution of a subroutine, tracing is also switched on upon RETURN to the caller.
You can use the CMSFLAG(EXECTRAC) function and the command QUERY EXECTRAC to test the setting of the system trace bit.
The command SET EXECTRAC ON turns on the trace bit. Using it before invoking a REXX program causes the program to be entered with debug tracing immediately active. If issued from inside a program, SET EXECTRAC ON has the same effect as TRACE ?R (unless TRACE I or S is in effect), but is more global in that all programs called are traced, too. The command SET EXECTRAC OFF turns the trace bit off. Issuing this when the bit is on is equivalent to the instruction TRACE O, except that it has a system (global) effect.