Error Trapping in Atari BASIC: TRAP, ERRSAVE and Friendly Recovery
A program that works perfectly for its author can still collapse the moment somebody else uses it: a write-protected disk, a typo at an INPUT prompt, an empty drive. In Atari BASIC an unhandled error stops the program dead with a terse ERROR- 144 AT LINE 110 and leaves the user at the READY prompt. Antic's editors once wrote that many otherwise excellent submissions were rejected simply because they lacked error trapping.
This guide shows you how to take control of errors yourself.
You will learn: how TRAP behaves, how to read the error number and the line it happened on, which error codes matter, and several patterns — retry loops, end-of-file detection, "does this file exist?" checks and input validation.
You need: any Atari 8-bit with Atari BASIC (any revision), or an emulator such as Altirra. A disk drive (real or emulated) for the file examples.
1. How TRAP works
TRAP takes a line number. From that moment on, instead of stopping, BASIC jumps to that line whenever an error occurs.
10 TRAP 1000
20 OPEN #1,4,0,"D:NOFILE.DAT"
30 PRINT "OPENED!":END
1000 PRINT "COULD NOT OPEN THE FILE":END
Three rules catch almost everybody out:
- A TRAP fires once. When an error is caught, the trap is used up. If another error happens later and you have not executed a new
TRAP, BASIC handles it the normal way and stops. The usual habit is to re-arm the trap as the very first statement of the handler. - Only the most recent TRAP counts. BASIC remembers one line number. You can therefore point different parts of your program at different handlers simply by executing a new
TRAPbefore each risky section. - To switch trapping off, TRAP to a line that cannot exist. Line numbers run from 0 to 32767, so
TRAP 40000is the conventional "off switch".
2. Finding out what went wrong
BASIC leaves two clues in memory when an error is trapped:
| Location | Name | Contents |
|---|---|---|
| 195 ($C3) | ERRSAVE | Number of the error that caused the stop or the TRAP |
| 186, 187 ($BA, $BB) | STOPLN | Line where the program stopped — by error, BREAK, STOP or TRAP |
1000 TRAP 1000
1010 EN=PEEK(195):EL=PEEK(186)+PEEK(187)*256
1020 PRINT "ERROR ";EN;" AT LINE ";EL
(Antic's article used the variable names ERR and ERL; that is legal in Atari BASIC, but both are reserved words in Turbo-BASIC XL, so names like EN/EL are kinder if your program may ever be run there.)
3. The error codes you will actually meet
Errors below 128 come from BASIC itself; 128 and above come from the operating system's I/O system (CIO) or DOS. The descriptions below follow Carl Evans's appendix in Atari BASIC Faster and Better and the status-code names in the cc65 atari.inc header.
BASIC errors
| Code | Meaning | Typical cause |
|---|---|---|
| 2 | Memory insufficient | DIM too large, program too big |
| 3 | Value error | POKE -37,10, PEEK(99999), a value out of range |
| 4 | Too many variables | more than 128 variable names |
| 5 | String length error | subscript 0 or beyond the DIMensioned length |
| 6 | Out of data | READ ran past the last DATA item |
| 7 | Number greater than 32767 | line number out of range in GOTO/GOSUB/RESTORE |
| 8 | Input statement error | letters typed where a number was expected |
| 9 | Array or string DIM error | used before DIM, DIMmed twice, or too big |
| 10 | Argument stack overflow | expression too complex; runaway GOSUBs |
| 11 | Floating point overflow | division by zero, result too large |
| 12 | Line not found | GOTO/GOSUB to a missing line |
| 13 | No matching FOR | NEXT without FOR |
| 14 | Line too long | e.g. ENTERing a SAVEd (tokenized) file |
| 15 | GOSUB or FOR line deleted | line edited while stopped, then CONT |
| 16 | RETURN error | RETURN without GOSUB |
| 17 | Syntax error (garbage) | corrupted program memory |
| 18 | Invalid string character | e.g. VAL("XYZ") |
| 19 | LOAD program too long | not enough memory to LOAD |
| 20 | Device number error | channel number below 1 or above 7 |
| 21 | LOAD file error | LOADing something that is not a SAVEd BASIC file |
I/O and DOS errors
| Code | Meaning | Code | Meaning |
|---|---|---|---|
| 128 | BREAK key abort | 144 | Device done error (e.g. write-protected disk) |
| 129 | IOCB already open | 145 | Bad screen mode number |
| 130 | Nonexistent device | 146 | Function not implemented in handler |
| 131 | IOCB opened for write only | 147 | Insufficient memory for screen mode |
| 132 | Invalid command | 160 | Invalid drive number |
| 133 | Device or file not open | 161 | Too many open files |
| 134 | Invalid IOCB number | 162 | Disk full |
| 135 | IOCB opened for read only | 163 | Fatal I/O error |
| 136 | End of file | 164 | File number mismatch |
| 137 | Truncated record | 165 | Invalid file name |
| 138 | Device timeout (no response) | 166 | POINT data length error |
| 139 | Device NAK | 167 | File locked |
| 140 | Serial bus framing error | 168 | Command invalid for disk |
| 141 | Cursor out of range | 169 | Directory full |
| 142 | Serial bus data overrun | 170 | File not found |
| 143 | Serial bus checksum error | 171 | POINT invalid |
SpartaDOS and SpartaDOS X add their own codes in the 148–158 range (for example 150 "directory not found" and 151 "file exists"), so a handler that prints an unknown number rather than crashing is worth having.
4. A disk-save routine that survives the real world
This is a tidied version of the approach in Heidi Brumbaugh's Antic article: re-arm the trap, close the channel, decode the error, and offer Retry or Abort.
100 TRAP 30000
110 OPEN #1,8,0,"D:DUCKS.DAT"
120 PRINT #1;"DONALD"
130 PRINT #1;"DAFFY"
140 CLOSE #1
150 PRINT "NAMES SAVED."
160 END
30000 TRAP 30000:CLOSE #1:PRINT
30010 EN=PEEK(195)
30020 IF EN=144 THEN PRINT "DISK IS WRITE-PROTECTED.":GOTO 30100
30030 IF EN=138 THEN PRINT "DRIVE NOT RESPONDING - CHECK CABLES.":GOTO 30100
30040 IF EN=162 THEN PRINT "DISK IS FULL.":GOTO 30100
30050 IF EN=167 THEN PRINT "FILE IS LOCKED.":GOTO 30100
30060 IF EN=169 THEN PRINT "DIRECTORY IS FULL.":GOTO 30100
30070 PRINT "ERROR ";EN;" OCCURRED."
30100 PRINT "PRESS R TO RETRY, A TO ABORT"
30110 OPEN #2,4,0,"K:":GET #2,K:CLOSE #2
30120 IF K=82 OR K=114 THEN 110
30130 IF K=65 OR K=97 THEN 160
30140 GOTO 30110
Points to notice:
- Line 30000 re-arms the trap before doing anything else, so an error inside the handler (say, the keyboard OPEN) does not drop the user to READY.
CLOSE #1is essential: the failed OPEN may have left the channel half-open, and the retry at line 110 would otherwise produce error 129.- The keyboard is read with
GETfrom theK:device; 82/114 and 65/97 are the ATASCII codes for upper- and lower-case R and A.
5. Errors as information
Some errors are not failures at all — they are the cheapest way of asking a question.
Read a file to its end. Rather than storing a record count, read until error 136:
100 DIM L$(120)
110 TRAP 200
120 OPEN #1,4,0,"D:NOTES.TXT"
130 INPUT #1,L$:PRINT L$:GOTO 130
200 TRAP 40000:EN=PEEK(195):CLOSE #1
210 IF EN<>136 THEN PRINT "ERROR ";EN
220 PRINT "DONE."
Does a file already exist? Try to open it for reading first. Error 170 means it does not, so it is safe to create; success means you should ask before overwriting.
Let users extend DATA lists. Antic's example read names with READ until error 6 (out of data) occurred, checking that the error came from the expected READ line before treating it as normal:
30000 TRAP 40000
30010 EN=PEEK(195):EL=PEEK(186)+PEEK(187)*256
30020 IF EN=6 AND EL=130 THEN 160
30030 PRINT "ERROR ";EN;" AT LINE ";EL:END
Checking the line as well as the number stops a genuine bug elsewhere from being silently swallowed.
6. Prevention beats cure
A TRAP is a safety net, not a design. Test for trouble before it happens:
100 PRINT "NUMERATOR";:INPUT N
110 PRINT "DENOMINATOR";:INPUT D
115 IF D=0 THEN PRINT "CAN'T DIVIDE BY ZERO.":GOTO 110
120 PRINT "ANSWER: ";N/D
Likewise, count items as they go into an array instead of waiting for a DIM error, and validate numbers before POKE or SOUND (a value outside 0–255 raises error 3).
A common annoyance is the user pressing RETURN at a numeric INPUT, which raises error 8. Trap it and simply re-prompt:
100 TRAP 100:PRINT "HOW MANY PLAYERS (1-4)";:INPUT P
110 IF P<1 OR P>4 THEN 100
120 TRAP 40000
Troubleshooting
- "My trap worked once, then the program crashed." You did not re-arm it. Put
TRAP nnnnat the top of every handler. - Error 129 on retry. Close the channel inside the handler before jumping back to the OPEN.
- The error is reported on a line that looks perfect. Mistyped DATA statements are the classic culprit: errors 3, 5, 6, 7, 8 and 141 are often reported on the line holding the
READ, not the faultyDATAline. After the stop, print the loop variable and the last value read in direct mode to find which item went wrong. - Mysterious error 10 after many retries. Jumping out of a subroutine or FOR loop with GOTO leaves its entry on BASIC's runtime stack. Repeated often enough, the stack fills. Use
POPbefore leaving a subroutine early. - BREAK still stops the program. TRAP does not catch the BREAK key in Atari BASIC; it can be disabled through POKMSK (location 16) and IRQEN (53774) — see our keyboard guide. Turbo-BASIC XL's
*Bcommand lets TRAP catch BREAK instead, and it addsERRandERLfunctions so you no longer need the PEEKs.
Further reading
- Atari BASIC Faster and Better — Carl M. Evans (IJG, Inc., 1983). Appendix C explains every error code with "wrong" and "correct" examples.
- Mapping the Atari — Ian Chadwick (Small System Services, 1983).
- The Atari BASIC Source Book — Bill Wilkinson, Kathleen O'Brien and Paul Laughton (Small System Services, 1983), for how the interpreter raises errors internally.
Credits
- Antic Vol. 7 No. 10 (Feb 1989) — Error Trapping in Atari BASIC (Heidi Brumbaugh) — AtariMagazines.com (Kevin Savetz), 1989
- Best of Antic Vol. 1 — Oh, Those Bugs (David Plotkin) — AtariMagazines.com (Kevin Savetz)
- Mapping the Atari (Ian Chadwick) — locations 186-187 STOPLN, 195 ERRSAVE — AtariArchives.org
- Atari BASIC Faster and Better (Carl M. Evans, IJG 1983) — Appendix C: Error Codes Explained — Atari8bit.net, 1983
- cc65 atari.inc — CIO/DOS status code equates — GitHub project authors
- Turbo-BASIC XL Expanded Documentation (Ron Fetzer) — ERR, ERL, *B — Turbo-BASIC XL Expanded Documentation (Ron Fetzer); AtariAge forum members
