DOSPLUS 3.5 for the Model III - JCL/CMD Disassembled

JCL/CMD

Other Navigation

DOSPLUS 3.5 JCL/CMD Disassembly - The Job Control Language (Model III)

JCL/CMD installs DOSPLUS's Job Control Language, run from the DOS command level as JCL (PROC=n,QUEUE=n); its heading reads JCL - DOSPLUS Job control language - 3.50. It is a load module of 14 blocks, 2960 bytes, at 5200H-5EBEH with the transfer address 5200H, after the two comment records (the name JCL and the copyright notice); the last block is the single byte at 5EBEH. JCL/CMD is on the Model III master only. Once installed, procedures are run with EX filespec values (default extension JCL).

The file has two parts. 5200H-5537H installs (5200H); 5538H-603FH, 0B08H bytes, is the resident part, which is moved up to end at the old HMEM$. The words of the resident part that hold its own addresses are listed in the file JCL/RLD (768 bytes: a count of 0140H entries, four bytes not used, then one address per entry, 43 of them in the installing part, which the installer passes over); the installer adds the distance of the move to each (52CBH). The addresses on this page are those of the file.

The Installation

PARAM@ stores the values of PROC and QUEUE straight into the operands at 527EH and 5266H (as loaded 0300H and 0100H); a value of 1100H or more is Invalid data provided. Below the resident part come the queue (QUEUE bytes) and the procedure area (PROC bytes); HMEM$ is set to the byte below them all, and must stay above 5BFFH, the high overlays, else No memory space available (525EH). The keyboard (KI) and the display (DO) must not be under FORCE or JOIN. Their drivers' addresses are kept at 5CF9H and 5CFCH and the devices given JCL's own drivers (5D31H, 5D7DH); the three bytes of CMNDI@ are kept at 5D08H and CMNDI@ becomes JP to the resident part (5538H). JCL installed at nnnnH shows the new address. JCL/RLD is read through the ROM's 0013H and is not closed.

The Parts of JCL/CMD

How JCL Works

A command line typed at the DOS command level reaches CMNDI@ with EXIT@ (402DH) as its return address; only such a line is tested for EX, all others go on to CMNDI@ as it was (5538H). EX copies the rest of the line to 5EBFH, points EXIT@, ABORT@ and ERROR@ into JCL, opens the procedure, sets the options to DSP, QUEUE and CHR and runs it as level 1 (555CH). Each level has a frame of 32 bytes in the procedure area, then its text (read to the end of the file, with a 0DH added) and then its variables, 18 bytes each (55B0H, 5B38H). The first line must start with the procedure's name; its other words are variables that take the values after the name, and $LEVEL is the level's digit.

Each line in turn is copied to 5EBFH, a line number from BASIC and the leading spaces passed over, and each $name is replaced by its value, from the last one back to the first; a $ at the start of the line is kept, as it names the variable of an assignment (56BDH). A line is a remark (a period), a label (a minus sign), an assignment ($name = value) or a command after a slash, looked up in the table at 57AAH (5755H). /TYPE, /PRINT and /DEBUG are DSPLY@, PRINT@ and DEBUG@ themselves. /DOS runs its line through CMNDI@ with EXIT@, ABORT@ and ERROR@ caught, and puts the error code into $ERR as two decimal digits (58AEH, 5D0BH). /IF makes the command after the condition the next line (58E2H). /RUN opens another procedure as the next level and /EXIT ends a level (5A69H, 5A24H).

The queue is a ring below the resident part (5C17H, 5C3EH). JCL's keyboard driver gives its bytes to the programs while QUEUE is on (5D31H): with QBYTE off only the requests made through the ROM's 0049H, which the line input uses, are served from it. The byte FFH that /QUEUE puts in for /JUMP stops the program that reads it and runs the procedure from the label after it, until /RESUME gives the program its character or /CANCEL ends the /DOS that ran it (5A86H, 5AD3H, 5AF5H); FEH, /VOFF, keeps the next line read from the queue off the screen. JCL's display driver puts what is shown into the queue with DQ on and shows nothing with DSP off (5D7DH). An error of JCL empties the queue, shows its message between the signs %% and ends EX (5DA7H).

Differences from the Manual

