TRS-80 DOS - VTOS 4.0.2 - SYS7/SYS Disassembled

SYS7/SYS

Other Navigation

VTOS 4.0.2 SYS7/SYS Disassembly - Program Chaining Overlay (Model I)

SYS7/SYS is the program chaining overlay for VTOS 4.0 on the TRS-80 Model I. It occupies the standard overlay slot at 4E00H-51FFH and is loaded on demand by the SYS0 resident overlay dispatcher when an SVC code in the range 40H-4FH or 70H-7FH is issued. Its primary function is to allow a running program to pass control to another program or DOS command, optionally carrying a command-line argument string, while cleanly managing the DOS interrupt vectors and the command-line buffer.

SYS7 handles three distinct entry scenarios, distinguished by the high nibble of the SVC code in Register A at entry:

• 10H range (nibble 1): Debug monitor enable path - installs or re-enables the debug interrupt vector and associated RST vector hooks, then waits for a command line.
• 20H range (nibble 2): DOS READY / command prompt path - manages the display of messages such as "CHAINING COMPLETED" or "INVALID CL," and then re-enters the DOS command loop.
• 40H range (nibble 4): Chain dispatch path - parses the command-line buffer at 4318H, searches the SYS1 command table for a matching keyword (ABORT, NALERTI, DELAY, OEXIT, NFLASH, PKEYIN, PAUSE, OSTOP, XOWAIT, HALT, and others), and either chains to the appropriate handler or reports an error.

SYS7 also contains the command keyword string table used during chaining, as well as the decimal number parser used to read numeric arguments from the command line. The file ends with a block of ASCII message strings (CHAINING COMPLETED, INVALID CL, CHAINING ABORTED, MANUAL CHAINING ABORTED) used by the various exit paths.

SYS7 calls into the SYS0 resident layer extensively: it uses the file open utility at 444BH, the display routines at 4467H and 447BH/447EH, the DOS-ready exit at 402DH, and the error exit at 4409H. It also calls the ROM character output at 0033H and the keyboard scan at 0049H.

Variable List

Memory Range / Size	Description
4318H—... 1+ bytes	Command-line input buffer (DOS resident). SYS7 reads the chain target name and arguments from this buffer. Written by the ROM line-input routine at 0040H.
4358H 1 byte	Current drive number / FCB drive field. Used by SYS7 as the FCB base address when opening the chained file via 444BH.
402DH—402FH 3 bytes	DOS READY exit vector (SYS0 resident). SYS7 patches this with a JP to 933EH (at 4EBACH) or restores it to point to 402DH. Self-modifying code target.
402FH 1 byte	DOS READY vector opcode byte. Set to EFH (RST 28H) by the cleanup routine at 4EBDH.
4030H—4031H 2 bytes	DOS error-exit vector operand (DE field). Set to 0A33EH by cleanup at 4EC0H.
4032H 1 byte	DOS error-exit vector opcode byte. Set to EFH (RST 28H) by cleanup at 4EC4H.
430FH 1 byte	DOS system flags byte (SYS0 resident). Bit 5: debug/chaining active flag tested and set by SYS7. Bit 7: DEBUG monitor enabled flag. Bit 4: drive-select hardware flag.
43BEH—43BFH 2 bytes	Saved DOS READY vector address. SYS7 saves the current 4016H pointer here at 4E20H and restores it at 4EACH.
4016H—4017H 2 bytes	DOS overlay return address pointer (SYS0 resident). SYS7 redirects this to 4E52H (its own ISR stub) during chaining, then restores the original value on exit.
3840H 1 byte	Disk hardware status port (memory-mapped, Model I). Bit 0: BREAK key / interrupt flag. Bit 2: drive-ready status. Read by SYS7 to detect disk presence and wait for key release.
4FBDH 1 byte	Self-modifying operand: stores the terminator character found during command-line parsing (used at 4FC0H/4F90H). Runtime value is the matched separator or 00H.
513FH 1 byte	Self-modifying operand inside the filename reader at 50FFH: stores whether a valid character was placed in the output buffer (00H = yes, non-zero = flag state). Runtime value set at 5100H and 5131H.
51AAH—51AFH 6 bytes	Filename/keyword work buffer. Receives the uppercase-converted, space-padded keyword extracted from the command line by the reader at 50FFH. Used as the search key against the command table at 50B6H.
50B6H—... variable	Command keyword table. Each entry is a variable-length keyword string followed by a 2-byte handler address. Entries: ABORT, NALERTI, DELAY, OEXIT, NFLASH, PKEYIN, PAUSE, OSTOP, XOWAIT, HALT (and more). Terminated by a sentinel entry.
51B2H—51F9H 72 bytes	ASCII message string area. Contains: "CHAINING COMPLETED"+0DH (51B2H), "INVALID CL,"+... (51C5H), "CHAINING ABORTED"+0DH (51D2H), "MANUAL CHAINING ABORTED"+0DH (51E5H).

