Everything about IEFBR14 utility

It takes one full blog post to list out (almost) everything that can be done using a utility which is widely known as a program that does nothing. Ironic! 😀

Yup! I'm talking about IBM's IEFBR14 utility. 

Table of Contents 📚

Use the links given below to navigate to various sections of this post.

• Introduction
• Using IEFBR14 utility to create and delete datasets
• What happens when you provide a GDG base in IEFBR14 utility with DISP=(MOD,DELETE,DELETE)?
• What happens when you provide a PDS member in IEFBR14 utility with DISP=(MOD,DELETE,DELETE)?
• Uncataloging a dataset using IEFBR14 utility
• Running an IEFBR14 JCL from Zowe CLI
• Conclusion

Introduction 

When IEFBR14 is invoked, it branches to the address in Register 14, which returns back control to the operating system. The Assembler instruction to do this is BR 14. That's how this utility got the name as IEFBR14.

When IEFBR14 is called, it immediately returns back the control to the operating system with a completion code of 0. By returning the control to z/OS, IEFBR14 allows the system to process the disposition parameter on any DD statements that are specified along with the EXEC statement. We're simply exploiting this functionality of IEFBR14 for the creation and deletion of datasets. 

IEFBR14 was created because while DD statements can create or delete files easily, they cannot do so without a program to be run due to a certain peculiarity of the Job Management system, which always requires that the Initiator actually execute a program, even if that program is effectively a null statement. The program used in the JCL does not actually need to use the files to cause their creation or deletion — the DD DISP=... specification does all the work. Thus a very simple do-nothing program was needed to fill that role.

- Quoted text from Wikipedia.

Using IEFBR14 utility to create and delete datasets 

IEFBR14 is typically used for creating and deleting datasets. A sample JCL is shown below. 

 ****** ***************************** Top of Data ******************************  
 000001 //Z01071A JOB 1,NOTIFY=&SYSUID                       
 000002 //*                                     
 000003 //STEP1  EXEC PGM=IEFBR14                         
 000004 //DEL01  DD DSN=Z01071.PS.A,                       
 000005 //     DISP=(MOD,DELETE,DELETE),                    
 000006 //     SPACE=(CYL,(1,0),RLSE)                      
 000007 //NEW01  DD DSN=Z01071.PS.B,                       
 000008 //     DISP=(NEW,CATLG,DELETE),                     
 000009 //     SPACE=(CYL,(1,0),RLSE),                     
 000010 //     DCB=(LRECL=80,RECFM=FB,BLKSIZE=800)                                         
 ****** **************************** Bottom of Data ****************************  

IEFBR14 job step usually consists of an EXEC statement and DD statement for each dataset that we want to process.

As datasets are being referenced in each DD statement, a DISP parameter SHOULD be accompanied. 

Creation of datasets can also be done in foreground mode - 3.2 Data Set Utility panel - from ISPF. IEFBR14 utility is used when we want to create or delete the datasets as part of batch run.  

Creating a dataset using IEFBR14 utility

The JCL to create a new dataset using IEFBR14 utility is as follows: 

 ****** ***************************** Top of Data ******************************  
 000001 //Z01071A JOB 1,NOTIFY=&SYSUID                       
 000002 //*                                     
 000003 //STEP1  EXEC PGM=IEFBR14                         
 000004 //NEW01  DD DSN=Z01071.NEW.DATASET,                    
 000005 //     DISP=(NEW,CATLG,DELETE),                     
 000006 //     SPACE=(CYL,(1,0),RLSE),                     
 000007 //     DCB=(LRECL=80,RECFM=FB,BLKSIZE=800)                                          
 ****** **************************** Bottom of Data ****************************  

The DD statement named as NEW01 creates a new, empty dataset called Z01071.NEW.DATASET. All the information necessary to create the dataset has been provided in the JCL. 

DISP=(NEW,CATLG,DELETE) - creates a new dataset and catalogs it under normal termination. The dataset will be deleted if the job is terminated abnormally.

BLKSIZE of 800 is provided because the dataset created when providing BLKSIZE=0 may not be opened for view/edit as the system issues 'Invalid block size' message.

