Editing Job Control Language (section)

==OS JCL==
OS JCL consists of three basic statement types:<ref>Ashley and Fernandez, ''Job Control Language'', pp. 8, 23.  There are also two additional statements, PROC and PEND, used to test JCL procedures.</ref>
* <code>JOB</code> statement, which identifies the start of the job, and information about the whole job, such as billing, run priority, and time and space limits.
* <code>EXEC</code> statement, which identifies the program or ''procedure''<ref>A pre-stored set of "EXEC PGM=" and "DD" JCL commands which could be parameterized</ref> to be executed in this step of the job,<br> and information about the step, including ''COND''itions for running or skipping a step.
* <code>DD</code> (Data Definition) statements, which identify a data file to be used in a step, and detailed info about that file. <code>DD</code> statements can be in any order within the step.

Right from the start, JCL for the OS family (up to and including [[z/OS]]) was more flexible and easier to use.

The following examples use the old style of syntax which was provided right from the launch of [[System/360]] in 1964. The old syntax is still quite common in jobs that have been running for decades with only minor changes.

===Rules for coding JCL statements===

Each JCL statement is divided into five fields:<ref>Ashley and Fernandez, ''Job Control Language'', pp. 12–16.</ref>

  Identifier-Field Name-Field Operation-Field Parameter-Field Comments-Field
                  ^          ^               ^               ^
               no space    space           space           space

<var>Identifier-Field</var> should be concatenated with <var>Name-Field</var>, i.e. there should be no spaces between them.

