TRS-80 DOS - LDOS 5.3.1 for the Model I - PR/FLT Disassembled

PR/FLT

Other Navigation

LDOS 5.3.1 PR/FLT Disassembly - The Printer Forms Filter (Model I)

PR/FLT is the LDOS version 5 printer forms filter. It is not a SYS overlay and not a command: it is a transient installer that the FILTER library command loads at 5200H and enters at 5200H in response to a command such as FILTER *PR USING PR/FLT (CHARS=80,INDENT=6). The installer reads its formatting parameters, relocates a 293-byte resident module into high memory below HIGH$ (4049H), inserts that module in front of the printer device's existing driver, and exits through @EXIT (402DH). From then on every character sent to *PR passes through the filter, which applies a left margin, a printable line width with automatic wrap and indent, tab expansion, single-character translation, carriage-return and line-feed conventions, and page and form-feed accounting.

The resident module is registered in high memory under the name $FF, which is how the FORMS library command (SYS7/SYS overlay 12) finds it again with RST 28H request code 0BCH in order to display or change the parameters after installation. PR/FLT keeps the page-geometry counters in the three working-storage bytes of the printer's own Device Control Block and the character-formatting parameters in a seven-byte block inside its resident image, and those two areas together are exactly the ten bytes FORMS reads and rewrites.

The file also carries a complete Model I printer driver of its own. When the printer DCB is still pointing at the DOS's own saved printer driver (PRSV$, 43BCH), PR/FLT substitutes its own driver, which is what makes the PORT= parameter possible: two instructions in that driver are patched from the memory-mapped printer latch at 37E8H to IN A,(port) and OUT (port),A. That driver also treats an all-ones status read as "ready", so a machine with no printer attached does not lock up.

The image is a single LDOS load module. Only a type-1FH copyright record ("Copyright 1991 MISOSYS, Inc., All rights reserved") precedes the load records. The transfer address is 5200H. The image occupies 5200H-550CH and 5517H-5629H, 1056 bytes, with one deliberate 10-byte unloaded gap at 550DH-5516H which is the module's control block: an eight-byte copy of the printer DCB plus a two-byte pointer back to the real one.

Load Map

Address Range	Contents
5200H-5374H 373 bytes	Transient installer. Sign-on, device validation, @PARAM parsing, PORT patching, high-memory allocation, relocation, module copy, DCB hook-up, exit and error paths. Overwritten as soon as the next program loads.
5375H-542FH 187 bytes	Sign-on banner and the four abort messages. Transient.
5430H-54D8H 169 bytes	@PARAM keyword table, 21 entries of 6-character keyword plus a 2-byte cell address, ended by a 00H byte. Transient.
54D9H-54E2H 10 bytes	The five @PARAM value cells that are not code operands: LINES, PAGE, CHARS, INDENT, MARGIN. Transient.
54E3H-5504H 34 bytes	Relocation table, 17 DEFWs, each the address of a 16-bit operand inside the resident module. Transient.
5505H-550CH 8 bytes	Resident module header: 18H signature which is also the JR of the entry vector, displacement, link word, name length 03H, name "$FF". Copied to high memory.
550DH-5516H 10 bytes	NOT LOADED. The module control block: an 8-byte copy of the printer DCB the filter forwards to, plus a 2-byte pointer to the real printer DCB. Built at install time. Copied to high memory.
5517H-551DH 7 bytes	Resident parameter block: column counter, XLATE pair, INDENT, flag byte, CHARS, MARGIN. Copied to high memory.
551EH-5629H 268 bytes	The resident filter itself: driver entry, pass-through paths, built-in printer driver, character filter, margin/wrap/indent, CR-LF handling, page accounting, tab expansion. Copied to high memory.
5505H-5629H 293 bytes	The block that is actually relocated (0125H bytes). Its destination is HIGH$ - 0124H, recorded in the resident cell 4DF6H so that a later re-installation re-uses the same allocation.

Parameters (all read by @PARAM at 4476H from the table at 5430H)