Click on the image for a larger version.

System issues 'Invalid block size' message when the dataset is created with BLKSIZE=0.

What happens when you try to create a dataset using IEFBR14 utility but without providing a DCB parameter in the DD statement 🤔?

The dataset gets created but it's not usable. Let's look at the dataset information.

 

Data Set Information shows the record format as ?, Record length and Block Size as 0.

Deleting a dataset using IEFBR14 utility

The JCL to delete an existing dataset before its creation is as follows: 

 ****** ***************************** Top of Data ******************************  
 000001 //Z01071A JOB 1,NOTIFY=&SYSUID                       
 000002 //*                                     
 000003 //STEP1  EXEC PGM=IEFBR14                         
 000004 //DEL01  DD DSN=Z01071.PS.A,                       
 000005 //     DISP=(MOD,DELETE,DELETE),                    
 000006 //     SPACE=(CYL,(1,0),RLSE)                      
 ****** **************************** Bottom of Data ****************************  

The DD statement named as DEL01 deletes an existing dataset. If the dataset doesn't exist, MOD disposition creates the dataset and deletes it. Hence, SPACE parameter is provided. 

💣The job will fail with JCL error if the DD statement has got a DISP=(MOD,DELETE,DELETE) without SPACE= parameter and the dataset doesn't exist. 

SPACE= parameter may not be necessary if you're trying to delete an already existing dataset with DISP=(MOD,DELETE,DELETE).

DISP=(OLD,DELETE,DELETE) without a SPACE= parameter can also be coded if you're pretty sure about the existence of a dataset before running the utility job to delete and re-create the dataset.

What happens when you provide a GDG base in IEFBR14 utility with DISP=(MOD,DELETE,DELETE) 🤔?

Let's try this out!

I've created a GDG base named Z01071.TEST.GDG with 3 generations.  

The JCL is as follows:

 ****** ***************************** Top of Data ******************************  
 000001 //Z01071A JOB 1,NOTIFY=&SYSUID                       
 000002 //*                                     
 000003 //STEP1  EXEC PGM=IEFBR14                         
 000004 //DEL01  DD DSN=Z01071.TEST.GDG,                     
 000005 //     DISP=(MOD,DELETE,DELETE)                     
 ****** **************************** Bottom of Data ****************************  

The JESYSMSG listing after the completion of the job is shown below.

Just the generations that are part of the GDG base gets deleted; not the GDG base itself. 

💡 If you want to delete the GDG base in batch run, IDCAMS utility with DELETE command can be used. 

What happens when you provide a PDS member in IEFBR14 utility with DISP=(MOD,DELETE,DELETE) 🤔?

Let's experiment!

I've created a PDS named Z01071.TEST.PDS with 3 members in it. 

Let's try to delete the first member (MEMBER1) using the following JCL. 

 ****** ***************************** Top of Data ******************************  
 000001 //Z01071A JOB 1,NOTIFY=&SYSUID                       
 000002 //*                                     
 000003 //STEP1  EXEC PGM=IEFBR14                         
 000004 //UNCAT01 DD DSN=Z01071.TEST.PDS(MEMBER1),                 
 000005 //     DISP=(MOD,DELETE,DELETE)                     
 ****** **************************** Bottom of Data ****************************  

The results are pretty surprising. Thank god, I didn't store anything important in the test PDS 😀.

The entire PDS is deleted. 

Uncataloging a dataset using IEFBR14 utility

There is a difference between uncataloging a dataset and deleting a dataset. 

When a dataset is uncataloged, it's removed from the catalog so that if you search for the dataset from the Data Set List Utility (=3.4) just by providing the dataset's name, you will not be able to find the dataset. You should also provide the Volume Serial number the dataset is residing upon.

 

Whereas, if a dataset is deleted, it's removed from VTOC (Volume Table of Contents) and the dataset may not be retrieved.   

Remember that both SMS and non-SMS data sets can be created and deleted using IEFBR14 utility. Only non-SMS data sets can be cataloged and uncataloged.

