TRS-80 DOS - NEWDOS/80 v2.0 for the Model III - SYS19/SYS Disassembled

SYS19/SYS

Other Navigation

NEWDOS/80 v2.0 – SYS19/SYS – RUN/LOAD/MERGE/SAVE/DELETE Overlay

SYS19/SYS is a BASIC/CMD overlay module for the TRS-80 Model III NEWDOS/80 v2.0 Disk Operating System. It occupies the shared overlay region at 5200H–56E7H (1,256 bytes; 1,105 bytes of active code, 151 bytes of NOP padding). The overlay entry point is 5200H, which contains a CP A / RET presence-detection stub identical to SYS18.

SYS19 implements four major BASIC statement extensions:

Address ranges and functional areas within SYS19/SYS

Self-Modifying Code Locations

SYS19 makes extensive use of self-modifying code for mode switching, pointer tracking, and parameter passing. The following locations have their operand bytes modified at runtime.

External Writes to BASIC/CMD Addresses

SYS19 modifies several locations in the BASIC/CMD main module (5700H-684BH range) and DOS/BASIC system RAM to control mode switching, keyboard interception, and program state.

Entry points and functional units within SYS19/SYS.

ROM Routines Called

ROM entry points (0000H-37FFH) used by SYS19

BASIC/CMD Routines Called (SYS0 Range)

Routines in the BASIC/CMD main module (4000H-56FFH range, accessed via the SYS0 page) called by SYS19.

RST Vectors Used

Architectural observations and design patterns discovered during the disassembly analysis

1. The overlay stub at 5200H (CP A / RET) is identical to SYS18. Both overlays share the same 5200H-56E7H address range and are loaded on demand. Only one can be resident at a time.
3. The option parser at 5202H-5228H uses an elegant opcode-patching scheme: Register B carries the opcode byte (18H=JR, 3EH=LD A,nn) that will be written to 5255H. When 3EH, it converts the JR Z,526BH instruction into LD A,14H, consuming the branch displacement as an immediate operand and causing fall-through to the V-option path. This avoids a separate conditional branch instruction.
4. The MERGE memory relocation uses a two-phase approach: (a) LDDR at 52AFH moves all existing data (variables, arrays, string descriptors, string stack) upward to create a gap at the program area for the merged lines, then (b) three-stage LDIR at 543EH-546EH compacts everything back down after the merge is complete. The SP−160 safety margin at 529BH and the 256-byte boundary check at 54BDH prevent the relocation from colliding with the stack.
5. The merge line comparison at 53B4H-53BBH uses SBC HL,BC + ADD HL,BC to perform a non-destructive comparison. The SBC sets the carry and zero flags based on old_line − new_line, then ADD restores HL to its original value. Three outcomes: carry (old < new → copy old first), zero (duplicate → error or skip), neither (old > new → insert new line).
6. The 4-byte line header written at 53C3H-53CAH and 541CH-5424H uses LD (HL),H for both link pointer bytes. This writes the current page address (H) as a temporary placeholder. The actual link pointers are fixed by ROM 1AF8H (relink) during the compaction phase at 5472H.
7. The FFFFH sentinel (set at 52D3H and 53F9H) ensures that the merge algorithm terminates correctly when one program is exhausted before the other. Since FFFFH (65535) is higher than any valid BASIC line number (max 65529), any remaining lines from the other source will always compare as "less than" and be appended.
8. The variable/string relocator at 54F2H-559BH is a sophisticated pointer-adjustment engine. It walks two data structures (variable table and string descriptor stack), identifies string pointers that fall within the relocated address range (using 5641H/5649H for lower/upper bound checks), and either adjusts the pointer by the merge delta (at 5579H) or allocates new string space (via ROM 28BFH at 5588H) and copies the string data (via LDIR at 5590H). This ensures that strings whose data resided in the deleted or relocated text area remain accessible after the merge/delete.
9. The delta accumulator at 5642H tracks the cumulative address offset caused by all merge insertions. Each call to 5478H computes the local delta (output position − source position), stores it at 557AH, and the call to 562AH adds it to the running total at 5642H. The accumulated delta is used by the range check at 5641H to determine the correct lower bound for string pointer relocation.
10. CMD"F",DELETE shares most of its code with MERGE. The mode flag at 5315H (value 02H) controls the behavioral differences: the post-load dispatch at 5314H routes to the continuation-line handler at 5322H, and the duplicate-line check at 53CDH raises an "Illegal Function Call" error instead of skipping the old line.
11. The SAVE path at 55E5H-561DH temporarily writes FFH to the byte before the program start (40A4H−1), saves the original byte in C, writes the program data in 256-byte chunks via SVC 4439H, then restores the original byte. The FFH marker identifies the start of a packed BASIC program file.
12. The INC L / CALL Z,54B2H pattern in the packed merge loop (52E6H-530EH) is an efficient page-boundary handler. INC L only affects the low byte of HL, so when L wraps from FFH to 00H, the Z flag triggers a sector read. This avoids a full 16-bit increment and comparison on every byte, at the cost of assuming page-aligned data boundaries.
13. SYS19 is the companion to SYS18 (BASIC direct statement executor). SYS18 handles LIST, EDIT, DELETE (direct mode), DI, DU, AUTO, RENEW, and dispatches RENUM/REF. SYS19 handles the program-mode file operations: RUN/LOAD with options, MERGE, CMD"F",DELETE, and SAVE. Both share the 5200H overlay space.

