A Disk File Menu in Atari BASIC: Reading and Parsing the Directory

Atari BASIC screen listing eight numbered DOS 2.5 files with lock asterisks and sector counts, 262 sectors free, the answer 7, NAME IS D:DOS25.DOC and the start of the file

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.DOC and choice 8 became D:DOSMAN, with no stray period.
  • Lines 120–140 read the first 24 bytes with GET, showing anything unprintable as a period. The program uses GET rather than INPUT, because INPUT waits for an end-of-line character. On a binary file such as DOSMAN, the first version of this program, which used INPUT, stopped with ERROR 136 because the file has no RETURN character before it ends. Here the TRAP is used for what it's for: a file shorter than 24 bytes. A 6-byte test file printed HELLO. 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. Use GET or 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