Archive and Superscratch Job Control Requirements

The following Job Control Statements are required to perform Archive Backup and Superscratch functions.

STEPLIB or JOBLIB DD statement

If FDR is not in the system link list (LNKLST), specifies the program library in which FDRABR resides. The library must be APF authorized.

EXEC statement

Specifies the program name (PGM=FDRABR), region requirement (REGION=, see Memory Requirements in FDRABR-Processing-Options-and-Requirements), and optional PARM= operand.

If a PARM field is specified, ABR uses data specified as the first control statement, which must be a valid DUMP statement; if the PARM data contains a slash “/”, the data after the slash is used as the second control statement (usually a SELECT). For example,

If FDRABR is invoked from a user program, Register 1 must follow IBM’s convention for passing data from the PARM field.

ABRARDQ DD statement

Specifies the remote queue data set for Archive Backup. This DD statement is optional. If specified, ABR reads the control statements contained within, if any, and appends these statements to the SYSIN data set. The SYSIN data set must contain at least a DUMP TYPE=ARC statement. After reading the control statements, ABR resets the file to null (empty) except on SIM. Specify DISP=SHR since ABR internally serializes this data set.

ABRMAP DD statement

Specifies the output report data set if SIM or PRINT=ABR is specified. It is optional; if not specified the SIM report is printed on the SYSPRINx DD Statement. See notes on SYSPRINT DD Statement.

ARCHIVE DD statement

Specifies the ABR Archive Control File. This DD statement is required for DUMP TYPE=ARC unless the DYNARC operand is specified. The standard name for this data set is FDRABR.ARCHIVE, but you can use any name as long as it has an index level of “ARCHIVE” somewhere in the name. ABR uses this data set as an inventory and catalog file for all data sets that have been archived from DASD volumes. Specify DISP=SHR since ABR internally serializes access. On SIMULATION or TYPE=SCR operations this DD statement is not required. For example:

FDREMAIL DD statement

Specifies input control statements for the FDR e-mail facility. If present, e-mail messages can be sent for unsuccessful or successful FDR operations. See FDR-E-mail-Notification-Facility for requirements and details.

FDRSUMM DD statement

(Optional) if present, ABR writes one-line messages for each volume dumped, giving result codes, elapsed time, and byte counts. See notes on SYSPRINT DD Statement. FDRSUMM is used only if RTC=YES is specified on the DUMP statement. A volume may appear more than once in FDRSUMM if the MAXBTRKS= value causes the volume to be processed more than once.

SYSIN DD statement

Specifies a data set containing the control statements for ABR. Usually a DD * data set. It is required, but if control statements were provided on the EXEC statement by PARM=, it can be DUMMY.

DISKxxxx DD statements

Optionally specifies DASD volumes to be processed by ABR. The format is:

//DISKxxxx DD UNIT=unit,VOL=SER=vol,DISP=OLD

xxxx