5200H - Overlay Presence Stub

SYS19 Overlay Detection Stub. This two-byte sequence serves as a presence test for the SYS19 overlay. Callers execute CALL 5200H and test the Z flag on return. CP A always sets Z (any value compared against itself is equal), so if SYS19 is loaded, Z is set. If SYS19 is not loaded, the memory at 5200H contains whatever was previously there (from a different overlay or uninitialized RAM), and the test fails.

5202H - RUN/LOAD/MERGE Entry Point and Option Parser

Main entry point for SYS19. This routine handles the extended RUN, LOAD, and MERGE statements with optional V (variable-preserving) and R modifiers. On entry, the BASIC statement parser has already consumed the filespec and the comma separator; HL points to the next character in the BASIC text. The code parses any trailing option letter, stores mode flags into three self-modifying code targets (5315H, 5FA8H, 5255H), then branches to the V-option path (variable-preserving load) or the standard load path.

521FH - Store Mode Flags to Self-Modifying Code Targets

Stores the parsed option values (from Registers B, C, D) into three self-modifying code locations that control behavior throughout SYS19 and BASIC/CMD. Then checks the FCB status flags to determine whether variable-preserving mode can actually be applied.

5240H - Packed File V-Option Validation

For packed BASIC program files (access mode >= 06H), this section validates whether the V-option can be applied. If the mode is exactly 06H and the V flag is set, the FCB access mode is decremented and the execution hook is configured for variable-preserving behavior. If the mode is not exactly 06H, execution falls through to the branch decision.

5255H - Mode Branch: V-Option vs Standard Load

This is the key decision point that splits execution between the V-option (variable-preserving) path and the standard (non-V) path. The opcode at 5255H is self-modifying: when the V-option is active, the opcode has been changed from 28H (JR Z) to 3EH (LD A,nn), which disables the branch and causes execution to fall through into the V-option initialization code at 5257H. When the V-option is not active, the original JR Z branches to 526BH for standard load behavior.

526BH - Standard Load Path (Non-V Mode)

Standard (non-variable-preserving) RUN/LOAD path. Disables the guard flag and calls ROM 1B4DH to initialize the BASIC runtime for a fresh program load, clearing all variables and closing all files. Then falls through to the common file-load sequence at 5271H.

5271H - Common File Load Sequence

Common path for both V-option and standard modes. Enables the guard flag, sets bit 6 of the DOS state flags at 4289H, then calls SVC 4436H to load the program file using the filespec at 570DH. On success (Z flag), continues to the MERGE path. On error 1CH (position error), redirects to the MERGE-after-load handler. On any other error, dispatches to the BASIC/CMD error translator at 5DEFH.

5289H - MERGE Post-Load: Memory Size Calculation

