FATSCOPY execution JCL

To execute FATSCOPY, the following JCL statements are used.

JOB/STEP statement

If you expect your FATSCOPY job or job step to be processing a large amount of data, you may wish to add TIME=1440 or TIME=NOLIMIT to the JOB or STEP statement to avoid an S322 abend.

EXEC statement

The EXEC statement specifies the FATSCOPY program name and memory requirements (if your installation defaults are insufficient).

A region of 0M is recommended for FATSCOPY; the program will use no more memory than is required for a particular function.

Example:

STEPLIB/JOBLIB DD statement

A STEPLIB or JOBLIB DD statement will be required if FATSCOPY has been linkedited into a private library. It can be omitted if FATSCOPY is in a system library that can be accessed without a STEPLIB/JOBLIB statement (that is, a library in the system link list). This must be an APF authorized library.

If ABRARC=YES is specified to copy ABR Archive and Application Backup data sets, the library that contains the ABR load modules must be added to the STEPLIB/JOBLIB, unless the ABR modules are in a link list library. ABR level 5.4/70 or higher is required to copy ABR tapes with FATSCOPY.

If you are selecting physical tapes on a StorageTek VSM virtual tape system with the PHYSVOL or ALLPHYS keyword, a STEPLIB or JOBLIB DD statement that specifies the link library (SLSLINK) that contains the VTCS and HSC modules is required (unless this library is in the linklist).

SYSPRINT DD statement

The required SYSPRINT DD statement indicates what data set receives FATSCOPY messages, and is normally allocated to a SYSOUT data set. Its DCB attributes are RECFM=FBA,LRECL=121. If BLKSIZE= is specified it must be a multiple of 121, otherwise it will default to 121 for SYSOUT or 1210 for other devices.

SELRPT DD statement

SELRPT is a required DD statement that receives a report showing all data sets selected from the system catalogs (based on the SELECT/EXCLUDE statements present). If CATDSN is specified, it will be in catalog order. If ALLDSN is specified, it will be in the order in which the data sets are on the volume. It will also show tape management information for each data set, and will indicate in the STATUS and REASON columns whether the data set was actually selected for copying. Some reasons for bypassing a data set include:

• NOTMINFO – No tape management information for volume.
• INV DSN – Invalid data set name.
• MISMATCH – The data set name and location recorded in tape management does not match the name and location recorded in the system catalog.
• MULTIFIL – The data set was on a multifile volume and MULTIFILE=NO was used.
• EXCLUDED – The data set matched one of the criteria on an EXCLUDE statement.
• EDM – The data set is controlled by an external data manager.
• DUPLICAT – The data set was already selected by a previous SELECT statement.

SELRPT is usually a SYSOUT data set and its DCB attributes are RECFM=FBA, LRECL=133. If BLKSIZE if specified, it must be a multiple of 133 otherwise it will default to 133 for SYSOUT and 1330 for other devices.

COPYRPT DD statement

COPYRPT is a required DD statement that receives a report showing all data sets actually copied to output tapes, in the order they were copied. It will display the output volser and file sequence number of each output file. It is usually a SYSOUT data set and its DCB attributes are the same as for SELRPT.

COPYRPT2 DD statement

The optional COPYRPT2 DD statement will receive the same report as COPYPRT, except that there are no report headers or page skips. This is suitable for importation into a spreadsheet or other reporting program. Its DCB attributes are the same as for SELRPT.

TAPESUMM DD statement

TAPESUMM is required. It receives a summary report of all input files in the order they were read, including data set name, tape label information, block and byte counts, and minimum, maximum and average block sizes. It is usually a SYSOUT data set and its DCB attributes are the same as for SYSPRINT.

ERRORRPT DD statement

The optional ERRORRPT DD statement indicates what data set receives all error messages. It is usually a SYSOUT data set and its DCB attributes are the same as for SELRPT.

AUDIT DD statement

The AUDIT DD statement is optional. If it is present, FATSCOPY will generate audit records for each data set it copies and write those records to this data set. The audit file must be a disk or tape data set with DCB attributes of RECFM=FB and LRECL=220. Refer to Writing Audit Records for suggestions on allocating and using the audit file. The FATAUDIT program can be used to produce formatted reports using the audit data set, see FATAUDIT Functional Description for a description of how to use FATAUDIT.

If an AUDIT DD statement is used, the AUDITLOG= keyword is ignored.

DSNTABLE DD statement

The DSNTABLE DD statement defines a data set that is used by FATSCOPY to save the selection results of a SIM job or an interrupted COPY job.

• A SIM job with the CHECKPT keyword creates a data set containing the files selected for copying.
• A COPY job that is interrupted by a STOP or CANCEL command creates a data set containing the files that have been selected and indicates which of those files have actually been copied.

