Using the OS can be confusing at times. There are a collection of JCL (Job Control Language) commands that can be executed at the prompt to perform basic operations. However, more complex jobs are executed from an ASCII script file that contains a collection of JCL commands. We are fairly confident this is a complete list of JCL commands, all reverse engineered by the incredibly talented Ren14500.

• Commas between parameters appear to be optionally allowed in at least some situations but never seem to be required.
• Some keywords like 'ON' are sometimes optional.
• Sizes are specified in tracks (T suffix) or sectors (S suffix). The default without a suffix is tracks.
• Libraries are files but a bit special so with some commands they can be treated like files and for some they cannot.
• JCL works like MS-DOS and BAT (batch) files in the sense that there is a single environment. Running a JCL script does not introduce a new environment like Unix shells, so any changes to variables are kept when the script ends.
• File, library, and volume names are all limited to 10 characters.
• Lines starting with * are comments, which are not printed when logging is turned off.
• Lines starting with / are echoed to the screen even if logging is turned off. Variables are expanded.
• Running JCL scripts from JCL scripts is the same as running them from the main prompt: just use the name of the script.
• Labels are used with .SKIP and .SKIPR and are created by an equal sign followed by the label name. Example: =ok

• Variable values are limited to 10 characters. If arithmetic expressions result in bigger values, they are truncated on the left, except the minus sign is kept if the value is negative and a digit is truncated instead.
• To assign a variable, use its name/number. To expand a variable to its value, precede it with #. Variables are a single digit or letter so you can immediately follow a variable dereference with additional literal digits or letters.
• There are 10 main user variables, numbered 0-9. When a JCL script is run, the arguments to it are loaded in. If there are less than 10 arguments, the values of the user variables are unchanged from their last setting. There are additional numbered variables up to a system limit, but they are only writable from JCL and cannot be read.
• There are also a number of special variables with predefined meanings. Some are meant to be read only and others can be read and written.

C, CC

Completion Code. After an executable runs, this variable is set to the value returned via the CPL 'STOP' command. To read the value in JCL, use #C. To assign it, use .SETA CC=. The value must be in the range [0,255].

D, DD

Default Drive. Default Drive. This allows you to get and set the default drive. Running commands on the default drive does not require a drive specifier. To read the value in JCL, use #D. To assign it, use .SETA DD=. To set the default for a partition, set the "D" disk default in P.SYSGEN.

I

Input device number. This variable is used in many scripts to create temporary file names that are unique to the user. It matches the partition number. It is read-only.

L

The "L" disk default set in P.SYSGEN. SYSGEN documentation suggests this is the default disk on which to create libraries. It is read-only.

M

Unknown meaning. It is read-only.

S

System drive number. It is read-only.

T

The "T" disk default set in P.SYSGEN. SYSGEN documentation suggests this is the default disk on which to create temporary files. It is read-only.

U, UPSI

User-Programmable Switch Indicator. This variable can be accessed by CPL programs, both read and write. It allows a single argument to be passed to and from the executable. It is also possible to access the numeric variables from CPL. To read the value in JCL, use #U. To assign it, use .SETA UPSI=. The value must be in the range [0,255].

V

CRT number. Usually seen in scripts to decide which CRT to use. It is read-only.

W

The "W" disk default set in P.SYSGEN. SYSGEN documentation suggests this is the default disk on which to create work files. It is read-only.