QBYTE is off when EX starts (the options are 25H): only the line input is served from the queue until /OPTION QBYTE/Y. PROC and QUEUE take values up to 10FFH, and there is no smallest value. The label of /GOTO must start with the minus sign, so the manual's /GOTO ERROR and /GOTO LOOP are Bad -LABEL (599EH). /IF compares the lengths of the two values first, the shorter being the smaller, and only values of the same length character by character. An empty line is Bad /COMMAND, and the last line of the file is run only if it ends with a carriage return. $LEVEL has no limit of 9 levels: after 9 its digit is a colon, and the procedure area is the only limit. With CHR off only the characters 20H-2FH and 3AH-3FH from the queue become spaces. During EX an error of a DOS command run by /DOS is not shown, only put into $ERR (ABORT@ gives 63); an EX given to /DOS goes to the DOS's own CMNDI@, not to JCL. /QLOAD stops silently at any read error.

Three findings stand from the bytes. LE holds when the first value is greater (5954H tests for GT), and GT jumps to the command with Register Pair AF still on the stack, so the RET at 5972H goes to an address made of Register A and the flags (5942H). /EXIT looks for $ERR with its dollar sign (582AH), which no variable has, so it makes an empty variable and copies the two bytes after its length into the value of $ERR that /RUN gives the calling level (5A24H, 5A7CH). /DOS counts 5E97H up but its DEC (HL) works on the command's text, so 5E97H is never counted down, and /CANCEL is refused only before the first /DOS of an EX (58C6H, 5AF5H).

5200H - JCL

JCL/CMD's transfer address, entered from the DOS command level as JCL (PROC=n,QUEUE=n). This part installs the JCL system: it reads the relocation file JCL/RLD, moves the resident part (5538H-603FH, 0B08H bytes) up to end at HMEM$, below it the queue (QUEUE bytes, 256 as loaded) and the procedure area (PROC bytes, 768 as loaded), lowers HMEM$ below them all, hooks the keyboard (KI) and display (DO) devices and points CMNDI@ (4405H) at the resident part, which then takes the command EX.

5334H - Displaying a Word

Displays Register Pair HL as four hexadecimal digits followed by H, through 5341H and the ROM's 0033H.

5341H - Displaying a Byte

Displays Register A as two hexadecimal digits: the high four bits first, then the low four by falling into 534AH.

5355H - Reading a Byte of JCL/RLD

Reads the next byte of the relocation file through the ROM's 0013H with the control block at 5418H; an error or the end of the file is posted.

5361H - The Errors of the Installation

5361H the message Can't install JCL under FORCE/JOIN and ABORT@; 536AH the error 2EH, Invalid parameter; 536DH, inside the LD BC at 536CH, 2DH, Invalid data provided; 5370H, inside the LD BC at 536FH, 21H, No memory space available; 5372H any error code in Register A. Each is posted with bit 6 set (no frame) and bit 7 clear, so ERROR@ ends through ABORT@.

5377H - The Texts and Tables of the Installation

The heading, the two messages, the table of PARAM@ and the file control block of JCL/RLD with its sector buffer.

5538H - The Resident Part: the Hook of CMNDI@

From here to 603FH the code and data are moved up below the old HMEM$ by the installer (5318H) after the words named in JCL/RLD have been relocated; the addresses on this page are those of the file. 5538H is the new target of CMNDI@ (4405H). A command line comes here with the return address 402DH (EXIT@) on the stack when it was typed at the DOS command level; only then is its name tested for EX. Every other command line goes on to CMNDI@ as it was (5D08H).

555CH - EX - Running a Procedure

EX filespec values: the rest of the line is copied to 5EBFH, EXIT@, ABORT@ and ERROR@ are pointed into JCL (5D19H, 5D26H, 5D28H) after their bytes are kept at 5CFEH, the procedure file is opened with the default extension JCL, the options are set to 25H (DSP, QUEUE and CHR on) and the procedure is run as level 1 (55B0H). When the last level ends, the three entry points are set back and EX returns through EXIT@.

55B0H - Starting a Procedure Level

Register Pair HL points to the name of the procedure and the values after it; the file is open with its control block at 5F00H. A frame of 32 bytes is made at 5E99H for the level: +02H the frame before, +08H the second line, +0AH the line run, +0CH the end of the text and the start of the variables, +0EH the next line, +10H the Stack Pointer (the return of this call), +12H the end of the variables, +14H a word of the line, +16H the values and then the end of the line copy, +1CH the next line kept by /JUMP. The file is read in after the frame and ended with a 0DH, its first line must be the procedure's name, its other words are variables that take the values, $LEVEL is set and the lines are run (5678H).

5678H - The Main Loop

Runs the line at +0AH of the frame, then steps to the next line, for ever: a procedure ends through /EXIT (5A24H) or an error (5DA7H).

5680H - Running a Line