Major Routine List

Address	Name and Purpose
4E00H	SYS7 Entry Dispatcher Entry: A = SVC code (high nibble determines path). Masks A to high nibble and routes to debug enable (4E13H), DOS READY (4E58H), or chain dispatch (4EC8H). Returns NZ if nibble not recognized.
4E13H	Debug Monitor Enable / Vector Install Entry: bit 5 of 430FH clear. Disables interrupts, sets bit 5 of 430FH, saves 4016H to 43BEH, installs ISR stub address 4E52H into 4016H, resets stack to 41E0H, opens command file via 444BH, re-enters command loop at 4405H.
4E52H	Interrupt Service Routine Stub Loads DE with 4358H (FCB base) and jumps to ROM 0013H to handle the interrupt return/dispatch.
4E58H	DOS READY / Chaining Exit Handler Entry: nibble = 20H. Resets stack, enables interrupts, checks 430FH bits 7 and 4, reads 3840H drive status, selects message (CHAINING COMPLETED or CHAINING ABORTED), displays via 0033H and 447BH, then calls cleanup at 4EA2H and exits via 402DH.
4EA2H	Interrupt Vector Cleanup Disables interrupts, clears bit 5 of 430FH, zeros 4358H, restores 4016H from 43BEH, patches 402DH/402FH and 4030H/4032H back to their RST 28H forms, returns.
4EC8H	Chain Dispatch / Command Parser Entry: nibble = 40H. Retrieves saved BC (chain parameter) from stack, opens FCB via 444BH, verifies drive numbers match, calls 4454H to validate, reads command line, searches command table, dispatches to handler or error path.
4EE0H	FCB Open and Command Line Read Opens FCB at 4358H via 444BH, reads command-line characters into 4318H buffer via 0013H, then re-enters main dispatch loop.
4F02H	Command Line Parser / Keyword Extractor Reads command line at 4318H, finds '/' delimiters, extracts keyword into 51AAH via 50FFH, searches command table at 50B6H via 5143H, dispatches to matched handler or falls through to error.
4F64H	Decimal Argument Reader Calls 5190H to parse decimal digits from command line into BC, loops B times calling 501EH, then falls to error path at 4F4DH.
4F6FH	Display Message and Wait for Key Pops and re-pushes HL (message pointer), calls 4467H to display message, polls 3840H bits 0 and 2 waiting for a key or drive event, then falls to error path.
4F7DH	Print String and Get Keypress Prints characters from HL until 0DH, calls 0049H for keyboard scan, echoes result via 0033H, stores character at 4FBDH, prints CR, then continues to verify path at 4F99H.
4F99H	Verify and Continue Path Opens FCB at 4358H via 444BH, reads chars into HL buffer via 0013H until 0DH, checks for '/' delimiter sequences, stores found terminator at 4FBDH, calls 447EH, then jumps to 4F4DH.
50FFH	Keyword/Filename Reader Entry: HL = source string, DE = destination buffer, B = max length. Reads up to B uppercase alphanumeric characters into DE, pads remainder with spaces, terminates buffer with 03H. Returns Z if valid keyword found, NZ otherwise.
5143H	Command Table Search Entry: BC = table base, DE = search key (51AAH). Scans table entries (8 bytes each: 6-char name + 2-byte address), returns Z and DE = handler address if matched, NZ if not found.
5190H	Decimal Number Parser Entry: HL = digit string. Parses ASCII decimal digits using multiply-by-10 algorithm (ADD HL,HL x2 + ADD HL,BC + ADD HL,HL). Returns BC = parsed value. Stops on non-digit.

Cross-Reference Notes

SYS7 calls into SYS0 resident: 402DH (DOS READY exit), 4405H (command loop re-entry), 4409H (error exit), 444BH (open file), 4454H (validate), 4467H (display message), 447BH (display with processing), 447EH (display alternate), 4016H (overlay return vector).

SYS7 calls into ROM: 0013H (interrupt dispatch/character input), 0033H (character output), 0040H (line input), 0049H (keyboard scan).

SYS7 is called from SYS0: via the overlay dispatcher when SVC codes 40H-4FH or 70H-7FH are issued by a user program or DOS command.

