TRS-80 DOS - TRSDOS v1.3 - SYS00/SYS Disassembled

The $FILPTR routine provides information on any user file that is currently open. It enables you to obtain the drive number and the logical file number for any file and should be used in conjunction with $RAMDIR. This operates with user files only.

Entry Conditions

• (DE) = Data Control Block (DCB) defined when file was opened
• CALL $FILPTR

Exit Conditions

• NZ = Error occurred
• Z = No error. The following registers are set up:
  • B = Which drive contains the file (0, 1,2, or 3)
  • C = Logical file number (1-96)

This is the $RAMDIR vector which will allow you to examine a diskette directory (one entry or the entire directory) or the diskette's free space. The information is written into a user specified RAM buffer. Only non-SYSTEM files are included.

On entry:

• HL must point to the RAM buffer
• B must point to the drive number
• C will be the desired function:
  • C=0 will get the entire directory
  • C=1 to 96 will get the one specified directory record into RAM
  • C=255 will get the free space information

On exit:

• Z = No error
• NZ = Error
• (HL) will hold the information sought as follows:
  • Bytes 0-14: filename/ext:d (left-justified followed by spaces)
  • Byte 15: Protection Level, binary 0-6
  • Byte 16: Byte EOF, binary 0-255
  • Byte 17: Logical record length, binary 0-255
  • Byte 18-19: Last sector number in file, binary LSB, MSB
  • Byte 20-21: Number of Granules allocated (LSB,MSB) binary
  • Byte 22: '' + '' (marks the end of directory list after entire directory.)

The $COMDOS routine executes a TRSDOS command and returns to TRSDOS READY.

Entry Conditions

• (HL) = Text of TRSDOS command, terminated by x'00'
• JP $COMDOS

This is the start address of a buffer containing the last command line entered under TRSDOS READY. Using this buffer, your program may recover parameters that were included in the last command line.

For example, given a program named EDITOR/CMD, we want the operator to select an input file name when the program is loaded and executed from TRSDOS READY:

TRSDOS READY

EDITOR MYFILE

The program, EDITOR, can recover the name of the file in the $CMDTXT buffer.

Note: On entry to a program, (HL) = First non-blank character following the program name.

Source label: KILFIL — Kill File Routine. If the first byte of the filespec shows the file is already open (bit 7 set), jumps directly to KILFI1 to kill it. Otherwise, opens the file first via OPEN, then kills it via DO 20,3.

On entry, DE needs to point to the memory location which states whether a file is currently open or not

Source label: FIX1 — FDC Error Recovery. Terminates the current FDC operation via TERM. If a sector-not-found error (bit 4) occurred, restores the drive to track 0 by issuing a RESTORE command.

The $ERRDSP routine displays a TRSDOS error message determined by the contents of the accumulator (A). This register contains an error code (0 = no error) after completion of any system routine.

Entry Conditions

• A = TRSDOS error code. In a TRSDOS error code, bits 6 and 7 are normally reset (off). So $ERRDSP interprets them as controls.
  • Bit 7:
    • Set - Return to caller upon completion
    • Not Set - Return to TRSDOS upon completion
  • Bit 6:
    • Set - Give detailed error message
    • Not Set - Give error number only

Source label: DEBUG — Debug Entry Point. Saves A via PUSH AF, then invokes the SYS5 debug overlay via DO 00,5.

The $DSPDIR routine displays the directory listing of all non-protected user files in a specified drive

Entry Conditions

• (4271) = ASCII-coded drive number "0," "1," "2," or "3"
• CALL $DSPDIR

The $SYNTAX routine moves a file specification to DCB. This routine takes a file specification and checks it for validity and moves it to a DCB so that the file may be opened.

Entry Conditions

• (HL) = Filename
• (DE) = DCB
• CALL $SYNTAX

Exit Conditions

• Z = Good file specification
• NZ = Bad file specification

$INIT is provided as an entry point to TRSDOS which will create a new file entry in the directory and open the DCB for this file. $INIT scans the directory for the filespec name given in the DCB. If the filespec name is found, $INIT simply opens the file for use. If the name is not found, a new file is created with the filespec name.