SYSRDR is usually meant to read from the jobstream. The way this works is after a .RUN command there will be additional lines of text that the executable started by the .RUN can read from SYSRDR. There is typically an EOF indicator like the word END or the symbols /* to tell the executable when to stop reading. When control is returned to the JCL script, it returns after the part read by the executable.

An example of this is seen with the S.DSORT executable in numerous scripts:

.RUN S.DSORT
PRINT=ALL,RECSIZ=25,INPUT=1,OUTPUT=INP
WORK=4,FILTYP=B,KEY=(5,20,AF)
/*

The S.DSORT executable will read the three lines that follow to get the parameters it needs to perform the desired sorting operation.

Clears a physical drive or library. Allows you to reset filesystem parameters. ALL DRIVE OR LIBRARY CONTENTS WILL BE DELETED.

Physical drive:

.CLR <drive> [VOL=<vol>] [DSIZE=<d>] [USIZE=<u>] [FSIZE=<f>]

Library:

.CLR <lib> ON <drive> [DSIZE=<d>] [USIZE=<u>] [FSIZE=<f>]
.CLR <lib> <drive> [DSIZE=<d>] [USIZE=<u>] [FSIZE=<f>]

Parameters:

<drive> = physical drive number.
<lib> = library name with trailing '.'.
<vol> = volume name (up to 10 characters).
<d> = size of directory file.
<u> = size of used-sectors file.
<f> = size of free-sectors file.

Examples:

.CLR 1 VOL=MYDISK

• Erase and reformat drive 1, name it MYDISK, use 1 sector each for the directory, used-sectors, and free-sectors files.

.CLR S. ON 0 DSIZE=2T USIZE=2T FSIZE=1S

• Erase the S library on drive 0, use 2 tracks for the directory and used sectors files and 1 sector for the free-sectors file.

See also: .FORMAT JCL command.

Deletes a file or library.

.DEL <file> ON <drive>
.DEL <file> <drive>

Parameters:

<drive> = physical drive number.
<file> = filename.

Examples:

.DEL MYFILE 0

• Deletes the file MYFILE on drive 0.

  .DEL MYLIB 0

• Deletes the library MYLIB on drive 0.

See also: S.DEL script.

Displays a directory listing of a physical drive or library.

Physical drive:

.DIR <drive> [(template)]

Library:

.DIR <lib> <drive> [(template)]

Parameters:

<drive> = physical drive number.
<lib> = library name with trailing '.'.
<template> = template to limit display to matches.

The display consists of 7 columns:

NAM = Name of file.
TYP = Type of file.
TKS = Number of tracks allocated.
SEC = Number of sectors allocated.
FSI = File Size Increment. This is the allocation chunk size. 
  Initial file size must be a multiple of this value; when the file grows it will grow in chunks this size.
CLS = File class. This value is informational.
DATE = File date.

After the list of files is a summary listing the total tracks and sectors used, the tracks and sectors used by the listed files, and the tracks and sectors free.

Examples:

.DIR 0

• List the contents of drive 0.

.DIR S. 0

• List the contents of the S library on drive 0.

.DIR S. 0 (X)

• List the files in the S library on drive 0 that start with X.

.DIR S. 0 ( OK )

• List the files in the S library on drive 0 that that have the second and third letters equal to OK.

Denote the end of a JCL script. WARNING: Do not use .END without a preceding .JOB. Otherwise you are trying to end JCL as a whole.

Waits for input from the console.

.ENTER <var>

Parameters:

<var> = variable name or number to receive the input.

Examples:

.ENTER 3

• Waits for input. Assigns the value entered to variable 3.

Formats a physical drive. Allows you to set filesystem parameters. ALL DRIVE OR LIBRARY CONTENTS WILL BE DELETED.

.FORMAT <drive> [VOL=<vol>] [DSIZE=<d>] [USIZE=<u>] [FSIZE=<f>]

Parameters:

<drive> = physical drive number.
<vol> = volume name (up to 10 characters).
<d> = size of directory file.
<u> = size of used-sectors file.
<f> = size of free-sectors file.

Examples:

.FORMAT 1 VOL=MYDISK

• Erase and reformat drive 1, name it MYDISK, use 1 sector each for the directory, used-sectors, and free-sectors files.

.FORMAT 1 VOL=MYDISK DSIZE=1T USIZE=1T FSIZE=8S

• Erase and reformat drive 1, name it MYDISK, use 1 sector each for the directory and used-sectors files and 8 sectors for the free-sectors file.

Gets information about files.

.FSPEC <file> ON <drive> [<var>=<param>]...

Parameters:

<drive> = physical drive number.
<file> = filename.
<var> = variable number or name.
<param> = file parameter of interest. Possible parameters are:
          CLASS = File class.
          DATE = File date.
          FSI = File Size Incremeent.
          SIZE = Size of file in sectors.
          TYPE = Type of file.
          USE = 1 if usable, not 1 if in use by another partition.

Examples:

.FSPEC @SYS ON 0 8=SIZE

• Sets variable 8 to the size of @SYS.

.FSPEC S ON 0 5=CLASS 6=DATE 7=FSI 8=SIZE 9=TYPE

• Sets variable 5 to the class, 6 to the date, 7 to the FSI, 8 to the size, and 9 to to the type of S.

See also: .DIR JCL command.

Turns on software guarding of a physical disk against formatting.

.GUARD <drive>

Parameters:

<drive> = physical drive number.

Examples:

.GUARD 0

• Turns on software guard of drive 0.

Displays the I/O mappings.

.IOA [ALL]

Examples:

.IOA

• Prints the mappings for the current partition.

.IOA ALL

• Prints the mappings for all partitions.

Starts a JCL job, defining the job name and some parameters.

.JOB <name> [abort=cancel] [form=<form>] [memory=wait]

Parameters:

<name> = Job name.
<form> = Form name for printing.

The meaning of the memory=wait is unknown. The abort=cancel is recommended so if you Control-C it will cancel the script and get you back to a good state.

Examples:

.JOB MYJOB ABORT=CANCEL

Loads a module in to the current partition.

.LOAD <module>

Parameters:

<module> = module name.

Examples:

.LOAD BASIC

• Loads the BASIC module, required for running BASIC programs.

Turns on logging.

.LOG

Examples:

.LOG

• Turns on logging. All JCL statements will be printed before execution, with variables expanded.

Renames a file.

.NAM <file> ON <drive> <newname>
.NAM <file> <drive> <newname>

Parameters:

<drive> = physical drive number.
<file> = filename.
<newname> = new filename.

Examples:

.NAM ? ON 0 QUESTION

• Renames the ? library on drive 0 to QUESTION.

Creates a file.

.NEW <file> ON <drive> '<type>' <size> [<param>=<val>]...
.NEW <file> <drive> '<type>' <size> [<param>=<val>]...

Parameters:

<drive> = physical drive number.
<file> = filename.
<type> = file type. Choices are:
  A = ASCII text file.
  B = Binary sequential file.
  C = Random access file.
  D = Directory/system maintenance file (not intended for users).
  E = Executable.
  I = VSI (Variable Spanned Indexed) file (minimum size of 1T).
  L = Library.
  Q = Unknown.
<size> = initial size allocation. Suffix T for tracks, S for sectors; default is T if not specified.
<param> = Creation parameters. Some apply to any file type while others apply only to specific types. 
  Choices are:
  FSI = File Size Increment. See the .DIR JCL command for more.
  KEYLEN = Key length. Only seen on type 'I' files.
  NOCLR = Unknown purpose. Only seen in P.BASIC. No value.
  PADDNG = Padding. Only seen on type 'I' files.
  RECSIZ = Record size. Only seen on type 'I' files.
<val> = Appropriate value for the parameter.

Examples:

.NEW MYTEXT ON 0 'A' 1S

Turns off software guarding of a physical disk against formatting.

.NOGUARD <drive>

Parameters:

<drive> = physical drive number.

Examples:

.NOGUARD 0

• Turns off software guard of drive 0.

Turns off logging.

.NOLOG

Examples:

.NOLOG

• Turns off logging. Only lines starting with / will be printed before execution, with variables expanded.

Turns off timestamps in logging.

.NOTIME

Examples:

.NOTIME

• Turns off timestamps.

Waits for a newline.

.PAUSE

Examples:

.PAUSE

• Waits until newline is entered.

Sets current terminal priority (1 to 127). This controls how many clock cycles that user gets priority over.

.PRI <val>

Parameters:

<val> = the priority from 1 to 127.

Examples:

.PRI 20

• Sets the priority to 20.

Release file?

.REL [<filespec>]...

Parameters:

<filespec> = file specification like SYS000, etc.

Examples:

.REL SYS000 SYS014

• Releases SYS000 and SYS014.

Reorganize a physical drive. This defragments the disk by rewriting it completely to a new drive.

.REORG FROM <drive> TO <drive> DATE=<date> VOL=<vol>

Parameters:

<drive> = physical drive number.
<date> = Y to check volume date, N to not check.
<vol> = Y to check volume name, N to not check.

Examples:

.REORG FROM 0 TO 1 DATE=Y VOL=Y

• Rewrite drive 0 on to drive 1 checking the volume date and name.

See also: S.DUMP JCL script.

Restore from one drive to another. Requires ?

.RESTORE <drive> TO <drive>

Parameters:

<drive> = physical drive number.

Examples:

.RESTORE 1 TO 0

• Restores drive 1 to drive 0.

See also: S.SELREST JCL script.

Run an executable.

.RUN <file>
.RUN <file> ON <drive>

Parameters:

<drive> = physical drive number.
<file> = filename.

Examples:

.RUN S.XEJECT

• Runs the S.XEJECT executable on the default drive.

.RUN S.XEJECT ON 0

• Runs the S.XEJECT executable on drive 0.

Set a variable, evaluating arithmetic expressions.

.SETA [<var>=<expr>]...

Parameters:

<var> = variable number or name.
<expr> = arithmetic expression. The +, -, *, and / operators work as expected.
  Parentheses are supported to change the order of operations.

Examples:

.SETA 1=123 2=3+4

• Sets variable 1 to 123 and variable 2 to 7.

.SETA 1=#2

• Sets variable 1 to the value of variable 2.

Set a variable as a string.

.SETC [<var>=<expr>]...

Parameters:

<var> = variable number or name.
<expr> = string. If special characters like . are in the string, it must be single-quoted.
  Spaces are removed.

Examples:

.SETC 1=ABC 2='A B C'

• Sets variables 1 and 2 to ABC.

.SETC 3='3.14' 4=''

• Sets variable 3 to 3.14 and 4 to the empty string.

Skips forward with an optional condition.

.SKIP <lines> [IF <expr> <op> <expr>]
.SKIP TO <label> [IF <expr> <op> <expr>]

Parameters:

<lines> = number of lines to skip.
<label> = label to skip to.
<expr> = string or arithmetic expression. Both expressions must be of the same type.
<op> = comparison operator. If the comparison is true, the skip is performed; 
  otherwise the next line is processed. 
  The operators are:
    EQ = equal to.
    NE = not equal to.
    LT = less than.
    LE = less than or equal to.
    GT = greater than.
    GE = greater than or equal to.

Examples:

.SKIP 1

• Skips the next line. Processing continues at the line after that.

.SKIP 3 IF #1 NE 0

• Skips the next three lines if variable 1 is not equal to zero. Does not skip otherwise.

.SKIP TO OK IF #2 GT 3

• Skips to the label OK if variable 2 is greater than three.

Skips backwards (reverse/rewind) with an optional condition.

.SKIPR <lines> [IF <expr> <op> <expr>]
.SKIPR TO <label> [IF <expr> <op> <expr>]

Parameters:

<lines> = number of lines to skip after rewinding to the beginning of the JCL script.
<label> = label to skip to.
<expr> = string or arithmetic expression. Both expressions must be of the same type.
<op> = comparison operator. If the comparison is true, the skip is performed;
  otherwise the next line is processed. 
  The operators are:
    EQ = equal to.
    NE = not equal to.
    LT = less than.
    LE = less than or equal to.
    GT = greater than.
    GE = greater than or equal to.

Examples:

.SKIPR 1

• Rewinds the script, then skips one line. Processing continues at line 2.

.SKIPR 0 IF #1 NE 0

• If variable 1 is not equal to zero, processing restarts at the beginning of the script. Does not skip otherwise.

.SKIPR TO OK IF #2 GT 3

• Skips to the label OK if variable 2 is greater than three.

Displays operating system status.

.STA [<part>]

Parameters:

<part> = partition number preceded by P.

Examples:

.STA

• Displays system status.

.STA P0

• Displays system status.

Starts a blind task.

.START <part> <script> [<params>]

Parameters:

<part> = partition number preceded by P.
<script> = script name.
<params> = parameters for the script.

See also: S.START JCL script.

Stops the current job. This is meant to stop background jobs like the printer spooler.

.STOP

See also: S.UNSPOOL JCL script.

Turns on timestamps in logging.

.TIME

Examples:

.TIME

• Turns on timestamps.

Set up a file to be used by an executable.

.USE <file> ON <drive> FOR <logunit> [shar] [pass]
.USE <file> ON <drive> <logunit> [shar] [pass]
.USE <special> <logunit>

Parameters:

<drive> = physical drive number.
<file> = filename.
<logunit> = logical unit. This is one of the following four reserved names or
  a numbered unit with prefix SYS:
    SYSIPT = system input device/file (console usually).
    SYSLOG = system log device/file.
    SYSLST = system list device/file.
    SYSRDR = redirect? device/file.
    SYSnnn = numbered unit where nnn = number up to the partition limit.
<special> = a special device, which has a prefix and a number of the device.
  Known devices are:
    CRTn = console #n.
    DUMMY = dummy device.
    PRTn = printer #n.
    shar = shared? Allow other partitions to open the same file?
    pass = ?

Examples:

.USE MYFILE ON 0 SYS000

• Set up MYFILE on drive 0 as SYS000.

.USE CRT0 SYSIPT

• Use console 0 for system input.

Gets information about the disk volume.

.VSPEC <drive> [<var>=<param>]...

Parameters:

<drive> = physical drive number.
<var> = variable number or name.
<param> = volume parameter of interest. 
  Possible parameters are:
    ASTATUS = 1 if assigned, 0 if not assigned.
    AVAIL = available space in sectors.
    GSTATUS = 1 if guarded, 0 if not guarded.
    USED = used space in sectors.
    VOL = volume name.

Examples:

.VSPEC 0 8=VOL

• Sets variable 8 to the volume name of drive 0.

.VSPEC 0 5=ASTATUS 6=AVAIL 7=GSTATUS 8=USED

• Sets variable 5 to the assigned status, 6 to the available sectors, 7 to the guard status, and 8 to the used sectors.

See also: .DIR JCL command and S.NEWDSK JCL script

Install WIPL on a drive.

.WIPLT <drive> [CODE=<code>]

Parameters:

<drive> = physical drive number.
<code> = boot code.

See also: S.NEWDSK and S.LOADER JCL scripts.