TRS-80 DOS - NEWDOS/80 v2.0 for the Model I - LMOFFSET Disassembled

LMOFFSET

Other Navigation

LMOFFSET/CMD (APPARAT LOAD MODULE OFFSET PROGRAM, VERSION 2.0) reads a load module from disk or from a SYSTEM tape, shows where it loads, and writes it to disk or tape again, optionally at a new load address. It does not relocate the code itself. When a new load base is given, every object code record at 4000H or above is simply given a new load address (the offset), so that DOS can load the module without overwriting itself. An appendage is then normally added: a few bytes of code, loaded just past the module, that become the new entry point, copy the program back to its original addresses and start it. The DOS-disabled appendage also has the operator reset into non-disk BASIC first, so that programs that use the DOS area can be run from a DOS disk. The manual describes the program in section 6.3.

The file loads at 5372H-58C5H and 5906H-5D81H (2,512 bytes) and starts at 537CH. The 64 bytes at 58C6H-5905H are not in the file: they are the appendage patch area, cleared at start-up. LMOFFSET uses the memory just below itself for its buffers and everything above 5E9BH, up to the top of memory given at 4049H, to hold the module.

Program Flow

Module Buffer Records

Load Range and Offset

The Appendages

Address Range	Purpose
3C3CH-3C3FH	Tape Status - the characters shown while a tape is read or written (see Module Buffer Records).
3840H	Keyboard Row 6 - bit 3 is the up-arrow key (583BH).
4049H-404AH	Top of Memory - the module buffer may not go past this address (5480H).
5200H-52FFH	Sector Buffer - for the source and destination files.
5300H-531FH	FCB - the filespec is typed straight into it (5521H), then it is used to open the file.
5332H-5371H	Input Buffer - 64 bytes for replies (5896H).
5372H	No-Appendage Flag - 01H = no appendage (no new load base, or suppressed); 00H = attach one.
5373H	Output Phase Flag - set to 01H when a destination is asked for (56E6H).
5374H-5375H	Module Buffer Pointer - the last byte stored in the module buffer.
5376H-5377H	Lowest Load Address - of the object code records at 4000H or above (starts at FFFFH).
5378H-5379H	Highest Load Address - the last byte loaded by those records (starts at 0000H).
537AH-537BH	Load Offset - new load base minus the lowest load address.
56D7H	DOS-Disable Choice - operand of LD A,00H: 00H = DOS enabled, 0BH = DOS disabled (stored at 565BH).
58C2H-5905H	Appendage First Record - header (length at 58C3H, load address at 58C4H) and the 64-byte patch area (58C6H-5905H, not in the file).
5906H-5A04H	Appendage Code and Records - its operands are filled in at 55A6H, 55ECH and 5664H-56BAH.
5D82H-5E94H	Stack - the Stack Pointer starts at 5E95H.
5E95H-5E9AH	Tape Name - six characters, padded with spaces (5787H).
5E9BH-	Module Buffer - the module's records, up to the top of memory.

5372H - Program Variables

The first ten bytes of the file are the program's variables. They load with the same values that the start-up code at 537CH stores into them, so the program also works when it is restarted from 5889H.

537CH - Program Entry Point and Start-Up

The transfer address of LMOFFSET/CMD. Also reached from 5889H when the operator asks for another source file. Sets the stack, resets every variable, clears the 64-byte appendage patch area and displays the title.

53A9H - Ask for the Source: Disk or Tape

Repeats until the reply is exactly one character, D or T.

53BAH - Read a SYSTEM Tape: Find the Leader

The tape is read into the module buffer as load module records. Anything that is not part of a normal SYSTEM tape is kept in marker records (see Module Buffer Records), and a status character is shown in the top line of the screen: * at 3C3DH when reading starts (the ROM adds two more at 3C3EH-3C3FH when the sync byte is found), P at 3C3CH for bytes before the 55H header byte, I at 3C3DH for bytes between blocks, and C at 3C3EH for a bad checksum.

53DFH - Read a SYSTEM Tape: the Name

After the 55H, the bytes up to the first 3CH (object code block) or 78H (entry point) are kept in an FEH record. On a normal tape these are the six bytes of the module name.

