TRS-80 DOS - LDOS 5.3.1 for the Model I - SYS4/SYS Disassembled

SYS4/SYS

Other Navigation

LDOS 5.3.1 SYS4/SYS Disassembly - System Error Dictionary (Model I)

SYS4/SYS is the LDOS system error dictionary. It is the overlay that services the @ERROR system call, reached through RST 28H with request code 96H in the accumulator. Its job is to turn a numeric error code into readable English text such as "Directory read error" or "File not in directory", frame that text as *** Error code = NN, message ***, and display it. If SYS4/SYS is purged from a working system disk, the resident kernel has no message text to draw on and every system error instead prints the terse fallback "SYS ERROR". Because the whole overlay occupies only a single granule it is recommended that it be kept.

To fit 46 distinct messages into one granule, LDOS does not store the messages as literal strings. Instead it stores a dictionary of 56 English words once (5088H-51AEH), a compact per-error definition table that lists each message as a short sequence of word numbers (4E03H-4EADH), and a one-byte-per-error index (505AH-5087H) that locates each definition. The display routine walks the word-number list for the requested error, copies each dictionary word into a work buffer with a separating space, and so reconstructs the full sentence on demand. Every word in the dictionary is stored with the high bit (80H) set on its final character, which marks the end of that word.

Beyond the message text, the routine optionally appends the identity of the offending object - either <Device=*XX> for a logical device or <File=NAME/EXT:D> for a disk file (read from the directory) - and a Referenced at X'NNNN' line giving the address from which the failing service was called. Option bits in the caller's accumulator select how much of this framing is produced and whether control returns to the caller or aborts to DOS. Because SYS4/SYS is a transient overlay it loads and runs at 4E00H and reaches the resident kernel (SYS0/SYS) only through fixed entry points.

Memory and Variable Map

Major Routines

Cross-Reference Notes

SYS4/SYS is invoked by the resident RST 28H supervisor dispatcher in SYS0/SYS when a caller issues the @ERROR request (code 96H). It calls the following resident SYS0/SYS entry points: 4B10H (DIRRD, read a directory record), 447BH (display a carriage-return-terminated string), 4D76H (store the value in register pair DE as four hexadecimal ASCII digits), and 4030H (@ABORT, return to DOS on the no-return path). It reads the resident variables 430AH (address of the current file/device control block), 430CH (address from which the failing service was called), 430FH (system flag byte), and 4758H (SYS1 status byte), and assembles its output in the resident shared buffer at 4200H.

4E00H - Overlay Entry Point

SYS4/SYS is loaded to 4E00H and entered here. The first three bytes are a jump over the read-only error-definition table that follows, landing on the executable @ERROR code at 4EAEH.

4E03H - Error Message Definition Table

Data, not code. One entry per error code. Each byte holds a dictionary word number in bits 0-5; bit 7 set marks the final word of that message. The decompression loop at 4F02H expands these lists into text. (The disassembler mis-reads these data bytes as instructions; they are shown here as DEFB data with the decoded message.)

4EAEH - @ERROR Service Entry, Option Decode and Display Gating

Entry from the JP at 4E00H. On entry the accumulator holds the RST 28H request code (96H). The caller's own accumulator - the error number in bits 0-5, with option bits 6 and 7 - was saved on the stack by the resident dispatcher and is recovered here. The resident SYS1 status byte at 4758H can force message-only mode or suppress the display entirely.

4EE4H - Error-Code Prefix Builder

Reached only when message-only mode is off. Copies the '*** Error code =' literal into the work buffer, then converts the error number to two decimal digits followed by a comma and a space, producing '*** Error code =NN, '.

4F02H - Message Decompression Loop

Reached with register C holding the error number and register pair DE pointing at the buffer position for the message text. Looks up the error's definition, then for each word number copies the matching dictionary word into the buffer followed by a space.

4F33H - Frame and Display the Message

The message text is now in the buffer with a trailing space. This block capitalizes the first letter, optionally appends the trailing '***', terminates with a carriage return, and displays the buffer through the resident string routine at 447BH - unless SYS1 status bit 7 suppressed the display.

4F69H - Device / File Specification Builder

Called when the full framing is wanted. Uses the resident pointer at 430AH to the control block of the object that failed. For a logical device it patches the '*XX' name into the Device template; for an open disk file it reads the directory record and builds NAME/EXT:D into the File template. Then it appends the 'Referenced at' line.

4FF7H - Referenced-At Address Line

Displays the device or file specification, then converts the saved caller address at 430CH to four hex digits and displays the 'Referenced at X'NNNN'' line before returning.

500DH - Message Template Literals

Data. The fixed text fragments the display code copies or fills in. Bytes shown are the raw literal; the 'NN', '*XX', 'NNNNNNNN/EEE:D' and 'NNNN' fields are overwritten at run time. (The disassembler mis-reads these as instructions.)

505AH - Error-Code Index Table

Data. One byte per error code (0 through 45). Each byte is the offset within the 4E00H page at which that error's definition begins (base 4E00H). The decompression loop indexes this table with the error number at 4F09H.

5088H - Compressed Word Dictionary

Data. The 56 English words shared by all messages. Each word's final character carries bit 7 (80H) set to mark the end of the word; the decompression loop uses that marker to count and copy words. (The disassembler mis-reads these as instructions.)