To create a new DSNTABLE data set, use DISP=(,CATLG). If you code a DCB parameter, use RECFM=FB, LRECL=334, and BLKSIZE=16700. (Note: these values are different from previous FATSCOPY versions.) If you omit the DCB parameter, FATSCOPY will use the correct values by default.

A DSNTABLE data set is also used by a subsequent COPY job with the RESTART keyword to select which files should be copied.

• When using a DSNTABLE created by a SIM job, the COPY RESTART job copies all the files selected by that SIM job.
• When using a DSNTABLE created by an interrupted COPY job, the COPY RESTART job copies the files that were selected but not yet copied by the interrupted job.

To use an existing DSNTABLE data set in a RESTART job, use DISP=SHR.

SYSABEND DD statement

SYSABEND requests an abend dump if major errors occur. Note that most internal abends in FATSCOPY are for the user's information only and do not normally cause dumps. SYSABEND is usually allocated to SYSOUT. Abend dumps are necessary for analysis of problems. If you have a debugging aid product on your system that would prevent the full dump from being produced, please add the appropriate one of these statements to allow the dump to be generated:

TAPEOUT DD statement

The TAPEOUT DD statement specifies the output tape onto which FATSCOPY will copy the requested data sets. The TAPEOUT DD must include DSN=. It must include at least one of UNIT=, STORCLAS=, and DATACLAS=. VOL=, DISP=, and RETPD= are optional (except that DISP= is required when your tape management is TLMS), but should be coded using the following guidelines.

DSN=

A valid permanent data set name, to meet z/OS requirements. However, this name is treated by FATSCOPY as a dummy name. Actual output data set names will be copied from the input tapes, or be determined by a RENAME statement. (To run concurrent FATSCOPY jobs, use different dummy data set names for each job.)

Note: If you have SMS routines that determine device allocation using data set names, then you must select a dummy data set name that will allow the proper output device to be allocated to your copy job.

UNIT=

A unit name that will allocate the desired type of output tape. Alternatively, STORCLAS= or DATACLAS= value may be specified.

If you are writing data sets to VTFM volumes, use UNIT=(unitvalue,,DEFER). This will guarantee that the VDB entries created by VTFM will contain the first data set name created by FATSCOPY, instead of the data set name coded in the DSN= parameter on the TAPEOUT DD. Also use DEFER if you are using the VIRTZSTD keyword to retrieve output tape compression statistics from an IBM TS7700 virtual tape device.

If you are writing data sets to an IBM TS7700 Series virtual tape system, the DATACLAS= value used determines which compression algorithm should be used by the TS7700.

VOL=

Optionally specify the volume serial of the output tape. If omitted, z/OS will request a scratch tape. Since the default maximum number of volumes that z/OS will allow for an output data set is 5, it is  recommended coding VOL=(,,,255) to avoid S837 abends in the event that more than 5 output tapes are required.

DISP=(NEW,KEEP)

This is required if you are using TLMS tape management. Do not specify CATLG since FATSCOPY will handle cataloging of the output data sets internally. Change NEW to OLD if you are adding files to a non- scratch volume (using the OUTFSEQ keyword, or LABEL=n on TAPEOUT).

RETPD= or EXPDT=

Specify one of these only to assign a specific expiration date to all of the output data sets. Do not use EXPDT=98000 if you are using the IMAGE keyword.

FREE=CLOSE

Required when using the VIRTZSTD keyword to retrieve output data set compression information on an IBM TS7700 virtual tape device.

For a SIM (Simulate) operation, the TAPEOUT DD statement may be omitted. If a TAPEOUT DD statement is present for a SIM and RETPD or EXPDT is specified, FATSCOPY will use the RETPD or EXPDT value to calculate the expiration dates for the output data sets that will be displayed in the SIM Report. Otherwise, the TAPEOUT DD statement is ignored for a SIM.

If you omit RETPD= or EXPDT= from the TAPEOUT DD, FATSCOPY will assign the expiration date of each output file using the expiration date of each input file from tape management. If EXPIRED=YES is specified (to copy expired data sets), and the input data set is expired, the expiration of the output data set is set to the current date plus 2 days.

If you specify DATACLAS= or STORCLAS= on the TAPEOUT DD, or you specify a DSN= that is assigned a SMS storage class by your SMS ACS routines, the output tape may be SMS- managed. However, FATSCOPY will not copy SMS class information from the input data sets to the output data sets, so the SMS classes specified or assigned will be used for all output data sets.

For example,

You can optionally specify a file sequence number in the LABEL= parm on the TAPEOUT DD to tell FATSCOPY to add data sets to a volume that already contains stacked data sets; however, the OUTFSEQ= keyword is the preferred method to use.

To specify the compression option to be used for output when writing to an IBM TS7700 Series virtual tape device, an appropriate DATACLASS= value must be specified on the TAPEOUT DD so that your SMS ACS routines will direct the TS7700 to use the desired compression type.

