How utilities work: IEFBR14, IEBGENER and IDCAMS

Utilities are ready-made programs you run from JCL and steer with control statements. They share a small set of DD name conventions and a common return-code language, so once you can read one, you can read most of them.

Why utilities exist

Most day-to-day data work on z/OS is not unique to one application: create an empty file, copy it, delete last week's version, list what is in the catalog. Rather than every team writing a program, z/OS ships utilities: tested, supported programs you call with EXEC PGM= and drive with a few lines of input. Production JCL is full of them, often more utility steps than application steps.

The shared conventions

Utilities written decades apart still follow the same pattern, which is why learning one helps with the next:

DD name	Usual meaning
SYSPRINT	The utility's report: what it did, messages, and why it failed
SYSIN	Control statements telling it what to do; DD DUMMY when there are none
SYSUT1	Input dataset (IEBGENER, IEBCOMPR, and IEBCOPY when you use the default names)
SYSUT2	Output dataset, or the second file in a comparison
SYSOUT	Message output for DFSORT (DFSORT uses SYSOUT, not SYSPRINT)

Control statements usually start in column 2 or later and stop by column 71; a non-blank in column 72 means continuation for many of the older utilities. When a utility says it found an invalid statement, check columns before checking logic.

Return codes: the shared language

Every utility ends with a return code. The numbers follow a convention, but the exact meaning is defined by each utility, so always confirm in SYSPRINT.

RC	General meaning	Example
0	Completed normally	IEBGENER copied every record
4	Completed with a warning	IDCAMS finished a command but noted a minor condition
8	A requested function was not done	IDCAMS DELETE of a dataset that is not in the catalog
12 or 16	Serious error; processing usually stopped	Invalid control statement, or an input dataset could not be opened

Later steps test these values with COND or IF/THEN, and the scheduler usually treats anything above an agreed maximum as a failure. A utility that ends with RC 8 has not abended, so a job can look like it 'ran' while a key step did nothing.

IEFBR14: allocation without a program

IEFBR14 returns immediately with RC 0. All the work is done by the system processing the DD statements: allocation when the step starts and DISP processing when it ends. That makes it the standard way to create an empty dataset or remove one.

IEBGENER: copy, print and simple reformat

IEBGENER copies a sequential dataset or a single PDS member. With SYSIN DD DUMMY it copies record for record; if the new output's record format and length are not coded, it takes them from the input. Pointing SYSUT2 at SYSOUT=* is a quick way to print a small file into the job output.

IEBGENER with a reformat (illustrative)

//REFMT    EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD DSN=PROD.CUST.MASTER,DISP=SHR
//SYSUT2   DD DSN=TEST.CUST.EXTRACT,DISP=(NEW,CATLG,DELETE),
//            SPACE=(CYL,(5,5),RLSE),RECFM=FB,LRECL=40
//SYSIN    DD *
  GENERATE MAXFLDS=2
  RECORD FIELD=(10,1,,1),FIELD=(30,21,,11)
/*

Reading the RECORD statementWhat it means

GENERATE MAXFLDS=2

Tells IEBGENER that editing is wanted and at most two FIELD parameters follow

FIELD=(10,1,,1)

Take 10 bytes from input position 1 and place them at output position 1

FIELD=(30,21,,11)

Take 30 bytes from input position 21 and place them at output position 11

At many sites the name IEBGENER is actually routed to ICEGENER, the DFSORT copy program, which is faster and falls back to real IEBGENER when it cannot handle the request. You usually cannot tell from the JCL; SYSPRINT shows ICE messages when it happened. For anything beyond a simple field rearrangement, DFSORT is the better tool.

IDCAMS beyond VSAM

IDCAMS is known for VSAM, but it is also the everyday catalog tool for ordinary datasets:

DELETE dsname removes a dataset and its catalog entry; DELETE ... NOSCRATCH removes only the catalog entry.
LISTCAT ENTRIES(dsname) ALL shows volume, creation date and attributes from the catalog.
DEFINE GDG creates a generation data group base with a LIMIT and SCRATCH or NOSCRATCH.
ALTER dsname NEWNAME(newname) renames a dataset; DEFINE ALIAS connects a high-level qualifier to a user catalog (usually a storage team task).
PRINT INFILE(dd) CHARACTER COUNT(10) dumps the first records, useful for inspecting packed data in hex with DUMP.
REPRO copies sequential files as well as VSAM.

Delete if present, then carry on (illustrative)

//CLEANUP  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE TEST.PAY.WORK1
  IF LASTCC = 8 THEN SET MAXCC = 0
/*

LASTCC is the condition code of the previous command and MAXCC is the highest so far, which becomes the step return code. The IF resets the result when the delete found nothing to delete. RC 8 is not unique to 'not found', though, so where it matters check SYSPRINT for IDC3012I (entry not found) rather than relying on the code alone. With several DELETEs, each needs its own test, because MAXCC keeps the worst code seen so far. Use this with care: SET MAXCC = 0 on its own also hides a real failure in an earlier command, such as a dataset that could not be deleted because it was in use.

TRY IT YOURSELF

Which IDCAMS variable holds the highest condition code so far and becomes the step return code?

Show a hint

It is the one paired with LASTCC.

Show the solution

MAXCC. LASTCC is only the most recent command's code.