TRS-80 - BASIC Utility

BASIC/CMD

Other Navigation

BASIC/CMD is the Disk BASIC extension module for TRS-80 Model III TRSDOS 1.3. This overlay provides all disk file I/O capabilities to BASIC programs, transforming the cassette-based Level II BASIC into a full-featured Disk BASIC environment.

The module occupies memory from 4152H to approximately 64DCH (approximately 8.5KB) and provides a comprehensive set of file handling commands including:

• File Operations: OPEN, CLOSE, KILL, NAME (rename), LOAD, SAVE, RUN, MERGE
• Sequential File I/O: INPUT#, PRINT#, LINE INPUT#
• Random Access File I/O: GET, PUT, FIELD, LSET, RSET, LOC, LOF, EOF
• Device Control: CMD (output redirection to devices)
• System Commands: SYSTEM (exit to TRSDOS), FILES (directory listing)

The program entry point is at 614DH, which initializes the Disk BASIC environment. Upon entry, the module:

1. Saves the current BASIC program pointer and system state
2. Initializes file control blocks and buffer areas
3. Copies ROM BASIC vectors to RAM for modification
4. Prompts for the number of file buffers (if not specified)
5. Displays the copyright banner: "S-80 Model III Disk BASIC Rev 1.3"
6. Transfers control to the BASIC READY prompt

The jump table at 4152H-41E2H provides entry points that are called by the BASIC interpreter when disk-related tokens are encountered. Each entry is a 3-byte JP instruction redirecting to the appropriate handler routine.

File Buffer Structure: Each open file requires a 360-byte (168H) buffer area. The module supports up to 15 simultaneous open files, with buffer space allocated at initialization based on user specification. File Control Blocks (FCBs) track file status, current position, record length, and buffer pointers.

Address	Bytes	Purpose
5200H-5202H	3	File open/close state flags - Byte 0: FFH if file operations active, Byte 1: verify flag, Byte 2: initialization flag
40A0H	2	BASIC memory top pointer (system variable, preserved/restored)
40A4H	2	String space pointer / File buffer base address
40A7H	2	Input buffer pointer for LINE INPUT# operations
40AFH	1	Variable type flag (1=integer, 2=string, 3=single, 4=double)
40B1H	2	Program end pointer
40B3H	2	Array variable pointer
40D3H	1	Temporary storage for string operations
40D4H	2	Temporary pointer for string descriptor
40D6H	2	String temporary pointer
40D8H	2	Saved HL pointer for array operations
40DCH	1	Array dimension flag (80H = processing dimensions)
40DFH	2	Saved HL for OPEN command processing
40ECH	2	Current line number for error reporting
40F3H	2	Saved file pointer for sequential operations
40F9H	2	End of file buffer area pointer
4121H	2	Variable pointer for DIM operations
4204H	2	Error handler vector (points to ROM error routine)
4272H	2	Temporary storage for SYSTEM command HL preservation
4274H	2	Secondary temporary for CMD "O" operations
426DH	1	Maximum file number allowed (0-15)
426EH	1	Verify flag - 'V' (56H) if verify enabled, 0 otherwise
426FH	2	Saved state for file operations (copied from 5200H)
427AH	1	SYSTEM command active flag (FFH = returning to DOS)
42AEH	1	BREAK enable flag (C9H=RET for enabled, C3H=JP for disabled)
442BH	1	DOS file access mode flags
442FH	1	ROUTE/DUAL flag (80H=ROUTE, FFH=DUAL, 00H=Neither)
4411H	2	DOS high memory limit
441FH	1	DOS version check byte (must be >= 13H for TRSDOS 1.3)
5868H-587BH	20	Error address lookup table (10 entries × 2 bytes)
59A8H-59BDH	22	Keyword strings: "LIST", "EDIT", "DELETE", "AUTO" with length prefixes
59BEH-59C7H	10	String "READY " for display matching
6126H-614CH	39	DOS error code to BASIC error code translation table
6301H-6319H	25	String: "Use TRSDOS 1.3 or Later" + CR + NUL
631AH-6328H	15	String: "How Many Files?" (prompt for file buffer count)
6329H-638EH	102	Copyright banner: "S-80 Model III Disk BASIC Rev 1.3" + date + copyright
638FH-63A1H	19	Free bytes display template: "00,000 Free Bytes 00 "
63A2H-63A5H	4	Disk geometry data copied from DOS
63A6H-63AEH	9	String: "Variable Files" (file type indicator)
63AFH-63B5H	7	String: "Files" + CR + NUL (alternate file type indicator)
63B6H	1	Record length for current file operation
63BCH	1	Last DOS error code encountered
63BDH	1	Read/Write direction flag (0=read, non-zero=write)
63BEH-63BFH	2	Current file's FCB pointer (0000H if no file active)
63C0H-63C1H	2	Current file buffer base pointer
63E0H-63E1H	2	Last allocated buffer end pointer
63E2H	1	EOF flag for current read operation (F1H=EOF, 0=not EOF)
63E3H	1	Saved file count during nested operations
63E4H	1	Command type marker (2AH='*' for RUN with files)
63E5H-63E6H	2	Saved string space pointer during initialization
63E7H-63E8H	2	Saved file count pointer during initialization
63E9H-63EAH	2	Saved memory top during initialization
63EBH	1	Initialization complete flag
63ECH	1	Memory size specified flag for -M option
63EDH	1	Files specified flag for -F option
63EEH-63EFH	2	Saved command line pointer at entry
63F0H-6349H	90	Command line copy buffer for RUN command parsing
6350H-6367H	24	Filename buffer for file operations (null-terminated)
64DCH+	varies	File buffer area - 360 bytes (168H) per open file, allocated at initialization

