LS-DOS 6.3.1 for the Model 4 - SYS3/SYS Disassembled
Page Customization
Page Index
SYS3/SYS
Other Navigation
Introduction/Summary
LS-DOS 6.3.1 SYS3/SYS Disassembly (Model 4)
SYS3/SYS is the system overlay of LS-DOS 6.3.1 that closes files and devices and turns a directory entry code back into a file specification. It is a load module of 882 bytes, 825 of them loaded in five load records covering two ranges, 1E00H-2136H and the length word at 23FEH-23FFH, with its transfer address at 1E00H. CKMOD@ on the SYS0/SYS page reads it into 1E00H whenever an SVC asks for overlay 5 and it is not already resident, and RST28 calls 1E00H with the request in Register A: 95H @CLOSE and A5H @FNAME from the SVC stubs, 85H from the COPY command, which only wants the overlay loaded, and B5H, a function that 6.3.1 has reduced to a RET (1E00H).
@CLOSE (1E12H) takes an FCB at Register Pair DE. A device FCB gets its specification back and nothing else (209DH). For a file, a short drive check of its own makes sure a diskette is turning in the drive (on a floppy drive whose DCT+4 bit 7 is clear: not on drive 0 of the release); if not, the CLOSE FAULT message asks for ENTER to try again or BREAK to give up (20C8H). The file's directory entry is read, the last buffer is written if it was changed (1E53H), and an FCB opened with UPDATE access or better has the entry brought up to date: the open bit reset, the end of file copied from the FCB, and, when the file was written to, the MOD flag, the date and, on a diskette dated in the new style, the time (1E67H). The granules that the directory gives the file beyond its end are then given back to the GAT, one at a time from the last extent, and extended directory entries left empty are given up with their HIT slots (1F1DH, 1F76H). Last, the name, extension and drive are written into the FCB as text, which closes it (200DH).
@FNAME (2064H) reads the directory entry of a DEC on a drive and writes its specification, NAME/EXT:d, into a buffer of the caller with the same routine.
The bytes are those of the LS-DOS 6.3.1 level 1H system diskette. The labels are those of the LS-DOS 6.3.1 source code of SYS3, which assembles to this file byte for byte.
Notes
The date of a change goes into the entry in two forms. DIR+1 bits 3-0 take the month and DIR+2 the day (bits 7-3) and the year less 1980 modulo 8 (bits 2-0), the old style, which can tell only eight years apart. When the bit of YFLAG$ for the drive is set (the diskette's GAT+CDH bit 3, read by @CKDRV), DIR+18 takes the hours (bits 7-3) and the high three bits of the minutes, and DIR+19 the low three bits of the minutes (bits 7-5) and the full year less 1980 (bits 4-0, 1980 to 2011): the field that held the user password hash in earlier versions. With no date set, the month, the day and the year are 0. The MOD flag (DIR+1 bit 6) is set only when the FCB shows a write (FCB+0 bit 2); DIR+1 bit 4, which the TRM says marks a change made with no date kept, is neither set nor reset.
Only an FCB opened with UPDATE access or better (FCB+0 bit 6) changes the directory at close. It resets the open bit in DIR+1 and writes the entry back on every close, even when nothing else changed and whether or not the open bit had been written to the disk at the open (SYS2/SYS writes it only with NFLAG$ bit 0). A file set up with the CREATE command (DIR+1 bit 7) keeps all its granules.
A close returns Z with Register A = 00H and every register but Register Pair AF as it was. It returns NZ with the error in Register A when a directory, HIT or GAT sector cannot be read or written or the last buffer cannot be written, with error 32 when the CLOSE FAULT message is answered with BREAK, and with error 38 for an FCB that is neither an open file nor a device; after every error but 38 the FCB stays open. A file whose directory entry is found no longer in use returns Z with Register A = 11H and is not closed (B22). @FNAME returns Register Pairs DE and HL as they were, not Register Pair HL at the entry as the TRM says, changes Register B, ends the text with 03H, not the 0DH of the TRM, and gives error 16 for a DEC whose sector is past the directory; it does not look at whether the entry is in use.
There are no hidden instructions. Four operands are changed while SYS3 runs: 1EEAH (the bit number of BIT n,A for the drive's bit of YFLAG$), 1FE5H (the DEC of the entry before an FXDE that is given up), 205CH (the drive digit of the text) and 20C6H (the bit number of RES n,B for a granule). The jump at 1EB4H is never reached, and the error 15 path at 2004H (a write protected diskette after the entry was written) returns success without writing the GAT.
Bugs (listed on the LS-DOS reference page): B21, CLOSE reads the directory entry before it writes the last buffer and keeps its pointer into SBUFF$; when that write (byte I/O) has to look up or allocate a granule in an extended directory entry that lies in another directory sector, SBUFF$ is left holding that sector, and CLOSE changes the bytes at the file's place in it, writes the whole sector over the sector of the file's own entry, which destroys the entries there, gives back granules by the extents of whatever entry sits at that place, which can be another file's, and puts that entry's name into the FCB (1E61H); B22, a file whose directory entry is no longer in use is not closed: the last buffer is lost and the FCB stays open, but Z is returned (1E5EH, latent); B23, after the CLOSE FAULT message ENTER checks only that a diskette is in the drive, not that it is the one the file was open on, so a wrong diskette gets the last buffer and the directory and GAT changes of another (20EBH, limit); B24, two FCBs can have the same file open with UPDATE access, because the open bit is not written to the disk, and the one closed last puts its own end of file back into the entry and gives back the granules past it, so what the other FCB added is lost (1E8EH, latent).
Variables
Memory Used by SYS3/SYS
| Address Size | Contents |
|---|---|
| 002EH-002FH 2 bytes | TIME$+1, TIME$+2 The minutes and the hours of the clock, read for the time field of the new style of dating (1EF5H). |
| 0033H-0035H 3 bytes | DATE$ The year less 1900, the day and the month, read for the date of a change (1EC1H, 1EC9H, 1ED1H); all 00H when no date was set. |
| 0074H 1 byte | KFLAG$ Bit 0, the BREAK bit, tested and reset through @CKBRKC while the CLOSE FAULT message waits for a key (20D0H, 20DCH). |
| 0082H 1 byte | YFLAG$ One bit for each drive, set when its diskette uses the new style of dating; tested for the file's drive (1EE6H). |
| 0470H-04BFH 80 bytes | DCT$ The drive code table entry of the file's drive: DCT+3 bit 3 hard drive, DCT+4 bits 4 and 7 alien and no index test, DCT+5 the current cylinder (1E29H-1E3CH); DCT+4 bit 5 two sided (1F91H, 207BH); DCT+7 heads and sectors (2068H); DCT+8 granules per track and sectors per granule (1F54H, 1F85H). |
| 1D00H-1DFFH 256 bytes | SBUFF$ The directory sector of the file's entry (1E58H, 2019H), of its FXDEs (1F41H), of the entry before an FXDE that is given up (1FE6H) and of an entry asked for by @FNAME (2094H), and the HIT (1FD9H). |
| 1EEAH 1 byte | BIT operand The second byte of BIT n,A, 47H + 8 x drive (1EE3H). |
| 1FE5H 1 byte | STUFDEC operand The DEC of the entry before an FXDE that is given up, from the FXDE's DIR+1 (1FD6H). |
| 205CH 1 byte | RCVN5 operand The drive as an ASCII digit for the text of the specification (2025H). |
| 20C6H 1 byte | CALC1 operand The second byte of RES n,B, 80H + 8 x the granule (20C2H). |
| 2300H-23FFH 256 bytes | DIRBUF$ The GAT of the file's drive, read when granules are to be given back (1F70H), changed bit by bit (1FAAH) and written back (2009H). |
| 23FEH-23FFH 2 bytes | Overlay length 0337H, the length of SYS3 read by SYSTEM (SYSRES). |
Routines of Other Files Called
| Address | Routine |
|---|---|
| 052DH | @DSPLY (BOOT/SYS): shows the CLOSE FAULT message (20CDH). |
| 0553H | @CKBRKC (BOOT/SYS): tests and resets the BREAK bit (20D0H, 20DCH). |
| 0635H | @KBD (BOOT/SYS): scans the keyboard (20D3H). |
| 06E3H | @DIV16 (BOOT/SYS): the ERN divided by the sectors per granule (1F61H). |
| 13A2H | RWRIT@ (SYS0/SYS): writes the last buffer if it was changed (1E61H). |
| 1566H, 1568H | LNKFCB@ and CKOPEN@ (SYS0/SYS): save the registers, point Index Register IX at the FCB and plant RESTREG (20A2H; 1E18H). |
| 1803H | @DIRWR (SYS0/SYS): writes a directory sector (1F18H, 1FCCH, 1FF5H, 1FFFH). |
| 1874H, 1875H | @GATRD and @GATWR (SYS0/SYS): read and write the GAT (1F70H; 2009H). |
| 1897H, 1898H | @HITRD and @HITWR (SYS0/SYS): read and write the HIT (1FD9H; 1FE0H). |
| 18BBH | @DIRRD (SYS0/SYS): reads the directory sector of an entry (1E58H, 1F41H, 1FE6H, 2019H, 2094H). |
| 190AH, 1927H | @MUL8 and @DIV8 (SYS0/SYS): sectors per cylinder (2075H); a granule turned into a cylinder and a granule in it (1F9AH). |
| 19D0H, 19D4H | @SEEK and @RSLCT (SYS0/SYS): a seek to the current cylinder and the controller status (1E41H; 1E23H, 1E47H). |
| 1A1EH, 1A2BH | @GTDCT and @DCTBYT (SYS0/SYS): the drive code table entry and one of its fields (1E20H; 1F54H, 1F85H, 1F91H, 2068H, 207BH). |
Disassembly
1E00H - SYS3: Entry and the Function Dispatcher
SYS3/SYS is loaded at 1E00H by CKMOD@ (1A7FH on the SYS0/SYS page) whenever an SVC asks for overlay 5 and it is not already resident, and RST28 calls 1E00H with Register A holding the request. Bits 6-4 of the request pick the function: 95H @CLOSE and A5H @FNAME come from the SVC stubs at 1999H and 199CH; B5H was the customer service number check of earlier versions and is only a RET in 6.3.1. Request 85H only loads the overlay and returns (the COPY library command sends it to have SYS3 in memory).
1E12H - CLOSE: @CLOSE and the Drive Check
@CLOSE (SVC 60, request 95H) has Register Pair DE at an FCB. An FCB whose first byte has bit 7 clear is not an open file: CLOSDEV (209DH) closes a device FCB (10H) and refuses anything else with error 38. For an open file CKOPEN@ saves the registers and points Index Register IX at the FCB; then a short check of its own makes sure the drive holds a diskette before the directory is touched: the controller must not be busy, and for a floppy drive that is not marked hard, alien or without an index test, a seek to the current cylinder must be followed within 48 status reads by a moment without the index pulse. A drive that fails goes to HOLDUP (20C8H), which shows the CLOSE FAULT message and waits for ENTER (try again) or BREAK (give up with error 32). In the release drive 0 has that bit set in its DCT+4, so a close on drive 0 never looks for the diskette.
1E53H - SAWBLK: Read the Directory Entry and Write the Last Buffer
The directory entry of the file (its DEC is FCB+7) is read into SBUFF$ at 1D00H. If the entry is no longer in use the close stops here and returns Z without writing anything. Otherwise RWRIT@ writes the last buffer of the file when it was changed in byte I/O. Bug B21: the entry is read before that write, and Register Pair HL is kept pointing into SBUFF$. When the last buffer is written in byte I/O, its granule is not among the FCB's extent records and the extent that holds or gets it is in an extended directory entry (FXDE) in another directory sector, RWRIT@ leaves that sector in SBUFF$ (unless the exclamation mark option made WEOF1 read the FPDE again): everything below then changes the bytes at the file's place in the wrong sector, writes them over the file's own directory sector (1F18H), gives back granules by the extents of whatever entry is at that place, and puts that entry's name into the FCB.
1E67H - CLOSE: the End of File, the MOD Flag and the Date
Only an FCB opened with UPDATE access or better (FCB+0 bit 6, set by OPNCB in SYS2/SYS) has close authority; any other close goes straight to RCVN0 (200DH) and leaves the directory as it is. With close authority the open bit (DIR+1 bit 5) is reset, the EOF offset (DIR+3) and the ERN (DIR+20, DIR+21) are taken from the FCB, and a file that was written to (FCB+0 bit 2) gets the MOD flag (DIR+1 bit 6) and the date of the change: the month in DIR+1, the day and the year less 1980 modulo 8 in DIR+2, and on a diskette with the new style of dating (its bit of YFLAG$) the time and the full year in DIR+18 and DIR+19. The entry is then written back.
1F1DH - CLOS6: Count the Granules the Directory Gives the File
Unless the file was set up with the CREATE command (DIR+1 bit 7), the close gives back the granules that lie past its end. CLOS6 adds up the granules of every extent of the entry, following the link (FEH and a DEC in the fifth field) into each extended directory entry (FXDE). The number of granules the file needs is its ERN rounded up to whole granules. When the directory gives the file more than that, the GAT is read and BAKUP (1FB7H) starts taking granules off at the end.
1F76H - CLOS11: Give One Granule Back
CLOS11 finds the last granule of the extent whose allocation byte is at Register Pair HL: the starting granule plus the count less 1, turned into cylinders and a granule by the number of granules per cylinder (doubled on a two sided diskette). The granule's bit in the GAT byte of that cylinder is reset (CALCBIT, 20BBH) and the extent is made one granule shorter. An extent left empty is marked unused (FFH FFH) and the walk steps back one field; when it steps back past the first field of an FXDE, that FXDE is given up too (BAKUP).
200DH - RCVN0 and RCVNAM: Put the File Specification Back
Every close of a file ends here. The directory sector of the file's FPDE is read again unless SBUFF$ already holds it (the last DEC in Register B is in the same sector), and RCVNAM writes the name, the extension and the drive into the FCB as text: NAME/EXT:d and 03H, at most 15 bytes. The first byte becomes a character with bit 7 clear, so the FCB is closed, and the specification can be given to @OPEN again; the password is not put back. @FNAME (2064H) calls RCVNAM at 2020H for a buffer of its caller.
2064H - FNAME: @FNAME, the File Specification of a Directory Entry
@FNAME (SVC 80, request A5H) has Register B = a DEC, Register C = a drive and Register Pair DE at a buffer of 15 bytes. It works out the number of directory sectors of the drive from its drive code table (sectors per cylinder less the GAT and the HIT), refuses a DEC whose sector bits lie past them with error 16, reads the entry's sector and lets RCVNAM write NAME/EXT:d and 03H into the buffer. Register Pairs DE and HL come back as they were (the TRM says Register Pair HL points to the entry), Register B is changed. The entry is not checked: a free entry or an FXDE gives whatever its name field holds.
209DH - CLOSDEV: Close a Device
An FCB that is not an open file is closed here only if it is a device FCB, 10H (routed) as DEVOPEN in SYS2/SYS builds it; anything else returns error 38 (File not open). The device itself is not told anything: the FCB just gets its specification back, an asterisk and the two letters DEVOPEN kept at FCB+6 and FCB+7, ended by 03H.
20BBH - CALCBIT: Reset a Granule's Bit
CALCBIT builds the instruction RES n,B at 20C5H for the granule number n in Register A and runs it, so that the granule's bit in the GAT byte held in Register B is reset.
20C8H - HOLDUP: the CLOSE FAULT Message
When the drive check of CLOSE fails, HOLDUP shows the message at 20EEH and waits for a key. ENTER goes back to CKAGN (1E23H) to check the drive again; BREAK gives up the close with Register A = 20H (error 32, Illegal drive number) and the NZ flag, leaving the FCB open. Every other key is ignored. Nothing checks that the diskette put back is the one the file was open on (B23).
2136H - DOID, Free Space and the Overlay Length
DOID was function 3 of SYS3 in earlier versions: it checked and showed the customer service number for the ID library command. 6.3.1 assembles only its RET (`@BLD631`), and the ID command shows No service contract! instead. The rest of the overlay area is not loaded, and the length of SYS3 at 23FEH ends the file as in the other system overlays.