TRS-80 DOS - LDOS 5.3.1 for the Model I - PATCH/CMD Disassembled

PATCH/CMD

Other Navigation

LDOS 5.3.1 PATCH/CMD Disassembly - Object-File Patch Utility (Model I)

PATCH/CMD is the LDOS 5.3.1 utility that applies byte-level corrections to an existing disk file - normally a load module such as a /CMD program or a /SYS overlay. It is the standard mechanism for installing the official fixes that MISOSYS distributed as /FIX files, and it can also remove a previously installed patch. The program is a single load module that assembles and runs at 5200H (its transfer address), sitting above the resident DOS and below the utility work area it builds at 5C00H and beyond.

Invoked as PATCH objectfile patchfile or PATCH objectfile (options), PATCH first parses the object filespec with @FSPEC (441CH), applies the default extension CMD with @FEXT (4473H) and opens it. It then either parses a second filespec (the /FIX patch file, default extension FIX) or reads an inline patch given in parentheses on the command line. The body of a patch is a series of text lines that PATCH reads a character at a time, strips to seven bits, and copies into a command buffer at 5F00H, turning each colon outside quotation marks into a carriage return so that one physical line can carry several patch statements.

Each statement begins with a period (a comment) or one of the patch verbs. The four documented verbs are D, F, L and X: X'nnnn'= installs a patch by memory load address, writing the patch code into a new load module appended to the end of the file so that it loads over address nnnn (and can later be removed with the YANK parameter); Drr,bb= is a direct disk modify at record rr, byte offset bb, applied straight to that record without extending the file; Frr,bb= is a find clause that must immediately follow its D line and requires the file's current bytes to match before the D patch installs, a safeguard against patching the wrong file or location; and Lnn designates a DOS library command module (its ISAM overlay number nn) inside SYS6/SYS7 whose following X' or D lines are then patched. The data after the equals sign is either hexadecimal bytes separated by single spaces or an ASCII string in double quotes. Three command-line parameters reach the same dispatcher: (YANK) removes a named memory-load (X-verb) patch, (REMOVE) un-installs a direct (D-verb) patch by restoring its original bytes, and (OPTION=N) lets a D patch install without its matching F line. PATCH runs the buffer twice: the first pass validates each statement and, for a D line, verifies the F clause; the second pass applies the changes, positioning the file with @POSN (4442H) and rewriting the affected record with @RWRIT (4457H). Progress is shown on a single status line - "Reading input", "Generating patch", "Installing patch", "Re-building library map", "Yanking patch from file" - and the run ends with "Patch(s) successfully installed" or "Patch successfully yanked", or with one of the diagnostic messages held in the data block at the end of the file.

PATCH performs no RST 28H supervisor request of its own; every service it uses is either a Model I ROM entry (@GET 0013H, @PUT 001BH, @DSP 0033H) or one of the resident SYS0/SYS SVC vectors (@FSPEC, @FEXT, @OPEN, @CLOSE, @READ, @POSN, @BKSP, @RREAD, @RWRIT, @DSPLY, @LOGOT, @ERROR, @EXIT, @ABORT), so no other overlay is loaded while it runs.

Variables, Buffers, and Self-Modifying Cells

Major Routines

Cross-Reference Notes

PATCH/CMD is a stand-alone utility loaded and run by the DOS command interpreter (SYS1/SYS); nothing in the operating system calls into it. It issues no RST 28H request of its own. Every external call it makes is resolved in the Model I ROM or in the resident core: the ROM character routines @GET (0013H), @PUT (001BH) and @DSP (0033H), and the resident SYS0/SYS vectors @FSPEC (441CH), @FEXT (4473H), @PARAM (4476H), @OPEN (4424H), @CLOSE (4428H), @READ (4436H), @POSN (4442H), @BKSP (4445H), @RREAD (4454H), @RWRIT (4457H), @DSPLY (4467H), @LOGOT (447BH), @ERROR (4409H), and the process vectors @EXIT (402DH) and @ABORT (4030H).

5200H - Program Entry, Sign-On, and File Opening

PATCH is loaded and run by the DOS command interpreter with Register Pair HL pointing at the command line following the word PATCH. This section displays the sign-on banner, parses and opens the object file to be patched, and parses the /FIX patch filename, copying it into the CLP name buffer.

525EH - Command-Line Option and Inline-Patch Scan

Reached when the command line carried no separate /FIX filespec. This scans past blanks, requires an opening parenthesis, and either parses the REMOVE and OPTION parameters with @PARAM or copies an inline patch body typed in parentheses into the command buffer at 5F00H.

52A5H - Open the Patch File and Fill the Command Buffer

Opens the /FIX patch file and reads it a character at a time into the command buffer at 5F00H, stripping each byte to seven bits, honouring quotation marks, and turning colons outside quotes into carriage returns. Overflow past 7300H reports "Fix file too big - partition it".

52FCH - Main Command Dispatch Loop

Walks the command buffer statement by statement. On the first pass it routes through 57A8H (which only sets flags and validates); once 57A2H has set the pass flag at 530BH non-zero, each statement is routed by its leading letter: the patch verbs D (direct disk modify), F (find/verify), L (library overlay) and X (memory-load patch), plus the internal handlers for the YANK, REMOVE and OPTION parameters (Y, R and O), with a leading period treated as a comment.

5375H - Completion and Exit

Closes the object file, displays the closing message and returns to DOS. The closing message pointer at 5384H is normally "Patch(s) successfully installed" but is changed to "Patch successfully yanked" by the yank path.

538CH - Skip to End of Command Line

Advances the statement pointer past a comment or otherwise skipped line, then re-enters the dispatch loop. The quote-state flag is cleared first so a colon in the skipped text cannot leave the reader stuck inside quotes.

