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

SYS2/SYS

Other Navigation

SYS2/SYS is the NEWDOS/80 v2.0 overlay module responsible for file open/initialization operations, filename parsing, directory searches, hash code computation, file positioning, and related sub-functions. It is loaded into memory at 4D00H-51FFH (1280 bytes, 5 sectors) when invoked via RST 28H with function codes 24H, 44H, 64H, 84H, A4H, C4H, or E4H (low 5 bits = 00100 for SYS2). On entry, IX points to the FCB, DE to user parameters, IY to system base (4380H). This module interacts with directory entries, FCBs, and system flags but does not perform direct disk I/O (delegates to other SYS modules like SYS1). Key purposes: enable file creation/access, validate filespecs, compute hashes for HIT lookups, and handle file attributes/renaming.

Address	Description	Origin/Trace	Purpose
4289H	File flags byte	Set during file ops (e.g., 4D88H loads it); part of system area.	Bit flags for file status; bit 0 tested for special mode in reposition/chain.
42C1H	Current drive number	Set by DOS init or user; loaded at 4DCFH.	Selects drive for directory ops; compared in 4DCCH.
4300H	Temp buffer start	Hardcoded at 4D92H; used for filespec parsing.	Holds parsed filename/extension for directory search.
431FH	Max open files count	System config (from PDRIVE); loaded at 50D6H.	Limits file table slots; used in allocation checks.
4380H	System area base (IY points here)	DOS base; hardcoded in init.	Base for offsets like IY+3FH (drive code), IY+FEH (default drive).
4D6EH	Temp flag (self-modifying)	Set at 4E9BH (1 if filename all spaces, else 0).	Indicates blank filename for error checks in 4ECAH.
4E0AH	Drive pair (BC stored here)	Set at 4E7FH from parsed drive code.	Holds source/target drives for ops like rename.
4E0EH	Current drive code	Set at 4E9FH from parsed filespec.	Used in directory searches (4791H).
4F46H	Sector offset temp	Set at 4E21H from DE param.	Part of file position calc in $POSN.
4F48H	Position pointer	Set at 4E31H during parse.	Points to file position data.
4F56H	Attribute flag	Set at 4DEAH in $INIT.	Modifies file attributes during creation.
4F58H	Record length	Set at 4E27H from param.	Used in FCB setup for random access.
4F5EH	Access mode	Set at 4E35H from param.	Bit flags for read/write/random mode in open/init.
505EH	Extent element temp	Set at 507EH during extent handling.	Holds current extent for positioning.
51ADH	Directory entry buffer	Used at 4EAEH for dir read.	Temp storage for directory entry during search.
51CDH	Filename workspace	Hardcoded at 4E38H; 11 bytes.	Holds padded filename for parsing/hash.
51D8H	Hash pointers	Set at 4E87H during hash init.	Points to hash computation areas.
51DFH	Hash workspace	Hardcoded at 5152H; 8 bytes.	Buffer for filename bytes during hash calc.
51E0H	Extension workspace	Set at 4D44H during parse.	Holds file extension for parsing.

Start	End	Description
4D00H	4D2DH	Main dispatcher: Function code branching for SYS2 ops.
4D2EH	4D31H	Error return (2AH).
4D32H	4D71H	E4H sub-fn 1: Rename/modify attributes.
4D72H	4D7AH	E4H sub-fn 4: $INIT with validation.
4D7BH	4D7FH	E4H sub-fn 3: Chain/link.
4D80H	4D91H	Function C4H: $FEXT (file extent).
4D92H	4DBCH	Function A4H: $FSPEC parse/search.
4DBDH	4E08H	Function 44H: $INIT (create file).
4E09H	4E1EH	Error check utilities.
4E1FH	4E2BH	Position extract.
4E2CH	4E81H	Filespec parse (name/ext/drive).
4E82H	4EC6H	Directory search/setup.
4EC7H	4F2DH	File allocation/FCB init.
4F2EH	4F81H	FCB update utilities.
4F82H	508BH	Function 64H: $POSN (position file).
508CH	50C9H	Extent handling.
50CAH	50FEH	E4H sub-fn 2: Read dir sector.
50FFH	5120H	Buffer clear utilities.
5121H	5151H	Char parse/validate (alpha/digit).
5152H	5187H	Function 84H: Hash computation.
5188H	51FFH	Unused padding (NOPs).

• 4D00H: Main dispatcher - Branches on function code (24H=$OPEN, 44H=$INIT, etc.).
• 4DBDH: $INIT - Create new file, setup FCB, allocate dir entry.
• 4E2EH: $OPEN - Open existing file, validate access, setup FCB.
• 4F82H: $POSN - Reposition file pointer in FCB.
• 5155H: Hash computation - For filename to HIT index.
• 4D92H: $FSPEC - Parse filespec and search directory.
• 4D80H: $FEXT - Locate/update file extent.
• 4D32H: E4H sub-fn 1 - Rename or modify file attributes.
• 50CAH: E4H sub-fn 2 - Read directory sector.
• 4D7BH: E4H sub-fn 3 - Chain/link operation.
• 4D72H: E4H sub-fn 4 - $INIT with extra validation.