Let's try to uncatalog a dataset using IEFBR14 and the JCL is as follows: 

 ****** ***************************** Top of Data ******************************  
 000001 //Z01071A JOB 1,NOTIFY=&SYSUID                       
 000002 //*                                     
 000003 //STEP1  EXEC PGM=IEFBR14                         
 000004 //UNCAT01 DD DSN=Z01071.INPUT.PS.A,                    
 000005 //     DISP=(OLD,UNCATLG)                        
 ****** **************************** Bottom of Data ****************************  

The JESYSMSG listing after the completion of the job is shown below.

Z01071.INPUT.PS.A dataset is uncataloged. 

Now that the dataset is uncataloged, let's try to search for the dataset just by providing the dataset's name. 

When we try to search for the dataset just by providing its name, No data set names found.

When we provide the Data set name as well as Volume Serial no., the dataset is listed. 

To catalog the dataset using IEFBR14 utility, the following JCL can be used. 

 ****** ***************************** Top of Data ******************************  
 000001 //Z01071A JOB 1,NOTIFY=&SYSUID                       
 000002 //*                                     
 000003 //STEP1  EXEC PGM=IEFBR14                         
 000004 //UNCAT01 DD DSN=Z01071.INPUT.PS.A,                    
 000005 //     DISP=(OLD,CATLG),                        
 000006 //     UNIT=3390,                            
 000007 //     VOL=SER=VPWRKB                          
 ****** **************************** Bottom of Data ****************************  

Note: The UNIT and VOL=SER= parameters must be provided to catalog a dataset.

Running an IEFBR14 JCL using Zowe CLI

Let's put everything (creating, deleting, cataloging and uncataloging) together in a JCL, store it as a local file (.txt file) in Desktop and try to invoke the local file using Zowe CLI (Command Line Interface).

Prerequisites:

• Access to Zowe and z/OS MF (I've used the access obtained as part of Master the Mainframe 2020). 
• Zowe CLI must be installed on the system (For additional Zowe CLI documentation, visit https://docs.zowe.org)

Let's create a text file with the following contents. 

 //Z01071A JOB 1,NOTIFY=&SYSUID        
 //*                      
 //STEP1  EXEC PGM=IEFBR14          
 //DEL01  DD DSN=Z01071.PS.A,         
 //     DISP=(MOD,DELETE,DELETE)      
 //UNCAT01 DD DSN=Z01071.INPUT.PS.A,      
 //     DISP=(OLD,UNCATLG)         
 //DEL02  DD DSN=Z01071.TEST.GDG,       
 //     DISP=(MOD,DELETE,DELETE)      
 //DEL03  DD DSN=Z01071.TEST.PDS(MEMBER1),  
 //     DISP=(MOD,DELETE,DELETE)   

The file is saved on my Desktop and it's named as IEFBR14.txt.

Zowe CLI is installed on your own computer, not on the mainframe. You'll use Zowe CLI to interface with Zowe and z/OSMF which is running on the mainframe. 

Steps to submit a JCL stored in a .txt file using Zowe CLI  are as follows: 

1. Open Command Prompt and type zowe. You'll get back a description, a listing of command groups, and options. 

Using the Zowe CLI. 

2. We have to use zos-jobs group to submit a JCL. Type zowe zos-jobs --help-examples  to view some examples. 

3. To submit a JCL from a local file, we should use the command, 

zowe zos-jobs submit local-file "IEFBR14.txt".

Upon the submission of the command, a status bar is shown submitting the local file to z/OS. 

Zowe CLI shows the JobID and the Jobname of the submitted job.

Let's use the JobID to locate the job from Zowe Explorer plug-in in VS Code. 

The JOBS Section on the left side bottom of the picture shows that the job with JobID as JOB04256 completed with return code 0. The JESYSMSG is opened on the right side using the Z Open Editor plug-in.  

Conclusion

Throughout this post, you have witnessed the uses of IEFBR14 utility. Most of the JCL's given in this post were commonly used on the sites that I've worked so far. If I had missed anything, please let me know through the Comments section below. Thx 👍