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

BASIC/CMD

Other Navigation

LDOS 5.3.1 BASIC/CMD Disassembly - LBASIC, the Disk BASIC Interpreter (Model I)

BASIC/CMD is LBASIC, the Disk BASIC supplied with LDOS 5.3.1 for the TRS-80 Model I. It is not a complete BASIC interpreter. The Model I Level II BASIC ROM at 0000H-2FFFH already contains the expression evaluator, the tokenizer, the statement executor and the whole floating-point library, and it was written from the start with a set of RAM hooks reserved for a disk extension that did not exist when the machine shipped. LBASIC is that extension. It supplies the code behind every disk keyword the ROM knows the name of but has no body for, and it re-points a handful of the ROM's inner loops at itself so it can add keywords the ROM has never heard of.

Physically the file is a single LDOS /CMD load module preceded by a type-1FH copyright record ("Copyright 1991 MISOSYS, Inc., All rights reserved"). It loads into two disjoint regions. The first, 4E00H-4E9EH, is 159 bytes that are never executed where they land: they are two blocks of JP instructions that the initialization code copies into the Level II BASIC RAM hook areas and then abandons. The second, 5200H-65FBH, is the interpreter extension proper, 5116 contiguous bytes, and the load module's transfer address is 52CCH.

The 4E00H block is loaded into what is normally LDOS overlay space. That is deliberate and it is safe: a /CMD program is brought in by @LOAD, and no numbered SYS overlay is resident at 4E00H at the moment the load records are being placed. The very first thing LBASIC does after taking control is to copy 4E00H-4E92H to 4152H and 4E93H-4E9EH to 4000H, after which the 4E00H area is free again. LBASIC then re-uses it as the load address for BASIC/OV3, the error-message and Sort overlay.

The Two RAM Hook Blocks

The 147 bytes at 4E00H-4E92H are forty-nine 3-byte JP instructions. They are copied verbatim to 4152H-41E4H, which is the Level II BASIC ROM's Disk BASIC entry-point table. Every slot in that table is a fixed address the ROM CALLs or JPs to when it meets a disk keyword or reaches one of its documented exit points; in a cassette-only machine each slot holds a RET or an error jump. Installing this block is what turns Level II BASIC into Disk BASIC. The slot order is fixed by the ROM and is confirmed here by the code each entry lands on: 4152H is CVI, 4158H is CVS and 415EH is CVD (the three routines at 5D2CH, 5D2FH and 5D32H differ only in the value they load into Register A, 01H, 03H and 07H, and share the tail at 5D34H), while 416AH, 416DH and 4170H are MKI$, MKS$ and MKD$ (the routines at 5D13H, 5D16H and 5D19H, which load 02H, 04H and 08H and share the tail at 5D1BH).

The 12 bytes at 4E93H-4E9EH are four more JP instructions, copied to 4000H-400BH. Those four addresses are the RAM hooks behind RST 08H, RST 10H, RST 18H and RST 20H. Three of them are pointed straight back at the ROM routines they normally reach - 1C96H for the RST 08H syntax check, 1C90H for the RST 18H unsigned DE:HL compare and 25D9H for the RST 20H value-type test. The fourth is the important one: the RST 10H "get the next character from the BASIC text stream" hook at 4003H is pointed at LBASIC's own routine at 6579H instead of at the ROM's CHRGTR at 1D78H. RST 10H is executed by the interpreter thousands of times per second, so owning it is what lets LBASIC recognise statement keywords the ROM's token table does not contain.

Start-Up Sequence

Execution begins at 52CCH with HL pointing at the command tail that LDOS left behind the program name. The initialization stores the first character of that tail and the tail pointer into self-modifying operand cells, saves the entry values of HIGH$ (4049H), TXTTAB (40A4H), 408EH and STKTOP (40A0H) into four more operand cells so that a later re-entry can undo everything, copies the ROM's 39-byte relocatable data table from 18F7H down to 4080H (the block that contains the self-modifying operands of the floating-point divide), installs the two hook blocks, sizes memory, prints the sign-on banner and finally builds the file control blocks. Control then passes to the ROM's BASIC command loop through the standard entry at 1A81H or, when a command tail was supplied, by re-executing that tail as a BASIC command line.

Before any of that, 5344H reads OSVER$ at 403EH and refuses to run under anything earlier than 5.3, displaying "Use LDOS 5.3 or later!" and returning to DOS. This is the same OSVER$ byte the rest of LDOS uses; 51H is the value the gate compares against.

Command Line Parameters

LBASIC accepts four keyword parameters, parsed by the resident @PARAM service at 4476H against the 8-byte-per-entry table at 528BH. MEM and M set the highest address BASIC may use, FILES and F set the number of disk file buffers to build, BLK and B switch blocked file mode on or off, and EXT and E switch off the default /BAS extension that LOAD, RUN, MERGE and SAVE otherwise apply. The published ranges are 1 to 15 files with 3 assumed, blocked mode ON by default, and EXT ON by default; the code tests the file count against 10H at 53C8H and takes the blocked-mode default from the assembled 0FFFFH at 53B9H, so both agree. A parameter that fails validation prints "Parameter error" through @LOGOT at 447BH and aborts; a memory request that cannot be satisfied prints "Out of memory". A command tail beginning with an asterisk is treated as a re-entry rather than a fresh start, which is how BASIC is resumed after a CMD shell-out.

File Buffers and the USR Vector Table

The FILES parameter decides how much workspace is built above the loaded image. 53CFH walks a chain of file buffers starting at 6632H, each 0122H bytes long (0222H when blocked file mode is on), zeroing the first byte of each and writing its address into a pointer table that starts at 65FAH. Before that, 5397H fills the ten words at 661CH-662FH with 642FH: that is the USR0 to USR9 vector table, and 642FH is the head of the error-code table, so a USR number that has never been given an address raises an error instead of jumping into nothing. Everything from 65FAH upward is workspace that exists only at run time; the loaded image itself ends at 65FBH.

The CMD String Shell

CMD"string" is the mechanism by which a BASIC program runs an LDOS command. The handler at 54ECH is the most intricate piece of code in the file. It copies the command text into INBUF$ at 4318H, checks that there is room, saves the six bytes of @EXIT and @ABORT (402DH-4032H) and the four bytes of @ERROR (4409H-440CH) into 540AH-5413H, then block-moves the whole of BASIC's low memory - 5200H up to STREND (40FDH), plus 407DH-41E4H - into the free space immediately below the stack, lowers HIGH$ to protect it, rewrites @EXIT, @ABORT and @ERROR to point at relocated stubs, and hands the line to @CMNDI at 4405H. When the DOS command finishes it exits through the patched @EXIT, which lands in the relocated copy of the restore routine at 559EH; that copies everything back, restores HIGH$, SP and the three DOS vectors from the saved bytes, and returns to BASIC. The saved-vector area is genuinely clever: 402DH, 4030H and 4409H each begin with a C3H JP opcode, so the saved copy is itself executable and the error stub simply jumps to it to chain to the real DOS handler.

The save area at 540AH-5413H physically overlays the instructions at 540AH-5413H, which belong to the MEM parameter range check. That is safe because the MEM check runs only during initialization and is never re-entered once BASIC is running.

Overlay Loading

CMD"N", CMD"X" and CMD"V" are dispatched at 5454H. The character following the quote selects the overlay digit in Register B: 31H for N (renumber, BASIC/OV1), 32H for X (cross-reference, BASIC/OV2) and 34H for V (variable dump, BASIC/OV4). Anything else is treated as a DOS command string and goes to 54ECH. 54A5H builds the filespec by copying the eight characters "BASIC/OV" from 548DH into CFCB$ at 4480H, appending the digit and a zero byte, and the overlay is then started with @RUN at 4433H with HL pointing at INBUF$ 4318H so the overlay can read the rest of the command line.

BASIC/OV3 is handled differently at 54B6H because it is a subroutine, not a program: it holds the long error-message text and the Sort routine and must return to LBASIC. It loads at 4E00H, and LBASIC uses OVRLY$ at 430EH as its "OV3 is already resident" marker - if 430EH holds 01H the overlay is simply entered at 4E00H without a disk access. Otherwise the code reproduces the resident @RUN preamble inline (set bit 2 of SFLAG$ at 430FH, then CALL @LOAD at 4430H, then EX (SP),HL and RET) so that the loaded overlay is entered with LBASIC's return address underneath it. A failed load prints "Can't load OV3".

Memory Map