53F8H - Read a SYSTEM Tape: Object Code Block

A tape block is 3CH, a count byte (00H = 256), the two-byte load address, the data and a checksum. It is stored in the disk load module format instead: 01H, a length byte equal to the count plus 2, the load address and the data. The checksum (the sum of the address bytes and the data) is checked but not stored.

5442H - Checksum Error

The block's data is already in the buffer. An FCH record of three bytes follows it: FCH, the checksum read from the tape and the checksum computed. It has no count, and 5733H does not accept it later (see Module Buffer Records).

5457H - Start a Marker Record

Stores the marker type in Register A and a two-byte count of zero after it. Returns HL pointing to the count and BC = 0000H, ready for 5492H.

5467H - Read a Two-Byte Address From the Tape

Reads the low byte and then the high byte into HL, storing both in the module buffer. Returns Register A = H.

5470H - Copy Bytes Into the Module Buffer

Copies Register B bytes from HL (00H = 256) to the end of the module buffer. Used to add the appendage (56CDH-56E3H). Returns HL pointing past the last byte copied.

5478H - Store a Byte in the Module Buffer

5478H reads a byte from the tape first. 547BH stores the byte in Register A after the last byte in the module buffer. If the buffer has reached the top of memory (the DOS high memory address at 4049H), it stops with INSUFFICIENT RAM MEMORY. All registers are preserved.

5492H - Store a Byte and Count It

Stores Register A in the module buffer, adds one to the count in BC and writes the count into the current marker record at HL (set up by 5457H).

549BH - Check a Load Address

Called for every object code record, with HL = the load address and Register B = the number of data bytes (00H = 256). Records below 3C00H, and records in the 3F00H page that run past 3FFFH, stop the program with SOURCE ILLEGAL LOAD-TO-MEMORY ADDRESS. Records that start in the display (3C00H-3FFFH) are accepted but are not counted in the load range, so they are never moved. Records at 4000H or above update the lowest and highest load addresses.

54CAH - Read a SYSTEM Tape: Entry Point

The 78H byte is followed by the two-byte entry point. It is stored as a disk transfer record: 02H, 02H and the address.

54DCH - Read a Load Module From Disk

Opens the source file and copies it record by record into the module buffer. The file is read through the alternate register set: HL' = the position in the sector buffer at 5200H, DE' = the FCB at 5300H, B' = the bytes left in the sector buffer. Every byte read is stored in the module buffer as it is. Object code records (01H) have their load address checked; a transfer record (02H) ends the file.

5521H - Ask for a Filespec

Displays the message at HL and reads up to 31 characters into the FCB at 5300H. Returns the Z FLAG set if the reply was empty. Otherwise it switches to the alternate register set and loads it for the DOS file routines: HL = 5200H (sector buffer), DE = 5300H (FCB), B = 00H (record length 256). Used for the source (54DFH) and the destination (56FFH).

5537H - Read a Byte From the Source File

Returns the next byte of the source file in Register A and stores it in the module buffer (547BH). Uses the alternate register set: B' counts the bytes left in the sector buffer and HL' points into it. When the buffer is empty the next sector is read into 5200H.

5547H - Read a Two-Byte Address From the File

Reads the low byte and then the high byte into HL, storing both in the module buffer.

5550H - Display the Load Information

Shows MODULE LOADS TO XXXX-XXXX for the module as it will load (the load range plus the offset). When an appendage is to be attached, the end address includes 4EH more bytes, the size of the DOS-enabled appendage; the DOS-disabled appendage is larger (137H bytes), but that choice is only made later (563EH). Then warns if the new start address is in the ROM or the DOS. Also reached from 55DEH and 55E6H after a new load base has been given.

5594H - Display the Entry Point and Ask for a New Load Base

With an appendage, the entry point is the first byte of the appendage, just past the module's last byte at its new address. Without one, it is the module's own entry point plus the offset; this is only the value displayed, since 561BH moves the entry point only if it lies inside the load range. The new entry point is also stored in the appendage's transfer record at 5A03H. Also reached from 55C3H when the reply is not valid hexadecimal.

