TRS-80 DOS - LDOS 5.3.1 for the Model I - SYS10/SYS Disassembled

SYS10/SYS

Other Navigation

LDOS 5.3.1 SYS10/SYS Disassembly - File Deletion and Module Lookup (Model I)

SYS10/SYS is the LDOS 5.3.1 overlay that deletes files. It services the @KILL vector at 442CH, which issues RST 28H with request code 9CH, and it is the exact counterpart of SYS8/SYS: where SYS8/SYS claims granules and builds extent entries as a file grows, SYS10/SYS gives every one of them back.

The overlay also carries a second, unrelated service. Request code 0BCH masks to sub-function 30H and selects the resident module and driver control-block lookup at 4F28H, which walks the chain of modules installed in high memory looking for one whose name matches the string the caller points at. That is the service SYS6/SYS LINK and ROUTE and SYS7/SYS SYSTEM, FORMS and SETCOM all use to locate the control block they are about to edit, and it is the source of the "not resident" and "not installed" messages those commands produce.

The file is small: 371 bytes spanning 4E00H through 4F72H, plus a 2-byte load block deposited at 4BC9H in the resident padding area, with a transfer address of 4E00H. It should remain on working SYSTEM diskettes, since without it no file can be removed.

Deletion begins with a permission check. LDOS numbers access levels from 0 for full access upwards, and only levels 0 and 1, full access and remove access, permit a file to be deleted; anything higher is refused with error 37. The overlay then reads the drive's Granule Allocation Table into its buffer at 5000H and walks the file's directory record. Each of the four 2-byte extent entries at DIR+16H through DIR+1DH names a cylinder and, in a packed byte, a starting granule and a granule count; for every one of them the routine at 4E8BH clears the corresponding allocation bits, rolling forward onto the next cylinder whenever a granule number reaches the number of granules a cylinder holds.

With the extents released, bit 4 of the record's attribute byte is cleared to mark the directory slot free, the record is rewritten, and the file's byte in the Hash Index Table is zeroed so the name no longer hashes to anything. If the record ended with the FEH marker at DIR+1EH the file continues in a secondary extended directory record, and the whole sequence repeats for it. Only when the chain is exhausted is the Granule Allocation Table written back, at which point the freed space genuinely becomes available. Finally the caller's 32-byte File Control Block is zeroed so it cannot go on referring to a file that no longer exists.

Deleting a logical device takes none of this. A device owns no granules and no directory record, so its control block is simply rebuilt as the four-byte specification *XX followed by an 03H terminator, in the same shape SYS3/SYS produces when it closes a device.

Two pieces of the overlay are worth noting for their construction. The Granule Allocation Table handler at 4ED4H has two entry points one byte apart which select reading or writing through a single shared body: 4ED4H is OR 0AFH, and entering at 4ED5H executes that instruction's second byte alone as XOR A, setting the Z FLAG that the test at 4EE2H reads. And the helper at 4EC7H builds a RES n,B instruction for a granule number and plants it before executing it, mirroring exactly the SET n,A builder SYS8/SYS uses when it allocates.

Memory Map

Variables and Self-Modified Operands

Major Routines

Error Codes Returned

Cross-References

SYS10/SYS is reached through the resident supervisor. The @KILL vector at 442CH in SYS0/SYS loads request code 9CH and issues RST 28H, and the dispatcher at 4BCDH brings this overlay in at 4E00H. The overlay calls back into the resident core for all disk work: the File Control Block prologue at 49F1H and its second entry at 49F3H, DIRRD at 4B10H and DIRWR at 4B1FH for directory records, DIRCYL at 4B65H and RDSSEC at 4B45H to reach the directory cylinder, WRPROT at 4768H and VERSEC at 4772H to write and verify the two table sectors with a deleted-data address mark, and DCTBYT at 479CH for drive geometry. It uses the resident shared sector buffer SBUFF$ at 4200H, and reads HIGH$ at 4049H and the top-of-memory word at 4403H when searching the module chain.

