TRS-80 DOS - VTOS 4.0.2 for the Model I - SYS4/SYS Disassembled
Page Customization
Page Index
SYS4/SYS
Other Navigation
Introduction/Summary
VTOS 4.0.2 SYS4/SYS Disassembly - Error Messages (Model I)
SYS4/SYS is the system overlay that shows error messages. A program, or the system itself, jumps or calls 4409H with an error code in Register A; SYS0/SYS's 44B0H pushes Register Pair AF and issues request 86H, and the request handler (4C31H) loads SYS4/SYS at 4E00H (directory entry code 06H). The manual calls it the system error dictionary; without it every error gives the form SYSTEM ERROR nn.
The file starts with a record of type 05H (the name SYS4), a record of type 1FH holding the copyright notice of Randolph Cook (1980) and four load blocks that fill 4E00H-51DDH, 990 bytes; the last record gives the transfer address 4E00H; one byte 03H follows it, which the loader never reads. The file carries no patch.
The Error Code
| Bits | Meaning |
|---|---|
| 5-0 | The error number, 00H-29H (the table below); a higher number shows the text of 29H, UNKNOWN ERROR CODE, with its own number. |
| 6 | Set: the text of the message alone. Clear: the long form. Bit 6 of the system flags 430FH set clears this bit, so that the long form is always given (4E0AH). |
| 7 | Set: return to the caller of 4409H with Register A = the code (bit 6 as used) after the message (through the request handler's 4C4BH). Clear: go to the abort exit 4030H, which shows VTOS READY (4E95H). |
Register Pairs BC, DE and HL are given back.
The Message
The message is put together in SYS0/SYS's sector buffer at 4200H and shown with 447BH, which also writes it, with the time in front, to the job log device JL when JL is not NIL. The text alone is the words of the message, each followed by a space, and 0DH. The long form starts on a new line with three asterisks, ERRCOD= and the error number as two decimal digits (05 for 5), a comma and a space, and ends with three asterisks:
*** ERRCOD=24, FILE NOT IN DIRECTORY ***
The long form then names the control block of the last file request, whose address SYS0/SYS keeps at 430AH (4E9CH), on a line of its own after 5 or 6 spaces: <FILE=NAME/EXT:d> from the directory record of an open file, <FILE=...> with the specification as typed for the errors marked in the table (the control block is not open then), or <DEVICE=*XX> for a device. A last line gives the address of the CALL that started that file request, from 430CH less 3: an address in SYS0/SYS or in the overlay that made the request (SYS2/SYS for an open, 4E69H; SYS3/SYS for a close; SYS10/SYS), not in the program:
REFERENCED AT X'48A4' (for a read through 4436H, whose 48A4H is the CALL 49EBH)
The bytes C3H, C5H and C6H in the texts are the space compression codes of the ROM's display driver (04A6H): C0H plus n is shown as n spaces.
How the Texts Are Kept
The 42 messages are made of 52 words. The table at 4F89H holds, for each error number, the low byte of its word list in 513EH-51DDH. Each byte of a list names a word by its number in bits 5-0 and has bit 7 set on the last byte; bit 6 of the last byte marks the errors whose control block holds the specification as typed. The table at 4FB1H gives the start of each word n at 4FB1H + 2n (from 4FB3H for word 1, since 4FB1H-4FB2H are the last two bytes of the table before), and a word ends where the next one starts, so the words at 5023H-513DH need no lengths and no separators. Words 03H, 14H and 24H have length 0 and no list names them.
The Messages
| Code | Text (the words; a mark after it: the file line shows the specification as typed) |
|---|---|
| 00H | NO ERROR |
| 01H | PARITY ERROR DURING HEADER READ |
| 02H | SEEK ERROR DURING READ |
| 03H | LOST DATA DURING READ |
| 04H | PARITY ERROR DURING READ |
| 05H | DATA RECORD NOT FOUND DURING READ |
| 06H | ATTEMPTED TO READ SYSTEM DATA RECORD |
| 07H | ATTEMPTED TO READ LOCKED/DELETED DATA RECORD |
| 08H | DEVICE NOT AVAILABLE (as typed) |
| 09H | PARITY ERROR DURING HEADER WRITE |
| 0AH | SEEK ERROR DURING WRITE |
| 0BH | LOST DATA DURING WRITE |
| 0CH | PARITY ERROR DURING WRITE |
| 0DH | DATA RECORD NOT FOUND DURING WRITE |
| 0EH | WRITE FAULT ON DISK DRIVE |
| 0FH | WRITE PROTECTED DISK |
| 10H | ILLEGAL LOGICAL FILE NUMBER |
| 11H | DIRECTORY READ ERROR |
| 12H | DIRECTORY WRITE ERROR |
| 13H | ILLEGAL FILE NAME (as typed) |
| 14H | GAT READ ERROR |
| 15H | GAT WRITE ERROR |
| 16H | HIT READ ERROR |
| 17H | HIT WRITE ERROR |
| 18H | FILE NOT IN DIRECTORY (as typed) |
| 19H | FILE ACCESS DENIED (as typed) |
| 1AH | FULL OR WRITE PROTECTED DISK (as typed) |
| 1BH | DISK SPACE FULL |
| 1CH | END OF FILE ENCOUNTERED |
| 1DH | RECORD NUMBER OUT OF RANGE |
| 1EH | DIRECTORY FULL - CAN'T EXTEND FILE |
| 1FH | PROGRAM NOT FOUND |
| 20H | ILLEGAL DRIVE NUMBER (as typed) |
| 21H | NO DEVICE SPACE AVAILABLE (as typed) |
| 22H | LOAD FILE FORMAT ERROR |
| 23H | MEMORY FAULT |
| 24H | ATTEMPTED TO LOAD READ ONLY MEMORY |
| 25H | ILLEGAL ACCESS ATTEMPTED TO PROTECTED FILE |
| 26H | FILE NOT OPEN (as typed) |
| 27H | DEVICE IN USE |
| 28H | PROTECTED SYSTEM DEVICE |
| 29H | UNKNOWN ERROR CODE |
Points to Note
The specification copied into the file line counts with Register B, which LD BC,0018H sets to 00H, so the copy stops only at 03H, 0DH or 256 characters (4ED1H). The line has room for 14 characters; a longer specification, which a password makes common, runs over the line REFERENCED AT at 4F72H. That line then shows the end of the specification (with exactly 15 characters, a blank line), and stays so for later messages while SYS4/SYS remains in memory, which is the case after a code with bit 7 set; with bit 7 clear the abort exit loads SYS1/SYS over it. A text with no 03H or 0DH in its first 256 bytes would be copied up to 5061H, over the tables at 4F89H-5022H.
The specification is shown as typed, so the file line shows the password, on the display and in the job log.
A file with no extension is shown with a slash and nothing after it, NAME/:d (4F00H); the read of its directory record is not tested (4EEAH).
The file line and the line REFERENCED AT name the last file request, which need not be the one that failed.
An error number above 29H shows UNKNOWN ERROR CODE, but ERRCOD shows the number given.
Memory Map
Load Areas
| Addresses Size | Contents |
|---|---|
| 4E00H-4E3DH 62 bytes | Entry The stack, the code adjusted by 430FH bit 6, the start of the long form with the decimal number. |
| 4E3EH-4E70H 51 bytes | The Words The word list of the error copied word by word to 4200H. |
| 4E71H-4E9BH 43 bytes | Show the Message The end of the message, 447BH, the return or the abort exit. |
| 4E9CH-4F40H 165 bytes | File or Device Line The control block of the last file request, the line REFERENCED AT. |
| 4F41H-4F88H 72 bytes | Texts The start of the long form and the three line templates. |
| 4F89H-4FB2H 42 bytes | Word List Table The low byte of each error's word list. |
| 4FB3H-5022H 112 bytes | Word Starts The start of each word 01H-37H and the end of 37H. |
| 5023H-513DH 283 bytes | The Words 52 words with no separators. |
| 513EH-51DDH 160 bytes | Word Lists One list for each error 00H-29H. |
Variables
Memory Outside the File
| Address Size | Contents |
|---|---|
| 4200H-42FFH 256 bytes | Sector Buffer of SYS0/SYS The message is put together here (4E13H); the directory sector of an open file is read here for the file line (4EEAH). |
| 430AH-430BH 2 bytes | Control Block of the Last File Request Stored by SYS0/SYS 49F1H; read at 4E9EH for the file or device line. |
| 430CH-430DH 2 bytes | Return Address of the Last File Request The address after its CALL 49EBH or 49E9H (SYS0/SYS 49EEH); less 3 it is shown after REFERENCED AT (4F2EH). |
| 430FH 1 byte | System Flags Bit 6 set: bit 6 of the error code is cleared, the long form is given (4E0AH). |
Operands Changed While Running
| Address Size | Contents |
|---|---|
| 4E97H-4E98H 2 bytes | Return into the Request Handler Operand of JP M,0000H at 4E96H: 4C4BH, taken from the stack at 4E01H. |
| 4F57H-4F58H 2 bytes | Device Letters The XX of the device line, written at 4EB5H. |
| 4F62H-4F71H 16 bytes | File Line The name, extension and drive or the specification as typed, then the closing bracket and 0DH (4EDEH-4F25H); a longer specification runs on into 4F72H. |
| 4F83H-4F86H 4 bytes | Address in Hex The address of the CALL that started the file request (4F38H). |
Outside Routines
| Address | Contents |
|---|---|
| 447BH | SYS0/SYS: display the text at Register Pair HL and write it to the job log (4E86H, 4F2BH, 4F3EH). |
| 4B10H | SYS0/SYS: read the directory sector of entry Register B on drive Register C into 4200H (4EEAH). |
| 4DE7H | SYS0/SYS: Register Pair DE as four hex digits at Register Pair HL (4F38H). |
| 4030H | SYS0/SYS: the abort exit, request A3H, VTOS READY (4E99H). |
| 4C4BH | SYS0/SYS: the request handler after the overlay's call: the BREAK byte put back, return to the caller of 4409H (4E96H). |
Disassembly
4E00H - Error Message Entry
SYS4/SYS is loaded at 4E00H by the request handler of SYS0/SYS for request 86H (bits 3-0 = 6, directory entry code 06H), which SYS0/SYS's 44B0H issues after a program jumps or calls 4409H with an error code in Register A. 44B0H pushes Register Pair AF before RST 28H, and the request handler calls the overlay from 4C48H, so the stack holds the return address 4C4BH, then the caller's Register Pair AF, then the address the caller of 4409H returns to when it called 4409H (after a jump, whatever the caller had on the stack). The code: bits 5-0 the error (00H-29H; higher numbers show the text of 29H), bit 6 set for the text alone, bit 7 set to return to the caller after the message instead of going to the abort exit 4030H.
4E3EH - The Words of the Message
Register C = the error number, Register B = 00H, Register Pair DE = the place in 4200H for the text. The byte of the error in the table at 4F89H is the low byte of its word list in 5100H-51FFH. Each byte of the list names a word: bits 5-0 the word's number n, whose start is the word at 4FB1H + 2n and whose end is the start of word n + 1; bit 6 of the list's last byte tells what the control block of the request holds (4E9CH); bit 7 is set on the last byte. Each word is copied with a space after it.
4E71H - Show the Message
The long form ends with three asterisks, and every message with 0DH; the text in 4200H is displayed and written to the job log through 447BH. The long form also shows the file or device of the request (4E9CH). Register Pair HL = the byte after the word list.
4E9CH - Show the File or Device
The long form names the file or device of the request: Index Register IX = the control block at (430AH), stored by SYS0/SYS's 49F1H at the start of each file request. Bit 6 of the last byte of the word list (Register Pair HL less one) is set for the errors met before a file is open (08H, 13H, 18H, 19H, 1AH, 20H, 21H, 26H): the control block then holds the specification as typed. When it is clear the block is open and its directory record gives the name, or it is a device route and bytes +06H-+07H give the device. The line is shown with 5 spaces (C5H) or 6 spaces (C6H) in front, then the line REFERENCED AT with the address of the CALL 49EBH or 49E9H that started the request, in SYS0/SYS or in the overlay that made it.
4F41H - Texts
The bytes C3H, C5H and C6H are space compression codes: the ROM's display driver (04A6H) shows a byte C0H plus n as n spaces.
4F89H - Word Lists of the Errors
One byte for each error number 00H-29H, the low byte of its word list in 5100H-51FFH (4E48H). The bytes of 28H and 29H, at 4FB1H-4FB2H, are also the place of the entry of word 0 in the table that follows, which no list names.
4FB3H - Starts of the Words
Two bytes for each word 01H-37H, the address of its first character; the entry of word n is at 4FB1H + 2n and the word ends where word n + 1 starts (4E57H-4E60H), so the entry at 5021H only gives the end of word 37H. Words 03H, 14H and 24H have length 0 and no list names them.
5023H - The Words
The characters of the words 01H-37H, one after another with nothing between them; a word is copied with a space after it (4E65H-4E6AH).
513EH - The Word Lists
The list of each error: one byte for each word, bits 5-0 the word number, bit 7 set on the last byte. Bit 6 of the last byte is set for the errors whose control block holds the specification as typed (4EA3H).