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

BASIC/OV3

Other Navigation

LDOS 5.3.1 BASIC/OV3 Disassembly - LBASIC Error Dictionary, Array Sort, Chained Load and Line Edit (Model I)

BASIC/OV3 is the one LBASIC overlay that has to be on the disk whenever DOS version 5 BASIC is running. The other three are loaded on demand by a single CMD statement and replace LBASIC's own image while they run; BASIC/OV3 is a subroutine library that LBASIC calls back into repeatedly, and the MISOSYS BASIC Reference Manual says plainly that it must always be present when programming in BASIC. It carries six services behind one entry point: the long error message dictionary that turns a Level II error number into English text, the translator that maps an LDOS error number onto a BASIC one, the CMD"O" string array sort, the machinery that keeps the variables alive across a chained load, and the two DOS version 5 single-key program line edit commands, M and C.

The overlay is a single LDOS load module of 1229 bytes: one type 1FH copyright record carrying "Copyright 1991 MISOSYS, Inc., All rights reserved", five type 01H load records and a type 02H transfer record. The image is contiguous at 4E00H-5281H, 1154 bytes with no gaps, and the transfer address is 4E00H. Alone among the four BASIC overlays it loads at 4E00H rather than 5200H, which is what lets it be a subroutine rather than a program: 4E00H-51FFH is the numbered SYS overlay area, free while a /CMD program is running, and BASIC/CMD has already emptied it by copying its two RAM hook images out to 4152H and 4000H during start-up. The top of the image, 5200H-5281H, does overlap BASIC/CMD's own banner, message and parameter table block, which is safe because none of that data is referenced once BASIC has started.

Entry is always at 4E00H with a FUNCTION SELECTOR in the alternate accumulator. The caller does LD A,n followed by EX AF,AF' before calling BASIC/CMD's loader at 54B6H, because the loader needs the primary accumulator for OVRLY$ and for the @LOAD error code. The first two instructions of the overlay write 01H into OVRLY$ at 430EH, and it is that byte the loader tests: when it already holds 01H the overlay is entered with no disk access at all. The overlay issues no RST 28H supervisor request of its own and calls no resident LDOS routine; every external call it makes is to a Level II ROM entry point, and the only LDOS cell it touches is OVRLY$.

The error dictionary is built the same way SYS4 builds the DOS error dictionary, and the resemblance is close enough to be deliberate. Messages are not stored as strings. A dictionary of seventy-seven English words holds each word once, with bit 7 set on its final character; an index table holds one entry per message, each entry a run of word numbers with bit 7 set on the last; and the expander walks both tables counting bit-7 bytes, so neither table needs offsets. Forty-nine messages are built from 428 bytes of dictionary and 127 bytes of index. The finished text is assembled into a buffer at 5414H, inside the block of BASIC/CMD start-up code that runs once and is never re-entered, which is the same space-reclaiming trick BASIC/CMD uses for its keyboard line buffer at 5309H and its DOS vector save area at 540AH.

File Format and Load Map

Memory Map

Function Selectors

Self-Modifying Code and Work Cells

Major Routines

Cross-Reference Notes

BASIC/OV3 is called only by BASIC/CMD, and always through BASIC/CMD's loader at 54B6H. The six call sites are 5A42H (long error messages, selector 01H), 644FH (DOS error translation, selector 02H), 5834H (CMD"O", selector 03H), 5EB0H (RUN and LOAD with the V option, selector 04H) and 6459H twice, through the one-letter abbreviation table at 656BH where M carries selector 05H and C carries 06H. Because selector 02H ends by jumping to the ROM error entry itself, the JP 19A2H at BASIC/CMD 6456H that follows that call is never reached.

The overlay makes no RST 28H supervisor request and calls no resident LDOS routine. OVRLY$ at 430EH is the only LDOS cell it touches, and it is written once, at 4E02H, as the resident marker BASIC/CMD's loader tests. Everything else it reads or writes below 4200H is a Level II BASIC RAM cell: STKTOP 40A0H, TXTTAB 40A4H, FRETOP 40D6H, VARTAB 40F9H, ARYTAB 40FBH, STREND 40FDH and the Disk BASIC vector table slot operand at 41B0H.

The Level II ROM entry points it uses are the error entries 1997H, 197AH, 19A2H, 1E4AH and 1ED9H, the line number parser LINSPC 1E4FH, the positive integer evaluator INTID2 1E46H, the line finder FNDLIN 1B2CH, the variable locator PTRGET 260DH, the string space allocator GETSPA 28BFH and the untokenizer BUFLIN 2B7EH, plus the RST 08H, RST 10H and RST 18H hooks at 4000H, 4003H and 4006H, which LBASIC has already pointed at the ROM or at its own replacements.

