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

SYS1/SYS

Other Navigation

LDOS 5.3.1 SYS1/SYS Disassembly - DOS Command Interpreter (Model I)

SYS1/SYS is the LDOS command interpreter. On a Model I running LDOS 5.3.1 it is not resident: it is a system overlay that the SYS0 resident supervisor loads into the transient region at 4E00H whenever a command must be read and dispatched. Control reaches it through the RST 28H supervisor mechanism (ROM 0028H vectors to 400CH which jumps to the resident dispatcher at 4BCDH); that dispatcher reads the matching SYS file from the directory, loads it at 4E00H, patches its own self-modified CALL with the overlay entry, and calls 4E00H with the request code in Register A.

The entry at 4E00H masks Register A with 70H to isolate a three-bit sub-function selector and branches accordingly. Selector 10H is the interactive command level: it re-establishes the command stack, arms or disarms the DEBUG trap according to a system-configuration bit, displays the LDOS Ready prompt, and reads a command line from the keyboard through the ROM $KBLINE routine at 0040H. The first character of the buffered line is then examined: an exclamation-point force-execute prefix and a leading-period comment marker are handled, the command word is parsed into a file specification, and it is matched against a built-in command-name table located later in this overlay. The built-in command names in that table are APPEND, ATTRIB, AUTO, BOOT, BUILD, CLS, COPY, CREATE, DATE, DEBUG, DEVICE, DIR, DO, DUMP, FILTER, FORMS, FREE, KILL, LIB, LINK, LIST, LOAD, MEMORY, PURGE, RENAME, RESET, ROUTE, RUN, SET, SETCOM, SPOOL, SYSTEM, TIME, TOF and VERIFY. When no built-in matches, the interpreter appends the default /CMD extension and transfers to the resident @RUN service at 4433H to load and execute the named program file.

This page documents the resident-patch fragment at 4BC9H and the command-processor entry, prompt, keyboard line input, parse, dispatch, break/abort and comment-line paths (4E00H through the RETurn at 4EA7H). The filespec parser at 4FD6H, the extension-append routine at 5048H, the selector-60H routine at 510EH, the command-name lookup at 50CBH, and the command-name and message data (4EBDH onward) are documented in the sections that follow in later portions of this disassembly.

Variable and Buffer List

Addresses in the 43xxH through 47xxH range are resident SYS0 system-area locations shared by every overlay (cross-referenced to the SYS0 page). Addresses at 4E7BH and above lie within this SYS1 overlay image.

Address Range Bytes	Purpose
4318H-4357H 64 bytes	Resident command-line input buffer. The caller's string (default path) or the keyboard line ($KBLINE) is placed here and terminated with 03H.
430FH 1 byte	Resident system configuration flags. Bit 7 enables the DEBUG single-step trap (read at 4E32H); bit 5 selects whether a leading-period comment line returns or loops for another line (read at 4EA0H).
4315H 1 byte	Resident DEBUG trap-vector opcode byte. Set to 0C3H (JP opcode, trap armed) or 00H (trap disarmed) at 4E3BH based on 430FH bit 7.
4480H 1 buffer	Resident parsed file-specification buffer. The command word is copied and validated into this buffer by the parser at 4FD6H.
4758H 1 byte	Resident command-processor status flags. Bit 1 marks caller-handled errors and gates the abort path (4E97H); bit 2 marks that a line is being entered (4E47H); bit 4 requests parse-only without executing the file (4E8EH).
4E7BH 1 byte	Self-modifying operand of the LD A,nn at 4E7AH. Written at 4E66H with (first command character minus 21H); zero indicates the exclamation-point force-execute prefix.
4EBDH-... 8 bytes/entry	Built-in command-name table. Each entry is a six-character, space-padded command name followed by a two-byte dispatch word: a one-byte command code (offset +6) and a one-byte dispatch flag (offset +7, bit 7 set for a library call, bit 6 selecting Library A or B). Searched by 50CBH with a stride of 8.
51EAH-51ECH 3 bytes	Default file extension string CMD (no terminator), appended to the file specification by 5048H.
51EDH-51F8H 12 bytes	Command prompt string: 0AH line feed, the text LDOS Ready, and 0DH carriage return. Displayed by @DSPLY at 4E41H.

