Mainframes 360
The one stop destination for System Z professionals

Friday, January 22, 2010

Basic Framework of JCL

Q. My head’s spinning around the 3 JCL Statements : JOB, EXEC and DD. Could you tell me something more about them?
So, you’ve got the gist of the concept behind JCL, all the JCL that you going to write from hereon, maybe for the next 10-20 years, would be composed of three main statements :

//name JOB parameters...
//name EXEC parameters...
//name DD parameters...

Each of this JCL Statements have a label – a symbolic name assigned to them. Its like naming kids. Well, there could be so many boys in your area, but how do distinguish them? Of course, by their names.

In the same way, a JCL may contain a bunch of DD Statements, one for Input file, one for the output file, one for the error file. How do you tell them apart, by naming them. As a good practice, we always give names to all our JCL Statements. Names kinda help you to refer back to these statements in the future. You want to point out a particular JCL Statement to your friend, just spell out its name.

But, notice carefully, each label(name) is preceded with two slashes //. The two slashes are a JCL Statement’s signature. They indicate that the statement is a JCL Statement(one of JOB, EXEC, DD). Every JCL Statement wear the two slashes //. A naked statement without // won’t be treated as a JCL Statement.

Now, every JOB, EXEC and DD Statement has got these whole lot of parameters. What you’ll be learning throughout these tutorials is mostly the parameters. Parameters add stuff and meaning to the JCL Statement. 

Now, let me give you a booster, that’s going to help you organise the way you think about this JCL.

- JCL is made up of mainly JOB, EXEC and DD.
- JOB is easy to learn and use.
- EXEC is easy and fun to use.
- DD Statements take three forms
   1. DD Statements to read a file.(easy)
   2. DD Statements to write to the logs.(easy)
   3. DD Statements to create a new file(hard!); you’d have to learn parameters such as DISP, UNIT, DCB, SPACE and several others to code this.

Have a good look at this chart :

Image99[1]
Q. Let’s set this straight. You’ve got to give me an overview of the JOB Statement.
You code the JOB Statement at the start of any JCL you write. It tells the MVS Operating system, who’s the guy requesting the program to be sent to MVS for execution, where MVS should send the print output, how much reporting(level of detail) should MVS provide, and how important is the Job as opposed to other competing jobs.

You can even indicate things like memory and processing time limits on the JOB Statement.

You write the JOB statement starting with a name, which becomes the JOB Name. JOB Names are a big deal, because MVS keeps track of thousands of Jobs using Job Names.

The most general form of the JOB Statement is this :
//AGY0157A JOB ...other parameters

As a programmer or developer, when you code some jobs for executing the programs that you’ve written, the job-name that follows the slashes, is your TSO-userid followed by a single letter. Like my TSO-userid happens to be AGY0157, so I’ve coded the job-name as AGY0157A. By doing so, anyone who happens to look at these jobs will deduce, all Jobs of the format AGY0157* belong to(are owned by) the TSO User-id AGY0157. It becomes so much each easier to trace back/revert back to the owner. God forbidding, should your job fail for some reason, the operator can immediately find out, to whom the job belongs and contact the respective owner.

The content of your JOB Statement usually very stable. Once, you have established a JOB Statement, you can use it for most of your work. Sometimes, your project leader or client Manager may give you an account-number to use, so that the resources used to run your job, maybe charged to an appropriate account.(The example, I have written is going to use the Account-no A123)

You are going to use other parameters like CLASS, MSGCLASS, MSGLEVEL, NOTIFY, REGION, TIME, and PRTY in you JOB Statements. Hey wait, don’t hit on the gas right now, hold on for a while, I am going to discuss the JOB Statement at length in the next tutorial.

In the figure below, I’ve reproduced the JCL, I wrote to copy one file to another using IEBGENER Utility program. Notice, the two different styles of coding the parameters. You can code just one parameter on each line to make it more readable.

Image101[1] 
(a) You can code JCL with a compact JOB Statement and put several parameters on the same line (b) An easier to read-style, is to code one parameter on each line, leaving room for comments.
Q. Could you give me a brief idea about EXEC Statement too..?
The EXEC Statement is the engine of your JOB. The EXEC statement tells the MVS, which program to run. So, you use EXEC JCL Statement, to announce to the MVS, which program, you want to run.

//STEP01 EXEC PGM=IEBGENER

Like any other JCL Statement, you write the EXEC Statement starting with two slashes //. You assign a name/label to the EXEC Statement, for unique identification like STEP01, which is called Step-name.

Let us make no mistake in understanding that -
1. The step-name is just a name given to the EXEC Statement. The step-name could be omitted as well. However, its always good to name all your EXEC steps, so that you can always refer back to step later. This would count a lot, pretty important stuff, when you write multi-step jobs.

2. AS Shakespeare has said, what’s in a name? A step-name is just a name given to the EXEC Step. The name could be possibly anything at all, it doesn’t need to always start with //STEP prefix. You could also name your step as //QUASAR or //BARABARA or //COPYSTEP or any name of your choice. But most people would use a step-name which is meaningful, and conveys the meaning of the step.

