IEFBR14

IEFBR14
Company type	Utility program
Industry	Computer software
Headquarters	United States
Products	Mainframe utility for dataset allocation and deallocation

IEFBR14 is an IBM mainframe utility available on all operating systems derived from OS/360, including z/OS. It functions as a no-operation program that always returns a zero exit code, comparable to the true command found in UNIX-like environments.

Dataset Allocation (Initialization)

In OS/360 and its successors, programs seldom refer to datasets directly; instead, datasets are specified through Job Control Language (JCL) DD statements. These statements incorporate a "disposition" parameter (DISP=...) that controls whether datasets are created, reused, or deleted.

IEFBR14 was created because JCL mandates the execution of a program to process these disposition parameters. Although the DD DISP=... clause manages dataset handling, an actual program must run to comply with the Job Management system’s requirement for program invocation. IEFBR14 meets this need by performing no functional operations while enabling dataset creation or removal through JCL.

Dataset Deallocation (Termination)

IEFBR14 is also utilized to release devices (such as tapes or disks) that remain mounted due to errors in previous jobs. System operators typically employ a started task—often named DEALLOC—which is triggered from the system console using the command: S DEALLOC This task usually consists of a single JCL step executing IEFBR14.

For proper operation, DEALLOC must be located in the system procedure library SYS1.PROCLIB. Furthermore, started tasks are required to be single-step jobs because the Started Task Control (STC) component of Job Management only accepts jobs with one step and refuses any multi-step jobs without exception: //STEP01 EXEC PGM=IEFBR14

Syntax Checking and Validation

On z/OS, when control branches to another program, the calling program's syntax is evaluated at that point.

Naming

The prefix "IEF" follows IBM mainframe naming conventions that categorize programs by their function or development group; programs related to Job Management, including IEFBR14, use this prefix. Other prefixes include "IEB" for dataset utilities, "IEH" for system utilities, and "IEW" for linkage and loading components. Key subsystems use prefixes such as "IEA" for the Operating System Supervisor and "IEC" for the Input/Output Supervisor.

The suffix "BR 14" refers to the fundamental operation of returning control to the operating system via the IBM assembler instruction "Branch to Register 14," a standard subroutine return command familiar to OS/360 users. Program names often combine these prefixes with mnemonic suffixes indicating their purpose (for example, IEBUPDTE applies updates; IEHINITT initializes tape labels).

Usage

Sample JCL for deleting a dataset: <syntaxhighlight lang="jcl"> //IEFBR14 JOB ACCT,'DELETE DATASET',MSGCLASS=J,CLASS=A //STEP0001 EXEC PGM=IEFBR14 //DELDD DD DSN=xxxxx.yyyyy.zzzzz, // DISP=(MOD,DELETE,DELETE),UNIT=DASD </syntaxhighlight>

Example JCL for creating a Partitioned Data Set: <syntaxhighlight lang="jcl"> //TZZZ84R JOB NOTIFY=&SYSUID,MSGCLASS=X //STEP01 EXEC PGM=IEFBR14 //DD1 DD DSN=TKOL084.DEMO,DISP=(NEW,CATLG,DELETE), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=80,DSORG=PO), // SPACE=(TRK,(1,1,1),RLSE), // UNIT=SYSDA </syntaxhighlight>

Implementation

IEFBR14 originally comprised just one assembler instruction: BR 14 ("Branch to Register 14"), which simply hands control back to the calling program. This corresponds to the standard System/360 instruction BCR 15,14.

According to OS/360 linkage conventions, register 14 stores the return address while register 15 holds the program’s load address. Upon finishing execution, programs place a return code into register 15 before branching back using register 14. Initially, IEFBR14 functioned as a placeholder control section that returned immediately without altering register 15.

In its earliest form, IEFBR14 was not an executable program but served as a stub during system generation (Sysgen). Since it was called through an instruction analogous to BALR 14,15, the return code in register 15 started as non-zero. Subsequent updates introduced an instruction to clear register 15, setting the return code to zero for a consistent exit status—an important refinement as developers increasingly relied on return codes in Job Control Language scripts.

The present machine instructions are:

        SR    R15,R15   ; reset completion code  
        BR    R14       ; return control

An alternative minimal machine code version is:

        SR    R15,R15   ; reset completion code  
        SVC   3        ; invoke EXIT supervisor call

This implementation corresponds with OS/360’s job-step handling, where tasks are initiated via SVC 42 and ended using the corresponding EXIT SVC 3 calls.

References

Trombetta, Michael & Finkelstein Sue Carolyn (1985). "OS JCL and utilities". Addison Wesley. page 152.