LS-DOS 6.3.1 for the Model 4 - SYS2/SYS Disassembled
Page Customization
Page Index
SYS2/SYS
Other Navigation
Introduction/Summary
LS-DOS 6.3.1 SYS2/SYS Disassembly (Model 4)
SYS2/SYS is the system overlay of LS-DOS 6.3.1 that opens files and devices. It is a load module of 1222 bytes in seven load records covering three ranges: 1E00H-22BDH, 22D5H-22DAH 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 4 and it is not already resident, and RST28 calls 1E00H with the request in Register A: 94H @OPEN, A4H @INIT, B4H @GTDCB, C4H @CKDRV or F4H @RENAME from the SVC stubs, and D4H or E4H from programs that want a name or a password hashed. Bits 6-4 of the request pick the function (1E00H).
@OPEN (1F5EH) takes a specification as @FSPEC leaves it in an FCB. A device (an asterisk and two letters) is found among the device control blocks at 0208H-02FFH (1E59H) and the FCB is routed to it (1F43H). For a file, XFRSPEC (219EH) copies the name, extension and password into work fields, the name and extension are hashed into one byte and the password into a word (1E1EH), and the hash is looked for in the Hash Index Table of the drive given, or of drives 0 to 7 in turn; each drive is first checked by CKDRV (1E7AH), which also reads the GAT and sets the drive's geometry and its bit of YFLAG$ from it. A slot that holds the hash leads to its directory entry, whose name is compared. The owner password gives full access; otherwise the file's protection level is the access, and NO ACCESS refuses the open (2000H). OPNCB (204CH) builds the 32 byte open FCB, with the buffer, the drive, the DEC, the record length and the extents, and checks the record length against the directory.
@INIT (2118H) opens a file or, when it is not found, creates it in a free slot of the directory, trying the middle of the directory first (220AH). @RENAME (2217H) gives a file a new name on the same drive, or a device new letters (229AH). @GTDCB finds a device control block by name, and @CKDRV tells whether a drive is ready and write protected.
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 SYS2, which assembles to this file byte for byte.
Notes
The hash of a name is the eleven characters of name and extension added bit by bit with a rotate after each, never 00H, which marks a free HIT slot. A password hashes to a word; eight spaces, no password, give 4296H. The slot of a file in the HIT is the DEC of its directory entry: bits 7-5 the entry in the sector, bits 4-0 the directory sector less 2.
Only the owner password (DIR+16) is compared. DIR+18 and DIR+19, once the user password, hold the time of the last change in this version; @INIT still writes the password hash there. A file created with a password gets protection NO ACCESS. With bit 7 of NFLAG$ set every password matches. The open bit of DIR+1 is set in the copy of the entry, but written to the disk only when bit 0 of NFLAG$ is set, which it is not in the file.
An FCB that starts with D2H (the letter R with bit 7 set) given to @RENAME is a request of the BACKUP utility: REN0 (2210H) changes the JR Z at 2023H into a JR, so that every open grants full access without the password, until SYS2 is next loaded into the overlay area.
Two places hide an instruction: 2167H and 216AH are 01H bytes (LD BC,nnnn) that pass over the LD A of the next error code. Several operands are changed while SYS2 runs: 1ED7H (the long count of the index test), 1F0AH (a SET or RES instruction for YFLAG$), 1F94H (the drive), 2023H (the opcode patched by REN0), 2036H (SFLAG$ on entry), 2080H (the write protect state), 20B5H (the access level), 20BDH (the exclamation mark bit), 20C5H-20C6H (the buffer) and 2132H (the attribute byte of a new file); SYS2 also stores C9H at 1A79H in SYS0/SYS to keep the debugger off for an EXEC only file.
A successful open of a file with its checks returns Z with Register A = 2AH, the code of the record length error, not 00H (a device, or an open with SFLAG$ bit 0, returns 00H). A drive given that is not ready makes @OPEN return error 24, not a drive error. An open that finds the file marked open in the directory, or the record lengths different, still leaves the FCB open and returns error 41 or 42. With no drive given, @INIT reports error 26 (No directory space available) when no drive can take the file, even when the drives are only write protected or not ready.
Bugs (listed on the LS-DOS reference page): B16, when the GAT cannot be read CKDRV returns the flags of the controller status saved before the read, not the error, and would report the drive ready if that status were 00H (1EF1H, latent); B17, an extension or a password that starts with a digit is taken as missing and the rest of the specification is ignored, so REPORT/1A:1 opens or creates REPORT on any drive (21C3H); B18, @RENAME writes a colon, a drive digit and 0DH into the caller's new name, two bytes past its end when it has no drive, and when the new name exists a whole FCB over it (225AH, latent); B19, @INIT writes the password hash into DIR+18 and DIR+19, the time field of a new entry (218BH, latent); B20, @INIT writes the HIT slot before the directory entry, so a failed directory read or write leaves a slot taken with no entry (2174H, latent).
Variables
Memory Used by SYS2/SYS
| Address Size | Contents |
|---|---|
| 000EH 1 byte | FDDINT$ F3H (DI) when SYSTEM (SMOOTH) is on: CKDRV then halves its index count and tests with interrupts off (1EBAH). |
| 0077H 1 byte | NFLAG$ Bit 7, the network bit, makes every password match (2016H); bit 0 has the open bit written to the directory (2088H). 00H in the file. |
| 007CH 1 byte | SFLAG$ Saved at 1F64H and bits 0-2 cleared on each open; bit 0 (no checks) set by RENAME (2229H, 2265H), bit 1 set for an EXEC only file run by @RUN (203EH), bit 2 reset by INIT (2127H). |
| 0082H 1 byte | YFLAG$ One bit for each drive, set or reset by CKDRV from GAT+CDH bit 3, the new style of directory dating (1F09H). |
| 0208H-02FFH 248 bytes | Device control blocks Searched by name (DCB+6, DCB+7) by GTDCB (1E5FH); RENDEV writes a new name (22B9H). |
| 1A79H 1 byte | SET@EXEC The debugger hook that RST28 puts back after the SVC; C9H is stored for an EXEC only file (2045H). |
| 1D00H-1DFFH 256 bytes | SBUFF$ The GAT read by CKDRV (1EEEH, GAT+CCH and GAT+CDH at 1DCCH), the HIT (1F9FH) and the directory sectors (1FD3H) in turn. |
| 1ED7H 1 byte | CDCNT operand The high byte of the long index count, 09H or 04H (1EC5H). |
| 1F0AH 1 byte | BIT1 The second byte of SET n,(HL) or RES n,(HL) for YFLAG$ (1F03H). |
| 1F94H 1 byte | OPEN2 operand The drive asked for, FFH for none (21ABH, 21D4H), then the drive the file was found on (1FF8H). |
| 2023H 1 byte | WASMAT The opcode of JR Z, made a JR by REN0 (2212H). |
| 2036H 1 byte | OPEN14 operand SFLAG$ as it was on entry to OPEN1 (1F64H), tested for bits 2 (2037H) and 0 (2059H). |
| 2080H 1 byte | OPNCB9 operand 80H when the drive last checked by CKDRV is write protected (1F2AH). |
| 20B5H 1 byte | OPNCB1 operand The access level for FCB+1 (2047H, 211BH). |
| 20BDH 1 byte | OPNCB3 operand 08H when the specification ends with an exclamation mark (21E5H). |
| 20C5H-20C6H 2 bytes | OPNCB4 operand The buffer address for FCB+3 and FCB+4 (1F77H). |
| 2132H 1 byte | INIT0 The attribute byte of a new file: 10H (2120H), or 17H with a password (21EBH). |
| 22BEH-22C5H 8 bytes | PSWDBUF The password of the specification, padded with spaces (21A0H, 21CAH). |
| 22C6H-22D0H 11 bytes | NAME$EXT and FILE$EXT The name and the extension, padded with spaces (21B0H, 21C3H). |
| 22D1H-22D4H 4 bytes | PW$HASH1 and PW$HASH2 The hash of the password given, twice (1F8DH, 1F90H). |
| 22D5H-22DAH 6 bytes | ERN init and DIR$INIT 0000H and four bytes for DIR+20, DIR+21 and DIR+0 to DIR+3 of a new entry (2133H, 2184H). |
| 22DBH 1 byte | LREC$ The logical record length asked for (1F74H). |
| 22DCH 1 byte | FILEHASH The hash of the name and extension (1E2AH). |
| 23FEH-23FFH 2 bytes | Overlay length 04DBH, the length of SYS2 read by SYSTEM (SYSRES). |
Routines of Other Files Called
| Address | Routine |
|---|---|
| 1566H | LNKFCB@ (SYS0/SYS): saves the registers, points Index Register IX at the FCB and plants RESTREG (1F5EH, 2118H, 2217H). |
| 1803H | @DIRWR (SYS0/SYS): writes a directory sector (208DH, 2194H, 2287H). |
| 181FH | @SCNHIT (SYS0/SYS): finds a free HIT slot (220CH). |
| 1897H, 1898H | @HITRD and @HITWR (SYS0/SYS): read and write the HIT (1F9FH, 1FC9H, 2147H, 228AH; 2174H, 2297H). |
| 18BBH | @DIRRD (SYS0/SYS): reads the directory sector of an entry (1FD3H, 2177H, 2274H). |
| 18D8H | @RDSSC (SYS0/SYS): reads the GAT (1EEEH). |
| 18F7H | @DIRCYL (SYS0/SYS): the directory cylinder of a drive (1EE7H). |
| 19C8H, 19D0H, 19D4H | @RSTOR, @SEEK and @RSLCT (SYS0/SYS): restore, seek and the controller status (1E97H, 1EA2H, 1EA8H, 1F39H). |
| 1A1EH | @GTDCT (SYS0/SYS): the drive code table entry of a drive (1E7CH). |
Disassembly
1E00H - SYS2: Entry and the Function Dispatcher
SYS2/SYS is loaded at 1E00H by CKMOD@ (1A7FH on the SYS0/SYS page) whenever an SVC asks for overlay 4 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: 94H @OPEN, A4H @INIT, B4H @GTDCB, C4H @CKDRV and F4H @RENAME come from the SVC stubs at 198AH-1996H; D4H hashes a file name and E4H hashes a password for the utilities that issue those requests themselves (ATTRIB, PURGE, BACKUP, FORMAT and REPAIR use E4H). Request 84H only loads the overlay and returns (BACKUP sends it to have SYS2 in memory).
1E59H - GETDCB and GTDCB: @GTDCB, Find a Device Control Block
@GTDCB (SVC 82, request B4H) looks through the device control blocks at 0208H-02FFH, 31 blocks of 8 bytes, for one whose name (DCB+6 and DCB+7) is the two letters in Register Pair DE, Register E the first. It returns Z with Register Pair HL at the block, or NZ with error 8 (Device not available). A name of 0000H finds the first free block. GETDCB takes the name from FCB+1 and FCB+2, the letters after the asterisk of a device specification, for DEVOPEN and RENDEV.
1E7AH - CKDRV: @CKDRV, Check a Drive
@CKDRV (SVC 33, request C4H) checks that drive Register C is enabled and holds a formatted diskette that turns. For a floppy drive it brings the head to a valid cylinder, waits for an index pulse (unless bit 7 of DCT+4 says not to), reads the GAT and updates the drive code table from it: the highest cylinder from GAT+CCH and the sides from GAT+CDH bit 5. For every drive it sets or resets the drive's bit of YFLAG$ from GAT+CDH bit 3. It returns Z when the drive is ready, with the Carry flag set for a write protected diskette or drive, and NZ when it is not. OPEN and INIT call it for each drive they search, and leave the write protect state at 2080H for OPNCB.
1F43H - DEVOPEN: Open a Device
A specification that starts with an asterisk names a device. DEVOPEN finds its DCB with GETDCB and turns the FCB into a DCB routed to it: FCB+0 = 10H (routed), FCB+1 and FCB+2 the address of the device's DCB, FCB+3 to FCB+5 zero, FCB+6 and FCB+7 the device name. Character I/O through the FCB then goes to the device.
1F5EH - OPEN: @OPEN, Open an Existing File
@OPEN (SVC 59, request 94H) has Register Pair DE at an FCB holding a specification (as @FSPEC leaves it, ended by 03H), Register Pair HL at a 256 byte buffer and Register B = the logical record length (00H for 256). OPEN copies the parts of the specification into the fields at 22BEH-22D0H, hashes the name and the password, and looks for the hash in the Hash Index Table of the drive given, or of each drive from 0 to 7. For each slot that holds the hash it reads the directory entry (the slot's place is the entry's DEC) and compares the name and extension. INIT (212AH) and RENAME (222BH, 2267H) call OPEN1, after LNKFCB@.
2000H - OPEN: the Password and the Access Level
The file's owner password hash (DIR+16) is compared with the hash of the password given. A match gives full access (level 0). Without it the file's protection level (DIR+0 bits 2-0) is the access, unless it is 7 (NO ACCESS), which returns error 25. An EXEC only file (level 6) opened for @RUN gets READ access for the loader, and the debugger is turned off for any EXEC only open. DIR+18 and DIR+19, once the user password, hold the time of the last change in this version and are not compared. With bit 7 of NFLAG$ set every password matches.
204CH - OPNCB: Open the FCB and Check It
OPNCB has Register Pair HL at the directory entry in SBUFF$, Register B = its DEC, Register C = the drive and Index Register IX = the FCB. It builds the open FCB (OPNCB0) and, unless bit 0 of SFLAG$ was set on entry, checks it: a file marked open in the directory (DIR+1 bit 5) is given READ access with error 41 (File already open); for an access of UPDATE or more on a write protected drive the access becomes READ; otherwise the directory entry is marked open (written to the disk only when bit 0 of NFLAG$ is set) and FCB+0 bit 6 lets the FCB write. Last, the logical record length asked for is compared with DIR+4: a difference returns error 42, with the file open all the same.
20A5H - OPNCB0: Build the Open FCB
OPNCB0 fills the 32 bytes of the FCB at Index Register IX from the directory entry at Register Pair HL and from what OPEN kept: +0 open (80H) with the PDS bit of DIR+0; +1 bit 7 for record I/O (any LRL but 256), bit 5 (the buffer holds no sector yet), bit 3 (the exclamation mark) and the access level; +2 zero; +3 and +4 the buffer; +5 zero; +6 the drive; +7 the DEC; +8 the EOF offset (DIR+3); +9 the LRL asked for; +10 and +11 zero (the next record); +12 and +13 the ending record number (DIR+20); +14 and +15 the first extent, then for each further extent of the entry the count of granules before it and the extent, FFH where there is none.
2118H - INIT: @INIT, Open or Create a File
@INIT (SVC 58, request A4H) takes the same registers as @OPEN. It first tries OPEN1: an existing file is opened (Z, Carry clear). On error 24 it creates the file: on the drive given, or on the first drive from 0 up that is ready, not write protected and has a free HIT slot. The new entry gets the attribute byte 10H (in use, FULL) or 17H (protection NO ACCESS) when a password was given, the record length asked for, the name, the owner password (DIR+16) and the time field (DIR+18) both set to the hash of the password given (bug B19), an ending record number of 0 and no extents; the HIT slot gets the name's hash. OPNCB then opens it, and INIT returns with the Carry flag set. With no drive given and no drive usable the error is 26 (No directory space available); for the drive given it is 32 (not ready), 15 (write protected) or 26.
219EH - XFRSPEC: Take the Specification Apart
XFRSPEC reads the specification text at Register Pair HL (the FCB, as @FSPEC left it) and fills the fields that OPEN and INIT use: up to 8 characters of the name at 22C6H, after a slash up to 3 of the extension at 22CEH, after a period up to 8 of the password at 22BEH (all three are first blanked with spaces), after a colon the drive number into 1F94H (FFH when there is none), and a closing exclamation mark into 20BDH. The first character of each field must be a letter, the others letters or digits. It returns Z, or NZ with error 19 (Illegal file name) when the name has no valid character or error 32 (Illegal drive number) for a drive that is not 0 to 7. An extension or a password that starts with a digit is taken as missing, and the parts after it are never looked at (bug B17).
220AH - SPRHIT: Find a Free HIT Slot
SPRHIT calls @SCNHIT with 28H as the first slot to try, the second entry of the ninth directory sector (sector 10 of the directory cylinder), so new files go to the middle of the directory first; when that slot is taken, or the diskette has no tenth directory sector, @SCNHIT scans the HIT from slot 02H.
2210H - REN0 and RENAME: @RENAME, Rename a File
@RENAME (SVC 56, request F4H) has Register Pair DE at a closed FCB with the current specification and Register Pair HL at the new name, ended by 0DH or 03H. A device (asterisk) goes to RENDEV. An FCB whose first byte is D2H (the letter R with bit 7 set) is the special request of BACKUP: REN0 patches OPEN so that every open gets full access whatever the password, as long as this copy of SYS2 stays in the overlay area, and returns error 24. For a file, RENAME opens the old name without checks and needs an access of RENAME or better (error 37 otherwise). It forces the drive of the new name to the old one by writing a colon, the drive digit and 0DH into the caller's string, checks with OPEN1 that the new name is not in use (error 19 if it is), and then writes the new name into the directory entry and its hash into the entry's HIT slot.
229AH - RENDEV: Rename a Device
For a device RENAME finds the old DCB, refuses the system devices KI, DO, PR, SI, SO and JL (their DCBs lie below 0231H) with error 40, needs the new name to be a device specification that names no DCB yet (error 19 otherwise), and then writes the new two letters into DCB+6 and DCB+7.
22BEH - Work Fields, Free Space and the Overlay Length
The fields that XFRSPEC fills and OPEN and INIT read lie after the code. Only 22D5H-22DAH (the ERN of a new entry and four bytes of DIR$INIT) are loaded with the file. The overlay length at 23FEH counts 1E00H to 22DAH, so LREC$ and FILEHASH are left out of it.