Major Routine List

Address	Name and Purpose
4BC9H	Resident Patch Two bytes (F9H, 03H) deposited by the overlay load records into resident low RAM immediately below the RST 28H dispatcher, falling into the resident disk-operation executor at 4BCBH. Entry: reached in the resident supervisor context. Exit: falls into 4BCBH.
4E00H	Command Processor Entry and Sub-Function Dispatch Isolates the sub-function selector from Register A and branches; the default path buffers a caller string to 4318H. Entry: Register A = RST 28H request code. Exit: to the selected sub-function, or RET on selector 00H.
4E2EH	Interactive Prompt and Line Input Re-establishes the command stack, arms/disarms the DEBUG trap, displays LDOS Ready, and reads a command line via ROM $KBLINE. Entry: selector 10H. Exit: falls into the parser at 4E5CH, or to the abort path on BREAK.
4E5CH	Command-Line Parse and Dispatch Scans the line, handles the exclamation-point prefix, parses the file specification, searches the built-in command table, and otherwise appends /CMD and runs the file. Entry: HL points at the command line. Exit: JP @RUN (4433H), RET, or the abort path.
4E97H	Break and Abort Path Returns quietly when status bit 1 is set, otherwise jumps to the resident @ABORT handler. Entry: BREAK, filespec error, or wildcard command word. Exit: RET or JP @ABORT (4030H).
4EA0H	Comment-Line Handling Handles a command line beginning with a period; loops back for another line or returns based on configuration bit 5. Entry: first character is a period. Exit: LOOP to 4E44H or RET.

One consequence of where this overlay sits deserves stating, because it governs what an address in the range 4E00H-51F8H means at any given moment. SYS1/SYS occupies 4E00H through 51F8H, and the Library A and Library B command overlays held in SYS6/SYS and SYS7/SYS are loaded to 5200H, immediately above it. Loading one of those command overlays therefore does not disturb this image: the parameter-list parser at 510EH, the decimal value parser at 51ABH, the hexadecimal value parser at 51C0H and the string area at 51EAH are all still in memory, and still callable, while a library command runs. That only holds until the command asks for a supervisor service of its own. Every other numbered overlay is loaded at 4E00H as well - SYS2/SYS for @OPEN, SYS3/SYS for @CLOSE, SYS4/SYS for @ERROR, SYS8/SYS for space allocation and the rest - and several of them run as high as 51FEH, so the first such request replaces this image completely, the two-byte length record at 4BC9H included. A command overlay that means to call into 4E00H-51F8H must do so before it opens a file or reports an error, and an address in that range appearing inside a command overlay is only SYS1/SYS if no other overlay has been loaded since.

Cross-Reference Notes

SYS1/SYS is invoked by the resident SYS0 RST 28H supervisor dispatcher (4BCDH) as an overlay loaded at 4E00H, and returns to it. It calls into the resident SYS0 system area for @DSPLY (4467H), the command-line hook vector (447EH), @RUN (4433H) and @ABORT (4030H), and pushes @EXIT (402DH) as a completion return; all of these are documented on the LDOS Model I SYS0/SYS page. Internal forward references (4FD6H, 5048H, 510EH, 50CBH) are resolved within this overlay in later sections. In the other direction, this image remains in memory beneath a command overlay loaded at 5200H and can be called into from there, but only until that command issues a request that loads another overlay over it; see the note on overlay lifetime above.

4BC9H - Overlay Load Block

Every LDOS overlay deposits a two-byte record into the padding area that precedes the resident RST 28H dispatcher in SYS0/SYS. The word records the length of the overlay image just loaded, which for SYS1/SYS is 03F9H, 1017 bytes, matching the span 4E00H through 51F8H. The disassembler renders the two bytes as instructions; they are data and are never executed.

4E00H - Command Processor Entry and Sub-Function Dispatch

SYS1 overlay entry point. The RST 28H supervisor loads this overlay and calls 4E00H with the request code in Register A; bits 4 through 6 select the sub-function and the low bits carry option flags.

4E2EH - Interactive Prompt: LDOS Ready and Line Input

