TRS-80 DOS - LDOS v5.3.1 for the Model I - BACKUP/CMD Disassembled

BACKUP/CMD

Other Navigation

LDOS 5.3.1 BACKUP/CMD Disassembly - The Disk Backup Utility (Model I)

BACKUP/CMD duplicates the data on one diskette onto another. It is a transient utility: DOS loads it, it runs, and it exits through @EXIT at 402DH, leaving nothing resident behind it. The command syntax is BACKUP :s [TO] :d (parm,parm) or BACKUP [-]partspec w/wcc:s TO :d (parm,parm), and the parameters are DATE, INV, MOD, MPW, NEW, OLD, QUERY, SYS and X.

The manual describes three kinds of backup, and the code implements exactly three. A mirror image is a cylinder-for-cylinder copy, attempted when the size, density and number of sides match on the two disks. A backup by class is a file-for-file copy, chosen by the operator whenever a partspec or any parameter other than X or MPW appears on the command line. A backup reconstruct is the same file-for-file copy, chosen by the utility itself when the two disks are not compatible enough for a mirror image.

What makes this file unusual is that those are not three code paths through one program. They are three separate programs carried in one load module, and two of them are stored at addresses they never execute at. The command-line front end is assembled to run at 5A00H, which is where the transfer address points, and both backup engines are also assembled to run at 5A00H. The mirror-image engine is stored at 5E00H and the file-by-file engine at 6300H. Once the front end has finished parsing and has decided which kind of backup is required, the selector at 6C00H block-moves the chosen engine down over the front end that has just finished with it, and jumps to 5A00H. The engine sections of this page are therefore annotated at the addresses the code actually runs at, with the load address stated in each section lead-in.

Everything above the moved engine is work space. After the block move, the selector rounds the end address up to the next page boundary and stores it at 5285H, and from that point on 5285H is the base of the buffers and HIGH$ at 4049H is their top. The two Granule Allocation Table copies and the general sector buffer sit at fixed addresses inside the file's own unloaded gap at 55F8H-59FFH.

BACKUP does almost all of its disk work itself rather than through the file system. It copies the drive's ten-byte Drive Control Table entry through the resident GETDCT routine at 478FH, points Register Pair IY at it, and reaches the floppy driver with a JP (IY) through the jump instruction at DCT+00, exactly as FORMAT/CMD does. Only two supervisor requests are issued, both as three-byte tail-call stubs: code 0E4H to hash a master password and code 84H to make SYS2/SYS resident before the copying starts.

The utility also suppresses the real-time clock. The mirror-image transfer is timed against the drive, so the engine saves the byte at 4012H inside the resident interrupt vector and writes a RET over it for the duration of the copy. That one byte is the entire reason the utility signs off with Note: Real time clock no longer accurate.

File Format and Load Map

BACKUP/CMD is 5880 bytes on disk: one type-1FH copyright record carrying Copyright 1991 MISOSYS, Inc., All rights reserved, then 27 type-01 load records, then a type-02 transfer address of 5A00H. The records place 5717 bytes into memory in six runs separated by five unloaded gaps. The gaps are working storage and are represented on this page as reserved space.

The two engine blocks are moved by a fixed amount, so every address inside them is the loaded address less a constant. The mirror-image engine is moved down by 0400H and the file-by-file engine by 0900H.

Variable and Buffer List

The Parameter Table

The table at 6D74H is the standard LDOS @PARAM form: a six-character blank-padded keyword followed by the address of a two-byte result cell, repeated until a 00H byte ends the list. A long form and its abbreviation point at the same cell, and the cells are not all in one place - some are in the small data run at 5200H and some are the operand fields of instructions out in the front end.

Major Routine List

Cross-Reference Notes

BACKUP is a transient utility, so nothing calls into it. It calls out to the resident core and to the ROM. From the Model I ROM it uses 002BH to test the keyboard, 0033H to display one character, 0040H to collect a line and 0060H to delay.

