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

570AH - Write Module Data Blocks to Disk

After successfully opening the destination file, this section switches to the alternate register set (which maintains the disk write buffer state) and begins processing module data blocks from the buffer at 5E9BH. It reads each block header, identifies the block type (01H for data, 02H for transfer address, or other markers), and writes the appropriate output. The routine at 5733H checks each byte to determine if it's a valid block marker, and blocks are processed sequentially until all data has been written to disk.

5721H - Write Type 01H Data Block to Disk

This section handles type 01H data blocks, which contain the actual relocatable module code and data. It calls 575CH to read and write the block type byte (01H), then decrements Register B twice to account for the 2-byte load address that will be written separately. It calls 5760H twice to write the load address bytes (low byte, then high byte), then enters a loop calling 5760H repeatedly to write all remaining data bytes in the block. After all bytes are written, it loops back to 570EH to process the next block.

5733H - Check Block Marker and Skip Invalid Blocks

This utility subroutine examines the byte at (HL) to determine if it's a valid block marker. Bytes less than 20H (space) are considered valid block type markers (01H, 02H, etc.) and the routine returns with Carry clear and the byte in Register A. Bytes from 20H to FDH are considered padding or invalid and return with Carry set. Bytes FEH and FFH are special: the routine reads the following 2-byte length value, adds it to HL to skip past the entire block, clears Register A, and returns with Carry clear. This allows the main loop to efficiently skip over blocks that aren't needed (like error markers from tape reads).

5744H - Write Transfer Address Block and Finalize File

This section writes the type 02H transfer address block to the disk output. It calls 575CH twice to read and write the transfer address bytes (2 bytes), then switches to the alternate register set to check if there are any buffered bytes waiting to be written. If Register B (in the alternate set) is non-zero, it calls 443CH to flush the partial sector buffer. Finally, it calls 4428H to close the output file, switches back to the primary register set, displays the "DONE" message from 5C27H, and jumps to completion handling at 585FH.

575CH - Read Byte Count and Write Single Byte

This short subroutine calls 5760H to read a byte and get its count in Register A, then stores that count in Register B for the caller's use. It's a wrapper that provides the byte count in two places (A and B) for different calling conventions.

5760H - Read Source Byte and Write to Disk Buffer

This critical subroutine reads one byte from the source buffer (pointed to by HL in the primary register set), switches to the alternate register set, writes that byte to the disk output buffer (pointed to by HL'), increments the buffer pointer, decrements the sector byte counter (B'), and checks if a complete 256-byte sector has been filled. If the counter reaches zero (sector full), it calls 443CH to write that sector to disk, returning any error via the NZ flag and jumping to error handler 5855H. It also decrements H' to wrap the buffer pointer within a 256-byte page. The routine returns the byte in Register A.

5771H - Retrieve Buffer End Pointer

This utility subroutine retrieves a 16-bit pointer value that was stored at the end of the buffer area. It preserves HL on the stack, loads HL with the buffer pointer from (5374H), reads the 16-bit value in reverse order (high byte at (HL), low byte at (HL-1)) into Register DE, restores HL, and returns. This is used to get the saved end-of-buffer marker.

577AH - Tape Output - Get Module Name

This section handles tape output. It prompts the user to input a 1-6 character tape module name using the message at 5C79H ("INPUT 1-6 CHAR TAPE MODULE NAME"). The code validates that the first character is A-Z and subsequent characters are A-Z or 0-9, as per cassette tape naming conventions. It reads up to 6 characters, converting lowercase to uppercase, and validates each character against the allowed character sets. If validation fails, it re-prompts. Once a valid name is entered, it stores the name at 5E95H, pads to 6 characters with spaces, and prepares for tape write operations.

57AFH - Prepare Tape Write and Prompt User

After the tape module name is validated and stored, this section calls 583AH to prepare the tape system, then displays the message "REPLY ENTER WHEN TAPE POSITIONED AND IN RECORD MODE" at 5CC2H. It waits for the user to press a key (ignoring the specific key pressed), then disables interrupts (DI) and calls the ROM cassette write initialization routine at 0284H. It displays an asterisk at the top-right of the screen (3C3FH) as a record indicator, then writes the sync byte 55H followed by the 6-character module name to tape.

57D2H - Write Module Data Blocks to Tape

This section implements the main tape write loop that processes all module data blocks from the buffer at 5E9BH. It reads each block type byte and handles them accordingly: type 01H blocks contain data with optional relocation bitmaps, type 02H blocks contain the transfer address (entry point). For type 01H blocks, it writes the '<' continuation marker, the block length, load address, and all data bytes, computing a checksum as it goes. After all data blocks, it toggles the screen indicator and continues reading. The loop processes blocks sequentially until reaching the end marker or type 02H transfer address block.

