TRS-80 DOS - NEWDOS/80 v2.0 for the Model I - ASPOOL/MAS Disassembled

ASPOOL/MAS

Other Navigation

NEWDOS/80 v2.0 ASPOOL/MAS Disassembly - The Automatic Spooler (Model I)

ASPOOL/MAS is the automatic print spooler supplied on the NEWDOS/80 diskette (manual section 6.7: H. S. Gentry's spooler, changed by Apparat to work with NEWDOS/80 and to relocate itself). While it is active, everything a program sends to the printer goes to one of five disk files, POOL1 to POOL5 on a drive chosen at setup, and the files are printed in the background whenever the program reads the keyboard or sends another character to the printer, and with the interrupt option also from the 25 ms timer interrupt.

The file loads at 5450H-5DD0H in ten load records (2,433 bytes), transfer address 5C4BH; the rest of its last sector is zero bytes after the transfer record. It is never run in place: ASPOOL/MAS,I asks the setup questions and writes a working module with DUMP (the master on the diskette is not changed), and filespec,A run on that module copies 5450H-58F9H to the top of memory, relocates it and hooks it into the printer and keyboard drivers. Once active it answers the DOS command *ASP, as a *name routine on SYS9's list.

The page shows every byte of the file once, in address order, written from S:\1\ASPOOL.MAS and its listing. The old version of this page had misaligned rows at 5479H-547BH, 5525H-552DH and 55A5H-55A8H (its seven TODO rows), named the commands and options wrongly (a W "write mode", P "print mode", an A "purge all" command), described a 256-byte circular buffer at 5440H-5540H, and described printer hardware that the Model I file does not use.

Commands

Memory Use

Pool Files and the Print Queue

Setup Answers

Relocation

5450H - The *name Block

ASPOOL/MAS loads at 5450H-5DD0H (ten load records, transfer address 5C4BH). 5450H-58F9H is the resident spooler: when it is activated, 5CB2H copies this part to the top of memory and 5D94H puts the copy's first 12 bytes on SYS9's list of *name routines (head at 4051H) through 4461H. The block is SYS9's format: a check word, a link to the next block, an 8-character name, then the code at +12. With ASP on the list, a DOS command line starting with *ASP makes SYS1 call SYS9, which finds the block by its name and jumps to its code at +12 (545CH) with Register Pair HL pointing past the name and its comma.

545CH - *ASP Command: Pick the Option

Block+12, the code SYS9 runs for a *ASP command (DOS command line, or CMD"*ASP..." from BASIC). Register Pair HL points to the command line just past the name and the comma or spaces after it, so it is at the option letter, or at the 0DH that ends the line when *ASP is typed alone. The return address on the stack is 4408H in SYS0, pushed by SYS1 above 402DH (DOS READY). *ASP alone shows the status; *ASP,P purges the spooler, *ASP,S stops it, *ASP,C clears the backlog or the file being printed, *ASP,W ends the file being spooled.

547DH - The Option Letter Must End the Line

Called from 5461H (the *ASP command) and from 5C4BH (the program run with filespec,I or filespec,A) with Register Pair HL at the option letter. The letter must be followed directly by the 0DH that ends the command line, otherwise BAD PARAMETER(S). When nothing was typed after the name, Register Pair HL is on that 0DH, and the test reads the byte after it in the command buffer.

5486H - *ASP Alone: Display the Status

Displays SPOOL STATUS, then either SPOOL STOPPING (after *ASP,S or a 04H byte) or the file being spooled, then the file being printed and every file waiting in the queue (BACK LOG). Each file is shown as POOLn:d, where n is its number 1-5 and d the spool drive chosen at setup. The queue is the five bytes at 5828H-582CH (one per pool file, FFH after them): 00H = free or being spooled, 01H = the file being printed or the next one to print, 02H-05H = its place in the queue.

54C5H - Display a Message and a Pool File Name

Called with Register A = a pool file number and Register Pair HL = a message ended by 03H. 54C5H shows nothing when Register A is 00H; 54C7H always shows the message followed by POOLn:d and a new line. The digit n goes into the name template at 581EH (POOL1:1 and 0DH), whose drive digit at 5824H was set at setup.

54D5H - *ASP,C: Clear the Backlog or the File Being Printed

Asks CLEAR BACKLOG OR PRINT (B/P)? and repeats the question until the answer starts with B or P. P stores 50H in the operand at 56C5H: when the next sector of the file being printed has been read, 56C4H sees it, and the file is emptied and closed without printing the rest. B frees every file that is waiting (queue byte 02H or more) and then falls into the W code at 5501H, so the file being spooled is ended and queued too. The freed files keep their data on the diskette; the next spool file with that number is written over them.

5501H - *ASP,W and *ASP,S

W ends the file being spooled and queues it for printing, as a 03H byte in the printer output does; S stops the spooler, as a 04H byte does. Both put the code in Register C as if it were a character sent to the printer and go through the printer driver entry 550BH, with 402DH (DOS READY) as the final return address. After the spooler has been stopped 550BH is a RET, so a later W or S goes straight to DOS READY.

550BH - Printer Driver: Spool One Character

5D9FH stores the relocated address of 550BH into 4026H-4027H, the driver address of the printer device control block at 4025H, so every character sent to the printer comes here with the character in Register C. 550BH first does the spooler's background work (567DH: print from the buffer, read the next sector, start the next file), then spools the character (5518H), and returns with Register Pairs BC, DE and HL as they were. The stop code (5634H) turns the PUSH HL at 550BH into a RET, after which printer output is ignored.

5518H - Spool a Character: Refuse Output From the DOS

Called from 5511H with Register C = the character. While an overlay function is running (4369H bit 6, set by the SYS0 RST 28H dispatcher), the character comes from the DOS itself (a DIR listing with P, J-K-L, PRINT) and the spooler must not do disk I/O in the middle of it: the character is dropped and CAN'T SPOOL FROM DOS is shown, but only for the first character of each run of such output. The operand at 5519H keeps the state of bit 6 for the previous character.

552DH - Spool a Character: Codes 04H, 0DH, 0CH and 03H

Register C is the character. 04H stops the spooler (5634H). Any other character first makes sure a spool file is open (55F7H when the operand at 5534H is 00H). 0DH is written and counted on the page; 0CH becomes a form feed (555BH); 03H ends the spool file (55B9H); anything else goes to 557EH. The line count is the byte at 582EH.

555BH - Form Feed

Called from 5555H (page full), from 5559H (a 0CH byte) and through the CALL NZ at 55BBH (top of form at the end of a file) with Register Pair HL = 582EH, the line count. Hard: a 0CH byte is written and the count set to 0. Soft: carriage returns are written until the count reaches the total lines per page, then the count is set to 0.

557EH - Write a Byte Into the Spool File

Register A is the byte. 582FH remembers whether the current line has a printable character: before a carriage return on an empty line a space is written first. The byte goes into the spool sector buffer 5300H-53FFH at the pointer kept in the operand at 5599H; when the buffer is full it is written to the spool file with verify (443CH) and the next sector is allocated (55F0H). Register Pair HL is kept; Register Pair DE is changed when a sector is written.

55B9H - End the Spool File (03H)

Reached from 557CH with Register Pair HL = 582EH, the line count. If the page has lines on it and top of form at the end of a file was chosen, a form feed is written first. A part-filled buffer is ended with a 03H byte (the print side stops at it, 5784H) and written; then the file is closed and queued.

55D0H - Close the Spool File and Queue It

Called from 55F4H (diskette full) and reached from 55C6H/55CDH. The file is closed, then counted into the print queue: its queue byte becomes one more than the number of files already queued, so it is printed after them. 5534H is set to 00H: no spool file is open. Register Pair DE is left at 5420H.

55F0H - Allocate the Next Sector of the Spool File

Called after every sector written (55B0H) and right after a spool file is opened (5621H), with Register Pair DE = 5420H. 444BH makes sure the sector at the FCB's NEXT exists, taking a granule when needed. If it cannot (the diskette is full), the file is closed and queued, and a new spool file is opened, so the output goes on in the next pool file.

55F7H - Open a New Spool File

Called from 5536H with Register C = the character to spool, and reached from 55F4H. The first free pool file (queue byte 00H) is taken; if all five are queued, SPOOL FULL. WAITING ON PRINTER is shown and the spooler does its background work (567DH) until printing frees one. The file POOLn:d is opened in the FCB 5420H with buffer 5300H, created if needed, and its first sector allocated.

5626H - Spool File Error: Report and Stop

Reached from 5623H (the open failed) and 55AEH (a sector write failed) with Register A = the DOS error code and Register Pair HL = CAN'T OPEN or CAN'T WRITE TO. The DOS error message is shown, then the message and SPOOL OUTPUT FILE, and the spooler is stopped (5634H).

5634H - Stop the Spooler

Reached for the 04H code (5530H: *ASP,S or LPRINT CHR$(4)) and after a spool file error. The printer driver entry 550BH becomes a RET, so any further printer output is ignored, and the flag at 56F1H is set: the files already queued are still printed, and when the queue is empty 56F3H runs the purge at 56F6H. The file being spooled, if any, stays open until that purge empties it.

5642H - Find a Free Pool File

Returns the Z FLAG with Register C = the number (1-5) of the first pool file whose queue byte is 00H (free), or the NZ FLAG (Register A = 01H) if all five are queued. Register Pair HL is left at the free entry or after the end mark.

5651H - Put POOLn:d Into an FCB

Called with Register A = a pool file number (1-5) and Register Pair DE = an FCB (5400H for printing and at activation, 5420H for spooling). The number is put into the name template at 581EH and the 8 bytes POOLn:d and 0DH are copied into the FCB as the filespec for the open. Register Pair DE is kept; Register Pair HL returns 5826H and Register Pair BC 0000H.

5661H - Keyboard Driver

5DA6H stores the relocated address of 5661H into 4016H-4017H, the driver address of the keyboard device control block at 4015H, so every keyboard read comes here. With the circular buffer (setup answer Y) the key is taken from the buffer at 5440H, which 57DDH fills; otherwise 5C8CH has put the previous keyboard driver's address into the CALL at 5661H. When no key is there, the spooler does its background work (567DH); when a key is there, the time of the key is kept for the print delay (5769H).

567DH - Background Work

Called from the keyboard driver (5668H) when no key is waiting, from the printer driver (550EH) before each character is spooled, and from the SPOOL FULL wait (5603H). It prints from the print buffer (575AH) with the timer routine held off, and then does the disk work, which the timer routine never does: read the next sector of the file being printed, finish a printed file, start the next queued file, or run the purge when the spooler has been stopped and the queue is empty. Nothing is done while an overlay function is running. Register Pairs BC, DE and HL are kept.

56A2H - Start Printing a Queued File

Reached from 56E8H with Register C = the number of the pool file whose queue byte is 01H. The file is opened in the FCB 5400H with buffer 5200H and its first sector read; 56B6H also reads every following sector. A failed open drops the file from the queue; a failed read (also the end of the file) or the end mark 03H finishes it.

56CAH - Finish the Printed File

Reached when the file has been printed (end of file, end mark), when it could not be read, or when *ASP,C was answered P. 5745H sets its EOF to 0 and closes it, so the DOS frees its space. Then the file is taken out of the queue: every queue byte from 01H up is lowered by one, so the next file gets 01H.

56E1H - Find the Next File to Print

Looks for the queue byte 01H. If a file has it, printing of that file starts (56A2H). If none has it and the spooler has been stopped (56F1H = C9H), the purge at 56F6H runs; otherwise nothing more is done.

56F6H - *ASP,P: Purge the Spooler

Reached from 5466H (*ASP,P, with SYS0's return address 4408H on top of the stack) and from 56F3H (stopped and the queue empty, with the three registers of 567DH on the stack). The file being spooled is emptied and closed, the timer routine is taken out of the chain, the printer and keyboard drivers that were there at activation are put back, HIMEM is given back if nothing has lowered it since, and the *name block is taken off SYS9's list. The manual says SPOOL PURGED is shown; the code never shows that message (588BH). Pool files still queued are not printed and keep their space.

5739H - Is the Print Buffer Used Up

Compares the print pointer, the operand at 573DH (the next byte of 5200H-52FFH to print), with 5300H. Returns the CARRY FLAG while bytes are left, the Z FLAG when the pointer is exactly 5300H (read the next sector), and the NZ and NO CARRY FLAGS when it is 5301H, the value 578AH stores when it meets the end mark 03H. Register Pair HL returns the pointer, Register Pair BC = 5300H.

5745H - Empty a Pool File and Close It

Called with Register Pair DE = an FCB (5400H or 5420H). The EOF in the FCB (bytes +8, +12 and +13) is set to 0 and the file is closed, so the DOS releases all its space. Register A returns 00H; the close's result is returned.

5755H - Timer Block

The block SYS0's timer chain walks every 25 ms tick (4610H) once 5DB6H has enqueued it through 4410H (interrupt option Y). Bytes 0-1 are the chain link, written by the enqueue; byte 2 the interval in ticks, byte 3 the countdown; when the countdown runs out SYS0 reloads it from byte 2 and calls byte 4. The routine at byte 4 prints from the print buffer only: disk I/O is never done from the interrupt. 567DH turns its first byte into a RET while it prints itself.

575AH - Print From the Buffer

Entered at 5759H from the timer chain and called from 567DH. SYS0 saves Register Pairs AF, BC, DE and HL around a timer routine, so only Index Register IX, which the keyboard check and the printer driver call change, is saved here.

5762H - Print Delay After a Key

First a key is taken into the circular buffer (57DDH). Nothing is printed when no file is being printed, or within the number of seconds chosen at setup after the last key (the time kept by 566DH). The seconds are compared modulo 60 and the minutes and hours as a word, with the borrow from the seconds.

5780H - Print Up to the End of a Line

Prints bytes from the print buffer until a carriage return has been sent, the buffer is used up, the printer is not ready, or the end mark 03H is met. Register Pair HL is the print pointer; the character is kept in Register C. Between characters the keyboard is read into the circular buffer.

57AAH - Parallel Printer at 37E8H

The status byte at 37E8H must show not busy (bit 7 clear), not out of paper (bit 6 clear), ready (bit 5 set) and bit 4 set; otherwise nothing is sent and the byte is tried again next time.

57B8H - Serial Printer Through the RS-232 Board

The UART's status (port EAH) must have bit 6, transmitter buffer empty, set. With the setup answer Y to H14 PRINTER, bit 6 of port E8H must also be set before the character is sent; with N the JR at 57BDH skips that test. The character goes to the UART's data port EBH.

57C7H - After Each Character

The print pointer moves on; after a carriage return the line ends here (with the line feed option a 0AH is put in its place first, so the line feed is printed next). Otherwise the keyboard is read and the next byte printed.

57DDH - Read the Keyboard Into the Circular Buffer

The buffer is the 10 bytes 5440H-5449H. The write pointer is the operand at 57E8H and the write count the operand at 57FDH; the count runs from F6H to FFH, and when it wraps to 00H the pointer goes back to 5440H and the count to F6H (5817H). Nothing stops the writer from passing the reader: 10 keys that are not read make the buffer look empty again.

57FAH - Take a Key From the Circular Buffer

The keyboard driver's first call (5661H). The read count (operand at 57FBH) is compared with the write count (operand at 57FDH): equal means empty, and Register A returns 00H with the Z FLAG. Otherwise the key at the read pointer (operand at 5802H) is returned and the pointer and count move on, wrapping like the writer. Register Pairs BC and HL are kept.

5817H - Wrap a Circular Buffer Pointer

Called by the writer (57F0H) and the reader (580AH) when their count has wrapped to 00H.

581DH - Resident Data

The last part of the resident area. 5CB2H copies it to the top of memory with the code, but the relocation scan stops at 581DH, so nothing here is changed by the relocation. It holds the name template POOLn:d, the B/P answer, the print queue, the page counters and the messages of the *ASP command and of the printer driver.

58FAH - filespec,I: Set Up a Working Module

Reached from 5C50H when the program is run as ASPOOL/MAS,I. Each answer is stored straight into the resident code as an opcode or an operand; then the DUMP command at 5C11H writes 5450H-5DD0H, with these changes, to the new file named by the user. The master file on the diskette is not changed. Every question is asked again until the answer has the right form: one character for the letter and drive questions, exactly two characters for the numbers.

59B0H - Write the Working Module With DUMP

The command at 5C11H is completed: the three hex addresses 5450H (start), 5DD0H (end) and 5C4BH (entry) and the filespec typed by the user. It is run through DOS-CALL (4419H), so SYS7's DUMP writes the changed program 5450H-5DD0H to the new file with its transfer address 5C4BH.

59FDH - Hex Digits

59FDH writes Register Pair DE as four hex digits at Register Pair HL, 5A02H Register A as two, 5A0BH the low four bits of Register A as one. Register Pair HL is moved past what is written.

5A18H - Ask a Question With Two Letter Answers

5A18H asks a Y/N question; 5A1BH any question whose answers are the letters in Register B and Register C. The question at Register Pair HL is shown and the answer read (5A2FH) until exactly one character is typed and it is one of the two letters. Returns the Z FLAG for the letter in Register B, the NZ FLAG for the one in Register C, and Register Pair DE = 5C44H, the answer.

5A2FH - Show a Question and Read One Character

Displays the question at Register Pair HL and reads up to one character into 5C44H with the ROM line input. Returns Register Pair HL = 5C44H and Register B = the number of characters typed (0 or 1); the 0DH follows at 5C45H.

5A3AH - Ask for a Two-Digit Number

Shows the question at Register Pair HL and reads up to two characters into 5C46H until exactly two are typed; their value is taken with the ROM's number conversion FIN (0E6CH). The ranges in the questions (10-99, 00-59) are not checked, and characters that are not digits are not refused. Returns Register A = the low byte of the value from 4121H; Register Pair DE = the question.

5A55H - Setup Questions

The questions of filespec,I, each ended by 03H so the answer is typed on the same line. 4467H displays them.

5C11H - The DUMP Command

Run through DOS-CALL at 59EBH. 59D6H types the filespec over the placeholder 5C16H-5C30H and 59DEH blanks what is left of it; 59B6H, 59BFH and 59C8H fill in the three hex fields. SYS7's DUMP takes spaces as separators, so the finished line is DUMP filespec 5450H 5DD0H 5C4BH.

5C44H - Answer Buffers

Used by the ROM line input during setup.

5C4BH - Program Entry: filespec,I or filespec,A

The transfer address of ASPOOL/MAS and of every working module. SYS2 runs the program with Register Pair HL past the filespec and its comma, at the option letter (or at the 0DH when none was typed). I sets up a working module (58FAH); A activates the spooler; anything else is BAD PARAMETER(S).

5C58H - filespec,A: Empty the Old Pool Files

The five files POOL1:d to POOL5:d on the spool drive are opened if they exist and emptied (EOF 0, close), so nothing spooled before is printed and their space is free.

5C6FH - Keep the Old Drivers and Apply the Options

The printer driver (4026H) and keyboard driver (4016H) found now are stored into the code that calls or restores them. Without the interrupt option the keyboard check calls the old keyboard driver instead of the ROM's; without the circular buffer the spooler's keyboard driver calls the old one and the keyboard check is a RET.

5C94H - Set Up the RS-232 Board for a Serial Printer

Only for the printer kind 00H. The UART is reset (port E8H), its control register is loaded from the board's switches (port E9H bits 3-7) with bit 2, transmit enable, set (port EAH), and its baud rate is set from switch bits 0-2 through the table at 5DBCH (port E9H).

5CB2H - Copy the Spooler to the Top of Memory

The area 5200H-58F9H (06FAH bytes: 250H bytes of buffers, then the code and data from 5450H) is placed just below HIMEM: the new HIMEM is HIMEM - 06FAH, the area starts 1 above it, and 5450H-58F9H is copied to the area start + 250H. The difference between the copy and the original (the area start - 5200H) is kept on the stack for the relocation.

5CE0H - Relocate the Copy

Walks the copied code instruction by instruction, working out each length from its opcode. Every instruction with a 16-bit address operand (LD rr,nn, LD (nn),HL and LD HL,(nn), LD (nn),A and LD A,(nn), JP, CALL, the conditional JP and CALL, ED-prefixed LD (nn),rr and LD rr,(nn)) has its operand moved by the offset when it lies in 5200H-58F9H. For a DD or FD prefix whose next byte is below 40H or from C0H up, the scan steps only over the prefix, so LD IX,nn and the like are relocated as LD HL,nn. Register Pair HL is the scan pointer, Register Pair BC the end, the offset is the word on top of the stack.

5D82H - Install the Copy

The scan must end exactly on the copy's 581DH, else error 3AH. SPOOL ACTIVE is shown, the copy's *name block is put on SYS9's list (error 35H, FILE ALREADY EXISTS, if a spooler is already active), HIMEM is lowered, the printer and keyboard drivers are pointed into the copy, and with the interrupt option the copy's timer block is enqueued.

5DBCH - Baud Rate Table and Message

The table is indexed by switch bits 0-2 of port E9H (5CA6H); each byte gives the same rate in both halves (high four bits sending, low four bits receiving).