TRS-80 DOS - TRSDOS v2.3 for the Model I - SYS6/SYS Disassembled

SYS6/SYS

Other Navigation

TRSDOS v2.3 SYS6/SYS Disassembly - The Library Commands (Model I)

SYS6/SYS holds the nineteen library commands of TRSDOS 2.3: APPEND, ATTRIB, AUTO, CLOCK, COPY, DATE, DEVICE, DIR, DUMP, FREE, KILL, LIB, LIST, LOAD, PRINT, PROT, RENAME, TIME and VERIFY. Unlike SYS1/SYS-SYS5/SYS it is not loaded into the overlay area at 4E00H but at 5200H, the address programs are loaded at, so the overlays SYS1/SYS and SYS2/SYS that its commands call stay usable while it runs. SYS1/SYS finds the command name in its second command table and enters SYS6/SYS with the command's number in Register C; bit 4 of the system flags at 430FH records that SYS6/SYS is in memory, so later library commands run without loading it again until a program is loaded over it.

The file is 3,840 bytes: a name record (SYS6), a 169-byte copyright comment record, 34 load records and a transfer record (5200H), followed by 370 bytes of E5H. The load records hold 3,151 bytes, 25 of which are loaded twice: the first record loads the dispatch table with JP Z,5251H (RESERVED COMMAND) in eleven places, and each later group of records fills in its own command's address over one of them; the record at 5507H-5509H replaces LD HL,478BH with CALL 60CDH, the routine loaded by the last record. The page shows the bytes as they are after loading, 3,126 in all, each on one row in address order, checked against S:\1\SYS6.SYS and its listing. The areas between the load records are shown as DEFS rows.

Memory Map

How SYS6/SYS Is Entered

SYS1/SYS's 4E90H handles every name in its second command table. When bit 4 of 430FH is set it jumps straight to 5200H; otherwise it sets the bit and executes RST 28H with Register A = 88H, and SYS0/SYS loads SYS6/SYS (directory sector 2, entry 1) into 5200H and calls it. Either way Register C = the command number (1-19, in the table's alphabetical order) and Register Pair HL = the command line after the command name. 5200H pushes 402DH, so a command that ends with RET goes to DOS READY; errors leave through 4030H.

The commands lean on the overlays below them. CLOCK and VERIFY call SYS1/SYS's 51A0H, which is still in the overlay area because SYS1/SYS has just dispatched the command. The SYS0/SYS entries 441CH, 4473H and 4476H load SYS1/SYS when they are used. Any open (4424H or 4420H) loads SYS2/SYS, and the commands then call SYS2/SYS's routines directly: ATTRIB its field copy (5081H) and password hash (50D1H), RENAME its name hash (509BH) and its hash index table read and write (512EH, 5141H), FREE its drive test (50FDH). PROT and FREE open an empty filespec only to have SYS2/SYS loaded.

The Commands

Every command that takes a filespec parses it into the FCB at 5551H (and a second one into 5571H) through 441CH, which skips the noise words TO, ON and OVER. A missing or bad filespec shows FILE SPEC REQUIRED; so does a device name (starting with an asterisk) for APPEND, ATTRIB, DUMP, LIST, LOAD, PRINT and RENAME's first name. Disk errors go to 554CH, which shows the message text alone (error number OR 40H through 4409H).

Shared Routines

5515H tests for BREAK (the NZ FLAG) and pauses on SHIFT and @ until a key is pressed; with bit 5 of 430FH set it returns at once. 52EAH reads three two-digit numbers with a given separator for DATE and TIME. 5454H reads a password of up to eight characters and returns its hash through SYS2/SYS's 50D1H. 5BD1H reads an ATTRIB option's value. 5DE1H clears DIR's directory copy, 5DF1H shows the size line of DIR (A) and 5E3EH counts a file's granules through its continuation entries. 606CH writes a value as five decimal digits with leading spaces, using 608CH for each digit, and 60A7H divides a three-byte value by one byte.

Notes from the Code

