TRS-80 DOS - VTOS 4.0.2 for the Model I - SYS7/SYS Disassembled

SYS7/SYS

Other Navigation

VTOS 4.0.2 SYS7/SYS Disassembly - The Execution Phase of CHAIN (Model I)

SYS7/SYS is the system overlay that runs a file of commands. CHAIN (SYS6/SYS member 12) compiles the file the user names into SYSTEM/JCL, opens it in the control block 4358H with SYS0/SYS's sector buffer 4200H and issues request 99H; the request handler (4C31H) loads SYS7/SYS at 4E00H (directory entry code 21H) and calls it with the request code in Register A. SYS7/SYS then feeds the lines of the file to the system as if they were typed: it puts itself in the way of the two exits every command ends through and of the keyboard driver, so that each line the ROM's line input asks for comes from the file. Lines that start with two slashes are directives of the execution phase, carried out by SYS7/SYS itself. The manual: "This overlay is required during program CHAINing operations."

The file starts with a record of type 05H (the name SYS7), a record of type 1FH holding the copyright notice of Randolph Cook (1980) and five load blocks that fill 4E00H-51A9H and 51B2H-51FAH, 1011 bytes; 51AAH-51B1H, the word buffer, is not loaded. The last record gives the transfer address 4E00H; one byte 03H follows it, which the loader never reads. The file carries no patch.

The Functions

How a Line Reaches the System

The Directive Lines

Points to Note

4E00H - Entry: The Four Functions

SYS7/SYS is loaded at 4E00H by the request handler of SYS0/SYS (4C31H) for a request code whose bits 3-0 are 9 (directory entry code 21H) and called at 4E00H with Register A = the request code (fetched from 430EH at 4C45H). Bits 6-4 choose the function: 99H (1) starts the execution phase of CHAIN (SYS6/SYS member 12 issues it at its 52BEH); A9H (2) and B9H (3) are the requests that SYS7/SYS itself writes into the exits 402DH and 4030H while chaining; C9H (4) comes from SYS0/SYS's 44BEH, which SYS7/SYS makes the keyboard driver. Any other code returns at once with the NZ FLAG set.

4E13H - Function 1 (99H): Start the Execution Phase

CHAIN has opened the file of commands (normally SYSTEM/JCL) in the control block 4358H with SYS0/SYS's sector buffer 4200H. 430FH bit 5 is set; when it was clear before, the keyboard driver of the KI device control block (4016H-4017H) is saved at 43BEH and the two exits are pointed at SYS7/SYS: 402DH becomes LD A,A9H / RST 28H and 4030H LD A,B9H / RST 28H. The first line is then read through the driver 4E52H and handed to 4405H to be executed, and from then on the keyboard driver is 44BEH. A CHAIN met while chaining (bit 5 already set) keeps the saved driver and the exits.

4E52H - The Driver of the First Line

The keyboard driver while 4E45H reads the first line: every key is the next byte of the file. Reached from the ROM's 03C2H through the KI device control block 4015H. The first line is not checked for a slash, a 00H byte or the end of the file.

4E58H - Function 2 (A9H): The Next Command Line

A command has ended through 402DH (LD A,A9H / RST 28H while chaining). As at the command level, the BREAK vector is armed when DEBUG is on. BREAK held down (unless 430FH bit 4 says BREAK is ignored) ends the chaining with MANUAL CHAINING ABORT!; the end of the file ends it with CHAINING COMPLETED. Otherwise the ROM's line input reads the next line, whose keys come from 4EC8H, and 4405H executes it.

4E8CH - Function 3 (B9H) and //ABORT: Chaining Aborted

A command ended through the abort exit 4030H (LD A,B9H / RST 28H while chaining), for instance after an error message of 4409H, or the file has a line //ABORT. 4E91H is //EXIT and the end of the file; 4E94H shows the text at Register Pair HL on a new line, logs it, ends the chaining and goes to VTOS READY.

4EA2H - End the Chaining