Keeps the frame at 5EA9H for /JUMP, copies the line to 5EBFH with its variables replaced (56BDH), shows it for the trace (5740H), finds the command (5755H) and jumps to it with Register Pair HL pointing to the word after the command.

5698H - The Next Line

The next line (+0EH) becomes the line to run (+0AH) and the line after it the next; when that one is the end of the text, EOF encountered.

56BDH - Preparing a Line

Passes a line number and the spaces at the start, copies the line to 5EBFH and then replaces the variables, the last $ in the line first: the name after the $ is looked up (5B38H, a new empty variable if none) and the $, the name and the rest of the line are replaced by the value and the rest. It stops at a $ at the start of the line (an assignment) or at the 24H kept at 5EBEH below the buffer. A line longer than 5EFFH is Line too long.

5740H - The Trace

With the option JCL on (bit 1 of 5E96H), the line at 5EBFH is shown, with the options set to 01H (DSP only) while it is displayed.

5755H - Finding the Command

The second word of the line goes to +14H. A first word starting with a period (a remark) or a minus sign (a label) runs 5A23H, a RET; a dollar sign the assignment 5A4CH; a slash the command whose name matches in the table 57AAH; anything else, an empty line included, is Bad /COMMAND. The routine's address is put into 5EA7H.

57AAH - The Table of the Commands

For each command its length, its name and the address of its routine; the name is compared for its own length (5788H), so a longer word that starts with it matches too. /TYPE, /PRINT and /DEBUG go straight to DSPLY@, PRINT@ and DEBUG@ in SYS0/SYS. FFH ends the table. After it, the two words that /QUEUE puts into the queue as one byte, and the names and values of the variables $LEVEL and $ERR.

5834H - /OPTION - The Switches

/OPTION name/Y or name/N, any number of them: each word is looked up in the table 5880H by its length less one, and the bit of the option in 5E96H is set by the entry's second mask (Y) or cleared by its first mask (N). Any other switch or name is Bad /OPTION.

5873H - The Next Option

Steps Register Pair DE from the length byte of an entry of 5880H to the next entry: the length, the name and the two masks.

5880H - The Table of the Options

For each option the length of its name with the slash, the name, the mask that clears its bit (N) and the mask that sets it (Y); FFH ends the table. The bits of 5E96H: 0 DSP, 1 JCL (the trace), 2 QUEUE, 4 QBYTE, 5 CHR, 7 DQ; bit 3 is set while a /JUMP runs and bit 6 while the echo of a line from the queue is off (VOFF).

58AEH - /DOS - Running a DOS Command

The rest of the line is run through CMNDI@ as it was (5D0BH); EXIT@, ABORT@ and ERROR@ come back here with the error code, which is put into $ERR as two decimal digits. 5E97H, the count of /DOS commands, is counted up before the command; the DEC (HL) after it works on the byte at Register Pair HL, the command's text in 5EBFH, so 5E97H is never counted down.

58C8H - /READ - A Line from the Queue or the Keyboard

/READ $var ...: a line of up to 63 characters is taken through the ROM's line input into 5EBFH, from the queue while it holds characters; its slashes, colons, periods and commas become spaces and its words are given to the variables named in the line as it is in the procedure (+0AH), one word each.

58E2H - /IF - A Comparison

/IF value relation value command: the two values are compared first by their lengths (the shorter is the smaller) and then character by character, upper case; the relation is found in 5991H (EQ 1, NE 2, LT 3, LE 4, GT 5, GE 6). When the condition holds, the fifth word of the line as it is in the procedure becomes the next line (5957H), so the command after it runs next. LE (5954H) holds when the first value is greater; GT (5942H) jumps to 5957H with Register Pair AF still on the stack, so the RET at 5972H goes to an address made of the flags and Register A.

5973H - Finding a Relation

Compares the two letters at Register Pair DE with each pair of the table at Register Pair HL; Register A returns the number of the pair (1 on) with the NZ FLAG, or 00H with the Z FLAG at the FFH.

599EH - /GOTO - The Jump to a Label

/GOTO -label: the word must start with a minus sign, else Bad -LABEL. From the second line of the procedure on, the first word of each line is compared with the label for that word's length, so a line -LOOP matches /GOTO -LOOP1; the line found becomes the next line. Reaching the end of the text is EOF encountered. /JUMP comes here too (5AD0H).

59CDH - /QUEUE - Putting a Line into the Queue

The rest of the line and its 0DH go into the queue. A slash followed by the word JUMP or VOFF puts the single byte FFH or FEH in their place; any other slash and its word go in as they are. A full queue is QUEUE full.