Selector 10H entry. Re-establishes the command stack, arms or disarms the DEBUG trap, prints the LDOS Ready prompt, and reads a command line from the keyboard.

4E5CH - Command-Line Parse and Dispatch

Scans the buffered command line, isolates the command word, matches it against the built-in command-name table, and otherwise runs it as a program file.

4E97H - Break and Abort Path

Reached on BREAK during line input, a file-specification error, or a wildcard command word. Either returns quietly or aborts to the resident @ABORT handler depending on status bit 1.

4EA0H - Comment-Line Handling

Reached when the command line begins with a period. Loops back to read another line, or returns, based on system configuration bit 5.

4EA8H - Built-in Command Dispatch

Entered from 4E85H when the typed command matches a name in the command table. Register Pair DE holds the matched entry's two dispatch bytes (E = command code, D = dispatch flag). Bit 7 of the flag chooses a direct jump into this overlay versus a library call through RST 28H.

4EB6H - BOOT Command Handler

Direct-jump target for the BOOT command (dispatch word 4EB6H). Re-homes the disk and halts pending the system restart.

4EBDH - Command Name Table

The table of built-in DOS command names searched by the lookup routine at 50CBH. There are thirty-five eight-byte entries: a six-character, space-padded command name followed by a one-byte command code and a one-byte dispatch flag.

4FD6H - File Specification Parser

Selector 40H service. Parses a file specification at (HL) into the buffer at (DE), accepting name, /extension, .password and :drive fields, then checks the result against the connector-keyword table. Returns Register A = 00H (Z) on success or NZ on error.

5027H - Connector Keyword Table

Eight-byte entries searched at 5010H: a six-character, space-padded connector keyword followed by a two-byte handler pointer (4200H, the parameter work buffer). Terminated by a zero byte.

5048H - Append Default Extension

Selector 50H service. Scans the parsed file specification for an existing /extension; if none is present it inserts the default extension pointed to by HL (the string CMD at 51EAH). On entry HL points to the extension string and DE to the file specification.

5060H - Insert Default Extension

Reached when the file specification has no extension. Shifts the specification to open a four-byte gap and writes the / separator followed by the three-character default extension.

5079H - Scan Name Field

Copies one file-specification field from (HL) to (DE), uppercasing letters, honouring the field-width limit in Register B, and stopping at a terminator. Entry 5079H presets an eight-character field; entry 507BH uses the width already in Register B. The delimiter character is returned in Register A.

50BDH - Alphanumeric Classifier

Tests the character in Register A. Returns the CARRY FLAG clear when the character is a digit (0-9) or upper-case letter (A-Z), and set otherwise. Register A is preserved.

50CBH - Command and Keyword Table Search

Searches an eight-byte-entry table at (BC) for the word at (DE). On a match returns the Z FLAG set with Register Pair DE holding the entry's two-byte dispatch/handler word; on no match returns Register A = 01H (NZ). Used for the command table (4E82H), the connector-keyword table (5010H) and parameter keywords (5132H).

510EH - Parameter List Parser

Selector 60H service. Parses a parenthesised parameter list "(KEYWORD=value,...)" at (HL). Register Pair DE points to a parameter-keyword table whose entries carry the storage address for each value. Reads each keyword into the buffer at 4200H, looks it up, and stores the parsed value.

5157H - Parameter Value Parser

Parses the value after an =: a quoted string, a decimal number, an X'..' hexadecimal number, or a Yes/No/False option. Returns the value in Register Pair BC for storage at 5142H.

5188H - Yes / No / False Option Helper

Interprets an option value beginning with a letter: Y or ON gives true (Register Pair BC = 0FFFFH via 519DH), N or OFF or F gives false (BC = 0). Skips to the next delimiter afterward.

51ABH - Decimal Value Parser

Reads a run of decimal digits at (HL) into Register Pair BC, accumulating value times ten plus each digit.

51C0H - Hexadecimal Value Parser

Reads an X'..' hexadecimal constant at (HL) into Register Pair BC, accumulating value times sixteen plus each hex digit. Requires the value to be enclosed in single quotes.

51EAH - Default Extension and Prompt Strings

The literal strings used by the overlay: the default command extension and the interactive prompt.