• PROT's password input (5454H) pads the characters typed with spaces using DJNZ with Register B = 8 minus the count. When all eight characters are typed the count is 0 and 256 spaces are written from 5608H to 5707H, over the first eight bytes of APPEND. SYS6/SYS stays in memory afterwards, so an APPEND typed before SYS6/SYS is loaded again runs those spaces as code. BREAK is not tested either.
• LIST puts its parameter table (598BH) in Register Pair BC at 5942H, but 4476H takes the table in Register Pair DE, which holds the FCB at 5551H; the names are compared with the filespec text there, and (LINE=n) does not set the line count. The skip loop for LINE (595AH-5965H) would count Register Pair BC wrongly unless Register C were 00H, and it does not stop at the end of the file.
• ATTRIB clears the access level on every change: without PROT the file ends at level 0. Nothing in ATTRIB clears the invisible bit. Only the first letter of each option is tested. The level table's fourth entry (two tildes, level 3) can never match, because the value is copied by SYS2/SYS's 5081H, which takes only letters and digits. A file not opened at level 0 gets error 37H, which SYS4/SYS shows as UNKNOWN ERROR CODE.
• DIR (A) divides the ending record number times 256 plus the end-of-file byte by the record length at 60A7H. The division keeps only 16 bits of quotient and, for a record length above 128, loses the top bit of its remainder at 60BBH, so the EOF= figure can be wrong for record lengths 129-255.
• DUMP checks END against START and START against 7000H after the file has been opened or created; the error exit leaves the file open. The name record gets the first six letters and digits of the file name.
• COPY gives both files the buffer at 5600H, so each sector read is written as it stands. Only when the read ends with 1DH does it copy file1's end-of-file byte and record length into file2's FCB.
• PROT LOCK and UNLOCK, and FREE's count of free entries, skip entries 0 and 1 of every directory sector, the places of the system files; LOCK and UNLOCK also skip entries with bit 3 (invisible) set. LOCK and UNLOCK change both password hashes of a file and leave its access level alone.
• DIR goes through its copy of the directory as entry 0 of sectors 2-9, then entry 1 of sectors 2-9, and so on.
• AUTO copies 32 bytes whatever the length of the command; DATE and TIME store their numbers without a range check and ignore what follows the third.
• The message DEVICE SPEC REQUIRED (5543H, 55A5H) is never shown: nothing jumps to 5543H.
• APPEND has fifteen NOP bytes at 573DH-574BH after its positioning call, whose result is not tested.
• VERIFY changes the JP at 4439H. 478EH stores the verify switch at 485EH on every call of 4439H and 443CH; the store at 60D5H decides the switch for writes that reach 485DH without going through 478EH.
• LIST and PRINT do not close their file; ATTRIB and RENAME leave theirs open after changing the directory.

Work Areas in SYS6/SYS

Operands Changed by the Code

Addresses Outside SYS6/SYS

5200H - Command Dispatcher

SYS1/SYS's 4E90H enters here (directly, or through RST 28H code 88H when SYS6/SYS is not yet in memory) with Register C = the library command's number in SYS1/SYS's second command table (1 APPEND to 19 VERIFY) and Register Pair HL = the command line after the command name. 402DH (DOS READY) is pushed as the return address of every command, then Register A counts down to the command's routine. A number outside 1-19 shows RESERVED COMMAND.

526BH - Nothing Done

PROT jumps here (53A3H) when none of PW, LOCK and UNLOCK was given, and ATTRIB (5B34H) when no parameter list follows the filespec.

5283H - AUTO (Command 3)

Copies 32 bytes of the command line, starting after the space that ends the word AUTO, into bytes E0H-FFH of the granule allocation table of drive 0, the place where SYS0/SYS's start-up looks for a command to run. The 32 bytes are copied whatever the length of the command, so the 0DH ending a short command is followed by whatever was in the command line buffer after it; AUTO with no command stores the 0DH first, which means no automatic command.

529DH - DATE (Command 6)

