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

SYS11/SYS

Other Navigation

LDOS 5.3.1 SYS11/SYS Disassembly - Job Control Language Execution (Model I)

SYS11/SYS runs Job Control Language jobs. The DO command in SYS6/SYS compiles a JCL source file, resolving its compile-time directives such as IF, ELSE, SET and INCLUDE, and then issues RST 28H with request code 9DH at 5301H to start the compiled job. That request loads this overlay, which sees the job through to its end.

The central idea is a small one. A job is a list of commands that the operator would otherwise type, so the overlay makes the job file be the keyboard. It saves the address of the real *KI driver out of the resident keyboard device control block KIDCB$ at 4016H into KIJCL$ at 43BEH, and writes in its place the two-instruction routine at 4E5AH, which returns the next byte of the job file. The ordinary ROM line-input routine at 0040H then collects a line of the job into the command buffer INBUF$ at 4318H without any idea that it is not reading the keyboard, and the line is handed to the command interpreter through @CMNDI. Everything else follows from that.

Because a job runs commands and programs that themselves finish or fail, the overlay also takes over the exit vectors. Six bytes are copied over @EXIT, @ABORT and @DVRHK at 402DH so that a program leaving normally re-enters the overlay with request code 0ADH and a program aborting re-enters it with 0BDH. In the first case the next line of the job is read and executed; in the second the job ends with Job aborted. When the job file runs out the run ends with Job done. The original six bytes are put back from the image at 4065H when the job ends, and the stack pointer is reset to 41E0H at every step rather than unwound, because the commands a job runs may leave it anywhere.

Once the first line has been read the keyboard driver is changed again, this time to the resident @DOKEY vector at 44BEH. That vector issues request code 0CDH, which brings every keyboard request back into this overlay at 4ECFH to be judged individually. The test is an unusually direct one. The supervisor dispatcher discards the return address that the RST 28H itself pushed, so the stack above this overlay still carries the working state of whatever asked for the keystroke; the overlay reaches fourteen bytes down it looking for the value 05E3H, which is the instruction after the CALL 0049H in the ROM line-input routine KEYIN and therefore the return address KEYIN leaves behind while it waits for a key. A request bearing that address is part of collecting a command line and is answered from the job file; anything else belongs to a program reading the keyboard for its own purposes and is chained straight through to the real driver parked in KIJCL$. Ten bytes down lies KEYIN's own pair of buffer counts, the original size it set at 05DFH and the number of bytes still free, and their being equal is what tells the overlay it is at the start of a fresh line rather than in the middle of one. A character fetched from the job file that turns out to begin a line with a slash is not passed to the program at all but taken away and processed as a directive.

Ten run-time directives are recognised, held in a keyword table of seven-byte entries at 51B5H: five characters of name, padded with a space where the name is shorter, followed by the address of the routine that carries the directive out. They are ABORT, ALERT, DELAY, EXIT, FLASH, KEYIN, PAUSE, STOP, WAIT and INPUT. The lookup returns the handler address in Register Pair DE and the caller reaches it by pushing it and executing a return, leaving the address of the job line still on the stack so that a directive which takes an operand can find its text.

KEYIN is what gives JCL its branching. It displays the rest of the line as a prompt, reads and echoes a single key, plants that key in the operand of the comparison at 4FC8H, and then reads forward through the job file looking for a line that begins with two slashes and that key, or with three slashes which matches anything. The job resumes at the line after the label. INPUT is the other way round: it hands the keyboard back to the operator for one reply by changing the request code the @DOKEY vector issues from 0CDH to 0DDH, which routes requests to the passthrough at 50C8H until a terminating character comes back and the code is set to 0CDH again.

ALERT is the most elaborate of the timing directives. It reads a sequence of numbers and plays them as alternating tones and silences, flipping a self-modified operand at 5006H between 00H and 0FFH so that the first number is sounded, the second is a pause, the third is sounded and so on; a group written in brackets is repeated by remembering the position of the opening bracket. The tones themselves come from an eight-entry table at 5187H and are produced by swinging bit 0 of the cassette port at FFH, with interrupts disabled across the loop so that a timer tick cannot stretch a half-cycle and spoil the pitch.

The overlay occupies 4E00H through 5180H and 5187H through 51FBH. The six bytes between, 5181H to 5186H, are deliberately not present in the file: they are the scratch area into which the directive name and the fields of a WAIT time are collected, and being uninitialised there is nothing to load.

Memory Map