55E9H - Move the Load Addresses

The operator has accepted the load base. The module's original entry point is saved in the appendage's move code at 59FFH. Then every record in the module buffer is walked through: marker records (FEH, FFH) are skipped (5733H), every object code record at 4000H or above gets the offset added to its load address, and the transfer address gets the offset only if it lies inside the load range. With an offset of 0000H nothing changes.

563EH - Ask Whether to Disable DOS

Only asked when an appendage is to be attached. The appendage is placed at the byte after the module's new last byte. With N the DOS-enabled appendage is used unchanged. With Y the addresses inside the DOS-disabled appendage are filled in and its first record is lengthened to C1H. The reply is also stored into the instruction at 56D6H, where 00H selects the DOS-enabled appendage. See The Appendages for their layout.

568FH - Fill In the Move Code and Add the Appendage

Fills in the move code at 59F3H-5A00H that both appendages end with: LD HL,new start / LD DE,original start / LD BC,length / LDIR or LDDR / JP original entry point. If the module now loads lower than its original address it is copied upward, so LDDR is used with the addresses of the last bytes. Then the transfer record at the end of the module buffer is removed and the appendage records (which end with their own transfer record) are added in its place.

56E6H - Ask for the Destination: Disk or Tape

Also reached from 587CH when the operator wants the same module written to another file.

570AH - Write the Module to Disk

Writes every record in the module buffer to the file in load module format. Marker records are skipped. Object code records and other record types are written unchanged; the transfer record is written last and the file is closed. The file registers are in the alternate set: HL' = the position in the sector buffer at 5200H, B' = a byte counter that reaches zero after every 256 bytes.

5733H - Check a Record Type

HL points to a record in the module buffer. Types below 20H are load module records: return the CARRY FLAG set, Register A = the type and HL unchanged. FEH and FFH are marker records made by the tape reader: step HL past the record (type, two-byte count and the bytes) and return with the NC FLAG and Register A = 00H. Any other type, including the FCH and FDH records the tape reader makes for checksum errors and extra bytes, stops the program with BAD MAIN MEMORY.

5744H - Write the Transfer Record and Close the File

The four bytes of the transfer record are written. If the sector buffer holds anything not yet written, it is written, and then the file is closed.

575CH - Write Bytes to the Destination File

575CH writes the byte at HL and the one after it, and returns Register B = that second byte (a length). 5760H writes the byte at HL, steps HL, and returns Register A = the next byte. Bytes are collected in the sector buffer at 5200H through the alternate register set; every 256 bytes the sector is written.

5771H - Fetch the Entry Point

Returns DE = the address in the last two bytes of the module buffer, which is the entry point of the module's transfer record.

577AH - Write to Tape: Ask for the Name

The name must be one to six characters, each a letter or a digit; it is padded with spaces to six characters at 5E95H. The message says the first character must be a letter, but the check is the same for every character, so a digit is also accepted first.

57AFH - Write to Tape: Header and Name

Waits for ENTER, then writes the leader, the sync byte, the 55H header byte and the six-character name.

57D2H - Write to Tape: the Records

Walks through the module buffer. Each object code record is written as a SYSTEM tape block: 3CH, the data byte count (00H = 256), the load address, the data and a checksum (the sum of the address bytes and the data). Marker records and record types other than 01H and 02H are not written. The transfer record ends the tape.

583AH - Before a Tape Operation

Only a RET. It is called before the tape is read (53BFH) and before the operator is asked to ready the tape for writing (57AFH).

583BH - Check the Up-Arrow Key

Reads keyboard row 6 at 3840H. If the up-arrow key (bit 3) is down, the current function is abandoned with FUNCTION CANCELLED BY OPERATOR. This is a jump, not a return, so the caller's return address is left on the stack; 537CH resets the stack when a new source file is started. Called while the tape is read or written and after every line typed (58A2H).

5846H - Error Exits

Each loads the address of a message and goes to 585FH. 5855H displays a DOS error instead.

585FH - Display a Message and Ask What to Do Next

Every function ends here: after DONE, an error or a cancel. If a destination was being written, the operator can write the same module to another file; otherwise, or after N, the operator can start another source module or go back to DOS.

