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

SYS2/SYS

Other Navigation

NEWDOS/80 v2.0 SYS2/SYS Disassembly - Open, Load, Allocate and RENAME (Model I)

SYS2/SYS is the overlay that opens files. It loads into the overlay area at 4D00H-51ACH (1,197 bytes, transfer address 4D00H) and is called with LD A,code / RST 28H; the SYS0 dispatcher (4BC2H) loads it when 4317H does not already hold its number (04H). Besides the two opens (4424H and 4420H) it loads and runs programs (4430H and 4433H), allocates granules when a file grows (called by SYS0 from inside a read or write), encodes passwords, and does the directory work of RENAME and of running a program named on the command line for SYS1.

The page shows every byte of the file once, in address order. 51ADH-51FFH, after the end of the file, is SYS2's work space (see Variables).

RST 28H Codes Handled by SYS2

How a File Is Opened

How Granules Are Allocated

Variables and Work Areas

SYS6 Uses SYS2's Code

4D00H - Function Dispatcher

SYS2 is entered here by the SYS0 RST 28H dispatcher (4BC2H) with Register A = the RST 28H code and the caller's BC, DE and HL unchanged. Bits 5-7 of the code are the function number (bits 0-4 = 04H, SYS2's directory slot): 24H open an existing file (4424H), 44H open a new or existing file (4420H), 64H allocate granules (SYS0 48BDH, inside the allocate routine 4809H), 84H encode a password, A4H load a program (4430H), C4H load and run a program (4433H). Function 7 (E4H) takes a sub-function in Register C: 1 RENAME (SYS1), 2 find a free directory entry on drive D, 3 run the program named on the command line (SYS1 4E96H), 4 create a new file. Any other code or sub-function returns error 2AH; SYS6 (568DH) relies on this to load SYS2 with C = FFH and then call into it.

4D2EH - Return Error 2AH

Reached from the dispatcher for an unknown function code or function 7 sub-function. RENAME also uses 4D30H to return error 25H.

4D32H - Function E4H, C = 1: RENAME

Called by SYS1 for the RENAME command (manual section 2.43) after it has opened the old file. DE points to the open FCB of the old file; SYS1 has put the new filespec at 51E0H. The new name is looked for on the drive of the old file only (4E75H is patched so that 4E77H-4E7EH run); if it exists the result is error 35H. Otherwise the new name and extension are written into the old file's FPDE and the new name's hash code into its HIT byte. The password and everything else in the entry are kept.

4D72H - Function E4H, C = 4: Create a New File

Opens a file as the 4420H function does, but returns error 35H if the file already exists. DE points to the FCB holding the filespec, HL to the buffer, Register B = the record length.

4D7BH - Function E4H, C = 3: Run the Program Named on the Command Line

SYS1 calls this (4E96H, code E443H) for a command word that is not a library command: the word has been put into the FCB at DE as a filespec with the default extension /CMD, and HL points to the command line after it. The program is loaded and run with HL pointing to the rest of the command line.

4D80H - Function C4H: Load and Run a Program (4433H)

DE points to the FCB holding the program's filespec. The program is loaded (4D92H) and entered at its transfer address with HL = the caller's HL (from 4D7BH, the command line pointer). If 4369H bit 7 is set (the DEBUG command was given), DEBUG is entered instead, with the transfer address on the stack as the program counter.

4D92H - Function A4H: Load a Program (4430H)

DE points to the FCB holding the program's filespec. The file is opened with 4200H as the buffer and loaded by the SYS0 loader (4C28H). The access level must allow EXEC (level 6 or below); for the load it is set to READ and put back afterwards. Returns HL = the transfer address (also stored at 4403H-4404H) and the Z FLAG, or an error.

4DBDH - Function 44H: Open a New or Existing File (4420H)

Manual section 3.4. DE points to the FCB holding the filespec, HL to the buffer, Register B = the record length (0 = 256). The file is looked for first (4E2EH). If it does not exist, a free directory entry is taken on the drive given in the filespec, or, without a drive number, on the first drive from option AO (43A1H) up that has room, and a new FPDE is written: in use, access FULL, EOF 0, no granules, the password's code as both passwords. Returns the Z FLAG with the CARRY FLAG set if the file was created, NC if it existed.

4DEAH - Write the New FPDE

HL points to the cleared directory entry (bytes 0-21 are 00H, 22-31 FFH), Register A = its DEC.

4E09H - Try the Next Drive or Return the Error

