Debugging Atari BASIC Programs: STOP, CONT and Beyond
Atari BASIC has no debugger, no TRACE command and no breakpoints. What it does have is an interactive prompt that stays live after a program stops, direct access to its own memory, and a few well-documented locations that tell you where it is and what it knows. Used together, they make most bugs easy to find. This guide collects the techniques, each tested on Atari BASIC revision C, and points to the classic tools Antic published for the job.
What you need: Atari BASIC (or an emulator with the Atari BASIC ROM) and a program that misbehaves. For the error messages themselves, see Atari BASIC Error Codes Explained; for handling errors inside a program, Error Trapping in Atari BASIC: TRAP, ERRSAVE and Friendly Recovery.
1. Stop, look, and carry on
Press BREAK while a program runs, or put a STOP statement where you want it to pause. BASIC prints STOPPED AT LINE n and returns to the prompt with all variables intact. Now you can:
PRINT X,Y,Sto see values, orPRINT A$to see a string.- Change a value (
L=99) to test a theory. LIST 200,260to read the lines around the problem.- Type
CONTto carry on, orGOTOa line number to resume somewhere else.
There is one surprise. CONT resumes at the start of the next line, not at the statement after STOP. In this test:
10 PRINT "A":STOP:PRINT "B"
20 PRINT "C"
RUN prints A and STOPPED AT LINE 10. Then CONT prints C: the PRINT "B" on the same line is skipped. So put a debugging STOP at the end of a line, or on a line of its own.
You can edit lines while stopped, but be careful when you then CONT. BASIC remembers where it is in active FOR loops and GOSUBs, so don't change those lines. After editing, use RESTORE before the next READ, or BASIC may read garbage from where its DATA pointer used to be.
2. Where am I?
When a program runs through many GOSUBs, it helps to know which line you are in. BASIC keeps a pointer to the line it is executing in STMCUR, locations 138 and 139, and every line starts with its own number:
100 GOSUB 1000
110 PRINT "BACK"
120 END
1000 L=PEEK(138)+256*PEEK(139)
1010 PRINT "NOW AT LINE ";PEEK(L)+256*PEEK(L+1):RETURN
This prints NOW AT LINE 1000, the line where STMCUR was read. Put the same two statements into a subroutine and you have a "who called me" tool. Read STMCUR as the first thing on the calling line, because the value changes as soon as BASIC moves on.
3. Tracing with PRINT
The oldest technique is still the fastest. Add temporary PRINT statements that show what the program is doing:
255 PRINT "I=";I;" Y=";Y(I);" X=";X(I)
Some tips that keep tracing from making things worse:
- Number debug lines oddly (255, 1015) so they are easy to find and delete later.
- In a graphics program, print to the text window, or
LPRINTto a printer so the trace doesn't disturb the screen. An emulator's printer output makes a convenient log. - Trace only the interesting case:
IF Y(I)>22 THEN PRINT ...instead of printing every pass. - Slow things down with a delay loop or by waiting for a key (
IF PEEK(764)=255 THEN 256) to watch a fast loop one step at a time.
4. Catching typos in variable names
Atari BASIC never complains about a misspelled variable. SCROE=SCORE+5 simply creates a new variable called SCROE, leaving the real score unchanged. The cure is to look at the variable name table, which lists every name BASIC has seen, in the order it first met them. Locations 130–131 (VNTP) point to its start and 132–133 (VNTD) to its end. The last letter of each name has bit 7 set.
Add this routine at the end of any program, run the program, then type GOTO 32000:
32000 REM LIST VARIABLE NAMES
32010 A=PEEK(130)+256*PEEK(131):E=PEEK(132)+256*PEEK(133)
32020 FOR I=A TO E-1:C=PEEK(I)
32030 IF C<128 THEN PRINT CHR$(C);
32040 IF C>=128 THEN PRINT CHR$(C-128);" ";
32050 NEXT I:PRINT
With a three-line test program that misspells SCORE, the output was:
SCORE LIVES SCROE A E I C
SCROE stands out at once. The last four names belong to the routine itself, and arrays and strings show with their ( or $. The routine works because each name byte below 128 is printed as it is, and a byte of 128 or more ends a name.
Two related facts help here:
- Names never leave the table on their own. Delete every line that used a variable and its name stays, still counting towards the limit of 128 names (ERROR 4).
LIST "D:PROG.LST",NEW, thenENTER "D:PROG.LST"rebuilds a clean table. - In June 1984 Antic published Jerry White's "BASIC - A Variable Approach", a pair of utilities on the same idea. A routine merged in at line 32000 walks the same table, asks you to type a short description of each variable, and writes the list to
D:VARIABLE.DAT. A second program sorts the list and prints it: instant documentation for a large program.
5. Runtime-stack leaks
BASIC keeps the return points of GOSUBs and the state of FOR loops on a runtime stack. Leaving them the wrong way leaves entries behind:
- GOSUB without RETURN. Jumping out of a subroutine with GOTO leaves its return address on the stack. Do it in a loop and the stack grows until memory runs out. The two-line test
10 N=N+1:GOSUB 20/20 GOTO 10stopped with ERROR 2 (insufficient memory) at line 10, andPRINT Nshowed 9,466 unreturned GOSUBs. In a real program the error appears long after the cause, which makes it hard to trace. - The fix is POP.
POPdiscards the most recent GOSUB (or FOR) entry, so a subroutine that has to exit by GOTO should POP first. WithPOPadded, the same loop ran 3,000 times without trouble. - FOR loops left by GOTO are less dangerous. Running the same
FOR I=...again replaces the old entry for I, so a loop that jumped out ofFOR I=1 TO 10and re-entered it 3,000 times finished without an error. Jumping out of a FOR into code that never comes back is still worth tidying with POP. - RETURN without GOSUB (ERROR 16) usually means the program fell into a subroutine. Put an
ENDor aGOTObefore the first subroutine.
6. Finding the slow parts
When a program works but is too slow, measure before you optimise. The jiffy clock at locations 18–20 counts frames (60 a second on NTSC, 50 on PAL):
100 POKE 19,0:POKE 20,0
110 REM ... code to time ...
120 PRINT "TOOK ";PEEK(19)*256+PEEK(20);" JIFFIES"
Time one suspect section at a time, and change one thing between runs. Making Atari BASIC Faster (and Smaller) lists the usual fixes.
For a whole program, Antic's Bottleneck Breaker (Stan Lackey, April 1989) is a real profiler. A machine-language routine runs on POKEY's Timer 1 interrupt, samples STMCUR (locations 138–139) more than 250 times a second, and counts which lines are running, with one counter for every ten line numbers. A report then lists the lines that used the most time. In its own example, a single line containing a cosine took 71% of the run time. It slows the program by about 25% while profiling, needs 8K for its counters and uses locations 203–208, and the program being profiled must leave lines 1–3 and 31000–31010 free. A 130XE version that keeps the counters in extended memory, by Eric Woodruff, followed in the October/November 1989 issue.
7. Help from an emulator
An emulator adds tools a real Atari never had:
- Save states let you return to the moment before a crash and try again.
- Warp speed gets you quickly to a bug that appears after minutes of play.
- Altirra's debugger understands Atari BASIC.
.basic_varslists every variable with its value, and.basic_dumpline *decodes the line being executed, all without touching the program. It can also set breakpoints on addresses and watch locations change, which is handy when a POKE writes somewhere it shouldn't (see Mastering the Altirra Debugger). - Printer and H: device output captures LPRINT traces and LISTings to files on the PC.
Troubleshooting
| Symptom | Likely cause | What to try |
|---|---|---|
| A variable keeps its old value | Misspelled name elsewhere | List the variable names (section 4) |
| CONT skips some statements | CONT resumes at the next line | Put STOP at the end of a line |
| READ gives nonsense after editing | Stale DATA pointer | RESTORE before READ |
| ERROR 2 after the program has run for a while | GOSUBs never RETURNed | POP before leaving a subroutine with GOTO |
| ERROR 4 in a program with few variables | Old names left in the table | LIST to disk, NEW, ENTER |
| ERROR 13 or 16 | Mismatched FOR/NEXT or RETURN | Check the flow around the line reported |
| Program much slower than expected | One hot line | Time sections, or use a profiler |
Further reading
- Atari BASIC Reference Manual, on STOP, CONT, POP and TRAP.
- Antic, June 1984: Jerry White, "BASIC - A Variable Approach". Antic, April 1989: Stan Lackey, "Bottleneck Breaker".
- On this site: Atari BASIC Error Codes Explained, Error Trapping in Atari BASIC: TRAP, ERRSAVE and Friendly Recovery, Inside a SAVEd Atari BASIC Program, Ram Cram: Squeezing Big Programs into Atari BASIC, Making Atari BASIC Faster (and Smaller).
Credits
- Picture: The variable-name lister from section 4 exposing a typo: SCROE sits next to SCORE. — Program authors; screenshot by the site
- Antic Vol. 7 No. 12 (April 1989) — Stan Lackey, Bottleneck Breaker (BASIC profiler) — AtariMagazines.com (Kevin Savetz), 1989
- Antic Software Archive — June 1984 disk: Jerry White, BASIC - A Variable Approach (VARIFILE, VARISORT listings) — J. D. Casten, 1984
- Antic Software Archive — Basic Profiler for 130XE (Eric Woodruff), October/November 1989 disk — AtariMagazines.com (Kevin Savetz), 1989
- Classic Computer Magazine Archive — Antic Vol. 3 No. 2 (June 1984) index (Toolbox: BASIC - A Variable Approach by Jerry White) — Jerry White; AtariMagazines.com (Kevin Savetz), 1984
- Altirra BASIC Reference Manual — compatibility notes on Atari BASIC's DATA pointer cache and CONT — Avery Lee (Altirra)
- Mapping the Atari — 18-20 RTCLOK, 130-133 VNTP/VNTD, 138-139 STMCUR, 764 CH — AtariArchives.org