57F0H - Write Type 01H Data Block to Tape

This section writes a type 01H data block to tape with full checksum validation. It first writes the '<' (3CH) continuation marker, then reads the block length from (HL+1), subtracts 2 to account for the load address bytes, and writes this adjusted length. It then reads the 16-bit load address and writes both bytes, accumulating them in the checksum (Register C). The code then enters a loop to write all data bytes, adding each to the checksum. After all data bytes are written, it writes the final checksum byte to tape, re-enables interrupts briefly via 583BH, toggles the screen indicator, and loops back to process the next block.

5827H - Write Transfer Address and Complete Tape Output

This section is reached when a type 02H transfer address block is encountered, signaling the end of the module data. It writes the 'x' (78H) completion marker to tape, then skips the block type and length bytes by incrementing HL twice. It reads the two transfer address bytes from the buffer and writes them to tape. Finally, it jumps to 5756H to display the "DONE" message and complete the operation.

583AH - Tape Preparation Hook (Placeholder)

This is a placeholder subroutine for tape system preparation. It simply returns immediately, allowing the code structure to call this address for initialization hooks without actually executing any code. This may be used for hardware-specific setup in modified versions of the utility.

583BH - Check BREAK Key and Allow Abort

This subroutine checks if the BREAK key is currently pressed by reading keyboard memory location 3840H and testing bit 3. If the BREAK key is not pressed, it returns immediately. If BREAK is pressed, it loads HL with 5CF6H (pointing to "FUNCTION CANCELLED BY OPERATOR" message) and falls through to 585FH to display the message and exit gracefully, allowing the user to abort long tape operations.

5846H - Error Handler - Bad Main Memory

This error handler is reached when a memory validation check fails. It loads HL with 5C69H pointing to "BAD MAIN MEMORY" message and jumps to 585FH to display it. This indicates that memory tests detected corruption or hardware problems during the relocation process.

584BH - Error Handler - Illegal Load Address

This error handler is reached when the module specifies an invalid or illegal load-to-memory address. It loads HL with 5C01H pointing to "SOURCE ILLEGAL LOAD-TO-MEMORY ADDRESS" message and jumps to 585FH to display it.

5850H - Error Handler - Bad Module Format

This error handler is reached when the source module has an invalid or corrupted format that cannot be processed. It loads HL with 5BD0H pointing to "SOURCE MODULE BAD FORMAT" message and falls through to 585FH to display it.

5855H - DOS Error Handler

This error handler is reached when a DOS operation (file open, read, write, close) returns an error code. It takes the error code in Register A, sets bit 6 and bit 7 (OR C0H) to form the DOS error number, calls DOS routine 4409H to convert the error code to an error message, then falls through to display the message. This provides user-friendly error messages for all disk I/O failures.

585CH - Error Handler - Insufficient RAM Memory

This error handler is reached when the buffer write pointer exceeds the available memory limit, indicating insufficient RAM to complete the relocation. It loads HL with 5BE9H pointing to "INSUFFICIENT RAM MEMORY" message and falls through to display it and handle the error.

585FH - Display Message and Prompt for Another Operation

This is the common completion/error message display routine. It calls DOS routine 4467H to display the message pointed to by HL, then calls 01F8H to reset DOS, and re-enables interrupts with EI. After displaying the message, it checks the disk output mode flag at (5373H). If disk mode was active (flag = 01H), it displays "ANOTHER DESTINATION FILE? (Y OR N)" and processes the response. If 'Y', it loops back to destination prompting at 56E6H. If 'N' or disk mode wasn't active, it displays "ANOTHER SOURCE FILE TO PROCESS? (Y OR N)". If 'Y', it returns to the program entry point at 537CH to start over. If 'N', it exits to DOS at 402DH.

5893H - Display Message and Get User Input

This versatile subroutine displays a message and gets user keyboard input. It calls 4467H to display the message pointed to by HL, sets up a 64-byte input buffer at 5332H, then calls ROM routine 0040H in a loop to wait for keystrokes. It processes each keystroke through 583BH (which checks for BREAK key abort), converts lowercase to uppercase, and continues until ENTER (0DH) is pressed. It returns with the character count in Register B, the last character in Register A, and Z FLAG set if the input was just ENTER (empty string). The routine handles BREAK key detection for user abort capability.

58C2H-58C5H - Data Area and Utility Subroutines

This section contains variable storage, bootstrap code templates for DOS-disabled mode, and utility subroutines for hexadecimal conversion. The area from 58C2H includes configuration bytes and parameters that get copied into the output file header. This is followed by bootstrap code sections (5906H-5A02H) that are used when creating non-DOS executable modules, and hex conversion routines (5A05H-5A3DH) for displaying addresses and converting user input.