Address Range	Purpose
4BC9H-4BCAH 2 bytes	Load block deposited into the resident padding area below the RST 28H dispatcher. SYS11/SYS writes the bytes FCH and 03H there.
4E00H-4E1DH 30 bytes	Overlay entry and dispatch across the five request codes 9DH, 0ADH, 0BDH, 0CDH and 0DDH.
4E1EH-4E59H 60 bytes	Start a job: divert the keyboard, arm the exit vectors, read and execute the first line.
4E5AH-4E5FH 6 bytes	The job file acting as the keyboard driver.
4E60H-4E81H 34 bytes	Resume the job after a program exits, or finish when the job file is exhausted.
4E82H-4E89H 8 bytes	Read one job line into the command buffer through the ROM line-input routine.
4E8AH-4EA2H 25 bytes	Abort entry, message dispatch, and the BREAK and interrupt poll the waiting directives use.
4EA3H-4ECEH 44 bytes	End the job, display the closing message and restore every resident vector the job diverted.
4ECFH-4F09H 59 bytes	Keyboard request interception for request code 0CDH.
4F0AH-4F64H 91 bytes	Directive line collection, label recognition, name extraction and dispatch.
4F65H-50B6H 338 bytes	The directive handlers: STOP, DELAY, PAUSE, KEYIN, ALERT, FLASH and WAIT, with the tone and delay primitives.
50B7H-50DBH 37 bytes	The INPUT directive and the keyboard passthrough for request code 0DDH.
50DCH-5180H 165 bytes	Name extraction, the alphanumeric test, the keyword table lookup and the decimal number reader.
5181H-5186H 6 bytes	Scratch area. Not present in the file; used for the extracted directive name and the three fields of a WAIT time.
5187H-5196H 16 bytes	Tone table. Eight two-byte entries of half-period and cycle count.
5197H-51B4H 30 bytes	Message text for the three ways a job can end.
51B5H-51FBH 71 bytes	Directive keyword table. Ten seven-byte entries and a zero terminator.

Request Codes Serviced

Code	Masks to	Entry	Purpose
9DH	10H	4E1EH	Start a compiled job. Issued by the DO command in SYS6/SYS at 5301H.
0ADH	20H	4E60H	A program run by the job has exited normally. Written over the @EXIT vector at 402DH when the job starts.
0BDH	30H	4E8AH	A program run by the job has aborted. Written over the @ABORT vector at 4030H when the job starts.
0CDH	40H	4ECFH	@DOKEY. A keyboard request while the job is running; the job decides whether to answer it.
0DDH	50H	50C8H	@DOKEY while an INPUT directive is being answered; the request goes straight to the operator.

Run-Time Directives

Directive	Entry	Handler	Action
ABORT	51B5H	4E8AH	End the job at once, reporting Job aborted and transferring to @ABORT.
ALERT	51BCH	4FD6H	Play a sequence of numbers as alternating tones and silences, with bracketed groups repeated.
DELAY	51C3H	4F72H	Pause for a decimal count of delay units.
EXIT	51CAH	4EA3H	End the job normally, reporting Job done and transferring to @EXIT.
FLASH	51D1H	505DH	Show the rest of the line a given number of times, blanking it between each.
KEYIN	51D8H	4F89H	Prompt, read one key, and resume the job at the label matching that key.
PAUSE	51DFH	4F7DH	Show the rest of the line and wait until the job is told to carry on.
STOP	51E6H	4F65H	End the job but leave the running command to be finished from the keyboard.
WAIT	51EDH	5088H	Wait until the real-time clock reaches a given time.
INPUT	51F4H	50B7H	Prompt and let the operator type the answer from the keyboard.

Variables and Self-Modified Operands

Address Range	Purpose
4FC9H 1 byte	Operand of the CP nn at 4FC8H. Written at 4F9CH with the key the operator pressed, so the label search matches it, and cleared at 4FCCH once the label has been found.
4FF7H-4FF8H 2 bytes	Operand of the LD HL,nnnn at 4FF6H. Written at 4FF1H with the position of an opening bracket in an ALERT operand, so the closing bracket can jump back to it.
5006H 1 byte	Operand of the LD A,nn at 5005H. Alternates between 00H and 0FFH so that successive numbers in an ALERT operand produce a tone and then a silence in turn; reset at 4FD7H.
50C9H-50CAH 2 bytes	Operand of the CALL nnnn at 50C8H. Written at 50BEH with the real keyboard driver address taken from KIJCL$ so that an INPUT directive reaches the operator.
5113H 1 byte	Operand of the LD A,nn at 5112H. Set non-zero at 50DFH and cleared at 5105H as soon as a character is copied, so it reports whether the name extraction found anything.
44BFH 1 byte	Resident. The operand of the LD A,nn at the @DOKEY vector 44BEH, which is the request code that vector issues. Changed to 0DDH at 50C3H while an INPUT directive is answered and back to 0CDH at 50D7H.
43BEH-43BFH 2 bytes	Resident KIJCL$. Holds the real *KI driver address while a job has the keyboard diverted. Written at 4E30H and read back at 4EB7H and 50BBH.
5181H-5186H 6 bytes	Scratch area above the code, not present in the file. Holds the extracted directive name and the three fields of a WAIT time.