5A05H - /QLOAD - Loading the Queue from a File

/QLOAD filespec: the file is opened with the default extension TXT (5C99H) and every byte of it goes into the queue until a read fails, the end of the file; a full queue is QUEUE full.

5A1CH - /PURGE - Emptying the Queue

The place of the next byte taken out is set to that of the next byte put in. Also called by the error routine (5DABH).

5A23H - A Remark or a Label

A line starting with a period or a minus sign comes here (57A3H) and does nothing.

5A24H - /EXIT - The End of a Level

The frame and all after it are given back (5E99H), the level is counted down and the Stack Pointer of the level is taken back, so the RET returns from the call of 55B0H: to EX (5599H) after level 1, else to /RUN (5A79H). Before that, two bytes are meant to be copied from the level's $ERR to 582FH for /RUN; the name is given with its dollar sign (582AH), which no variable has, so 5B38H makes a new empty variable and the two bytes after its length byte are copied, whatever they are.

5A4CH - The Assignment

$name = value: the word after the name must start with an equal sign, else Bad assignment; the next word (up to eight characters, none for an empty value) is stored as the variable's value. The name is taken from 5EC0H, after the dollar sign at the start of the line, which 56BDH does not replace.

5A69H - /RUN - Another Procedure

/RUN filespec values: the file is opened with the default extension JCL, the free place is set to the end of this level's variables and the procedure is run as the next level (55B0H); when it ends, this level's $ERR takes the value at 582FH (see 5A24H).

5A86H - /JUMP - A Jump Read from the Queue

Entered from JCL's keyboard driver (5D55H) when a program takes the byte FFH from the queue. With no procedure running it goes back to the driver. Else the program's registers and its Stack Pointer are kept (5EADH), the stack of /JUMP at 603FH is taken, bit 3 of the options is set, the next line is kept at +1CH, the rest of the queue's line (the label) is read into 5EBFH and /GOTO runs with it; the main loop goes on there (567BH) until /RESUME or /CANCEL.

5AD3H - /RESUME - Back to the Program

Only while a /JUMP runs (bit 3): the next line kept at +1CH is taken back, the program's Stack Pointer and registers are restored and JCL's keyboard driver goes on with the program's request (5D31H).

5AF5H - /CANCEL - Ending the Stopped Program

Only when 5E97H is not 00H (a /DOS has been run) and a /JUMP runs: the next line kept at +1CH is taken back, the program's stack is taken and EXIT@ (402DH, JP 5D19H during EX) ends the /DOS with 00H, so the procedure goes on after the /DOS line.

5B15H - The Next Word

Passes the spaces at Register Pair HL and measures the word after them, up to a space or the 0DH: Register Pair DE returns its start, Register B and Register A its length (the Z FLAG for none) and Register Pair HL the space or 0DH after it. With no word, Register Pair DE keeps the place where the search began.

5B38H - Finding a Variable

The variables of a level follow its text, from +0CH to +12H of its frame, 18 bytes each: the length of the name, the name (eight places), the length of the value and the value (eight places). The name at Register Pair HL is compared with each name for that name's own length, so a variable FILE is found for FILENAME too. Register Pair DE returns the place of the value's length, Register Pair HL the name. When none matches, the word at Register Pair HL (up to a space) becomes a new variable with an empty value; no word is Bad $VAR.

5B75H - Making a Variable

Puts an entry of 18 bytes at the end of the variables (+12H), with the name at Register Pair HL, Register A characters long (eight at most); Register Pair DE returns the place of the value's length. Out of memory when the entry reaches the limit 5E9DH.

5BAEH - Storing a Value

Stores Register A, the length of the value, at Register Pair HL and the Register A characters at Register Pair DE after it, eight at most.

5BC0H - Giving Values to Variables

Register Pair HL points to names, each a dollar sign and the name, Register Pair DE to values; each name takes the next word of the values, an empty value when there are no more. A name without the dollar sign, or the dollar sign alone, is Bad $VAR. Used for the first line of a procedure, /READ, $LEVEL and $ERR.

5BF3H - Comparing Characters

Compares Register B characters at Register Pair HL and Register Pair DE, both made upper case: the Z FLAG when they are the same (also for Register B 00H), else the flags of the character at Register Pair DE compared with the one at Register Pair HL. Register Pair BC, Register Pair DE and Register Pair HL are kept.

5C0EH - Upper Case

Makes a lower case letter in Register A (61H-7AH) upper case; any other character is kept.

5C17H - Taking a Byte from the Queue

