TRS-80 DOS - NEWDOS/80 v2.0 for the Model III - SYS3/SYS Disassembled

SYS3/SYS

Other Navigation

NEWDOS/80 v2.0 SYS3/SYS Disassembly - CLOSE, KILL, Timer Chain and Library Commands (Model III)

SYS3/SYS is a one-granule overlay that loads into the overlay area at 4D00H-51DFH (1,248 bytes in five load records, transfer address 4D00H). The manual describes it as the overlay that closes FCBs, kills files, and inserts and deletes entries in the 25 ms timer chain, and as the executor of the library commands BLINK, BREAK, CLOCK, DEBUG, JKL, LC, VERIFY and most of PURGE. It is called with LD A,code / RST 28H; the SYS0/SYS dispatcher at 4B67H loads it when 4288H does not already hold its directory slot, 05H, and calls 4D00H with the caller's registers.

The page shows every byte of the file once, in address order. 518FH-51DFH are 81 bytes of 00H.

RST 28H Codes Handled by SYS3/SYS

How CLOSE and KILL Release Space

Bytes Changed by SYS6/SYS

4D00H - Function Dispatcher

SYS3/SYS is entered here by the SYS0/SYS RST 28H dispatcher (4B67H) with Register A = the RST 28H code and the caller's Register Pairs BC, DE and HL unchanged. Bits 5-7 of the code are the function number (bits 0-4 = 05H, SYS3/SYS's directory slot): 25H CLOSE (4428H), 45H KILL (442CH), 65H enqueue a timer routine (447BH), 85H dequeue a timer routine (4413H), A5H the J-K-L screen print (SYS0/SYS 459DH), C5H write EOF (4451H). Function 7 (E5H) takes a sub-function in Register C: 1 BLINK, 2 CLOCK, 3 DEBUG, 4 VERIFY, 5 BREAK, 6 PURGE (chained from SYS7/SYS), 7 EOF to the FPDE (chained from 4FEAH), 8 not used (error 2AH), 9 LC. Any other code or sub-function returns error 2AH; SYS6/SYS (568DH) relies on this to load SYS3/SYS with Register C = FFH and then use its code. The first 224 bytes (4D00H-4DDFH) are also used as work space by CLOSE and KILL once this code has run (4E7BH).

4D43H - Return Error 2AH

Reached from the dispatcher for an unknown function code or function 7 sub-function.

4D47H - Function 65H: Enqueue a Timer Routine (447BH)

Manual section 3.8. Register Pair DE points to the caller's timer routine block: bytes 0-1 the forward link (filled in here), byte 2 the interval in 25 ms ticks, byte 3 the countdown, the routine itself from byte 4. The block is put at the head of the chain whose head pointer is the operand of the SYS0/SYS LD HL,nnnn at 4583H (the operand is at 4584H-4585H), which the clock routine of SYS0/SYS walks at every 25 ms tick.

4D55H - Function 85H: Dequeue a Timer Routine (4413H)

Manual section 3.9. Register Pair DE points to the block to take out of the timer chain. The links are followed from the chain head at 4584H; when a link points to the block, that link is replaced by the block's own link. A block that is not in the chain is ignored.

4D70H - Function E5H Sub-function 2: CLOCK

CLOCK[,Y|N] (manual 2.12). The ROM shows the time on the display while bit 0 of its I/O control byte at 4210H is set: CLOCK or CLOCK,Y sets it through ROM 0298H, CLOCK,N clears it through ROM 02A1H.

4D7BH - Function E5H Sub-function 9: LC

LC[,Y|N] (manual 2.28). Sets the keyboard a-z toggle, bit 0 of 4019H, the shift lock flag of the ROM keyboard routine: LC or LC,Y clears it (a-z are accepted as they are), LC,N sets it (a-z are changed to A-Z).

4D88H - Function E5H Sub-function 1: BLINK

BLINK[,Y|N] (manual 2.6). Sets bit 0 of 401CH, the cursor blink switch of the ROM (00H = the cursor blinks): BLINK or BLINK,Y clears it, BLINK,N sets it.

4D95H - Function E5H Sub-function 3: DEBUG

DEBUG[,Y|N] (manual 2.18). Bit 7 of 4289H is the DEBUG enable flag: SYS2/SYS (4D88H) tests it after loading a program with load-and-run and enters DEBUG (440DH) instead of starting the program.

4DA2H - Function E5H Sub-function 4: VERIFY

VERIFY[,Y|N] (manual 2.48). 4A2DH-4A2FH in the SYS0/SYS sector write routine loads the value whose bits 7 and 4 decide whether the write is read back: LD A,(IX+01H) (FCB+1, verify only for record and byte I/O) or NOP / LD A,0FFH (every write through 4439H is verified).