Entry Conditions

• (HL) = BUFFER
• (DE)= DCB
• B = LRL
• CALL $INIT

Exit Conditions

• IY = changed
• Z = OK
• c carry flag is ON if a new file was created
• A = TRSDOS error code

$OPEN provides a way to open the DCB of a file which already exists in the directory. The DCB must contain the filespec of the file to be opened before entry to $OPEN.

Entry Conditions

• (HL) = BUFFER
• (DE)= DCB
• B = LRL
• CALL $OPEN

Exit Conditions

• Z = OK
• z = 0 if file does not exist
• A = TRSDOS error code
• IY = changed

The $CLOSE routine closes a file from the last processing done. It is very important to do a $CLOSE on every file opened before the program ends. If you do not close a file, the directory entry for this file is incorrect if any new records have been written into the file. Other cases are not given here, but it is very important to TRSDOS that all of the "housekeeping" be complete for file management.

Entry Conditions

• (DE)= DCB
• CALL $CLOSE

Exit Conditions

• Z = OK
• A = TRSDOS error code

The $KILL routine deletes the directory entry for a file and releases the disk storage. The file may be open or closed; $KILL will operate in either case.

Entry Conditions

• (DE)= DCB
• CALL $KILL

Exit Conditions

• Z = OK
• A = TRSDOS error code

$READ Vector. If LRLO, $READ transfers the logical record whose number is in the DCB as NRN into the RAM area addressed as UREC for the length LRL as defined at open time. The record comes from "BUFFER" defined at open time. If TRSDOS must read a new physical record to satisfy the request, it will do so. "Spanned" logical records will be re-assembled as necessary. $READ automatically increments NRN by l in the DCB after the transfer is completed. $INIT/OPEN set NRN = x'0000' in order to read the first record with the first READ.

If LRL = 0, $READ transfers one physical record into BUFFER, defined at open time, from the disk file. Registers HL are ignored. $READ increments NRN as above.

Entry Conditions

• (HL) = UREC if LRL is not zero. Unused if LRL = 0.
• (DE) = DCB
• CALL $READ

Exit Conditions

• Z = OK
• A = TRSDOS error code. (EOF= X'1C' or X'1D')

If LRLO, $WRITE transfers the one logical record from the RAM area addressed as UREC for the length LRL as defined at open time. The record goes into the BUFFER which was defined at open time. If TRSDOS must write a physical record in order to satisfy the request, it will do so. "Spanning" will be handled by TRSDOS as necessary. At $INIT/$OPEN time the DCB value of NRN is set to X'0000' so that the first record will be written. After each logical record is transferred, the NRN value in the DCB will be incremented by 1.

If LRL = 0, $WRITE transfers one physical record from BUFFER into the disk file using the NRN in the DCB. BUFFER is defined at $INIT/OPEN time only. The DCB value NRN is updated as above, after the WRITE.

Entry Conditions

• (HL) = UREC if LRL is not zero. Unused if LRL = 0
• DE = DCB
• CALL $WRITE

Exit Conditions

• Z = OK
• A = TRSDOS error code

The only difference between $VERF and $WRITE is that $VERF writes one physical record to disk and then reads it back into a special TRSDOS RAM area not defined by the user. This special area and the original write buffer are then compared byte by byte to assure that the record was successfully written.

Entry Conditions

• (HL) = Same as $WRITE above
• (DE)= DCB
• CALL $VERF

Exit Conditions

• Z = OK
• A = TRSDOS error code

The $REWIND routine will point to the beginning of the file. This routine positions the file pointer to the first record in the file. This is useful when the same file must be processed more than once.

Entry Conditions

• (DE) = DCB
• CALL $REWIND

Exit Conditions

• Z = Good file spec
• NZ = Bad file spec

The $POSN routine positions a file to read or write a randomly selected logical record. Since it deals with logical records, the proper computation is done to locate which physical record(s) contain the data. Following a $POSN with a $READ or $WRITE will transfer the record to/from RAM.

Note that positioning to logical record zero sets the file to read the first logical record in the file. To position to end of file in order to add new records onto the end, use the record number ERN + 1.

Entry Conditions