The queue is a ring from 5EA3H up to the byte before 5EA5H: 5EA1H the place of the next byte taken out, 5E9FH that of the next byte put in. Register A returns the byte with the C FLAG clear, or the C FLAG set when the queue is empty. Register Pair DE and Register Pair HL are kept.

5C3EH - Putting a Byte into the Queue

Puts Register A in at 5E9FH unless the place after it is the next byte to be taken out; then the C FLAG is returned, the queue being full. One place of the ring stays empty, so the queue holds at most QUEUE less 2 bytes. Register A, Register Pair DE and Register Pair HL are kept.

5C6AH - Delimiters to Spaces

Turns every slash, colon, period and comma of the line at Register Pair DE, up to its 0DH, into a space, so each part becomes a word for 5BC0H. Register Pair DE is kept.

5C8DH - Passing a Line Number

Steps Register Pair HL past the digits 0-9 at the start of a line, the number of a file saved by BASIC. The CP 7FH has no effect: its flags are replaced by the next comparison.

5C99H - Opening a File

Opens the file named by the first word at Register Pair HL, with the default extension at Register Pair DE, in the control block 5F00H with the buffer 4300H; the name's place is kept at 5EBCH for the test of the first line. Any error is Bad load file. Register Pair HL is kept. The procedure files are only read and are not closed.

5CC3H - Two Decimal Digits

Writes Register A (0-99) at Register Pair HL as two decimal digits, the tens counted up from 30H. Register A and Register Pair HL are kept.

5CD4H - Passing a Line

Steps Register Pair DE past the 0DH of the line it points to; a line that runs past the end of the text (+0CH) is EOF encountered.

5CE9H - Comparing Two Addresses

Compares Register Pair HL with Register Pair DE: the Z FLAG when they are equal, the C FLAG when Register Pair HL is the smaller. Register A is changed.

5CEFH - The Jumps Put over the Entry Points

5CEFH-5CF4H are copied over EXIT@ and ABORT@, 5CF5H-5CF8H over ERROR@ during EX (5580H-5587H); 5CF8H and 5CFBH are also the way to the keyboard and display drivers JCL found (5235H, 524FH). 5CFEH-5D0AH keep the bytes of EXIT@, ABORT@, ERROR@ and CMNDI@ (00H as loaded); the last two groups are run as code.

5D0BH - Running a DOS Command

Runs the command line at Register Pair HL through CMNDI@ as it was (5D08H), with Index Register IX and the Stack Pointer kept in a chain through 5EABH. The command's return, EXIT@ (5D19H), ABORT@ (5D26H, the code 3FH) and ERROR@ with bit 7 clear (5D28H) all come back to 5D1AH with Register A holding the error code, bits 5-0; ERROR@ with bit 7 set runs as it was (5D04H). During EX an error of a DOS command is therefore not shown, only put into $ERR.

5D31H - JCL's Keyboard Driver

The driver of the KI device after the installation. With QUEUE off (bit 2 of 5E96H) the keyboard's own driver runs (5CF8H). With QBYTE off (bit 4) the queue serves only a request whose return address, twelve bytes up the stack, is 004CH, that is one made through the ROM's 0049H, as the ROM's line input does; others go to the keyboard. An empty queue goes to the keyboard. FFH is a /JUMP (5A86H); FEH sets bit 6, the echo off (VOFF), and a 0DH after it is passed. With CHR off (bit 5) the characters 20H-2FH and 3AH-3FH become spaces.

5D7DH - JCL's Display Driver

The driver of the DO device after the installation, with the character in Register C. With DQ on (bit 7 of 5E96H) a 0DH or any character from 20H up goes into the queue too (QUEUE full when it does not fit). With DSP off (bit 0) nothing is shown; while bit 6 is set (VOFF) the characters are not shown up to and including the next 0DH, which clears it. Else the display's own driver runs (5CFBH).

5DA7H - JCL's Errors

Register A holds JCL's error number, 01H-0CH. The queue is emptied, the level, the count of /DOS and the options (25H) are set back, the procedure area is free again and $ERR's value is 00; the message, the Register A th text after the 03H at 5DF3H, is shown between two signs %% and EX ends through 559CH, which sets EXIT@, ABORT@ and ERROR@ back.

5DF3H - The Texts and the Variables

JCL's twelve messages, each after a 03H and ended by one, then the default extensions, the name EX, the signs %%, the options and the pointers of the procedure area and the queue. The words at 5E99H-5EA6H hold their own addresses as loaded; the installer writes them (5261H-5289H) and JCL/RLD relocates them.