SYS7 patches SYS0 resident locations: 402DH-4032H (DOS READY / error exit vectors), 4016H (overlay return pointer), 430FH bit 5 (chaining active flag), 4315H (BREAK handler opcode).

4E00H - SYS7 Entry Dispatcher

Entry point for all SYS7 calls. Register A holds the SVC code passed by the caller. The high nibble of A determines which of three execution paths to take: debug enable (10H), DOS READY/chaining exit (20H), or chain dispatch (40H).

4E52H - Interrupt Return Stub and Drive Reset

A two-instruction stub stored at a fixed address and used as the interrupt return vector. Loads DE with the FCB base address at 4358H and jumps to ROM 0013H to re-enter the character-input dispatcher. This address is installed into the interrupt vector at 4016H by the LD (4016H),DE at 4E3CH.

4E58H - SVC 20H Entry: Interactive Command Prompt

Entry point for SVC class 20H dispatched from 4E04H. Sets up the stack, enables interrupts, checks bit 7 of the DOS flags at 430FH to determine whether to arm the DEBUG re-entry hook, then checks bit 4 to determine whether SYS6 is already loaded. If not loaded, reads the keyboard at 3840H for a BREAK key, then either falls through to the SYS6 prompt path or takes the keyboard-input path.

4E79H - SYS6 Prompt Path: Open FCB and Read Command

Opens the FCB at 4358H via 444BH, reads a command line into the buffer at 4318H via ROM 0040H, then dispatches to DOS via 4405H. If the FCB open fails, falls through to the error/abort path.

4E8CH - Load Short Message and Display

Loads HL with the address of "CHAINING ABORTED!" message at 51D2H and jumps to the display-and-exit path. Reached from the SVC 30H dispatch at 4E08H when the SVC class is 30H, indicating a command-line context error.

4E91H - Load Abort Message

Loads HL with the address of the "CHAINING ABORTED" message at 51B2H and falls through to the display-and-exit routine. Reached when a file open failure or other abort condition is detected.

4E94H - Display Message and Return to DOS READY

Common exit path for all SYS7 error and completion conditions. Outputs a newline (0AH), calls 447BH to display the message pointed to by HL, calls the cleanup routine at 4EA2H to restore interrupt vectors and DOS state, then jumps to DOS READY at 402DH.

4EA2H - Interrupt Vector Cleanup

Restores all DOS vectors and flags that were modified during chaining. Called from the display-and-exit path at 4E9CH and also directly when aborting. Clears bit 5 of 430FH, zeros the FCB drive byte at 4358H, restores the overlay return vector at 4016H from 43BEH, and re-patches 402DH/402FH and 4030H/4032H back to RST 28H dispatch form.

4EB8H - Vector Install / Restore Subroutine

Shared subroutine called from both the enable path (4E29H) and the cleanup path (falls through from 4EB5H). Writes HL into 402DH (the DOS READY vector JP target), writes EFH into 402FH (the RST 28H opcode), writes DE into 4030H (the error-exit vector), and writes EFH into 4032H. This either installs SYS7 redirect addresses or restores the original RST 28H dispatch forms, depending on the values in HL and DE at call time.

4EC8H - Chain Dispatch / Command Parser Entry

Entered when the SVC code high nibble equals 40H. This is the main chaining path. The routine recovers the BC parameter passed by the caller from the stack, opens the FCB, verifies drive numbers, reads the command line from the I/O device, and dispatches to the appropriate command handler.

4EE0H - FCB Open and Command Line Input

Reached when the caller's DE parameter matched the expected sentinel 05E3H. Opens the FCB at 4358H, then reads characters from the I/O device via ROM 0013H into the command-line buffer at 4318H until a carriage return is received. Then re-enters the main dispatch loop.

4F02H - Command Line Parser / Keyword Extractor

Entered when the first command-line character is '/'. This routine manages the overall loop of parsing '/' delimited command keywords from the buffer at 4318H, extracting each keyword into the work buffer at 51AAH via the reader at 50FFH, searching the command table at 50B6H via 5143H, and dispatching to the matched handler. If no match is found, falls through to the error path at 4F4DH.

4F4DH - Parse Loop Exit / Stack Cleanup

Common exit point for the command parser. Cleans up the three values saved on the stack (HL buffer start, DE FCB pointer, BC chain parameter) and jumps back to the FCB open and command read sequence at 4EE0H to process the next command.

4F52H - Invalid Command Line Error

Reached when the command line contains an unrecognized keyword or invalid syntax. Loads the address of the "INVALID CL," message and jumps to the display routine.

4F58H - Cleanup and Return to Drive Select