After a successful file read (for MERGE), this section calculates whether enough memory is available to accommodate the merged program. It computes the total size of the new program text plus the existing data (variables, arrays, strings) and checks that the result fits below the current stack pointer with a safety margin of 160 bytes (A0H). If memory is sufficient, it performs an LDDR block move to relocate the existing data upward to make room for the merged text, then updates all the BASIC memory pointers (string space, variable start, array end, string stack).

52C0H - Initialize MERGE Line Chain Walk

After relocating the existing data upward, initialize the pointers for walking the BASIC program line chain during the MERGE operation. The code stores the program start address into the merge tracking variables at 5429H and 547FH, then begins reading the first line’s link pointer and line number from the program text.

52D0H - Complete Line Number Read and End-of-Program Check

Continues the BASIC line chain walk started at 52CAH. Loads the high byte of the current line number into Register B (completing BC = full 16-bit line number), then checks whether the link pointer was 0000H (end of program). If so, sets BC = FFFFH as a sentinel that will always compare higher than any real line number, ensuring that all remaining file lines are appended at the end. Pushes the line number and initializes the merge delta accumulator.

52DDH - PDRIVE Table Check: ASCII vs Packed Merge

Checks the first byte of the PDRIVE table at 4300H to determine whether the current operation is merging from an ASCII file or a packed file. If the first PDRIVE entry is not FFH (the table contains valid drive entries), the file is being read as a packed/tokenized program, and execution branches to the MERGE-from-file reader at 535BH. If the first entry is FFH (the default uninitialized state), the program data has already been loaded into the program area, and the merge proceeds inline.

52E6H - Merge Main Line Copy Loop (Packed Data)

Main merge loop for packed (in-memory) program data. Walks the relocated old program line by line, reading each line’s link pointer and line number through a series of INC L / CALL Z,54B2H steps. The INC L advances through the 4-byte line header (link_low, link_high, linenum_low, linenum_high), while CALL Z,54B2H handles page boundary crossings (when L wraps to 00H, a new sector must be read). Once the line number is loaded into BC, calls 53B4H to compare it against the current merge file line and decide whether to insert the file line or copy the old program line. After the line comparison, copies the tokenized line text byte by byte to the merge output area at (DE), then loops back for the next line.

5310H - End of Merge / Merge Finalization

Reached when all old program lines have been processed (link pointer = 0000H at 52F5H) or when the MERGE-from-file reader finishes reading all file lines. Pops the saved line number, calls the merge compaction routine at 543EH to relocate the merged data back to its final position, then falls through to the post-load mode dispatch at 5314H.

5314H - Post-Load Mode Dispatch

After the file has been loaded (or merge completed), this dispatch reads the mode flag from self-modifying location 5315H and branches to the appropriate handler. Mode 00H (no option) goes to ROM 1A19H for a standard BASIC warm start. Mode 01H (V-option or R-option) goes to ROM 1D1EH for variable-preserving run continuation. Mode 02H (CMD"F",DELETE) goes to the RUN-after-delete handler at 5322H.

5322H - CMD"F",DELETE Post-Delete Run Handler

After CMD"F",DELETE has completed the line deletion (mode = 02H), this routine reads the continuation line number from the self-modifying variable at 57B8H, searches for that line in the BASIC program via ROM 1B2CH, and positions HL just before the found line for execution to continue. If the continuation line is not found exactly, it checks whether a higher-numbered line exists (for JP Z,1D1EH) or reports a syntax error.

5334H - CMD"F",DELETE Entry Point

Entry point for the CMD"F",DELETE statement handler. This routine is reached from the BASIC/CMD CMD"F" dispatcher when the DELETE keyword is recognized. It checks whether 40A2H is FFFFH (indicating direct-mode execution, which is prohibited), parses the line number range parameters, adjusts the FCB access mode for V-option behavior, stores mode flag 02H to 5315H, and then jumps back to 5266H to enter the common merge/delete flow which will delete the specified lines by rebuilding the program without them.

5350H - Direct Mode CMD"F",DELETE Redirect

When CMD"F",DELETE is executed as a direct statement (prohibited per the manual), this path checks for end-of-statement. If valid end-of-statement, it falls through to store the mode flag. If not, it reports a syntax error. This allows certain limited direct-mode operations while blocking the full DELETE operation.

535BH - MERGE-From-File Line Reader