• (DE) = DCB (must have been opened previously)
• BC = Logical record number to position for
• CALL $POSN

Exit Conditions

• Z = OK
• A = TRSDOS error code

The $BKSPC routine positions the file record pointer to the previous record.

Entry Conditions

• (DE) = DCB
• CALL $BKSPC

Exit Conditions

• Z = Valid position
• NZ = Invalid position

The $POSEOF routine points to the end of file. This routine positions the file pointer to the last record in the file. This may be used to extend a sequential access file.

Entry Conditions

• (DE) = DCB
• CALL $POSEOF

Exit Conditions

• Z = Good file spec
• NZ = Bad file spec

This $PUTEXT routine will add an extension to a filename if an extension does not already exist. An extension to a filename may be useful for identifying the type of data in the file.

Entry Conditions

• (DE) = DCB
• (HL) = The extension to be added to the file
• CALL $PUTEXT

Exit Conditions

• None

The $DMULT routine uses a 16-bit multiplicand and an eight-bit multiplier. After multiplication takes place, the product replaces the 16-bit multiplicand.

Entry Conditions

• HL = Multiplicand
• A = Multiplier
• CALL $DMULT

Exit Conditions

• H = High order byte
• L = Middle order byte
• A = Low order byte

The $DIVIDE routine takes a 16-bit dividend and an eight-bit divisor. After division, the quotient replaces the 16-bit dividend and the remainder replaces the eight-bit divisor.

Entry Conditions

• HL = Dividend
• A = Divisor
• CALL $DIVIDE

Exit Conditions

• HL = Quotient
• A = Remainder (0 if none)

Source label: CIO1 — Character I/O Linkage (Disk), at 44B0H. Gets the driver address from DCB offsets 01H-02H (DADDL/DADDH) and the device type from offset 00H. Type 10H routes to another DCB (back to CIO0 at 44ADH); a type above 10H is a disk file DCB and goes to CIOF (44C3H); a type below 10H jumps to the driver with JP (HL).

Source label: CIOF — Disk File Character I/O. Sets bit 7 of IX+PROT to indicate not LRL-256 mode. Calls SAVER to set up registers, then dispatches to WRBYTE (write) or RDBYTE (read) based on function code in B.

Register B holds the KIND of I/O needed and Register C holds the byte to be sent.

Source label: DSEL — Select Drive by Number. Entry: C = drive number (0-3). Converts to bit pattern via SITIT, ORs with DOUBLE (80H) density bit, stores result in DRIVE variable.

Source label: DSELCT (44DDH) — Select Drive by Bit Pattern. Reads the DRIVE variable and outputs the bit pattern to port F4H (CDRV drive select latch).

Register C holds the drive number to select.

Source label: SEEK — Seek to Track. Entry: D = desired track, C = drive number. Saves registers (SAV3 macro). Sets write pre-compensation for tracks >= 22. Compares current track position to desired track. Issues RESTORE + re-seek on seek error.

On entry, Register C holds the drive number, and Register D holds the track number.

On entry, Register A should hold the current track number and Register D should hold the desired track number.

Source label: TERM — Terminate FDC Operation. Outputs the force-interrupt command (D0H) to port F0H (CSTAT). This immediately stops any in-progress FDC command.

Assumes the head is already properly positioned.

Source label: BOTNMI — Set Up NMI for Disk I/O, at 459CH. Saves HL, points the NMI vector address field (404AH) at BORNMI (45ADH), writes C3H (the JP opcode) to 4049H, reads port F0H to clear any pending FDC interrupt and returns with interrupts disabled. The caller then enables the FDC interrupt through port E4H.

Source label: BORNMI — NMI Handler for Disk I/O Completion. Clears the NMI mask (port E4H), resets the NMI vector to point at RETX (a RETN instruction at 42BDH), then clears any pending FDC interrupts.

Assumes the head is already properly positioned and that Register A holds the drive select code.

Positions the head first. Register C must be set to ... dunno.

First we need to check for write protect.

