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

BASIC/OV2

Other Navigation

LDOS 5.3.1 BASIC/OV2 Disassembly - The LBASIC Cross Reference Overlay (Model I)

BASIC/OV2 is the overlay behind LBASIC's CMD"X" statement, the DOS version 5 cross reference facility. It reads the tokenised BASIC program that is sitting in memory and produces a listing of every variable and every line number reference, each followed by the numbers of the lines in which it appears. The banner it prints identifies it as "BASIC Cross Reference Listing Utility - Version 1.22", copyright 1987 MISOSYS, Inc. DOS version 6 replaces it with the separate BREF/CMD utility, which is run from the DOS Ready prompt rather than from inside BASIC.

The documented syntax is CMD"X devspec/filespec -V|=var,-L|=lnum,<title>". The device or file specification chooses where the listing goes; if it is omitted the listing goes to the video display, and if it names a disk file the default extension /TXT is supplied. A leading -V restricts the listing to variables and -L restricts it to line numbers; an =name or =number restricts it to that one entry; and any text between angle brackets becomes a title printed at the head of every page. Both BASIC/CMD and BASIC/OV2 must be present on the disk, and a program which contains a line number zero cannot be cross referenced.

The overlay is reached from LBASIC's CMD dispatcher. BASIC/CMD evaluates the quoted string at 57C6H, sends anything two characters or longer to 5454H, requires the second character to be a space, matches the first against N, X and V, and for X loads Register B with 32H. 54A5H then builds the file specification "BASIC/OV" plus the digit 2 into CFCB$ at 4480H and 5484H does LD HL,4319H / LD DE,4480H / JP 4433H, so @RUN loads this overlay over LBASIC's own image at 5200H and enters it at 5200H with Register Pair HL pointing at the parameter text inside INBUF$ at 4318H. That is the same entry convention BASIC/OV1 uses for CMD"N" and BASIC/OV4 uses for CMD"V". The overlay exits by planting "BASIC/CMD" in CFCB$ at 4480H and an asterisk in INBUF$ at 4318H and issuing @RUN again, so the interpreter is reloaded and re-entered with the program and the variables intact.

File Format and Load Map

BASIC/OV2 is a standard LDOS load module of 1647 bytes. It carries one type-1FH comment record holding "Copyright 1991 MISOSYS, Inc., All rights reserved", then six 256-byte type-01H load records at 5200H, 5300H, 5400H, 5500H, 5600H and 5700H, a 28-byte type-01H load record at 5800H, and a type-02H transfer record with the entry address 5200H. The image is therefore 5200H-581BH, 1564 bytes, contiguous with no gaps and with no byte loaded twice. Executable code occupies 5200H-5720H and data occupies 5721H-581BH. Everything the overlay uses above 581BH is uninitialised RAM which it simply claims.

Memory Map

Address Range	Contents
5200H-5720H 1313 bytes	Executable code. Entry is at 5200H and every exit path converges on 568DH.
5721H-581BH 251 bytes	Data: the form feed byte, the title buffer, the column heading line, the rule fragments, the two run-time work bytes 5793H and 5794H, the BREAK message, the default extension, the sign-on banner and the out-of-memory message.
581CH-5866H 75 bytes	Work cells above the loaded image. Name buffers, the output field, the list pointers, the switch flags and the 32-byte file control block of the listing output file.
5900H-59FFH 256 bytes	The sector buffer handed to @INIT for the listing output file.
STREND+5 upward 2 bytes per entry	The list of line numbers collected for the entry currently being listed. It grows above STREND at 40FDH and is refused room at STKTOP at 40A0H.

How the Listing is Produced

