DOS 2 File Operations from the Inside: What OPEN, CLOSE, APPEND, RENAME and POINT Really Do

Atari BASIC screen listing five numbered tests: two files both called B.DAT after a rename, C.DAT using four sectors after three appends, POINT on an output file giving ERROR 171, a POINT into another file giving ERROR 164, and deleting a locked file…

Atari DOS 2.0S is small enough that its whole file manager (FMS) was published with a commentary, in Inside Atari DOS (COMPUTE! Books, 1982). Its chapters walk through each routine: what happens on OPEN, on CLOSE, on each XIO command, and when a sector fills up. Read them next to a running system and a lot of DOS 2 folklore suddenly makes sense: why RESET can lose a file, why appending wastes disk space, why RENAME can leave you with two files of the same name.

This guide follows those routines and checks each consequence with a BASIC program. It builds on two earlier guides: Inside DOS 2 in Memory (the layers, FCBs, buffers and burst I/O) and Inside a DOS 2 Disk (VTOC, directory and sector links). For everyday file handling, see Working with Disk Files in Atari BASIC.

What you need: Atari BASIC and a DOS 2.0S disk. The programs were run in atari800 (XL/XE mode, with its built-in AltirraOS) and a real Atari BASIC revision C ROM, on a DOS 2.0S disk and again on DOS 2.5. Both DOSes gave the same results. Routine names and addresses below are DOS 2.0S's, from the book.

1. How a command reaches FMS

