BASIC TRACER
Powerful debugging utility
by KEVIN GEVATOSKY
BASIC Tracer is a powerful debugging tool that displays onscreen the line number being executed by your program. This BASIC program requires an Atari XL or XE model with al least 32K memory and a disk drive.
If you write long BASIC programs, you've probably spent long hours trying to figure out what made a GOTO or GOSUB go somewhere it shouldn't.
Finding thr bug usually requires inserting STOPs, TRAPs, PRINT statements, etc. at various points in the program and then RUNning it so you can observe the results. Repeating this "insert and RUN" method enough times should eventually isolate the problem. However, there is now an easier, more direct way to trace the workings of your Atari BASIC program.
BASIC Tracer is a debugging utility for Atari XL and XE computers. It tracks and displaps the current line number that your own BASIC program is pointing to. It also gives you the option of slowing down the execution speed, so that you can see then and where your program is branching. When you find a glitch in your own program's flow, just press the [BREAK] key and execution will stop at the displayed line number so you can solve the problem.
GETTING STARTED
BASIC Tracer is written in MAC/65 asssembly language, but it's adapted to a "BASIC loader" version that will be easier for you to type. Listing 2, TRACER.M65, is the assembly language source code--it is provided just for your information and you don't need to type it.
Type in Listing 1, TRACER.RAS, check it with TYPO II and SAVE a copy before you RUN it. When RUN, the program will write a "load and go" binary file called TRACER.EXE to the disk. Copy this file to another disk and name it AUTORUN.SYS.
USING TRACER
When TRACER.EXE is activated, a blank Graphics 0 text line appears across the top of the screen and you'll see the READY prompt. Type [? A] and you'll see the line number 32768--which BASIC assigns to a statement that has been entered without a line number. Now load or type in a short Atari BASIC program and watch the line number change as the program executes.
If you POKE 207,20 and RUN the program again, you'll notice the line number changing much more slowly. This is because location 207 now contains the delay value used to control BASIC's execution speed, and can be POKEd with any number between 1 and 255. The larger the number POKEd, the slower BASIC will execute. To restore execution speed to normal, POKE 207 with a zero.
Also, holding down [CONTROL] while pressing [ESCAPE] will temporarily bypass the execution delay, and BASIC will proceed at the normal (zero) rate until the [ESCAPE] key is released. This feature is handy for quickly getting through portions of a program that you are not interested in tracing. Finally, program execution can be halted and resumed again by toggling the [CONTROL] [1] key sequence.
HOW IT WORKS
Atari BASIC, unfortunately, does not provide any RAM vectors to its execution control code located in ROM. Thus there is no way to monitor the line number being executed. However, BASIC Tracer overcomes this by copying the BASIC ROM code to lower RAM and then switching off the ROM.
The code is then moved back up to high RAM, starting at address $A000, and a vector is installed at address $A978. This vector points to code on Page 6 which reads the current value of STMCUR ($8A) and displays the value on the text line at the top of the screen.
Control is returned to BASIC via a JMP to STGO (STatement GO) at location $A97E. The 76-byte routine that sets up the RAM-BASIC and installs a vector is only used once--to initialize BASIC Tracer. Since I needed the space on Page 6, I put this routine on the system stack at address $100.
To display the additional text line, I changed the ANTIC instruction for displaying eight blank lines ($70) to the instruction for displaying a Graphics 0 mode line ($42). Of course, the 40 bytes of screen data required to display the mode line had to be located in memory somewhere outside Page 6 that would not be disturbed by BASIC. For this purpose, I chose the cassette buffer at address $400.
This method is compatible with any BASIC program that does not alter the first three instructions of the display list. Whenever BASIC JuMPs through the vector at $A978, BASIC Tracer checks to see if the changes in the display list are still active. If not, a JSR is made to the routine which alters the display list so that the line number will continue to be displayed even with a change in graphics mode.
MORE HINTS
1. Pressing [RESET] re-initializes the BASIC ROM and disables BASIC Tracer.
2. Any BASIC statement which alters Page 6 (or decimal locations 20,207,208 or 209), such as a POKE or USR(1536), must be REMmed out before you attempt to trace the program.
3. Be sure to SAVE any BASIC program in memory before accessing DOS, or the program won't be where you left it when you return.
4. After going to DOS, you can return to the RAM-BASIC by using the RUN AT ADDRESS option (DOS menu choice M) and typing A000.
5. If the Graphics 0 mode line should vanish from the top of the screen, don't panic. It will reappear when BASIC executes the next program statement.
6. In GTIA Graphics 9, 10 and 11, the displayed line number is unreadable.
7. If you load a BASIC program from cassette, then you will have to enter a Graphics 0 command and a [?] to clear the garbage off the line number display.
Kevin Gevatoskry of Eugene, Oregon is the Atari consultant and programmer for Covox Inc., makers of the Voice Master speech system, and a freelance writer-programmer.
Listing1:TRACER.EXE Download