DATE MM/DD/YY: three two-digit decimal numbers separated by slashes, read by 52EAH into 52DEH (month), 52DDH (day) and 52DCH (year) and copied into SYS0/SYS's date bytes 4044H (year), 4045H (day) and 4046H (month). The numbers are not checked against the length of a month or year; anything after the third number is ignored.

52B1H - TIME (Command 18)

TIME HH:MM:SS: three two-digit decimal numbers separated by colons, read by 52EAH into 52DEH (hours), 52DDH (minutes) and 52DCH (seconds) and copied into SYS0/SYS's clock bytes 4041H (seconds), 4042H (minutes) and 4043H (hours). The numbers are not checked against 24 hours or 60 minutes; anything after the third number is ignored.

52C5H - CLOCK (Command 4)

CLOCK or CLOCK (ON) adds SYS0/SYS's time display task (the task control block at 4CA9H, which shows the time on the top line of the screen at 3C35H-3C3CH) to timer slot 6; CLOCK (OFF) removes it. The word in parentheses is read by SYS1/SYS's 51A0H, which is still in the overlay area at 4E00H-51FFH because SYS1/SYS has just dispatched this command.

52EAH - Read Three Two-Digit Numbers

Register Pair HL = the command line, Register C = the separator (2FH slash for DATE, 3AH colon for TIME). Reads a two-digit decimal number, stores it at 52DEH, and repeats for 52DDH and 52DCH, with Register C required between the numbers. Returns the Z FLAG when all three were read, the NZ FLAG for a bad digit or separator. Register Pair HL ends after the third number; what follows it is not looked at.

52FFH - Read Two Decimal Digits

Register Pair HL = the text. Reads two characters that must both be digits 0-9 and combines them as tens and units. Returns the Z FLAG with Register A = Register E = the value 0-99, or the NZ FLAG when either character is not a digit. Register Pair HL ends past the characters read.

5316H - Read One Digit

Register Pair HL = the text. Returns Register A = the character minus 30H and the CARRY FLAG set when the character is a digit 0-9; Register Pair HL is moved past the character.

531DH - DEVICE (Command 7)

Lists the two-letter names of SYS0/SYS's device table at 43C0H (KI keyboard, DO display, PR printer), one per line. The table has four bytes per device (the name, then the driver address) and ends with 00H at 43CCH. Only the names are shown.

533AH - LIB (Command 12)

Lists the names of the nineteen library commands from SYS1/SYS's second command table at 4EBDH, which is still in the overlay area: four names to a line, each line starting with two spaces and each name followed by eight. A table entry is eight bytes, six characters of name and the address of its handler; the table ends with 00H.

536AH - PROT (Command 16)

PROT [:d] (PW,LOCK,UNLOCK) works on the master password of a diskette, kept as a hash at bytes CEH-CFH of its granule allocation table. It refuses to run while bit 5 of the system flags at 430FH is set. The person must type the current master password; PW then asks for a new one and writes it to the table, LOCK gives every user file on the diskette the master password as both its passwords, and UNLOCK gives them the blank password (the hash of eight spaces, 4296H). The first two directory entries of every directory sector, the places of the system files, and entries with bit 3 of their attributes set are left alone.

5454H - Read a Password

Reads up to eight characters typed at the keyboard into 5600H through the ROM's line input, pads them with spaces to eight characters and jumps to SYS2/SYS's 50D1H, which returns their hash in Register Pair HL. SYS2/SYS must be in the overlay area. The padding loop counts 8 minus the characters typed: when all eight are typed the count is 0 and DJNZ writes 256 spaces, from 5608H to 5707H, over the first bytes of APPEND at 5700H. BREAK is not tested.

54EBH - PROT Parameter Table

Three eight-byte entries for SYS1/SYS's parameter reader (4476H): six characters of name, then the address of the two-byte variable the value goes into. The variables are the operands of the LD DE,nnnn instructions that test them. 00H ends the table.

5504H - VERIFY (Command 19)

