IEFBR14

From Wikipedia, the free encyclopedia

IEFBR14 is an IBM mainframe utility program that does nothing. It runs in all IBM mainframe environments derived from OS/360, including z/OS.

The requirement for this program was because in order for any program to use a file (what in IBM parlance is called a dataset, any file, it is necessary that the file be declared in JCL. Unlike, say, on PCs where one can, for example, open an existing file or save a new file (such as a word processing document or a spreadsheet) by naming it in an open or save statement or in response to an open or save dialog on Microsoft Windows, in general, a program running on IBM's mainframe operating systems (such as the batch environment OS/360) could not directly create new files, access existing files, or even delete no-longer-needed files, instead a program must reference a file through a name on a DD statement in JCL, and the operating system either finds the file (if it exists), or creates it (if it doesn't). Also, programs could not delete existing files, that can only be done via JCL.

However, the problem is that JCL cannot do anything with files either, unless the JCL executes some program, even a program that never uses those files or which does nothing. Thus, in order to provide the ability to create new files or to delete no longer needed existing files, it is necessary to run a program from JCL that essentially does nothing but return to the operating system. This was the reason for creating the program IEFBR14.

As explained below, BR14 was the essential function of the program, to simply return back to the operating system. The prefix IEF was a convention in IBM programs or classes of programs the corporation released for use on Mainframe computers be assigned a 3-letter identifier preceding the name of the program or type of function, and the first letter is always 'I', e.g. the programs that deal with VSAM files all begin with 'IDC' (IDCAMS), and the COBOL Compiler's prefix is 'IKF' (IKFCBL00), so this particular program was assigned to the class of programs given the prefix 'IEF'.

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

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

It didn't set the return code and 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)

1 History of IEFBR14, from the RISKS Digest
2 See also
3 References
4 External links

[edit] History of IEFBR14, from the RISKS Digest

Here is an article contributed by John Pershing to the RISKS Digest that explains some of the history of IEFBR14:^[1]

From: John Pershing <PERSHNG@ibm.com>
Date: 25 Jan 88 11:41:42 EST

You can't even necessarily write the null program without encountering
problems...

There is an apocryphal story about the large number of attempts that were
required in order to produce a "correct" version of MVS's null program,
IEFBR14 (this was done back in the days when MVS was still called OS).
As with all MVS programs, IEFBR14 is called using the standard system
calling conventions, and all it has to do is return successfully.

The first version was something like this:

         IEFBR14 START
                 BR    14       Return addr in R14 -- branch at it
                 END

First bug:  A program indicates its successful completion by zeroing
register 15 before returning; this version of the null program "failed"
every time.  Try it again:

         IEFBR14 START
                 SR    15,15    Zero out register 15
                 BR    14       Return addr in R14 -- branch at it
                 END

Much better.  However, this caused some-or-other problems with the linkage
editor, since the END statement didn't specify the primary entry point
of the routine.  Version three:

         IEFBR14 START
                 SR    15,15    Zero out register 15
                 BR    14       Return addr in R14 -- branch at it
                 END   IEFBR14

At least now, the null program was functionally correct.  However, dump
analysis was impeded because the program didn't include its own name in
the source code, as an "eyecatcher" (this is a time-honored convention).
Null program, mark four:

         IEFBR14 START
                 USING IEFBR14,15  Establish addressability
                 B     GO          Skip over our name
                 DC    AL1(L'ID)   Length of name
         ID      DC    C'IEFBR14'  Name itself
                 DS    0H          Force alignment
         GO      SR    15,15       Zero out register 15
                 BR    14          Return addr in R14 -- branch at it
                 END   IEFBR14

The next change had something esoteric to do with save-area chaining
conventions -- again, for the sake of conventions and to keep the dump
analysis tools happy.

Note that the "null program" has tripled in size:  both in terms of the
number of source statements and in terms of the number of instructions
executed!