Keyword	Cell	Meaning and Effect
LINES, L	54D9H	Printed lines per page. Stored plus one in DCB+05. Defaults to FFFFH, which the installer turns into "same as PAGE".
PAGE, P	54DBH	Physical page length in lines. Pre-set to 0042H (66). Stored plus one in DCB+03.
CHARS, C	54DDH	Printable characters per line. Stored in the parameter block at 551CH. Zero disables wrapping.
INDENT, I	54DFH	Spaces inserted at the start of a wrapped continuation line. Stored at 551AH.
MARGIN, M	54E1H	Left margin in spaces, emitted at column zero only. Stored at 551DH.
ADDLF, A	527AH	Switch. Send a line feed after every carriage return. Becomes bit 0 of the flag byte at 551BH.
FFHARD, F	5274H	Switch. Advance the page with a single 0CH form feed instead of a run of line feeds. Becomes bit 1 of the flag byte at 551BH.
TAB, T	526EH	Switch. Expand 09H to the next 8-column tab stop. Becomes bit 2 of the flag byte at 551BH.
SLINE, SL	5330H	0 or 1. One selects the Model III convention (67 lines, first line numbered 1); zero or omitted selects the Model I convention (66 lines, first line numbered 0). Becomes bit 3 of the flag byte at 551BH and also patches the line-counter reset constant at 560CH.
XLATE, X	5283H	X'aabb'. Character aa is replaced by character bb on the way out. High byte to 5518H, low byte to 5519H.
PORT	522DH	Model I only. 1 to 255. Patches the built-in printer driver from the memory-mapped latch at 37E8H to IN A,(port) at 5553H and OUT (port),A at 554FH.

Variable and Buffer List

Address Range	Purpose
4049H-404AH 2 bytes	HIGH$. Top of user memory. The installer lowers it by 0125H to carve out the resident module, but only the first time the filter is installed.
441FH 1 byte	DFLAG$. Bit 3 is the "printer forms filter is installed" flag: the installer aborts with "PR/FLT already active!" if it is already set, and sets it once the parameters have parsed. Bit 0, the spooler-installed flag, gates the linkage block at 533FH.
43BCH-43BDH 2 bytes	PRSV$. The DOS's saved printer driver address. If the printer DCB still points here, PR/FLT substitutes its own driver at module base + 3AH.
4DF0H-4DF1H 2 bytes	Resident cell holding the address of the installed print spooler module's CONTROL BLOCK, which is its module base plus 0AH. Read only when DFLAG$ bit 0 says the spooler is present. Note that this is not laid out like 4DF6H, which holds a module base rather than a control block address. Zeroed by SYS0/SYS at boot.
4DF6H-4DF7H 2 bytes	Resident cell holding the base address of the installed $FF forms-filter module. Zero means "never allocated", in which case the installer takes the space from HIGH$; non-zero means re-use the same block, which is why re-installing the filter does not consume more memory. Zeroed by SYS0/SYS at boot.
522DH-522EH 2 bytes	Operand of the LD HL at 522CH. The PORT= value.
526EH-526FH 2 bytes	Operand of the LD BC at 526DH. The TAB switch, 0000H or 0FFFFH.
5274H-5275H 2 bytes	Operand of the LD BC at 5273H. The FFHARD switch.
527AH-527BH 2 bytes	Operand of the LD BC at 5279H. The ADDLF switch.
5283H-5284H 2 bytes	Operand of the LD BC at 5282H. The XLATE character pair.
5330H-5331H 2 bytes	Operand of the LD HL at 532FH. The SLINE value, also read as a single byte at 525FH.
54D9H-54E2H 10 bytes	@PARAM value cells for LINES (54D9H, pre-set FFFFH), PAGE (54DBH, pre-set 0042H), CHARS (54DDH), INDENT (54DFH) and MARGIN (54E1H).
5507H-5508H 2 bytes	The resident module header's link word. The installer writes the previous top-of-chain address here before the module is copied.
550DH-5514H 8 bytes	The module's private copy of the printer DCB, taken from the real one at install time. Every pass-through call the filter makes uses this DCB, so the filter reaches the driver that was in place before it.
5515H-5516H 2 bytes	Pointer to the real printer DCB. This is the word FORMS follows to reach the page counters.
5517H 1 byte	Column counter. Number of printable characters emitted on the current line; margin spaces are not counted.
5518H 1 byte	XLATE source character, the high byte of X'aabb'.
5519H 1 byte	XLATE replacement character, the low byte of X'aabb'.
551AH 1 byte	INDENT. Spaces emitted at the start of a wrapped continuation line.
551BH 1 byte	Flag byte. Bit 0 ADDLF, bit 1 FFHARD, bit 2 TAB, bit 3 SLINE.
551CH 1 byte	CHARS. Printable characters per line, zero meaning no wrap.
551DH 1 byte	MARGIN. Spaces emitted whenever the column counter is zero.
5551H, 5555H 1 byte each	The third byte of the two printer-access instructions. Left as part of LD (37E8H),A and LD A,(37E8H), or overwritten with 00H (NOP) when PORT= shortens them to two-byte port instructions.
560CH 1 byte	Operand of the LD (IX+04H),nn at 5609H. The value the line counter is reset to at top of page: 01H under the Model III convention, 00H under the Model I convention.
DCB+03H 1 byte	Physical page length plus one. Written by the installer from PAGE, decremented again when SLINE is zero or absent.
DCB+04H 1 byte	Current line number within the page. Incremented on every new line, reset at top of form.
DCB+05H 1 byte	Printed lines per page plus one. Written from LINES, or from DCB+03H when LINES was not given.