Address Range	Contents
4E00H-4E92H 147 bytes	Image of the 49-entry Disk BASIC vector table. Copied to 4152H-41E4H at 5331H and then abandoned.
4E93H-4E9EH 12 bytes	Image of the four RST hook vectors. Copied to 4000H-400BH at 5306H and then abandoned.
4E00H-5281H 1154 bytes	Run-time load area for BASIC/OV3 (error messages and Sort). Occupies the space the two hook images were loaded into.
5200H-524FH 80 bytes	Sign-on banner text, CR-framed and 00H-terminated.
5250H-528AH 59 bytes	Message block: version refusal, "Parameter error", "Out of memory".
528BH-52CBH 65 bytes	@PARAM keyword table, eight 8-byte entries plus a 00H terminator.
52CCH-5453H 392 bytes	Initialization, version gate, parameter processing, file control block construction and entry to BASIC.
5454H-548CH 57 bytes	CMD string dispatcher and the DOS command tail builder.
548DH-54A4H 24 bytes	"BASIC/OV" filespec stem and the "Can't load OV3" message.
54A5H-55F6H 338 bytes	Overlay filespec builder, BASIC/OV3 loader and the CMD string memory-swap shell.
55F7H-65FBH 4101 bytes	The disk keyword bodies, the file I/O engine, the RST 10H token hook and the shared support routines.
65FAH upward run time	Workspace built at start-up: file buffer pointer table from 65FAH, the ten-word vector table 661CH-662FH, and the file buffers themselves from 6632H, each 0122H or 0222H bytes.

Self-Modifying Operand Cells and Run-Time Variables

Address Range	Purpose
5301H-5302H 2 bytes	Operand of the LD HL,0000H at 5300H. Loaded at 52ECH with the entry value of 408EH, the maximum-files byte, so a re-entry can restore it.
5354H 1 byte	Operand of the LD A,00H at 5353H. Loaded at 52D4H with the first character of the LDOS command tail. Compared against 2AH at 5355H and again at 53F4H to decide between a cold start and a re-entry.
5360H-5361H 2 bytes	Operand of the LD HL,0000H at 535FH. Loaded at 52F2H with the entry value of STKTOP (40A0H).
5366H-5367H 2 bytes	Operand of the LD HL,0000H at 5365H. Loaded at 52E6H with the entry value of TXTTAB (40A4H).
53ACH-53ADH 2 bytes	Operand of the LD HL,0000H at 53ABH. Loaded at 52D7H with the command tail pointer and reloaded at 53B6H with whatever @PARAM left in HL.
53FEH-53FFH 2 bytes	Operand of the LD DE,0000H at 53FDH. Loaded at 52E0H with the entry value of HIGH$ (4049H); it is the ceiling the MEM parameter is checked against.
540AH-5413H 10 bytes	Save area for the DOS vectors across a CMD shell-out: 402DH-4032H (@EXIT and @ABORT) go to 540AH-540FH and 4409H-440CH (@ERROR) to 5410H-5413H. Both copies retain their C3H JP opcodes and are jumped to directly. The area overlays the MEM range-check instructions, which do not run again.
556BH-556CH 2 bytes	Operand of the LD DE,0000H at 556AH. The destination of the outward LDDR, set at 5537H to SP minus one.
5572H-5573H 2 bytes	Operand of the LD BC,0000H at 5571H. The byte count of the block to be saved, computed at 5519H as STREND minus 5200H.
5592H-5593H 2 bytes	Operand cell loaded at 5529H with HIGH$ so the relocated copy can report it.
5598H-5599H 2 bytes	Operand of the JP M,0000H at 5597H. Set at 5567H to the relocated address of the saved @ERROR vector bytes, so a return-to-caller error chains to the real DOS handler.
55BAH-55BBH 2 bytes	Operand of the LD BC,0000H at 55B9H. The residual byte count for the second half of the restore LDIR.
55BFH-55C0H 2 bytes	Operand of the LD HL,0000H at 55BEH. The HIGH$ value to restore after a CMD shell-out.
55C5H-55C6H 2 bytes	Operand of the LD SP,0000H at 55C4H. The stack pointer to restore after a CMD shell-out.
65FAH upward run time	File buffer pointer table, two bytes per file, built at 53E5H. The image ships 65FAH-65FBH as 0000H.
661AH-661BH run time	Address of the first file buffer, stored at 53E2H.
661CH-662FH run time	The USR0 to USR9 vector table, ten words, each initialized at 539FH to 642FH so that an undefined USR raises an error. DEF USR writes a slot at 5737H and USR reads one at 5704H.
6630H-6631H run time	Cleared to 0000H at 53A8H.

Major Routines

Address	Name and Purpose
52CCH	Initialization Entry The load module's transfer address. Entered with HL pointing at the LDOS command tail. Saves the entry environment into self-modifying cells, installs both RAM hook blocks, sizes memory and starts BASIC.
5344H	Version Gate Reads OSVER$ at 403EH and refuses to run below 51H, displaying "Use LDOS 5.3 or later!" through STROUT at 28A7H.
5397H	USR Vector Table Initialization Fills the USR0 to USR9 vector table at 661CH-662FH with ten copies of the error entry 642FH and clears 6630H, then calls @PARAM at 4476H against the table at 528BH.
53CFH	File Buffer Chain Builder Builds one 0122H-byte (or 0222H-byte) buffer per file from 6632H upward and records each address in the pointer table from 65FAH.
5400H	MEM Parameter Range Check Validates the requested memory ceiling against HIGH$ and against TXTTAB plus 012CH, sets MEMSIZ (40B1H) and STKTOP (40A0H), then calls the ROM NEW routine at 1B4DH.
5454H	CMD String Dispatcher Entered from the CMD vector at 4173H. Selects BASIC/OV1, BASIC/OV2 or BASIC/OV4 on N, X or V, and sends anything else to the DOS command shell at 54ECH.
54A5H	Overlay Filespec Builder Copies "BASIC/OV" from 548DH into CFCB$ at 4480H, appends the digit in Register A and a 00H byte.
54B6H	BASIC/OV3 Loader Uses OVRLY$ at 430EH as the resident marker; loads the overlay to 4E00H with @LOAD at 4430H using the resident @RUN preamble, and enters it by RET.
54E1H	Command Tail Copier Copies a 00H-terminated string to INBUF$ at 4318H and terminates it with a carriage return.
54ECH	CMD String Shell Saves BASIC's whole low-memory state above the stack, patches @EXIT, @ABORT and @ERROR, and passes the line to @CMNDI at 4405H.
559EH	CMD String Shell Return The relocated restore routine that the patched @EXIT, @ABORT and @ERROR vectors reach. Copies everything back, restores HIGH$, SP and the DOS vectors and returns to BASIC.
55EBH	Variable Reference Parser Checks for the FN token, sets SUBFLG (40DCH) to 80H and enters the ROM's PTRGET at 2612H.
55F7H	FN User-defined function evaluation. Reached from vector slot 4155H.
56D8H	DEF DEF FN and DEF USR processing. Reached from vector slot 415BH.
56FBH	USR USRn function call. Reached from vector slot 41A9H.
573CH	PRINT Device Check The ROM's print processing exit at 41CAH; recognises PRINT# and diverts to the file writer.
57C6H	CMD The CMD statement. Reached from vector slot 4173H.
587BH	PRINT# Reached from vector slot 41BEH.
5882H	INPUT# Reached from vector slot 41D6H.
5912H	LINE INPUT Reached from vector slot 41A3H.
5A2CH	LIST and INPUT Assignment Exit Reached from vector slot 41DFH.
5A42H	Long Error Message Handler Reached from vector slot 41A6H. Expands a BASIC error code into full text using BASIC/OV3.
5A61H	TIME$ Reached from vector slot 4176H.
5A77H	INSTR Reached from vector slot 419DH.
5AFFH	& (Hexadecimal and Octal Constants) Reached from vector slot 4194H.
5B50H	MID$ on the Left of an Assignment Reached from vector slot 41D9H, the only ROM exit that is a JP rather than a CALL.
5BD1H	Keyboard Line Input Exit Reached from vector slot 41AFH.
5C00H	Byte Output To Any Device Reached from vector slot 41C1H, the ROM's character output exit at 032CH.
5C0EH	Keyboard Scan Exit Reached from vector slot 41C4H, the ROM's INKEY$ and BREAK check at 0358H.
5C9EH	Comma Field and TAB Exit Reached from vector slot 41D3H.
5CB6H	Line Table Update Exit Reached from vector slot 41B5H.
5CC3H	Line Table Update With CLEAR Exit Reached from vector slot 41B8H.
5CCFH	PRINT Carriage Return Exit Reached from vector slot 41D0H.
5CD0H	Number Conversion Exit Reached from vector slot 41CDH.
5D13H / 5D16H / 5D19H	MKI$ / MKS$ / MKD$ Three entries into one routine, separated by a 01H byte so that a fall-through reads the following LD A,nn as the operand of a LD BC. Reached from vector slots 416AH, 416DH and 4170H.
5D2CH / 5D2FH / 5D32H	CVI / CVS / CVD The same three-entry construction, reached from vector slots 4152H, 4158H and 415EH.
5D49H	READ and INPUT Variable Assignment Exit Reached from vector slot 41DCH.
5E42H	MERGE Reached from vector slot 418BH.
5E70H	RUN With A Filename Reached from vector slot 41C7H.
5E78H	LOAD Reached from vector slot 4188H.
5FC4H	READY Prompt Exit Reached from vector slot 41ACH.
5FD8H	Post-Tokenization Exit Reached from vector slot 41B2H.
5FECH	SAVE Reached from vector slot 41A0H.
6043H	CLOSE Reached from vector slot 4185H.
6074H	NEW and END File Closure Exit Reached from vector slot 41BBH.
607EH	FIELD Reached from vector slot 417CH.
60D8H / 60D9H	RSET / LSET Reached from vector slots 419AH and 4197H.
617BH	EOF Reached from vector slot 4161H.
61B2H / 61B7H	LOC / LOF Reached from vector slots 4164H and 4167H.
6204H / 6205H	PUT / GET Reached from vector slots 4182H and 417FH.
62DBH	OPEN Reached from vector slot 4179H.
6385H	EXT Parameter Cell The result cell the EXT and E keywords in the @PARAM table at 52BBH and 52C3H write, controlling whether LOAD, RUN, MERGE and SAVE supply the default /BAS extension.
6412H	KILL Reached from vector slot 4191H.
642FH	Error Code Table Ten entry points separated by 01H skip bytes, each loading Register E with a BASIC error number and converging on the ROM error handler at 19A2H through 644CH. 642FH itself supplies 2EH and is the default contents of all ten USR vector slots at 661CH-662FH.
6579H	RST 10H Token Hook Installed at 4003H in place of the ROM's CHRGTR. Fetches the next character of the BASIC text stream and recognises the keywords LBASIC adds.