5893H - Display a Message and Read a Reply

5893H displays the message at HL and reads up to 64 characters into the buffer at 5332H. 589BH reads a line into the buffer at HL with the maximum length in Register A. BREAK makes it read the line again; the up-arrow key is checked after every line (583BH). Lower case letters are changed to capitals. Returns HL = the buffer, Register B = the number of characters typed, Register A = the first character and the Z FLAG set if nothing was typed.

58C2H - Appendage: First Record Header and Patch Area

The appendage is kept here as ready-made load module records. This header starts its first object code record: type 01H, the length byte and the load address. The length is 50H for the DOS-enabled appendage (5D15H) and C1H for the DOS-disabled one (568DH); the load address is filled in at 5656H. 56CDH copies these four bytes and the 64 patch bytes after them into the module buffer. See The Appendages.

58C6H - Appendage Patch Area

Not part of the file: the file has no load record for 58C6H-5905H. 5388H sets these 64 bytes to zero, and they become the first 64 bytes of every appendage. The manual describes them as a patch area: code patched in here runs first when the output module is started, before the program is moved and before DOS is disabled.

5906H - DOS-Disabled Appendage: Save the Screen and Show the Instructions

This code is not run here. From 5906H to 5A00H it is copied into the module being written (56DEH-56E3H), where it runs at X+40H, X being the appendage's load address. The zero operands are filled in at 5664H-5687H. It saves the screen above the appendage, puts a jump at 42E9H (the start of the non-disk BASIC program area), shows the instructions and waits in a loop for the operator to reset the computer into non-disk BASIC.

592AH - DOS-Disabled Appendage: Instructions to the Operator

Displayed by 591FH. The text is split between the appendage's two records: 5985H-5988H in the middle is the header of the second record, which is not part of the text once the records are loaded. The manual gives the message as RECORD AND THEN PERFORM THE FOLLOWING INSTRUCTIONS and step 4 as ENTER "."; the file has DO THE FOLLOWING: and ENTER "/".

5985H - DOS-Disabled Appendage: Second Record Header

The second object code record of the DOS-disabled appendage: type 01H, length 7AH (120 data bytes: 5989H-5A00H) and the load address X+BFH, filled in at 5676H. 56E1H-56E3H copies this header, the record and the transfer record after it.

5989H - DOS-Disabled Appendage: Instructions, Continued

The rest of the message started at 592AH, ended by a carriage return.

59E8H - DOS-Disabled Appendage: Restore the Screen

Reached through the jump at 42ECH after the operator has started non-disk BASIC and answered SYSTEM with /. Runs at X+11EH. Copies the saved screen back and falls into the move code.

59F3H - Appendage: Move the Program and Start It

The end of both appendages. In the DOS-enabled appendage it runs at X+40H, straight after the patch area; in the DOS-disabled one it follows 59F1H. Moves the program from where the output module loads it back to its original addresses and jumps to the original entry point. The operands are filled in at 55ECH and 569FH-56BAH.

5A05H - Convert a Hexadecimal Number

Converts the characters at DE into HL. Register A = the number of characters. Returns the CARRY FLAG set if there are more than four characters or one of them is not 0-9 or A-F. Used for the new load base (55C0H).

5A25H - Write a Hexadecimal Number

5A25H writes DE as four hexadecimal characters at HL, 5A2AH writes Register A as two and 5A33H writes the low four bits of Register A as one. HL is left pointing past the last character. Used to fill in the XXXX fields of the messages.

5A3EH - Messages

All displayed through the SYS0 routine at 4467H. Messages ended by 03H leave the cursor on the same line for the reply; those ended by 0DH end the line. The XXXX fields are filled in by 5A25H before the message is shown.

5D15H - Reset the Appendage Length and Point to the Title

Called once at start-up (53A3H). Sets the length byte of the appendage's first record back to 50H, the DOS-enabled size, because 568DH changes it to C1H when DOS is to be disabled. Returns HL pointing to the title.

5D1EH - Unused Bytes

The last 100 bytes of the file are zero and nothing refers to them.