TRACE
by Stuart Nicholls
from Personal Computer News weekly, 6th April 1985


TRACE OF A SOLUTION

If the frustration of debugging your programs threatens to drive you
into the mad-house, try this handy machine code solution from Stuart
Nicholls. And it opens up a new avenue of programming possibilities.


Spectrum owners who can't face another mammoth Basic program debugging
exercise could try this machine code solution. It helps with the
debugging and opens up a range of possibilities for machine code
programmers.

You'll cover the method of running a Basic program under the control
of the operator, stepping through the program a statement at a time,
either at predetermined intervals or when a key is pressed, displaying
the line and statement number being executed. In other words you'll
end up with a TRACE (TRON) facility as found on many other computers.

This routine is not interrupt driven: it diverts the running of a
Basic program from the ROM interpreter to our own interpreter in RAM.
With this set up, it is a simple matter to insert an extra machine
code routine (TRON) into the interpreter so a printout can be given
after each statement is executed.


Using the program

To set up the routine use a hex loader and enter the code as in the
hexdump. Don't forget to set RAMTOP to 64499 before entering the code.
Then save it using:
	SAVE "TRACE" CODE 64500,547
To check the routine you need to know some of the following instructions.

The delay between the execution of each statement is set up in a
similar manner to the PAUSE command, in that the unused system
variables 23728/ 23729 hold the number of 1/50th seconds delay. For
example, a delay of two seconds requires the direct commands:
	POKE 23728,100 : POKE 23729,0
Similarly a delay of ten seconds requires:
	POKE 23729,INT (500/256) : POKE 23728,(500-256*PEEK 23729)
An infinite delay that allows a step only when a key is pressed is:
	POKE 23728,0 : POKE 23729,0

Once this delay is set up and your Basic program is loaded, run it
using:
	RANDOMIZE USE 64500 : RUN
as a direct command. If it's the first line of your program use:
	1 RANDOMIZE USE 64500: GO TO NEXT LINE

Your program should now run as normal, but with a printout at 21,0; of
the current line and statement in the form [20:5]. All errors are
reported when found and the break keys function. What's more, if a bug
is found, it can be corrected and the program run without the TRACE
using the RUN command in the usual way thus using the ROM interpreter.

Listing 2 is my assembly listing for machine code programmers who are
interested in the working of the routine. The main part is a copy of
that in ROM but with the addition of the CALL TRON routine at line
0545; ie. after the correct interpretation of a statement and the
checking of the break keys (line 0510)

The diverting of the ROM interpreter is achieved at the beginning of
the code by ensuring that the ERR-SP is correctly set up with 1303h
and that the machine stack is cleared. In other words, the command
RANDOMIZE USR 64500 is assumed completed when the code reaches line
0024, and our interpreter takes over to execute the next statement at
STLP line 0040; the next statement, of course, is run and as such
[0:2] is the first TRACE output.

Machine code programmers will also notice that it has been necessary
to redirect the REM and IF commands to run in our RAM interpreter, as
those in ROM will cause the routine to re-enter the ROM interpreter
and we would lose our TRACE.

This method of diverting the ROM interpreter to one in RAM opens up
the path to rewriting the whole of Spectrum Basic.