Called by the drive loops of the open (4EA9H) and of the create (4DE5H) with Register E = the error to give if no drive is left (18H or 1AH) and Register A = the error of this drive (or 0). Returns Register A = the next drive if there is one. Otherwise it discards its return address and RETurns from the routine that called it with an error: when all drives have been tried, the one in Register E; when a drive number was given, the drive's own error if there was one, else the one in Register E.

4E1BH - Return Error 20H

Reached for a bad drive number in the filespec: not a digit, over 255, or (for RENAME) given at all.

4E1FH - Take Byte 1 and the EOF Low Byte of an Entry

HL points to byte 0 of a directory entry. Byte 1 is stored at 4F46H (it becomes FCB+2) and byte 3 (the EOF low byte) at 4F58H (it becomes FCB+8). Returns HL pointing to byte 4. SYS6 calls 4E21H (56C4H) with HL = byte 1 and Register A = 00H, which it stores instead of byte 1.

4E2CH - Function 24H: Open an Existing File (4424H)

Manual section 3.4. DE points to the FCB holding the filespec NAME/EXT.PASSWORD:d, HL to the buffer, Register B = the record length (0 = 256; 4E2CH sets 0). The filespec is parsed into 51CDH-51DFH, the password encoded, the name's hash code worked out, and the directory of each drive searched (4EAEH) until the file is found. The FCB is then built from the FPDE (4F2EH). Errors: 30H bad filespec, 20H bad drive number, 18H not found, 19H wrong password, a disk error for a drive that was given.

4E77H - RENAME Only: Use the Old File's Drive

Reached only while 4E75H is LD A,08H (RENAME).

4E7FH - Encode the Password and Hash the Name

Stores the drive range, replaces the password characters by their code (51D8H-51DBH) and works out the name's hash code (4D6EH) from the 11 name and extension characters.

4E9FH - Search the Drives

Tries each drive from the first to the limit (4E09H). Register E = 18H is the error returned if the file is on none of them.

4EAEH - Search One Directory

The HIT (directory sector 1) has one byte per DEC: 00H for a free entry, else the hash code of the name. The DECs whose HIT byte equals the name's hash code are collected at 51ADH-51CBH (up to 31 at a time), then each is checked (4EDDH). Register B = the next DEC to look at, Register C = 1FH (DECs with bits 0-4 = 1FH are not looked at: HIT byte 1FH holds the number of extra FDE sectors).

4EDDH - Check the Matching Entries

Takes the DECs from the list, last first. An entry must be an FPDE in use with the same name and extension. For the matching entry the password is checked (4F06H).

4F06H - The File Is Found: Check the Password

HL points to byte 15 of the FPDE. If option AA (436CH bit 7, passwords on) is off, or the password given has the update password's code, the file is opened with access level 0 (FULL). If it has the access password's code, the level in bits 0-2 of byte 0 is used. Otherwise the result is error 19H.

4F2EH - Build the Open FCB

IX points to the FCB. DE (4F2EH) or the word on the stack (4F30H) points to byte 20 of the FPDE, Register A (4F30H) = the access level. The other values come from operands stored earlier: FCB+2 (4F46H), the buffer (4F48H), the DEC (4F56H), the EOF low byte (4F58H) and the record length (4F5EH). SYS6 calls 4F2EH (56CCH) to open a file whose entry it has found itself. Returns Register A = 0 and the Z FLAG, or error 2CH if the EOF in the entry is bad.

4F79H - Copy 8 Bytes

4F79H copies 8 bytes from DE to HL, 4F7AH from HL to DE: four extent elements.

4F82H - Function 64H: Allocate Granules

Called by SYS0 at 48BDH (CALL 49DDH) from the sector mapping routine (4809H) when the sector wanted lies past the last granule the file has. IX = the FCB, IY = 4380H, DE = the number of granules missing minus 1, and 486AH (the operand of the LD A,nn at SYS0 4869H) holds the DEC of the file's last directory entry (the FPDE, or its last FXDE). SYS2 allocates DE + 1 granules, extending the last extent element while the next granule is free, else starting a new element; when the entry's four elements are used up it creates an FXDE (5058H). After the granules asked for it takes up to 3 more that follow on without a gap (5018H); CLOSE (SYS3) gives back what the file does not use. The GAT and the entries are written, the elements of the FPDE copied into FCB+14 to FCB+21, and SYS2 returns with HL pointing to the last entry, from which SYS0 (48C2H) maps the sector again. Errors (3DH no extend, 1BH diskette full, 2CH, disk errors) leave through SYS0's DOS function error exit (49CDH).