3. The executable program that you want to run, should be specified after PGM.

You can code a lot of extra things on the EXEC Statement, such as REGION, TIME, COND, PARM and ACCT. I’ll give many more inputs to my readers, about these extra parameters, as you progress through the tutorials.

Image102[1]

In the above JCL, to copy the contents of a file to another file, using IEBGENER, when you take a glance at the JOB Statement, you would find that I’ve coded REGION and TIME Parameters on the JOB Statement. REGION and TIME specify memory space limit and time limit on the JOB. But guess what, if you code the REGION and TIME Parameter on the EXEC Statement, that allows you to specify a memory limit and time limit for that program or step only.
Q. Could you give me a brief overview of how DD Statement refers to files?
A program executed at a step can access zero, one or more Files(Datasets). For each dataset, the program accesses, you must code a DD Statement.

MVS frees and relieves the programmer/developer, from having to know the actual(real) name of the file, and other details about the files, while writing a COBOL or PL/I Program. The programmer is unaware of the real file. Instead in COBOL, he refers to the input file(s) and output file(s) only by their symbolic DD-names. COBOL Program refers to files by their smbolic dd-names. It is through the DD Statement in JCL, that assign actual physical files to these symbolic dd-names. Thus, the dd-names serve as an indirect reference to the actual file.

How symbolic dd-names are associated with actual, physical files, is explained in the diagram below.

Image104[1]

The COBOL Program refers to the files as INPUT-FILE and OUTPUT-FILE. In the JCL, you specify the actual(real) files in the DD-Statement, AGY0157.INPUT.DATA and AGY0157.OUTPUT.DATA. The common connecting link/bridge between them is the dd-name INPUTDD and OUTPUTDD.

In the COBOL Program, the INPUT-FILE and OUTPUT-FILE shall represent the file whose dd-names are INPUTDD and OUTPUTDD. In the Job JCL, the ddnames //INPUTDD and //OUTPUTDD are set to point to the files AGY0157.INPUT.DATA and AGY0157.OUTPUT.DATA. Thus, this helps establish a relationship. Thus, the COBOL Programmer and the one who writes the JOB; there should be common agreement amongst them, with regards to the dd-names. If the COBOL program expects an input file, with dd-name INPUTDD, which is not supplied in the JCL, this would be a JCL-Error.

The same applies to the IBM-supplied Utility programs like IEBGENER, SORT, IEBCOPY etc. The developers of IEBGENER assumed dd-name of input file as SYSUT1, and output file as SYSUT2. The //SYSUT1 and //SYSUT2 DD Statements must appear in your JCL. Thus, for built-in IBM Utility programs, there are some pre-defined dd-names, which you have to stick to.
Q. Could you give me a short description of the 3 different types of DD-Statements?
As I mentioned before, the 3 general categories of DD Statements are :
1. A DD Statement for reading a file/dataset
2. A DD Statement for recording/writing to the log(diary). MVS operating System keeps a log, a diary of notes of how each job ran, whether it was successful or a failure. With this DD Statement, you can scribble and write anything you wish to the log
3. A DD Statement for creating a new dataset, and writing to the file(dataset).
 
Let me explain this, with a concrete example. Click here to download this Job-Listing and try it out on your PC. -

Image105[1]
Reading a file or Dataset
The IEBGENER program expects to read the records from the Input file at the //SYSUT1 DD Statement. There’s nothing much to it, DD statement for reading records from an Input file is damn easy.

Creating a new Dataset, and writing records to it(Hard!!)
The IEBGENER program expects to write the records to the output file at the //SYSUT2 DD Statement. To create a new file/dataset in JCL, as you can observe, you need to code a lot of extra parameters like SPACE, UNIT, DCB etc.

Writing to the log
To make note in the logs(diary), to write any text to the logs, you code a parameter on the DD Statement called SYSOUT=*.  Logs are indicated by coding the parameter SYSOUT=* on the DD Statement.
 
While running your job, ,MVS keeps prepares a status report about how your program is running, its status, whether it succeeded or failed. Thus, this status report report messages are important, because they tell you whether the Job ran fine.

The MVS OS expects to write status report messages to the output file at //SYSPRINT DD Statement. By coding the SYSOUT=* parameter on //SYSPRINT DD statement, you redirect all MVS Messages to be recorded in the logs.

Image106[1]

To many people who are thrown to work at a mainframe computer on their first job, they feel lost. Mainframe people seem to speak a completely different language and that doesn't make life easy. What's more, the books and manuals are incredibly hard to comprehend.

"What on earth is a Mainframe?" is an absolute beginner's guide to mainframe computers. We'll introduce you to the hardware and peripherals. We'll talk about the operating system, the software installed on a mainframe. We'll also talk about the different people who work on a mainframe. In a nutshell, we'll de-mystify the mainframe.

Readers based in India, can buy the e-book for Rs. 50 only or the print book. International readers based in the US and other countries can click here to purchase the e-book.