A Disk File Menu in Atari BASIC: Reading and Parsing the Directory
Many programs need a "load which file?" screen: a game choosing a saved position, a paint program choosing a picture, a utility choosing a document. Atari BASIC can read the disk directory as if it were a text file, but what comes back is a screen-formatted listing, not a list of file names. This guide shows how to read that listing cleanly, take each line apart, and turn the user's choice into a name you can OPEN. It ends with a CIO technique for loading a whole file when you don't know its length.
What you need: Atari BASIC and a DOS 2-family disk (DOS 2.0S, DOS 2.5, or a compatible DOS). The programs were run in atari800 (XL mode, AltirraOS, Atari BASIC revision C) on DOS 2.0S and DOS 2.5 disks, including one with only 9 free sectors. For the basics of OPEN, INPUT # and TRAP, see Working with Disk Files in Atari BASIC.
1. What the directory looks like to BASIC
OPEN #1,6,0,"D:*.*" opens the directory for reading. The wildcards work as they do in the DOS menu. Each INPUT #1 then returns one line, exactly as DOS would print it:
* DOS SYS 037
DOSMAN 009
262 FREE SECTORS
Every file line has the same columns:
| Columns | Contents |
|---|---|
| 1 | * if the file is locked, otherwise a space |
| 2 | space |
| 3–10 | name, padded with spaces |
| 11–13 | extension, padded with spaces (may be empty) |
| 14 | space |
| 15–17 | size in sectors, three digits |
The listing ends with a line that starts with the free-sector count, and then the file reports end of file. Reading once more gives ERROR 136.
2. Finding the end without TRAP
The usual idiom is to keep reading and TRAP the ERROR 136. That works, but it means jumping out of a loop through an error. There's a cleaner test: a file line always starts with * or a space, and the last line always starts with a digit. DOS 2 prints the free count as three digits with leading zeros, so even a nearly full disk gives a digit first. On our test disk with 9 sectors left, the program read the count correctly. So:
30 INPUT #1,L$
40 C$=L$(1,1):IF C$>="0" AND C$<="9" THEN 70
As a bonus, VAL(L$(1,3)) on that last line gives the free space.
A word of caution: this rule is for DOS 2-style listings. Other DOSes format their directories differently and may print other lines at the end. If your program must work under any DOS, keep the TRAP as a safety net as well.
3. The menu program
This complete program reads up to 64 entries into one long string, 17 characters per entry (Atari BASIC has no string arrays), shows a numbered menu, rebuilds the chosen file's name and shows its first bytes:
10 DIM L$(20),F$(17*64),N$(16),C$(1)
20 N=0:OPEN #1,6,0,"D:*.*"
30 INPUT #1,L$
40 C$=L$(1,1):IF C$>="0" AND C$<="9" THEN 70
50 N=N+1:F$(N*17-16,N*17)=L$(1,17)
60 GOTO 30
70 CLOSE #1:FREE=VAL(L$(1,3))
80 FOR I=1 TO N:? I;". ";F$(I*17-16,I*17):NEXT I
90 ? N;" FILES, ";FREE;" SECTORS FREE"
100 ? "WHICH FILE";:INPUT K:IF K<1 OR K>N THEN 100
110 GOSUB 500:? "NAME IS ";N$
120 OPEN #1,4,0,N$:TRAP 140:? "STARTS: ";
130 FOR I=1 TO 24:GET #1,B:B=B-128*(B>127):? CHR$(46+(B-46)*(B>31 AND B<123));:NEXT I
140 CLOSE #1:TRAP 40000:?:END
500 REM BUILD D:NAME.EXT FROM ENTRY K
510 P=K*17-16:N$="D:"
520 FOR J=P+2 TO P+9:IF F$(J,J)<>" " THEN N$(LEN(N$)+1)=F$(J,J)
530 NEXT J
540 IF F$(P+10,P+10)=" " THEN RETURN
550 N$(LEN(N$)+1)="."
560 FOR J=P+10 TO P+12:IF F$(J,J)<>" " THEN N$(LEN(N$)+1)=F$(J,J)
570 NEXT J:RETURN
How it works:
- Lines 20–70 read the listing with the digit test from section 2.
F$is dimensioned for 64 entries, the most a DOS 2 directory can hold. - Lines 80–100 print the menu and ask for a number. To show only some files, change the wildcard in line 20, for example
"D:*.PIC". - Lines 500–570 rebuild the name. They copy the non-space characters of the name field, then add a period and the extension only if there is one. On the DOS 2.5 master disk, choice 7 became
D:DOS25.DOCand choice 8 becameD:DOSMAN, with no stray period. - Lines 120–140 read the first 24 bytes with
GET, showing anything unprintable as a period. The program usesGETrather thanINPUT, becauseINPUTwaits for an end-of-line character. On a binary file such asDOSMAN, the first version of this program, which usedINPUT, stopped with ERROR 136 because the file has no RETURN character before it ends. Here theTRAPis used for what it's for: a file shorter than 24 bytes. A 6-byte test file printedHELLO.and stopped cleanly.
Columns 15–17 give you each file's size, and column 1 its lock state. Use them to warn before overwriting a locked file, or to refuse files too big for your buffer. A multiple of 125 bytes per sector is a good estimate for DOS 2 single density.
4. Loading a whole file of unknown length with CIO
For machine code, pictures or data you want in memory in one go, BASIC's GET is slow. CIO's GET CHARACTERS command (7) reads a block straight into memory. The question that always comes up is how to read a file whose length you don't know. The answer is to ask for the largest amount you can accept. If the file ends first, CIO stops, returns status 136 and changes the IOCB's length field to the number of bytes actually read.
This BASIC test calls CIO directly for IOCB 1 ($350). It uses a three-instruction machine-code routine stored in M$ (PLA, LDX #$10, JMP $E456) and asks for 1,000 bytes each time:
10 DIM B$(1000),M$(7)
20 FOR I=1 TO 7:READ A:M$(I,I)=CHR$(A):NEXT I
30 DATA 104,162,16,76,86,228,0
40 OPEN #1,4,0,"D:DUP.SYS"
50 A=ADR(B$):POKE 852,A-256*INT(A/256):POKE 853,INT(A/256)
60 POKE 856,232:POKE 857,3:POKE 850,7
70 X=USR(ADR(M$)):? "STATUS ";PEEK(851);" BYTES ";PEEK(856)+256*PEEK(857)
80 POKE 852,A-256*INT(A/256):POKE 853,INT(A/256):POKE 856,232:POKE 857,3:POKE 850,7
90 X=USR(ADR(M$)):? "STATUS ";PEEK(851);" BYTES ";PEEK(856)+256*PEEK(857)
100 CLOSE #1
110 OPEN #1,4,0,"D:SHORT.TXT"
120 POKE 852,A-256*INT(A/256):POKE 853,INT(A/256):POKE 856,232:POKE 857,3:POKE 850,7
130 X=USR(ADR(M$)):? "STATUS ";PEEK(851);" BYTES ";PEEK(856)+256*PEEK(857)
140 CLOSE #1
It printed:
STATUS 1 BYTES 1000
STATUS 1 BYTES 1000
STATUS 136 BYTES 6
The two reads from the 42-sector DUP.SYS filled the buffer and returned status 1. The read from a 6-byte file returned 136, with the length field (852–853 is the address, 856–857 the length, 850 the command, 851 the status) reduced to 6. In assembly the pattern is the same: set ICBLL/ICBLH to your buffer size, call CIOV, and on return read ICBLL/ICBLH for the real size. Treat Y = $88 (136) as "end of file reached", not as a failure. Set the length again before each call, as lines 80 and 120 do, because CIO changes it.
Troubleshooting
- The menu shows a "file" called FREE SECTORS: your end test isn't working. Check that you're testing column 1, and that the DOS prints a DOS 2-style listing.
- ERROR 165 when opening the chosen file: the rebuilt name has stray spaces or a trailing period. Print
N$between quotes to check it. - ERROR 136 reading a file with
INPUT: the file has no RETURN characters. UseGETor a block read. - Garbage after a block read: you used the requested length, not the returned one. Read 856–857 (or ICBLL/ICBLH) after the call.
Further reading
- De Re Atari, chapter 8, and Mapping the Atari, locations 832–959 (the IOCBs), for the CIO block commands.
- On this site: Working with Disk Files in Atari BASIC, CIO and IOCBs: How Atari Input/Output Really Works, DOS 2 File Names, Wildcards and the Boot Record, Calling Machine Language from Atari BASIC with USR.
Credits
- Picture: The menu program on the DOS 2.5 master disk: pick a number and it rebuilds the file name and opens the file. — Program authors; screenshot by the site
- AtariAge — 'How to perform a DIRECTORY read in Basic without using TRAP' (January 2025): end-of-listing detection ideas, DOS 2.5 '<' entries, AUX1=7 — AtariAge forum members, 2025
- AtariAge — 'How do I use CIO to load a file of an unknown size?' (September 2025): GET CHARACTERS with maximum length, $88 status and updated length — AtariAge forum members, 2025
- Mapping the Atari — IOCB locations 832–959 — AtariArchives.org
