Content deleted Content added
m →History of IEFBR14, from the [[RISKS Digest]]: Fixed format of cited message |
Link suggestions feature: 2 links added. |
||
| (122 intermediate revisions by 59 users not shown) | |||
Line 1:
{{Short description|"Do nothing" program on IBM mainframes}}
'''IEFBR14''' is a [[IBM mainframe utility programs|utility program]] that runs on [[Mainframe computer|mainframe computer]]s from [[IBM]]. It runs in all mainframe environments derived from [[OS/360]], including [[z/OS]]. It is a placeholder that returns the [[exit status]] zero, similar to the [[True and false (commands)|true]] command on [[Unix-like|UNIX-like]] systems.<ref name=":0">{{Cite web|url=https://www.ibm.com/support/knowledgecenter/zosbasics/com.ibm.zos.zdatamgmt/zsysprogc_utilities_IEFBR14.htm|title=IBM Knowledge Center|last=|first=|website=www.ibm.com|publisher=IBM Corporation|year=2010|access-date=2016-12-26}}</ref>
== Purpose ==
=== Allocation (also called initiation)===
On OS/360 and derived mainframe systems, most programs never specify files (usually called [[Data set (IBM mainframe)|dataset]]s) directly, but instead reference them indirectly through the [[Job Control Language]] (JCL) statements that invoke the programs. These data definition (or "<code>DD</code>") statements can include a "disposition" (<code>DISP=...</code>) parameter that indicates how the file is to be managed — whether a new file is to be created or an old one re-used; and whether the file should be deleted upon completion or retained; ''etc''.
IEFBR14 was created because while <code>DD</code> 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]].<ref>{{Cite web|url=http://www.miketaylor.org.uk/tech/oreilly/iefbr14.html#gsc.tab=0|title=True in a Nutshell Appendix: IEFBR14|last=Schmidt|first=Sebastian|date=2004-04-24|website=www.miketaylor.org.uk|publisher=Mike Taylor|access-date=2016-12-27}}</ref> The program used in the JCL does not actually need to use the files to cause their creation or deletion — the <code>DD DISP=...</code> 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 (also called termination)===
A secondary reason to run IEFBR14 was to unmount devices (usually tapes or disks) 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 unmount the devices, and a started task – <code>DEALLOC</code> – was often provided for this purpose.
Simply entering the command
S DEALLOC
at the [[system console]] would run the started task, which consisted of just one [[Job Control Language#Jobs.2C steps and procedures|step]]. However, due to the design of Job Management, DEALLOC must actually exist in the system's procedure library, SYS1.PROCLIB, lest the start command fail.
Also, all such started tasks ''must'' be a single jobstep as the "Started Task Control" (STC) module within the Job Management component of the [[operating system]] only accepts single-step jobs, and it fails all multi-step jobs, without exception.
//STEP01 EXEC PGM=IEFBR14
=== Parsing and validation ===
At least on z/OS, branching off to execute another program would cause the calling program to be evaluated for syntax errors at that point.<ref name=":0">{{Cite web|url=https://www.ibm.com/support/knowledgecenter/zosbasics/com.ibm.zos.zdatamgmt/zsysprogc_utilities_IEFBR14.htm|title=IBM Knowledge Center|last=|first=|website=www.ibm.com|publisher=IBM Corporation|year=2010|access-date=2016-12-26}}</ref>
== Naming ==
The "IEF" derives from a convention on [[mainframe computer]]s 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.<ref>{{Cite web|url=http://www.miketaylor.org.uk/tech/oreilly/more-iefbr14.html#gsc.tab=0|title=True in a Nutshell Appendix: IEFBR14: Clarification|last=Bagwell|first=David|date=2005-08-09|website=www.miketaylor.org.uk|publisher=Mike Taylor|access-date=2016-12-27}}</ref> Other major components were (and still are) "IEA" (Operating System Supervisor) and "IEC" ([[Input/Output Supervisor]]).
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 "'''B'''ranch (to the address in) '''R'''egister '''14'''", 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 ==
Example [[Job Control Language|JCL]] would be :
<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>
To create 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 consisted initially of a single instruction a "Branch to Register" 14. The mnemonic used in the [[IBM]] [[Assembly language#Assembler|Assembler]] was BR and hence the name: IEF '''BR 14'''. BR 14 is identically equivalent to BCR 15,14 (Branch Always [ mask = 15 = always ] to the address contained in general purpose register 14). BR is a pseudo instruction for BCR 15,[reg number]. The system assembler accepts many cases of such pseudo-instructions, as logical equivalents to the canonical System/360 instructions. The canonical instance of '''BR 14''' is '''BCR 15,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. But, initially IEFBR14 was ''not'' coded with these characteristics in mind, as IEFBR14 was initially used as a dummy control section, one which simply returned to the caller, not as an executable module.
The original version {{Citation needed|reason=What *exactly* is the "original version"? Is it the first public release on March 31, 1966? If so, then the text should so state.|date=July 2025}} of the program did not alter register 15 at all {{Citation needed|reason=This is folklore, not fact.|date=July 2025}} as its original application was as a placeholder in certain load modules which were generated during ''Sysgen'' (system generation), not as an executable program, per se. Since IEFBR14 was always invoked by the functional equivalent of the canonical '''BALR 14,15''' instruction, the return code in register 15 was always non-zero. Later, a second instruction was to be added to clear the return code so that it would exit with a determinate status, namely zero. {{Citation needed|reason=The assertion that a 2nd instruction was inserted "later" to "clear the return code" is folklore, not fact.|date=July 2025}} Initially, programmers were not using all properties of the Job Control Language, anyway, so an indeterminate return code was not a problem. However, subsequently programmers were indeed using these properties, so a determinate status became mandatory. This modification to IEFBR14 did not in any way impact its original use as a placeholder.
The [[machine code]] for the modified program is:
SR R15,R15 put zero completion code into register 15
BR R14 branch to the address in register 14 (which is actually an SVC 3 instruction in the Communications Vector Table)
The equivalent machine code, eliminating the BR for clarity, is:
SR R15,R15 put zero completion code into register 15
SVC 3 issue EXIT [[Supervisor Call instruction|SVC]] to terminate the jobstep
This makes perfect sense as the OS/360 Initiator initially "attaches" the job-step task using the ATTACH macro-instruction (SVC 42), and "unwinding" the effect of this ATTACH macro (it being a Type 2 SVC instruction) ''must'' be a complementary instruction, namely an EXIT macro (necessarily a Type 1 SVC instruction, SVC 3).
==See also==
* {{Mono|[[True_and_false_(commands)|true]]}} - the Unix-equivalent "do nothing" program
==References==
Trombetta, Michael & Finkelstein Sue Carolyn (1985). "OS JCL and utilities". Addison Wesley. page 152.
<references/>
[[Category:IBM mainframe operating systems]]
[[Category:Software]]
| |||