Two of the ROM entries are taken part way into a routine rather than at its front door, and both are worth knowing about in their own right. EDITRT at 2FEBH is the common exit of the EDIT command: it reloads Register Pair HL from BUFPNT at 40A7H, returns at once if the Z FLAG says there is no line number, and otherwise sets the CARRY FLAG to mark a line number as already collected and jumps to EDENT at 1A98H, which tokenizes the buffer and inserts it as the line numbered in Register Pair DE. That is the whole of how a line is entered without being typed. 2BCAH is three instructions into DELETE, past the range scan SCNLIN at 1B10H and the POP DE that follows it, and expects Register Pair BC pointing at the first line of the range with Register Pair DE holding the last line NUMBER of the range; because FNDLIN preserves Register Pair DE, one call to FNDLIN sets up both and produces a range of one line.

Three cells inside BASIC/CMD's image are written from here and nowhere else: the chain state byte 65F4H when it holds 0D6H, the last DOS error byte 65F7H, and the five operand cells of the chained-load fixup at 5F54H. The message assembly buffer at 5414H and the line input buffer reached through BUFPNT 40A7H are both shared with BASIC/CMD, and in both cases the sharing is safe because the BASIC/CMD code that occupies those addresses runs only once, during start-up.

4E00H - Overlay Entry Point and Function Selector Dispatcher

BASIC/OV3 is a SUBROUTINE overlay, not a program. BASIC/CMD loads it at 4E00H through the loader at 54B6H and enters it with a RET, so the overlay is reached with BASIC/CMD's own return address on the stack and every selector path here ends by returning to it. The function selector is carried in the ALTERNATE accumulator because the loader needs the primary accumulator for OVRLY$ and for the @LOAD error code, so the first thing the dispatcher does after marking itself resident is EX AF,AF' to bring the selector into Register A. Six selectors are implemented.

4E1BH - Selector 01H: Expand a BASIC Error Number into Message Text

Level II BASIC in ROM prints two-letter error abbreviations. LBASIC replaces that with full English text by hooking the ROM error path, and this routine is the dictionary lookup behind it. Register L arrives holding the ROM error value, which is twice the documented BASIC error code. The routine converts that value to an index, walks the message index table at 5057H to the matching entry, then walks the word dictionary at 50D6H once per word number in the entry, copying the words into a buffer with single spaces between them. It returns Register Pair HL pointing at the assembled text so the caller can hand it to the ROM string printer STROUT at 28A7H.

4E6BH - Selector 02H: Translate an LDOS Error Number into a BASIC Error

When a disk operation fails, LDOS returns an error number of its own that has no meaning to Level II BASIC. This routine records that number for later inspection by CMD"E" and then converts it into a Level II error value through the 42-entry lookup table at 502DH, entering the ROM error handler with the result. It never returns.

4E80H - Selector 03H: CMD"O" String Array Sort, Argument Parsing

CMD"O",numelem,firstelem sorts a singly dimensioned string array in place. The manual states that the sort starts at the element given and covers the number of elements given, and that the count must not run past the end of the array; nothing in this code checks that, so the caller carries the responsibility. BASIC/CMD reaches here with a JP rather than a CALL, from the CMD"O" stub at 5834H, so this routine's RET returns to whatever called the CMD statement handler. On entry Register Pair HL points at the BASIC text immediately after the closing quotation mark of the CMD string.

4E95H - CMD"O" Sort: Halve the Gap and Test for Completion

The sort is a Shell sort. The gap starts at half the element count and is halved on every pass; when it reaches zero the array is ordered and the routine returns. This block is the top of the outer loop, re-entered from 4F16H after every complete pass.

4EADH - CMD"O" Sort: Compare and Exchange

One position of one pass. The element at the current position and the element a gap above it are compared as strings, and if they are out of order their three-byte descriptors are exchanged and the comparison is repeated a gap lower down, which is what turns a plain gapped exchange into a proper Shell sort. Level II holds a string variable as a three-byte descriptor of length followed by text address, so exchanging descriptors reorders the array without moving any string text.

4F19H - Selector 04H: Retain the Variables Across a Chained Load, Simple Variables