VERIFY or VERIFY (ON) makes every write through SYS0/SYS's 4439H read the sector back, by putting 47A8H (the write with verify, 443CH's routine) into the operand of the JP at 4439H; VERIFY (OFF) puts back 478BH, the plain write. 60CDH also sets SYS0/SYS's switch at 485EH (01H on, 00H off). The file first loads 21 8B 47 (LD HL,478BH) at 5507H; a later load record replaces those three bytes with CALL 60CDH.

5515H - Test for BREAK and Pause

Called between records by APPEND (57C6H), LIST (5976H), PRINT (59D1H) and DIR (5DB7H). Returns the Z FLAG to go on and the NZ FLAG when BREAK is pressed. A key that gives 60H (SHIFT with @) pauses until any key is pressed; BREAK during the pause also returns the NZ FLAG. With bit 5 of the system flags at 430FH set, it returns the Z FLAG at once without looking at the keyboard.

553AH - Error Exits

553AH shows FILE SPEC REQUIRED for a missing or bad filespec or a device name where a file is needed. 5543H shows DEVICE SPEC REQUIRED; nothing in SYS6/SYS jumps to it. 554CH shows a disk error from SYS0/SYS through the error message routine 4409H with bit 6 set, so only the text of the message is shown, without the ERRCOD line or the file and REFERENCED AT lines; SYS4/SYS then goes to 4030H.

5700H - APPEND (Command 1)

APPEND file1 TO file2 adds the bytes of file1 to the end of file2. Both must be files (a name starting with an asterisk is refused with FILE SPEC REQUIRED) and both must exist. file2 is opened with the buffer at 5600H and positioned at its end, file1 with the buffer at 6F00H; the copy loop at 57B6H then moves one byte at a time through the ROM's device routines until file1 ends or BREAK is pressed, and both files are closed.

574FH - COPY (Command 5)

COPY file1 TO file2 copies file1 sector by sector into file2, which is opened, or created when it does not exist. Both FCBs use the same buffer at 5600H, so each sector read for file1 is written to file2 straight from the buffer. When the read reports 1DH (RECORD NUMBER OUT OF RANGE), file1's end-of-file byte and record length are copied into file2's FCB before both files are closed; when it reports 1CH (END OF FILE ENCOUNTERED) both are closed as they are. A device name is not refused here.

57B6H - APPEND: Byte Copy Loop

Reached from 574CH. Each byte of file1 is read through the ROM's input routine 0013H and written to file2 through the ROM's output routine 001BH; with an open FCB as the device control block, SYS0/SYS's 47AEH reads or writes the next byte of the file. After each byte 5515H tests for BREAK, which ends the copy and closes both files.

57D7H - DUMP (Command 9)

DUMP filespec (START=a,END=b,TRA=c) writes memory from a to b into a disk file in the load module format SYS0/SYS's loader reads: a name record (type 05H, the first six letters and digits of the file name), load records (type 01H) of at most 254 bytes each, and a transfer record (type 02H) with c. The default extension is CIM. START and END default to 7000H and TRA to 402DH (DOS READY). START must be 7000H or more, above everything SYS6/SYS uses, and END must not be below START; both are checked only after the file has been opened or created, and the error exit leaves it open.

58F5H - DUMP Parameter Table

Three eight-byte entries for SYS1/SYS's parameter reader (4476H): six characters of name, then the address of the two-byte variable the value goes into, the operand of an LD HL,nnnn. 00H ends the table.

5914H - KILL (Command 11)

KILL filespec opens the file, to find its directory entry and check its password, and deletes it through SYS0/SYS's 442CH. A device name is not refused here.

592CH - LIST (Command 13)

LIST filespec (LINE=n) shows a text file on the display, one byte at a time, testing for BREAK and the SHIFT and @ pause at the end of every line. The parameter table address is put in Register Pair BC at 5942H, but SYS0/SYS's 4476H takes the table in Register Pair DE, which still holds 5551H: the parameter names are compared with the filespec text in the FCB instead of the LINE entry at 598BH. The skip loop for LINE counts lines in Register Pair BC with DEC C and DEC B, which is only right when Register C is 00H, and it does not stop at the end of the file. The file is not closed.