Major Routines

Address	Name and Purpose
5200H	Installer Entry Entered by the FILTER command with Register Pair DE pointing at the device's DCB and Register Pair HL pointing at the parameter text. Displays the banner, rejects an inactive, routed, non-output or already-filtered device, then parses the parameters.
522CH	PORT Parameter Validates a PORT= value of 1 to 255 and rewrites the two printer-access instructions in the built-in driver as IN A,(port) and OUT (port),A.
524DH	Parameter Transfer Moves CHARS, MARGIN and INDENT into the resident parameter block and packs SLINE, TAB, FFHARD and ADDLF into the flag byte at 551BH, and XLATE into 5518H/5519H.
528DH	High-Memory Allocation Re-uses the block recorded at 4DF6H if there is one, otherwise lowers HIGH$ (4049H) by 0125H. Carries the previous chain head into the module's link word.
52ADH	Relocation Pass Adds destination minus 5505H to each of the 17 operands named by the table at 54E3H.
52D9H	Module Copy and DCB Hook-Up LDIRs 0125H bytes to high memory, substitutes the built-in printer driver when the DCB still holds PRSV$, copies the DCB into the module, stores the real DCB address in the module, and points the DCB at the module header.
5317H	Page Counter Seeding Writes PAGE+1, the initial line number and LINES+1 into DCB+03H, DCB+04H and DCB+05H, then applies the SLINE convention.
533FH	Spooler Linkage and Exit When DFLAG$ bit 0 says the spooler is resident, follows the word at spooler control block + 8 to the despooler's output DCB pointer and replaces it with the filter's own private DCB, then exits through @EXIT (402DH).
5357H	Parameter Error Issues error 2CH with the message-only and return-to-caller bits set through @ERROR (4409H), then aborts.
5360H	Message Selection Four entry points into one @LOGOT (447BH) call and one abort, separated by DDH prefix bytes.
551EH	Resident Filter Entry The address the DCB now points at, reached through the header's JR. Carry selects input, Zero selects output, neither selects control.
5535H	Send Onward Puts Register C into Register A and calls the ROM @PUT (001BH) with the module's private DCB.
553FH	Built-In Printer Driver Waits for printer ready and writes the byte to the Model I printer latch at 37E8H, or to the port named by PORT=. Treats a status of 0F0H as ready so a missing printer cannot hang the machine.
555EH	Output Entry Points Register Pair IY at the parameter block, runs the filter, and returns with the Zero flag set and Carry clear.
556DH	Character Filter Applies XLATE, then routes carriage return, line feed, form feed, the 06H top-of-page request, an expandable tab and any control character below 20H.
5596H	Print a Character Emits the left margin at column zero, sends the character, counts the column and wraps with an indent when CHARS is exceeded.
55C0H	Carriage Return and Line Feed Sends CR then LF when ADDLF is set; otherwise sends CR on a line that has content and LF on an empty one, then zeroes the column counter.
55DFH	New Line and Page Accounting Advances the line counter, and at the end of the printed area skips to top of form with a hard form feed or a run of line feeds.
560EH	Tab Expansion Turns 09H into 8 minus (column modulo 8) spaces.
5619H	Left Margin Emits MARGIN spaces, but only when the column counter is zero, and does not count them.