RUN"filespec",V and LOAD"filespec",V load a new program but keep the current variables. BASIC/CMD calls this selector from 5EB0H after the filespec has been parsed and BEFORE the ROM NEW at 5EC5H wipes the variable area, and everything the later fixup code at 5F54H needs is set up here, because nothing in BASIC/CMD writes any of it. The work is in three stages. First the simple variables are walked, function definitions are voided and any string whose text still lives inside the program is copied into string space so that it survives the load. Then the arrays are walked for the same reason. Finally the whole variable block is moved up under the stack and the five operand cells in BASIC/CMD are filled in. This block is the first stage.

4F3FH - Chained Load: Walk the Arrays

The array table runs from ARYTAB to STREND. Each array is a type byte, two name characters, a two-byte block length, a dimension count, one two-byte size per dimension and then the elements. Only string arrays need attention, and for those every element descriptor is passed to the same relocator the simple variables used.

4F6AH - Chained Load: Move One String Body into String Space

A Level II string variable is a three-byte descriptor of length followed by text address, and the text itself may live in one of two places. A string assigned from a quoted constant points straight into the program text, which costs nothing while that program is loaded but is worthless once it has been replaced. A string built at run time already lives in string space at the top of memory and needs no attention. This routine tells the two apart by two address comparisons and copies only the first kind, rewriting the descriptor to point at the new copy. Entry is with Register Pair HL at the descriptor and Register Pair DE at the top of the region being scanned. Exit is always with Register Pair HL advanced by three, so the caller can walk straight on.

4F99H - Chained Load: Park the Variable Block and Seed the BASIC/CMD Operand Cells

Every string that had to be rescued has been rescued, so the whole variable block from VARTAB to STREND can now be lifted out of the way and the load allowed to proceed. The block is moved to sit just below the stack, STKTOP is lowered to protect it, and the five 16-bit operand cells that BASIC/CMD's fixup code at 5F54H reads are filled in. Those five cells ship as 0000H in the BASIC/CMD image and NO instruction in BASIC/CMD ever writes them, so this is their only source. The chain-state byte 65F4H is set to 0D6H last, and that is likewise the only place in either module the value 0D6H is written.

4FD6H - Selectors 05H and 06H: the M and C Program Line Edit Commands

The two single-key edit commands that DOS version 5 LBASIC keeps in this overlay. C n1,n2 duplicates line n1 as a new line n2, and M n1,n2 does the same and then deletes n1. Line n1 must exist and line n2 must not. BASIC/CMD's READY prompt line collector at 6459H recognises the letters through its abbreviation table at 656BH, where M carries the selector value 05H and C carries 06H, and the manual notes that both commands clear the variables and close open files, which is a consequence of the line being re-entered through the ordinary tokenizer. The two selectors share one body: the difference is a single flag pushed at 4FD8H and tested at 500DH. Both entries lean on the ROM twice over. The new line is entered by handing the untokenized text to EDITRT at 2FEBH, the exit the EDIT command itself uses, and for a move the old line is removed by jumping into the DELETE body at 2BCAH with a one-line range already set up. Neither borrowed entry point is the routine's own front door, which is why the register conditions are spelled out on each row.

502DH - Data: LDOS Error Number to BASIC Error Value Table

Forty-two bytes, one per LDOS error number from 0 at 502DH to 41 at 5056H. Each byte is the value the Level II ROM error handler expects in Register E, which is twice the documented BASIC error code. LDOS distinguishes far more failures than BASIC has messages for, so the table is heavily many-to-one: twenty-one different LDOS numbers all report Disk I/O error, which is exactly why the manual recommends CMD"E" for the real reason. Selector 02H at 4E6BH is the only reader.

5057H - Data: Message Index Table

Forty-nine entries, 5057H to 50D5H. Each entry is a run of word numbers into the dictionary at 50D6H, with bit 7 set on the last of them, and the entries are laid out so that the entry number is the BASIC error code plus one for the ROM range and the code less twenty-four for the disk range. The expander at 4E36H reaches the entry it wants by counting bit-7 bytes, so the entries can be any length and no offset table is needed. This is the same three-table scheme SYS4 uses for the DOS error dictionary.

50D6H - Data: Word Dictionary

Seventy-seven English words plus a leading marker byte, 50D6H to 5281H, and the last data in the file. Each word is stored once in plain ASCII with bit 7 set on its final character, and messages are built by naming the words rather than by repeating them: "out" and "of" are each stored once and used by four messages, "file" by nine. Case is stored as written, so GOSUB, RESUME and FIELD keep their capitals while everything else is lowercase and gets its initial capital from the RES 5,(HL) at 4E68H.