4D00H - SYS2 Main Function Dispatcher

SYS2 is the NEWDOS/80 overlay that handles $OPEN (open existing file) and $INIT (initialize/create new file) operations. When the DOS invokes SYS2 via the RST 28H supervisor call mechanism, entry is at 4D00H with the function code in Register A. The low 5 bits of the function code encode this as SYS2 (directory sector 6, function 0 = binary 00100). The high 3 bits (bits 5-7) encode which specific function within SYS2 is requested. Valid function codes for SYS2 are: 24H, 44H, 64H, 84H, A4H, C4H, and E4H. Register Pair IX points to the File Control Block (FCB) for the operation. Register Pair DE points to the user-supplied parameter block. Register Pair IY points to the DOS system area base (4380H on Model III).

4D2EH - General Error Return (Error 2AH)

This routine returns to the caller with error code 2AH (general error) and the NZ FLAG set to indicate failure.

4D32H - E4H Sub-Function 1: Rename/Modify File Attributes

This routine handles function code E4H with sub-function C=1. It renames a file or modifies its attributes. On entry, Register Pair DE points to the parameter block (first byte is the FCB pointer, second byte onward contains the new filename/attributes). Register Pair IX is set from DE to preserve the parameter block address.

4D72H - E4H Sub-Function 4: $INIT with Validation

This routine handles function code E4H with sub-function C=4. It calls the $INIT handler at 4DBDH (same as function code 44H) and returns based on the result.

4D77H - File Not Found Error Return (Error 35H)

This routine returns to the caller with error code 35H and the NZ FLAG set, indicating the specified file was not found in the directory.

4D7BH - E4H Sub-Function 3: Chain/Link Operation

This routine handles function code E4H with sub-function C=3. It calls a support routine at 4C7AH in SYS0/SYS1, and based on the result, either returns with error or falls through to the $FEXT handler at 4D80H.

4D80H - Function C4H: $FEXT (File Extent/Locate) Handler

This routine handles function code C4H ($FEXT). It calls the $FSPEC routine to parse and search for a file, and based on the result, dispatches to either the error handler at 4409H, the DEBUG entry at 440DH, or returns normally via 4BC5H. The POP AF at 4D7F means that when entered from the E4H/C=3 path, the stack has been adjusted.

4D92H - $FSPEC: File Specification Parse and Directory Search

This routine (function code A4H) parses a filespec string pointed to by Register Pair DE and searches the directory for a matching file. It first calls the full $OPEN search routine at 4E2CH, then examines the result. If the file is found, it sets up the FCB and returns the file's directory information.

4DA0H - Process Found Directory Entry

When the file search at 4E2CH returned with Z FLAG set, the file was found in the directory. Register Pair DE points to the buffer area where the directory data has been stored. This routine extracts the file's attributes, validates access permissions, stores the directory location, and returns the information to the caller.

4DBDH - Function 44H: $INIT (Initialize/Create New File) Handler

This routine handles function code 44H ($INIT), which creates a new file on disk. It first calls the $OPEN search routine at 4E2EH to check if a file with the specified name already exists. If the file already exists (Z FLAG set), it returns immediately (error - duplicate filename). If the file does not exist but a special condition is indicated (A=18H), it proceeds to allocate a new directory entry and set up the file.

4E09H - Error/Retry Handler

This routine handles error conditions during directory operations. Register E contains the error type/count parameter (1AH for directory-full type errors). Register D is preserved from the caller. The routine manages a retry counter and determines whether to retry the operation or return a fatal error. The address 4E0DH is a [SELF-MODIFYING CODE] location that stores the retry counter.

4E1BH - Invalid Drive Number Error Return (Error 20H)

This short routine returns error code 20H (decimal 32) with the NZ FLAG set, indicating an invalid drive specification in the filespec.

4E1FH - Extract Directory Parameters from Buffer

This routine reads 3 bytes from the buffer pointed to by HL, extracting directory track, sector, and drive information used for disk I/O operations. The values are stored in system variables at 4F46H and 4F58H for use by the disk read/write routines.

4E2CH - Pre-Entry: Set B=00H Before $OPEN

This two-byte stub sets Register B to 00H before falling through to the main $OPEN entry at 4E2EH. When entered directly via function code 24H ($OPEN), B is set here. When entered from other paths (like $INIT at 4DBDH), B may already contain a specific value and the call targets 4E2EH directly.

4E2EH - Function 24H: $OPEN (Open Existing File) Main Entry

This is the main entry point for the $OPEN operation. It calls the SYS0 context setup routine, then parses the user-supplied filespec string, computes the hash code, and searches the directory for a matching file. On entry: Register Pair DE points to the user parameter block containing the filespec string. Register B contains a mode flag (00H for normal open). Register Pair IY points to the DOS system area base at 4380H.

4E77H - Drive Number Validation

This code validates the parsed drive number against the system maximum and retrieves the actual drive number from the DOS system area if no explicit drive was specified.

4E83H - Hash Code Computation and Directory Search

