Working with Disk Files in Atari BASIC

Saving and loading programs is one thing. Most useful software also needs to store data: high scores, address books, game levels, configuration. Atari BASIC handles this with a handful of statements that talk to DOS's D: handler through CIO. This guide covers them all, with working examples, from writing your first file to updating records in place with NOTE and POINT.

You need: Atari BASIC and a booted DOS: Atari DOS 2.0S or 2.5, MyDOS, SpartaDOS and most others all support these commands. Use a scratch disk or a blank ATR image in an emulator. In Altirra you can create one from File › New disk, or format a blank disk image from the DOS menu.

1. The core statements

Statement Purpose
OPEN #n,mode,0,"D:NAME.EXT" Open a file on channel n (1–5 recommended)
PRINT #n;... Write text/numbers as a record ending in RETURN ($9B)
INPUT #n,var Read a record into a string or number
PUT #n,byte / GET #n,var Write/read a single byte
NOTE #n,sec,byte / POINT #n,sec,byte Read/set the file position
STATUS #n,var Get the status of a channel
XIO cmd,#n,a1,a2,"D:..." Any other CIO/DOS command
CLOSE #n Finish with the file. Essential when writing

The mode numbers, as tabulated in The Creative Atari and De Re Atari:

Mode Meaning
4 Read only
8 Write only. Erases any existing file of that name
9 Append: write at the end of an existing file
12 Update: read and write, starting at the beginning
6 Read the disk directory

Avoid channels #0, #6 and #7. BASIC uses them for the screen editor, the GRAPHICS screen and LPRINT/LOAD/SAVE (see CIO and IOCBs).

2. Your first data file

10 OPEN #1,8,0,"D:TEST.DAT"
20 PRINT #1;"THIS IS A STRING"
30 PRINT #1;12345.6
40 PRINT #1;"THIS IS ANOTHER STRING"
50 CLOSE #1
60 DIM S$(40)
70 OPEN #1,4,0,"D:TEST.DAT"
80 INPUT #1,S$:PRINT S$
90 INPUT #1,N:PRINT N*2
100 INPUT #1,S$:PRINT S$
110 CLOSE #1

Points that catch everyone out, all explained by Dave Johnson and Embee Humphrey in The Creative Atari:

  • PRINT # writes characters, exactly as they would appear on screen. 12345.6 is stored as the seven characters "12345.6", not as a binary number, so the number 10 takes two bytes and 123 takes three. Reading it back with INPUT #1,N converts it again.
  • One item per PRINT #. If you write PRINT #1;"NAME";42, the file holds the single record NAME42, and BASIC has no way to split it later. Write separate records, or put a comma between items (PRINT #1;A;",";B) and read them with INPUT #1,A,B.
  • Always CLOSE after writing. Data sits in DOS's buffer until the sector is full or the file is closed. Forget the CLOSE and your last records never reach the disk.

3. Reading to the end: TRAP and ERROR 136

You often do not know how many records a file holds. Reading past the end raises ERROR 136 (end of file). The idiom is to TRAP it:

10 DIM S$(40)
20 OPEN #1,4,0,"D:TEST.DAT"
30 TRAP 70
40 INPUT #1,S$
50 PRINT S$
60 GOTO 40
70 CLOSE #1
80 TRAP 40000

TRAP 40000 (any line number above 32767) switches trapping off again, the convention Jerry White uses in his diskfile tutorial. Inside a TRAP routine, PEEK(195) gives the error number and PEEK(186)+256*PEEK(187) the line where it happened. White's tutorial uses exactly this pair to tell a harmless end of file (136) from a real error:

9100 IF PEEK(195)=136 THEN GOTO LINE
9120 PRINT "ERROR ";PEEK(195);" AT LINE ";PEEK(186)+PEEK(187)*256