5994H - LOAD (Command 14)

LOAD filespec loads a program file into memory through SYS0/SYS's 4430H without running it, and goes back to DOS READY.

59ACH - PRINT (Command 15)

PRINT filespec sends a file to the printer one byte at a time through the ROM's 003BH, testing for BREAK and the SHIFT and @ pause after every byte. At the end, or on an error, one more 0DH goes to the printer. The file is not closed.

5B00H - ATTRIB (Command 2)

ATTRIB filespec (INV,ACC=password,UPD=password,PROT=level) changes a file's directory entry. The file must open at access level 0, with its owner password, or the command stops with error 37H, which SYS4/SYS shows as UNKNOWN ERROR CODE. Only the first letter of each option is looked at (I, A, U or P). INV sets bit 3 of the attribute byte; nothing here clears it. ACC puts the hash of its password at entry plus 12H (the user password), UPD at entry plus 10H (the owner password). PROT takes the first two letters of its level word, looks them up in the table at 5C61H (EX, RE, WR, NA, KI, FU, with REN for RENAME) and puts the level 6, 5, 4, 2, 1 or 0 into bits 0-2. The attribute byte's bits 0-2 are cleared on every ATTRIB, so a command without PROT leaves the file at level 0. Password values are copied by SYS2/SYS's field routine, which takes only letters and digits starting with a letter.

5BD1H - Read an Option's Value

Register Pair HL = the first letter of the option. Moves along the option's name to an equals sign. When ENTER, a closing parenthesis or a comma comes first it returns the Z FLAG with Register Pair HL on that character. Otherwise it fills 5155H-515CH with spaces, copies up to eight letters and digits of the value there through SYS2/SYS's 5081H (the first must be a letter) and returns the NZ FLAG with Register Pair HL on the character that ended the value.

5BF7H - Change the Directory Entry

Reached from 5B8EH at the closing parenthesis. Reads the directory sector holding the file's entry (drive and locator from the open FCB), rebuilds the attribute byte from the options, puts in the password hashes asked for, and writes the sector back.

5C61H - Access Level Table

Seven two-letter entries read by 5B5DH. The entry found gives the level 6 for the first entry down to 0 for the last. The fourth entry, two tilde characters, stands for level 3; the value is copied by SYS2/SYS's 5081H, which takes only letters and digits, so it can never match.

5C6FH - DIR (Command 8)

DIR [:d] (A,I,S) clears the screen and shows the diskette's name and date from its granule allocation table, then copies directory sectors 2-9 to 6100H-68FFH and lists the files three to a line: name/extension, then S for a system file, I for an invisible file and P for a file with a password. The list goes through the copy in the order entry 0 of every sector, then entry 1 of every sector, and so on. Unused entries and continuation entries are skipped; system files are shown only with S and invisible files only with I. With A each file gets its own line with its record length, its record count and the granules it uses. Every 12 lines DIR waits for a key; BREAK ends the list. The copy is cleared to zeros before DIR leaves.

5DE1H - Clear the Directory Copy

Fills 6100H-68FFH, the copy of directory sectors 2-9, with zeros.

5DF1H - DIR (A): Size of a File

Register Pair HL = the entry in the copy. Shows LRL= the record length (256 for 00H), EOF= the three bytes ending record number high, low and end-of-file byte (ERN times 256 plus the end-of-file byte) divided by the record length, and SIZE= the granules of all the file's extents. The division at 60A7H loses the top bit of its remainder when the record length is above 128, so EOF= can be wrong for record lengths 129-255. Returns Register B = 01H.

5E3EH - Count a File's Granules

Register Pair HL = an entry in the copy at 6100H-68FFH. Adds up the granules of the extents at entry plus 16H: each extent is a track byte and a granule byte whose bits 0-4 are the granules minus 1. A track byte of FFH ends the list; FEH continues it in the entry whose locator is the next byte, found in the copy. Returns Register Pair DE = the granules.