It is the mirror image of SYS8/SYS, which allocates the granules this overlay releases and builds the extent entries it walks; the two share the directory extent layout, the FXDE link convention and the Granule Allocation Table and Hash Index Table sector handling, and their bit helpers are opposites. SYS3/SYS performs the same kind of partial release when it trims unused granules on close, and produces the same *XX device specification at 5029H. The error codes returned here are turned into readable text by SYS4/SYS. The module lookup at 4F28H is called by SYS6/SYS LINK and ROUTE and by SYS7/SYS SYSTEM, FORMS and SETCOM.

4BC9H - Overlay Load Block

The two bytes every SYS overlay deposits into the padding area of the resident core immediately below the RST 28H dispatcher. They are data, not instructions, and are never executed. SYS10/SYS writes 73H and 01H here, in the same way SYS8/SYS writes 96H and 02H and SYS4/SYS writes AFH and 03H.

4E00H - Overlay Entry and Request Dispatch

SYS10/SYS services two supervisor requests. Request code 9CH, which masks to sub-function 10H, is @KILL, the file and device deletion service. Request code 0BCH, which masks to 30H, is the resident module lookup. Any other value returns without action.

4E0AH - Delete a Disk File

The deletion path checks that the file was opened with an access level that permits removal, then walks the directory extent chain releasing every granule the file owns back into the Granule Allocation Table, marks each directory record free and de-hashes it in the Hash Index Table, follows any FXDE link to a secondary extended record, writes both tables back, and finally clears the caller's File Control Block.

4E72H - Close Out a Logical Device

A logical device owns no granules and no directory record, so there is nothing to release. The control block is simply rebuilt as the four-byte device specification *XX followed by the 03H terminator, exactly as SYS3/SYS does at 5029H when it closes a device, leaving a block that can be handed straight back to an open request.

4E8BH - Release One Extent Into the Granule Allocation Table

Given an extent word in Register Pair DE, this routine clears the allocation bit of every granule the extent describes. It reads the drive geometry to find how many granules a cylinder holds, doubling it for a double-sided drive, then walks the extent granule by granule, rolling over to the next cylinder's allocation byte whenever the granule number reaches the per-cylinder figure.

4EC7H - Granule Allocation Bit Reset Builder

A granule number from 0 to 7 cannot be used directly by a Z80 bit instruction, so this helper constructs the second opcode byte of a RES n,B instruction for that granule and plants it in the instruction at 4ED1H before executing it against a cylinder's allocation byte. It is the exact counterpart of the bit-setting helper SYS8/SYS uses when it allocates a granule.

4ED4H - Read or Write the Granule Allocation Table

One body serves both directions, selected by which of two entry addresses the caller uses. Sector 0 of the directory cylinder holds the Granule Allocation Table, one byte per cylinder with a set bit for every granule in use, and it is held in this overlay's buffer at 5000H. Reads return error 20 on failure; writes go out with a deleted-data address mark, are verified, and return error 21.

4EF8H - Read the Hash Index Table

Sector 1 of the directory cylinder holds the Hash Index Table, one hash byte per directory record with zero marking a free record. Two entry points choose the destination buffer: 4EF8H reads it into the overlay buffer at 5000H and 4EFDH into the resident shared buffer SBUFF$ at 4200H, which is the one the deletion path uses. A failure returns error 22.

4F0FH - Write the Hash Index Table

The amended Hash Index Table image at 4200H is written back to sector 1 of the directory cylinder with a deleted-data address mark and then verified, committing the release of the file's directory records. A failure returns error 23.

4F28H - Resident Module and Driver Control Block Lookup

This is the service behind request code 0BCH. Register Pair DE addresses a module or device name; the routine measures it, then walks the chain of resident modules installed above HIGH$ comparing each header's name against it. A match returns the address of that module's control block in Register Pair DE with the Z FLAG set, which is what SYS6/SYS LINK and ROUTE and SYS7/SYS SYSTEM, FORMS and SETCOM use to find the block they are about to edit. No match returns error 8.