IEFBR14

From Wikipedia, the free encyclopedia
Jump to: navigation, search

IEFBR14 is an IBM mainframe utility program. It runs in all IBM mainframe environments derived from OS/360, including z/OS. It is a placeholder whose purpose is to do nothing. As it turned out, over the years, its attempt to do nothing was too concise and would cause problems with related tools, leading to the slight expansion of the program.

Purpose[edit]

Allocation[edit]

On OS/360 and derived mainframe systems, most programs never specify files (usually called datasets) directly, but instead reference them indirectly through the Job Control Language (JCL) statements that invoke the programs. These data definition (or "DD") statements can include a "disposition" (DISP=...) parameter that indicates how the file is to be managed — whether a new file is to be created or an old one re-used; whether the file should be deleted upon completion or retained; etc.

IEFBR14 was created because while DD statements can create or delete files easily, they cannot do so without a program to run. 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.

IEFBR14 can thus be used to create or delete a data set using JCL.

Deallocation[edit]

A secondary reason to run IEFBR14 was to unmount tapes that had been left mounted from a previous job, perhaps because of an error in that job's JCL or because the job ended in error. In either event, the system operators would often need to demount the tapes, and a started task – DEALLOC – was provided for this purpose.

Simply entering the command

S DEALLOC

at the system console would run the started task, which consisted of just one step

//STEP01    EXEC PGM=IEFBR14

Naming[edit]

The "IEF" derives from a convention on mainframe computers that programs supplied by IBM were grouped together by function or creator and that each group shared a three-letter prefix. In OS/360, the first letter was almost always "I", and the programs produced by the job management group (including IEFBR14) all used the prefix "IEF". Other common prefixes included "IEB" for dataset utility programs, "IEH" for system utility programs, and "IEW" for program linkage and loading.

As explained below, "BR 14" was the essential function of the program, to simply return to the operating system. This portion of a program name was often mnemonic — for example, IEBUPDTE was the dataset utility (IEB) that applied updates (UPDTE) to source code files, and IEHINITT was the system utility (IEH) that initialized (INIT) magnetic tape labels (T).

As explained further in "Usage" below, the name "BR14" comes from the IBM assembler-language instruction, which by convention is used to "return from a subroutine". Most early users of OS/360 were familiar with IBM Assembler Language and would have recognized this at once.

Usage[edit]

Example JCL would be :

//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

To create a Partitioned Data Set:

//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

Implementation[edit]

IEFBR14 consisted initially of a single instruction a "Branch to Register" 14. The mnemonic used in the IBM Assembler was BR and hence the name: IEF BR 14.

The linkage convention for OS/360 and its descendants requires that a program be invoked with register 14 containing the address to return control to when complete, and register 15 containing the address at which the called program is loaded into memory; at completion, the program loads a return code in register 15, and then branches to the address contained in register 14.

The original version of the program didn't alter register 15 at all. Since the program was not loaded at address zero (as that address range is reserved for hardware use), the return code was not zero. Hence, a second instruction had to be added to clear the return code so that it would exit with the correct status.

The machine code for the modified program is:

        SR    R15,R15  put zero into register 15 (return code)
        BR    R14      branch to the address in register 14 (return to scheduler)

History from the RISKS Digest[edit]

Here is an article contributed by John Pershing to the RISKS Digest[1] that explains some of the history of IEFBR14. Note that there is an error in the final version of the code as posted—it contains the instruction BR GO, however GO is an instruction label, not a register. The correct code would be B GO. As of November 2009, the code is once again the very brief second version.[citation needed]

See also[edit]

References[edit]

  1. ^ Pershing, John (1988-01-25). "Safe programming languages". RISKS Digest. Retrieved 2006-10-12. 

External links[edit]