Cross-References

SYS11/SYS is started by the DO command in SYS6/SYS, which compiles the JCL source and issues request code 9DH; the two @EXIT launch stubs 0ADH and 0BDH that DO writes over the exit vectors are answered here. It leans heavily on SYS0/SYS: the keyboard device control block KIDCB$ at 4015H and its driver word at 4016H, the @DOKEY vector at 44BEH and its request-code operand at 44BFH, KIJCL$ at 43BEH, JFCB$ at 4358H, the flag bytes SFLAG$ at 430FH and KFLAG$ at 4423H, the command buffer INBUF$ at 4318H, the clock workspace at 4041H through 4043H, and the vectors @CMNDI 4405H, @ERROR 4409H, @CKEOF 444BH, @RREAD 4454H, @DSPLY 4467H, @LOGOT 447BH and @LOGER 447EH. It calls the Model I ROM directly for character and line input and output at 0013H, 0023H, 0033H, 0040H, 0049H and 0060H.

If SYS6/SYS has been purged there is no way to launch a job, so keeping SYS11/SYS serves no purpose; the reverse is also true, in that a job which runs no directives still needs this overlay to feed its lines to the command interpreter.

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. SYS11/SYS writes FCH and 03H here, in the same way SYS10/SYS writes 73H and 01H and SYS8/SYS writes 96H and 02H.

4E00H - Overlay Entry and Request Dispatch

SYS11/SYS answers five supervisor requests, all of them parts of running a Job Control Language job: 9DH starts a job, 0ADH and 0BDH report that a program under the job has exited or aborted, and 0CDH and 0DDH are the two forms of the keyboard request through which the job feeds characters to the programs it runs. Every entry begins by clearing the interrupt-request bit in KFLAG$.

4E1EH - Start a Job

Starting a job saves the real keyboard driver, diverts the keyboard to the job file, arms the exit vectors so that a program finishing or failing comes back here, reads the first line of the job into the command buffer and hands it to the command interpreter. The stack is reset to the resident base at every step rather than unwound, because the commands the job runs may leave it anywhere.

4E5AH - The Job File as a Keyboard Driver

Two instructions that make the whole design work. Installed as the *KI driver, this routine returns the next byte of the compiled job file instead of a keystroke, so the ordinary ROM line-input routine collects a line of the job exactly as though the operator had typed it.

4E60H - Resume After a Program Exits

Request code 0ADH arrives when a program run by the job finishes normally. Unless BREAK has been pressed, the next line of the job is read and executed; when the job file is exhausted the run ends with Job done.

4E82H - Read One Job Line into the Command Buffer

The job line is collected by the ordinary ROM line-input routine at 0040H. Because the keyboard driver has been diverted to the job file, that routine gathers a line of the job into INBUF$ without knowing it is not reading the keyboard.

4E8AH - Abort the Job

Request code 0BDH arrives when a program run by the job has aborted. The job ends with Job aborted and control passes to the resident @ABORT vector. This is also where the BREAK check and the malformed-job path arrive.

4E92H - Break and Interrupt Poll

Every directive that waits calls this routine. It abandons the whole job if the operator has pressed BREAK, and otherwise reports in the Z FLAG whether the directive that is running should be cut short.

4EA3H - End the Job and Restore the Resident Vectors

The common ending. The message is displayed, the in-effect flag is cleared, the job file control block is closed, the real keyboard driver is put back and the three exit vectors are restored from their saved image. The destination vector is pushed before the restore so that the closing RET transfers to either @EXIT or @ABORT.

4ECFH - Keyboard Request Interception

Request code 0CDH is what the resident @DOKEY vector issues once a job is running. Because the supervisor dispatcher throws away the return address the RST 28H pushed, this routine can reach down the stack into the working state of whatever asked for the keystroke. It looks for the return address 05E3H, which the ROM line-input routine KEYIN leaves there while it waits for a key, and answers only those requests from the job file; anything else is chained straight to the real keyboard driver. It then reads KEYIN's own buffer counts to tell the start of a fresh line from the middle of one, and a line beginning with a slash is taken away to be processed as a directive rather than handed to the program.

4F0AH - Directive Line Processing and Dispatch

A line beginning with a slash is collected into the command buffer and examined. Two slashes followed by a third slash or by a digit make a label, which is stepped over. Otherwise the directive name is extracted, looked up in the keyword table at 51B5H, and the handler address the lookup returns is pushed and returned to, which transfers control to it with the line still addressable on the stack.