4DB8H - Function E5H Sub-function 5: BREAK

BREAK[,Y|N] (manual 2.8). 4478H-447AH is the SYS0/SYS BREAK hook: the ROM keyboard driver does an RST 28H with Register A = 01H when BREAK is pressed, and the dispatcher sends codes below 20H to 4478H. JP 4546H throws the key away, RET passes it on as a key with code 01H. DOS READY sets it again from option AG.

4DCCH - Read a Y/N Parameter

4DCCH reads the parameter and then requires the end of the command line; 4DD1H only reads it. On entry Register Pair HL points to the parameter (SYS1/SYS has already stepped past the comma or spaces after the command word). Result: the Z FLAG and Register A = 00H for N; the NZ FLAG for Y (Register A = 0BH) or when the line ends there (Register A = BFH). Anything else, or anything after the parameter when 4DCCH is used, goes to the SYS0/SYS error exit 4409H with error 34H.

4DE6H - Function 45H: KILL the File of an FCB (442CH)

Manual section 3.16. Register Pair DE points to an open FCB. The directory entries and granules of the file are released through the same code as CLOSE, with the mode byte at 4FB8H = 01H and a granule target of 0, so every granule is freed; finally the FCB is set to all zeroes (4FB5H).

4DF4H - KILL Entry Used by PURGE

PURGE (5113H) comes here with Register Pair DE = 4480H (the DOS FCB, marked open, with the DEC at 4487H) and Register Pair HL = the FPDE in the directory buffer at 4300H. It skips the FPDE check and the access check of 4DE6H.

4E02H - Function 25H: CLOSE the FCB (4428H)

Manual section 3.15. Register Pair DE points to an open FCB. The buffer is written if it holds changed data, the EOF of the FCB is written into the FPDE, granules beyond the EOF are released unless the no deallocate bit of the file is set, and the FCB is turned back into a filespec (NAME/EXT:d).

4E1AH - Granules Needed for the EOF

Also entered from SYS6/SYS (60BCH) with Register Pair HL = an FPDE in 4300H pushed onto the stack, Register A = its EOF low byte and Register Pair DE = its EOF middle and high bytes, to release the granules of a copied file beyond its EOF. Register Pair DE is the number of sectors the EOF reaches into (the FPDE form: the middle and high bytes are one higher when the low byte is not 0).

4E2FH - Count the Granules of the File

Register Pair HL points to a directory entry in the buffer at 4300H, Register D holds its DEC and Register E the value bits 7 and 4 of its first byte must have. The extent elements at bytes 22-31 are added into Register Pair BC. An element with lump FEH links to an FXDE (the DEC in its second byte) and must be the fifth one; FFH ends the list. The offset of the last entry examined is kept at 4EA1H.

4E52H - Error Exit and Directory Helpers

4E52H: five elements without an end mark, or the wrong kind of entry, is error 2CH. 4E59H: read the directory entry whose DEC is in Register D. 4E5FH: write the directory sector in 4300H. Both helpers return only on success (the Z FLAG); an error leaves the DOS function through 4972H.

4E64H - End of the Extents of an Entry

Register A holds FEH or FFH from 4E3FH and Register Pair HL points to the second byte of the element.

4E72H - Prepare the Work Maps

All the entries of the file have been counted: Register Pair BC = the granules the file owns, the stack holds the granules it keeps (what the EOF needs for CLOSE, 0 for KILL) and Register Pair HL points to the second byte of the element with the FFH end mark. From here SYS3/SYS uses its own first 224 bytes as work space: 4D00H-4DBFH becomes a mask for the allocation bytes of the GAT (FFH = keep, a 0 bit = a granule to free) and 4DC0H-4DDFH a 256-bit map of DECs to clear in the HIT. Since that overwrites the code of SYS3/SYS, the overlay number at 4288H is cleared so that the next RST 28H for SYS3/SYS reloads it.

4E9EH - Free Granules from the End of the File

Register Pair BC counts up from minus the number of granules to free. Working backwards from the last extent element, each granule is marked in the GAT mask at 4D00H (lump offset, granule bit). CLOSE shortens the element, and an element or an FXDE that becomes empty is replaced by an end mark (FFH FFH). KILL leaves the elements as they are, since the whole entry is released. An FXDE that has been emptied (CLOSE) or passed (KILL) is freed through 4FC2H and the walk goes on in the entry its back link names. The offset of the entry being worked on is at 4EA1H; its DEC is in Register D.

4EFFH - Write the Last Entry and Finish

Reached when the excess granules are freed (4EC8H) or when the walk has come back to the FPDE (4EABH). Register Pair HL points into the entry whose offset is at 4EA1H.