4FC5H - Scan the GAT

The GAT (directory sector 0) has one byte per lump, one bit per granule (1 = in use). HL = 4200H + lump, Register C = the granule's bit, Register B = the granules left in this lump, DE = the extent element being filled in 51ADH-51B4H. The scan runs to the last lump (430BH), then once more from lump 0.

4FFDH - Take a Free Granule

Register A = the element's lump byte plus 1 (0 if the element is empty), HL = the GAT byte, Register C = the granule's bit.

5018H - Up to Three More Granules

When the granules asked for have been taken, three more are asked for, unless bit 0 of 436BH shows that this has been done already or bit 1 is set (SYS6's copy, which sets it during its pre-allocation write). While bit 0 is set, a granule that does not follow on (5052H) or a full diskette (4FF0H) ends the allocation without an error.

502AH - Finish

Writes the GAT and the extent elements and returns to SYS0 with HL pointing to the file's last entry as it was at the start (the one in 486AH).

5043H - Add the Granule to the Element

DE points to the element's lump byte. The granule is the one after the element's last, so it is added if the element has fewer than 32 granules.

504CH - Next Element

The granule does not follow the element (or the element is full): go on with the next element of the entry. After the fourth comes the FEH stored at 51B5H.

5058H - Create an FXDE

All four elements of the entry are used. A free directory entry is found (50CFH), starting in the FDE sector of the old entry and with the old entry's HIT byte as its hash code. It becomes an FXDE: byte 0 = 90H, byte 1 = the DEC of the old entry. The old entry gets FEH and the new DEC in bytes 30-31. The allocation then goes on with the new entry's empty elements.

508CH - Write the GAT and the Extent Elements

Writes the directory sector in 4200H (the GAT), then copies 51ADH-51B4H into bytes 22-29 of the entry being extended (505EH) and writes it. If that entry is the FPDE, the elements are also copied to FCB+14 to FCB+21. Returns HL = 4200H.

50AEH - Write the Directory Sector

Writes the sector in 4200H; an error leaves through 503DH.

50B4H - Copy an Entry's Extent Elements

Register A = the entry's offset in 4200H. Copies bytes 22-29 to 51ADH-51B4H and puts FEH at 51B5H. Returns HL pointing to the last element in use, with NZ; or to 51ADH with the Z FLAG if all four are empty.

50CAH - Function E4H, C = 2: Find a Free Directory Entry

Register D = the drive, HL = the address of the hash code for the HIT, Register B = the DEC or hash code whose FDE sector the search starts in. 50CFH is called directly by the open (4DDEH), by 5061H and by SYS6 (610EH) with the drive already selected. The search starts in FDE sector (B AND 1FH) modulo the number of FDE sectors (8 + HIT byte 1FH), takes the first entry whose HIT byte is 00H, stores the hash code there and writes the HIT, then clears the entry (5110H). Returns HL = the entry, Register A = its DEC and the Z FLAG, or 1AH (DIRECTORY SPACE FULL), 2CH, or a disk error.

5110H - Clear an Entry or an FCB

HL points to 32 bytes: bytes 0-21 are set to 00H and bytes 22-31 to FFH (empty extent elements). Used for a new directory entry (510FH) and for the FCB (4F33H). Registers A and HL are kept; returns the Z FLAG.

5121H - Copy a Filespec Field

DE points to the character before the field, HL to where it goes, Register B = the field length (5121H sets 8). With the NZ FLAG on entry the field is not there and is filled with spaces. Otherwise its first character must be a letter, the others letters or digits; it ends at the first other character, which is returned in Register A, and the rest of the field is filled with spaces. A bad first character or a field that is too long returns error 30H (BAD FILESPEC) from the open.

5146H - Fetch the Next Filespec Character

Returns the next character, in upper case, in Register A with NC if it is a letter A-Z, the CARRY FLAG otherwise.

5152H - Function 84H: Encode a Password

Works out the 16-bit code of the 8 characters ending at HL (5152H: the password at 51D8H-51DFH), going from the last character to the first, and sets the characters to spaces. Returns HL = the code, BC and DE kept. A blank password gives 4296H, PASSWORD gives 42E0H. Through RST 28H (code 84H) the caller's HL points to the last character and the code is returned in HL.

5188H - Unused Bytes

The end of the file. Nothing in SYS2 reaches these bytes.