From the resident core it uses the supervisor vectors @EXIT 402DH, @ABORT 4030H, @ERROR 4409H, @INIT 4420H, @OPEN 4424H, @CLOSE 4428H, @KILL 442CH, @READ 4436H, @VER 443CH, @REW 443FH, @POSN 4442H, @DSPLY 4467H, @DATE 4470H, @PARAM 4476H, @LOGOT 447BH, @CKDRV 44B8H and @MULT 44C1H, together with the disk primitives RSELCT 4759H, SEEK 475EH and GETDCT 478FH, the directory helpers RDSSEC 4B45H and DIRCYL 4B65H, and the keyboard-status poller at 4DA6H. All of these are documented on the SYS0/SYS page.

It reads five resident cells and writes two. It reads SFLAG$ at 430FH bit 5 to find out whether a job is in effect, KFLAG$ at 4423H bits 0 to 2 for BREAK, PAUSE and ENTER, HIGH$ at 4049H for the top of memory, TIMER$ at 4040H for the drive-ready timeout, the month cell at 4046H to see whether a date has been established, and the word at 4BDFH inside the supervisor dispatcher for the X parameter residency test. It writes the drive number into LDRV$ at 4308H before each disk operation, the per-drive extended-dating flag at 475DH once a pack's Granule Allocation Table has been read, and the interrupt vector byte at 4012H for the duration of a mirror-image transfer.

Two supervisor requests are issued, both documented on the main LDOS disassembly page: code 0E4H, the password hash serviced by SYS2/SYS, and code 84H, the pre-load that makes the same overlay resident. The file-by-file engine additionally depends on SYS3/SYS for @CLOSE, SYS8/SYS for granule allocation and SYS10/SYS for @KILL, reached through the resident vectors rather than directly, which is why the X parameter insists that those four overlays are resident before it will run.

The disk layout BACKUP works against is the one FORMAT/CMD lays down, and the two files are the two halves of one story about the Hash Index Table: FORMAT reserves two directory slots for BOOT/SYS and DIR/SYS, and BACKUP claims the remaining thirteen, for SYS0/SYS through SYS12/SYS, when it turns a formatted DATA disk into a SYSTEM disk, checking all fifteen as one table. The per-drive extended-dating flag at 475DH that BACKUP writes is the same flag DATECONV/CMD exists to make meaningful.

5200H - Parameter Result Cells and Selection Flags

The first load record places twenty-nine bytes of data, not code, at 5200H. Five of them are the result cells the @PARAM service at 4476H writes into when it recognises a keyword on the command line, and the rest are the selection criteria the front end assembles from the partspec. The whole block ships as blanks and zeroes and is filled in during parsing, so the listing's rendering of these bytes as instructions is a misreading of data. Every byte here is read by the file-by-file engine when it decides whether a given directory record is to be copied.

Unloaded Storage
The image resumes at 5285H. The 104 bytes from 521DH to 5284H are not written by any load record; they are the filespec build area at 521DH, the destination file control block at 523DH, the keyboard reply and date scratch fields at 525DH and the system date buffer at 527DH. They are working storage and hold whatever was in memory when the utility was loaded.

5285H - Endings, Disk Mounting and the Disk Operation Stubs

The second load record opens with a two-byte cell and then runs into the block of subroutines that both backup engines share. Everything here survives the block move that brings an engine down to 5A00H, which is why the endings, the prompt machinery and the disk operation stubs live in this range rather than inside either engine. The block holds the three ways the utility can finish, the routine that puts the resident interrupt vector back and clears the work space, the two routines that mount and verify the source and destination disks, the flashing prompt loop, and the eight two-byte stubs that reach the floppy driver.