Cross-Reference Notes

PR/FLT is loaded and entered by the FILTER library command in SYS6/SYS. It issues no RST 28H request of its own; every service it uses is either a ROM low-core vector or a resident SYS0/SYS supervisor-call vector: @DSPLY (4467H), @PARAM (4476H), @LOGOT (447BH), @ERROR (4409H), @EXIT (402DH), @ABORT (4030H), and at run time the ROM entries $GET (0013H), $PUT (001BH) and $CTL (0023H). The resident SYS0/SYS page therefore covers every external address on this page except the three ROM entries.

The resident module is found again by the FORMS library command, SYS7/SYS overlay 12, which asks SYS10/SYS for the module control block of "$FF" with RST 28H request code 0BCH. FORMS then follows the word at control block + 8, which is 5515H in this listing, to reach the printer DCB, and treats DCB+03H through DCB+05H plus the seven bytes at 5517H-551DH as one ten-byte structure. That is why the page counters are held in the DCB and not in the module: they have to be reachable from a command overlay that only knows the module's name.

The print spooler in SYS6/SYS overlay 6 and this filter know about each other in both directions. If the filter is installed first, SPOOL tests DFLAG$ bit 3, walks the $FF module header from 4DF6H to reach its control block, follows the word at control block + 8 to find the real printer DCB, and when that is the device it is about to spool it hooks itself into the filter's private DCB rather than the device DCB, so that the filter feeds the spooler. If the spooler is installed first, the block at 533FH here does the mirror-image job. SPOOL also requires the KI/DVR keyboard driver, DFLAG$ bit 4, because disk-backed despooling is paged in from the keyboard task.

RESET *PR restores the printer DCB to its saved driver, which removes the filter from the I/O path and clears DFLAG$ bit 3, but leaves the high-memory allocation in place for the next installation.

5200H - Installer Entry, Sign-On and Device Validation

The transient installer is entered here by the FILTER library command. Register Pair DE holds the address of the Device Control Block of the device being filtered, Register Pair HL holds the address of the parameter text that followed the filespec, and nothing else is defined. The block saves both pointers, displays the banner, and rejects the four conditions under which the filter cannot be installed.

522CH - The PORT Parameter and the DFLAG$ Marker

PORT= is a Model I only parameter that moves printer output from the memory-mapped latch at 37E8H to a genuine Z80 I/O port. It is implemented by rewriting the two instructions in the built-in printer driver that touch 37E8H. Because the driver is three bytes wide at each point and a port instruction is two, the third byte is turned into a NOP.

524DH - Moving the Format Parameters into the Resident Parameter Block

Five of the parameters live in ordinary two-byte @PARAM cells at 54D9H-54E2H and are copied, one byte each, into the seven-byte parameter block at 5517H-551DH that travels with the resident module. The four switches and SLINE are packed into a single flag byte instead, and XLATE is split into its two halves.

528DH - Claiming the High-Memory Block

The resident module is 0125H bytes long, 5505H through 5629H. The first time the filter is installed the space is taken from HIGH$ and the base address is recorded in the resident cell 4DF6H. On any later installation that cell is still set, the same block is re-used, and HIGH$ is left alone. Either way the module's link word is loaded with the address that used to head the high-memory module chain.

52ADH - Relocating the Module's Internal Addresses

The module is assembled to run at 5505H but will execute wherever it has been placed in high memory. Seventeen instructions inside it carry absolute 16-bit operands that point back into the module; every one of them is named by a DEFW in the table at 54E3H, and each is adjusted by the difference between the destination and 5505H. Relative jumps need no adjustment and do not appear in the table.

