JCL (Job Control Language)

JCL_book

Whenever new mainframers referencing JCL on the “interweb” or attending an in-depth overpriced JCL course,  it seems that the Job Control Language is presented as something more difficult than it really is.

I blame this difficulty with not being fluent in what I call IBM’rish’.  A word I just made up referring to the cryptic  language IBMers and IBM manuals may use.  Signs of those fluent in IBM’rish include robot dance moves and entire conversations using only acronyms.

(yes, I’ve been accused of IBM’rish)

(The great thing about JCL is that I use an old reference book: "System 370 Job Control Language", by Gary DeWard Brown, that's been passed around at work over the years.

Published in 1977 and it's still relevant.  For a more up to date reference try googling "z/os mvs jcl reference".)

The JCL Structure

In its rawest form JCL can be broken down to these 3 basic parts:

  1. JOB CARD / OR PROC NAME
  2. EXEC STATEMENT
  3. DD (Data Definition) STATEMENT

I know there’s several veterans out there that will protest in rage that JCL is not as simple as that, but let’s examine some code and decide for ourselves.

JCL1
Here is a simple JCL job that uses TRSMAIN – this program will ‘TERSE’ files, which is IBM’s own compression.  Think of this as ‘.ZIP’ files, but for the mainframe.

Here’s the layout:

Lines:

000001 //JOBNAME  JOB ACCOUNTING_INFO,NOTIFY_USER,        
000002 //            CPU_TIME_LIMIT,MESSAGE_OUTPUT_CLASS, 
...                  REGION_STORAGE_SIZE_FOR_STEPS
000003 //LABEL    OUTPUT JES_OUTPUT_LOCATIONS 
000004 //* COMMENT
000005 //* COMMENT

000006 //TERSE    EXEC PGM=TRSMAIN,PARM=PACK 

...           'PARM=PACK means compress the files'

000007 //SYSPRINT DD LOCATION

...           'This Data Definition defines where all 
               messages from the program are sent.'    

000008 //INFILE   DD THE_FILE_LOCATION_AND_SHARING_DETAILS
000009 //OUTFILE  DD THE_NEW_OUTPUT_FILE_LOC_AND_DETAILS
...
000013 /*     'The delimiter.  The "end-of-file" statement'

Nothing too complicated.  This job will compress the ‘BFCU.TOMZOS.ICAT.INSTLIB‘ library to a single file called ‘USER123.BFCU.TOMZOS.ICAT.INSTLIB.PACKED

Then this single file could be FTP to IBM or somewhere else.

After ‘Submit‘, or ‘SUB‘ on the command line above it’s sent to JES2 (Job Entry Subsystem) and if there’s no errors or syntax mistakes will run successfully with a RC (Return Code) = CC (Condition Code) 0000.

Here’s the unreadable output resulting from this job:

new_packed_dataset

JCL PROCS and SYMBOLS

A similar job to ‘UNPACK‘ this TERSE file would be necessary.

JCL2_unpack

Whoa!!!  Something is different in this job!

We’ve stepped it up a notch and now we have the same basics (JOB CARD, EXEC, DD) however we’ve added some JCL symbols and a procedure (PROC).

Lines of interest:

000006 // SET HLQ='USER123'
...
000008 //UNPKSS PROC DIR=',400'
...
000011 //INFILE DD DISP=SHR,DSN=&HLQ..&NSMPIN..PACKED
000012 //OUTFILE DD DISP=(NEW,CATLG),
                   DSN=&HLQ..&NSMPIN..UNPACKED,
000013 //          UNIT=SYSDA,SPACE=(TRK,(300,300&DIR),
                   RLSE
...
000015 // PEND
...
000017 //F01 EXEC UNPKSS,NSMPIN='BFCU.TOMZOS.ICAT.INSTLIB'

Basically the difference and flow with this job is:

  1. start JOB at the JOBCARD on line 000001
  2. EXECute procedure (PROC) UNPKSS on line 000017
  3. PROC UNPKSS begins on line 000008 and ends on line 000015
  4. PROC UNPKSS puts the &HLQ. value set on line 000006, which is ‘USER123’
  5. PROC also reference the PARM that was pass on line 000017, ‘NSMPIN=’BFCU.TOMZOS.ICAT.INSTLIB
  6. line 000011 is translated to:  USER123.BFCU.TOMZOS.ICAT.INSTLIB.PACKED
  7. line 000012 is translated to: USER123.BFCU.TOMZOS.ICAT.INSTLIB.UNPACKED

You’ll notice lines 000018 to 000025 were commented out (‘//*‘).  If there was a list of files that required to be UNPACKED but with different names, the comments (‘//*’) would be replace with ‘//’ and the statement would run with the PARMS passed, as would be reflected in the UNPKSS PROC.

Hopefully this gives you a taste of the power and simplicity of JCL.

Happy coding and job submitting!

Transferring files via FTP to z/OS seems to cause quite a bit of trouble with new Millennial Mainframers. This is partly because it’s not very intuitive sending and receiving files from the mainframe. Fortunately, there are a few ways to FTP.

One of the easiest ways is using IBM’s Personal Communications (or PCOMM). PCOMM is a 3270 terminal emulator, which is a client-side application that many mainframers use to communicate with the host. In some ways, PCOMM is a software implementation of the Ninjutsu (忍術) technique Hensōjutsu (変装術), which involved disguise, impersonation, and infiltration. From the perspective of the mainframe, z/OS thinks that it’s communicating with a traditional 3270 “green screen” terminal. However, in reality, the mainframe is really communicating with a Macbook Air or Microsoft Surface in disguise.

One of the great things about PCOMM is that is has FTP functionality built right into it. That’s right! PCOMM’s got additional Ninjutsu (忍術) powers!

In this case, PCOMM uses a host file-transfer program called IND$FILE to practice a technique of file transfer resembling Shurikenjutsu (手裏剣術). However, instead of throwing deadly weapons at the heart of your enemies, IND$FILE throws your choice of files into the heart of the z/OS filesystem!

If you’d like to learn more about the secretive art of IND$FILE, check out this great document from GSF Software.

For more general information about PCOMM, go here.

Send File to Host Example

Let’s go ahead and send a file to the mainframe. In this case, we’re going to send up a snapshot of the Earth taken by an Astronaut on the Apollo 17 mission. Since the System/360 mainframe was a key technology used by NASA to send men to the moon, this is pretty appropriate!

To follow along, grab this photo from Wikipedia here:

To start the transfer,  go to the “ISPF Command Shell” (Option 6 from the ISPF Primary Option Menu). Once on the panel, make sure that the cursor is on the beginning of the command line.

Then click on Actions -> Send File to Host…

This will open up Send Files to Host dialog.

Click on the ‘Browse…’ to select the Earth photo from your PC.

You’ll notice by default that the dialog automatically generates a Host File Name based on the file name appended with “bin” to signify that this is a binary file.  However, this will not work, as “The_Earth_seen_from_Apollo_17.jpgbin” does not follow z/OS dataset naming conventions.

According to convention, a z/OS dataset (file) is uniquely identified by a series of strings between one and eight characters, each separated by the dot (“.”) operator.  In the mainframe world, these names are each called “level qualifiers.” The leftmost or beginning string is called the dataset’s “high-level qualifier.” The subsequent middle strings are called “middle-level” qualifiers. The rightmost or last string is called the dataset’s “low-level qualifier”.

For example, in the z/OS dataset PAULY01.WORK.CLIBS:

  • PAULY01 is the High-Level Qualifier
  • WORK is a Middle-Level Qualifier
  • CLIBS is the Low-Level Qualifier
Oftentimes, the high-level qualifier is shared between numerous datasets to act as a form of organization similar to a directory.  The low-level qualified is often used to show the type of data stored in the dataset, similar to a file extension.

To correct this naming issue, rename the photo to ‘[USERID].EARTH,’ where USERID is your current z/OS user ID. I also make sure that “binary” is selected in the Transfer Type drop-down box, since with is binary file (.jpg) and not a text file.

It is critical to select “binary” because z/OS uses EBCDIC for character encoding, which is different from the ASCII scheme used by other platforms. Selecting “text” in the Transfer Type drop-down box causes the file to be translated between the two schemes to ensure the that text is readable by mainframe tools such as ISPF Editor. If you select this for your image, the binary data in the jpg photo of the Earth will become scrambled and unreadable.

Once the dialog is filled out, click “Update in List” to update the transfer file changes.

Finally, click “Send” to initiate the transfer.  The pop-up window will disappear when the transfer is complete.

Let’s check to make sure that our photo actually made it into z/OS. Go back to the “ISPF Primary Option Menu” and select option “3 Utilities” and “4 Dslist” to enter the DSList utility.  Once in DSList, enter [USERID].EARTH in the panel and hit execute. We now can see our file in z/OS.

We can go ahead an browse the dataset, but we’ll only see the JPG binary data associated with the Apollo 17 snapshot of Earth. Since z/OS doesn’t have a GUI like Windows, Linux, or Mac OS X, there is no direct way to view the photo directly.

FTP with Windows’ FTP.exe

Now that we’ve uploaded the binary data of “Earth.jpg” to z/OS dataset named [USERID].EARTH, let’s go ahead and download the file back to our PC using the Microsoft FTP Utility so that we can make sure that the picture is intact.
To do this, open up a DOS prompt (Start > Run > cmd) and enter ftp to start ftp.exe

Then enter the ftp command “open” followed by the IP address or DNS name of your mainframe.

If you don’t know this, then you’ll have to talk with your network admin to find out the IP or DNS name (or if it’s even activated).

In this example, we connected to host at “server.ca”

After connecting to the mainframe, enter your login userid (BBBBBPG) and password.

Notice that upon connecting, your “working directory” is set to BBBBBPG. This “working directory” is really the High-Level Qualifier of the datasets in the filesystem. Since a common z/OS convention is to set the high level qualifier of datasets to the USERID that owns the dataset, this is logical.

Similar to when we uploaded the photo, change the transfer type to “binary” by entering the FTP command ‘bin’

Finally, receive the file from the host by issuing ‘get earth’

Notice the message ‘Sending data set BBBBBPG.EARTH.’

At this point, the transfer is successful. The file is now on our local hard drive. However, the High-Level Qualifier of the file has been stripped off, so the file is called “earth” without a file extension.

To help your operating system understand that this file contains picture data, rename the file to add the “.jpg” file extension in the DOS prompt with the command “rename oldfile newfile.jpg”

Now, we can open the file and automatically using a photo viewer.  Success!  The entire Earth is there.

From coast to coast and continent to continent, you are now the Mainframe Ninja!

Paul Gamble
Graduate of Georgian College, Computer Programmer Analyst program

After doing a four month internship with the Canadian Government, Paul was offered the rare opportunity to work in their on-site Data Centre. Starting out as an Operator for four years before becoming a Systems Programmer rolling out different independent software vendors (ISVs) and different IBM Tivoli products for monitoring and automation to the z/OS platform. Paul enjoys the constant learning the z/OS operating system offers in comparison to other platforms. On weekends you’ll find Paul getting his adrenalin fix by instructing and coaching at the local skydiving drop-zone.
Connect with Paul on LinkedIn

z/OS Kung-fu Moves

#1 ISPF Combo moves 

By far the easiest way to master z/OS is to learn how to navigate and edit with ISPF really quickly, and the best way to bring swiftness to ISPF is through some choice combo moves.
Screenshot here of the ISPF Primary Option Menu.
I’m going to open up a dataset and play around to show some simple yet effective combo moves to get things done faster in ISPF.
To open a dataset for editing, enter one the following on the Option ===> prompt
           
            =3.4 or =3;4
These are shortcuts that concatenate the commands for going to the “3” Utilities and then the “4  Dslist panel.  This allows you to quickly navigate to DSList, which is one of the most powerful utilities in ISPF.

Once the “Data Set List Utility” is displayed, I can enter a Data Set name.  In this case, I’ve forgotten the exact Low-level Qualifier (LLQ) of my Data Set that I’d like to select. However, since I remember part of the dataset qualifiers, I can use wildcards “*” to help me out.  By entering BS9U.DEVT3.CLIB*, I can see all matching datasets.

Note: An LLQ is the last qualifier in a data set.  It’s the segment after the last “.”

This brings up a list of all the datasets that matched my dataset name parameters.  In this case, I see CLIBANDER, CLIBJAS, CLIBJAS3, CLIBPAU, CLIBRIC, CLIBSUT, and CLIBTOM

Hmm, it seems that I still can’t remember which of these data sets might contain the data I’m interested in, let alone the name of the particular member! 
Rather than thumbing through each data set, I decide to use a little-known command:
SRCHFOR [string]
This command invokes SuperC  [=3.12] to search for that string.  In this case I’m looking for the member that has the word “Coffee” in it.

The string is found in one of the data sets, in this case BS9U.DEVT3.CLIBPAU

Once I know the data set, there are two ways to find which member I want. 

Firstly, I can look in the output data set from SuperC, which is stored my default at userid.SRCHDSL.LIST


Secondly, I can simply  an “E” (for edit) next to the dataset, in this case BS9U.DEVT3.CLIBPAU, and issue SRCHFOR COFFEE again.  This time the search will be executed within the context of the data set, identifying the particular member I’m interested in.

It turns out that the member “TIMMIES” is the one I want.  (Here in Canada we drink a lot of Tim Horton’s coffee).

Now it’s time to edit this member, I place an “E” (edit) next to TIMMIES to edit this lovely member…a simple REXX program I wrote a few years ago available @ http://paulywill.com/mainframes/first_rexx_program

Since it’s been a few years since I’ve written this REXX EXEC, perhaps I’ve since given up coffee and switched to tea.  So naturally I’ll have to change every instance of “Coffee” to “Tea”.
First I want to see how many instances of the string “Coffee” are in this program using the find command:
F all coffee

Notice that the results are not case sensitive.
From the “ISPF Edit and Edit Macros ISPF Edit and Edit Macros” manual:

Once I’ve selected all of the strings I’d like to replace using using the FIND (or F) command, I can then change all the instances of “Coffee” to “Tea with the CHANGE (or C) command as follows:
C all Coffee Tea


Mmm… refreshing Canadian Tea.

Now that Tea Time is over, let’s add some more Kung-Fu

First, go ahead and change the strings back from tea to coffee using the following commands:

F all Tea
C all Tea Coffee

Now that we’re back to coffee, let’s assume I just want to display the lines with instances of  “coffee” and exclude all other lines of text in this member.

I could first use the EXCLUDE ALL (or X ALL) command to hide all of the lines of text:
xall

Then I could follow that with a find command for all lines with the String Coffee (here we specify ‘all’ to find all result):
fcoffee all

Then we can hide all of the ugly “Line(s) not Displayed” overlays by specifying:
            x hide

Let’s speed things up…

Let’s setup some of our keys so we’ll never have to enter those commands again.
Enter “Keys” at the command line to open up the “Keylist”.

If you scroll down (F8) you’ll notice it goes up to F24.  By pressing shift you can access this extra set of F keys for your own use.
For example you see that I have designated:
           
  • F21 (Shift + F9) has the SWAP command to switch between split screens (we can cover setting up split screens like a super star on another Kung-Fu Move) 
  • F22 (Shift + F10) has a reset command (RES) 
  • F23 (Shift + F11) has the commands we just entered EXCLUDE ALL; HIDE X; 
  • F24 (Shift + F12) has the CRETRIEV command which I use ALL THE TIME!!!  If the cursor is not on the command line it will place the cursor there; if I keeping hitting the key it will cycle through the last commands I entered,
Back to our example I could have:

  1. Opened the member with EDIT
  2. Excluded all the lines and hide exclude information with my F23 key (x all;hidex)
  3. Used the FIND command to find all the instances (f all coffee) 
  4. Made all the changes (C all Coffee Tea)
  5. Pressed F22 to reset the screen and see our changes 
  6. Saved changes with the SAVE command (my F4 key)
Boom!  All done.
Knowing some basic ISPF navigation, little known commands, and doing some basic KEY setup can speed things up.
For more Kung-Fu moves from others:
Google  “100 COOL MAINFRAME TIPS by Johnathan Jeban Martin”
Google “ISPF Hidden Treasures by Peter Van Dyke”

Flawless Victory!

Paul Gamble
Graduate of Georgian College, Computer Programmer Analyst program

After doing a four month internship with the Canadian Government, Paul was offered the rare opportunity to work in their on-site Data Centre. Starting out as an Operator for four years before becoming a Systems Programmer rolling out different independent software vendors (ISVs) and different IBM Tivoli products for monitoring and automation to the z/OS platform. Paul enjoys the constant learning the z/OS operating system offers in comparison to other platforms. On weekends you’ll find Paul getting his adrenalin fix by instructing and coaching at the local skydiving drop-zone.
Connect with Paul on LinkedIn