Overlapping Code
The three bytes 01 3E 20 at 529DH are read two ways. Entered from 529BH the leading 01H makes them a load of Register Pair BC, which changes nothing and leaves the error number 11H that 529BH put in Register A. Entered at 529EH the 01H is skipped and the remaining two bytes load Register A with 20H. One three-byte sequence therefore provides two error exits, and both of them fall into the common handler at 52A0H.

5487H - The Shared Message Block

The remainder of the second load record is text, not code. These ten messages are the ones both backup engines need, which is why they sit below 5A00H where the block move that brings an engine down cannot reach them. Three terminators are in use and they are not interchangeable. A 0DH ends the line. A 03H leaves the cursor where it is, which is what a prompt needs. A leading 1DH returns the cursor to the start of the current line and a following 1EH clears to the end of it, so a message that begins with that pair overwrites the line it is on rather than scrolling the screen, and that is how the flashing prompt loop at 53FEH alternates a prompt against a blank line without disturbing anything above it.

Unloaded Storage
The image resumes at 5A00H. The 1032 bytes from 55F8H to 59FFH are not written by any load record and are the largest gap in the file. They are the geometry scratch and the source file control block at 55F8H, the saved copy of the source disk's Granule Allocation Table sector at 5700H, the destination's at 5800H, and the general 256-byte sector buffer at 5900H. The two Granule Allocation Table copies are addressed at true Granule Allocation Table offsets throughout the file, so 5760H and 5860H are the lock-out maps, 57CCH and 58CCH the configuration words, 57CEH and 58CEH the master-password hashes and 57D0H and 58D0H the eight-character disk names.

5A00H - Front End Entry and Command Line Parsing

The transfer address named by the type-02 load record is 5A00H, so this is the first instruction BACKUP executes. The front end sets up its stack, signs on, and takes the command line apart: the optional leading minus sign, the file name, the extension, and the two drivespecs, prompting for either drivespec that the command line did not supply. Note that this whole block is temporary. Once the front end has decided which kind of backup to run, the selector at 6C00H moves one of the two engines down over it, and every address in this range becomes part of that engine.

5A7FH - Parameters, the Single Drive Test and the DATE Range

The parameter list in brackets is handed to the resident @PARAM service, which writes each value into the cell the table at 6D74H names. The two drive numbers are then exclusive-ORed together into 53DCH, the byte that tells the rest of the utility whether this is a single-drive backup, and a single-drive backup under a job is refused outright because there is nobody at the keyboard to swap disks. The DATE string is parsed into the two packed bounds at 5201H and 5203H, and the SYS, INV and MOD switches are folded into the attribute selection byte at 5210H in the bit positions a directory record uses.

5AF9H - The Backup By Class Decision and Mounting the Source

The manual says a backup by class is done when the user specifies a partspec or any parameter except X or MPW. That rule is implemented literally, as one chain of ORs over the ten cells that are neither X nor MPW, and the answer is planted in the first instruction of the engine selector. The source disk is then mounted: SYS2/SYS is pre-loaded so that the open and initialise services are resident before any disk swapping begins, and the drive is selected, restored and read.

5B73H - Reading the Source Geometry and Mounting the Destination

The source disk's boot sector gives up its directory cylinder and its geometry, its Granule Allocation Table is read into 5700H, and its master password is checked. The destination is then mounted and put through the same sequence, with two extra refusals that only apply to it: a rigid drive can never be a mirror-image destination, and a write-protected destination cannot be written at all. The write-protect test is deliberately made twice over, from the status the controller returned and from bit 7 of the Drive Control Table specification byte, so that either source of the information is enough to stop the backup.

5C0EH - The Mirror Image Decision

This is where the manual's three kinds of backup are chosen between. A mirror image needs the size, the density and the number of sides to match, and all three live in the high byte of the Granule Allocation Table configuration word, so one exclusive-OR and one mask settle the question. A difference in cylinder count alone is not fatal and the operator is asked about it. Anything else, and any rigid destination, produces a backup reconstruct, which is reached by entering the selector one instruction past its class test so that the file-by-file engine runs whatever the class flag says.

