DOS 2 File Names, Wildcards and the Boot Record: How FMS Reads a Name and Finds a File
Type OPEN #1,8,0,"D:MY-FILE.DAT" under DOS 2.0S and you get a file called MY, with no extension. Type "D:9LIVES" and you get ERROR 165. Rename DOS.SYS and the disk stops booting. None of this is a bug: each result follows from a few short routines in DOS 2's File Management System, which Inside Atari DOS (COMPUTE! Books, 1982) documents in its chapters on file-name decoding, directory searching and the boot record.
This guide walks through those three areas and checks each one with a BASIC test. It is the fourth guide in a set. Inside DOS 2 in Memory covers the layers, buffers and burst I/O. Inside a DOS 2 Disk covers the VTOC, directory and sector links. DOS 2 File Operations from the Inside covers OPEN, CLOSE, APPEND, RENAME and POINT.
What you need: Atari BASIC and a DOS 2.0S disk. The tests were run in the atari800 emulator (XL mode with its built-in AltirraOS) with Atari BASIC revision C, on a DOS 2.0S disk. The name tests were then repeated on DOS 2.5, which behaves differently in two places. Routine names and addresses are DOS 2.0S's, from the book. Use a scratch disk: the third test deletes and rewrites DOS.SYS.
1. From your string to an 11-character name
Every FMS command that takes a file name starts by passing it to FNDCODE ($E9E). This routine turns whatever you typed into an 11-byte field called FNAME: 8 characters of name and 3 of extension, padded with spaces. It works like this:
- Skip to the first colon. If there isn't one within 256 characters, the result is a file-name error.
- Fill FNAME with spaces and start on the name part.
- Take characters one by one:
- A letter or digit is stored. Once a part is full (8 for the name, 3 for the extension), further characters are dropped without any error.
- A
?is stored as it is. - An*fills the rest of the current part with?. - The first.switches to the extension. A second.ends the name. - Anything else (a space, a hyphen, a lower-case letter, the closing quote, the end of the string) ends the name.
The book gives examples of the result. D:*.* becomes eleven question marks. D:GL?P.S* becomes GL?P····S?? (· is a space), and D1:G* becomes G??????? followed by three spaces.
The first test program opens eight names for output and then lists the directory:
10 DIM N$(20),L$(20)
20 FOR I=1 TO 8:READ N$
30 TRAP 60:OPEN #1,8,0,N$:PRINT #1;"X":CLOSE #1
40 ? N$;" OK"
50 GOTO 70
60 ? N$;" ERR ";PEEK(195):CLOSE #1
70 NEXT I
80 GOSUB 500:END
100 DATA D:MY-FILE.DAT,D:LONGFILENAME.TEXT,D:A.B.C,D:9LIVES
110 DATA D:lower.dat,D:WILD?.DAT,D:G*X.BAS,D:SP ACE.DAT
500 TRAP 540:OPEN #2,6,0,"D:*.*"
510 INPUT #2,L$:? L$
520 GOTO 510
540 CLOSE #2:RETURN
(Type lower.dat with the CAPS key switched to lower case.) The results under DOS 2.0S, as the raw directory entries show them:
| You typed | File created | Why |
|---|---|---|
D:MY-FILE.DAT |
MY |
The hyphen ends the name before the period is reached |
D:LONGFILENAME.TEXT |
LONGFILE.TEX |
Extra characters in each part are dropped silently |
D:A.B.C |
A.B |
The second period ends the name |
D:9LIVES |
ERROR 165 | See below |
D:lower.dat |
ERROR 165 | A lower-case letter ends the name at once, so the name is empty |
D:WILD?.DAT |
WILD.DAT |
Wildcards become spaces when a file is created |
D:G*X.BAS |
G.BAS |
* fills the name with ?, so the X is dropped; the ?s then become spaces |
D:SP ACE.DAT |
SP |
The space ends the name |
Two results need a comment. In the book's step-by-step description, FNDCODE accepts any letter or digit, but in our test DOS 2.0S still refused a name that starts with a digit. So treat "first character must be a letter" as the DOS 2.0S rule. And when a name containing wildcards is used to create a file, the ? characters in FNAME end up as spaces in the directory entry. No error is raised, so a typo with ? or * in an output name quietly gives you a different, shorter file name.
DOS 2.5 is friendlier. Repeating the test on DOS 2.5 created 9LIVES without complaint and turned lower.dat into LOWER.DAT. Everything else came out the same as on 2.0S.
2. Searching the directory
A DOS 2 directory is sectors 361–368: 8 sectors of 8 entries, so 64 files at most. The search routine has two entry points. SFDIR ($F21) starts at the first entry, and CSFDIR ($F31) carries on from the entry after the last match. That second entry point is how DELETE, LOCK and RENAME work through every file that matches a wildcard. The search keeps a few variables: the current sector (0–7), the offset within it, the file number (0–63), and the position of the first hole, meaning the first free entry it passed.
For each entry it applies four rules:
- A flag byte of zero marks the end of the used part of the directory. The search stops there and reports "not found".
- Entries open for output are skipped, so a file that is still being written can't be found by another OPEN.
- A deleted entry is remembered as the hole, if no hole has been found yet.
- Otherwise the 11 characters are compared, and a
?in FNAME matches any character.
When a new file is created, it goes into the first hole. The second test shows the results:
10 DIM N$(20),L$(20)
20 FOR I=1 TO 4:N$="D:F":N$(4)=STR$(I):N$(LEN(N$)+1)=".DAT"
30 OPEN #1,8,0,N$:PRINT #1;"FILE ";I:CLOSE #1:NEXT I
40 XIO 33,#1,0,0,"D:F2.DAT"
50 OPEN #1,8,0,"D:NEW.DAT":PRINT #1;"NEW":CLOSE #1
60 ? "AFTER DELETE F2, CREATE NEW:":GOSUB 500
70 OPEN #1,4,0,"D:F*.DAT":INPUT #1,L$:CLOSE #1
80 ? "OPEN D:F*.DAT READS: ";L$
90 XIO 32,#1,0,0,"D:F?.DAT,Z?.TXT"
100 ? "AFTER RENAME F?.DAT,Z?.TXT:":GOSUB 500
110 TRAP 140:FOR I=1 TO 70:N$="D:M":N$(4)=STR$(I)
120 OPEN #1,8,0,N$:CLOSE #1:NEXT I
130 GOTO 150
140 ? "FILE M";I;": ERROR ";PEEK(195):CLOSE #1
150 END
500 TRAP 540:OPEN #2,6,0,"D:*.*"
510 INPUT #2,L$:? L$
520 GOTO 510
540 CLOSE #2:RETURN
On DOS 2.0S it printed:
AFTER DELETE F2, CREATE NEW:
DOS SYS 039
DUP SYS 042
F1 DAT 001
NEW DAT 001
F3 DAT 001
F4 DAT 001
622 FREE SECTORS
OPEN D:F*.DAT READS: FILE 1
AFTER RENAME F?.DAT,Z?.TXT:
DOS SYS 039
DUP SYS 042
Z1 TXT 001
NEW DAT 001
Z3 TXT 001
Z4 TXT 001
622 FREE SECTORS
FILE M59: ERROR 169
What it shows:
- NEW.DAT took F2's place in the directory listing, because F2's deleted entry was the first hole. It also got F2's old data sector, since the sector allocator always takes the lowest free sector. The directory isn't kept in creation order, and that is why.
- A wildcard OPEN for reading opens the first match.
D:F*.DATopened F1.DAT. If you need a particular file, don't rely on a wildcard. - A wildcard RENAME renames every match, and a
?in the new name keeps the character from the old name: F1.DAT became Z1.TXT. Be careful: DOS 2 doesn't check whether the new name already exists (see DOS 2 File Operations from the Inside). - The 64th entry is the last. DOS.SYS, DUP.SYS, four test files and M1–M58 make 64, so creating M59 failed with ERROR 169 (directory full), even though the disk still had more than 500 free sectors.
3. DOS.SYS and the boot record
Sectors 1–3 of a DOS 2 disk hold the boot record and the start of FMS. FMS keeps a copy of this area in memory at $700–$87F. The two fields that matter here are DFSFLG at $70E, which is non-zero when a DOS.SYS file exists, and DFLINK at $70F–$710, the number of DOS.SYS's first sector. At power-up the OS loads the boot sectors and calls XBCONT ($714). If DFSFLG is zero it reports a failed boot. Otherwise it follows DOS.SYS's sector chain from DFLINK into memory.
FMS treats the name DOS.SYS specially:
- Opening
DOS.SYSfor output runs WRTDOS ($120A). This puts the new file's first sector into DFLINK and writes sectors 1–3 from $700–$87F. Then WD0 ($1267) copies the whole FMS from memory into the file in 125-byte pieces. So any program can write DOS to a disk just by opening DOS.SYS for output. - Deleting DOS.SYS, or renaming it to another name, runs DELDOS ($1219). This sets DFSFLG to zero and rewrites sectors 1–3.
- Renaming any file to DOS.SYS points the boot record at that file.
The third test watches the in-memory copy of the flag and link while it does each of these:
10 DIM L$(20)
20 ? "AT START: ";:GOSUB 400
30 XIO 32,#1,0,0,"D:DOS.SYS,DOSX.SYS"
40 ? "RENAMED AWAY: ";:GOSUB 400
50 XIO 32,#1,0,0,"D:DOSX.SYS,DOS.SYS"
60 ? "RENAMED BACK: ";:GOSUB 400
70 XIO 33,#1,0,0,"D:DOS.SYS"
80 ? "DELETED: ";:GOSUB 400
90 OPEN #1,8,0,"D:DOS.SYS":CLOSE #1
100 ? "OPEN+CLOSE: ";:GOSUB 400
110 GOSUB 500:END
400 ? "FLAG ";PEEK(1806);" LINK ";PEEK(1807)+256*PEEK(1808):RETURN
500 TRAP 540:OPEN #2,6,0,"D:*.*"
510 INPUT #2,L$:? L$
520 GOTO 510
540 CLOSE #2:RETURN
AT START: FLAG 1 LINK 4
RENAMED AWAY: FLAG 0 LINK 4
RENAMED BACK: FLAG 1 LINK 4
DELETED: FLAG 0 LINK 4
OPEN+CLOSE: FLAG 1 LINK 4
DOS SYS 039
DUP SYS 042
After the OPEN and CLOSE, DOS.SYS was back: 39 sectors, starting at sector 4 again, because the freed sectors were the lowest free ones. The disk booted normally to the DUP menu. Its sectors 1–3 were byte-for-byte the same as before the test. Four sectors inside the new DOS.SYS were different, though. WD0 copies FMS as it is in memory at that moment, so the file captured some of the working variables and buffer contents of the running FMS. That does no harm, because FMS sets them up again when it starts.
In a separate test the disk was left with DOS.SYS renamed to DOSX.SYS. The file was still on the disk, but DFSFLG was zero, so the disk no longer booted and the emulated computer just kept retrying. Renaming it back to DOS.SYS fixes that.
On DOS 2.5 the same test stopped at line 30 with ERROR 167 (file locked), because the DOS 2.5 master disk ships with DOS.SYS and DUP.SYS locked. That lock is the only protection there is: unlock DOS.SYS on either version and a rename or delete will make the disk unbootable.
4. Practical rules
- Keep names to A–Z and 0–9, start them with a letter, and use at most 8+3 characters. Anything else is cut off silently, and you won't be told.
- Never put
?or*in an output name. You won't get an error, just a different name. - Wildcards are fine for DELETE, LOCK, UNLOCK and RENAME, which act on every match. For reading, name the file exactly.
- A full directory gives ERROR 169 even on a half-empty disk. Use fewer, larger files, or a DOS with subdirectories (MyDOS, SpartaDOS).
- To make a disk bootable from your own program,
OPEN #1,8,0,"D:DOS.SYS":CLOSE #1does the same job as DUP's H option for DOS.SYS (DUP.SYS still has to be copied separately). Keep DOS.SYS locked on your working disks.
Troubleshooting
- ERROR 165 on a name that looks fine: a lower-case letter, a leading digit (DOS 2.0S), or a missing
D:. - The file has the "wrong" name: look for a hyphen, a space or a second period in what you typed.
- "BOOT ERROR" or endless retries after tidying a disk: DOS.SYS was renamed or deleted. Rename it back, or write a new one with DUP's H option.
- A new file appears in the middle of the directory: it took the slot of a deleted file. That's normal.
Further reading
- Bill Wilkinson, Inside Atari DOS (COMPUTE! Books, 1982): chapter 15 (File Name Decode Routine), chapter 16 (Directory Searching), chapters 20 and 21 (The Boot Process, Maintaining the Boot Record). The full text is on atariarchives.org.
- The Atari DOS 2.0S and DOS 2.5 reference manuals, for the user's view of file names and the DUP menu.
- On this site: Inside DOS 2 in Memory, Inside a DOS 2 Disk, DOS 2 File Operations from the Inside, Atari DOS 2.5, Writing a Bootable Disk Program (No DOS Required).
Credits
- Picture: The first test under DOS 2.0S: eight names go in, and the directory shows what FMS actually made of them. — Program authors; screenshot by the site
- Bill Wilkinson et al., Inside Atari DOS (COMPUTE! Books, 1982) — Chapter 15: File Name Decode Routine (FNDCODE $E9E, transform examples) — AtariArchives.org, 1982
- Inside Atari DOS — Chapter 16: Directory Searching (SFDIR $F21, CSFDIR $F31, holes, open-for-output skip) — AtariArchives.org
- Inside Atari DOS — Chapter 20: The Boot Process (XBCONT $714, DFSFLG, DFLINK) — AtariArchives.org
- Inside Atari DOS — Chapter 21: Maintaining the Boot Record (WRTDOS $120A, WD0 $1267, DELDOS $1219) — AtariArchives.org
- Own tests: three BASIC programs run in atari800 (XL, AltirraOS, Atari BASIC rev. C) on DOS 2.0S and DOS 2.5 disk images; directory and boot sectors inspected on the PC — XL
