Saving, Loading and Merging Atari BASIC Programs
Atari BASIC gives you two completely different ways to store a program, and mixing them up is one of the commonest beginner frustrations ("ERROR 21", "ERROR 14"). Once you understand the difference between a tokenized file and a listed file, you also gain some genuinely useful tricks: merging libraries of subroutines, cleaning out junk variables, and chaining programs together.
You will learn: the SAVE/LOAD and LIST/ENTER pairs, cassette commands, file names and devices, merging, chaining, auto-running BASIC programs at boot, reading a disk directory from BASIC, and how to cope with revision B's growth bug.
You need: Atari BASIC plus a disk drive (real, emulated, or an SIO2PC/FujiNet device) or a program recorder. For disk work you need DOS booted — on a real machine, power on with a DOS disk in drive 1.
1. Two formats
When you type a line, BASIC converts it to compact tokens — keywords become single bytes, numbers become six-byte constants, variables become references into a table. The commands fall into two families:
| Save with | Load with | Format | Notes |
|---|---|---|---|
SAVE "D:NAME" |
LOAD "D:NAME" or RUN "D:NAME" |
tokenized | compact and fast; includes the variable tables |
LIST "D:NAME" |
ENTER "D:NAME" |
plain ATASCII text | readable by editors; merges into memory |
CSAVE |
CLOAD |
tokenized, cassette only | fastest tape format |
Cross the pairs and you get errors: LOADing a listed file gives ERROR 21 (load file error), and ENTERing a SAVEd file typically gives ERROR 14 (line too long), because the tokenized bytes are being read as if they were typed text.
A file name can be a string variable as well as a literal — DIM F$(20):F$="D:TESTNAME":SAVE F$ works.
2. SAVE and LOAD in detail
SAVE writes, in order, a short header of BASIC's internal pointers (adjusted so they are relative to the start of the program area), then the variable name table, the variable value table, the tokenized program and the immediate-mode line. On LOAD, BASIC adds the current bottom-of-memory address (MEMLO) back on, which is why a SAVEd program loads correctly even if you boot a different DOS that occupies more or less memory.
SAVE "D:GAME.BAS"
LOAD "D:GAME.BAS"
RUN "D:GAME.BAS"
RUN "D:..." loads and immediately runs — and it works inside a program, which is how you chain programs: a title or set-up program can end with RUN "D:MAIN.BAS", freeing memory for the main code. It's a classic way to get one-time initialisation code out of the way.
Because the variable value table is saved too, a SAVEd program remembers every variable name you ever typed, even ones you have since deleted.
3. LIST and ENTER: text that merges
LIST "D:NAME" writes the program out exactly as it would appear on screen; you can list a range with LIST "D:PART.LST",1000,1999. LIST "P:" sends a listing to the printer.
The key property of ENTER is that it does not erase the program already in memory. It behaves as if you typed each line in: new line numbers are added and existing ones replaced. That makes it perfect for keeping a library of subroutines:
LIST "D:TITLE.LST",1,99
saves lines 1–99 of one program; later, with another program in memory,
ENTER "D:TITLE.LST"
slots them in. Robert Peck's Atari BASIC Tutorial uses this for a standard title block; Carl Evans's Atari BASIC Faster and Better numbers all of its subroutines from 20000 upwards for the same reason. Plan line ranges so that libraries do not collide with your program's lines.
Cleaning out dead variables
Atari BASIC never removes names from its variable table, and there is a limit of 128 names. De Re Atari's cure:
LIST "D:TEMP.LST"
NEW
ENTER "D:TEMP.LST"
ENTER re-tokenizes everything from scratch, so only the variables actually used survive. SAVE the result afterwards if you want the faster-loading format.
4. Cassette
For a program recorder the routine is always the same: position the tape, type the command, wait for the buzzer, press the recorder's buttons, then press RETURN.
| To save | Recorder buttons | To load |
|---|---|---|
CSAVE (short gaps, fastest) |
PLAY + RECORD | CLOAD |
SAVE "C:" (long gaps) |
PLAY + RECORD | LOAD "C:" or RUN "C:" |
LIST "C:" (slowest; tape stops between blocks) |
PLAY + RECORD | ENTER "C:" |
The computer beeps twice before a save (press PLAY and RECORD) and once before a load (press PLAY). Load each format with its matching command.
One historical gotcha: an Atari technical tip from 1982 warns that on the 400/800, pressing RESET does not reset POKEY's serial data line, which can make the next CSAVE unreadable. Either avoid RESET before a CSAVE or first execute a serial-bus command such as LPRINT (an ERROR 138 with no printer attached is harmless and still resets the line).
5. File names and devices
Most Atari DOSes accept a name of one to eight characters plus an optional extension of up to three, built from capital letters and digits, usually starting with a letter. Prefix the device: D: (drive 1), D2: to D8: for other drives, C: for cassette, P: for the printer. Conventional extensions are .BAS for SAVEd programs and .LST for LISTed ones — following them saves a lot of guessing later.
6. Running a BASIC program at boot
DOS automatically loads and runs a machine-language file called AUTORUN.SYS when it boots, but a BASIC program cannot simply be renamed to that. The classic answer is a small AUTORUN.SYS whose only job is to type RUN "D:YOURPROG" into BASIC for you. Carl Evans's AUTOGO program (in Atari BASIC Faster and Better) generates one; many other utilities did the same. Turbo-BASIC XL takes a simpler approach: it automatically runs a program called AUTORUN.BAS if it finds one on the boot disk.
7. Reading a directory from BASIC
You do not have to drop to DOS to see what is on a disk. Opening a file spec with auxiliary value 6 returns the directory as lines of text. A routine along these lines does the job:
5 DIM R$(20)
10 OPEN #4,6,0,"D:*.*"
20 TRAP 60:INPUT #4,R$
30 PRINT R$
40 GOTO 20
60 CLOSE #4
The last line returned is the free-sector count, after which the INPUT reaches end of file (error 136) and the TRAP closes the channel.
8. The revision B growth bug
Revision B of Atari BASIC, built into many 600XL and 800XL computers, has a serious bug. As Bill Wilkinson explained in COMPUTE! in June 1985, every LOAD (or CLOAD, or RUN "filename") adds 16 bytes to the program, and saving and reloading compounds it. The remedy is to save with LIST and reload with ENTER — at least now and then — or to use a revision C cartridge, which Atari offered to 600XL/800XL owners from June 1984. Check your revision with PRINT PEEK(43234): 162 is A, 96 is B, 234 is C. Antic published a type-in "Revision C Converter" fix in September 1985.
Troubleshooting
- ERROR 21 on LOAD: the file was LISTed (use ENTER) or is a machine-language file (load it from DOS).
- ERROR 14 on ENTER: the file was SAVEd (use LOAD).
- ERROR 170: file not found — check the drive number and spelling, and remember the
D:. - ERROR 144 on SAVE: the disk is write-protected (or the disk image is mounted read-only).
- ERROR 19 on LOAD: not enough memory — perhaps a bigger DOS is resident than when the program was saved.
- Program grows every save: revision B; see section 8.
- Cassette load fails: try the other loading command — the format must match the save command.
Further reading
- Atari BASIC Tutorial — Robert A. Peck (Howard W. Sams, 1983), Chapter 4.
- Disk Guide Atari 400 and 800 — David A. Wilson (McGraw-Hill, 1983).
- Inside Atari DOS — Bill Wilkinson (Small System Services, 1982).
Credits
- De Re Atari, Chapter 10 — Atari BASIC (SAVE/LOAD internals, LIST/ENTER cleanup) — Lane Winner (Section 10 of De Re Atari)
- comp.sys.atari.8bit FAQ — 7.2.1 (BASIC revisions) and 7.2.2 (cassette load/save); 7.3.5 (filenames) — Michael Current (comp.sys.atari.8bit FAQ)
- Atari BASIC Tutorial (Robert A. Peck, Howard W. Sams 1983) — Program Save and Load — Atari8bit.net, 1983
- Atari BASIC Faster and Better (Carl M. Evans) — AUTOGO; Appendix C error codes — Atari8bit.net
- Mapping the Atari — Appendix Eleven directory routine — AtariArchives.org