5C72H - Ask About a Cylinder Count Mismatch

A short routine that displays the question, collects a reply and reports whether it was Y. It is the only question in the front end whose answer changes which engine runs.

5C89H - The Master Password Check

A disk still carrying the default master password is accepted without a word. Otherwise the password is taken from the MPW parameter if it was given and from the keyboard if it was not, hashed by SYS2/SYS through the supervisor stub at 6C6BH, and compared twice: once against the reserved bypass constant that SYS2 itself honours, and once against the hash stored in the disk's own Granule Allocation Table. A wrong password ends the backup with no retry.

5CB1H - The Filespec Character Filter

One routine fills both the file name mask and the extension mask. It accepts the digits, the letters in either case and the dollar sign that is the LDOS wildcard, folds lower case to upper so that the mask matches the form a directory record stores, and stops at the first character that is none of those, handing that character back to the caller so that the caller can see whether the field ended in a slash, a colon or something else.

5CCCH - The DATE Parameter Parser

The DATE parameter accepts four forms and this block handles all of them. A group of month, day and year is split on the slash into three fields stored downwards, each field is collected as exactly two digits, the year is moved into the right century and tested for a leap year, the month is range checked and the day is checked against the maximum-days table at 7006H, and the validated result is packed into the same two bytes a directory record uses at its offsets 01H and 02H so that the selection test later is a plain sixteen-bit comparison. Note that the leap-year adjustment modifies the February entry of that table in place and never puts it back, which is harmless because at most two dates are parsed in one run of the utility.

Unloaded Storage
The image resumes at 5E00H. The 174 bytes from 5D52H to 5DFFH are not written by any load record. Nothing in the front end refers to them, and they exist only because the next load record begins on a page boundary.

5E00H - Mirror Image Engine, Pack ID and Lock Out Map Tests

The mirror-image engine is loaded here at 5E00H but is assembled to run at 5A00H, over the front end. The selector at 6C06H moves it down before it is entered, so every address in the mnemonic column of these sections is 0400H below the address in the leftmost column, and the links follow the operand to the place the instruction is shown rather than the place it runs. The engine begins with the two tests that can refuse the whole backup before a single byte moves: the Pack IDs must match, and no cylinder that carries data on the source may be locked out on the destination.

Relocated Block
Everything from 5E00H to 6208H is loaded where it is shown and executed 0400H lower. An operand such as the jump at 5F54H reads 5AEEH because that is where the instruction it targets will be when the block move has been done; the link on that row goes to 5EEEH, which is where the same instruction is shown on this page. The two are the same instruction seen before and after the move. Only JP and CALL carry an absolute operand and therefore only those show a run-time address; the disassembler resolves JR and DJNZ from their displacements, so those operands are already the addresses shown in the leftmost column. Throughout these sections the descriptions cite the address as it appears on this page, which is also where the link goes. Note also that eight of the addresses in this range are written into by the front end before the move and mean something else entirely until then, which is why several rows below are marked as self-modifying in both directions.

5E4AH - Preparing the Destination and Marking It

The destination boot sector is read, given the source disk's directory cylinder and geometry if the disk is a dual-density one, and written back with a marker byte in its first position. That marker is how the destination is recognised for the rest of the run whenever the operator is asked to swap disks, and it is cleared again at 60B2H when the backup finishes.

5E7DH - Computing the Geometry and Planting It

The number of sectors in a cylinder, the number of sectors on a single-density cylinder 0, and the number of whole cylinders that will fit in the work space are all worked out once, here, and then written into eight separate immediate operands scattered through the three transfer loops. That is why the loops themselves contain no memory references for geometry: every constant they need has already been assembled into the instruction stream.

5ED2H - Suppressing the Clock