Cross-Reference Notes

BASIC/CMD is started by the LDOS command interpreter (SYS1) like any other /CMD program and issues no RST 28H supervisor request of its own. Everything it asks of the operating system goes through a resident SYS0 vector or a Level II BASIC ROM entry point.

Resident SYS0 vectors used: @EXIT 402DH, @ABORT 4030H, @CMNDI 4405H, @ERROR 4409H (and its operand 440AH), @DEBUG 440DH, @FSPEC 441CH, @INIT 4420H, @OPEN 4424H, @CLOSE 4428H, @KILL 442CH, @LOAD 4430H, @RUN 4433H, @READ 4436H, @WRITE 4439H, @REW 443FH, @POSN 4442H, @BKSP 4445H, @PEOF 4448H, @CKEOF 444BH, @LOC 445AH, @LOF 445DH, @TIME 446DH, @DATE 4470H, @FEXT 4473H, @PARAM 4476H, @LOGOT 447BH, CFCB$ 4480H and the disk primitive slot at 4750H. Resident state read or written: @KITSK 4300H, OVRLY$ 430EH, SFLAG$ 430FH, the DEBUG re-entry trap slot 4315H, INBUF$ 4318H and 4319H, KFLAG$ 4423H, and the patch byte 4BF0H, which is the NOP at the head of the RST 28H dispatcher's sub-80H request path at 4BEFH. LBASIC writes 0C8H (RET Z) there to make that path return immediately, and 00H (NOP) to restore it, in step with setting and clearing bit 4 of SFLAG$ 430FH.