Positions the head first (continuation after verification that the disk isn't write protected).

Start of a BIG loop for 9 iterations. The bottom of the loop is at 464EH.

Positions the head first (continuation after positioning the head successfully.

At this point, we know the disk isnt write protected, that we are on the right track, and that the FDC wasn't busy and didn't have an error ... so we are good to start writing.

End of loop of 9 tries.

Source label: XREAD — Sector Read with Retries. Entry: D=track, E=sector, C=drive, HL=>buffer. Saves buffer pointer in RHL, calls CHKDRV to verify drive exists. Retries RETRY (9) times. Classifies errors: EHFLT (hardware fault/motor off), ELOSTD (lost data), ECRC (CRC error), ERNF (record not found), ESKER (seek error).

This has 2 entry points. The first empties HL (to toss away any data held there) one one leaves it alone.

Start of a BIG loop for 9 iterations. The bottom of the loop is at 46A7H.

If we are here, then we need to deal with a NOT READY FDC error from 469FH.

Jumped here from 4689H to deal with a SEEK ERROR, CRC ERROR or BUSY FDC code.

This is the VECTOR call for POSN - Position a File for Access.

This is the VECTOR call for BACKSPACE - Back Up To the Previous Record in a File.

Source label: REW — Rewind File. Calls SAVER, sets BC=0 (record 0) and A=0 (offset 0), then falls through to POSN2 for positioning.

This is the VECTOR call for REWIND - Position to the Start of a File.

Source label: PEOF — Position to End of File. Calls SAVER, reads ERN (ending record number) into BC and EOF byte into A from DCB, then falls through to POSN2.

This is the VECTOR call for POSEOF - Position to the End of a File.

This is the VECTOR call for READ - Read the Logical Record at the "NEXT" Position.

SUBROUTINE to first verify that READ ACCESS or higher is permitted, and then continue at 476CH. Called from 4772 and 4797.

Called from 4C58.

Source label: RDSEC — Read Sector into Buffer. Calls GETPDA to get the physical disk address (track/sector), clears bit 5 of PROT to show record has been read, loads buffer address from DCB, then calls XREAD.

Continues from routine at 476CH (which makes sure we are not past EOF). Sets up HL for re-entry into the position head and read sector routine.

Source label: RDBYTE — Read Byte from File. If bit 5 of PROT is set, reads next record first via RDREC1. Calls GETPRN to verify record is in range. Calls CALCBA to get buffer address. Returns byte in A. Increments OFFSET; when OFFSET wraps to 0, sets bit 5 of PROT and increments NRN.

47B6H - Start of a loop for the entire LRL of the sector.

This little routine is called both when there is an error, or when there isn't, in the above routine.

Source label: WRRECX — Write Physical Record. Sets carry flag (bit 6 of PROT). Checks protection level: if >= PREAD (5), returns EFAD (access denied) error. Calls GETPDA for physical address, ALLOC if record out of range, then XWRITE. Updates ERN if record exceeds current end.

Called from 47B3H (the WRITE VECTOR) if it was determined that SECTOR I/O was required.

If we are here then we have an error, so we need to figure out which error and waht to do about it.

Source label: WRBYTE — Write Byte to File Buffer. If sector not yet read (bit 5 of PROT set), reads it first via RDSEC. Calculates buffer address via CALCBA. Stores byte, sets bit 4 of PROT (record needs writing). When OFFSET wraps to 0, sets bit 5 and writes the full buffer via WRRECX.

Called from the prior WRITE A BYTE AT NEXT POSITION routine if the current sector is already loaded.

Jumped to from the prior routine when it is time to write the buffer out to diskette because the buffer is full.

Source label: DBLOCK — Check/Write Pending Buffer. Checks bits 4 (write pending) and 6 (carry flag) of PROT. If either is set, writes the buffer via WRREC. Otherwise returns Z (no action needed).

Source label: CALCBA — Calculate Buffer Address. Reads OFFSET from DCB, adds to BUFL/BUFH to compute DE => next available byte in buffer. Returns C = byte offset.

Source label: SAVER — Save Registers for DCB Operations. Checks bit 7 of first DCB byte to verify file is open. Saves caller return address in SAVE2, DCB pointer in SAVE3. Moves DE to IX for indexed addressing. Pushes HL, DE, BC, IY. Sets up RET6 as cleanup address. Returns to caller with Z flag set.

This routine is called a LOT and prepares for an actual diskette write.

This routine will finish up the diskette write and RETURN. It was set in 489BH.

This routine is JUMPed to from 4883H if the file we wanted to do I/O upon was not open.

This subroutine is called from 47FF to allocate filespace (and/or expand if we hit the EOF).

The next 4 instructions are designed to set Register Pair HL to be the extent elements by setting HL as a base of 10, putting the DCB into Register Pair DE, and then adding DE to HL.

This routine is JUMPed to from 4905H if an open extent is found.

The next few instructions basically set Register C to be the number of grans offset from the start of the track.

The next few instructions basically set Register A to be the number of grans in the extent.

So now C holds the number of grans offset from the start of the track, and A holds the grans in the extent.

There aren't a lot of variables in the Z-80 so the next 3 instructions simply set DE to point to the GAT Table, by setting A=L, A=A+E, E=A.

The next bunch of instructions set that there is now one less gran on the disk to allocate.

This subroutine is called from 494DH to continue with the file space allocation.

The first part of this routine figures out what the EOF data is in the buffer and then saves the new EOF in the directory.

Now that the new EOF has ben saved, need to deal with the extents.

Routine to search for an available gran and if none, error out.

SUBROUTINE called from 4997H to find a free gran on a diskette and either JUMP to 49A7H if there is one or error out if there isn't.

The next bunch of instructions only serves to set DE = DE - number of sectors in the extent and put that into Register A (with the CARRY FLAG set if the result is negative).

DE now holds the number of sectors in the extent.

If we are here then every extent has been checked and all extents have been used. This is bad.

The next few instructions get the offset (in grans) into the track of the extent.

Now that the offset (in grans) is in Register A, prepare to calculate it and write it.

Jumped here from 4A1BH if the offset is negative.

SUBROUTINE to convert the Grans (which was the masked value) into a sector.

Subroutine to check if the sought after sector is after the EOF. Called from 476CH, 479BH, and 4815H.

The combination of IX+08H, IX+0CH, and IX+0DH is the relative byte address of the EOF.

The combination of IX+05H, IX+0AH, and IX+0BH is the relative byte address of the "NEXT" sector.

Subroutine to WRITE the Directory Entry from Buffer # 1. Called from 4981H.

Jumped to from 48B3H.

Subroutine to WRITE the GAT TABLE from the Buffer. Called from 497DH.

This routine is called to position for a READ (called from 4A69H and 4A7DH) or for a wRITE (called from 4A7DH). Register L will hold the results

The next 3 instructions set Register A to be the appropriate directory sector by setting Register E = Register L + 3.

We next want to test Register B (the remainder) to see if it is ZERO or not, but we don't necessarily want to mess with other registers, so the simplest way to do that is to increase and decrease Register B.

If we are here, then the remainder was NOT zero, so we need to do some math, via a LOOP set to B interations.

Set up for an ILLEGAL LOGICAL FILE NUMBER error and RETurn.

This is the jump point from the routine to compute where the directory entry for a file is located when the remainder is zero (meaning, no offset calculation was required).

Called from 4A71, 4A96, and 4ABD

This routine is JUMPed to from 4B23H if it didn't find 0FEH as the first byte on the disk, meaning that there is no system!

Routine exits with the director track number in Register D.

The next few instructions create an OPCODE along the lines of BIT nn of Register B.

Put the generated OPCODE into 4B53H. If tthe value is 40H then it tests Bit 0; 48H tests Bit 1, 50H tests Bit 2, 58H tests Bit 3, and so on.

On exit, Register A = Overflow and Register Pair HL = the result of the multiplication.

Start of an 8 bit loop.

End of an 8 bit loop. The next bunch of varliable exchanges are to set Register A = Overflow and Register Pair HL = the result of the multiplication

Start of a loop.

End of the loop.

Register A to hold the requested overlay on entry.

The next 3 instructions set B = Logical File Number * 2 + 0E0H.

The next 2 instructions set HL = 4300H + B.

The next 4 instructions set DE = the First Overlay Extent Element.