Performs cleanup of the interrupt vector state, pops the three saved stack values (HL, DE, BC), loads DE with the drive configuration table base at 4015H, and jumps to ROM 0013H to complete the operation via the character-input/dispatch handler.

4F64H - Decimal Argument Reader and Loop

This routine reads a decimal numeric argument from the current parse position in the command buffer, then calls a sub-handler B times (the parsed count), and falls through to the parse loop exit at 4F4DH. It is reached as a dispatch target from the command table for commands that take a repeat count.

4F68H - Repeat Call Loop

Calls the sub-handler at 501EH exactly B times, then falls to the parse loop exit.

4F6FH - Display Message and Wait for Key or Drive Event

Pops and re-pushes HL to get the message pointer, calls 4467H to display the message, then polls the hardware status port at 3840H waiting for either bit 0 (BREAK/key signal) or bit 2 (drive-ready signal) to become active. On detection, falls through to the parse loop exit.

4F7DH - Print String and Get Keypress

Pops and re-pushes HL to get the message pointer, prints the message character by character via ROM 0033H until a carriage return is found, then calls ROM 0049H for a keyboard scan, echoes the key via 0033H, stores it at 4FBDH, prints a CR, and falls through to the verify-and-continue path at 4F99H.

4F99H - Verify and Continue Path

Opens the FCB at 4358H, reads characters from the open file into the command buffer at 4318H via HL until a carriage return, then scans for '/' delimiter sequences. If a '//NUL' or specific terminator pattern is found, stores the result at 4FBDH and calls 447EH before jumping to the parse loop exit.

4FC0H - Store Terminator and Call Display

Stores the current Register A value (the terminator character found - either 00H from a null option or 00H from a '///' sequence) into 4FBDH, then calls 447EH to display the buffer content, and jumps to the parse loop exit.

4FCBH - Skip Spaces and Commas

Advances HL through the command buffer skipping space (20H) and comma (2CH) separator characters, stopping on the first non-separator character or carriage return. Used to position HL at the start of the next token after a delimiter.

4FE7H - Closing Parenthesis Handler

Handles a ')' character found during parsing. Loads HL with 0000H (null pointer) and tests whether it is non-zero. Since it is always zero here, jumps to the skip-separator loop at 4FCBH to continue parsing after the closing parenthesis.

4FF1H - Option Token Processor

Reached when a non-separator, non-parenthesis character is found. Steps HL back one position to point at the character, calls 5190H to parse a decimal count, stores the XOR-inverted count as a self-modifying operand, then enters a loop that alternately calls 5014H (when bit 0 of the count is set) and 501EH (when bit 0 is clear), polls the hardware status port for a terminating event, and repeats via DJNZ.

5014H - Sub-handler A: Six Iterations of 502FH

Preserves BC, calls 502FH six times via DJNZ, then restores BC and returns. Called from the option token processor at 5000H when bit 0 of the handler-selection byte is set.

501EH - Sub-handler B: Conditional Delay

Reads bit 3 of the DOS system flags byte at 430FH. If set, calls the delay routine at 5026H. Returns to the caller. Called from the option token processor at 5005H when bit 0 of the handler-selection byte is clear, and from the repeat loop at 4F68H.

5026H - Delay Routine

Preserves BC, loads BC with 199BH (the delay count), calls ROM 0060H to perform a busy-wait delay loop, then restores BC and returns.

502FH - Port Assert and Optional Delay

Writes 01H to the output port at 37E4H (asserting a signal), then calls 503CH which writes 00H to the same port (deasserting it) and optionally delays. Used by sub-handler A at 5017H to toggle the port six times per call.

5036H - Write to Port 37E4H and Optional Delay

Writes Register A to memory-mapped I/O port 37E4H, reads bit 3 of the DOS flags at 430FH, and if set calls the delay routine at 5041H. Returns to the caller. This is the low-level port write used by both the assert (01H) and deassert (00H) steps of the option token processor.

504AH - Read Count and Timed Loop

Parses a decimal count from the command buffer via 5190H, then loops B times calling 505EH per iteration, polling 3840H for a terminating event after each call. On event detection or loop completion, jumps to the parse loop exit.

505EH - Timed Action: Delay then Video Invert

Calls the conditional delay at 501EH, then falls through to 5064H to invert the video RAM. Used as the body of the timed loop at 504EH.

5064H - Video RAM Invert

Inverts every byte in the Model I video RAM (3C00H-3FFFH, 1024 bytes) by XORing each byte with DFH. This toggles bit 5 of each character code, switching between normal and inverse video for every character on screen. Used to produce a flash effect by the timed action loop.

