TRACE - BINARY AND SUBALGOL PACKAGE

To Trap and Report all Transfers:
For Program Debugging

J. Lederberg
June 30, 1964

INTEGER LIBRARY PROCEDURE CLOCK(0)$

GLOBAL INTEGER TRAPOFFS

GLOBAL EXTERNAL SUBROUTINE SETTRAPS

PROCEDURE TRAPEM(FROM, FRA, LOCTAR, PLATAR, XR1,XR2,XR4,1FEX,CT,OV,QP
MQ,AC,CLATAR) $

INTEGER EXTERNAL PROCEDURE COREVAL(LOC) ,LOCR(S$SLABEL) $

TRACE is useful mainly to debug external procedures, though it may have
exceptional applications in diagnosing mysterious halts and loops in BALGOL,
especially if these originate from data or compiler errors.

CLATAR in TRAPEM is equivalenced from TRACE; the other value parameters
are defined by reference to CLATAR and are used to save and report the registers.

The procedure uses the trapping mode (ETM) to trap every successful
transfer. The registers having been saved and effective addresses calculated,
a TSX TRAPEM,4 transfers to the BALGOL PROCEDURE TRAPEM(), which generates a
report.

The report comprises FRA = address containing FROM = transfer instruction
to LOCTAR, which contains the instruction CLATAR, followed by the registers.

If LOCTAR is library procedure (address higher than EXIT), it is marked * and
IFEX is set = 1, which results in the suspension of trap until the return. The
trap is also disarmed upon TRA .EXIT.

To set the trap, call ENTER SETTRAP$. TRAPOFF=1$ will result in the trap
being released after the next transfer. To resume trapping, TRAPOFF = 0$
ENTER SETTRAPS. |

The remaining value parameters are CT (sense indicators), PLATAR
(instructions saved from the return point of the last library procedure), @V
(AC-overflow indicator) and QP (AC-overflow bits). One may use these variables

for more elaborate manipulations and selective reporting, e.g., to test for a
spurious store since the last transfer, or to call for a selective dump with
COREVAL(FRA+N): see below. However, as the registers are reloaded and the
address recalculated from these variables, they should be protected from

unwanted alteration.

Programming notes:

The programmer can arrange his own output format to display the registers
he is interested in. He should also arrange for selective printout by embedding
WRITE(SS$DIAG,NOSIS) in a suitable condition, since output line-count and program
time are even more costly than TRACE itself.

INTEGER EXTERNAL PROCEDURE COREVAL(LOC) gives the programmer access to
absolute locations of core. . For example, he may wish to reference locations

relative to FRA, or to other pivotal points in his program.

INTEGER EXTERNAL PROCEDURE LOCR(S$SLABEL) Supplies the absolute

location of a variable or program label.
Programs which use specially written external procedures (i.e. not

library procedures) for exit or input-output or other valunerable routines
will need special provision to disarm the trap before they are called. The
equivalenced name .EXIT is used to define the boundary between main program
and library procedures.

TRACE is more conservative in saving registers than many library procedures;
e.g. WRITE will set the MQ register and the AC-overflow indicator. In TRACE,
however, these are saved before, and restored after entry to TRAPEM in which ©

WRITE is called.