Handles MERGE when lines are being read from an open disk file (the PDRIVE table at 4300H had a valid entry). Decrements IX+17H to adjust the file position, reads lines from the file one byte at a time via CALL 60F2H (the BASIC/CMD File Read routine), assembles each line in the buffer at (40A7H), parses the line number, and calls 53B4H to insert the line into the merge output at the correct position in the sorted line chain. Loops until the file is exhausted.

538AH - Parse Assembled Line and Insert into Merge

After a complete line has been assembled in the buffer, parse the line number from the ASCII text, strip trailing spaces, tokenize the line via ROM 1BC0H, and insert it into the merge output via 53B4H. Then copy the tokenized line text byte by byte to the merge output and loop back for the next file line.

53B4H - Line Number Comparison and Insertion

Core merge insertion routine. Called with the new line number in BC (from the merge source) and the old program line number on the stack (pushed at 52D6H or re-pushed during the merge loop). Uses EX (SP),HL to access the old line number, compares it against BC via SBC HL,BC, and decides: if the old line is less than the new line, the old line’s 4-byte header is written to the output and control returns to copy the old line’s text. If the old line equals the new line (duplicate), execution branches to 53CDH for duplicate handling. If the old line is greater, execution branches to 53FEH to insert the new line first.

53CDH - Duplicate Line Number Handler

Reached when the old program line number equals the new/file line number (a duplicate). If BC = FFFFH (the end-of-program sentinel), this means both programs have been exhausted and the merge is complete — jump to the error exit at 5DBBH. Otherwise, check the mode flag at 5315H: if mode is 02H (CMD"F",DELETE), report an “Illegal Function Call” error since DELETE cannot process duplicate lines. For MERGE mode, skip the old program line (advance past its text) and re-enter the comparison loop with the NEXT old program line.

53EEH - Old Program Line Header Reader

Reads the 4-byte header of the next old program line. Saves HL (start of line) to 53DCH, reads the 2-byte link pointer, and returns with A = line number low byte and HL pointing to the line number high byte. If the link pointer is 0000H (end of program), pops the caller’s return address and injects HL = FFFFH into the comparison loop at 53B7H, effectively ending the old program scan.

53FEH - Copy Old Program Lines to Output Until Insertion Point

Reached when the old program line number is less than the new/file line number (the old line should appear first in the output). Copies old program lines — including their full text and 4-byte headers — to the merge output, advancing through the old program chain until the old line number exceeds the new line number. At that point, writes the new line’s header and returns to the caller to copy the new line’s text.

543EH - Merge Compaction: Three-Stage LDIR

Final memory compaction routine called after all lines have been merged. Performs up to three LDIR block moves to relocate the merged program text, the variable/array area, and the string stack back to their final contiguous positions. Updates the BASIC memory pointers (40F9H, 40FBH, 40FDH), relinks the program line chain via ROM 1AF8H, and sets the reset vector via JP 6497H. The three LDIR moves correspond to: (1) merged data → string space, (2) variable/array area, (3) string stack. Each region’s size is loaded from a self-modifying operand set by 5495H.

5478H - Delta Accumulator Updater

Calculates the distance (delta) between the merge output pointer (5442H) and the merge source pointer (547FH), stores the result at 557AH, then conditionally calls the variable/string relocator at 54F2H if 5429H is nonzero. Exits via JP 562AH which accumulates the delta into 5642H and restores DE/HL from the stack.

5495H - Memory Region Size Calculator

Calculates the sizes of the three memory regions above the BASIC program (string stack, variable/array area, and the gap between them) and stores the results into self-modifying operands for the three-stage LDIR compaction at 543EH. Called during merge initialization at 5289H and during the merge pointer init at 54D9H.

54B2H - Page Boundary / Sector Read Handler

Called conditionally (CALL Z) when INC L wraps from FFH to 00H during the merge line copy loop. Reads the next sector from the file via SVC 4436H, then checks whether the merge output has caught up to the merge source (53DCH), which would indicate an out-of-memory condition.

54C8H - Merge Pointer Initialization