If you are using the VIRTZSTD keyword to display compression information when writing to an IBM TS7700 Series virtual tape system, you must use all of the following on the TAPEOUT DD statement so that the virtual tape device will refresh the information that it generates for FATSCOPY to determine output file compression statistics:

• FREE=CLOSE
• DISP=(,KEEP)
• UNIT=(,,DEFER)

ARCHIVE DD statement

(ABR customers only) The ARCHIVE DD statement is used to specify the name of the ARCHIVE Control File that will be updated if any ABR Archive or Application Backup data sets are copied due to the use of ABRARC=YES. If ABRARC=YES is specified and no ARCHIVE DD is present in the JCL, FATSCOPY will attempt to dynamically allocate the Archive Control File using the Archive DSN in the FDR Options Table.

MAPTAPE DD statement

The MAPTAPE DD statement is required when using the PHYSVOL, ALLPHYS, or VIRTZSTD keywords with an IBM TS7700 virtual tape system.

• When used with PHYSVOL or ALLPHYS, it describes a standard label tape data set on the virtual tape device containing the input volumes to be copied. The TS7700 cannot be a disk-only configuration, i.e. it must use physical tapes for storing logical volumes.
• When used with VIRTZSTD, it describes a standard label tape data set on the virtual tape device containing the output volumes.

This data set is used by FATSCOPY to request tape mapping or status information from the TS7700, and by the TS7700 to communicate the results back to FATSCOPY. Use the DCB characteristics from the following example: 

FATSCOPY uncatalogs the MAPTAPE data set at the end of the job.

For PHYSVOL and ALLPHYS, this data set is used by FATSCOPY to perform selection of volumes for both SIM and COPY jobs. (It is not needed by a COPY job using RESTART.) If you are using the ISPF panels to do an online SIM with the PHYSVOL or ALLPHYS keyword, your TSO userid must have the MOUNT attribute.

For VIRTZSTD, this data set is used to retrieve output data set compression information from the TS7700. Instead of using UNIT=, use the same DATACLAS= value as on the TAPEOUT DD statement. Since each output data set and volume requires a separate query to the device, a new MAPTAPE volume will be dynamically allocated for each output data set written, and for each volume of a multivolume output data set. These MAPTAPE volumes will be allocated with RETPD=0.

PUNCH DD statementThe PUNCH DD statement is required when using the PUNCH keyword. The PUNCH DD statement specifies a partitioned data set (PDSE or PDS) that will be used as the “punch library“ in which FATSCOPY will create members containing FATSCOPY jobs. To create a new PDSE, use the DCB characteristics in the following example:

If you want to create a PDS instead of a PDSE, use DSNTYPE=PDS instead of DSNTYPE=LIBRARY, and be sure the directory value in the SPACE parameter (50, in the example above) is large enough to accommodate the number of members you expect to create with your PUNCH jobs. If the PDS is not large enough to hold a new member, a SB14 abend will occur.

For a PUNCH job using an existing punch library, use

See Writing FATSCOPY Jobs to a Partitioned Data Set for more information on using the PUNCH DD statement.

JCLMASK DD statement

The JCLMASK DD statement is used to specify a JCLMASK data set when using the PUNCH keyword. The JCLMASK data set provides the JCL that will be inserted by the PUNCH job into the FATSCOPY jobs that it creates in the punch library.

The JCLMASK data set is often defined with in-stream data records following the JCLMASK DD statement (using the DLM= parameter to define the end-of-stream delimiter), but the JCLMASK data set may also be a sequential data set or PDS member specified in the JCLMASK DD statement.

Substitution variables are available to customize the JCL generated by each job created by one FATSCOPY PUNCH job. If the JCLMASK DD statement is omitted, the members in the punch library will contain only FATSCOPY control statements, without JCL.

See Writing FATSCOPY Jobs to a Partitioned Data Set for more information on using the JCLMASK DD statement and the JCLMASK data set.

SYSIN DD statement

The required SYSIN DD statement is the source of FATSCOPY control statements. It is normally a
DD * spool file, but can be any data set with DCB characteristics RECFM=FB and LRECL=80.

DAPRENV DD statement

(Control-M/Tape only) The DAPRENV DD statement is optional. Control-M/Tape generates a large amount of configuration information in SYSPRINT when FATSCOPY updates tape management data for output data sets. To suppress this output, you may specify //DAPRENV DD DUMMY in your FATSCOPY job.

NOSTACK DD statement

(Control-M/Tape only) The NOSTACK DD statement is optional. If Control-M/Tape Dynamic Data Set Stacking is active, that may supersede the output data set grouping done by FATSCOPY, and the output data sets may be grouped differently than expected by FATSCOPY. If you want to override Dynamic Data Set Stacking to ensure that the output data sets are stacked in the way that they are grouped by FATSCOPY , add the following DD statement to your FATSCOPY Copy jobs:

//NOSTACK DD DUMMY Suppress Dynamic Data Set Stacking