LS-DOS 6.3.1 for the Model 4 - SYS4/SYS Disassembled
Page Customization
Page Index
SYS4/SYS
Other Navigation
Introduction/Summary
LS-DOS 6.3.1 SYS4/SYS Disassembly (Model 4)
SYS4/SYS is the system overlay of LS-DOS 6.3.1 that turns an error number into its message: the system error dictionary behind @ERROR (SVC 26). It is a load module of 1307 bytes, 1242 of them loaded in two ranges and the length word, 1E00H-2171H, 2177H-22DCH and 23FEH-23FFH, with its transfer address at 1E00H. CKMOD@ on the SYS0/SYS page reads it into 1E00H whenever an SVC asks for overlay 6 and it is not already resident, and RST28 calls 1E00H with the request in Register A: 96H from the @ERROR stub at 1B0FH, which has pushed the error number first (1E00H, 1EAFH).
A program gives @ERROR the error number in Register C, with bit 6 set for the short display (the message alone) and bit 7 set to get control back; with bit 7 clear the program is ended through @ABORT (1FB9H, 1FC1H). SFLAG$ bit 6 cancels bit 6 of the number, CFLAG$ bit 6 suppresses every display (error 63 too, where the TRM says 0 to 62), and CFLAG$ bit 7 puts the short message into the program's buffer at Register Pair DE instead of on the screen (1EEFH). The long display is the format the TRM gives for version 6.2:
| Line | Text (for error 24 after an @OPEN) |
|---|---|
| 1 | After a line feed: two asterisk signs, a space, Error code = 24, Returns to X'3012' |
| 2 | Two asterisk signs, a space, File not in directory |
| 3 | File = REPORT/TXT:1 |
| 4 | Last SVC = 59, Returned to X'300C' |
The first line holds the number in two decimal digits and the address after the program's RST 28H (1EFBH); the second the message; the third the file or device of the error, from the FCB or DCB that the last file SVC used (1FC4H); the fourth the number and the return address of the SVC before @ERROR (205AH).
The messages are not stored as text. Each error from 0 to 45 has a sentence: a list of word numbers in page 1EH (1E03H), found through the table of low bytes CODTAB (2178H). The words are in a dictionary of 58 words, each ended by its last character's bit 7 (21A6H). ERR2A (1F67H) finds each word by counting endings from the start of the dictionary, copies it with a space after it, and makes the first letter a capital. Error 63, the extended error, has a line of its own that shows the program's Register Pair HL in hex (1F3FH), and every number from 46 to 62 gives Unknown error code.
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 SYS4, which assembles to this file byte for byte.
Notes
The messages, as the code builds them: 0 No error, 1 Parity error during header read, 2 Seek error during read, 3 Lost data during read, 4 Parity error during read, 5 Data record not found during read, 6 Attempted to read system data record, 7 Attempted to read locked/deleted data record, 8 Device not available, 9 Parity error during header write, 10 Seek error during write, 11 Lost data during write, 12 Parity error during write, 13 Data record not found during write, 14 Write fault on disk drive, 15 Write protected disk, 16 Illegal logical file number, 17 Directory read error, 18 Directory write error, 19 Illegal file name, 20 GAT read error, 21 GAT write error, 22 HIT read error, 23 HIT write error, 24 File not in directory, 25 File access denied, 26 No directory space available, 27 Disk space full, 28 End of file encountered, 29 Record number out of range, 30 Directory full - can't extend file, 31 Program not found, 32 Illegal drive number, 33 No device space available, 34 Load file format error, 35 Memory fault, 36 Attempted to load read only memory, 37 Illegal access attempted to protected file, 38 File not open, 39 Device in use, 40 Protected system device, 41 File already open, 42 Logical record length open fault, 43 SVC parameter error, 44 Parameter error, 45 to 62 Unknown error code, 63 Extended error, HL = X'xxxx'. They match the TRM's list but for 35 and 36, which it does not list, and 42, which it calls LRL open fault. Every message but the extended error's ends with a space before its 0DH, in the program's buffer too (the line of error 63 ends with its quote and keeps its two asterisk signs in the buffer as well); TED, which takes the message into its buffer, steps back from the 0DH to that space and marks it as the last character.
The library commands of the DOS all call @ERROR with bits 6 and 7 set (the short message and a return), so the long display is seen only from a program that leaves bit 6 clear (the TRM's own sample programs set it) or with SFLAG$ bit 6 set, which no command of the DOS sets. With CFLAG$ bit 7 the message is always the short one, even with SFLAG$ bit 6, and SYS4 resets the bit after the call, so each call that wants the buffer must set it again; with CFLAG$ bit 6 set too, @ERROR leaves before that and bit 7 stays. The file line is taken from JDCB$ (0024H), the FCB of the last file SVC, whatever the error: after an error that has nothing to do with a file (35, 43 or 44, say) it describes the FCB of the last file SVC: its drive and DEC while it is open, and for any FCB with bit 7 clear, a closed one too, a false device name made of its seventh and eighth characters (B30); and a file specification that was typed with a password shows the password. A specification with an exclamation mark, which @FSPEC keeps in the FCB, gives Unknown FCB/DCB.
@ERROR returns (bit 7 set) through 1A77H in RST28 with Register Pairs BC, DE and HL as the program had them and Register A holding the error number as adjusted, with the S flag set and NZ: the TRM's Success always does not mean Register A = 0. Request 86H only loads SYS4 (nothing sends it); requests A6H to F6H are taken as @ERROR too, although no stub pushes an error number for them. The source's comment at ERR2A still says that a number above 43 becomes 44: the code makes it 45.
There are no hidden instructions. Six operands are changed while SYS4 runs: 1F24H (the program's return address), 1F46H (its Register Pair HL), 1FBFH (the way back, 1A77H), 1FF2H (the target of the device name, B27), 205EH (the last SVC) and 2072H (its return address). SYS4 also writes into its own texts: the hex of the extended error (20BDH), the device name (20EBH, 213AH), the file specification (20F5H on), the drive and DEC of an open FCB (211DH, 2124H) and the Last SVC line (2158H, 216CH). LILBUF (2172H-2176H) is not loaded.
Bugs (listed on the LS-DOS reference page): B25, for error 63 in the long form the header with the return address is built in SBUFF$ but only the line in SYS4 is shown, so the header is lost (the file and Last SVC lines are left out on purpose) (1F61H); B26, a test of bit 6 of Register C, which the source comments as Extended error?, can never be true because the number was masked to bits 5-0, so the two asterisk signs are always written (1F31H, no effect); B27, DSPC2 changes the target of the device name store to the line Device = for good, so a later Open DCB line in the same load of SYS4 shows the old name (200BH, latent); B28, a file text of 24 characters without an end puts its 0DH over the first letter of Open FCB (2031H, latent); B29, errors 41 and 42 are marked as errors of an unopened specification, but SYS2 returns them with the FCB open, so their file line is always Unknown FCB/DCB (1FCBH); B30, the open FCB line takes every FCB with bit 7 clear as a device, so a closed FCB or a specification not opened gives Open DCB with its seventh and eighth characters as the device name (1FDBH).
Variables
Memory Used by SYS4/SYS
| Address Size | Contents |
|---|---|
| 000BH-000CH 2 bytes | SVCRET$ The address the last SVC before @ERROR returned to (SVCUSER does not store it for SVC 26), copied for the Last SVC line (1ECBH). |
| 000DH 1 byte | LSVC$ The number of that SVC, copied for the Last SVC line (1EB3H). |
| 0024H-0025H 2 bytes | JDCB$ The FCB or DCB of the last call of CKOPEN@ or LNKFCB@, read for the file line (1FC6H). |
| 006CH 1 byte | CFLAG$ Bit 6 no display (1EE1H); bit 7 the short message to the program's buffer at Register Pair DE, tested and reset (1EE6H, 1F5DH, 1FA7H; not reset when bit 6 is set). |
| 007CH 1 byte | SFLAG$ Bit 6, extended error messages wanted: clears bit 6 of the error number (1ED2H). |
| 1D00H-1DFFH 256 bytes | SBUFF$ Where the long header and the message are built and shown from (1EEAH, 1FABH). |
| 1F24H-1F25H 2 bytes | USRET operand The return address of the program's RST 28H (1EC4H). |
| 1F46H-1F47H 2 bytes | EXTEND operand The program's Register Pair HL, shown for error 63 (1EBAH). |
| 1FBFH-1FC0H 2 bytes | ERR7 operand 1A77H, the return into RST28 (1EBEH). |
| 1FF2H-1FF3H 2 bytes | DSPC1A operand Where DSPC1 stores the device name: 213AH in the file, 20EBH once DSPC2 has run (200BH). |
| 205EH 1 byte | SVSVC operand The number of the last SVC (1EB6H). |
| 2072H-2073H 2 bytes | SVRET operand The address the last SVC returned to (1ECEH). |
| 20BDH-20C0H 4 bytes | EXT$ERR+26 The program's Register Pair HL in hex (1F4BH). |
| 20EBH-20ECH 2 bytes | DEV$NAM The device name of the line Device = (1FF0H after 200BH). |
| 20F5H-210DH 25 bytes | FILE$EQ+7 The file specification from the FCB and its 0DH (202EH, 2054H). |
| 211DH, 2124H-2125H 3 bytes | OPN$FCB+16, OPN$FCB+23 The drive digit and the DEC in hex of an open FCB (2043H, 204AH). |
| 213AH-213BH 2 bytes | OPN$DCB+18 The device name of an open DCB (1FF0H). |
| 2158H-215BH 4 bytes | SVC$NUM+11 The last SVC number in decimal and 03H (2068H, 206DH). |
| 216CH-216FH 4 bytes | SVC$RET+16 The return address of the last SVC in hex (2074H). |
| 2172H-2176H 5 bytes | LILBUF Not loaded: the SVC number in five decimal characters from @HEXDEC (2062H). |
| 23FEH-23FFH 2 bytes | Overlay length 04DDH, the length of SYS4 read by SYSTEM (SYSRES). |
Routines of Other Files Called
| Address | Routine |
|---|---|
| 0500H | @LOGOT (BOOT/SYS): shows a line and writes it to the job log, which @LOGER skips when JL is NIL (1F62H, 1FAEH, 2057H, 207AH, 2080H). |
| 06F6H | @HEXDEC (BOOT/SYS): the SVC number in decimal (2062H). |
| 07BDH, 07C2H | @HEX16 and @HEX8 (BOOT/SYS): a word or a byte in hex (1F26H, 1F4BH, 2074H; 204AH). |
| 1A77H | The end of RST28 (SYS0/SYS): restores @DBGHK and returns to the program (1FBEH). |
| 1B08H | @ABORT (SYS0/SYS): ends the program with the return code FFFFH (1FC1H). |
Disassembly
1E00H - SYS4: the Entry and the Sentence Table
SYS4/SYS is the system error dictionary. CKMOD@ (1A7FH on the SYS0/SYS page) reads it into 1E00H whenever an SVC asks for overlay 6 and it is not already resident, and RST28 calls 1E00H with the request in Register A: 96H from the @ERROR stub at 1B0FH. The entry jumps over the sentence table: one list of word numbers for each error from 0 to 45, each byte the number of a word of the dictionary at 21A6H in its bits 5-0, the last byte of a list with bit 7 set. Bit 6 of the last byte tells DSPSPEC (1FC4H) where the long display finds the file or device of the error: set (C0H) for the errors that come from a specification not yet opened, where the FCB still holds the text; clear (80H) for the others, where the FCB or DCB is open. CODTAB (2178H) holds the low byte of each list; the source requires the whole table to lie in page 1EH.
1EAFH - BEGIN: @ERROR Takes Its Arguments
A program calls @ERROR (SVC 26) with the error number in Register C, bit 6 set for the short display and bit 7 set to be given control back. The SVC dispatcher stores neither LSVC$ nor SVCRET$ for SVC 26 (1A45H), so they still name the SVC before it; it hands the number over in Register A to the stub at 1B0FH, which pushes it and sends request 96H. RST28 drops the stub's own return address, so on entry the stack holds RST28's return address 1A77H, the pushed error number and the return address of the program's RST 28H. BEGIN plants these addresses, the caller's Register Pair HL (the value an extended error 63 shows) and the last SVC into the operands that use them, and saves Register Pairs HL, DE and BC. SFLAG$ bit 6 (extended messages wanted) cancels bit 6 of the number; CFLAG$ bit 6 suppresses all display and CFLAG$ bit 7 sends the short message to the program's buffer at Register Pair DE instead.
1EEFH - ERR0: the User Buffer, and the Header of the Long Display
With CFLAG$ bit 7 the message always goes to the program's buffer in the short form, whatever bit 6 of the number and SFLAG$ say. For the long form (bit 6 of the adjusted number clear) the first line is built in SBUFF$: a line feed, two asterisk signs, Error code = and the number in two decimal digits, then Returns to X' and the return address of the program's RST 28H in hex; the next line starts with two asterisks and a space, and the message itself follows. A test that the source comments as Extended error? looks at bit 6 of a number already masked to bits 5-0, so the two asterisk signs are always written (B26); for error 63 the header is never shown at all (B25).
1F3FH - ERR2: Error 63, the Extended Error
Error 63 has no sentence: its message is the line Extended error, HL = X'xxxx' after two asterisk signs, at 20A3H, with the program's Register Pair HL written into it in hex. The line is copied to Register Pair DE (SBUFF$, after the long header if there is one, or the program's buffer), but what is shown is the line at 20A3H itself, so the long header built in SBUFF$ never reaches the display (B25). The file line and the Last SVC line are left out on purpose: the source handles error 63 alone (Do extended error only) and goes straight to ERR6A.
1F67H - ERR2A: the Message Built from the Dictionary
An error number above 45 becomes 45 (Unknown error code); the source's comment still says 43 and 44. CODTAB gives the low byte of the sentence, and for each word number of the sentence LP1 counts word endings (bit 7) through the dictionary from 21A6H, LP2 copies the word with bit 7 cleared and a space after it. The first character of the message is made a capital (RES 5), the message ends with 0DH after the trailing space, and unless CFLAG$ bit 7 sent it to the program's buffer it is shown and logged by @LOGOT from SBUFF$, header and all. In the long form DSPSPEC then adds the file or device line and the Last SVC line.
1FB9H - ERR6A: Back to the Program, or @ABORT
Every path of @ERROR ends here. The program's Register Pairs BC, DE and HL are restored and Register A holds the error number as adjusted (bit 6 cleared by SFLAG$ bit 6, set by CFLAG$ bit 7). With bit 7 of the number set, ERR7 jumps to 1A77H in RST28, which puts back the @DBGHK byte and returns to the instruction after the program's RST 28H with the S flag set and NZ; the TRM's Success always does not mean Register A = 0. With bit 7 clear the program is ended through @ABORT, which gives SYS1 the return code FFFFH.
1FC4H - DSPSPEC: the File or Device of the Error
DSPSPEC names what the error happened to, from the FCB or DCB of the last file SVC (JDCB$, set by CKOPEN@ and LNKFCB@), whatever the error is. Bit 6 of the sentence's last byte chooses how it reads it. Clear: the FCB is taken as open; a file (FCB+0 bit 7) gives Open FCB, Drive=d, DEC=nn from FCB+6 and FCB+7; any other FCB is taken as a device FCB (10H, from @OPEN of a device) and gives Open DCB, Device= and the asterisk sign with FCB+6 and FCB+7 as the name, so the text of a closed FCB or of a specification not opened gives its seventh and eighth characters as a device (B30). Set: the FCB still holds the specification as text; a device (asterisk sign first) gives Device = and the name, a file File = and its specification as @FSPEC stored it (in capitals), up to 24 characters of the characters CHKASC accepts. Anything that does not fit gives Unknown FCB/DCB. Errors 41 and 42 have bit 6 set but leave the FCB open, so they always give Unknown FCB/DCB (B29). DSPC2 changes the target of the device name store for good (B27), and a 24 character text puts its 0DH over the first letter of the next message (B28).
2038H - RCVSPEC: the Open FCB Line, and the Last SVC Line
For an open file the line is Open FCB, Drive=d, DEC=nn, the drive as a digit 0 to 7 and the DEC in hex. RSPC5 ends the line built with 0DH and RSPC6 shows it with @LOGOT. Every path of DSPSPEC then shows the last SVC: Last SVC = and its number in decimal (LSVC$, the last SVC before @ERROR), and on the same line , Returned to X' and the address that SVC returned to (SVCRET$), in two calls of @LOGOT. The job log gets both parts on one line, each after a time stamp of its own, because the first part ends with 03H.
2083H - CHKASC and EDEC
CHKASC accepts the characters of a file specification as DSPSPEC wants them: 2EH to 3AH (the period, the slash, the digits and the colon) and the capitals A to Z, with Carry clear; anything else returns Carry. EDEC copies the digits of a number written by @HEXDEC, passing over its leading spaces, up to the 00H that follows LILBUF.
20A3H - The Texts of the Display
The fixed parts of the lines of @ERROR, with the places that SYS4 fills in: the hex of the extended error, the error number and the return address of the long header (written in SBUFF$, not here), the device name, the file specification, the drive and the DEC of an open FCB, the device of an open DCB, and the SVC number and return address of the Last SVC line. A 0DH ends a line; 03H ends a part after which the cursor stays on the line. What SYS4 writes into these texts stays there while SYS4 is in the overlay area.
2178H - CODTAB: Where Each Sentence Starts
One byte for each error number from 0 to 45: the low byte of its sentence in page 1EH. ERR3 (1F6EH) adds the error number to 2178H and puts 1EH in front of the byte it finds there.
21A6H - WORDS: the Dictionary
The 58 words that the sentences are made of, numbered from 1, each ending with its last character's bit 7 set; the entry 0 before them only gives the count a start. LP1 (1F7DH) finds word n by counting n endings from 21A6H, so a word is found in a time that grows with its number. Three words are used by no sentence: 3 (o, which the source calls an extra word), 36 (y) and 55 (or).