There is no sort table anywhere in the overlay. Instead one complete pass is made over the BASIC program for every entry that is printed. Each pass starts with the current-entry cell 5824H filled with 0FFH, which is higher than any character that can start a name, and with the previous-entry cell 581CH holding the name that was printed last. Every reference the scanner finds is compared against both: it is discarded unless it is higher than the name already printed and lower than or equal to the best candidate found so far in this pass. When a candidate displaces the current best the line number list is reset and collection starts again; when a candidate matches the current best its line number is appended. At the end of the pass the winner is printed together with its line numbers, it becomes the new previous entry, and another pass is run. When a pass finds nothing at all the listing is complete.

The program text scanner at 538AH is what makes the references reliable. It reads the tokenised line through Register Pair IY as (IY+04H), because a Level II BASIC line record is a two-byte link to the next line, a two-byte line number, the tokenised text and a 00H terminator. It returns at once on the REM token 93H, skips the whole of a string literal, skips a DATA item list to its closing colon or to the next token, and skips numeric constants including the hexadecimal and octal forms introduced by an ampersand. A variable name is collected as its first letter, its second character, any type declaration character and any opening parenthesis, which is exactly the identity Level II BASIC itself gives a variable, so A, A1, A$ and A( are listed as different entries while ALPHA and ALTITUDE are correctly listed as the same one. A line number is collected only after one of the seven tokens that may precede one - THEN, ELSE, RESUME, GOTO, GOSUB, RUN and ERL - and is right-justified in five characters with leading zeros so that the same character comparison that orders names also orders numbers correctly.

Variable and Work Cell List

Address Range	Purpose
55FBH-55FCH 2 bytes	Output Control Block Operand Self-modifying code. The operand of the LD DE,0000H at 55FAH inside the string output routine. 5255H writes the listing file control block address 5847H here, 55E8H writes the video control block address DODCB$ 401DH and 55F2H writes the printer control block address PRDCB$ 4025H.
5721H 1 byte	Page Break Form Feed The 0CH printed immediately before the title at every page break.
5722H-575FH 62 bytes	Title Buffer Cleared to a single 00H at 5578H and filled by 55C6H from the text between angle brackets, up to 58 characters plus a carriage return and a terminator.
5793H 1 byte	Output Destination Flag The first byte of the output file control block as @FSPEC left it. 00H means no output was specified and the listing goes to the video, 2AH means a device, and a letter means a disk file which 5710H must close.
5794H 1 byte	Page Line Counter Incremented at 5609H for every carriage return sent and cleared at 5613H for every form feed. 50 lines force a page at the start of a new entry, 55 lines force one at the end of an output line.
581CH-5823H 8 bytes	Previous Entry The reference that was listed last. Filled with blanks at 526DH so the first pass accepts anything, and updated at 5303H after each entry is printed.
5824H-582BH 8 bytes	Current Entry The lowest acceptable reference found so far in the pass now running. Filled with 0FFH at 5285H at the start of each pass, unless an =name or =linenumber parameter has put a specific request there.
582CH-5833H 8 bytes	Candidate Reference The buffer the scanner writes each name or line number into. Blanked at 5299H before every call.
5834H-583BH 8 bytes	Output Field The seven-character field every piece of the listing is built in, plus its 00H terminator. 5834H and 583AH hold the colons that bracket the reference column.
583CH-583DH 2 bytes	Line Number List Pointer Set to STREND+5 by 5515H, advanced by 552FH while the list is built and by 5555H while it is read back.
583EH-583FH 2 bytes	Previous Line Number Cleared by 5521H and used by 5555H so that several references to the same name in one program line print that line number only once.
5840H 1 byte	Pass Result Flag Cleared at 5274H and set to 01H at 52EAH when a pass accepts any reference. A pass that leaves it clear ends the listing.
5841H 1 byte	Output Field Counter The number of fields already placed on the current output line. A count of 1 makes the field the bracketed reference column; a count of 10 forces a continuation line.
5842H 1 byte	Line Number List State Set to 01H at 5440H while a comma-separated list of line numbers such as an ON n GOTO is being read, so the next call to the scanner resumes at 5416H instead of restarting the token scan.
5843H 1 byte	Restriction Switch 56H for -V, variables only; 4CH for -L, line numbers only; 00H for both. Written at 558CH and read at 52AAH.
5844H 1 byte	Specific Entry Flag Set to 01H at 55BAH when the parameter text carried an =name or =linenumber. It stops 5273H from resetting the current entry, makes 52C9H reject every other name, and makes 534DH end after a single pass.
5845H-5846H 2 bytes	Parameter Text Pointer The position reached in the CMD"X parameter text. Written at 5213H and again at 5229H once @FSPEC has consumed the file specification, and read at 5258H before the switches are parsed.
5847H-5866H 32 bytes	Listing File Control Block Filled by @FSPEC at 5223H, extended by @FEXT at 5234H, opened by @INIT at 5240H and closed by @CLOSE at 571DH.
5900H-59FFH 256 bytes	Listing File Sector Buffer Handed to @INIT at 5237H with a logical record length of 00H, meaning 256 bytes, so the listing is written as a plain byte stream.

Major Routines

Address	Routine
5200H	Entry Point Entry Register Pair HL at the CMD"X parameter text in INBUF$ 4318H. Skips blanks, prints the banner through @DSPLY, folds the text to upper case, and opens the listing file with @FSPEC, @FEXT and @INIT. Exit is into 5246H.
5273H	Selection Pass Entry with 581CH holding the entry listed last. Walks every program line from TXTTAB 40A4H, keeps the lowest reference above 581CH in 5824H and its line numbers in the list above STREND, and sets 5840H if anything was found. Exit into 52EFH.
52EFH	Print One Entry Entry with 5824H holding the entry and the line number list terminated. Prints the bracketed reference column and eight line numbers per line, wrapping onto continuation lines. Exit to 534DH.
5360H	Compare Two Strings Entry Register Pair HL and Register Pair DE at two 00H terminated strings. Exit with the Z FLAG set when they match and the CARRY FLAG set when the string at Register Pair DE is the lower; both registers are preserved.
5374H	Copy a String Entry Register Pair HL at the source and Register Pair DE at the destination. Copies up to but not including the 00H terminator, so trailing blanks in the destination survive.
537BH	Fill a Name Field Entry Register Pair HL at an eight-byte field. 537BH fills with blanks; 537DH fills with the character in Register A. Register Pair HL and Register Pair BC are preserved.
538AH	Program Text Scanner Entry Register Pair IY at the current program line record and Register Pair HL at the candidate buffer. Exit with the next variable name or line number reference in the buffer, or with the buffer still blank at the end of the line.
5414H	Line Number Collector Entry Register Pair IY on a reference token. Skips blanks, commas and the equals token, drops leading zeros, takes up to five digits and right-justifies them with leading zeros. Sets 5842H so an ON n GOTO list is followed through.
5479H	Character Classifier Entry Register Pair IY on the character. Exit Register A = 0 for a token or other non-name character, 1 for a digit, 2 for a letter, 3 for one of ! # $ %, and 4 for an opening parenthesis, with the Z FLAG set only for 0.
54AEH	Line and Page Control 54AEH ends an output line and turns that into a page break past 55 lines. 54B9H starts a new entry, drawing the rule and throwing a page past 50 lines. 54CFH draws the seven-character rule.
54F6H	Output Field Manager 54F6H starts a new output line; 54FAH blanks the field at 5834H, counts it in 5841H and brackets it with colons when it is the first field of the line. Exit Register Pair HL at 5834H and Register A holding the count.
5515H	Line Number List 5515H points the list at STREND+5; 5521H terminates it and rewinds it; 552FH appends the line number from IX+02H and IX+03H and checks the list against STKTOP 40A0H; 5555H reads the next number back, suppressing repeats.
5570H	Parameter Parser Entry Register Pair HL after the output specification. Sets 5843H from -V or -L, builds an =name or =linenumber into 5824H and sets 5844H, and copies a title between angle brackets into 5722H.
55F6H	String Output Entry Register Pair HL at a 00H terminated string. Sends every character through $PUT 001BH to the control block whose address is in the self-modified operand at 55FBH, counts lines in 5794H, calls @KITSK 4300H between characters, and honours PAUSE and BREAK through KFLAG$ 4423H. Register Pair HL, Register Pair DE and Register Pair IY are preserved.
5661H	Keyboard Flag Poll Reads KFLAG$ 4423H, drains the type-ahead through @KBD 002BH when BREAK or PAUSE is pending, and returns Register A holding the flag byte with the Z FLAG reflecting the BREAK bit. 5673H clears the low three bits.
568DH	Common Exit The single way out. Closes the listing file through 5710H, plants "BASIC/CMD" in CFCB$ 4480H and an asterisk in INBUF$ 4318H, and jumps to @RUN 4433H so the interpreter is reloaded over this image and re-entered with the program intact.
56B0H	Upper Case Conversion Entry Register Pair HL at the parameter text. Converts every lower case letter in place and stops at the first byte below 20H. Register A, the flags and Register Pair HL are preserved.
56C8H	Line Number to ASCII Entry Register Pair HL holding the number. Uses ROM MAKINT 0A9AH, FOUINI 1034H and FOUT2 0FD9H. Exit Register Pair DE one past the text in FBUFFR 412FH, Register Pair HL unchanged.
56D8H	Program Line Navigation 56D8H steps Register Pair IX to the next line record; 56E8H reports a 0000H link word, the end of the program, with the Z FLAG.
56F2H	Reference Token Test Entry Register A holding a program byte. Exit with the Z FLAG set for THEN 0CAH, ELSE 95H, RESUME 9FH, GOTO 8DH, GOSUB 91H, RUN 8EH or ERL 0C2H.
5708H	DOS Error Exit Entry Register A holding a DOS error number. ORs it with 0C0H, reports it through @ERROR 4409H and falls out through 568DH.

Cross Reference Notes

BASIC/OV2 is called only by BASIC/CMD, through the CMD statement dispatcher at 57C6H and the overlay dispatcher at 5454H, and it calls only BASIC/CMD, by reloading it at 56A2H. It 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 ROM entry point, so no request code row on the main LDOS disassembly index changes.

The resident LDOS vectors it uses are @DSPLY at 4467H for the banner, @FSPEC at 441CH and @FEXT at 4473H to build the output file control block, @INIT at 4420H to create the listing file, @CLOSE at 4428H to close it, @ERROR at 4409H for both error paths, @KITSK at 4300H between output characters, and @RUN at 4433H to reload the interpreter. It reads KFLAG$ at 4423H directly and writes it back with the low three bits cleared. The device control blocks DODCB$ at 401DH and PRDCB$ at 4025H are used as output destinations.

The Level II ROM entry points it uses are $PUT at 001BH for every character of the listing, @KBD at 002BH to drain the type-ahead, $KEY at 0049H to hold the display during a pause, and MAKINT at 0A9AH, FOUINI at 1034H and FOUT2 at 0FD9H to convert a line number to text in FBUFFR at 412FH. The Level II BASIC workspace cells it reads are TXTTAB at 40A4H, the start of the program text; STREND at 40FDH, above which the line number list is built; and STKTOP at 40A0H, which is the ceiling that list may not cross.

Two details are shared with BASIC/OV1 and are worth reading together. The seven-token reference set tested at 56F2H here is the same set BASIC/OV1 tests at 55A8H when it renumbers a program. The exit stub is the same too, down to the unused letter L that sits immediately below the "BASIC/CMD" string: BASIC/OV1 carries it at 55C7H and BASIC/OV2 carries it at 56A5H, and in both overlays the copy into CFCB$ starts one byte later.

One routine in the image has no caller. 55EEH is the printer counterpart of 55E4H and would aim the output routine at PRDCB$ at 4025H; nothing in the overlay reaches it, because the printer is selected by naming *PR as the output device rather than by a switch.

5200H - Entry Point, Sign On and the Output File

Register Pair HL arrives pointing at 4319H, one byte into INBUF$ at 4318H, at whatever followed CMD"X and its separating space. This block skips leading blanks, displays the banner, folds the whole parameter text to upper case and, if a device or file specification was given, parses it, applies the default extension /TXT and opens it with @INIT.

5246H - Select the Output Destination and Print the Headings

With the output file open, the string output routine is aimed at either the video display control block DODCB$ at 401DH or the file control block at 5847H, the remaining parameters are parsed, and the title and column headings are printed. The line number list is pointed at the free memory above STREND at 40FDH.

5273H - The Selection Pass Over the Program Text

This is the outer loop of the utility. One pass walks every line of the BASIC program, collects every variable name and line number reference, and keeps the lowest one that is still higher than the name printed by the previous pass, together with the numbers of the lines that mention it. No sort table is used; the ordering falls out of running the pass once per entry.

52EFH - Print One Cross Reference Entry

The entry selected by the pass just finished is printed as a seven-character reference column followed by its line numbers, eight to a line, wrapping onto continuation lines with an empty reference column.

534DH - End of the Listing

Reached when a selection pass finds nothing left to list, or after the single entry named by an =name or =linenumber parameter has been printed.

5360H - Compare Two Zero Terminated Strings

The comparison that orders the cross reference. Register Pair HL addresses one string, Register Pair DE the other; both registers are returned unchanged and the caller reads the Z FLAG and the CARRY FLAG.

5374H - Copy a Zero Terminated String

Copies from Register Pair HL to Register Pair DE, stopping at but not copying the 00H terminator so that trailing blanks already in the destination survive.

537BH - Fill an Eight Byte Name Field

Writes seven copies of a fill character followed by a 00H terminator. Entering at 537BH fills with blanks; entering at 537DH fills with whatever the caller has put in Register A.

538AH - The Program Text Scanner

Walks the tokenised BASIC line with Register Pair IY, reading each byte as (IY+04H) because the line record begins with a two-byte link and a two-byte line number. It skips string literals, REM comment text, DATA item lists and numeric constants, recognises the seven tokens a line number may follow, and otherwise collects a variable name.

5406H - Skip a Quoted String Literal

Runs forward to the closing quotation mark so that names and numbers inside a string constant are never listed.

5414H - Collect a Line Number Reference

Entered after one of the seven reference tokens. Blanks, commas and the equals token are skipped so that an ON n GOTO list is followed all the way through; leading zeros are dropped; up to five digits are taken and the result is right-justified with leading zeros so that a character comparison orders line numbers numerically.

5472H - Store a Character and Classify the Next

A two-part helper: it stores the character under Register Pair IY into the buffer at Register Pair HL, advances both pointers, and then falls through into the classifier so the caller is told what the next character is.

5479H - The Character Classifier

Returns Register A as 0 for a BASIC token or any other character that cannot be part of a name, 1 for a digit, 2 for a letter, 3 for one of the type declaration characters ! # $ %, and 4 for an opening parenthesis.

54AEH - End the Output Line and Break the Page

54AEH ends the current line, turning that into a page break when the page line counter 5794H has reached 55. 54B9H is the entry used when a new cross reference entry begins, which draws the separator rule and throws a page once 50 lines have been used.

54CFH - Draw the Reference Column Rule

Prints a carriage return, a plus sign, five hyphens, a plus sign and a carriage return. The five hyphens match the five character positions between the colons of the reference field at 5834H.

54F6H - The Seven Character Output Field

All listing output is built in the eight bytes at 5834H-583BH. 54F6H starts a new output line by zeroing the field counter 5841H; 54FAH blanks the field, counts it, and brackets it with colons when it is the first field of a line.

5515H - Reset the Line Number List Pointer

The collected line numbers are kept in the free memory above STREND at 40FDH, which is the first byte above all of the BASIC program's variables.

5521H - Terminate the Line Number List

Writes the 0000H terminator, clears the duplicate suppression cell and resets the list pointer so the same pointer reads the list back.

552FH - Append a Line Number to the List

Copies the line number field of the program line record Register Pair IX is standing on into the list, and checks that the list has not grown up into string space.

5555H - Read the Next Line Number from the List

Advances the list pointer, suppresses a number identical to the one before it, and reports the 0000H terminator with the Z FLAG.

5570H - Parse the Switches, the Named Entry and the Title

Handles the -V and -L restriction switches, the =name or =linenumber form that limits the listing to a single entry, and the title enclosed in angle brackets.

55E4H - Force the Output to the Video or the Printer

Two entry points that rewrite the self-modified output control block operand at 55FBH. 55E4H selects the video display and is used for the messages that must be seen even when the listing is going to a file. 55EEH selects the line printer and has no caller in this overlay.

55F6H - Send a String to the Current Output

The single output path of the utility. It counts lines for the page break logic, sends each character through the ROM routine $PUT at 001BH, gives any resident keyboard task its turn, and honours PAUSE and BREAK.

5661H - Poll the Keyboard Flag Byte

Reads KFLAG$ at 4423H, the resident byte in which the LDOS keyboard driver records a BREAK, PAUSE or ENTER request, and drains the type-ahead before reporting the BREAK bit.

5673H - Clear the Pending Key Requests

Clears the low three bits of KFLAG$ at 4423H so that a key pressed during the listing does not fall through into the BASIC session afterwards.

567EH - The BREAK Exit

Prints "Break" on the video display and falls into the common exit.

568DH - Close the Listing and Reload the Interpreter

The single exit from the overlay. Every path through the utility ends here. The listing file is closed if one was opened, the file specification of the interpreter is planted in CFCB$ at 4480H, an asterisk is planted in INBUF$ at 4318H so that BASIC/CMD re-enters with the program and the variables intact, and @RUN loads BASIC/CMD back over this image.

56B0H - Fold the Parameter Text to Upper Case

Converts every lower case letter of the CMD"X parameter text in place and stops at the first control character, which is the carriage return ending the line in INBUF$ at 4318H.

56C8H - Convert a Line Number to ASCII

Hands the 16-bit value in Register Pair HL to the Level II ROM number formatting routines and returns Register Pair DE addressing the resulting text in the ROM buffer FBUFFR at 412FH.

56D8H - Advance to the Next Program Line

Steps Register Pair IX past the link word and the line number and then forward to the 00H that ends the tokenised text, leaving it on the first byte of the following line record.

56E8H - Test for the End of the Program

Reads the two-byte link word of the record Register Pair IX is standing on and reports 0000H, the end of the BASIC program, with the Z FLAG.

56F2H - Test for a Line Number Reference Token

The seven Level II BASIC tokens that may be followed by a line number. This is the same set BASIC/OV1 tests at 55A8H when it renumbers a program.

5708H - The DOS Error Exit

Reached when @FSPEC rejects the output specification or @INIT cannot create the file.

5710H - Close the Listing File

Closes the output file, but only when 5793H shows that a real disk file was opened rather than the video or a device.

5721H - Data - The Form Feed Byte and the Title Buffer

Not executable. 5721H is the form feed printed at a page break; the title buffer that follows it is 5722H-575FH and is large enough for the 58 characters the parser accepts plus a carriage return and a terminator.

5760H - Data - The Column Heading Line

Not executable. Printed when the listing starts and at the top of every new page.

578AH - Data - Rule Fragments, Control Strings and Work Bytes

Not executable. Five short strings that build the +-----+ rule and end the output lines, followed by the two run-time work bytes that live inside the loaded image.

5795H - Data - The BREAK Message and the Default Extension

Not executable.

579EH - Data - The Sign On Banner

Not executable. Sent to @DSPLY at 4467H, which stops on the carriage return at 580AH.

580BH - Data - The Out of Memory Message

Not executable. Printed on the video display when the line number list grows past STKTOP at 40A0H.