After parsing the filespec and storing the drive numbers, this section computes the hash code for the parsed filename, stores it for later matching, and begins the directory search loop. The hash code is a single byte derived from the 11-byte filename+extension that provides a quick lookup index into the HIT (Hash Index Table) sector.

4EAEH - HIT Search Loop: Find Matching Hash Code in Directory

The GAT and HIT sectors have been successfully read from disk. Register Pair DE is set to 51ADH (the start of the working buffer for directory data). Register Pair BC is loaded with the size of the search range. The code now scans through the HIT (Hash Index Table) looking for entries that match the computed hash code of the target filename. When a match is found, the corresponding directory sector is read and the full 11-byte filename is compared.

4F2EH - FCB Initialization Entry (from $INIT path)

This entry point is used when initializing a new file ($INIT at 4E04H). It pushes DE and clears A before falling through to the FCB initialization at 4F30H.

4F30H - FCB Initialization: Set Up File Control Block

This routine initializes the FCB (File Control Block) for a newly opened or created file. IX points to the FCB base address. The routine clears the FCB, then fills in the status flags, drive info, extent descriptors, and EOF position.

4F79H - Copy 8-Byte Extent Data Block

Utility routine that copies 8 bytes from the source at DE to the destination at HL. Used to transfer extent descriptor data between directory entries and FCBs.

4F82H - Function 64H: $POSN (File Position) Handler

This routine handles function code 64H ($POSN), which repositions a file's read/write pointer to a specified location within the file. It verifies the file is open with the correct access mode, then walks the file's extent chain to locate the disk sector corresponding to the requested position. On entry: IX points to the FCB, DE points to the user parameter block containing the new position.

4FC5H - Position Traversal: Walk Extent Chain

This section manages the traversal of the file's extent chain during positioning. It reads sectors from the file, tracks the current position through the extent table, and handles transitions between extents and tracks. The code also manages granule allocation when the position extends beyond the current end of file (for write operations).

4FFDH - Handle Unallocated Granule During Position

When the GAT scan finds an unallocated granule during file positioning, this code determines whether to allocate a new granule (for write/extend operations) or to continue scanning. The code manages extent chain building and sector allocation.

502AH - Finalize Extent Chain and Return

This routine finalizes the extent chain after positioning is complete or when the extent has been modified. It writes the updated extent data and GAT sector back to disk, then performs cleanup and returns to the caller.

5043H - Mid-Extent Position Continuation

When the position scan encounters a non-terminator extent byte during granule allocation, this code continues processing the extent chain, handling transitions between extent entries and tracks.

508CH - Save Current Extent Data to Directory

Utility routine that copies extent data from the working buffer (51ADH) back to the directory sector buffer, then writes the sector to disk.

50AEH - Write Directory Sector with Error Check

Writes the current directory sector to disk and checks for errors. On error, jumps to the error exit at 503DH.

50B4H - Load Extent Table from Directory Entry

Reads the extent table from the current directory entry into the working buffer at 51ADH. Also scans for empty extent entries to determine the end of the extent chain.

50CAH - E4H Sub-Function 2: Read Directory Sector

Handles function code E4H with sub-function C=2. Reads a specific directory sector. Register D contains the directory-relative sector number to read.

50CFH - Search HIT for Free Slot

Searches the HIT sector for a free (empty) directory slot. Reads the HIT, then scans through the 256-byte sector buffer looking for zero entries (indicating unoccupied directory slots).

5110H - Clear/Initialize Directory Entry or FCB Buffer

This utility routine clears a block of memory used for directory entries or FCB buffers. It writes 00H bytes for the main data area (22 bytes per extent block) and FFH sentinel bytes at the boundaries. This creates the empty extent structure needed for a new file.

5121H - Extract Filename Characters from Filespec String

This routine extracts up to 8 characters from the filespec string pointed to by DE, converting them to uppercase and storing them in the buffer pointed to by HL. If fewer than 8 characters are provided (terminated by a delimiter), the remaining positions are padded with spaces. On return, A contains the delimiter character that terminated the extraction.

5146H - Fetch and Validate Next Character from Filespec

Fetches the next character from the filespec string at DE, converts it to uppercase via the ROM routine at 4548H, and tests whether it is an alphabetic letter (A-Z). Returns with CARRY set if not alphabetic.

5152H - Compute Filename Hash Code (Entry with HL=51DFH)

Entry point that sets HL to 51DFH before falling through to the main hash computation at 5155H. Used when the hash workspace needs to be at the default location.

5155H - Function 84H: Compute Filename Hash Code

This routine computes a 16-bit hash code from the 8-byte workspace buffer. The algorithm uses a series of XOR, rotate, and shift operations to produce a well-distributed hash value. The hash is used for quick directory lookups via the HIT (Hash Index Table). On entry: HL points to the end of the 8-byte workspace buffer. On return: HL contains the computed hash value.

5188H - NOP Padding (Unused Space)

Addresses 5188H through 51ACH contain NOP (00H) instructions. This is unused padding space at the end of the SYS2 overlay module. The overlay occupies addresses 4D00H through 51FFH (5 sectors × 256 bytes = 1280 bytes), and the active code ends at 5187H. The remaining 37 bytes are filled with zeros.