Initializes all four merge tracking pointers (53DCH, 547FH, 5429H, 5442H) from the current HL/DE values, zeros the delta accumulator via CALL 5638H, calculates region sizes via CALL 5495H, then jumps to the merge compaction at 543EH. Called during V-option setup at 5263H and by the CMD"F",DELETE handler at 55BCH.

54DFH - Variable Relocation Entry

Entry point for the variable relocation sequence used by the V-option (variable-preserving RUN/LOAD) and CMD"F",DELETE paths. Clears the BASIC program line chain by writing 0000H to 40F0H, saves the merge context, disables the guard flag, reinitializes the BASIC system via ROM 1B8FH, and jumps to the address stored at 54F0H to continue execution.

54F2H - Variable/String Pointer Relocator

Adjusts internal variable and string pointers that reference the BASIC program text, accounting for the address changes caused by the merge relocation. Walks the variable table (40F9H–40FBH) and string descriptor stack (40FBH–40FDH), adjusting any pointers that fall within the relocated range. Uses the self-modifying operands at 5565H, 556CH, 5574H, and 5576H to track the relocation parameters. Calls 555BH/5558H for individual string descriptor relocation, and ROM 0BAAH for string copy operations.

5527H - String Descriptor Stack Walk

After the variable table walk completes, walks the string descriptor stack from 40FBH through 40FDH. Each string descriptor stack entry is a 5-byte record: [type][length][addr_low][addr_high][extra]. For type 03H (string), the entry contains a string count and multiple sub-records that need relocation via ROM 0BAAH (string copy).

5558H - String Descriptor Reader / Relocator

Reads a 3-byte string descriptor (length + 2-byte address) from (HL) and optionally relocates the string pointer if it falls within the relocated range. Entry at 5558H reads without relocating; entry at 555BH performs the full relocation check. Uses self-modifying operands at 5564H–5576H to store relocation parameters, and calls 5641H/5649H for range comparison.

559CH - CMD“F”,DELETE Range Parser

Parses the line number range for the CMD"F",DELETE statement. Expects a comma separator (RST 08H ⇒ 2CH), then the DELETE keyword token (B6H), then the first line number, a dash separator, and the second line number. Searches for the start and end lines in the BASIC program chain, sets up the merge pointers, and enters the variable relocation and compaction flow to rebuild the program without the deleted lines.

55C5H - SAVE / MERGE ASCII File Handler

Handles the SAVE and MERGE paths for ASCII format files. Checks for a comma and the “A” option (41H), verifies memory space, and either writes the program to a file (SAVE) or reads from a file and enters the BASIC editor (MERGE/LOAD ASCII). Uses 5710H to communicate the buffer limit address.

55E5H - Default SAVE Path (No Option)

SAVE without the “A” option (packed binary format). Reads the byte before the program start, temporarily writes FFH as an end-of-file marker, computes the file size, writes the program to disk via SVC 4439H, restores the original byte, and then writes a terminator record. Uses the DOS file write routine at 6370H to complete the save.

5620H - Merge Delta Accumulator Initializer

Initializes the merge delta accumulator at 5642H to 0000H and returns HL pointing to 543EH (the merge compaction routine address). Called at 52D7H to set up the delta tracking before the merge loop begins.

562AH - Delta Accumulation and Return

Adds the current merge delta (from 557AH) to the running total at 5642H, then restores DE and HL from the stack and returns. Called from the delta updater at 5492H.

5638H - Delta Zero and Variable Relocate

Zeros the delta accumulator at 5642H by storing A (expected to be 00H) via BC, then calls the variable/string relocator at 54F2H. Called from 54D6H during merge pointer initialization.

5641H - Lower Bound Range Check

Checks whether the string address in DE is at or above the lower bound calculated from HL + BC. If DE is below the range, exits via 564EH which pops the return address and jumps to 5599H (skip relocation).

5649H - Upper Bound Range Check

Checks whether the string address in DE is below the upper bound in HL. Complements the carry flag so that the exit logic at 564CH works consistently for both bounds.

5651H - NOP Padding

Unused/reserved area filled with NOP instructions (00H bytes). This padding extends from 5651H through 56E7H (151 bytes), filling the remainder of the SYS19 overlay space. The overlay occupies 5200H–56E7H (1,256 bytes total), matching the SYS18 overlay region.