may be 1-4 alphanumeric (A-Z,0-9) or national (@ # $ in the US) characters.

unit

is either a generic name, such as 3390, or an esoteric name assigned during your I/O configuration, such as DISK or SYSALLDA.

vol

is the volume serial of the DASD volume (if an esoteric unit name is used, the volume serial must be mounted on a DASD unit which is part of that esoteric). You may use either DISP=OLD or DISP=SHR; it makes no difference.

The DISKxxxx DD statement may also specify multiple volume serials, up to 255, in the format:

//DISKxxxx DD UNIT=unit,DISP=OLD, // VOL=SER=(vol1,vol2,…)

All the volumes must be of the same type (for example, 3390) and have the same capacity (for example, 3390-3) and the same SMS status (either all SMS-managed volumes or all non-SMS volumes).

ABR builds a list of the volume serials from all of the DISKxxxx DD Statements found in the ABR step JCL; these volumes are processed in the order that the DISKxxxx DD Statements appear in the JCL. A maximum of 256 DASD volumes can be processed in one execution of ABR; if more DASD volumes are required, MAXDD= must be specified on the DUMP statement.

However, DISKxxxx DD Statements are not required and there are easier alternatives. The ONLINE and ONLVOL operands of the DUMP statement and the MOUNT statement are easier ways of specifying volumes or groups of volumes (including SMS storage groups).

SYSPRINT DD statement

Specifies the primary output message data set; it is required. It is usually a SYSOUT data set but if it is assigned to a data set on tape or DASD, this DD statement must specify DISP=MOD. DCB characteristics are RECFM=FBA and LRECL=121; the block size defaults to 1210 on DASD or tape.

SYSPRINx DD statement

Specifies the secondary output data set for messages related to the matching TAPEx DD Statement. A SYSPRINx DD statement is required for each TAPEx DD Statement present in the step. See notes on SYSPRINT DD Statement in Archive and Superscratch Job Control Requirements.

SYSUDUMP DD statement

Specifies the abend dump data set. Usually specifies a SYSOUT data set. Although not required, we strongly urge you to always include this DD statement, so that we can help you diagnose error conditions. If you have a debugging aid product on your system that would prevent the desired dump, please add the appropriate one of these statements to the JCL so that a fully-formatted dump is produced.

TAPEx DD statement

Specifies the output device on which backup files are to be created. “x” may be any single alphanumeric (A-Z, 0-9) or national (@, #, and $ in the US) character. A maximum of nine such TAPEx DD statements may be present in the ABR step JCL. ABR starts an internal dump subtask for each TAPEx DD statement present, each subtask processing one DASD volume from ABR’s list of DASD volumes. If only one TAPEx is provided, ABR processes DASD volumes one at a time; if multiple TAPEx DD statements are present, ABR processes up to nine DASD volumes in parallel (however, region size limitations may limit the number of concurrent subtasks; see Memory Requirements in FDRABR-Processing-Options-and-Requirements). TAPEx DD statements that specify DUMMY or DSN=NULLFILE are ignored except for simulation and Superscratch.

Tape output

If outputting to tape or cartridge, the TAPEx DD Statement must specify:

A data set name is required by z/OS, but it is overridden by ABR at OPEN time, so any non-temporary name is acceptable. The name you specify is not used by ABR, but z/OS does an exclusive enqueue on this name at job initiation so each ABR job should use unique names.

Specify a generic (for example, 3590) or esoteric (for example, CART) name to allocate the type of tape drive desired.

Specify a volume count, for example, VOL=(,,,255), to prevent ABR from abending if more than five tape volumes are required. If high-capacity cartridges are used, VOL= can be omitted. Do not use VOL=REF= to refer-back to a previous ABR step; use the “LAST TAPE Option” in Section 51.4 to add files to a tape.

You may want to specify RETPD= or EXPDT= to identify the expiration date of the backups. See “Backup Retention and Tape Management” in Section 51.1 for details on retention of ABR Archive Backups.

Is required; do not specify CATLG since ABR handles cataloging of output files internally.

Do not specify FREE=CLOSE since it causes ABR to fail when it tries to create a second file on the tape. For example:

//TAPE1 DD DSN=ABR1,UNIT=3590-1,DISP=(NEW,KEEP), // EXPDT=99000

If multiple DASD volumes are dumped to a given TAPEx DD Statement, ABR creates multiple files on the tape, one file for each DASD volume, using the naming convention in Tape Format and Naming Conventions in Introduction-to-FDRABR-Archiving-and-Superscratch. If a tape volume is filled, ABR mounts a new tape, creating a multi-volume, multi-file tape aggregate. By default ABR creates as many as 255 files on a tape or aggregate before starting over with file 1 on a fresh scratch tape, but that limit can be overridden by the MAXFILE= operand, up to 65534 files. Larger MAXFILE= values can be used with high-capacity tapes.

DCB parameters are not required and should be omitted.

The hardware Virtual Tape System (VTS) is supported. In a VTS, data written to “tape” is really written to DASD internal to the VTS and is later moved to high-capacity tapes, resulting in much better physical tape utilization. When a tape is required for input, the data is staged back to the internal DASD. VTS users may wish to specify MAXFILE=1 to avoid having to stage many tape files during a recall when only one file is actually needed, however, you may not want to use MAXFILE=1 if a second backup copy is directed to real tapes. MAXFILE=1 may require a larger number of virtual volumes in the VTS.

LAST TAPE option

The LAST TAPE option of ABR allows you to add backup files to a tape or tape aggregate created by a previous ABR step (even if that step is in another job and even if it was run on a previous day). This option is controlled entirely through JCL. To request LAST TAPE, the TAPEx DD Statement is similar to that described above except that you specify:

DSN=FDRABR.LASTAPE.xxxxxxxx

The last index is 1 to 8 characters of your choice; you may have multiple LASTAPE files for various purposes. This name is cataloged in the ABR catalog to record the tape volume serial and file number where ABR is to start its output on the next run.

This tells ABR to locate the FDRABR.LASTAPE.xxxxxxxx file in the catalog, verify that the file exists on the output tape, and begin outputting to the tape at that point. If the name is not cataloged, ABR calls for a scratch tape and begin at file 1, so you can force ABR to start on a new tape simply by uncataloging the LASTAPE name. If you specify NEW instead of MOD, ABR ignores the LASTAPE file and use scratch tapes (but it still records the new LASTAPE file for future use. For example:

//TAPE1 DD DSN=FDRABR.LASTAPE.ABR1,DISP=(MOD,KEEP), // UNIT=TAPE,EXPDT=99000

On cartridge tape drives, ABR records the location of the LASTAPE file and uses hardware high-speed positioning when positioning to add files to the backup tape.

DASD output

You may request that ABR create Archive Backup files on DASD. This is often used for COPY1, with a short retention such as 15 to 60 days so that recalls requested shortly after a data set is Archived can be completed without a tape mount (if you have an Automated Tape Library (ATL) or Virtual Tape System (VTS), recalls from tape may be almost as fast as from DASD).

The TAPEx DD simply points to one or more DASD volumes; ABR internally handles naming, allocating, and cataloging the required backup files. See Tape Format and Naming Conventions in Introduction-to-FDRABR-Archiving-and-Superscratch for the file names that ABR creates. Usually these are volumes that are dedicated to ABR use. For example:

//TAPE1 DD UNIT=3390,DISP=OLD, // VOL=SER=(ARC001,ARC002,ARC003,ARC004,…)

If the backup file is on DASD:

• By default, ABR sorts the volume list by the amount of free space available on each volume, so that the volumes with the most available space are used first.
• If the POOLSORT=NO option is specified, and the ABR POOLDISK option is used (discussed below), then ABR uses the volumes in the order specified, but remembers from run to run which volume it used last and starts with that volume in the next run.
• If the POOLSORT=NO option is specified, and the ABR POOLDISK option is not used, then ABR uses the volumes in the order specified, and starts at the beginning of the list in each run.

By default, ABR allocates its backup files with:

SPACE=(TRK,(100,100),RLSE,ALX) for non-SMS output volumes or SPACE=(TRK,(100,1000),RLSE,ALX) for SMS-managed output volumes

The ALX operand specifies that the backup data set is allocated using the 5 largest extents on the volume that are at least 100 tracks large, so that it has a minimum size of 100 tracks and a maximum of 4369 cylinders (65,535 tracks) or the size of the DASD volume, whichever is less. RLSE requests that any unused space be released at the end of the backup. Since ABR cannot predict how big the backup data set is going to be, this technique gets all or most of the free space on the target volume, for output to 3390-3 or smaller, and releases it at the end. The default allocation may be overridden by specifying the SPACE= operand on the TAPEx DD Statement. If the output volumes are 3390-9 or larger, specify a SPACE parameter without ALX to allow ABR to allocate all of the space on the volume if needed. Examples:

SPACE=(CYL,(1000,1000),RLSE),DSNTYPE=LARGE,EATTR=OPT SPACE=(CYL,(30000,10000),RLSE)

If the primary allocation is more than 4369 cylinders, FDRABR automatically sets DSNTYPE=LARGE and EATTR=OPT. DSNTYPE=LARGE is needed for sequential data sets larger than 4369 cylinders (65,535 tracks). EATTR=OPT allows the data set to be allocated in cylinder-managed space on an Extended Address Volume (EAV); if the output volume is not an EAV, EATTR=OPT has no effect. If the primary allocation is 4369 cylinders or less, but you want the data set to be able to extend to more than 4369 cylinders with secondary allocations, then DSNTYPE=LARGE must be specified and, if desired, EATTR=OPT, or specify DATACLAS= a data class with these attributes, or have the ACS routine assign such a data class. RLSE does not need to be specified since it is forced by ABR.

If the space allocated on a volume is not sufficient, then ABR extends the Archive backup file to additional volumes from the volume list.

Do not specify a DSN= parameter unless the POOLDISK option is used. RETPD= or EXPDT= may be specified to set the expiration date of the backups; this specification is recorded in the Archive Control File.

• If the backup file is on DASD, it can be SMS-managed. Instead of a volume list, specify VOL=(,,,n,SER=vvvvvv), where “n” is a volume count and “vvvvvv” is one SMS-managed volume.

When the volume serial specifies an SMS-managed volume, ABR by default assigns a storage class of FDRBKUP. If you prefer a different storage class, you can either specify STORCLAS= or have the ACS routine assign a storage class for the data set names that ABR creates for Archive backup files (see Introduction-to-FDRABR-Archiving-and-Superscratch). A data class is also required (see below for details); DATACLAS= must be either specified on the DD statement, or assigned by the ACS routine. A management class is optional, and can also be either specified on the DD statement, or assigned by the ACS routine.

The data class must specify a Dynamic Volume Count (DYNVOL COUNT), in case the backup file needs to use more then one volume.

• The suggested value for Dynamic Volume Count for this data class is 20. (ABR supports a maximum of 20 volumes for a backup file. A value of up to 59 can be specified, in case the data class is also used for data sets that can use more than 20 volumes.)
• A regular Volume Count (VOLUME COUNT), if specified in the data class, will not be used for ABR allocations.
• Even though the data class specifies a dynamic volume count, it is also necessary to specify a volume count in the VOL= parameter on the DD statement, i.e. VOL=(,,,n,SER=vvvvvv).
• As discussed above, the data class may also specify Data Set Name Type as LARGE, and EATTR as OPT (ABR sets these attributes automatically if the primary allocation is larger than 4369 cylinders).

For example:

//TAPE1 DD VOL=(,,,10,SER=TECH01),UNIT=SYSALLDA, // STORCLAS=SCARCH,DATACLAS=DCARCH,DISP=OLD, // SPACE=(CYL,(30000,30000),RLSE)

POOLDISK option

When outputting to non-SMS DASD volumes, you may use the ABR POOLDISK option, allowing ABR to manage a pool of DASD volumes used for ABR backup data sets. Like LASTAPE, this is invoked through JCL options by specifying DSN=FDRABR.POOLDISK.xxxxxxxx on the TAPEx DD Statement, where “xxxxxxxx” is any name of your choice (allowing you to have multiple pools for various purposes). Otherwise the JCL is the same as just described for DASD output. For example:

//TAPE1 DD DSN=FDRABR.POOLDISK.ARCHIVE1, // UNIT=3390,DISP=OLD,RETPD=30, // VOL=SER=(ARC001,ARC002,ARC003,ARC004,…)

Alternately you may catalog the POOLDISK data set with IDCAMS or IEFBR14, pointing to the volumes in the pool; then the volume list may be updated at any time without modifying the ABR JCL. For example:

For DUMP operations to cloud storage

You may request that ABR create Archive Backup files in the cloud. This is appropriate when the Archives have a long retention and will probably not need to be recalled.

For Transparent Cloud Tiering (TCT), TAPEx points to one or more DASD volumes on which ABR will create backup control files. All of the input volumes processed in this jobstep must reside in a single DASD control unit (or in other control units that are connected to the same cloud and are able to access the same containers), and the backup control file volumes (TAPEx) must also reside in that DASD control unit (or in other control units that are connected to the same cloud and are able to access the same containers).

The actual backup files are written to the cloud, but the backup control file contains information that is needed in order to do the restore. The cloud name and container name are recorded in the backup control file, and do not need to be specified at restore time.

Most of the considerations discussed above for DASD Output apply to the TAPEx for cloud storage. ABR internally handles naming, allocating, and cataloging the backup control files; see “Tape Format and Naming Conventions” in Section 51.1 for the file names that ABR creates. One difference is that backup control files are usually small; they only need to be a few tracks, unless a large number of data sets are being archived. The backup control file cannot be multi-volume, but it can have multiple extents. We recommend starting with SPACE=(TRK,(15,15),RLSE), and increasing the allocation for archives that run out of space. The backup control file can be SMS-managed. For backup control files on SMS, since a backup control file cannot be multi-volume, the considerations above under DASD Output for volume count and dynamic volume count do not apply. It is desirable that the backup control file remain on disk for as long as the archives are retained. However, the backup control file is also backed up to the cloud; if it is deleted from disk, then ABR will automatically restore it from the cloud if DYNTAPE is specified, including for auto recall, in order to be able to restore the Archived data sets. The backup control files should be managed using FDRARCH REORG in the same way as regular ARCHIVE backup files on disk. The backups in the cloud can then be cleaned up by FDRTCTUT with the DELETEBACKUPS command, as shown in FDRTCTUT-FDR-Transparent-Cloud-Tiering-Batch-Utility.

Examples showing TAPEx definition to create the backup control file:

Non-SMS:

//TAPE1 DD UNIT=SYSALLDA,DISP=OLD,SPACE=(TRK,(15,15),RLSE), // VOL=SER=ARC001

SMS:

//TAPE1 DD UNIT=SYSALLDA,DISP=OLD,SPACE=(TRK,(15,15),RLSE), // VOL=SER=TECH01,STORCLAS=SCARCH

Simulation and Superscratch

If Superscratch (DUMP TYPE=SCR), simulation of Superscratch (SIM TYPE=SCR) or simulation of Archive Backup (SIM TYPE=ARC) is requested, you must specify:

TAPExx DD Statement

Specifies that ABR is to create a duplicate backup (COPY2). “xx” must specify the same character twice with “xx” corresponding to the “x” of the TAPEx DD Statement. For example:

produces a tape that contains the same backup as:

ABR reads the DASD once and writes the same data to the TAPEx DD Statement and TAPExx DD Statement concurrently. These are known to ABR as COPY1 (TAPEx) and COPY2 (TAPExx).

TAPExx must be omitted for backups to cloud storage.