4F10H - Apply the GAT Mask

If any byte of the mask at 4D00H-4DBFH is not FFH, the GAT (directory sector 0) is read, each of its allocation bytes 00H-BFH is ANDed with the mask (a cleared bit frees that granule) and the GAT is written back.

4F33H - Apply the HIT Map

If any bit of the map at 4DC0H-4DDFH is set, the HIT (directory sector 1) is read and the byte of every marked DEC is set to 00H (entry free), then the HIT is written back. The map holds one bit per DEC, bit 7 of 4DC0H for DEC 00H.

4F5AH - Put the Filespec into the FCB

Manual sections 3.15 and 3.16. The FCB (Index Register IX) is rewritten as NAME/EXT:d with 03H at the end, from the entry whose DEC is in FCB+7 and the drive number at 427EH; for KILL (mode 01H at 4FB8H) its 32 bytes are then cleared. Skipped when bit 2 of 428BH is set (SYS6/SYS sets it while it uses this code during COPY). Reached as a subroutine from 4F0DH, or with JP from CLOSE (4E0CH, 4E13H), in which case its RET ends the DOS function.

4FC2H - Free a Directory Entry

Frees the entry at the offset stored at 4EA1H (in the buffer at 4300H), whose DEC is in Register D: bit 4 of its first byte is cleared (manual 5.7: the rest of the entry is left as it was), the sector is written, and the DEC is marked in the HIT map at 4DC0H. Returns Register D = the second byte of the entry, which for an FXDE is the DEC of the entry before it.

4FEAH - Write the Buffer, Then the EOF

Used by CLOSE (4E09H) and write EOF (5030H) inside their DOS function. Two words are pushed so that the SYS0/SYS buffer write at 4A07H returns into 497CH: an error there leaves through 4972H, otherwise 497CH pops E507H and does RST 28H with Register A = E5H and Register C = 07H, which runs sub-function 7 (4FF5H) of this same overlay. Its RET comes back to the caller of 4FEAH.

4FF5H - Function E5H Sub-function 7: Write the EOF of the FCB into the FPDE

Reached only through the chain set up by 4FEAH, so it runs inside the caller's DOS function (Index Register IX = the FCB). Files whose access level is 5 or more (READ, EXEC, LOCK) are not changed: RETurn with the CARRY FLAG clear. Otherwise the EOF of the FCB is stored in the FPDE (low byte at byte 3, middle and high at bytes 20 and 21 in the FPDE form, one higher when the low byte is not 0) and the directory sector is written only if the value changed. Returns the CARRY FLAG, Register Pair HL = the FPDE and Register Pair DE = the EOF middle and high bytes in the FPDE form.

502DH - Function C5H: Write the EOF to the Directory (4451H)

Manual section 3.28. Register Pair DE points to an open FCB. The buffer is written if it holds changed data, then the EOF is stored in the FPDE. Returns error 25H if the access level of the file does not allow the change.

503AH - Function E5H Sub-function 6: PURGE

PURGE,[password:]dn[,/ext][,USR] (manual 2.40). SYS7/SYS (4D70H-4D7CH) handles the start of the command and chains here with RST 28H: Register B = the drive number (from 427EH) and Register Pair HL = the command line after the drive. This part reads the options into Register C: bit 0 = /ext given (the extension at 5141H-5143H), bit 1 = USR (leave out system and invisible files).

5081H - PURGE: Ask About Every File

Every FDE sector of the directory is read in turn (Register C = the FDE sector number, counted from 0, which is also the DEC of its first entry) and each entry that is an FPDE in use is offered, except DEC 00H (BOOT/SYS) and DEC 01H (DIR/SYS). The operator answers Y (kill it), N (keep it) or Q (stop).

5136H - Display Characters Without Spaces

Register Pair HL points to the characters, Register B holds how many. Spaces are skipped; Register Pair HL is left after the last character.

5140H - PURGE Data

The option bits, the wanted extension and the prompt. SYS3/SYS is loaded from the diskette for every PURGE (SYS7/SYS runs first in the same overlay area), so the extension starts as three spaces each time.

515FH - Function A5H: J-K-L Screen Print

Manual sections 2.26 and 4.5. The SYS0/SYS key combination check (459DH) does RST 28H with code A5H when J, K and L are held down. The display memory 3C00H-3FFFH is sent to the printer through ROM 003BH, a carriage return before each 64-character line. Characters 00H-1FH and anything above the value of option AX (4290H) are sent as a period. BREAK stops the print.

518FH - Unused Bytes

The end of the file. Nothing in SYS3/SYS reaches these bytes.