Clears 430FH bit 5, stores 00H in byte +00H of the control block 4358H (bit 7 clear: not open; the file is only read, so nothing is written), puts the keyboard driver saved at 43BEH back into 4016H-4017H and writes the original exits: 402DH LD A,93H / RST 28H (VTOS READY) and 4030H LD A,A3H / RST 28H (the abort exit). Interrupts are left disabled: no EI follows the DI. 4EB8H, the end of it, writes the exits from Register Pairs HL and DE.

4EC8H - Function 4 (C9H): The Keyboard Driver While Chaining

44BEH (LD A,C9H / RST 28H) is the driver of the KI device control block while chaining, so every key request of the ROM (0013H through 03C2H, from 002BH and 0049H) comes here. On entry the stack holds 4C4BH (the request handler's return), 03DDH (the return into the ROM's 03C2H), the words 03C2H pushed (Register Pairs DE, IX and HL), the Register Pair BC that 0013H pushed, the return address of the CALL to 0013H or 002BH, and the word above it. Only a request made by the ROM's line input, whose CALL 0049H at 05E0H leaves 05E3H at the stack's 0EH, is served from the file; every other key request (INKEY$, a program's own key wait, the //KEYIN answer) goes to the keyboard driver saved at 43BEH.

4EE0H - The Next Byte for the Line Input

Register B = the room left, Register C = the most characters of the line. At the end of the file the chaining ends with CHAINING COMPLETED. The end of the file is tested at every key request, so a last line cut off by the end of the file is dropped. Inside a line the next byte of the file is the key. At the start of a line (Register B = Register C) the file is first set back to the sector of its buffer, since 4200H, the buffer of 4358H, is also where SYS0/SYS reads the overlays (a line whose 0DH is the last byte of a sector makes this replay that sector, 4EEFH); then the first byte is read: 00H ends the chaining, a slash starts a directive line (4F02H), anything else is the key. 4F50H comes back here after a directive line.

4F02H - A Line Starting With a Slash

The whole line is read into the command line buffer 4318H, up to and including its 0DH; nothing limits its length. A line with one slash is dropped. Three slashes end every block of //KEYIN (4FBDH := 00H). Two slashes and a digit are a block label: 4FBCH compares 39H less the digit with 4FBDH. Two slashes and anything else: the line is written to the job log, spaces are passed over, and the word that follows (6 letters or digits at most, made upper case) is looked up in the table of directives at 50B6H. A directive is entered with Register Pair HL past the word and the character after it (on that character when it is 03H, 0DH or an opening parenthesis), and the stack holding 4318H, then Register Pair DE (4358H), then Register Pair BC. A line whose word is not in the table is only logged.

4F4DH - The Next Line

Every directive and every dropped line ends here: the three words saved at 4F03H-4F08H are taken off the stack and the next line is begun at 4EE0H, still with Register B = Register C, so the line input gets the first character of the next line that is not a directive.

4F52H - Invalid JCL

A //WAIT time without its colons, or a closing parenthesis of //ALERT with no opening one before it, ends the chaining here.

4F58H - //STOP

Ends the chaining with no message and gives the line input that is waiting a key from the keyboard: the rest of the line, and the commands after it, are typed by the user.

4F64H - //DELAY n

Waits n times 96 ms, about 0.1 second (n taken modulo 256; 0, no number, or a second space before the number gives 256, about 24.6 seconds). No key ends the wait, although the manual says ENTER or BREAK stops it.

4F6FH - //PAUSE

Shows the whole line, //PAUSE included, and waits while neither ENTER nor BREAK is held down.

4F7DH - //KEYIN

Shows the whole line, //KEYIN included, waits for a key from the keyboard and shows it; the key is stored in 4FBDH, and the lines of the file are read and passed over up to a line of two slashes and that key (the block of the answer) or a line of three slashes. The key is read with the ROM's 0049H, which 4EC8H sends to the keyboard.

4FC0H - A Label Line Taken

Register A = 00H (three slashes), the key (a match in the search of //KEYIN) or 39H less the digit of a label that matched 4FBDH at 4F23H. It is stored in 4FBDH, the line is written to the job log and the lines after it are executed.

4FCBH - //ALERT

//ALERT n1,n2,... or //ALERT (n1,n2,...): each number is a count of units of about 0.1 second, sound and silence by turns (the first number sound, the next silence, and so on; the turn is kept in 4FF7H and goes on from one //ALERT line to the next when no command line runs between them, since each command loads SYS1/SYS over SYS7/SYS). Spaces and commas are passed over; an opening parenthesis is remembered at 4FE8H and the closing one goes back to it, so the list in parentheses repeats until ENTER or BREAK is held down; 0DH ends the line. ENTER or BREAK ends the directive at once. The sound is made by switching the cassette select latch 37E4H on and off, a square wave of about 59 Hz.

5014H - One Unit of Sound

Six cycles of the cassette select latch (502FH), about 0.1 second.

501EH - Wait About 0.1 Second

The ROM's delay 0060H with Register Pair BC = 199BH (6555 passes of 26 clock cycles, about 96 ms at the Model I's 1.77 MHz), made twice when 430FH bit 3 says the clock runs fast (SYSTEM (FAST)). //DELAY, //FLASH and the silence of //ALERT use it.

502FH - One Cycle of the Latch

Writes 01H and then 00H to 37E4H, the cassette select latch of the expansion interface (0 cassette 1, 1 cassette 2), each followed by a wait of 0240H passes of 26 clock cycles (about 8.4 ms), made twice with the fast clock.

504AH - //FLASH n

Flashes the screen n times (n modulo 256; 0, no number, or a second space before the number gives 256), each flash about 0.3 second; ENTER or BREAK held down ends it.

505EH - One Flash

A wait, every byte of the screen changed (5064H), a wait, every byte changed back (5064H run a second time), a wait: three waits of about 0.1 second.

5076H - //WAIT hh:mm:ss

Shows the whole line and waits until the clock (4043H hours, 4042H minutes, 4041H seconds) shows exactly the time given. The three numbers must be separated by colons, and the first must follow WAIT after exactly one character that is not a letter or digit (a space, a comma, a colon); otherwise INVALID JCL ends the chaining (with no such character the word is WAIT and the digits, which is no directive, and the line is only logged). No key ends the wait, and an hour above 23 or a minute or second above 59 waits for ever.

50B6H - The Table of Directives

Nine entries of 8 bytes, a name of 6 characters padded with spaces and the address of its routine, in alphabetical order, ended by 00H; searched by 5143H for the word after two slashes.

50FFH - Copy a Word

Register Pair HL = the text, Register Pair DE = the buffer, Register B = the most characters (6 from 4F39H). Letters and digits are copied, small letters made capital; letters and digits past the most are passed over. 03H, 0DH and an opening parenthesis end the word and are not passed over; any other character ends it and is passed over. 03H is stored after the word. Returns Register A = the character that ended the word and the NZ FLAG when no character was stored.

5143H - Search the Table of Directives

Register Pair DE = the word (ended by 03H), Register Pair BC = the table. An entry matches when its first character equals the word's and its next 5 characters are equal too, or a space stands where the word has ended (03H or 0DH, or a character other than a letter or digit). Found: Register Pair DE = the entry's address word, Register A = 00H and the Z FLAG. Not found: Register A = 01H and the NZ FLAG. Register Pair HL is kept.

5190H - Read a Decimal Number

Register Pair HL = the text. Digits are read into Register Pair BC (modulo 65536) up to the first character that is not a digit, where Register Pair HL stops; with no digit Register Pair BC = 0000H. Returns the CARRY FLAG for a character below 0, the NC FLAG for one above 9.

51AAH - The Word Buffer

Not in the file: the load blocks leave 51AAH-51B1H out.

51B2H - Messages

The four texts, each shown by 447BH on a new line and written to the job log. 51D2H is the second part of the text at 51C5H.