Level II BASIC ROM entry points are used throughout; the file references 132 distinct ROM addresses in 0000H-2FFFH. The four RST hooks it installs at 4000H-400BH point at 1C96H (SYNCHR), 6579H (LBASIC's own CHRGTR replacement), 1C90H (DCOMPR) and 25D9H (GETYPR).

Overlays: BASIC/OV1 (CMD"N", renumber) and BASIC/OV2 (CMD"X", cross-reference) and BASIC/OV4 (CMD"V", variable dump) all load at 5200H and are started with @RUN, replacing LBASIC's own image; BASIC/OV3 (long error messages and Sort) loads at 4E00H, is a subroutine, and is tracked by OVRLY$ at 430EH.

4E00H - Disk BASIC Vector Table Image (Data)

Forty-nine 3-byte JP instructions that are never executed at this address. The initialization routine at 5331H block-moves all 147 bytes to 4152H-41E4H, the Level II BASIC ROM's Disk BASIC entry-point table, and the area is then re-used as the load address for BASIC/OV3. Every slot below is identified by the fixed ROM address it lands on once the copy has been made; the ROM either CALLs or JPs to that address when it meets the corresponding keyword or reaches the corresponding exit point.

4E93H - RST Hook Image (Data)

Four more 3-byte JP instructions, again never executed where they are loaded. The initialization routine at 5306H copies these 12 bytes to 4000H-400BH, the RAM hook block behind RST 08H, RST 10H, RST 18H and RST 20H. Three of the four are pointed back at the ROM routines they normally reach, which is what makes the copy safe to perform unconditionally; only the RST 10H hook is diverted into LBASIC.

5200H - Sign-On Banner (Data)

The banner LBASIC displays once memory has been sized. It is sent by STROUT at 28A7H from 5421H, which prints characters until it meets the 00H at 5250H. The two carriage returns at the end leave a blank line before the READY prompt.

5251H - Message Block (Data)

Three short messages, each with its own terminator convention because each is displayed by a different routine. The refusal at 5254H goes through STROUT at 28A7H and needs a 00H; the two error messages go through @LOGOT at 447BH and need a carriage return.

528BH - @PARAM Keyword Table (Data)

The keyword table the resident @PARAM service at 4476H is pointed at from 53AEH. The format is the standard LDOS one used throughout SYS6 and SYS7: eight 8-byte entries, each a six-character blank-padded keyword followed by a two-byte little-endian address of the cell that is to receive the parsed value, ended by a single 00H byte. Every keyword is present twice, once spelled out and once abbreviated to its initial letter, and both spellings point at the same result cell.

52CCH - Initialization Entry

The load module's transfer address, entered by the LDOS command interpreter through @RUN. On entry Register Pair HL points at the first character of the command tail, the text LDOS left behind the program name, and the machine is still in the state SYS1 handed over: Level II BASIC's RAM workspace holds whatever the last BASIC session or the boot left there, and none of the disk keywords work yet. This routine saves the entry environment into self-modifying operand cells so a later re-entry can undo it, installs both RAM hook blocks, sizes memory and sets up the keyboard line buffer.

5344H - Version Gate and Re-Entry Test

LBASIC 5.3.1 depends on services and on a directory date format that earlier LDOS releases do not have, so it refuses to run under them. OSVER$ at 403EH is the resident byte every LDOS component uses to identify the release. Once the gate is passed, the saved first character of the command tail decides whether this is a fresh start or a re-entry into a session that is still resident.

5397H - USR Vector Table Initialization and Parameter Parsing

The cold-start path. The ten USR vectors above the loaded image are seeded with the address of the error-code table so that calling a USR number that was never defined raises an error rather than jumping into whatever happens to be there, and then the command tail is handed to the resident @PARAM service. The three parameters that have local result cells are validated here; MEM is validated later at 5400H because it depends on where the file buffers ended up.

53CFH - File Buffer Chain Builder

Entered with Register A holding the number of files, either freshly validated at 53CCH or recovered from MAXFIL on a re-entry at 5359H. It lays out one buffer per file above the loaded image and records the address of each in a pointer table, then falls through into the program text area setup. The buffers are 0122H bytes each, or 0222H when the BLK parameter has set VARREC.

53FDH - MEM Parameter Range Check

The requested memory ceiling is checked twice: it must not be above the HIGH$ that LDOS handed over, and it must leave at least 012CH bytes above the start of the program text. This code runs exactly once, which is what makes it safe for 540AH-5413H to be reused as the DOS vector save area by the CMD shell at 5504H, and for 5309H-53F8H to be reused as the keyboard line buffer.

5421H - Sign-On and Entry to BASIC

Everything is in place, so the banner is displayed and control passes to Level II BASIC. If anything followed the parameters on the LDOS command line it is treated as a BASIC command and executed immediately, which is how a JCL job can start BASIC and run a program in one line; if nothing followed, BASIC simply comes up at the READY prompt.

5454H - CMD String Dispatcher

Reached from the CMD statement at 57CBH when the quoted string is two characters or longer, with Register A holding the string length and Register Pair DE pointing at the string itself. There is a second entry at 5468H, taken from 5803H-5808H when CMD was given a single letter that the statement's own dispatcher did not recognise; that path arrives with Register Pair HL already loaded with 1E4AH so that an unrecognised letter raises ?FC. The test that separates an overlay call from a DOS command is not the letter but the character after it: only a space makes 5465H look at the letter at all, which is exactly the published syntax CMD"N !line,newline,inc,last", CMD"X devspec..." and CMD"V ...".

548DH - Overlay Filespec Stem and Message (Data)

Twenty-four bytes of data sitting between the dispatcher and the filespec builder. The first eight are the constant part of the overlay filespec, copied wholesale into the command file control block; the rest is the message shown when BASIC/OV3 cannot be loaded.

54A5H - Overlay Filespec Builder

Builds "BASIC/OVn" into CFCB$ at 4480H, the command file control block that @LOAD and @RUN both take in Register Pair DE. Entered with the overlay digit in Register B. Note the terminator: after @FSPEC has parsed a filespec the control block begins with the specification as plain ASCII text, and a 00H byte ends it.

54B6H - BASIC/OV3 Loader

BASIC/OV3 is the odd one out. It holds the long error message text and the CMD"O" array sort, so it must be callable as a subroutine and must return; the other three overlays are programs that replace LBASIC. It therefore loads at 4E00H, in the space the two RAM hook images occupied before 5306H and 5331H copied them away, and it is entered with @LOAD rather than @RUN. Five places call here: 5837H (CMD"O" sort), 5A52H (long error text), 5EB0H, 6453H and 6564H. OVRLY$ at 430EH is used as the "already resident" marker, which is a second, entirely legitimate use of a resident LDOS cell by a transient program.

54E1H - Command String Copier

Copies a counted string into INBUF$ at 4318H, the resident LDOS input buffer that @CMNDI reads, and gives it the carriage-return terminator LDOS expects. Entered with Register Pair HL pointing at the string and Register C holding its length; Register B is cleared here so the caller need only set the length byte.

54ECH - CMD String Shell, Outward Half

This is how a BASIC program runs an LDOS library command. The problem it solves is that a DOS command loads at 5200H, exactly where LBASIC lives, so BASIC's whole low memory must be moved out of the way and brought back afterwards. The block moved is 5200H up to STREND, plus the Level II workspace 407DH-41E4H, and it is parked immediately below the stack with HIGH$ lowered to protect it. Three DOS vectors are saved and rewritten so that however the command finishes - normally, by aborting, or by raising an error - control comes back to the relocated restore routine.

5590H - Resident Module Header and Return Stubs

Fourteen bytes serving two purposes. The first six are a standard LDOS resident high-memory module header, planted at the foot of the protected region by the LDDR at 5583H so that the saved BASIC session is a named entry in the module chain rather than an anonymous hole below HIGH$. The remainder are the three tiny stubs the patched @ERROR, @ABORT and @EXIT vectors point at, arranged so that all three converge on one EX AF,AF' and carry their outcome into the alternate flag set.

559EH - CMD String Shell, Return Half

Reached by falling out of whichever stub the DOS command triggered, with the outcome parked in the alternate flag set. This code runs from its relocated copy above HIGH$, not from 559EH itself, which is why every address it touches is either absolute or was patched before the move. It brings the saved block back, restores HIGH$, the Stack Pointer and the three DOS vectors, and then either returns to the BASIC statement that issued the CMD or raises an error.

55EBH - Variable Reference Parser

A short shared routine used by the FN evaluator at 55F7H and by DEF at 56DCH. Both need to read a function name from the BASIC text, and both must accept it as a variable-style name that may not exist yet, so the ROM's variable locator is entered with the create flag primed.

55F7H - FN, User-Defined Function Evaluation

Reached through vector slot 4155H whenever the interpreter meets an FN reference in an expression. Level II BASIC's own DEF FN allows one argument; LBASIC's allows several, which is why this routine is so much larger than the ROM's. The mechanism is the classic one for a recursive function: every parameter variable's current value is pushed on the stack, the argument expressions are evaluated into those variables, the definition text is evaluated, and the saved values are popped back. Register pair usage throughout is that Register Pair HL is the BASIC text pointer and Register Pair DE the address of a variable's value, with the two exchanged whenever the roles swap.

56D8H - DEF, Function and USR Definition

Reached through vector slot 415BH. DEF introduces either DEF FN, which records where a function's definition text begins, or DEF USR, which records the machine-language entry point for one of the ten USR vectors. The two are told apart by the token that follows.

56FBH - USR, Machine-Language Function Call

Reached through vector slot 41A9H, which the ROM's USR processor at 27FEH CALLs. Level II BASIC has a single USR entry; Disk BASIC has ten, USR0 to USR9, held in the vector table at 661CH. This routine resolves the digit, fetches the address, and arranges for the machine-language routine to be entered with the argument available and for its result to be collected afterwards.

571BH - USR Number Resolver

Shared by USR at 56FCH and by DEF USR at 572DH. Reads the optional digit that follows the USR token and converts it into the address of one of the ten two-byte slots in the vector table at 661CH. An absent digit means USR0, which is what preserves compatibility with the single USR of Level II BASIC.

572DH - DEF USR, Set a Machine-Language Entry Point

Reached from 56DAH when DEF is followed by the USR token. The digit selects one of the ten vector slots and the expression after the equals sign supplies the address, which is why a DEF USR must be executed before the matching USR call is made.

573CH - PRINT# Device Check

Reached through vector slot 41CAH, which the ROM CALLs at 206FH once it has begun a PRINT statement. Level II BASIC already understands PRINT #-1, the cassette form, so LBASIC must let that through untouched and claim only PRINT #n where n is a disk file number. It does that by peeking one character ahead: the token 0CEH is the minus sign, so a minus following the hash mark means the cassette form and LBASIC steps aside.

5748H - CMD Switch Parser

Reads the second, string, argument of a two-part CMD statement such as CMD"B","OFF" and reports whether it says ON or OFF. The test is neat and cheap: it looks only at the second character of the string, which is N in "ON" and F in "OFF", so no string comparison is needed. It returns with the Z FLAG set when the switch is off.

5764H - CMD"L", Load a Machine-Language File

Reached from the CMD statement dispatcher at 57D3H. CMD"L","filespec" loads a machine-language load module into memory without executing it, which is how a BASIC program brings in the routine a USR vector will call. The first file buffer doubles as the scratch area in which the file control block is built, since no BASIC file need be open to use this command.

5776H - CMD"P", Read the Printer Status

Reached from the CMD statement dispatcher at 57D8H. The Model I printer interface is memory-mapped, and reading 37E8H returns the printer's status lines in the high nibble: busy, out of paper, unit select and fault. This command hands that nibble to a BASIC variable so a program can test whether the printer is ready before it prints. The variable may be numeric or a string, and the routine converts as needed.

57A3H - CMD"B", Enable or Disable the BREAK Key

Reached from the CMD statement dispatcher at 57F9H. CMD"B","OFF" stops the BREAK key interrupting a running program, which is how a finished application protects itself. Two things have to change together: the resident LDOS flag that the keyboard driver consults, and a patch byte inside the RST 28H dispatcher in SYS0.

57BAH - Exit to DOS

The single way out of LBASIC, reached by CMD"S" at 57E4H, by CMD"A" at 57E9H with the CARRY FLAG set, and by the two initialization failures at 538FH. The one thing that must not be forgotten on the way out is the RST 10H hook: LBASIC redirected it to its own character fetch at 6579H, and leaving it there would send every subsequent RST 10H in the machine into an image that is about to be overwritten.

57C6H - CMD Statement

Reached through vector slot 4173H. CMD is the door between BASIC and the operating system, and it carries two quite different kinds of traffic: a quoted string of two characters or more is either an overlay call or an LDOS command line and goes to the dispatcher at 5454H, while a single letter selects one of a dozen built-in functions. The letter is folded to upper case with RES 5, which incidentally is what makes 2AH, the asterisk of CMD"*", arrive here as 0AH.

580EH - CMD"R" and CMD"T", Interrupt Control

Four bytes, two functions, and one of the neatest constructions in the file. Entered at 580EH the bytes read EI / LD A,0F3H / RET, which is CMD"R"; entered one byte later at 5810H the 0F3H is no longer an operand but an opcode in its own right, DI, giving DI / RET, which is CMD"T". Model I cassette input and output are timed by software and cannot tolerate the real-time clock interrupt, so a program that reads or writes tape brackets the operation with these two.

5812H - CMD"*", Screen Print

Copies the whole video display to the printer, one 64-column row at a time, without needing the JKL screen-print function of the keyboard driver to be active. Video RAM runs from 3C00H to 3FFFH, so the loop ends when the high byte reaches 40H, which is tested with a single BIT instruction. Video control codes below 20H are shifted into the printable range before they are sent.

5834H - CMD"O", Array Sort

Reached from 57F5H. CMD"O",numelem,firstelem sorts part of a singly dimensioned string array. LBASIC does none of the work itself: it selects function 3 and hands over to BASIC/OV3, the same overlay that holds the long error message text. The selector travels in the alternate accumulator, which is free because nothing between here and the overlay's entry uses it.

583AH - CMD"I", Run a DOS Command and Stay in DOS

Reached from 57EDH. This is the deliberately one-way relative of the CMD string shell: the command is executed and control is left at DOS Ready rather than returned to BASIC. Because nothing comes back, none of the memory saving that 54ECH performs is needed, and the routine is nine instructions long instead of eighty.

584AH - CMD"E", Report the Last DOS Error

Reached from 57FDH. BASIC's error dictionary is much smaller than the operating system's, so several distinct DOS failures collapse into one BASIC message such as "Disk I/O error". This command displays the operating system's own wording for the most recent failure, which is how a programmer tells those cases apart. The code is kept in a single run-time byte at 65F7H, just below the file buffer pointer table.

5852H - CMD"D", Debugger Control

Reached from 5801H. With no switch this enters the system debugger immediately. With a switch it arms or disarms the resident re-entry trap instead, so that the debugger is reached later by pressing BREAK while the BASIC program keeps running until then. The trap slot at 4315H holds a three-byte JP 400FH when armed; only the opcode byte is written here, because the operand at 4316H already holds 400FH and is never disturbed.

5867H - CMD Argument Evaluator

Two entry points into one routine. 5867H requires a comma first and is used by the two-argument forms; 5869H skips that check and is used by the CMD statement itself, which has already consumed the opening quote. Both return the argument string's length in Register A and its address in Register Pair DE, and both reject an empty string, since every CMD function needs at least one character to dispatch on.

587BH - PRINT Completion Hook

Reached through vector slot 41BEH, which the ROM CALLs at 2174H as it finishes a PRINT statement and resets the output device back to the video display. LBASIC uses the opportunity to forget which disk file was current, so that a bare PRINT following a PRINT#n cannot accidentally write to the file. Register A is zero when the ROM arrives here, so both bytes of the pointer are cleared.

5882H - INPUT# and INPUT@

Reached through vector slot 41D6H, which the ROM CALLs at 219EH at the start of an INPUT statement. Two quite different extensions share this entry. A hash mark introduces INPUT#n, which reads from a disk file, and is passed through to the ROM if it turns out to be the cassette form INPUT#-1. An at sign introduces INPUT@, LBASIC's fielded screen input: it positions the cursor, optionally displays a prompt, and then accepts a string of a stated width into a highlighted field with a chosen fill character, optionally restricted to numeric characters and optionally terminating as soon as the field is full. The field description is packed into Register C, which is why it is built so carefully.

5912H - LINE INPUT

Reached through vector slot 41A3H, the LINE token. LINE must be followed by INPUT, and the statement then reads a whole line into a single string variable without treating commas or quotation marks as separators. A hash mark after INPUT diverts to the file form. The body from 5922H is shared with INPUT@: the two differ only in whether Register B arrives holding a field width or zero.

5949H - Fielded Input Collector

Called from 5935H when INPUT@ supplied a field width. It runs the field editor, then terminates the collected text in the buffer. Register B holds the field width and Register C the packed description that 58E3H onwards built.

5960H - Field Editor

The heart of INPUT@. It paints the field with the fill character so the operator can see how much room there is, backs the cursor up to the start, and then runs a keystroke loop that accepts characters, honours backspace and erase-line, and ends on ENTER or BREAK. The fill character is planted into a self-modifying operand rather than kept in a register, because every register is spoken for.

599EH - Erase One Character

The backspace action of the field editor, called once for the left arrow and repeatedly from 5998H for the shifted left arrow. Erasing means putting the fill character back, not writing a space, so the field stays visibly the size it was. Register B counts the positions still free and Register C the field width, so the two are equal exactly when nothing has been typed.

59B2H - Accept a Printable Character

Reached from 5983H when the key pressed is 20H or above. The character must survive three tests before it is stored: it must not be in the graphics and token range, there must be room left in the field, and if the field was declared numeric it must be a digit, a sign or a decimal point. Every rejection simply jumps back to the keystroke loop, so an unwanted key is silently ignored rather than beeping or erroring.

59E2H - Finish the Field

The common exit of the field editor, reached on ENTER from 5987H, on BREAK from 598BH with the CARRY FLAG set, and by falling through from 59E1H when a full field terminated itself. It clears the remaining fill characters so the display shows only what was typed, brings the ROM's column tracker back into step, and converts the free-position count into the number of characters actually entered.

5A04H - Move the Cursor Left

The display driver's own backspace moves the cursor left but will not step it back up to the end of the previous row, so the field editor has to detect that case itself and adjust the cursor address in the device control block before sending the control code. The port FFH shadow at 403DH is consulted because in the 32-character wide display mode each character occupies two screen positions.

5A1BH - Wrap the Cursor to the Previous Row

Two entry points. 5A1BH tests whether the cursor is at the left margin and moves it back one row if it is; 5A22H is entered directly from 58A8H by INPUT@ to add an arbitrary offset in Register Pair DE to the screen base and install the result. Both end by writing the cursor address into the display device control block.

5A27H - Display the Fill Character

Two instructions, one of which is a self-modifying operand. Keeping the fill character here rather than in a register is what lets the painting loop at 596AH and the erase routine at 59A9H share it without either of them having a register to spare.

5A2CH - LIST and INPUT Assignment Exit

Reached through vector slot 41DFH, which the ROM CALLs from two quite different places: 2278H, just after an INPUT statement has assigned a value, and 2B44H, in the middle of LIST. LBASIC needs to behave differently in each case and the ROM gives it nothing to distinguish them, so the routine works it out by comparing its own return address against the start of the LIST routine. It only does any of this when a disk file is current; otherwise it steps aside at once.

5A42H - Long Error Message Handler

Reached through vector slot 41A6H, the first of the twenty-one stubs the ROM leaves as bare RETs on a cassette machine. Level II BASIC reports errors as two-letter abbreviations; Disk BASIC spells them out. The message text is too bulky to keep resident, so it lives in BASIC/OV3 and is fetched on demand. The OV3 function selectors travel in the alternate accumulator: 01H expands an error code, 02H translates a DOS error number, 03H sorts an array, and 04H - used only by the RUN"filespec",V path at 5EB0H - parks the variables that are to survive a chained load.

5A61H - TIME$

Reached through vector slot 4176H. TIME$ returns a seventeen-character string holding the date, a space and the time, built directly from the two resident LDOS services rather than from BASIC's own clock. The string is allocated first and the two services are asked to write straight into it, so no intermediate buffer is needed.

5A77H - INSTR

Reached through vector slot 419DH. INSTR searches one string for another and returns the one-based position of the first match, or zero if there is none. The optional first argument is a starting position, and it is detected by evaluating the first parameter and asking what type it came out as: a string means there was no starting position and the search begins at 1. The result is delivered by pushing two ROM addresses as a chain of return addresses, so that a plain RET from the search loop converts Register A into a BASIC value and tidies up.

5AFFH - & Prefix, Hexadecimal and Octal Constants

Reached through vector slot 4194H when the expression evaluator meets an ampersand. &H introduces a hexadecimal constant and &O an octal one; an ampersand followed by anything else is taken as octal, so &777 works as well as &O777. Both paths accumulate into Register Pair HL and Register Pair DE alternately, exchanging the two at each step so that the ROM's character fetch always has the text pointer where it expects it. The result is delivered as a 16-bit integer.

5B50H - MID$ on the Left of an Assignment

Reached through vector slot 41D9H, which the ROM enters with a JP from 2AECH rather than a CALL. That makes it the only one of the Disk BASIC exits with no return address of its own, which is why this routine builds its own by planting the ROM's FINZER address on the stack before it starts copying. MID$(A$,n,m) = expr overwrites part of a string in place instead of building a new one, so the target's characters must be somewhere writable; 5B66H-5B6FH sees to that before anything is changed. The number of characters actually replaced is the smallest of the requested length, the room left in the target from position n, and the length of the source.

5BC3H - Optional Length Parser

Reads the optional third argument of MID$ on the left of an assignment and the closing parenthesis. When no length is given the default is 0FFH, larger than any string, so the limits at 5B9EH and 5BBFH reduce it to whatever is actually available. Entered with the character after the starting position already in Register A.

5BD1H - Keyboard Line Input Exit

Reached through vector slot 41AFH, which the ROM CALLs at 0368H whenever it is about to collect a line. When no file is current the whole thing is handed to 6459H and behaves as it always did. When a file is current LBASIC collects the line itself, with the loop below, rather than letting the ROM's own collector run: it discards the ROM's return address and never goes back. The loop is a compact line reader that stops on a carriage return, ignores a line feed that arrives before any character has been stored, and terminates the text with a zero byte.

5C00H - Byte Output To Any Device

Reached through vector slot 41C1H, which the ROM's character despatcher CALLs at 032CH. Every single character BASIC prints passes through here, so the test has to be as cheap as possible: if no file is current the routine returns at once and the ROM sends the character to the screen or printer as usual. If a file is current the character is written to it instead, and the two stacked return addresses are thrown away because the file writer takes over the statement.

5C0EH - Keyboard Scan Exit

Reached through vector slot 41C4H, which the ROM's INKEY$ simulator ISCHAR CALLs at 0358H as its very first act. ISCHAR is the bottom of every keyboard path in Level II BASIC, so this hook sees every request for a key from anywhere in the interpreter - and it has to tell them apart, because LBASIC wants to answer some of them from a disk file and others from the real keyboard. It does that by reaching PAST its own caller and looking at who called ISCHAR: the return address two levels up is 0387H if the request came from INCHR, the ROM's wait-for-a-keypress loop, and 01A8H if it came from the INKEY$ function itself. Only the INCHR case is diverted to the file, which is exactly right - INKEY$ must keep polling the operator even while a program is being loaded from disk, whereas the line collector that INCHR feeds is precisely what an ASCII LOAD or MERGE wants to fill from the file. The whole test is done in the ALTERNATE register set so that the caller's registers are not disturbed, and note that EXX exchanges only BC, DE and HL: Register A and the flags pass straight through it, which is what lets the current-file test be made on one side and acted on from the other.

5C53H - BREAK And PAUSE Poll For Every Other Keyboard Request

The continuation of the keyboard scan exit, reached when the caller two levels up was not INCHR. If it was the INKEY$ function itself the request is handed straight back to the ROM. Everything else - and that means the polls Level II makes while a program is running, in order to notice a BREAK - is answered by LBASIC entirely, from the DOS keyboard flag KFLAG$ 4423H rather than by scanning the keyboard matrix. The routine returns 01H, the code the keyboard driver gives for BREAK, or 00H for no key, and because 5C0FH threw the ISCHAR return level away, that value goes straight back to whoever called ISCHAR without the rest of ISCHAR running at all. Answering from KFLAG$ is what lets a BREAK pressed at any moment - including one the DOS type-ahead buffer caught while a disk operation was in progress - be seen by a running BASIC program, and it is also where LDOS's shift-@ PAUSE is implemented.

5C7FH - Clear The Pending BREAK, PAUSE And ENTER Requests

A two-byte routine that exists purely to give the body at 5C93H a second name. It is CALLed at 52DAH, near the top of initialization, and again at 55D9H when a CMD shell-out returns from DOS: both are moments at which a BREAK or a shift-@ left over from whatever went before must not be allowed to fall into the BASIC session that is about to start. NOTE THAT THIS IS NOT DEVICE OR INTERRUPT STATE SETUP, as the earlier reading of the two call sites suggested. All it does is clear the low three bits of KFLAG$ 4423H, which is the same "clear the pending key requests" idiom used at the head of several SYS6 and SYS7 command overlays.

5C81H - Keyboard And BREAK Poll

CALLed from 5C64H on the keyboard-scan path and from 5822H inside CMD"*", the screen print. It reads KFLAG$ 4423H, the resident keyboard flag that the interrupt-driven keyboard task maintains, and reports bit 0 - BREAK - in the Z FLAG while returning the whole byte in Register A so that the caller can look at the PAUSE bit as well. If either BREAK or PAUSE is pending it first empties the type-ahead buffer, because the characters queued behind a BREAK are stale by definition. The routine leaves KFLAG$ itself alone; clearing the bits is the job of 5C93H below, and separating the two is what lets 5C64H test the PAUSE bit, act on it, and only then clear it.

5C9EH - Comma Fields And TAB

Reached through vector slot 41D3H, which the ROM CALLs from two places: 2108H, where a comma in a PRINT list has to be padded out to the next 16-column field, and 2141H, where TAB(n) has to pad to a requested column. Both decisions depend on knowing the current column, and the ROM's own column counter TTYPOS 40A6H tracks the SCREEN. When output is going to a file that is the wrong number entirely, so LBASIC substitutes the file's own column counter, which lives at offset 1 of the file buffer and is maintained by the byte writer at 61DEH-61ECH. Which of the two ROM continuations to rejoin is decided without any flag being passed in: the routine simply looks at the return address the ROM left, and 2108H's is below 2130H while 2137H's is above it.

5CB6H - Line Table Exit

Reached through vector slot 41B5H, which the ROM CALLs at 1AECH once it has finished rebuilding the line-link table - that is, immediately after a program line has been entered, altered or deleted. Together with 5CC3H below it forms a save-and-restore pair around the ROM's edit housekeeping: this half parks the current file pointer in TEMP2 40F3H and points file slot zero at a dummy buffer, and 5CC3H puts both back. The dummy is the byte at 65F2H, which is inside the run-time cell block above the loaded image, ships as 00H and is never written by anything in the file; since offset 0 of a file buffer is its mode, a buffer that begins there always reads as CLOSED. The same trick is used again by the program loader at 5EB7H and undone at 5ED6H, which is the clearest statement of what it is for: while the ROM is free to reorganise memory, no reference to file zero may find a live buffer.

5CC3H - Line Table Plus CLEAR Exit, And The PRINT Carriage Return Exit

Reached through vector slot 41B8H, which the ROM CALLs at 1AF2H - the same line-table point as 41B5H, but on the path that also performs a CLEAR. It reverses everything 5CB6H did. Its closing RET at 5CCFH is ALSO the whole body of a second routine: vector slot 41D0H, the exit taken after PRINT has sent a carriage return, points at 5CCFH, so that hook is a bare RETurn. LBASIC has nothing to do there, and rather than assemble a RET of its own it points the slot at one that already exists.

5CD0H - Number Conversion Exit

Reached through vector slot 41CDH, which the ROM CALLs at 20C6H once it has converted a number to its ASCII form and is about to print it. When output is going to the screen or the printer LBASIC steps aside; when a file is current it takes the statement over completely, discarding the ROM's return address and jumping into the PRINT continuation that sends the string through the file writer. The current-file test here is the same five-instruction idiom used at 5A2CH, 5BD1H, 5C00H and 5C18H, and it depends on POP not disturbing the flags.

5CDAH - The Shared File Reference Parser

The routine six other sections depend on, and the reason the file statements are as short as they are. It has three entry points and they divide the work cleanly. 5CEFH is the parser proper: it evaluates a file number, range-checks it against MAXFIL, indexes the file buffer pointer table and returns the buffer address in Register Pair BC together with the buffer's MODE byte in Register A. The mode is 01H for a file opened for sequential input, 02H for sequential output and 03H for random or direct access, and 00H for a slot that is not open. 5CDCH wraps that in the syntax an OUTPUT statement wants - an optional leading "#", the required mode, a required comma - and makes the file current; PRINT# reaches it from 5745H with Register C = 02H. 5CDAH is the same thing with Register C preset to 01H for input, used by INPUT# at 588EH and LINE INPUT# at 5D5DH. GET and PUT bypass both wrappers and call 5CEFH directly at 6209H so that they can insist on mode 03H themselves, and FIELD does the same at 607EH.

5D13H, 5D16H, 5D19H - MKI$, MKS$ And MKD$

Vector slots 416AH, 416DH and 4170H. The three functions turn a number into the string of raw bytes that a random file record holds: two bytes for an integer, four for single precision and eight for double. One body serves all three, because the byte count and the Level II type code VALTYP are the same number - 02H integer, 04H single, 08H double - so a single constant in Register A drives both the conversion and the allocation. The three entries are built with the skip-byte overlap that appears twice in this file: the bytes are 3E 02 / 01 3E 04 / 01 3E 08, so entering at 5D13H executes LD A,02H and the 01H that follows swallows the next LD A as the operand of a LD BC, while entering at 5D16H or 5D19H executes LD A,04H or LD A,08H instead.

5D2CH, 5D2FH, 5D32H - CVI, CVS And CVD

Vector slots 4152H, 4158H and 415EH, and the exact inverse of the three above: they take the raw bytes out of a string and read them as a number. The same three-entry overlap is used, but the constants are one LESS than the type code - 01H, 03H and 07H - because the first thing the routine does is compare the constant against the string's length, and the string must be LONGER than that to be long enough. Incrementing it afterwards produces the VALTYP to store. Note that the RAM reference page labels slot 4152H "ERCALL"; the vector table image at 4E00H points it at 5D2CH, which is CVI, and the three-entry construction proves the whole trio.

5D49H - READ And INPUT Assignment Exit

Reached through vector slot 41DCH, which the ROM CALLs at 222DH as it is about to take the next field out of the input line and assign it to a variable. If no file is current LBASIC steps aside and the ROM reads from the keyboard buffer as usual. If a file IS current the whole assignment is taken over: the field is scanned out of the file a character at a time by the collector at 5D71H below, and the result is handed back to the ROM at 2243H, past the point where it would have looked at the keyboard line. The only things this entry has to establish are which characters end a field and where to rejoin the ROM. Register D and Register E become the two terminator characters - a comma at 2CH and a space at 20H for a numeric field, a comma in both for a string field, since a string may legally contain blanks - and Register Pair BC becomes the ROM address to RETurn to. The LD BC,2243H and LD DE,2C20H instructions are therefore loading four independent BYTE constants, not two addresses; the second is immediately halved by 5D5AH on the string path.

5D5DH - LINE INPUT#

Reached from the LINE INPUT statement at 591AH once it has found a "#" and knows the source is a file. LINE INPUT takes an entire line, so it wants NO terminator characters at all except the carriage return that the collector handles separately, and it can only assign to a string. It sets both terminator registers to zero, locates the destination variable itself with the ROM's PTRGET, and stacks two return addresses so that when the collector finishes the value is stored by the ROM's own LET code and the output device is then reset - which is how a routine reached by a jump from the middle of a statement still unwinds tidily.

5E42H - MERGE

Vector slot 418BH. MERGE reads a program that was SAVEd in ASCII and folds its lines into the program already in memory, replacing any line whose number already exists. The remarkable thing about the implementation is how little of it there is: LBASIC opens the file, checks that it really is ASCII, backs the one byte it read out again, and jumps to the interpreter's ordinary command level. From there the ROM collects "typed" lines exactly as it always does - and the keyboard scan exit at 5C0EH quietly supplies each character from the file instead of from the keyboard, so the ROM's own line-insertion code does all the merging without knowing that anything is unusual. The end of the file is turned into a carriage return and a READY message by 5C4FH. This is the clearest illustration in the whole file of what the vector table is for.

5E64H - The Optional Line Number Parameter

A small helper with two entry points, used three times by the RUN and LOAD parser. Entered at 5E64H it expects either the end of the statement or a comma followed by a line number; entered at 5E68H it goes straight to the line number, which is what 5E97H wants because the digit has already been seen. Either way the result is deposited in the operand cell at 5FB2H, where the "start the loaded program" tail reads it, and a value of zero there means "from the beginning".

5E70H And 5E78H - RUN With A Filename, And LOAD

Vector slots 41C7H and 4188H. RUN"filespec" and LOAD"filespec" are the same routine with one bit of difference, and the difference is carried in the chain-state byte 65F4H: RUN sets it to 0FFH so that the program is started when the load finishes, LOAD sets it to 00H so that READY is printed instead. The two entries are the skip-byte overlap once more - the bytes at 5E77H are F6 AF, which is OR 0AFH entered at 5E77H and XOR A entered at 5E78H - so the RUN entry falls through the flag-setting code it needs and the LOAD entry starts one byte later. Both then accept the documented options: a line number, "R" to leave open files open, or "V" to keep the variables as well. The V case is the one that reaches BASIC/OV3 with function selector 04H, which is the fourth selector and the only one no other call site uses. Everything from 5EB7H onwards is shared: protect the file table across the NEW, read the first byte, and take one of two completely different routes according to whether the file is tokenized or ASCII.

5F54H - Move The Retained Variables Down Behind A Chained Program

The tail of the LOAD, RUN and MERGE code, reached from 5F52H when the chain-state byte 65F4H holds 0D6H. RUN"filespec",V is documented as loading a new program while keeping every variable and every open file, and this is the half of that mechanism which lives in BASIC/CMD: by the time it runs, the new program is in memory, VARTAB 40F9H has just been set to the byte after it, and the old variable area is sitting parked above STKTOP 40A0H where the NEW performed at 5EC5H could not reach it. The routine works out how far the variables have to travel, relocates ARYTAB 40FBH by that distance, block-moves the saved area down into place, restores STREND 40FDH, FRETOP 40D6H, STKTOP 40A0H, SAVSTK 40E8H and the Stack Pointer, clears the chain-state byte so the whole path is one-shot, and enters the new program. Five of its operands are the parked area's description - old VARTAB at 5F5EH, old ARYTAB at 5F65H, block length at 5F71H, saved FRETOP at 5F7EH and saved STKTOP at 5F84H - and all five are assembled as 0000H and are never written by any instruction in BASIC/CMD. The only candidate that can write them is BASIC/OV3, which the ",V" path CALLs at 5EB0H with function selector 04H, a selector no other call site uses; the same overlay is therefore also what writes 0D6H to 65F4H, because nothing in this file does. Confirm both when BASIC/OV3 is disassembled. Note that 5F56H-5F5BH is not part of this routine: it is the out-of-memory exit that the MERGE line-insertion loop above jumps into, and it happens to sit in the two bytes the JR at 5F54H steps over.

5F98H - Finish The Load And Start The Program

The ordinary tail of LOAD and RUN, reached from 5F52H when no variables are being carried over. It performs the CLEAR that RUN implies, then reads the chain-state byte once more to decide between printing READY and running the program. The one subtlety is that MAXFIL is temporarily set to zero across the CLEAR, exactly as it is at 5EB3H, so that the ROM's CLEAR cannot close the buffers - the "R" and "V" options both promise that open files survive a chained load, and this is where that promise is kept. The second half, from 5FB1H, is the common "start the program" entry that 5C41H and 5F96H both arrange to reach.

5FC4H - READY Exit

Vector slot 41ACH, which the ROM CALLs at 1A1CH on its way to displaying the READY prompt, and also called directly from 5C36H, 5E4AH, 5F93H and 6040H whenever LBASIC finishes an operation that has to leave the machine at command level. It does three things: reset the output device to the video display, close every open file, and - only when it really was the ROM's READY path that called it - run the protection check at 63EDH. That last test is made by looking at the return address rather than by any flag, so the four internal callers get the file closing without the check.

5FD8H - Post-Tokenize Exit

Vector slot 41B2H, which the ROM CALLs at 1AA1H the moment a line has been tokenized and it is about to decide whether that line is a program line or a direct statement. LBASIC only cares about the direct statement case, and only when a file is current - because a file is only current at this point during an ASCII LOAD or MERGE, and a "direct statement" arriving from a file means the file is not a BASIC program at all, or that one of its lines was longer than the 240 characters the collector allows. That is precisely the condition the manual describes for error 66.

5FECH - SAVE

Vector slot 41A0H. SAVE is really two routines sharing an OPEN. SAVE"filespec",A hands the whole job to the ROM's LIST code at 2B2EH, so an ASCII save is literally a LIST with the file as the output device - which is exactly why an ASCII SAVE and a MERGE are inverses of one another. SAVE"filespec" with nothing after it writes the tokenized program straight out of the program area. It plants the 0FFH marker that the loader tests at 5EE9H in the byte below the text, re-points the file control block's own sector buffer INTO the program area so that every record is written from where the program already is, PRE-EXTENDS the file to its finished length before a single record goes out, and only then writes the records one after another. The pre-extension is the point of the @POSN at 601DH: if the disk is going to fill up, it fills up before any of the program has been written.

6043H - CLOSE

Vector slot 4185H, and one of the neater pieces of housekeeping in the file. The ROM arrives with the flags the character fetch left when it ended the CLOSE token, so the Z FLAG on entry IS the argument test: Z means a bare CLOSE and every file is to be shut, NZ means a list of file numbers follows. Both halves end at the same worker at 6194H, which is entered by pushing its address and RETurning to it rather than by a CALL, because the address has to be carried in a register pair across the loop anyway. The all-files loop counts DOWN from MAXFIL to zero inclusive, so it closes LBASIC's own file zero as well as the operator's files - which is the reason 53CFH builds MAXFIL+1 buffers rather than MAXFIL.

6074H - NEW And END Close-Files Exit

Vector slot 41BBH, which the ROM CALLs at 1B8CH when NEW is executed and again at 1DB0H when a program reaches END or STOP. Both have to shut every open file, and all this routine does is manufacture the condition the CLOSE code reads as "no file list follows" and hand over to it.

607EH - FIELD

Vector slot 417CH. FIELD divides a random file's 256-byte data area into named string variables, and it does it without moving a single character: each variable's DESCRIPTOR is simply pointed at a slice of the buffer, with the length the statement gave it. Everything that later assigns to one of those variables through LSET or RSET at 60D8H therefore writes directly into the sector that will go to disk. The loop is unusually economical with registers - Register Pair BC is the buffer address on the first pass round and the WIDTH of the field just placed on every pass after it, so the single ADD HL,BC at 6098H serves both as "the data area starts here" and as "the next field starts here".

60D8H And 60D9H - RSET And LSET

Vector slots 419AH and 4197H, and another skip-byte overlap: the two bytes F6 37 are OR 37H entered at 60D8H, and the 37H alone is SCF entered at 60D9H. OR always CLEARS the CARRY FLAG, so RSET arrives with it clear and LSET with it set, and that one flag steers the whole routine to its two padding calls at 6145H and 6157H. Everything else is shared. The body assigns a string to a fielded variable WITHOUT altering that variable's length or its address: the characters are copied into the space FIELD gave it, truncated if there are too many and padded with spaces if there are too few - at the right-hand end for LSET, at the left-hand end for RSET. The one complication is a target whose characters live inside the program text, which must not be written in place; 60FDH-6115H detects that case and gives the target a private copy in string space first.

617BH - EOF

Vector slot 4161H. EOF(n) is a function rather than a statement, so the ROM's expression machinery has already evaluated its argument into the accumulator by the time this is reached, and the whole implementation is one DOS call: @CKEOF answers whether there is still a record to read. The answer is handed back as an integer - zero for false and minus one for true - which is what Level II expects of any relational result. A file open for sequential OUTPUT is rejected, because the question has no meaning there.

6194H - Close One File

The worker behind every kind of close in LBASIC. The CLOSE statement reaches it once per file at 6053H and 6073H; the READY exit CALLs it directly at 5FC7H, where Register A is zero because the ROM's FINPRT has just cleared it on its way through the PRINT completion hook, so THAT call closes FILE ZERO - the internal file LOAD, SAVE, MERGE and CMD"L" all use. Whatever the file was, the last thing that happens is that the first 34 bytes of its buffer are zeroed, which makes the mode byte 00H and blanks the control block; that is what makes the file "not open" as far as the parser at 5CFCH is concerned, and it is why the buffer can be handed straight back out again. A file open for sequential INPUT skips the DOS call altogether: nothing has been written to it, so the directory needs no update and @CLOSE would only cost a disk access.

61B2H And 61B7H - LOC And LOF

Vector slots 4164H and 4167H. LOC(n) returns the current record number and LOF(n) the number of the last record - the length of the file in records. The two functions differ only in which DOS vector they call, so LOF loads @LOF into Register Pair HL, LOC loads @LOC, and both fall into a shared tail that makes the call and delivers the answer as an integer. The call itself is made through the little JP (HL) at 61CFH, which is nothing more than a way to CALL a routine whose address is in a register pair; the byte writer at 61D0H sits immediately after it and is unrelated.

61D0H - The Byte Writer

Vector slot 41C1H, which the ROM CALLs at 032CH for every single byte it sends to any output device. Most of the time there is no file current and the byte is destined for the screen or the printer, and this routine passes it straight to the ROM's own $PUT and returns - but it also maintains, for whatever file IS current, that file's OWN print column at buffer offset 01, entirely separately from the screen's TTYPOS. That per-file column is what the comma-field and TAB hook at 5C9EH reads instead of TTYPOS when output has been diverted to a file, so that PRINT#1, with commas and TABs lines its columns up in the file exactly as it would on the screen. A carriage return resets the column to zero; any printable character advances it. The routine is entered with the current file pointer already known to be non-zero, so it does not repeat the current-file test.

6204H And 6205H - PUT And GET

Vector slots 4182H and 417FH, and the third of the file's F6-AF skip-byte overlaps. The two bytes F6 AF are OR 0AFH entered at 6204H and XOR A entered at 6205H; the first leaves Register A non-zero, the second leaves it zero, and that byte is stored at 65F6H as the discriminator the shared body reads at 624CH and 625BH to decide between @WRITE and @READ. So PUT and GET are one routine that transfers a whole 256-byte record between a random file's buffer and the disk, differing only in the direction of the transfer. An optional record number may follow; when it is present the file is @POSNed there first, and when it is absent the DOS simply uses the next record in sequence.

627BH - Read One Byte From The Current File Or Device

The single byte-input primitive of the whole extension, CALLed from nine places: the keyboard scan exit at 5C22H, the LINE INPUT# collector and the INPUT# field scanners at 5D74H, 5D8FH, 5DB2H, 5DD2H, 5DE0H and 5DF1H, the MERGE reader at 5E54H and the ASCII program loader at 5EDFH. It reads the next byte from whatever 65F8H currently names and returns it in Register A with the CARRY FLAG clear, or returns CARRY set to mean end of file. Registers BC, DE and HL are all preserved. The interesting part is the middle: LDOS uses two different result conventions for the same $GET call, and this routine picks between them by looking at the file control block's own type byte. For an OPEN DISK FILE (bit 7 of FCB+00 set) the Z FLAG means the transfer succeeded and NZ leaves an error number in Register A; for a DEVICE it is the keyboard convention, where a returned character sets NZ and the Z FLAG means nothing is available yet, so the routine simply asks again. That is what lets INPUT# read from *KI, *SI or a filtered device as naturally as from a disk file, and it is why the two exits are the same three POPs.

62A1H - The Filespec Builder

A short helper CALLed by OPEN at 633EH and by KILL at 6416H. It evaluates the string expression that names the file, copies it to a scratch area at 5414H with a zero terminator, and passes it to @FSPEC, which parses "NAME/EXT:d" into the file control block. The scratch area at 5414H sits in the start-up code around the sign-on entry, which has already run by the time any file is opened, so it is reused as workspace - the same space-reclaiming trick the keyboard buffer and the DOS-vector save area use. Register Pair BC on entry is the file's buffer address; it survives the call so that both callers get it back.

62DBH - OPEN

Vector slot 4179H, and the largest single routine in the extension. It parses the whole OPEN"mode",bufnum,"filespec"[,reclen] statement, decodes the one- or two-letter mode string into a byte of flags, then decides between @OPEN and @INIT according to whether the file must already exist. The mode letters follow the manual exactly: I input, O output, R random, E output-and-extend, with a second letter O ("must be old") or N ("must be new") allowed on the output modes. The routine returns to the ROM through FINPRT, whose address it pushes first. The bulk of it - the DOS-open decision and the buffer set-up - lives in the fall-through worker from 6333H, which SAVE, LOAD, MERGE and RUN also reach through 5E21H.

63EDH - The Memory-Protection Check

CALLed from the READY exit at 5FD2H (but only when the ROM's own READY code was the caller), from the post-tokenize exit at 5FE6H before any direct statement runs, and from the long error handler at 5A5BH. It clears the run-in-progress flag and then, if the open path at 63D4H recorded that the DOS cleared memory while a protected program was being loaded, it erases what is left of that program, does a NEW and raises error 90H. This is the mechanism behind the manual's "Protection has cleared memory" error: a program marked no-list, no-save cannot be left half-resident where the operator could examine it.

6412H - KILL

Vector slot 4191H. KILL deletes a named file from the disk. It has no buffer of its own to work in, so it borrows the internal file-zero buffer: it @FSPECs the filespec into that buffer's control block, @OPENs the file to get a valid control block, @KILLs it, and finally clears the borrowed buffer's mode byte so that file zero is left closed. There is no need to close the file after @KILL because @KILL releases it as it deletes it.

642FH - The Error-Code Table

Every "raise a fixed BASIC error" jump in the extension lands somewhere in this table, and the whole of it is one more application of the 01H skip-byte idiom - the same construction FDUBL uses at 5320H and PATCH at 5870H. Each entry is LD E,nn, two bytes, and between one entry and the next sits a single 01H byte, the opcode for LD BC,nnnn, which swallows the following LD E as its 16-bit operand when control arrives from above. So the table reads as a run of harmless LD BC instructions when entered at the top, but a jump straight to any entry executes just that one LD E,nn and falls through every 01H below it to the common JP 19A2H at 644CH, the ROM error entry. The number in Register E is TWICE the documented BASIC error code, because that is the convention the ROM's error routine uses for the disk errors. The very first entry, 642FH, is also the value planted in all ten USR vector slots at 5397H and the target of the FN evaluator's JP Z at 5608H, which is why "undefined user function" and "called an undefined USR" are the same error.

644FH - The DOS Error Translator

The other way an error is raised. Where the table above turns a FIXED BASIC error number into a message, this routine turns an LDOS error number - the kind a DOS call leaves in Register A - into the matching BASIC error. It cannot do the translation itself, because the mapping and the message text live in BASIC/OV3, so it loads that overlay with selector 02H and lets it do the work, then reaches the same ROM error entry the table uses. Every "JP NZ,644FH" after a DOS call in the extension ends here.

6459H - The Ready-Prompt Line Collector

The path 5BD8H hands control to when the ROM asks for a line and no file is current. It does far more than the ROM's own collector: at the READY prompt it turns the TRS-80's cursor-movement keys into a single-line editor, and it recognises one-letter command abbreviations. It only does any of this when the line is being collected for the ROM's MAIN direct-mode loop - it checks the return address two levels up against 1A7EH and steps quietly aside for an INPUT statement. The first keystroke is read on its own to decide which kind of line this is: an arrow or a full stop starts line navigation, a backspace or a tab edits the current line, and an ordinary character starts a normal line which is then collected by the ROM and, when complete, checked against the abbreviation table at 656BH. The TRS-80 video control codes used throughout are 0EH cursor on, 0FH cursor off, 1BH cursor up, 1DH move to the start of the line and 1EH erase to the end of the line.

6579H - The RST 10H Replacement

The keystone. Initialization installed this address at 4003H in place of the ROM's own CHRGTR at 1D78H, so every "fetch the next character of the program" in the whole machine now passes through here - thousands of times a second. Almost always it is transparent: it does the real fetch and returns. The one thing it adds is that when, and only when, the caller is the statement executor at 1D5BH - the point in NEWSTT at which the ROM is about to act on a statement keyword - it looks at the token and handles the two statements the ROM's dispatcher does not know. Token 90H is RESTORE, which LBASIC extends to accept a line number; the ROM's own RESTORE always rewinds to the first DATA statement. The other is a two-token form beginning 83H that repositions a random file. Because this hook owns the interpreter's inner loop it is the mechanism behind every keyword LBASIC adds that the ROM's token table does not contain, and it is why the single exit to DOS at 57BAH is so careful to put 1D78H back into the operand at 4004H first: leaving 6579H there would send every subsequent fetch into an image about to be overwritten.

65F2H - The Run-Time Cells

The last ten bytes of the loaded image, all shipping as 00H and none of them code. They are the extension's scratch variables, described in full in Section 25 of the working notes; they are listed here so that the disassembly accounts for every byte to 65FBH. The pointer table that begins at 65FAH grows two bytes per open file, so it starts inside the image and continues into the memory above it.