Datasets and Mainframe Utilities

The ddnames (LOANTRAN, COPYLIB, OLDWORK) mean nothing to IEFBR14; they only have to be unique in the step.

DISP=(NEW,CATLG,DELETE) creates the data set, catalogs it when the step ends normally and deletes it if the step abends. Without the catalog request, a new data set is lost at the end of the job unless it is passed to a later step.

SPACE=(TRK,(5,1),RLSE) asks for 5 tracks, up to 1 more track at a time when full, and the release of unused space when the data set is closed after being written by a program. RLSE does nothing in a step that does not open the data set, as here, but it is the habit to carry to the DD statements of the writing steps. For a partitioned data set the third value of the inner list is the number of directory blocks, 20 here.

DSNTYPE=LIBRARY makes a PDSE, a partitioned data set extended; leaving it out gives a PDS, which has to be compressed from time to time (see IEBCOPY).

BLKSIZE=0 makes the system determine the block size, which is the normal practice (see RECFM, LRECL and BLKSIZE).

DISP=(MOD,DELETE,DELETE) on a data set that may not exist is the usual idiom for "delete it if it is there": MOD on a data set that does not exist is treated like NEW, so the step creates it and the disposition deletes it again, and the job does not fail with "data set not found". Running the job twice is therefore safe, except for the first two DD statements, which fail the second time because the names already exist. A job that is run again and again uses this idiom first and allocates afterwards.

The first command sets the format, the length, the block size and the space explicitly. --size takes a number followed by CYL or TRK and sets the primary allocation; the secondary allocation then becomes about 10 percent of it. The defaults of data-set-sequential are, per the documentation, FB, a record length of 80 and a block size of 6160, so a data set for 30-byte records must say so. The block size 27990 is 933 records of 30 bytes, the largest multiple of 30 that fits in the 27998-byte half-track block that is usual on a 3390 disk; the next section shows why a multiple of the record length is needed, and BLKSIZE=0 in JCL achieves the same without the arithmetic.

The second command takes the defaults of data-set-partitioned (FB, 80, 5 directory blocks) and --data-set-type LIBRARY makes it a PDSE, as DSNTYPE=LIBRARY does in JCL. The other values of --data-set-type listed by the documentation are BASIC, EXTPREF, EXTREQ, HFS, LARGE, PDS and PIPE.

The third command creates a data set with the attributes of an existing one, which is the quick way to make a work file the same shape as a master. --like can be combined with an override such as --record-length.

The space is given with --size here, whose unit is explicit; if --primary-space is used instead, check in --help which unit applies before relying on it, because the documentation page does not state it.

With SYSIN DD DUMMY there is no editing, so the record length and the format of the output come from the input data set and the system selects the block size, as in the IBM example.

The same program also copies an in-stream or sequential data set into a member of a PDS (SYSUT2 names USERID.CIRC.COPYLIB(LOANREC), a member, not a whole library), which is how a copybook is loaded from a job. The control statements GENERATE and RECORD describe editing and the creation of several members; they are rarely needed for the Circulation job and are described in the IBM manual.

ICEGENER is the DFSORT front end that does the same unedited copy, generally faster. The IBM manual advises it in preference to IEBGENER for unedited copies when DFSORT is installed, and notes that it may be installed under the name IEBGENER, so that the job above may in fact run it. Both take the same DD names.

IEBGENER copies sequential data sets and members; it cannot copy a VSAM cluster (IDCAMS REPRO does that) and cannot copy a whole PDS in one step (IEBCOPY does that).

COPY OUTDD=...,INDD=... names the ddnames of the output and the input; a SELECT MEMBER=(...) statement after it limits the copy to the listed members (and EXCLUDE does the reverse). A selected member can be written with the replace option, as in SELECT MEMBER=((LOANREC,,R)) (the form used in the IBM example), to replace a member of the same name in the output; without it, check in SYSPRINT whether the member was copied, because a changed copybook that was not replaced is a classic source of builds that use old code.

The second step is the compress-in-place form: the same data set under two ddnames, one as input and one as output, and no SELECT. The IBM manual warns to take a backup first, because an interruption during a compress can destroy the library, and not to compress a library other users are using at the time. Compression does not apply to a PDSE, which does not need it, and the need to do this on a PDS is one of the reasons to prefer a PDSE for new libraries.

The utility reports the members copied, replaced or not copied in SYSPRINT, which is where to look first when a build does not see a changed copybook.

LISTCAT LEVEL(USERID.CIRC) lists the catalog entries whose names start with those qualifiers; ENTRIES(name) with ALL lists one entry with all its fields, including the attributes (key length and offset, record size, control interval size, space and the high-used values). A listing like this is the quickest way to check that an allocation did what was intended.

DELETE ... CLUSTER PURGE removes a VSAM cluster, its components and its catalog entry; PURGE deletes it even if its retention period has not expired. For a non-VSAM data set the entry type is NONVSAM, and SCRATCH (the removal from the volume as well as from the catalog) or NOSCRATCH decides whether the data is removed from the disk.

DELETE of an entry that does not exist gives a condition code of 8 with a message that the entry was not found (a message of the family IDC3012I). IF MAXCC = 8 THEN SET MAXCC = 0 resets the step’s code, so that a clean-up that finds nothing to delete does not stop the job; the hyphen at the end of a line continues an IDCAMS command on the next line.

REPRO INDATASET(...) OUTDATASET(...) copies the records; with a VSAM input and a sequential output data set that has been allocated with RECFM=FB and LRECL=60 first (for example with the IEFBR14 job above), it makes a flat backup that IEBGENER or a COBOL program can read. REPRO accepts FROMKEY, TOKEY, SKIP and COUNT to select a range.

The return code of the IDCAMS step is the highest condition code of its commands (MAXCC), and the messages (IDC...I) in SYSPRINT explain every non-zero code.

The statements of CTL1CNTL are ordinary DFSORT control statements (USING(CTL1) on an operator means "read CTL1CNTL`"). `OUTFIL FNAMES=ddname,INCLUDE=(...) writes to the named DD only the records that satisfy the condition, so one pass over the input produces both output data sets. The positions are those of LOANREC: type at 1, member at 2, book at 8, date at 14.

COPY and SORT move records from the FROM data set to the TO data set, or to the OUTFIL outputs of the control data set. COUNT writes a message with the number of records, STATS reports statistics (minimum, maximum, total and average) of a numeric field given in ON(position,length,format), here the six zoned-decimal digits of the book number, and DISPLAY produces a report of the listed fields on the LIST DD. These operators are the building blocks of a reconciliation step: the count of the input must equal the sum of the counts of the outputs, and a job step that tests it turns a silent loss of records into a non-zero return code.

TOOLMSG receives ICETOOL’s messages and DFSMSG those of DFSORT, one of each is needed in every ICETOOL step.