Disk errors worth recognising (codes from cc65's atari.inc; BASIC prints the same numbers):

Error Meaning Usual cause
136 End of file Normal end of a read loop
138 Device timeout Drive off, wrong drive number
139 Device NAK Bad command or disk problem
144 Device done error Write-protected disk, or bad sector
162 Disk full
165 Bad file name Name over 8+3 characters, or lowercase/illegal characters
167 File locked Unlock it first
169 Directory full DOS 2 allows 64 files per disk
170 File not found Typo, or wrong drive

4. Adding to a file: APPEND

Mode 8 starts the file again from nothing. To add records, open with 9:

10 OPEN #1,9,0,"D:TEST.DAT"
20 PRINT #1;"THIS IS ADDED"
30 CLOSE #1

5. Byte-level files: GET # and PUT

For binary data, such as a character set, level maps or a saved high-score table, use PUT # and GET #. They move one byte (0–255) at a time, and no RETURN characters are added:

10 REM SAVE N BYTES STARTING AT ADDRESS A
20 A=1536:N=256
30 OPEN #1,8,0,"D:PAGE6.BIN"
40 FOR I=0 TO N-1:PUT #1,PEEK(A+I):NEXT I
50 CLOSE #1
60 OPEN #1,4,0,"D:PAGE6.BIN"
70 FOR I=0 TO N-1:GET #1,B:POKE A+I,B:NEXT I
80 CLOSE #1

This works, but slowly: one CIO call per byte. For kilobytes of data, use the GET CHARACTERS block call shown in CIO and IOCBs. It loads a whole screen in one go.

6. Random access with NOTE and POINT

Sequential files must be read from the start. DOS can also jump straight to any byte. NOTE reports where the next read or write will happen, and POINT moves there. The position has two parts: a sector number and a byte offset within that sector. A DOS 2 sector holds 125 data bytes (0–124). The last three bytes hold the file number, the link to the next sector and the byte count.

The recipe is the one from The Creative Atari and Jerry White's tutorial:

  1. Use fixed-length records, so a rewritten record never overruns its neighbour. Pad strings with spaces, and format numbers as strings of fixed width.
  2. As you write each record, NOTE its position and store the sector and byte in arrays.
  3. Later, POINT to the stored position and INPUT or PRINT the record.
10 DIM R$(10),T$(3),SEC(20),BYT(20)
20 OPEN #1,8,0,"D:RECS.DAT"
30 FOR N=1 TO 20
40 R$="RECORD":R$(7)="    ":T$=STR$(N):R$(11-LEN(T$))=T$
50 NOTE #1,S,B:SEC(N)=S:BYT(N)=B
60 PRINT #1;R$
70 NEXT N
80 CLOSE #1
100 REM UPDATE RECORD 7 IN PLACE
110 OPEN #1,12,0,"D:RECS.DAT"
120 POINT #1,SEC(7),BYT(7)
130 PRINT #1;"CHANGED!  "
140 POINT #1,SEC(7),BYT(7)
150 INPUT #1,R$:PRINT R$
160 CLOSE #1

The index arrays only exist while the program runs. A real application saves them to a second small file, or rebuilds them by reading the data file once with NOTE before each INPUT, as White's update routine does. DOS checks that a POINTed sector actually belongs to the open file, and refuses if it does not. A stale index therefore gives an error rather than silent corruption.

Note that NOTE and POINT values are DOS-specific. They are physical sector numbers in DOS 2.x and MyDOS. SpartaDOS-family DOSes use different file structures, so index files are not portable between DOSes.

7. Reading the directory

Mode 6 opens the directory as a file of text records, one per file plus a free-sectors line:

10 DIM D$(20)
20 OPEN #1,6,0,"D:*.*"
30 TRAP 70
40 INPUT #1,D$
50 PRINT D$
60 GOTO 40
70 CLOSE #1:TRAP 40000

Wildcards work as in the DOS menu: D:*.BAS, D2:PRO*.*, D:TEST??. Under DOS 2.5, OPEN #1,7,0,"D:*.*" also lists files in the extended (enhanced-density) area that DOS 2.0 cannot see, showing them in angle brackets.

8. File management with XIO

Everything on the DOS menu that manipulates files is also available from BASIC through XIO. The command numbers are from De Re Atari:

XIO 32,#1,0,0,"D:OLDNAME.DAT,NEWNAME.DAT":REM RENAME
XIO 33,#1,0,0,"D:JUNK.DAT":REM DELETE
XIO 35,#1,0,0,"D:KEEP.DAT":REM LOCK
XIO 36,#1,0,0,"D:KEEP.DAT":REM UNLOCK

The channel must not be open when you use these. Formatting is XIO 254 (XIO 254,#1,0,0,"D1:"). DOS 2.5 adds XIO 253 to force single density. Be very careful with both: they erase the whole disk.

9. Housekeeping tips

  • Too many files at once? DOS 2.0S reserves buffers for only three simultaneously open files by default. Location 1801 holds this limit (up to 7) and location 1802 holds the drive bitmap. Change them and rewrite DOS with menu option H. Each buffer costs 128 bytes.
  • Faster writes: POKE 1913,80 makes DOS 2.0S write without verifying (POKE 1913,87 restores verify). That address is specific to DOS 2.0S.
  • Program files vs data files: SAVE/LOAD use tokenised BASIC, while LIST "D:X.LST" and ENTER use plain text records. Because LISTed files are just records, your own programs can read and write them with INPUT # and PRINT #.

Troubleshooting

  • ERROR 129 on OPEN: the channel is already open, perhaps from an earlier run that stopped. Put CLOSE #1 before every OPEN.
  • Last records missing: the file was never CLOSEd (BREAK or an error before the CLOSE). Close files in your TRAP handler.
  • String too short on INPUT #: a record longer than the DIMmed string is cut off. DIM generously.
  • ERROR 165 with an apparently correct name: DOS 2 names are up to eight letters or digits starting with a letter, plus an optional three-character extension. No spaces, lowercase or punctuation.

Further reading

  • The Creative Atari (Creative Computing Press): "Using Disks With Atari Basic" and Jerry White's three-part "Atari Diskfile Tutorial".
  • De Re Atari (Atari, Inc., 1982), Chapter 9: FMS internals, the sector format and NOTE/POINT.
  • Inside Atari DOS by Bill Wilkinson (Small System Services, 1982): the complete FMS source explained.
  • On this site: CIO and IOCBs, Error trapping.

Credits