4F65H - The STOP Directive

STOP dismantles the job but does not abandon the command that is running. The keyboard is handed back to the operator, who finishes the command by hand.

4F72H - The DELAY Directive

DELAY reads a decimal count from the line and pauses for that many delay units, each of which honours the Fast and Slow setting recorded in SFLAG$.

4F7DH - The PAUSE Directive

PAUSE displays the rest of the line and waits. The wait ends when the interrupt-request bit in KFLAG$ is set, and pressing BREAK abandons the job entirely.

4F89H - The KEYIN Directive and the Label Search

KEYIN is how a job asks a question. The rest of the line is displayed as a prompt, one key is read and echoed, and the job file is then scanned forward for a line beginning with two slashes and that key, or with three slashes which matches anything. The job resumes at the line after the label, which is what gives Job Control Language its branching.

4FD6H - The ALERT Directive

ALERT plays a sequence of numbers as alternating tones and silences, so that the first number is sounded, the second is a pause, the third is sounded and so on. A group written in brackets is repeated: the position of the opening bracket is remembered in a self-modified operand and the closing bracket jumps back to it.

501FH - Sound One Tone

The number selects one of the eight entries of the tone table at 5187H, whose first byte sets the pitch and whose second sets the length. The note is produced by swinging bit 0 of the cassette port at FFH, which is how the Model I makes sound, and interrupts are disabled across the loop so that a timer tick cannot stretch a half-cycle and spoil the pitch.

5044H - Silence and the Delay Unit

The counterpart of the tone routine waits without sounding anything. Both it and the DELAY directive measure time in units produced by the routine at 504CH, which doubles the pause when SFLAG$ shows the machine is running fast so that a job keeps roughly the same timing on either setting.

505DH - The FLASH Directive

FLASH shows the rest of the line, leaves it up for a fixed count of polling passes, then erases it with the video control codes 1BH and 1EH and pauses before showing it again, repeating the number of times the directive asks for.

5088H - The WAIT Directive

WAIT collects a time written as hours, minutes and seconds into the scratch area and then polls the resident clock workspace until it matches. The clock fields run downwards in memory from the hours at 4043H, which is why the comparison steps its pointer backwards.

50B7H - The INPUT Directive and the Keyboard Passthrough

INPUT hands the keyboard back to the operator for one reply. It plants the real driver address in the call at 50C8H and changes the request code the resident @DOKEY vector issues from 0CDH to 0DDH, which routes every following keyboard request straight to the operator until a terminating character comes back, at which point the code is set to 0CDH again and the job resumes supplying the keyboard.

50DCH - Extract a Name and Test for Alphanumeric

The directive name is copied out of the job line into the scratch area, folded to upper case so it may be written either way, and closed with an 03H terminator. A self-modified operand records whether any characters were copied at all, which is how an empty name is reported as a malformed job.

5125H - Look Up a Directive Name

The extracted name is searched for in the seven-byte entries of the keyword table. A shorter name matches an entry padded with spaces, and a match returns the two-byte handler address that follows the name in the entry.

5167H - Read a Decimal Number

Digits are accumulated by multiplying the running total by ten through repeated additions of Register Pair HL to itself. The routine returns the value in Register Pair BC and leaves in Register A the character that stopped it, less 30H, which is how the WAIT directive recognises the colons between the fields of a time.

5181H - Scratch Area (Not Present in the File)

Six bytes that the load module deliberately steps over: the file loads 4E00H through 5180H and resumes at 5187H. The area needs no initial contents because it is only ever written before it is read, holding the directive name that 50DCH extracts and, for the WAIT directive, the three fields of the time collected at 509DH.

5187H - Tone Table

Eight two-byte entries, indexed by the low three bits of the number the ALERT directive is given. The first byte of an entry is the half-period held by the delay loops at 5035H and 503BH and so sets the pitch; the second is the number of complete cycles sounded and so sets the length. The two run in opposite directions through the table, so the higher notes are sounded for more cycles and every entry lasts about the same time.

5197H - Message Text

The three ways a job can end, written as two overlapping strings and one separate one. The malformed-job message at 5197H runs straight into the abort message at 51A0H, so the shorter text is simply the tail of the longer and the two share their carriage return.

51B5H - Directive Keyword Table

Ten seven-byte entries followed by a zero byte, searched by the lookup at 5125H. Each entry is five characters of directive name, padded with a space where the name is shorter, followed by the two-byte address of the routine that carries the directive out. The entries are in alphabetical order except for INPUT, which sits last and was evidently added after the rest.