4152H - DISK BASIC JUMP TABLE

This is the primary dispatch table for Disk BASIC commands. When the BASIC interpreter encounters a disk-related token, it calculates the offset into this table and executes the corresponding JP instruction. Each 3-byte entry redirects to the actual command handler. The table contains 32 entry points covering all file I/O and disk system commands.

5200H - FILE STATE FLAGS AND ARRAY DIMENSION HANDLER

This section contains three flag bytes at 5200H-5202H that track file operation states, followed by the array dimension handler for disk file operations. The routine at 5203H processes DIM statements for arrays that will be used with random access files. It validates the number of dimensions and stores array bounds.

523AH - DIM STATEMENT DISK HANDLER

This is the main entry point for the DIM statement when disk file support is active. It calls the dimension processor at 522EH, then checks the variable type and sets up the array descriptor pointer. Entry: HL points to BASIC text. Exit: Array is dimensioned, HL points past the dimension specification.

5276H - ARRAY SUBSCRIPT PROCESSING AND STORAGE

This section processes accumulated array subscripts from the stack and stores dimension bounds into the array descriptor. It handles the closing parenthesis verification and stores subscript values into the appropriate memory locations. Entry: Stack contains dimension values, HL points to array descriptor, DE points to BASIC text.

52FFH - DEFUSR STATEMENT HANDLER

Handles the DEFUSR statement which defines the entry address for a USR machine language function. Syntax: DEFUSR[n]=address where n is 0-9. The address is stored in a lookup table at 5868H.

5322H - USR FUNCTION HANDLER

Handles the USR function call which invokes a machine language routine previously defined with DEFUSR. Entry: HL points to text after USR token, optional digit 0-9 specifies which USR slot. Exit: Returns result from machine language routine in the numeric accumulator.

5342H - USR NUMBER PARSER

Parses the optional digit (0-9) after USR to determine which USR slot to use. If no digit follows, defaults to USR0. Returns pointer to the 2-byte address entry in the USR table at 5868H. Entry: HL points to BASIC text. Exit: DE = pointer to USR table entry, HL = updated text pointer.

5354H - ALTERNATE DEFUSR HANDLER

Alternate entry for DEFUSR when preceded by token C1H. Parses the USR number and stores the address value into the USR table.

5363H - UNDEFINED ARRAY ERROR HANDLER

Generates error code 2EH (Undefined array) when an array is referenced that hasn't been dimensioned. Jumps to the standard BASIC error handler.

5368H - CMD Statement Pre-Check Routine

This routine is called before processing CMD statements that require a file number. It checks if the next token is the USING keyword (token CEH) and if so, returns immediately with Z flag set. Otherwise, it validates that the current variable contains a valid file number and jumps to the file number validation routine at 5A46H.

5374H - CMD Statement Main Handler (Device Dispatcher)