539DH - D Sub-Command - Apply a Data Patch

Handles a D statement: it parses the record number and byte offset, then parses and applies the replacement data, verifying the original bytes through the F clause when one is present.

53A6H - Parse the Record Number and Byte Offset

Reads the hexadecimal record number and the comma-separated byte offset that address a byte inside the load module, positions the object file to that record, reads it, and stores the offset.

53D0H - Parse and Apply the Replacement Data

Parses the bytes after the equals sign and hands each to 5849H, which on the second pass writes it into the record buffer and on the first pass verifies the original byte. When the statement ends, and only on the second pass, the modified record is written back with @RWRIT.

5409H - R Sub-Command - Reverse the Patch Sense

A R statement forces the reverse/remove flag on so the following statements remove rather than install a patch, then skips the rest of the line.

5411H - Y Sub-Command - Yank (Remove) a Patch

Displays "Yanking patch from file", then reads the object file's load records looking for the type-07 patch record whose stored name matches the CLP name. When found, the patch is unlinked and the record removed; when the file ends without a match, "Can't yank, patch not in load file" is shown.

54A4H - O Sub-Command - Set the On/Off Option

An O=Y, O=N or O=OFF statement sets the on/off option flag that gates whether the following data statements are applied, then skips the rest of the line.

54D3H - L Sub-Command - Select a Library Overlay

An L statement names a library-overlay number. PATCH locates that overlay inside the load file, reads its record, regenerates the library map and rebuilds the load image so that subsequent D statements address bytes within the chosen overlay.

5526H - Read the Next Load-Module Record

Displays "Positioning load file", then reads load-record type bytes from the object file, skipping over each record's data, and returns when it reaches a record whose type is 02H, 03H, 04H or 0AH - the record types the callers act on.

555BH - Assemble the X-Verb Memory-Load Patch Module

Displays "Generating patch", writes a type-07 patch record carrying the CLP name (the identification that later lets YANK find and remove this patch) into the work image at 7300H, then walks the remaining statements assembling each X'nnnn' memory-load entry into the image before the module is appended to the file.

5605H - Install the Assembled Patch Into the Load File

Copies the object File Control Block, reads the load file forward while writing each byte back and also into the work image beyond the assembled patch, then appends the assembled patch record to the file.

5668H - Token and Hexadecimal Scanner

Reads one value from the command buffer. A quoted character is returned literally; otherwise one or two hexadecimal digits are converted to a byte. The entry at 5668H first clears the quote flag; the entry at 566CH preserves it.

56ADH - Convert an ASCII Hexadecimal Digit

Converts the ASCII digit in Register A to its 0-15 value, or aborts with "Non-hex digit encountered" if it is not a valid hexadecimal digit.

56BFH - Locate a Library Overlay in the Load File

Scans the object file's load records counting library-overlay markers (type 08H) until the overlay number requested by the L command is reached, then reads that overlay's load address and length into Register Pair BC and Register C. Reaching the transfer record first raises "Library overlay not found".

56F7H - Object-File Byte Reader

Reads the next byte of the open object file through the ROM @GET routine, returning it in Register A, or diverts to the shared error exit if the read fails. Reached both by direct call and by falling through from 56F6H.

56FEH - Rebuild the Load-Module Image

Streams the object file's load records into the work area at 7300H so that a load address can be resolved to a byte position, adjusting each record's stored load address as the records are laid down, then writes the rebuilt image back to the file.

57A2H - Switch to the Second Pass

Ends the first (validating) pass by setting the pass flag non-zero and restarting the dispatch loop so every statement is applied on the second pass.

57A8H - First-Pass Command Validation

On the first pass each statement is recognised and validated without writing the file. R and O set their flags, D falls through to the verify path, and the comment, F, Y, L and X statements are simply skipped. Reaching the end of the buffer switches to the second pass.

57ECH - Verify a D Statement Against Its Find Clause

Confirms that the D and F parts of the statement address the same record and offset, then parses and checks the original bytes so a mismatched patch is refused with "FIND line mismatch".

581AH - Verify a Reverse Patch and Swap D/F

In reverse (remove) mode the roles of the D and F clauses are swapped: the file is verified against the replacement bytes, and the statement's leading letters are rewritten so the second pass restores the original bytes.

5834H - Line-Scan Helpers

Small helpers used by the verify and option paths: 5834H skips forward past comment lines, 583DH advances to the next carriage return, and 5844H reads one character folded to upper case.

5849H - Apply or Verify One Patch Byte

The workhorse of the D command. On the second pass it writes the byte to the record through the @PUT wrapper; on the first pass it reads the corresponding object-file byte and compares it, aborting with "FIND line mismatch" if they differ.

585DH - Position, Output, and Error Exits

The @POSN wrapper, the @PUT wrapper, and the shared error exits. 5867H hands an error code to @ERROR and aborts; 586CH does so with a comma error; 5870H, 5874H, 5878H, 587CH, 5880H, 5889H and 588DH each select a fixed message and abort.

589FH - Data - Default Extensions, Sign-On Banner, and Messages

Non-executable data: the default file extensions applied by @FEXT, the sign-on banner, the five status-line strings shown while a patch is processed, and every diagnostic message. The status strings are framed by video control codes (1DH, 1EH) and end with 03H so they overwrite the status line in place; the diagnostic messages end with a carriage return.

5AC0H - Data - Run-Time Buffers and the @PARAM Keyword Table

The CLP name length cell and eight-byte name buffer (filled at run time by the patch filename), the @PARAM keyword table naming the REMOVE and OPTION parameters, and the parameter result cells. Each @PARAM entry is a six-character blank-padded keyword followed by the two-byte address of its result cell; a 00H byte ends the table.