5906H - Bootstrap Code for DOS-Disabled Module (Template 1)

This section contains bootstrap code that gets embedded in the output file when DOS is disabled (flag C1H at 58C3H). This code executes after the module loads and performs system initialization. It clears the video RAM (3C00H-3FFFH, 1024 bytes), then copies 6 bytes from address 0000H to 42E9H (likely interrupt vectors or system parameters), loads HL with 0000H, calls a DOS display routine at 4467H, then enters an infinite loop at 5922H. This bootstrap ensures the relocated module can run in a non-DOS environment.

592AH - User Instruction Messages for DOS-Disabled Bootstrap

This section contains the text messages that appear when a DOS-disabled module boots. These instructions guide the user through the process of activating non-disk BASIC, initializing it, entering SYSTEM mode, and then executing the relocated module. The messages are stored as ASCII text with control characters for screen clearing (1CH + 1FH) and line feeds (0AH). The DEFM statements represent "DEFine Message" data.

5985H - Bootstrap Code Continuation

This section contains additional bootstrap code parameters and user instruction messages that continue from the previous section.

59E8H - Bootstrap Code Template 2

This section contains a second bootstrap code template that performs memory copying operations. It first clears video RAM (similar to template 1), then copies a variable-length block of memory from one location to another (both addresses and length are filled in at module generation time), and finally jumps to the module's entry point. This template is used for modules that need to relocate themselves or copy initialization data before execution.

5A01H - Data Area and Configuration Bytes

This section contains configuration bytes and data storage used during the module relocation process. These bytes are read and written by the main program to store temporary values, flags, and calculated addresses.

5A05H - Convert Hexadecimal String to 16-Bit Binary

This utility subroutine converts a hexadecimal string (pointed to by DE) into a 16-bit binary value in Register HL. It processes B hex digits (typically 4 for addresses), validating each character as 0-9 or A-F. The routine shifts HL left 4 bits for each digit and adds the new digit value. For digits 0-9, it subtracts 30H; for A-F, it subtracts 37H (30H + 7). If any character is invalid or the digit count is too large, it returns with Carry flag set to indicate an error. This routine is used to parse user-entered hexadecimal addresses.

5A25H - Convert 16-Bit Binary to Hexadecimal ASCII String

This utility subroutine converts a 16-bit binary value in Register DE into a 4-character hexadecimal ASCII string, storing the result at the memory location pointed to by HL. It processes the high byte (D) first via a CALL to 5A2AH, then processes the low byte (E). The routine at 5A2AH handles one byte by calling 5A33H twice: once for the high nibble (after 4 right rotations) and once for the low nibble. Each nibble is converted using a BCD adjustment algorithm that produces ASCII hex digits '0'-'9' or 'A'-'F'.

5A2AH - Convert Single Byte to Two Hex ASCII Characters

This subroutine converts one byte (in Register A) into two ASCII hex characters. It saves the byte on the stack, rotates it right 4 times to get the high nibble, converts that nibble to ASCII via 5A33H (storing at (HL)), increments HL, restores the original byte, and converts the low nibble to ASCII. Each nibble conversion uses the BCD adjustment trick: add 90H, decimal adjust, add 40H with carry, decimal adjust again. This produces '0'-'9' for values 0-9 and 'A'-'F' for values 10-15.

5A33H - Convert Single Nibble to ASCII Hex Character

This clever subroutine converts a nibble value (0-F in the low 4 bits of Register A) into its ASCII hex representation ('0'-'9' or 'A'-'F'). It uses the Z80's Decimal Adjust Accumulator (DAA) instruction in a creative way: mask to 4 bits, add 90H, DAA, add 40H with carry, DAA again. This produces ASCII '0' (30H) through '9' (39H) for input 0-9, and 'A' (41H) through 'F' (46H) for input 10-15. The result is stored at (HL) and HL is incremented.

5A3EH - Data Area and Program Messages

This section contains two data bytes followed by all the text messages used by the LMOFFSET utility. The messages are stored as ASCII text with terminators: 0DH (carriage return) for display messages and 03H for input prompts. The DEFM (DEFine Message) statements represent the actual text strings stored in memory.

5D15H - Initialize Display and Return Title Message Address

This small utility subroutine is called at program initialization. It stores 50H at location 58C3H (initializing a mode flag), loads HL with 5A3EH (the address of the program title "APPARAT LOAD MODULE OFFSET PROGRAM, VERSION 2.0"), and returns. The calling code then uses this address to display the title message.

5D1EH-5D81H - Padding Area (End of Program)

This section contains 100 bytes of NOP instructions (00H) that pad out the program to its final size. This padding ensures the program occupies a complete block and may provide space for future modifications or patches. The program ends at 5D81H, with the entry point documented as 537CH.