This is the main entry point for the CMD statement. It evaluates a string expression to get the device/option code, then dispatches to the appropriate handler based on the first character. CMD supports: D (DOS directory), L (LOAD command string), P (PRINT# position), J (JKL system), Z (ZONE settings), C (cassette options), O (file rename), X (DOS exit), B (BREAK on/off), E (video enable), T (tape operations), R (cassette read), S (SYSTEM), A (SYSTEM with carry), & (debug/special), and I (immediate DOS command).

53D5H - CMD "R" Handler (Cassette Read Mode)

This handler activates cassette read mode by calling the ROM cassette initialization routine at 0298H. After setup, it re-enables interrupts and returns to BASIC.

53DAH - CMD "T" Handler (Tape Motor Control)

This handler controls the cassette tape motor by calling the ROM routine at 02A1H. This allows BASIC programs to start/stop the tape motor programmatically.

53E0H - CMD "I" Handler (Immediate DOS Command)

This handler executes an immediate TRSDOS command from a string. It expects the syntax CMD "I,command" where "command" is the DOS command string. The routine copies the command to the DOS command buffer at 4225H and calls the $COMDOS routine at 4299H to execute it.

5410H - CMD "E" Handler (Video Enable Control)

This handler controls video output by calling DOS function at 4409H. It reads the last DOS error code from 63BCH, ORs it with C0H (setting bits 6 and 7), and passes this value to the video control routine. This enables or configures video display output.

541AH - CMD "D" Handler (DOS Directory with Options)

This handler processes the CMD "D" command which displays a directory listing with optional filtering. The rest of the CMD string contains filter options that are passed to the DOS directory display routine at 4419H. The format is CMD "D:filter" where filter specifies what files to list.

5427H - LINE INPUT Statement Handler

This is the entry point for the LINE INPUT statement. It handles both LINE INPUT# (file input) and LINE INPUT (keyboard input). The statement reads an entire line of text into a string variable without parsing. If a # symbol follows, it redirects to the LINE INPUT# handler at 5AC9H.

5451H - Clear File Buffer Pointer Routine

This utility routine clears the current FCB (File Control Block) pointer at 63BEH to indicate no file is currently active. It's called when closing files or when file operations complete.

5459H - PRINT# File Number Check Routine

This routine validates the file number for PRINT# statements. It expects A to contain '#' (23H) when called. If '#' is present, it advances to get the file number and validates it for output. If not '#', it returns to normal PRINT handling.

5471H - Check if Output to File Active

This routine checks whether output is currently being directed to a file (vs console). It examines the FCB pointer at 63BEH - if it's zero, no file output is active. If non-zero, it checks if the return address indicates we're coming from the right place in the PRINT routines and redirects accordingly.

5487H - CMD "&" Handler (Debug/Special Operations)

This handler processes the CMD "&" command which provides special debug and memory poke operations. The format is CMD "&&" (double ampersand required). It then calls a data table interpreter at 563FH with a pointer to the operation table at 549BH. This allows direct memory manipulation and system control.

549BH - CMD "&" Operation Data Table

This is a data table used by the CMD "&" debug handler. It contains encoded operations for memory manipulation, system control, and special functions. The data is interpreted by the routine at 563FH. Each entry specifies a memory address and operation to perform. The table is XOR-encoded with 55H for obfuscation.

54F3H - CMD "L" Handler (LOAD Program from String)

This handler processes the CMD "L,filename" command which loads a program file. The filename is taken from a BASIC string expression following the comma. The routine copies the filename to the DOS command buffer at 4465H (with CR terminator) and calls the DOS $LOAD routine at 4430H.

552DH - CMD "P" Handler (PRINT# Position)

This handler processes the CMD "P,expression" command which sets the print position for subsequent PRINT# output. It evaluates a string expression and stores the position information in a string variable descriptor, then formats the memory size value in a specific format for display purposes.

557CH - CMD "J" Handler (JKL System)

Executes the TRSDOS JKL system routine. The JKL system provides keyboard macro capabilities in TRSDOS.

The JKL system allows users to define keyboard macros. This handler preserves the return address around the DOS call to ensure proper continuation of BASIC command processing.

5594H - CMD "X" Handler (Exit to TRSDOS)

Exits BASIC and returns to TRSDOS operating system prompt.

The EXIT command terminates BASIC and returns control to TRSDOS. The code after the CALL at 5598H is never executed since the DOS exit routine transfers control directly to the operating system. However, it's included for consistency with other handlers.

559FH - CMD "Z" Handler (ZONE N/F - ROUTE/DUAL Settings)

Controls printer output routing: ZONE "N" enables ROUTE mode (duplicate output to printer), ZONE "F" disables it. The "Z" command syntax is: CMD "Z","N" or CMD "Z","F"

55ADH - Enable ROUTE/DUAL Mode (CMD "Z","N")

Enables printer output duplication - all screen output is also sent to the printer.

The DUAL mode works by redirecting both output vectors to a special handler at 4CE1H that duplicates all output to both the screen and printer. The original vectors are saved so they can be restored when DUAL mode is disabled.

55CDH - ZONE Command Exit Handler

Common exit point for ZONE command - checks for closing quote and returns.

55D4H - Check for 'F' (Disable ROUTE/DUAL)

Handles CMD "Z","F" to disable printer output duplication.

Disabling DUAL mode restores the original output vectors from their saved locations. This returns output routing to normal screen-only operation. The ROUTE/DUAL flag at 442FH is set to 00H to indicate disabled state.

55F4H - CMD "C" Handler (Cassette R/S Options)

Controls cassette tape operations: CMD "C" (read mode, E=02) or CMD "C","R" (read mode, E=02) or CMD "C","S" (write mode, E=00). This sets up the cassette system for either reading or writing.

NOTE: There's a bug in this code. When "R" is specified, E should be 02H (read mode), but the code path leaves E=01H. However, at 5602H it jumps to 560AH which calls 4281H. The cassette control routine at 4281H may handle E=01H as read mode, or this might be a minor bug that doesn't affect functionality. The correct values should be: E=02H for read, E=00H for write.

560AH - Execute Cassette Control

Calls the DOS cassette control routine with the mode in register E.

5610H - CMD "O" Handler (Rename File)

Renames a disk file. Syntax: CMD "O", oldname$, newname$ - The "O" command provides file renaming capability from BASIC.

The rename operation requires two string parameters. The DOS routine at 4284H expects the old filename pointer at 4272H and the new filename pointer at 4274H. Both filenames must be valid strings; empty strings cause a Type Mismatch error.

563FH - XOR-Encoded Table Interpreter

Processes XOR 55H encoded command tables. Used by CMD "&" handler to interpret encoded operation data. This routine reads a count byte, then XOR-decodes and outputs each subsequent byte.

This routine is used to decode the CMD "&" operation data table at 549BH-54F2H. Each byte in the table is XOR'd with 55H to produce the actual character to output. This simple encoding may have been used to avoid conflicts with special characters or control codes in the source file.

564BH - CMD "B" Handler (BREAK ON/OFF)

Controls CTRL+C break handling. CMD "B","N" enables breaks (stores C9H=RET at 42AEH). CMD "B","F" disables breaks (stores C3H=JP at 42AEH). This uses self-modifying code to enable/disable the break check.

565DH - Check for 'F' (Disable Breaks)

5666H - Store Break Control Byte and Exit

The BREAK control mechanism uses self-modifying code. Location 42AEH contains either RET (C9H) which allows breaks, or JP (C3H) which bypasses the break check. When breaks are disabled, the break handler immediately jumps past the break detection code. This is an efficient way to enable/disable a feature without conditionals in the time-critical break check routine.

566FH - NAME Statement Handler

Implements the NAME statement for renaming files. Syntax: NAME oldname$ AS newname$. This provides an alternative syntax to CMD "O" for file renaming.

The NAME statement closes all files before attempting the rename operation. This ensures that neither the old nor new filename is currently in use by an open file buffer. The actual rename processing is handled by the DOS routine at 427EH.

567BH - FILES Statement Handler

Implements the FILES statement for displaying disk directory. Syntax: FILES [filespec$] - If no filespec is provided, displays all files. This provides directory listing capability from BASIC programs.

5696H - Process FILES Command Parameters

This is a complex routine that appears to handle multiple parameter formats for the FILES command. The exact behavior continues in the next section starting at 56C8H. The routine manages string allocation and type checking for the directory listing parameters.

56C8H - FILES Handler String Comparison Loop

Continuation of FILES statement handler - performs string comparison and manipulation for directory filtering.

56DFH - Character-by-Character Comparison Loop

Compares source and destination strings character by character.

56F1H - Complete Match Found

Destination string completely matched against source - return position in source.

56FAH - Character Mismatch - Try Next Position

Characters didn't match - advance source position and retry.

This is a substring search routine used by the FILES statement to filter directory listings. It searches for a match of the destination string within the source string, returning the 1-based position if found, or 0 if not found. The algorithm tries every possible starting position in the source string.

5703H - &H/&O Number Parser (Hexadecimal and Octal Literals)

Parses hexadecimal (&H) and octal (&O) number literals. Returns 16-bit value in DE. Used by BASIC to support &H and &O number formats.

The parser recognizes three formats: &H for hexadecimal (base 16), &O for octal (base 8), and a bare & followed by digits which defaults to octal. This provides compatibility with various BASIC dialects.

570FH - Hexadecimal Number Parser (&H)

Parses up to 5 hexadecimal digits (supports 0-9, A-F). Result accumulated in HL, then moved to DE.

5723H - Process Hex Letter (A-F)

5729H - Shift and Add Hex Digit

5736H - Prepare for Octal Parse (No 'O' Specified)

5737H - Octal Number Parser (&O or bare &)

Parses octal digits (0-7). Result accumulated in HL, then moved to DE.

5754H - Finalize Number and Return

Common exit point for both hex and octal parsers. Converts result and returns.

The number parsers support hexadecimal (&H) and octal (&O or bare &) literals in BASIC expressions. Hexadecimal numbers can be up to 5 digits (though only 4 digits = 16 bits are typically used), and octal numbers can be any length until overflow. Invalid digits for the selected base cause appropriate errors. The final result is converted to BASIC's internal floating-point format before returning.

5759H - MID$ Statement Handler

Implements the MID$ statement for modifying a substring within a string variable. Syntax: MID$(string$, position [, length]) = replacement$. This allows in-place modification of strings.

The MID$ statement requires careful handling because it modifies strings in place. The code checks whether the string is in the string space (above memory top) or in the program area, as different handling is needed for each case. Strings in program space are literals and should not normally be modified.

5779H - Parse Position, Length Parameters, and Replacement String

57ABH - Perform String Replacement

Copies replacement characters into the target string at the specified position.

57C3H - Character Copy Loop

The MID$ statement replaces up to the specified number of characters in the target string with characters from the replacement string. If the replacement string is longer than the specified length or available space, it's truncated. If the replacement string is shorter, only those characters are replaced.

57CCH - Parse Optional Length Parameter

Helper routine to parse the optional length parameter in MID$ statement. Sets E to FFH if no length specified, otherwise evaluates the length expression.

57D7H - Verify Closing Parenthesis

57DAH - INPUT# Statement Handler

Reads data from a file using INPUT# statement. Checks if a file is open and routes to appropriate input handler.

57EEH - Read Characters from File Loop

Reads characters from file into input buffer, processing special characters.

5807H - Continue Reading Characters

580AH - Terminate Input Line

5813H - INPUT# Separator Check

Checks for field separators (comma, colon) when reading from a file with INPUT#.

The INPUT# handler reads up to 240 characters (F0H) from a file, stopping at CR (0DH). It masks the high bit of characters and skips leading LF characters. The data is placed in the input buffer at 40A7H and null-terminated.

5822H - INPUT with File Check

Checks whether INPUT should read from a file or keyboard, and routes accordingly.

5862H - Use Normal Keyboard INPUT

This section provides complex logic to determine whether INPUT should read from a file or the keyboard. It checks the FCB pointer at 63BEH to determine if a file is currently open for input operations. The code handles EOF conditions and routes to appropriate error handlers.

5868H - USR Function Address Table

Table of 10 addresses for USR(0) through USR(9) functions. All initialized to 1E4AH (Type Mismatch error handler). Users can POKE new addresses to redirect USR functions to custom machine language routines.

587CH - INPUT Statement Entry Point (No File)

Main entry point for INPUT statement when no file is open. Checks if this is a special editing command (LIST, EDIT, AUTO, DELETE) or regular INPUT.

This routine detects special editing keys: LF (line feed), '[', '.', and ',' all trigger line number input for editing commands. ESC cancels input. ^Z (1AH) is used for special commands. Regular characters go through the normal INPUT buffer processing.

58BBH - Get Current Line Number for Editing

Retrieves the current line number from system variable for use in LIST, EDIT, AUTO commands.

58BFH - Process Editing Command

Processes special editing commands like AUTO, EDIT, LIST, DELETE. Parses optional line number and validates the command.

58DCH - Check for Carry Flag from Line Number Parse

58DEH - Check for '[' Key

58E2H - Validate String Space Pointer

Checks if string space pointer has moved during command processing.

58F6H - Transfer Parsed Values

58F8H - Setup Command Parameters

Prepares registers for command execution - BC contains line number, DE contains next line pointer.

5923H - Compare Screen with "READY" String

Checks if "READY" appears on screen at the cursor position.

5930H - Restore Cursor and Execute Command

This section handles the interactive editing features. It detects "READY" on the screen and erases it before executing LIST, EDIT, AUTO, or DELETE commands. The cursor positioning code ensures clean display output. The routine at 2B33H handles the actual command execution based on the parsed parameters in BC (line number) and DE (next line pointer).

5938H - Command Keyword Detection (LIST/EDIT/DELETE/AUTO)

Identifies which editing command (LIST, EDIT, DELETE, AUTO) was entered and sets up parameters for execution.

5959H - Process Recognized Keyword

Keyword was recognized - extract length and setup for comparison.

596EH - Validate Complete Keyword Match

This routine uses SELF-MODIFYING CODE at three locations: 5975H (ADD nn), 598FH (LD HL,nnnn), and 5992H (LD C,nn). It expands abbreviated keywords (L, E, D, A) to their full forms (LIST, EDIT, DELETE, AUTO) by copying the full keyword text into the input buffer. The LDDR backwards copy prevents overwriting source data when the destination overlaps.

5997H - Exit Keyword Processing

5998H - Jump to Command Processor

599BH - Check for End of Keyword

Verifies that keyword is followed by valid delimiter (=, (, or CR).

59A8H - Keyword String Table (DATA)

Length-prefixed keyword strings for LIST, EDIT, DELETE, and AUTO commands.

59BEH - "READY" String (DATA)

10-byte string displayed at BASIC ready prompt: "READY" followed by 5 spaces.

The "READY" string is exactly 10 bytes to fill a line on the TRS-80 screen. It's used by the code at 5923H to detect and erase the READY prompt when executing editing commands.

59C8H - End of READY String / Code Boundary

59C9H - SYSTEM Statement Handler

Exits BASIC and returns to TRSDOS operating system. Closes all files and restores DOS environment before exit.

The SYSTEM statement performs a clean exit from BASIC. It sets the SYSTEM active flag to prevent re-entry, restores the original DOS state saved at initialization (5200H), sets up an error handler, closes all files to flush buffers and release resources, then transfers control back to TRSDOS. The carry flag determines which DOS entry point to use.

59E5H - Check File Open and Process

Validates that a file is open and processes file operations. Used by various file I/O statements.

59FDH - File Buffer Save Routine

Saves the current file FCB pointer and buffer pointer for later restoration.

5A0CH - File Buffer Restore Routine

Restores previously saved FCB and buffer pointers.

5A19H - LIST File Mode Check

Checks if a file is open for LIST output. If file is open, redirects to file output instead of screen.

This routine intercepts LIST commands when a file is open. Instead of displaying to the screen, it redirects the LIST output to the open file by removing the normal return address and jumping to a file-specific LIST handler.

5A23H - Memory Calculation Routine

Converts floating point value to integer and performs memory-related calculation. Used by file buffer allocation routines.

This routine multiplies the input value by 192 (C0H), which is the size of file buffer structures. This is used to calculate memory requirements for file buffers. The result is converted to a format suitable for memory allocation.

5A33H - Open File for Output Helper

Opens a file for output and saves the DOS state.

5A38H - Open File for Input Helper

Opens a file for input and saves the DOS state.

5A3BH - Save DOS State After File Open

Common routine to save DOS state after opening a file.

5A44H - File # Validation Helper (Expects '#')

Sets C=1 and falls through to check for '#' character.

5A46H - File # Validation (Called from 5371H)

Checks if next character is '#', returns if not. Used by PRINT#, INPUT#, etc.

5A59H - File # Parser

Parses file number after '#' character, validates range, and returns FCB pointer in BC.

The file number table at 63C0H contains 16 word pointers (32 bytes total) to FCB structures. Each file number (0-15) has a 2-byte pointer. The routine multiplies the file number by 2 (two ADD HL,DE) to index into this table. The FCB's first byte is the status: 00H=closed, non-zero=open.

5A7DH - MKD$ Function Handler

Converts double-precision floating point to 8-byte string representation.

5A80H - CVI Function Handler

Converts 2-byte string to integer value.

5A83H - CVS Function Handler (and common MKx$ processing)

Converts 4-byte string to single-precision value. Also serves as common code for MKI$/MKS$/MKD$.

5A96H - CHR$ Function Handler (Disk Version)

Extended CHR$ function supporting additional parameters for disk BASIC.

5A99H - MKI$ Function Handler

Converts integer to 2-byte string representation.

5A9CH - MKS$ Function Handler (and common CVx processing)

Converts single-precision to 4-byte string. Also common code for CVI/CVS/CVD functions.

The MKI$/MKS$/MKD$ functions convert numeric values to binary string representations, while CVI/CVS/CVD convert binary strings back to numbers. These are used for binary file I/O. The type codes are: 1=integer (2 bytes), 2=single (4 bytes), 3=double (8 bytes). The string length must be exact for the type being converted.

5AB3H - WRITE# Statement Handler

Implements WRITE# for formatted output to sequential files. Automatically adds delimiters (commas) between fields and quotes around strings. Syntax: WRITE# filenumber, expression [, expression...]

WRITE# uses specific delimiters: strings are enclosed in quotes (22H) and fields are separated by commas (2CH). Numeric values use space (20H) delimiter. This differs from PRINT# which doesn't add quotes or commas automatically.

5AC9H - LINE INPUT# Statement Handler

Reads an entire line from a file into a string variable. Syntax: LINE INPUT# filenumber, string$. Unlike regular INPUT#, this reads the complete line including commas and quotes as literal characters.

5ADDH - WRITE# Main Processing Loop

Core routine for reading and processing file data for WRITE# or LINE INPUT#. Handles quotes, delimiters, and special characters.

5AEEH - Check for Quote Character

5B00H - Character Processing Main Logic

5B32H - Check for Delimiter Match

5B3EH - Read Next Character

5B43H - Field Complete - Process Terminator

5B4CH - Skip Trailing Spaces/Quotes

5B5DH - Handle End of Line (CR Found)

5B66H - Decrement Record Counter

5B72H - Decrement Record Counter and Check for Refill

Decrements the record counter at (HL). If counter reaches FFH, reads next record from file. Returns Z flag set if counter is zero.

The record counter at FCB+7 tracks how many characters remain in the current buffer. When it reaches FFH (255), the buffer is exhausted and a new record must be read from disk. This automatic buffering makes sequential file access efficient.

5B8BH - Finalize Field Input

Terminates the input buffer, processes the field data, and returns to caller.

5B9EH - Space Delimiter Special Handling

5BA4H - Store Character in Input Buffer

Stores character in buffer if non-zero and space remains. Auto-exits if buffer full.

5BADH - LOAD/RUN/MERGE Common Entry

Common initialization for LOAD, RUN, and MERGE statements. Sets up parameters and jumps to main OPEN processing.

5BB3H - RUN Statement (File Version)

Loads and executes a BASIC program from disk. Syntax: RUN "filename"

The RUN statement accepts optional ",R" parameter to start execution. The RUN mode flag at 5200H is set to FFH to distinguish from LOAD. After loading completes, execution transfers to the newly loaded program.

5BD1H - RUN Statement Execution (Continued)

Completes RUN statement by clearing file number, setting EOF flag, and executing the loaded program.

5BD8H - LOAD Common Completion

Common exit point for LOAD and RUN. Sets up EOF flag, initializes buffer, and completes the load operation.

5BFEH - Load Program Into Memory

Main program loading loop - reads file data into memory until EOF or memory full.

The LOAD routine reads the program file byte-by-byte into the string space area, checking memory limits. After loading, it processes the program lines (1AF8H), links them properly (1B5DH), and if this is RUN (EOF flag = F1H), executes the program at 1D1EH.

5C38H - PRINT# Output Completion

Finalizes PRINT# statement output. Closes file if requested and cleans up.

5C4CH - Out of Memory During LOAD

5C52H - MERGE Statement Handler

Merges program from disk with current program in memory. Syntax: MERGE "filename"

5C60H - Execute MERGE Operation

5C6EH - MERGE/LOAD Record Processing

5C7BH - PRINT# Statement Handler

Outputs formatted data to a file. Syntax: PRINT# filenumber, expression [; expression...]

5C90H - SAVE Statement Handler

Saves current BASIC program to disk. Syntax: SAVE "filename" [,A]

5CA0H - Save Program in Binary Format

Saves program as tokenized binary format (default for SAVE without ,A option).

SAVE writes the program in tokenized binary format by default. The FFH marker at the start indicates binary format. The ",A" option (handled at 2B2EH) saves in ASCII format instead. Binary saves are smaller and faster but not human-readable.

5CB8H - CLOSE Statement Handler

Closes one or all open files. Syntax: CLOSE [#filenumber] or CLOSE (closes all files)

5CC0H - Close All Files Loop

Iterates through all file numbers and closes each open file.

5CD1H - Check for Additional Files to Close

5CD8H - Close Specific File Number

5CE9H - Close All Files Routine

Emergency close all files. Called by SYSTEM, errors, and program termination.

5CF3H - FIELD Statement Handler

Defines field structure for random access files. Syntax: FIELD #n, width AS stringvar [, width AS stringvar...]

5D0CH - FIELD Definition Loop

Processes each field definition in the FIELD statement.

5D2EH - Validate Field Width

5D39H - Store Field Descriptor

The FIELD statement maps string variables to sections of a random access file's record buffer. Each field has a width (in bytes) and a string variable name. The statement stores width and buffer address in the string descriptor (3 bytes: length, addr_low, addr_high). The field position is tracked and validated against the record length (63B6H) to prevent buffer overflow.

5D4BH - RSET Statement Handler

Right-justify string in field. Syntax: RSET stringvar = expression. Pads left side with spaces.

5D4DH - LSET Statement Handler

Left-justify string in field. Syntax: LSET stringvar = expression. Pads right side with spaces. RSET falls through to here.

NOTE: The SYNCHR at 5D56H uses D5H as the expected character. This is unusual - D5H is not the '=' character (which is 3DH). This appears to be an error or the bytes may be misaligned. The hex should be verified against the actual file.

5D7BH - Garbage Collection for Field Assignment

If destination is a temporary string, performs garbage collection to make room.

5DA2H - Get Source and Destination Pointers

5DB6H - Calculate Padding and Perform Copy

5DC0H - String Copy Loop

5DC6H - Zero-Length Field Cleanup

5DCBH - Pad Right Side (LSET)

5DD0H - Fill with Spaces Subroutine

Fills C bytes at (DE) with spaces (20H). Used for padding in LSET/RSET.

5DD9H - String Allocation Error Handler

5DE9H - Continue Error Recovery

5DEFH - EOF Function Handler

Tests if end-of-file reached for a file. Syntax: EOF(filenumber). Returns -1 (true) if at EOF, 0 (false) otherwise.

5E0EH - Return EOF Status

EOF checks if the current record number equals the last record number AND if the buffer position equals or exceeds the characters remaining. This indicates all data has been read. The function returns -1 (true) if at EOF, 0 (false) otherwise.

5E14H - File Close Helper

Internal file close routine. Validates file number and closes the file via DOS.

5E2AH - Clear File Buffer

5E33H - LOC Function Handler

Returns current record number for random access file. Syntax: LOC(filenumber)

5E53H - Calculate Record Position (LOC/LOF Common)

Calculates record number based on byte position. Uses self-modifying code for record length.

5E67H - Divide by Record Length

LOC uses self-modifying code at 5E69H and 5E70H to store the record length and position for calculation. The routine multiplies the record number by record length and adds the position to get the total byte position, then returns this as a floating point number.

5E78H - Convert to Floating Point

5E7CH - LOF Function Handler

Returns length of file (total number of records). Syntax: LOF(filenumber)

LOF reuses most of LOC's code, but uses offset 14 (file length) instead of offset 12 (current record). Both functions share the calculation routine at 5E53H which handles the self-modifying record length division.

5E88H - Character Output to File Entry (Stack Cleanup)

Prepares for character output to file by cleaning up stack.

5E89H - Character Output to File Routine *** CRITICAL ***

Core routine for writing characters to sequential files. Called by PRINT#, WRITE#, SAVE, and all output statements. Manages output buffer and writes to disk when full.

*** CRITICAL ROUTINE *** This is one of the most important routines in the entire file system. It is called by every file output operation. Understanding this routine is essential to understanding how file output works.

5EA6H - Call DOS Write Routine

5EB1H - Success Path - Restore and Return

5EB6H - Error Path - Check DOS Error Code

The character output routine at 5E89H is the bottleneck for all file output. It calls ROM routine at 001BH which manages the actual character buffering and disk writes. The mode byte at FCB+1 is temporarily cleared and restored - this may be for DOS compatibility. CR (0DH) is handled specially without updating the position counter.

5EBFH - PUT Statement Handler

Writes a record to a random access file. Syntax: PUT #filenumber [, recordnumber]

5EE7H - GET/PUT with Explicit Record Number

5EEAH - Validate Syntax and Record Number

5F05H - Position to Specific Record

5F15H - Handle Record Not Found (Create New)

5F24H - Read or Write Record

5F42H - GET Success - Return

5F45H - Clear Record Buffer

Clears the record buffer to zeros. Used when GET fails or for new records.

PUT/GET use self-modifying code at 5F01H to store the auto-increment flag. The operation flag at 63BDH distinguishes PUT (FFH) from GET (00H). The verify flag at 426EH controls whether read errors on non-existent records are reported or silently ignored by zeroing the buffer.

5F53H - Read Character from File *** CRITICAL ***

Core routine for reading characters from sequential files. Called by INPUT#, LINE INPUT#, LOAD, MERGE, and all input statements. Manages input buffer and reads from disk when exhausted.

*** CRITICAL ROUTINE *** This is the mirror of 5E89H for input operations. Every file read operation calls this routine. Understanding this is essential to understanding file input.

The character read routine at 5F53H calls ROM routine 0013H which manages the actual buffer and disk reads. Error codes 1CH and 1DH are treated as EOF conditions and return with carry set. The routine at 5F7BH may retry the read under certain conditions (Z flag set from ROM call).

5F73H - Set EOF Flag and Return

5F75H - Restore and Return with Carry

5F7AH - Success Path - Character Read OK

5F7FH - Filename Parser *** IMPORTANT ***

Parses filename string, converts to uppercase, validates with DOS. Result stored at 6350H. Called by OPEN, LOAD, SAVE, KILL.

*** IMPORTANT ROUTINE *** Called by all file operations that need filenames.

5F99H - Filename Copy and Uppercase Conversion Loop

5FAFH - Validate Filename with DOS

The filename parser converts lowercase (61H-7AH) to uppercase by XORing with 20H. Maximum filename is 23 characters (18H-1). Result stored at 6350H and validated through DOS call 441CH.

5FC3H - OPEN Statement Handler *** CRITICAL ***

Main entry for OPEN statement. Syntax: OPEN "mode", #filenumber, "filename" [, recordlength]

*** CRITICAL ROUTINE *** Heart of the file system. All file operations start here.

5FF3H - Parse File Number and Filename

6007H - Common Entry Point (used by LOAD/RUN/MERGE)

NOP placeholder - may be modified at runtime

6008H - Get FCB and Parse Filename

6026H - Save State and Call DOS

6056H - Call DOS Open Based on Mode

OPEN determines file mode from first character: I=input(01H), O=output(02H), R=random(03H), E=extend(04H). Extend mode converts to output after positioning to end. Mode byte stored at FCB+0. Parser position saved at 40DFH. RUN/LOAD flag at 5200H modifies DOS behavior for program loading.

60A3H - File Cleanup Routine

Cleans up after file operations. Clears buffers and resets flags.

60CDH - KILL Statement Handler (continued)

Deletes a file from disk. Syntax: KILL "filename"

KILL statement uses DOS call 442CH to delete the file. The filename is parsed through 5F7FH and stored at 6350H. The three NOPs at 60D0H-60D2H may be placeholders for future modification.

60F9H-6110H - Error Code Jump Table (DATA)

Error entry points. Each loads specific error code and jumps to error handler at 19A2H.

Error Code Jump Table:

60F9H	LD E,6CH	Error 6CH - Bad File Mode
60FBH	LD BC,681EH	Error 68H - unused?
60FEH	LD BC,661EH	File Number Out of Range (error 66H)
6101H	LD BC,7C1EH	Error 7CH
6104H	LD BC,6E1EH	Error 6EH
6107H	LD BC,801EH	Error 80H
610AH	LD BC,7E1EH	Error 7EH
610DH	LD BC,641EH	Error 64H
6110H	JP 19A2H	Jump to error display routine

6113H - DOS Error Translation *** CRITICAL ***

Translates DOS error codes to BASIC error numbers using table at 6126H.

*** CRITICAL ROUTINE *** All DOS errors pass through here for translation to user-friendly BASIC errors.

6126H-614CH - DOS to BASIC Error Code Lookup Table (DATA)

39-byte table mapping DOS errors (00H-26H) to BASIC error numbers.

The error translation table converts DOS-specific error codes into user-friendly BASIC error messages. Error 72H is the most common (general I/O error). Error 66H indicates bad file number. Errors 1CH-1FH (EOF conditions) all map to error 66H.

Error Translation Table (6126H-614CH) - 39 bytes:

Index	Bytes	BASIC Error
00-06	72 72 72 72 72 72 72	Error 72H (I/O error) - repeated
07	80	Error 80H (file error)
08-0E	72 72 72 72 72 72	Error 72H - repeated
0F	88	Error 88H (different I/O)
10	66	Error 66H (bad file number)
11-12	72 72	Error 72H
13	80	Error 80H
14-18	72 72 72 72 6A	Error 72H, then 6AH
19	8A	Error 8AH (write error)
1A	86	Error 86H
1B	7A	Error 7AH
1C-1F	66 66 66 66	Error 66H (repeated)
20	80	Error 80H
21-24	66 66 66 66	Error 66H (repeated)
25	8A	Error 8AH
26	66	Error 66H
27+	xx	Defaults to Index 01 - Error 72H

614DH - PROGRAM ENTRY POINT *** CRITICAL ***

Main initialization when BASIC/CMD loads. Saves state, sets up file system, displays copyright.

*** PROGRAM ENTRY POINT *** This is where execution starts when BASIC/CMD is loaded. Critical initialization code.

6188H - Self-Modify Entry Point (First Run) **SELF-MODIFY**

619BH - Continue Initialization

61B2H - DOS Version Too Old - Exit with Error

61BCH - Check for Re-entry ('*' Parameter)

61E2H - Normal Entry Path

The entry point performs critical initialization. On first run (6188H-6199H), it self-modifies code at 614DH. The '*' parameter (2AH) triggers re-entry path at 61BCH which restores saved state. DOS version check at 61ABH requires TRSDOS 1.3 or later. The entry point copies 39 bytes from ROM (18F7H) to RAM (4080H) using LDIR.

61F0H - Prompt "How Many Files"

Prompts user for number of files (0-15) and optional verify mode.

621EH - Store File Count and Allocate

623BH - Allocate File Buffer Array *** IMPORTANT ***

Creates file pointer table at 63C0H, allocates FCB+buffer space starting at 64DCH.

*** IMPORTANT ROUTINE *** Sets up the entire file buffer structure. Each file gets 360 bytes (168H).

6269H - Prompt for Memory Size

Prompts "Memory Size?" and allocates memory for BASIC.

6291H - Display Copyright and Return to BASIC

6297H - Validate Memory Size

629FH - Set Memory Size and Allocate

62E5H - Display Copyright Banner **SELF-MODIFY**

Displays TRS-80 Model III Disk BASIC copyright. Self-modifies to run only once.

The copyright display routine uses self-modifying code. On first run, 62E6H contains 3EH (LD A,01H). After running once, it modifies itself to 3EH 00H (LD A,00H), so subsequent calls return immediately at 62EBH.

6301H - String Data and System Variables

Text strings, buffers, and system variables used by BASIC/CMD.

6301H - Error Message: "Use TRSDOS 1.3 or Later"

631AH - Prompt: "How Many Files"

6329H - Copyright Banner

638FH - Memory Size Display Buffer

The memory display buffer at 638FH is a template. Actual memory size digits are filled in at runtime at positions 638FH-6394H before display.

63A6H - Verify Mode Message: "Variable Files"

Alternate message displayed when verify mode is disabled would be at a different location (not shown in verify path).

63B6H - System Variables and Buffers

Runtime variables used by file system and initialization code.

63C0H - File Pointer Table (32 bytes)

The file pointer table at 63C0H stores pointers to FCB+buffer structures for up to 16 files (0-15). Each entry is 2 bytes. File #0 is reserved. Actual number of entries used is determined by "How Many Files" prompt response.

63E0H - Last Allocated Buffer End

63E4H - Entry Parameter Byte

63E5H - Saved String Space Pointer

63E7H - Saved Max File Number

63E9H - Saved Memory Top

63EBH - Initialization Flag

63ECH - Command Line Flags

63EEH - Saved Entry HL Register

63F0H - Temporary Filename Buffer (16 bytes)

The temporary buffer at 63F0H (16 bytes) is used during command line processing to build quoted filenames from command parameters before execution.

6400H - Reserved Area (9 bytes)

6409H - Command Line Processing

Processes command line parameters passed to BASIC/CMD.

6438H - Process Option Flags (-M or -F)

647CH - Process Memory Option (-M)

649EH - Finalize Command Line Processing

64DCH - File Buffer Area (END OF CODE)

Dynamic file buffer area. Each file allocated gets 360 bytes (168H).

File Buffer Structure:

Base Address: 64DCH

Size per file: 360 bytes (168H) in normal mode, 616 bytes (268H) in verify mode (adds 256-byte verify buffer)

Maximum allocation: 16 files × 360 bytes = 5,760 bytes. Actual allocation determined by "How Many Files" prompt (0-15)

Buffer Layout per file:

Offset 00H-31H: FCB (File Control Block) - 50 bytes

Offset 32H-131H: Record buffer - 256 bytes

Offset 132H-167H: Additional workspace - 54 bytes

File pointer table at 63C0H contains 2-byte pointers to each FCB.

Table is null-terminated when buffer list ends.