TRS-80 DOS - VTOS v4.0.2 for the Model I - SYS1/SYS Disassembled

SYS1/SYS

Other Navigation

VTOS 4.0 SYS1/SYS Disassembly - Command Line Interpreter (Model I)

SYS1/SYS is the command line interpreter overlay for VTOS 4.0. It is loaded on demand by the RST 28H overlay dispatcher whenever the system needs to accept user input or process a DOS command. SYS1 loads into the overlay area at 4E00H-51FFH and provides six request codes (10H-70H) that handle different phases of command processing: displaying the "VTOS READY" prompt, accepting keyboard input, interpreting commands against the library command table, extracting filespecs, adding default extensions, and parsing command parameters.

The module is organized around a central SVC request dispatcher at 4E00H that examines bits 4-6 of Register A to route execution to the appropriate handler. Request codes 10H and 20H initialize the stack and display the DOS READY prompt; request code 30H copies a command string into the command buffer and interprets it; request code 40H extracts a filespec (NAME/EXT.PASSWORD:DRIVE) from the command line; request code 50H inserts a default "/CMD" extension if none is present; request code 60H parses parenthesized parameters after a filename; and request code 70H is the core command interpreter entry that works with request codes 10H/20H.

The command table at 4EADH contains 36 alphabetically-sorted entries, each 8 bytes: a 6-character space-padded command name followed by a 2-byte handler value. The handler value is loaded into Register Pair DE. If the high byte (D) has bit 7 set, the low byte (E) is a SYS6 overlay command index passed via RST 28H with SVC code 88H. If bit 7 is clear, DE is a direct address and execution transfers there via a PUSH DE / RET NC sequence. The only command that uses a direct address is BOOT (handler 4EA9H, which executes a HALT instruction to reset the system). All other 35 commands dispatch through the SYS6 overlay mechanism.

The command table search routine at 50BCH performs a linear scan of 8-byte entries, comparing the first byte, then doing a full 6-byte comparison on match. It returns the matched entry's handler value in DE and the entry index in C. A second, smaller table at 5021H contains parameter keywords (TO, ON, OVER, USING) used during parameter parsing. The filespec parser at 4FCEH handles the full VTOS filename format including the optional password and drive specifier fields. The parameter parser at 510FH supports decimal numbers, hexadecimal numbers (X'nn' format), quoted strings, and YES/NO/ON/OFF boolean values.

Request Codes

Major Routines

Library Commands (36 total)

Cross-Reference Notes

SYS1 calls into SYS0 resident routines extensively: 4467H (display message), 447BH (display message with continuation), 447EH (display with CONFIG/SYS), 4433H (load and execute program), 4030H (error exit to DOS READY), 402DH (DOS READY SVC). It also uses ROM routines at 0040H (line input with editing). The command table search at 50BCH is called both for the main command table at 4EADH and the parameter keyword table at 5021H. When a command is not found in either table, SYS1 appends "/CMD" to the command name and attempts to load it as an external program via 4433H (JP 4CCBH, load and execute).

4E00H - SVC Request Dispatcher

Entry point for SYS1/SYS. Register A contains the SVC code from the RST 28H overlay dispatcher. The request code is encoded in bits 4-6 (masked with 70H). Each request code routes to a different handler: 10H/20H = DOS READY prompt and input, 30H = interpret command from buffer, 40H = extract filespec, 50H = add default extension, 60H = parse parameters, 70H = command interpreter core. If the request code does not match any handler, execution returns to the caller via RET NZ.

4E20H - Request 30H: Copy and Interpret Command

Copies a command string from the address in HL to the DOS command buffer at 4318H (up to 63 characters), appends a 03H terminator, and falls through to the command interpreter at 4E59H. This request is used when a command string has been constructed in memory (e.g., from an AUTO procedure or CHAIN command) and needs to be interpreted.

4E2FH - "WHAT?" Error Handler

Displays the "WHAT?" error message when an unrecognized command is entered or when the BREAK key is pressed during command input. After displaying the message, jumps to the error exit at 4030H which returns to DOS READY.

4E38H - Request 10H/20H: DOS READY Prompt and Input

The primary user interaction handler. Reinitializes the system stack to 41E0H, enables interrupts, sets the BREAK key handler state based on the system mode flags (bit 0 of 430FH controls whether BREAK triggers DEBUG), displays the "VTOS READY" prompt, and accepts a line of keyboard input into the command buffer at 4318H. If the BREAK key is pressed during input (Carry flag set from ROM routine 0040H), displays "WHAT?" and re-prompts. Otherwise, falls through to the command interpreter.

4E5CH - Command Interpreter Core

The central command interpretation logic. Pushes 402DH (DOS READY address) onto the stack as a safety net return address. Examines the first character of the command: if it is a period (2EH), handles re-entry mode; if it is an exclamation mark (21H), treats the command as a direct SVC code. Otherwise, copies the command to the system DCB at 4480H via the filespec extractor (Request 40H), searches the SYS1 command table at 4EA5H, and if not found, searches the SYS6 parameter table. If still not found, appends "/CMD" and attempts to load the command as a program file.

4E8EH - Period (.) Re-entry Command

Handles the period (.) command, which provides a re-entry or continuation mechanism. Tests bit 5 of the system mode flags at 430FH. If bit 5 is set (a previous execution context exists to return to), returns to the caller via RET. If bit 5 is clear, re-prompts for a new command.

4E96H - Command Dispatch

Dispatches the matched command. Called after the table search at 50BCH finds a match. Register Pair DE contains the 2-byte handler value from the table entry. If bit 7 of D is clear, DE is a direct address and execution jumps there. If bit 7 of D is set, E contains the SYS6 overlay command index, and the overlay is loaded via RST 28H with SVC code 88H.