* <var>Identifier-Field</var> (<code>//</code>): The identifier field indicates to the system that a statement is a JCL statement rather than data. The identifier field consists of the following:
** Columns 1 and 2 of all JCL statements, except the delimiter statement, contain <code>//</code>
** Columns 1 and 2 of the delimiter statement contain <code>/*</code>
** Columns 1, 2, and 3 of a JCL comment statement contain <code>//*</code>
* <var>Name-Field</var>: The name field identifies a particular statement so that other statements and the system can refer to it. For JCL statements, it should be coded as follows:
** The name must begin in column 3.
** The name is 1 through 8 alphanumeric or national (<code>$</code>, <code>#</code>, <code>@</code>) characters.
** The first character must be an alphabetic.
** The name must be followed by at least one blank.
* <var>Operation-Field</var>: The operation field specifies the type of statement, or, for the command statement, the command. <var>Operation-Field</var> should be coded as follows:
** The operation field consists of the characters in the syntax box for the statement.
** The operation follows the name field.
** The operation must be preceded and followed by at least one blank.
** The operation will be one of <code>JOB</code>, <code>EXEC</code> and <code>DD</code>.
* <var>Parameter-Field</var>: The parameter field, also sometimes referred to as the operand field, contains parameters separated by commas. Parameter field should be coded as follows:
** The parameter field follows the operation field.
** The parameter field must be preceded by at least one blank.
** The parameter field contains parameters which are keywords that used in the statement to provide information such as the program or dataset name.
* <var>Comments-Field</var>: This contains [[comment (computer programming)|comments]]. <var>Comments-Field</var> should be coded as Follows:
** The comments field follows the parameter field.
** The comments field must be preceded by at least one blank.

===Keyword parameters===
<syntaxhighlight lang="jcl">
//NEWFILE DD DSN=MYFILE01,UNIT=DISK,SPACE=(TRK,80,10),
//           DCB=(LRECL=100,BLKSIZE=1000),
//           DISP=(NEW,CATLG,DELETE)
</syntaxhighlight>
All of the major parameters of OS JCL statements are identified by keywords and can be presented in any order. A few of these contain two or more sub-parameters, such as <code>SPACE</code> (how much disk space to allocate to a new file) and <code>DCB</code> (detailed specification of a file's layout) in the example above. Sub-parameters are sometimes positional, as in <code>SPACE</code>, but the most complex parameters, such as <code>DCB</code>, have keyword sub-parameters.

Positional parameter must precede keyword parameters. Keyword parameters always assign values to a keyword using the equals sign (<code>=</code>).<ref>Ashley and Fernandez, ''Job Control Language'', pp. 13–15.</ref>

===Data access (DD statement)===
The <code>DD</code> statement is used to reference data. This statement links a program's internal description of a dataset to the data on external devices: disks, tapes, cards, printers, etc.  The DD may provide information such as a device type (e.g. '181','2400-5','TAPE'), a [[Volume (computing)|volume serial]] number for tapes or disks, and the description of the data file, called the <code>DCB</code> subparameter after the [[Data Control Block]] (DCB)  in the program used to identify the file.

Information describing the file can come from three sources: The DD card information, the dataset label information for an existing file stored on tape or disk, and the DCB macro coded in the program.  When the file is opened this data is merged, with the DD information taking precedence over the label information, and the DCB information taking precedence over both.  The updated description is then written back to the dataset label. This can lead to unintended consequences if incorrect DCB information is provided.<ref>{{cite book|last1=IBM Corporation|title=OS/VS MVS Data Management Services Guide|date=August 1978|url=http://www.prycroft6.com.au/misc/download/GC26-3875-0_MVS_DataMgmtSrvcsGde_Aug78OCR.pdf|access-date=Oct 17, 2014|ref=DataMgmt}}</ref>

Because of the parameters listed above and specific information for various access methods and devices the DD statement is the most complex JCL statement. In one IBM reference manual description of the DD statement occupies over 130 pages—more than twice as much as the JOB and EXEC statements combined.<ref>{{cite book |last1=IBM Corporation |title=IBM System/360 Operating System: Job Control Language Reference |date=June 1971 |url=http://www.bitsavers.org/pdf/ibm/360/os/R20.1_Mar71/GC28-6704-1_OS_JCL_Reference_Rel_20.1_Jun71.pdf |access-date=June 25, 2019}}</ref>

The DD statement allows inline data to be injected into the job stream.  This is useful for providing control information to utilities such as IDCAMS, SORT, etc. as well as providing input data to programs.

===Device independence===
From the very beginning, the JCL for the OS family of operating systems offered a high degree of device independence. Even for new files which were to be kept after the end of the job one could specify the device type in generic terms, e.g., <code>UNIT=DISK</code>, <code>UNIT=TAPE</code>, or <code>UNIT=SYSSQ</code> (tape or disk). Of course, if it mattered one could specify a model number or even a specific device address.<ref>McQuillen, ''System/360–370 Assembler Language'', pp. 297, 406–407.</ref>

==={{anchor}}Procedures===
'''Procedures''' permit grouping one or more "''EXEC PGM=''" and ''DD'' statements and then invoking them with "''EXEC PROC=''procname" -or- simply "EXEC procname" <ref>the default for the EXEC statement is PROC=</ref>

A facility called a Procedure Library allowed pre-storing procedures.

====PROC & PEND====
Procedures can also be included in the job stream by terminating the procedure with a <code>// PEND</code> statement, then invoking it by name the same was as if it were in a procedure library.

For example:
<syntaxhighlight lang="jcl" highlight="1,6">
//SUMPRINT PROC 
//PRINT    EXEC PGM=IEBGENER
//SYSUT1   DD   DSN=CEO.FILES.DAYEND.RPT24A,DISP=SHR
//SYSUT2   DD   SYSOUT=A
//SYSIN    DD   DUMMY
//         PEND
// EXEC SUMPRINT
</syntaxhighlight>

===Parameterized procedures===
OS JCL procedures were parameterized from the start, making them rather like [[Macro assembler|macros]] or even simple [[subroutine]]s and thus increasing their [[Code reuse|reusability]] in a wide range of situations.<ref>Ashley and Fernandez, ''Job Control Language'', pp. 129–131.</ref>
<syntaxhighlight lang="jcl">
//MYPROC PROC FNAME=MYFILE01,SPTYPE=TRK,SPINIT=50,SPEXT=10,LR=100,BLK=1000
.....
//NEWFILE DD DSN=&FNAME,UNIT=DISK,SPACE=(&SPTYPE,&SPINIT,&SPEXT),
//           DCB=(LRECL=&LR,BLKSIZE=&BLK),DISP=(NEW,CATLG,DELETE)
....
</syntaxhighlight>
In this example, all the values beginning with ampersands "<code>&</code>" are parameters which will be specified when a job requests that the procedure be used. The PROC statement, in addition to giving the procedure a name, allows the programmer to specify default values for each parameter. So one could use the one procedure in this example to create new files of many different sizes and layouts. For example:
<syntaxhighlight lang="jcl">
//JOB01  JOB ..........
//STEP01 EXEC MYPROC FNAME=JOESFILE,SPTYPE=CYL,SPINIT=10,SPEXT=2,LR=100,BLK=2000
or
//JOB02  JOB ..........
//STEP01 EXEC MYPROC FNAME=SUESFILE,SPTYPE=TRK,SPINIT=500,SPEXT=100,LR=100,BLK=5000
</syntaxhighlight>

===Referbacks===
In multi-step jobs, a later step can use a ''referback'' instead of specifying in full a file which has already been specified in an earlier step. For example:
<syntaxhighlight lang="jcl">
//MYPROC ................
//MYPR01 EXEC PGM=..........
//NEWFILE DD DSN=&MYFILE,UNIT=DISK,SPACE=(TRK,50,10),
//           DCB=(LRECL=100,BLKSIZE=1000),DISP=(NEW,CATLG,DELETE)
....
//MYPR02 EXEC PGM=..........
//INPUT01 DD DSN=*.MYPR01.NEWFILE
</syntaxhighlight>

Here, <code>MYPR02</code> uses the file identified as <code>NEWFILE</code> in step <code>MYPR01</code> (<code>DSN</code> means "dataset name" and specifies the name of the file; a DSN could not exceed 44 characters<ref>{{cite web
   |url=https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.idad400/name.htm
   |title=Data set names
   |website=[[IBM]]
 |date=27 March 2014
 |quote=Data set names must not exceed 44 characters, including all name segments and periods.}}</ref>).

In jobs which contain a mixture of job-specific JCL and procedure calls, a job-specific step can refer back to a file which was fully specified in a procedure, for example:
<syntaxhighlight lang="jcl">
//MYJOB JOB ..........
//STEP01 EXEC MYPROC             Using a procedure
//STEP02 EXEC PGM=.........      Step which is specific to this job
//INPUT01 DD DSN=*.STEP01.MYPR01.NEWFILE
</syntaxhighlight>
where <code>DSN=*.STEP01.MYPR01.NEWFILE</code> means "use the file identified as <code>NEWFILE</code> in step <code>MYPR01</code> of the procedure used by step <code>STEP01</code> of this job". Using the name of the step which called the procedure rather than the name of the procedure allows a programmer to use the same procedure several times in the same job without confusion about which instance of the procedure is used in the referback.

===Comments===
JCL files can be long and complex, and the language is not easy to read. OS JCL allows programmers to include two types of explanatory comment:
*On the same line as a JCL statement. They can be extended by placing a continuation character (conventionally "<code>X</code>") in column 72, followed by "<code>// </code>" in columns 1–3 of the next line.
*Lines which contain only comment, often used to explain major points about the overall structure of the JCL rather than local details. Comment-only lines are also used to divide long, complex JCL files into sections.
<syntaxhighlight lang="jcl">
//MYJOB JOB ..........
//*  Lines containing only comments.
//******** Often used to divide JCL listing into sections ********
//STEP01 EXEC MYPROC             Comment 2 on same line as statement
//STEP02 EXEC PGM=.........      Comment 3 has been extended and       X
//         overflows into another line.
//INPUT01 DD DSN=STEP01.MYPR01.NEWFILE
</syntaxhighlight>

===Concatenating input files===
OS JCL allows programmers to concatenate ("chain") input files so that they appear to the program as ''one'' file, for example
<syntaxhighlight lang="jcl">

//INPUT01 DD DSN=MYFILE01,DISP=SHR
//        DD DSN=JOESFILE,DISP=SHR
//        DD DSN=SUESFILE,DISP=SHR
</syntaxhighlight>

The 2nd and third statements have no value in the name field, so OS treats them as concatenations. The files must be of the same basic type (almost always sequential), and must have the same record length, however the block length need not be the same.

In early versions of the OS (certainly before OS/360 R21.8) the block length must be in decreasing order, or the user must inspect each instance and append to the named DD statement the maximum block length found, as in, for example,
<syntaxhighlight lang="jcl">

//INPUT01 DD DSN=MYFILE01,DISP=SHR,BLKSIZE=800
//        DD DSN=JOESFILE,DISP=SHR (BLKSIZE assumed to be equal to or less than 800)
//        DD DSN=SUESFILE,DISP=SHR (BLKSIZE assumed to be equal to or less than 800)
</syntaxhighlight>

In later versions of the OS (certainly after OS/MVS R3.7 with the appropriate "selectable units") the OS itself, during allocation, would inspect each instance in a concatenation and would substitute the maximum block length which was found.

A usual fallback was to simply determine the maximum possible block length on the device, and specify that on the named DD statement, as in, for example,
<syntaxhighlight lang="jcl">

//INPUT01 DD DSN=MYFILE01,DISP=SHR,BLKSIZE=8000
//        DD DSN=JOESFILE,DISP=SHR (BLKSIZE assumed to be equal to or less than 8000)
//        DD DSN=SUESFILE,DISP=SHR (BLKSIZE assumed to be equal to or less than 8000)
</syntaxhighlight>

The purpose of this fallback was to ensure that the access method would allocate an input buffer set which was large enough to accommodate any and all of the specified datasets.

===Conditional processing===
OS expects programs to set a return code which specifies how successful the ''program'' thought it was. The most common conventional values are:<ref name=Brown />{{rp|p.87}}
*0 = Normal - all OK
*4 = Warning - minor errors or problems
*8 = Error - significant errors or problems
*12 = Severe error - major errors or problems, the results (e.g. files or reports produced) should not be trusted.
*16 = Terminal error - very serious problems, do not use the results!

OS JCL refers to the return code as <code>COND</code> ("condition code"), and can use it to decide whether to run subsequent steps. However, unlike most modern programming languages, conditional steps in OS JCL are ''not'' executed if the specified condition is true&mdash;thus giving rise to the [[mnemonic]], "If it's true, pass on through [without running the code]." To complicate matters further, the condition can only be specified ''after'' the step to which it refers. For example:
<syntaxhighlight lang="jcl">
//MYJOB JOB ...........
//STEP01 EXEC PGM=PROG01
....
//STEP02 EXEC PGM=PROG02,COND=(4,GT,STEP01)
....
//STEP03 EXEC PGM=PROG03,COND=(8,LE)
....
//STEP04 EXEC PGM=PROG04,COND=(ONLY,STEP01)
....
//STEP05 EXEC PGM=PROG05,COND=(EVEN,STEP03)
....
</syntaxhighlight>
means:
# Run <code>STEP01</code>, and collect its return code.
# Don't run <code>STEP02</code> if the number 4 is greater than <code>STEP01</code>'s return code.
# Don't run <code>STEP03</code> if the number 8 is less than or equal to any previous return code.
# Run <code>STEP04</code> only if <code>STEP01</code> abnormally ended.
# Run <code>STEP05</code>, even if <code>STEP03</code> abnormally ended.

This translates to the following [[pseudocode]]:
 run STEP01
 '''if''' STEP01's return code '''is greater than or equal to ''' 4 '''then'''
     run STEP02
 '''end if'''
 '''if''' any previous return code '''is less than ''' 8 '''then'''
     run STEP03
 '''end if'''
 '''if''' STEP01 abnormally ended '''then'''
     run STEP04
 '''end if'''
 '''if''' STEP03 abnormally ended '''then'''
     run STEP05
 '''else'''
     run STEP05
 '''end if'''

Note that by reading the steps containing <code>COND</code> statements backwards, one can understand them fairly easily. This is an example of [[Transposition (logic)|logical transposition]].
However, IBM later introduced IF condition in JCL thereby making coding somewhat easier for programmers while retaining the <code>COND</code> parameter (to avoid making changes to the existing JCLs where {{code|COND parm}} is used).

The <code>COND</code> parameter may also be specified on the <code>JOB</code> statement. If so the system "performs the same return code tests for every step in a job. If a JOB statement return code test is satisfied, the job terminates."<ref>{{cite web|last1=IBM Corporation|title=Relationship of the COND parameters on JOB and EXEC statements|url=https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.ieab500/iea3b5_Relationship_of_the_COND_parameters_on_JOB_and_EXEC_statements.htm|website=IBM Knowledge Center|access-date=Feb 21, 2018}}</ref>

===Utilities===
Jobs use a number of [[IBM mainframe utility programs|IBM utility programs]] to assist in the processing of data. Utilities are most useful in batch processing. The utilities can be grouped into three sets:
* Data Set Utilities - Create, print, copy, move and delete data sets.
* System Utilities - Maintain and manage catalogs and other system information.
* Access Method Services - Process [[Virtual Storage Access Method]] (VSAM) and non-VSAM data sets.

===Difficulty of use===
OS JCL is undeniably complex<ref name="asm-jcl"/> and has been described as "user hostile".<ref>{{cite book | title=NetView: IBM's Network Management Product | first=Alfred | last=Charley | publisher=Van Nostrand Reinhold | location=New York | date=1993 | page=[https://books.google.com/books?id=TPVSAAAAMAAJ&q=jcl+%22user+hostile%22 93] | isbn=0-442-01407-4}}</ref><ref>{{cite web  |author=Mathew W. Blode
   |url=https://hn.matthewblode.com/item/22785474
   |quote=JCL in particular is notoriously user hostile and has been called "the worst programming language ever designed" by Fred Brooks ... (<nowiki>http://dtsc.dfw.ibm.com/MVSDS/'HTTPD2.APPS.ZOSCLASS.PDF(ZCLA</nowiki>...)[link in original].
   |date=April 6, 2020  |access-date=May 7, 2020
   |title=Newly unemployed New Yorkers are being frustrated by 1970s-era technology(nytimes.com)}}</ref> As one instructional book on JCL asked, "Why do even sophisticated programmers hesitate when it comes to Job Control Language?"<ref name="jcl-self"/>  The book stated that many programmers either copied control cards without really understanding what they did, or "believed the prevalent rumors that JCL was horrible, and only 'die-hard' computer-types ever understood it" and handed the task of figuring out the JCL statements to someone else.<ref name="jcl-self">Ashley and Fernandez, ''Job Control Language'', pp. vii–viii, back cover.</ref>  Such an attitude could be found in programming language textbooks, which preferred to focus on the language itself and not how programs in it were run.  As one [[Fortran IV]] textbook said when listing possible error messages from the [[WATFOR]] compiler: "Have you been so foolish as to try to write your own 'DD' system control cards? Cease and desist forthwith; run, do not walk, for help."<ref>{{cite book | title=Introduction to FORTRAN IV Programming: Using the WATFOR/WATFIV Compilers | first=John M. | last=Blatt | publisher=Goodyear Publishing Company | location=Pacific Palisades, California | date=1971 | page=276 | isbn=0-87620-440-X}}</ref>

Nevertheless, some books that went into JCL in detail emphasized that once it was learned to an at least somewhat proficient degree, one gained freedom from installation-wide defaults and much better control over how an IBM system processed your workload.<ref name="jcl-self"/><ref name="asm-jcl"/>  Another book commented on the complexity but said, "take heart. The JCL capability you will gain from [the preceding chapter] is all that most programmers will ever need."<ref name="asm-jcl">McQuillen, ''System/360–370 Assembler Language'', pp. 406–407.</ref>