CIO calls FMS through its handler table, DFMSDH at $07CB. Open, Close, Get Byte, Put Byte and Status each have their own entry. Everything else (XIO and BASIC's NOTE and POINT) arrives at one routine, DFMDDC ($BA7). It sends 254 to the formatter and accepts command numbers 32–38 ($20–$26), dispatching them through a table:

XIO Command FMS routine
32 Rename XRENAME ($BD9)
33 Delete XDELETE ($C32)
35 / 36 Lock / Unlock XLOCK / XUNLOCK ($C7C)
37 Point XPOINT ($CBA)
38 Note XNOTE ($D03)
254 Format XFORMAT ($D18)

Anything else gets the command error. All disk traffic goes through one small routine, BSIO ($76C), which fills in the device control block and calls SIO with four retries.

2. OPEN

The open routine, DFMOPN ($8AB), decodes the file name, checks for the directory-read code (6 in BASIC's OPEN), searches the directory, and then branches on the mode:

  • Input (4) and update (12): the name must exist (otherwise error 170). Update also checks the lock. The first data sector is read into the file's buffer at once.
  • Output (8): if the name exists, the old file is deleted on the spot by XDELO, then a new directory entry is made, a first sector is allocated, and the entry is written back with the "open for output" flag.
  • Append (9): the name must exist, it must not be locked or a DOS 1 file, and the disk must not be write-protected. FMS then allocates a new sector to start the appended data and remembers it in the FCB for CLOSE.

The order in the output case matters more than anything else in this guide. Section 6 shows why.

3. Writing, and when sectors hit the disk

Bytes go into the file's 128-byte sector buffer. Only when it is full does WRTNXS ($F94) act: it calls GETSECTOR for a new sector number, stores the byte count and the new sector's number in the last three bytes (with the file number), writes the full sector and starts filling the next. So at any moment the newest data, up to 125 bytes, exists only in memory.

GETSECTOR ($1106) scans the VTOC bit map from the start for the first free sector, clears its bit, decrements the free count and flags the VTOC as changed. It is not written back yet. Because the scan starts at the beginning, freed sectors near the front of the disk are reused first. In our tests a replaced file started at exactly the same sector as the file it replaced.

4. CLOSE

DFMCLS ($B15) does nothing much for an input file. For an output or append file it:

  1. writes the last, partly filled data sector;
  2. for an append, reads through the whole existing file to its last sector and links the new chain onto it;
  3. in CLOUT ($B50), updates the directory entry's sector count, clears the "open for output" flag, and writes the directory sector and then the VTOC.

Step 2 means appending to a long file is slow, because CLOSE follows every sector link. Step 3 means the directory and VTOC on the disk are only brought up to date at CLOSE.

5. The first test program

10 DIM L$(40):TRAP 20:XIO 36,#1,0,0,"D:*.DAT":XIO 33,#1,0,0,"D:*.DAT"
20 ? "1 RENAME A.DAT TO B.DAT:"
30 OPEN #1,8,0,"D:A.DAT":? #1;"FILE A":CLOSE #1
40 OPEN #1,8,0,"D:B.DAT":? #1;"FILE B":CLOSE #1
50 XIO 32,#1,0,0,"D:A.DAT,B.DAT":GOSUB 500
60 ? "2 ONE WRITE, THEN 3 APPENDS:"
70 OPEN #1,8,0,"D:C.DAT":? #1;"ONE":CLOSE #1
80 FOR I=1 TO 3:OPEN #1,9,0,"D:C.DAT":? #1;"MORE":CLOSE #1:NEXT I
90 GOSUB 500
100 ? "3 POINT ON OUTPUT FILE: ";
110 TRAP 130:OPEN #1,8,0,"D:E.DAT":S=100:B=0:POINT #1,S,B
120 ? "OK":GOTO 140
130 ? "ERROR ";PEEK(195)
140 CLOSE #1:? "4 POINT B.DAT INTO C.DAT: ";
150 OPEN #1,4,0,"D:C.DAT":NOTE #1,S,B:CLOSE #1
160 TRAP 190:OPEN #1,4,0,"D:B.DAT":B=0:POINT #1,S,B:? "POINT OK, ";
170 GET #1,X:? "GET OK"
180 GOTO 200
190 ? "ERROR ";PEEK(195)
200 CLOSE #1:? "5 LOCK B.DAT, THEN DELETE: ";
210 XIO 35,#1,0,0,"D:B.DAT":TRAP 230:XIO 33,#1,0,0,"D:B.DAT"
220 ? "OK":GOTO 240
230 ? "ERROR ";PEEK(195)
240 GOSUB 500
250 END
500 TRAP 540:OPEN #2,6,0,"D:*.DAT"
510 INPUT #2,L$:? L$
520 GOTO 510
540 CLOSE #2:RETURN

Line 10 tidies up from any earlier run. Lines 500–540 read the directory as a file with OPEN mode 6, the same formatted listing DUP prints. FMS builds each line in FDENT, with an asterisk for a locked file, and a final line from the VTOC's free count. The output on DOS 2.0S (shown in the screenshot) was:

Test 1: RENAME made a duplicate. After renaming A.DAT to B.DAT, the directory held two files called B.DAT. XRENAME searches for the old name, checks the lock, and overwrites the name in each matching entry. Nothing checks whether the new name is already in use. Every later command that searches by name finds both: LOCK in test 5 locked both copies (two asterisks), and a DELETE would remove both. Wildcards work the same way, so XIO 32,#1,0,0,"D:*.DAT,*.BAK" renames every match. To clean up duplicates, rename one of them with something only it matches, or copy the one you want under a new name before deleting.

Test 2: three appends cost three sectors. One short PRINT and three appended PRINTs, about 20 bytes, took 4 sectors: each append started a new sector, and the half-empty sectors before it stay half empty. Programs that log data by opening for append, writing a line and closing again waste most of a sector per entry. Keep the file open, or rewrite it.

Test 3: POINT on an output file: ERROR 171. XPOINT refuses any file that can acquire new sectors (output or append). For random access, open with mode 12 (update) or 4 (input).

Test 4: POINT into another file's sector: ERROR 164. We NOTEd a position in C.DAT and POINTed B.DAT at it. FMS read the sector, found C.DAT's file number in its last bytes, and stopped with the file number mismatch error, at the POINT itself, before any GET. This is the same check that catches broken sector chains while reading (RDNXTS, $100F).

Test 5: locked files. XLOCK sets bit 5 ($20) of each matching directory entry's flag, and DELETE on a locked file gives ERROR 167.

One BASIC detail turned up while writing the test: Atari BASIC's NOTE and POINT need variables for the sector and byte. POINT #1,100,0 is a syntax error; S=100:B=0:POINT #1,S,B is accepted.

6. The second test: RESET before CLOSE

10 DIM L$(40):IF PEEK(1536)=99 THEN 100
20 POKE 1536,99:? "OPEN C.DAT FOR OUTPUT, WRITE 300 BYTES"
30 OPEN #1,8,0,"D:C.DAT":FOR I=1 TO 300:PUT #1,65:NEXT I
40 ? "DIRECTORY WHILE STILL OPEN:":GOSUB 500
50 ? "NOW PRESS RESET, THEN TYPE RUN"
60 GOTO 60
100 POKE 1536,0:? "AFTER RESET:":GOSUB 500
110 TRAP 140:OPEN #1,4,0,"D:C.DAT":N=0
120 GET #1,X:N=N+1:GOTO 120
140 ? "READ ";N;" BYTES, ERROR ";PEEK(195):CLOSE #1
150 END
500 TRAP 540:OPEN #2,6,0,"D:*.DAT"
510 INPUT #2,L$:? L$
520 GOTO 510
540 CLOSE #2:RETURN

Run on the disk left by the first test, it opens the existing four-sector C.DAT for output, writes 300 bytes (two full sectors and part of a third), lists the directory with the file still open, and waits. After RESET, a flag in page 6 sends the second RUN to line 100.

  • While open: C.DAT was missing from the listing. The directory search skips entries flagged "open for output", and the old C.DAT had already been deleted at OPEN. The free count read 620, from the VTOC in memory.
  • After RESET: C.DAT was still missing, and opening it for input gave ERROR 170, file not found. The free count read 619, the figure from before the test, because the VTOC in memory was never written back.

Looking at the disk image on a PC afterwards explained the rest. The C.DAT directory entry was still there with the flag $43 ("in use" plus "open for output") and a sector count of 0, so DOS skips it while it still takes a directory slot. The new data had gone into sectors 87 and 88, over the start of the old file. The old file's sectors were still marked as used in the VTOC, and nothing pointed at them.

So a RESET, a crash, a power cut or a disk swap between OPEN and CLOSE costs you both versions of the file. Atari BASIC closes open files for you at END (we checked: a file written without CLOSE before END read back all 300 bytes), and RUN and NEW close all channels too. RESET does not. Two habits protect important files:

  1. Write to a new name, then swap. Write SCORES.NEW, CLOSE it, delete SCORES.DAT, then rename SCORES.NEW to SCORES.DAT. If anything fails, one complete copy survives. (Delete first: RENAME won't stop you creating a duplicate.)
  2. Keep the open window short. Open, write, close, rather than leaving a file open for output while the user plays.

7. Delete, format and the write-protect check

XDELETE ($C32) loops over every matching name, which is why wildcards delete groups. For each file XDELO ($C53) checks that the disk can be written, checks the lock, sets the "deleted" bit in the directory flag, then follows the file's sector chain and returns each sector to the bit map with FRESECT ($10C5). The data itself isn't touched, which is what makes un-deleting possible (see Inside a DOS 2 Disk).

The write check is OPVTOC ($10BF). It simply reads the VTOC and writes it straight back. On a write-protected disk that write fails with error 144 before anything has been changed.

XFORMAT asks the drive to format the disk, then builds an empty VTOC: every sector free except the boot sectors and the nine VTOC and directory sectors, and eight cleared directory sectors. It doesn't write DOS.SYS. Writing DOS files is a separate job for DUP.

Troubleshooting

  • ERROR 170 on a file you just wrote: it was never closed. Data written since OPEN is gone, and so is the previous version.
  • Two files with the same name: an earlier RENAME. Rename one by a pattern only it matches, or copy, delete both and copy back.
  • ERROR 171 from POINT: the file is open for output or append. Use mode 12.
  • ERROR 164 from POINT: the sector belongs to another file, usually a stale NOTE value or an index file from another disk.
  • ERROR 167: the file is locked. XIO 36 unlocks it (and every other file the name matches).
  • Free sector count drops and never comes back: files left open at RESET leave orphaned sectors. A disk fixer, or copying the files to a fresh disk, recovers them.
  • Syntax error on POINT or NOTE: use variables, not constants.

Further reading

  • Bill Wilkinson and others, Inside Atari DOS (COMPUTE! Books, 1982), chapters 7–19: device-dependent commands, open, close, get and put byte, directory reading, sector I/O, file name decoding, directory search, and the sector allocation routines.
  • Atari, Disk Operating System II Reference Manual: the DOS error numbers and XIO commands.
  • On this site: Inside DOS 2 in Memory: How the File Manager Works, Inside a DOS 2 Disk: VTOC, Directory, Sector Links and Deleted Files, Working with Disk Files in Atari BASIC, Atari BASIC Error Codes Explained, Atari DOS 2.5: A Practical Guide.

Credits