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

SYS3/SYS

Other Navigation

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

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 (section 5.2) 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, LCDVR, LC, VERIFY and most of PURGE. It is called with LD A,code / RST 28H; the SYS0 dispatcher (4BC2H) loads it when 4317H does not already hold its number, 05H, and calls 4D00H with the caller's registers.

The page shows every byte of the file once, in address order. The file on the system diskette has the mandatory zaps applied (see Zaps).

RST 28H Codes Handled by SYS3

How CLOSE and KILL Release Space

Zaps

4D00H - Function Dispatcher

SYS3 is entered here by the SYS0 RST 28H dispatcher (4BC2H) 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's directory slot): 25H CLOSE (4428H), 45H KILL (442CH), 65H enqueue a timer routine (4410H), 85H dequeue a timer routine (4413H), A5H the J-K-L screen print (SYS0 45BFH), 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), 7 EOF to the FPDE (chained from 500DH), 8 LCDVR, 9 LC. Any other code or sub-function returns error 2AH; SYS6 (568DH) relies on this to load SYS3 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 (4E9EH).

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 (4410H)

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 LD HL,nnnn at 461CH (the operand is at 461DH-461EH), which the timer tick (4610H) walks every 25 ms.

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 461DH; 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 clock display routine is the timer block at 44A0H in SYS0 (its routine at 44A4H shows the time on the top line). It is always dequeued first, so it is never in the chain twice, and enqueued again for Y.

4D82H - Function E5H Sub-function 8: LCDVR

LCDVR[,x[,s]] (manual 2.29). The first parameter switches the lower case driver built into SYS0: 4593H is the first byte of the case handling in the keyboard driver (RET = off, LD C,A = on) and 4505H is the first byte of the display driver (JR = straight to the ROM routine at 0458H, JR C = characters 20H-7FH go to ROM 047DH without the upper case conversion). The second parameter sets the a-z toggle like LC; without it the toggle is set to convert to upper case. Option BF does the same at reset.

4DA2H - Function E5H Sub-function 9: LC

LC[,Y|N] (manual 2.28), and the second parameter of LCDVR (from 4D9AH). Sets the a-z toggle at 45B4H in the SYS0 keyboard driver.

4DABH - Function E5H Sub-function 1: BLINK

BLINK[,Y|N] (manual 2.6). 4502H is the first byte of the cursor timer routine in SYS0 (the 44EBH block): RET Z (C8H) lets the cursor blink, RET (C9H) stops the blinking. Option BH sets it at reset.

4DB8H - Function E5H Sub-function 3: DEBUG

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

4DC5H - Function E5H Sub-function 4: VERIFY

VERIFY[,Y|N] (manual 2.48). 4A88H-4A8AH in the SYS0 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).

4DDBH - Function E5H Sub-function 5: BREAK

BREAK[,Y|N] (manual 2.8). 4312H-4314H is the SYS0 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 4312H. JP 45B0H throws the key away, RET passes it on as a key with code 01H. DOS READY sets it again from option AG.

4DEFH - Read a Y/N Parameter

4DEFH reads the parameter and then requires the end of the command line; 4DF4H only reads it. On entry Register Pair HL points to the parameter (SYS1 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 4DEFH is used, goes to the SYS0 error exit 4409H with error 34H.

4E09H - 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 4FDBH = 01H and a granule target of 0, so every granule is freed; finally the FCB is set to all zeroes (4FD8H).

4E17H - KILL Entry Used by PURGE

PURGE (5136H) 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 4200H. It skips the FPDE check and the access check of 4E09H.

4E25H - 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).

4E3DH - Granules Needed for the EOF

Also entered from SYS6 (60BCH) with Register Pair HL = an FPDE in 4200H 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).

4E52H - Count the Granules of the File

Register Pair HL points to a directory entry in the buffer at 4200H, 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 4EC4H.

4E75H - Error Exit and Directory Helpers

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

4E87H - End of the Extents of an Entry

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

4E95H - 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 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, the overlay number at 4317H is cleared so that the next RST 28H for SYS3 reloads it.

4EC1H - 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 4FE5H and the walk goes on in the entry its back link names. The offset of the entry being worked on is at 4EC4H; its DEC is in Register D.

4F22H - Write the Last Entry and Finish

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

4F33H - 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.

4F56H - 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.

4F7DH - 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 4308H; for KILL (mode 01H at 4FDBH) its 32 bytes are then cleared. Skipped when bit 2 of 436BH is set (SYS6 sets it while it uses this code during COPY). Reached as a subroutine from 4F30H, or with JP from CLOSE (4E2FH, 4E36H), in which case its RET ends the DOS function.

4FE5H - Free a Directory Entry

Frees the entry at the offset stored at 4EC4H (in the buffer at 4200H), 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.

500DH - Write the Buffer, Then the EOF

Used by CLOSE (4E2CH) and write EOF (5053H) inside their DOS function. Two words are pushed so that the SYS0 buffer write at 4A62H returns into 49D7H: an error there leaves through 49CDH, otherwise 49D7H pops E507H and does RST 28H with Register A = E5H and Register C = 07H, which runs sub-function 7 (5018H) of this same overlay. Its RET comes back to the caller of 500DH.

5018H - Function E5H Sub-function 7: Write the EOF of the FCB into the FPDE

Reached only through the chain set up by 500DH, 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.

5050H - 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.

505DH - Function E5H Sub-function 6: PURGE

PURGE,[password:]dn[,/ext][,USR] (manual 2.40). SYS7 (4D69H) handles the start of the command and chains here with RST 28H: Register B = the drive number (from 4308H) 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 5164H-5166H), bit 1 = USR (leave out system and invisible files).

50A4H - 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).

5159H - 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.

5163H - PURGE Data

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

5182H - Function A5H: J-K-L Screen Print

Manual sections 2.26 and 4.5. The SYS0 key combination check (45BFH) 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 are sent as 40H-5FH (what the display shows for them) and anything above the value of option AX (4370H) as a period. BREAK stops the print. Zap 046 (optional, not applied in this file) sends codes 80H-BFH as A0H-DFH for Epson graphics, with its code in 51B4H-51BBH.

51B4H - Unused Bytes

The end of the file. Nothing in SYS3 reaches these bytes; the optional zap 046 puts its code in 51B4H-51BBH.