52D9H - Copying the Module and Hooking the Printer DCB

With every internal address adjusted, the 293-byte module is moved into its high-memory home. The printer DCB is then rebuilt in three steps: if it still points at the DOS's own saved printer driver, the module's own driver is substituted; the resulting eight-byte DCB is copied into the module so that the filter has a private path to whatever was there before it; and finally the real DCB is pointed at the module header, which puts the filter in front of everything.

5317H - Seeding the Page Counters in the Printer DCB

The three page-geometry values do not live in the module. They are kept in the working-storage bytes of the printer Device Control Block, DCB+03H, DCB+04H and DCB+05H, which are reachable from a command overlay that only knows the module's name. Both PAGE and LINES are stored with one added; the SLINE convention then decides whether that bias survives.

533FH - Spooler Linkage and Exit

One last hook. The print spooler, when it is resident, keeps its own copy of the address of the DCB its despooler sends characters to, because the despooler runs as an interrupt task and calls the printer driver directly rather than going through the device chain. If the filter has just been inserted in front of that device, the despooler has to be pointed at the filter's private DCB instead of the real one, so that both present the same control block to the printer driver. The block is skipped entirely when the spooler is not installed, and the installer then returns to the DOS through @EXIT.

5357H - Parameter Error Path

Reached from the three places where a parameter cannot be accepted: an unrecognised keyword at 5229H, a PORT= value above 255 at 5235H, and an SLINE= value other than 0 or 1 at 5266H.

5360H - Message Selection and Abort

Four abort messages share one @LOGOT call and one abort. Each entry point loads Register Pair HL with its own message address, and a single DDH byte sits between them: entered at 5360H, 5364H or 5368H the following 21 nn nn reads as LD IX rather than LD HL, so Register Pair HL survives untouched all the way to the call. Entering at 5364H, 5368H or 536CH skips the DDH and the same three bytes load Register Pair HL directly.

5375H - Sign-On Banner

The banner @DSPLY writes at 5207H, before any validation is done, so it appears even when the installation is about to be refused. It is data, not code, and it is transient: it lives at 5375H in the load image and is never copied to high memory.

53DEH - Abort Message Text

The four refusal messages, each ended by 0DH for the @LOGOT call at 536FH. Every one of them is followed immediately by an abort through @ABORT at 4030H, so the filter is never partly installed.

5430H - @PARAM Keyword Table

The table Register Pair DE points at when @PARAM is called at 5226H. Every entry is eight bytes: a six-character keyword padded with blanks, then the address of the two-byte cell that is to receive the value. Every keyword appears twice, spelled out and abbreviated, and both forms name the same cell. A 00H byte at 54D8H ends the table. Six of the cells are ordinary storage at 54D9H-54E2H; the other five are 16-bit operands inside the installer itself, which is how a parameter turns directly into an instruction operand.

54D9H - @PARAM Value Cells

The five parameters whose values are not instruction operands are held here. @PARAM writes the whole 16 bits, but the installer only ever reads the low byte of each, so a value above 255 is silently truncated. The assembled contents shown are the pre-set defaults.

54E3H - Relocation Table

Seventeen DEFWs, each holding the address of a 16-bit operand inside the module that points back into the module and therefore has to be adjusted when the module moves. The loop at 52C3H reads each entry, fetches the operand it names, adds the relocation displacement and writes it back. Relative jumps and the DDH and FDH indexed instructions carry no absolute addresses and are absent from the table.

5505H - Resident Module Header

The eight-byte header every LDOS high-memory module carries. Its first byte doubles as the opcode of the entry vector, so the address the device DCB is pointed at is the header itself. The resident module-lookup service reached by RST 28H request code 0BCH walks the chain of these headers down from HIGH$, matches the name, and hands back the address of the bytes that follow it.

550DH - The Module Control Block (Not Loaded)

Ten bytes the load records deliberately skip. They are declared storage, not initialised data, and the installer fills them in at 52FAH-530EH just before the DCB is hooked. Everything from 5505H to 5629H is copied to high memory as one block, so these ten bytes travel with the module. In the LDOS module convention the bytes following the name are the control block, which makes this area exactly what the lookup service hands back to a caller.