5076H - Display Message from Stack and Read Decimal

Exchanges HL with the top of stack to retrieve a message pointer, calls 4467H to display the message, restores HL, then calls 5190H to read a decimal number from the command buffer. Used to prompt the user and read a response count.

509EH - Clock Wait Loop

Waits until the real-time clock values at 4041H (seconds), 4042H (minutes), and 4043H (hours) reach the threshold values patched into the comparison instructions at 50A2H, 50A9H, and 50B0H respectively. Loops continuously reading the clock bytes and comparing against the stored thresholds until all three match, then jumps to the parse loop exit.

50B6H - Command Keyword Table

The command keyword table searched by the routine at 5143H. Each entry consists of a 6-character keyword (space-padded, uppercase, terminated by 03H at position 6) followed by a 2-byte little-endian handler address. The search key from the keyword reader at 50FFH is compared against the 6-character name field of each entry. A null entry (first byte 00H or sentinel) terminates the table.

50FFH - Keyword / Filename Reader

Reads up to B characters from the source string at HL into the destination buffer at DE. Accepts uppercase letters (41H-5AH), digits (30H-39H), and lowercase letters (61H-7AH converted to uppercase by subtracting 20H). Any other character terminates the read. The destination buffer is written with valid characters and closed with a 03H terminator. Returns Z if at least one valid character was written, NZ if none were found.

512CH - Store Valid Character into Output Buffer

Common entry point reached after a character in Register A has been validated as alphanumeric (and uppercased if necessary). Decrements the remaining-space counter B, stores the character to DE if space remains, clears the no-valid-character flag at 513FH, advances DE, and loops back to 5104H to read the next character. If the buffer is full, increments B back to 1 and loops to discard further source characters.

513AH - Pad Buffer and Return

Reached when a terminating character is found during the keyword read. Saves the terminating character in C, writes a 03H terminator into the output buffer at DE, then tests the flag byte at 513FH via OR to set the Z or NZ return condition. Returns Z if at least one valid character was stored (513FH was zeroed at 5131H), NZ if the buffer is entirely empty (513FH still holds the original count). Register A on return holds the terminating character.

5143H - Command Table Search

Searches the command keyword table pointed to by BC for an entry whose 6-character name field matches the search key at DE. Each table entry is 9 bytes: 6-char name + 03H terminator + 2-byte handler address. Advances through the table in 8-byte steps (add 0008H to HL) until a match is found or a null sentinel terminates the scan. Returns Z and DE = handler address on match; NZ on no match.

5157H - Full Keyword Match

Reached when the first character of the search key matched the current table entry. Compares the remaining 5 characters of the keyword one by one. If all 5 match, loads DE with the handler address from the table entry and returns Z. If any character mismatches, steps to the next table entry and resumes the outer scan.

5177H - Mismatch: Resume Outer Scan

Reached when a character comparison failed during the full keyword match at 5166H. Restores DE and HL from the stack, then re-enters the outer scan loop to advance to the next table entry and retry.

5187H - Trailing Space Check

Reached when the search key ended before all characters were compared (03H or CR terminator found) or when the mismatched character is a non-alphanumeric. Checks whether the corresponding table entry character is a space (20H). If so, the keyword matches on the shorter form and jumps to the success path at 516BH. Otherwise falls through to the outer scan resume at 518CH.

518CH - Restore Stack and Advance to Next Entry

Restores DE and HL from the stack after a failed match attempt, then jumps back into the outer scan loop at 514AH to advance HL to the next table entry and continue the search.

5190H - Decimal Number Parser

Reads ASCII decimal digit characters from the source string at HL and accumulates their value into BC using a multiply-by-10 algorithm. Returns BC = the parsed value and HL advanced past the last digit consumed. If the first character is not a digit, returns BC = 0000H immediately. Uses the sequence ADD HL,HL / ADD HL,HL / ADD HL,BC / ADD HL,HL (equivalent to HL = HL*10 + digit) to build the result.

51B2H - Message and Data Strings

Read-only message strings and data constants used by the SYS7 overlay routines. Each string is terminated by 0DH (carriage return) except where noted. The disassembler has incorrectly decoded these data bytes as Z80 instructions; they are DEFM (define message) data.

51AAH - Keyword Work Buffer

A 8-byte scratch buffer within SYS7's data area used by the keyword reader at 50FFH as the destination for extracted keyword strings. The reader writes up to 6 uppercase alphanumeric characters followed by a 03H terminator into this buffer. The table search at 5143H then compares this buffer against the command keyword table at 50B6H.