A sector transfer on a Model I is timed against the drive, and a clock interrupt in the middle of one loses data. The engine therefore saves the byte at 4012H inside the resident interrupt handler and writes a RET over it. Everything on the way out of the utility puts it back, and the note about the clock is displayed unconditionally because of it.

5EE7H - The Read Pass

Cylinders are copied in groups as large as the work space will hold. For each cylinder the engine merges the source allocation byte with the two lock-out maps, which both decides whether the cylinder is worth copying at all and builds the destination Granule Allocation Table entry at the same time. A cylinder with nothing on it is skipped entirely, and the two boot sectors on cylinder 0 are never read, so that the destination keeps its own bootstrap.

5F5EH - The Write Pass

The same cylinders are written out from the buffer, with the same merge repeated so that the pass knows which ones to skip. Only the directory cylinder is written with a deleted data address mark; everything else gets a normal one, which is the arrangement FORMAT/CMD lays down and which the file system depends on.

5FDCH - The Verify Pass

The third pass reads every sector back and checks its cyclic redundancy check without transferring anything, which is why it needs no buffer pointer. When it finishes the engine jumps back to the read pass to start the next group of cylinders.

603FH - Finishing the Mirror Image

With every cylinder copied, the destination is given the source's identity and the current system date, its Granule Allocation Table is written and verified, the modification flags are cleared throughout both directories, the two boot sectors are patched to name the new directory cylinder, and the destination's old directory cylinder is erased back to the state FORMAT/CMD left it in if the new directory has landed elsewhere. Every one of these steps corresponds to a sentence in the manual.

6148H - The Three Digit Number Formatter

A small routine that writes a value into three characters by repeated subtraction, presetting the hundreds and tens to blanks so that leading zeros are suppressed and the units to the character zero so that a value of zero still displays. It is what keeps the cylinder number on the progress line readable as it counts up.

616EH - The Not Mirror Image Exit

Reached only from the lock-out map walk, before any data has been moved.

6174H - The Mirror Image Engine Message Block

The last 149 bytes of the third load record are the engine's own text. They sit above the code rather than below it because the block move that brings the engine down to 5A00H carries them with it, so the engine reaches them at 5D74H onwards once it is running. The three progress lines all begin with 1DH, which is what lets the cylinder number be rewritten in place instead of the screen scrolling once per cylinder.

Unloaded Storage
The image resumes at 6300H. The 247 bytes from 6209H to 62FFH are not written by any load record. The block move at 6C0FH copies 0500H bytes rather than the 0409H the engine actually occupies, so part of this gap is carried down with the engine and lands harmlessly above it.

6300H - File By File Engine, Setup and the System Disk Slots

The file-by-file engine serves both a backup by class and a backup reconstruct, which the manual says function identically. It is loaded here at 6300H and assembled to run at 5A00H, so every address in the mnemonic column of these sections is 0900H below the address in the leftmost column, and the links follow the operand to where the instruction is shown on this page. Only JP and CALL carry an absolute operand and therefore show a run-time address; JR and DJNZ are resolved from their displacements and already read as the addresses in the leftmost column. The engine begins by working out how much the destination disk holds, disabling a check that only a mirror image needs, and, when the SYS parameter was given, reserving the fifteen directory slots the system files must occupy.

Data, Not Instructions
The ten bytes at 63E0H are data and the two bytes at 63EAH and 63EBH that follow them are the two abandon-this-file exits, which the selection tests reach from a dozen places. A disassembler reading straight through this range resynchronises three bytes late, so the addresses either side of it have to be taken from the code that jumps into them rather than from the listing.

63EAH - The Directory Scan and the Selection Tests

The scan walks the Hash Index Table rather than reading every directory sector, because a zero byte there means a free record and can be rejected without touching the disk. For each occupied slot the directory record is read and put through the tests in the order the manual describes them: allocated and primary, then the SYS and INV classes, then the partspec with its wildcard and its optional negation, then the date range. Only a file that survives all of them is worth building a file specification for.