4EA5H - SYS6 Return Handler and Command Table

The bytes at 4EA5H-4EACH serve a dual purpose. As code, they execute after RST 28H returns from SYS6 at 4EA4H: LD C,A saves the return code, LD HL,4020H loads the cursor position, and HALT resets the system. As data, the first byte (4FH = 'O') acts as a dummy command table entry that never matches any real command (no VTOS command starts with 'O'), so the table search at 50BCH always skips past it. The real command table begins at 4EADH with 36 entries of 8 bytes each.

4EADH - Library Command Table

The library command table containing 36 entries, each 8 bytes: 6 bytes of space-padded ASCII command name followed by a 2-byte handler value (little-endian). The handler value is loaded into DE by the table search routine at 50BCH. If the high byte has bit 7 set (80H), the low byte is a SYS6 command index dispatched via RST 28H with A=88H. If bit 7 is clear, the value is a direct address jumped to via the PUSH DE / RET NC mechanism. The table is sorted alphabetically and terminated by a 00H byte at 4FCDH. The only direct-address command is BOOT (handler 4EA9H); all others dispatch through SYS6.

4FCEH - Request 40H: Filespec Extractor

Parses a VTOS-format filespec from the command line at (HL) and stores it into the DCB at (DE). The full format is: NAME/EXT.PASSWORD:DRIVE, where NAME is up to 8 characters, EXT is up to 3 characters, PASSWORD is up to 8 characters, and DRIVE is 1 character. Each section is optional and delimited by the appropriate separator (/ . :). The parsed result is terminated with 03H. After parsing, checks the result against the parameter keyword table at 5021H; if the parsed name matches a keyword (TO, ON, OVER, USING), re-enters the extractor to search for a SYS6 handler. The ! prefix (exclamation mark) followed by asterisk and 2 hex digits is handled as a direct SVC code. Returns with Z flag set on success, NZ on failure.

5021H - Parameter Keyword Table

A small table of 4 parameter keywords used by the filespec extractor to detect and skip keyword tokens that appear in command lines. Each entry is 8 bytes: 6-byte space-padded keyword name followed by 2 zero bytes (no handler - keywords are just consumed, not dispatched). The table is searched by the same 50BCH routine used for the command table.

5042H - Request 50H: Add Default Extension

Scans the filename in the DCB at (DE) for a / extension separator. If one is found, the filename already has an extension and no modification is needed. If no / is found within 9 characters, a 4-byte hole is created in the string via LDDR block move, and "/CMD" (or the extension string pointed to by HL) is inserted. This allows commands typed without an extension (e.g., "MYFILE") to be automatically expanded to "MYFILE/CMD".

5076H - Filename Character Reader

Reads valid filename characters from the command line at (HL), converts lowercase to uppercase, and stores them in the DCB at (DE). Entry at 5076H reads up to 8 characters; entry at 5078H reads up to B characters. Valid characters are digits (30H-39H) and uppercase letters (41H-5AH). Lowercase letters (61H-7AH) are converted to uppercase by subtracting 20H. The routine terminates the stored string with 03H and returns the delimiter character in A. Uses self-modifying code at 50B8H to track whether any characters were stored (Z flag = no valid chars stored = error, NZ = at least one char stored).

50BCH - Command/Keyword Table Search

Searches a table of 8-byte entries for a match with the string at (DE). Register Pair BC points to the table on entry. Each entry has a 6-byte name followed by a 2-byte handler value. The search is linear: compare the first byte, if it matches, compare the remaining 5 bytes. If all 6 match, load the handler value from offset 6-7 into DE and return with Z set. If no match, advance by 8 bytes and try the next entry. The table is terminated by a 00H byte. Returns NZ (A=1) if the entry is not found.

510FH - Request 60H: Parameter Parser

Parses command parameters that follow a filename in the command line. Parameters are enclosed in parentheses and separated by commas: (KEYWORD=VALUE,KEYWORD=VALUE,...). The value can be a decimal number, a hex number (prefixed with X'), a quoted string (enclosed in double quotes), or a YES/NO/ON/OFF boolean. The parser uses the keyword table at 5021H to identify known keywords and calls specialized value parsers at 5181H (YES/NO), 51A6H (decimal), and 51C0H (hex).

5181H - YES/NO Boolean Parser

Parses a boolean parameter value. Recognizes Y, YES, N, NO, ON, and OFF. Returns BC=FFFFH for true values (Y, YES) and BC=0000H for false values (N, NO, OFF, ON treated as a special case). Scans characters with case-insensitive comparison (RES 5,A converts to uppercase). Returns Z on success, NZ on unrecognized value.

51A6H - Decimal Number Parser

Parses a decimal number string from (HL) and returns the 16-bit result in Register Pair BC. Uses the standard multiply-by-10-and-add algorithm: for each digit, compute BC = BC * 10 + digit. The multiply-by-10 is implemented as BC * 2 * 2 + BC (= BC * 5), then double the result (BC * 10). Stops on the first non-digit character. Returns with Carry set if the first character is not a digit, or NC on success.

51C0H - Hexadecimal Number Parser

Parses a hexadecimal number in X'nnnn' format from (HL) and returns the 16-bit result in Register Pair BC. On entry, HL points to the opening single quote (the 'X' prefix was already consumed by the caller at 5161H). Each hex digit is converted from ASCII to binary (0-9 via SUB 30H, A-F via additional SUB 07H) and shifted into BC using four left shifts (multiply by 16). The closing single quote terminates the parse. Returns Z on success, NZ on failure.

51EBH - String Data

Constant string data used by the SYS1 command interpreter. The default file extension "CMD" is referenced when no extension is specified on the command line. The "VTOS READY" prompt is displayed at the start of each command input cycle. The "WHAT?" message is displayed for unrecognized commands.