5517H - The Resident Parameter Block

Seven bytes of formatting state that travel with the module and are addressed through Register Pair IY, which the output entry at 5560H points here. Six of them are written by the installer at 524DH-528CH; the first is a running counter maintained by the filter itself. Together with the three working bytes of the printer DCB these seven bytes are the ten-byte structure the FORMS command reads and rewrites.

551EH - Resident Filter Entry

Everything from here to 5629H runs in high memory, not at the addresses shown; the listing keeps the assembled 5505H origin, and the relocation table at 54E3H names every operand that has to be corrected for the difference. The entry is reached through the JR that the module header's 18H signature byte forms, which is where the printer DCB now points. The Model I ROM reaches a device driver through the central I/O dispatcher at 03C2H, which sets Register Pair IX to the Device Control Block, puts the data or control byte in Register C, and selects the operation with the flags: CARRY set for an input request from $GET at 0013H, ZERO set for an output request from $PUT at 001BH, and neither for a control request from $CTL at 0023H. Register Pair IX therefore addresses the printer DCB throughout, which is how the page counters in DCB+03H to DCB+05H are reached.

5535H - Send a Character Onward

The single exit every formatting decision funnels through. It takes the byte in Register C, which is where the filter keeps the character it is working on, and passes it to whatever driver the module's private DCB names. Ten of the seventeen relocation entries exist because of the calls to this routine and to the DCB address it uses.

553FH - The Built-In Model I Printer Driver

A complete printer driver, installed into the printer DCB at 52F4H whenever that DCB was still pointing at PRSV$, the DOS's own saved driver. It is reached exactly as any driver is, with Register Pair IX addressing the DCB, Register C holding the byte, and the flags selecting the operation. Its two accesses to the Model I printer latch at 37E8H are the instructions the PORT= parameter rewrites into port instructions at 523CH and 5244H, which is why PORT= exists at all: without this driver in the DCB there would be nothing to patch.

555EH - Output Entry

Reached from 5520H when a byte is being printed. It establishes Register Pair IY over the seven-byte parameter block, runs the filter, and returns the "device ready, no error" condition the caller expects from a driver.

556DH - The Character Filter

The routing decision for one outgoing character. Translation is applied first, so a translated character is then treated as whatever it became. Carriage return and line feed both mean "new line". Form feed skips to top of form without counting a line. 06H is the top-of-page reset that the DOS manual documents as LPRINT CHR$(6). A tab is expanded only when the TAB switch is on. Anything else below 20H is passed through untouched, so printer control sequences survive the filter intact.

5596H - Print a Character, with Margin and Line Wrap

The printable-character path, and also the routine the indent and tab loops call so that the spaces they emit obey the same rules. It emits the left margin when the line is empty, sends the character, counts it, and forces a new line with an indent when the CHARS limit has been reached.

55C0H - Carriage Return and Line Feed

What actually goes down the wire when a line ends. With ADDLF the filter always sends carriage return then line feed. Without it, a line that has content ends with a carriage return, and a line that is already empty is given a line feed instead, which is what makes LPRINT with no arguments produce a blank line on a printer that would otherwise ignore a bare carriage return.

55DFH - New Line, Line Count and Page Advance

The page accounting. The three counters it works on live in the printer Device Control Block, reached through Register Pair IX, which the ROM device dispatcher set before the filter was entered: DCB+03H is the physical page length, DCB+04H the current line number and DCB+05H the number of printed lines allowed. Both DCB+03H and DCB+05H carry the plus-one bias the installer applied at 531AH and 5325H unless SLINE selected the Model I convention, which removed it again at 5336H.

560EH - Tab Expansion

Reached from 5590H when a 09H arrives and the TAB switch is on. Tab stops are fixed at every eighth column, and the count is worked out from the column counter rather than from any stored tab table.

5619H - The Left Margin

Called from 5596H before every printable character, with the MARGIN width already in Register A, but only actually emitting anything when the column counter is zero. The spaces are sent through 5535H rather than through 5596H, so they are not counted in the column and do not consume any of the CHARS line width.