COPY/SIM statement

A COPY or SIM control statement is required and must be the first statement. However, all of its operands are optional. Operands may appear in any order on the statement.

A SIMULATE (SIM) statement causes FATSCOPY to simulate the copy operation. It will scan the catalogs and tape management records according to your SELECT/EXCLUDE statements and it will display the data sets that it will select and show the order that they will be copied to output tapes. SIM will not open TAPEOUT (which can be omitted) and it will not mount or read any input tapes. By default, SIM will create an estimate of the number of output tapes needed to copy all of the data sets and a report showing the VOLSERs of the input tapes needed for the job. SIM can be used in conjunction with the CHECKPT keyword to create a data set to be used as input to a subsequent FATSCOPY job to actually copy the data sets.

Operands

The following operands can be specified on a COPY/SIM statement. For each of the operands below, the default value set by the FATSCOPY program or contained in the FATSCOPY Option Table shipped with the FATSCOPY product follows the operand. The values for many operands can be changed using the FATZAPOP program (described in Displaying and Modifying FATSCOPYDefaults). Any of the operands whose defaults are followed by an asterisk (*) may be changed by the system programmer at your installation. To display the options currently in effect in your installation, run the FATZAPOP program with the PRINT control statement. You should use the ECHO=YES operand on the FATSCOPY COPY/SIM statement if you have any question about the options currently in effect in your installation.

These operands are ignored if SELECT ALLDSN statements are used to select tape volumes to copy.

ABEND|RETCODE

ABEND causes FATSCOPY to terminate with a U0888 or U0300 abend when serious errors are found. ABEND cannot be used when RETCODE is also specified.

RETCODE causes FATSCOPY to terminate with a return code (condition code) of 12 when serious errors are found. RETCODE cannot be used when ABEND is also specified.

ABRARC=

(ABR customers only) Controls whether ABR Archive or Application Backup data sets can be selected for copying:

YES - ABR Archive and Application Backup data sets that match the data set selection criteria will be automatically included in the files that are copied. FATSCOPY will update the ABR Archive Control File or ABR Application Control File to reflect the new volume(s) containing the archive and application backup data sets that have been copied.

If the ARCHIVE DD JCL statement has been used, then the data set specified by that DD statement is assumed to be the ABR Control file to be updated. If no ARCHIVE DD is present, the FDR Options Table will be used to determine the name of the Archive Control File to update.

If the ABR modules are not in a LINKLIST library, a STEPLIB or JOBLIB DD must be included for the ABR load library. ABR level 5.4/70 or higher is required.

NO – ABR Archive and Application Backup data sets will not be selected, even when they otherwise match the data set selection criteria.

Delivered default(*): ABRARC=NO

ABRINDEX=

(ABR customers only) Specifies the ABR prefix (first index level) of the ABR ARCHIVE and BACKUP files to be copied. This may be used with FDR Application backups.

Delivered default(*): The ABRINDEX value in the FDR Global Options Table, usually “FDRABR”

ADDXDAYS=

If TMSINPUT=SCRATCH is specified, this value (0 to 999) is added to the current date to calculate the date on which input tapes will be scratched. Though it is recommended to use the default value, RMM-controlled tapes with Vital Record Retentions will be retained indefinitely unless ADDXDAYS=0 is specified.

Delivered default(*): ADDXDAYS=4 (retain for 4 days, then scratch)

ARCBACKUP=

(ABR customers only) When copying Archive or Application Backup files, this parameter directs FATSCOPY to invoke FDRDSF to DUMP the ABR Control File used in this step as the last file on the tape once all files have been copied. This operates the same as the ARCBACKUP=DSF option of ABR. If no ABR archive or backup data sets were copied, FATSCOPY will not backup the ABR Control Files.

The file used as the ABR Control File is that specified on the ARCHIVE DD JCL statement, if present; otherwise, the FDR Options Table will be used to determine the name of the ABR Control File to update. If the ABR modules are not in a LINKLIST library, a STEPLIB or JOBLIB DD must be included for the ABR load library.

ARCB1DSN=

(ABR customers only) Specifies the data set name to be used on the output tape for the backup of the Archive Control File that is done if the ARCBACKUP=DSF operand has also been specified.

Delivered default: The index level ARCHIVE in the existing ABR Control File data set name will be changed to ARCBKUP.

AUDITLOG=

“logstreamname” specifies the name of a system logger log stream which is being used to record FATSCOPY audit records. When AUDITLOG= is used, an audit record of each data set copied is written to the system logger. See Writing Audit Records for information on using the system logger to write audit records.

If an AUDIT DD statement is also used, the AUDITLOG= keyword is ignored, and all audit records will be written to the sequential data set specified by the AUDIT DD statement.

BUFNO=

Specifies the number of buffers FATSCOPY will use to copy data. Values are from 2 to 25.

Delivered default(*): BUFNO=10

CAT=

Controls cataloging of data sets copied to the output tape:

ONLY – output data sets will be cataloged only if the equivalent input data sets are cataloged. The catalog must point to the matching volser and file sequence number of the input data set.

NO - output data sets will not be cataloged.

YES - output data sets will be cataloged if they are not already cataloged.

RECAT - output data sets will be cataloged; if they are already cataloged, the catalog will be updated.

Delivered default(*): CAT=ONLY

CHECKPT

(SIM only) Used to create a data set that can be used as input to a subsequent FATSCOPY job that will copy all of the data sets selected by the simulation. The CHECKPT keyword requires a DSNTABLE DD in the JCL.

COPYOWNR

(RMM only) Used to specify that the RMM Owner information for the output volume will be copied from the Owner information for the input volume when SELECT CATDSN is being used. (By default, the owner information is propagated only when SELECT ALLDSN is used.) If TMSDATA=NOCOPY is also specified, then COPYOWNR is ignored.

DUMP=

Controls whether an ABEND dump will be produced for errors that don’t usually produce a dump, such as U0100, U0888, U0913, and U0502 ABENDS.

YES – produce a dump for these ABENDs, if a SYSUDUMP or SYSABEND DD is provided

NO – do not produce a dump

ASK – ask the operator, via a WTOR, if a dump should be produced.

Delivered default(*): DUMP=NO

ECHO=

Used to produce a display of the values of FATSCOPY options used by this job. It shows the values resulting from keywords you have specified, and other values used by default from the FATSCOPY Global Options Table.

NO – do not echo the FATSCOPY option values in SYSPRINT.

YES – echo the FATSCOPY option values in SYSPRINT.

Delivered default(*): ECHO=NO

EXCRPGM=(pgmname,…, pgmname)

Used to exclude data sets from being copied if one of the pgmnames specified matches the name of the program that created the data set. For example, specifying EXCRPGM=(FDRDSF) will exclude any data set that was created by FDRDSF. The keyword requires a fully qualified program name, accepts up to 10 values, and can be used for either CATDSN or ALLDSN processing.

Delivered default: None

EXLASTJOB=(jobname,…, jobname)

Used to exclude data sets from being copied if one of the jobnames specified matches the name of the job that last used the data set. Each jobname can be either a 1-8 alphanumeric character job name, or a 1-7 alphanumeric character job name prefix followed by an asterisk. For example, specifying EXLASTJOB=FATS* will exclude all data sets that were last used by jobs whose names start with FATS. This keyword accepts up to 10 values, and can be used for either CATDSN or ALLDSN processing.

This keyword is supported only when the tape management system is RMM, Zara, Control-M/Tape, or TLMS.

Delivered default: None

EXLASTPGM=(pgmname,…, pgmname)

With RMM, Control-M/Tape, or Zara, used to exclude a data set from being copied if one of the pgmnames specified matches the name of the program that last used the data set.

With CA 1, used to exclude a data set from being copied if one of the pgmnames specified matches the name of the program that last used the volume (or multivolume set) containing the data set.

For example, EXLASTPGM=FATSCOPY will exclude all data sets that were last used by FATSCOPY . The keyword requires a fully qualified program name, accepts up to 10 values, and can be used for either CATDSN or ALLDSN processing. This can be used to avoid copying data sets that were already copied by FATSCOPY.

This keyword is supported only when the tape management system is RMM, Zara, Control-M/Tape, or TLMS.

Delivered default: None

EXPDTGROUP=

nnn specifies the allowable spread of expiration dates when FATSCOPYis stacking data sets. nnn may be 0-999. The purpose of this keyword is to group together data sets that will expire within a few days of one another, so that one data set with an especially long retention will not cause the tape to be retained far past the expiration of other data sets on the tape. Data sets with special expirations (such as 99000 (catalog control) and 99nnn (cycle control)) will be grouped separately from data sets with explicit expirations (unless EXPDTGROUP=999 is specified).

EXPDTGROUP=999 is a special value that indicates that expiration dates will be ignored when stacking data sets, so that data sets with any expirations will be stacked together. When EXPDTGROUP=999 is specified, all data sets on the selected input tapes will be copied to a single output tape (or multi-volume tape set), except that the MAXFILE= operand may also be used to limit the number of input files to be copied to a given output tape. The value “999” is always honored regardless of the value of the GROUPBY= parameter.

When GROUPBY=VOLSET has also been used, other values of “nnn” are ignored; expiration dates are not used to group data sets. Each input volume (or multi-volume tape set) will be copied to a separate output tape or tape set.

If LASTAPE= is specified, EXPDTGROUP=999 is forced.

Delivered default(*): EXPDTGROUP=7

EXPIRED=

YES – both expired and non-expired data sets (according to tape management data) may be selected.

NO – only data sets that are not expired in your tape management system may be selected. If a volume is in scratch status, data sets will not be selected from the volume even if EXPIRED=YES is used. If you need to copy a data set from a tape that is in scratch status, you must update the volume’s record in your tape management system to take it out of scratch status.

Delivered default: EXPIRED=NO when SELECT CATDSN is used; EXPIRED=YES when SELECT ALLDSN is used.

GROUPBY=

Specifies how the output data sets should be grouped. Each group of data sets will be used to create a separate output volume (or multivolume set).

VOLSET – Output data sets will always be grouped the same way they are grouped on the input volumes. All of the files selected from a single input volume (or multivolume set) will be grouped together on the output volume(s). GROUPBY=VOLSET minimizes the number of input tape mounts required. When GROUPBY=VOLSET is used, the value of EXPDTGROUP=nnn is ignored, except that EXPDTGROUP=999 is always honored.

EXPDATE – Output data sets will always be grouped by the expiration dates of the input files. The allowable spread of expiration dates used to group files together is the value specified by the EXPDTGROUP= parameter. GROUPBY=EXPDATE may result in many tape mounts for an individual input tape.

Delivered default: GROUPBY=VOLSET for SELECT ALLDSN; GROUPBY=EXPDATE for SELECT CATDSN.

HSMBAKMASK= | HSMMIGMASK=

If your installation does not use the default IBM data set names for your DFSMShsm (HSM) backup and migration data sets, you can specify masks or fully-qualified data set names that FATSCOPYcan use to identify these data sets. See 32.5 Data Set Name Filters (Masks) for details on specifying a data set name mask.

By default, FATSCOPYwill automatically exclude these backup and migration tape data sets. (If HSMML2=YES is specified, HSM ML2 data sets will not be excluded.)

Delivered default(*): the following masks will be used by FATSCOPYto identify and exclude HSM backup and migration data sets.

HSMML2=

Controls whether or not HSM Migration Level 2 data sets will be copied:

NO - HSM ML2 data sets will be excluded from copying.

YES - HSM ML2 data sets will be copied; an HSM RECYCLE command will be issued to copy any HSM ML2 data sets and update the HSM MCDS.

The rules for determining which data sets are considered to be HSM ML2 data sets are determined by the HSMMIGMASK parameter. If HSMMIGMASK has been specified, then the files considered to be HSM ML2 data sets are those that match the user-specified mask. If HSMMIGMASK is not specified, they are the ones that match the IBM default data set masks for migrated data sets, as listed above under the HSMMIGMASK= parameter.

Delivered default(*): HSMML2=NO

IMAGE

Used to create an image copy of a volume. An image copy is an exact bit-for-bit copy of an input tape, including the volume label, header and trailer labels, and all data files on the tape. The tape management information for the volume is updated so the information relates to the device where the volume is located after the image copy.

An image copy can be useful when you are migrating your tapes from one tape device to another, and want to maintain the original VOLSER and the position of each file on the volume. The original tape management information, such as, creation date, expiration date, etc., will be maintained; however, the device type, library name, storage group, etc. will be updated to reflect the new tape.

When using IMAGE, do not specify EXPDT=98000 on the TAPEOUT DD statement. The output volume must be under tape management control.

Many software products maintain databases that record the VOLSER, file sequence number, and/or block position of each file on the tape that they control. As long as the product using your tape does not record and use the device type for the tapes in its database (or you copy to the same device type as the input tapes), the image copies produced by FATSCOPY will be usable by the product on the output device.

LASTAPE=

If files are being stacked on an output tape (MAXFILE= is greater than 1), LASTAPE= allows an output tape to be used in multiple FATSCOPY runs, adding additional files to the tape in each run. LASTAPE= specifies a valid fully-qualified data set name (up to 44 characters). The data set name may also be a GDG; specify the GDG base name followed by “(0)”. At the end of a FATSCOPY step, an empty file with this data set name will be created and cataloged, to mark the last file created on the tape (for a GDG, the +1 generation will be created). In a subsequent FATSCOPY step (even in a different job), FATSCOPY will determine if the data set is cataloged; if so, the previously-used tape will be mounted and repositioned to the LASTAPE file number so that additional files can be added to the tape after that point. If the LASTAPE data set is not cataloged, FATSCOPY will call for a fresh scratch tape. If you don’t want FATSCOPY to use a previous tape, simply uncatalog the LASTAPE name. LASTAPE= is mutually exclusive with the OUTFSEQ= operand.

When this parameter is specified, FATSCOPY will not allow a multi-volume output tape to be created, unless LASTMULT is also specified.

If you are using a DATACLAS or STORCLAS on your TAPEOUT DD statement to assign the output device, you must add UNIT=(,,DEFER) to the TAPEOUT DD statement to allow FATSCOPY to call for a mount of the correct output tape.

If LASTAPE= is specified, EXPDTGROUP=999 is forced.

LASTFILE=

If files are being stacked on an output tape (MAXFILE= is greater than 1), LASTFILE= controls how FATSCOPY operates when the end of the output tape is reached. nnnn specifies a number of megabytes (MB). FATSCOPY will continue to add additional files to the current output tape until either MAXFILE= files have been written to the tape or the end of tape (EOT) is reached. If EOT occurs, FATSCOPY will calculate how many bytes from the current input file (the last file on the output tape) have been written. If the calculated megabytes is less than LASTFILE=, FATSCOPY will delete that file from the output tape, call for a fresh scratch output tape, and recopy the current input file to the output tape. If more than LASTFILE= megabytes have been copied from the current input file to the output tape, FATSCOPY will call for a fresh scratch tape and continue to copy that input tape, creating a multi-volume output tape.

LASTFILE= does not apply to the first output file on a given output tape volume; if the current input file completely fills the output tape, it will always create a multi-volume output file.

LASTFILE= is ignored if a SELECT ALLDSN statement is used to select data sets, unless EXPDTGROUP=999 is also specified.

Delivered default(*): LASTFILE=1000 which is 1000 Megabytes or 1 Gigabyte (GB).

LASTMULT

If LASTAPE is specified, by default FATSCOPY will not allow a multi-volume output tape to be created. However, if LASTMULT is also specified, FATSCOPY will use the LASTFILE= value (or its default) to determine whether to create a multi-volume tape. LASTMULT is mutually exclusive with the THRESHOLD= operand.

LINECNT=

nnnnn (1-32767) specifies the number of lines per page to print on all FATSCOPY print data sets.

Delivered default(*): LINECNT=60

LOGERROR=

When using the system logger to write audit records, this specifies what FATSCOPY should do if it encounters an error when attempting to write an audit record to the log stream.

ABEND – Terminate the job with an abend.

CONTINUE – Write a warning message, but continue copying data sets.

Delivered default(*): LOGERROR=ABEND

MAXERR=

nnnnn (1-32767) specifies the maximum number of major errors (non-data check errors) that are allowed to occur on a file being copied before FATSCOPY will stop copying the file. Non- data check tape errors are usually equipment check errors or intervention required (tape no longer ready) conditions; these may indicate problems with the input tape drive or with the current input tape. Exceeding “nnnnn” major errors on an input tape file will cause FATSCOPY to stop copying the current file. FATSCOPY will then reset the major error count to '0' and attempt to copy another selected tape file, if any remain.

Delivered default(*): MAJERR=1, stop copying the current file after the first major error.

MAJERR=

nnnnn (1-32767) specifies the maximum number of data checks that are allowed to occur on a file being copied before FATSCOPY will stop attempting to copy the file. Data checks usually indicate an error on the current input tape, but can also indicate errors with the tape drive.

Encountering “nnnnn” data checks on an input tape file will cause FATSCOPY to stop copying that file. FATSCOPY will then reset the data check count to '0' and attempt to copy another selected tape file, if any remain.

Delivered default(*): MAXERR=1, stop copying after the first data check.

MAXFILE=

nnnnn (0-65535) specifies the maximum file number to create on the output tape. If MAXFILE= is not equal to 1, then tape stacking (writing multiple files on an output tape) will be done. Once nnnnn files have been written on an output tape it will be dismounted and a fresh scratch tape will be mounted to receive new copied files.

If MAXFILE=1, then no stacking will occur and a fresh scratch tape will be mounted for each output file.

If MAXFILE=0, tape stacking will be done. Files will be added to the output tape until it reaches its capacity, at which point a fresh scratch tape will be mounted to continue copying files.

Delivered default(*): MAXFILE=0

MAXRBLK=

nnnnnn is a decimal number (4-262144) giving the largest input blocksize to be considered for reblocking. MAXRBLK= is meaningful only if REBLOCK= is also specified. Any input file whose blocksize on TAPEIN is greater than n will not be reblocked. .

Delivered default: All files are reblocked if REBLOCK= is specified.

MAXTERR=

If nnnnnn temporary data checks are detected on TAPEIN, FATSCOPY will stop copying the current file, issue a non-zero return code, and start a new file. n may be 1-32767.

Delivered default(*): MAXTERR=100

MAXTOTFILE=

(CATDSN only)

nnnnn (1-65535) specifies the maximum number of input tape files to copy in this FATSCOPY step. Once nnnnn files have been selected for copying, FATSCOPY will stop searching the catalogs for additional files.

Delivered default(*): MAXTOTFILE=1000

MAXVOLS=

nnn (1-256) specifies how many SELECT ALLDSN,VOL= statements are created in each job generated with the PUNCH keyword. After nnn SELECT statements are created for a job, that job is written to a member in the punch library specified by the PUNCH DD, and a new member is created if more SELECT ALLDSN statements are to be generated.

MAXVOLS= is frequently used in conjunction with NUMVOLS=. When NUMVOLS specifies a large range of volumes, MAXVOLS can be used to break this up into a smaller number of volumes per job in the punch library.

See 32.7 Writing FATSCOPY Jobs to a Partitioned Data Set for more information on using MAXVOLS=.

Delivered default: MAXVOLS=1

MULTIFILE=

(CATDSN only)

Controls whether multi-file input tapes will be copied. When you are using FATSCOPY for tape stacking, this can be used to avoid copying tapes that already have stacked files (more than one file on the tape).

NO - tapes containing multiple files will not be copied.

YES - tapes containing multiple files will be copied. If you are using FATSCOPY to migrate tape files to a new type of tape, you will probably want to specify MULTIFILE=YES.

Delivered default(*): MULTIFILE=YES - tapes containing multiple files will be copied.

MULTIVOL=

Controls whether multivolume files or sets will be copied.

YES – files that are located on single volume and multivolume sets will be copied.

NO – with SELECT ALLDSN, files that are located on multivolume sets will not be copied. With SELECT CATDSN, multivolume files will not be copied.

ONLY – with SELECT ALLDSN, only files that are located on multivolume sets will be copied. With SELECT CATDSN, only multivolume files will be copied.

For SELECT ALLDSN, MULTIVOL= controls file selection whether or not an individual file is a multivolume file. For example, a single-volume file which is located on a volume that is part of a multivolume set will be selected if MULTIVOL=YES or MULTIVOL=ONLY is specified, and bypassed if MULTIVOL=NO is used.

Delivered default(*): MULTIVOL=YES - both single volume and multi-volume tapes will be copied.

NOSUPULAB

See SUPULAB | NOSUPULAB .

NOTCATRC=

(ALLDSN only)

This specifies the return code that will be issued by FATSCOPY when SELECT ALLDSN and CAT=ONLY are specified, and FATSCOPY is unable to catalog the output data set because the input wasn‘t cataloged. Allowed values are 0, 4, and 8.

Delivered default(*): NOTCATRC=0

OFFSITE=

Controls whether tape volumes that are recorded in your tape management system as being off-site (vaulted) will be copied. Usually tapes that are off-site should not be copied because they are off-site and cannot be mounted. If you have a special reason for copying tapes that are marked as off-site and are sure they are available to be mounted, you can request that they be copied.

NO - off-site tapes will be automatically excluded.

YES - tapes marked as off-site will be selected for copying, as well as on-site tapes. Be sure that your SELECT statements will select only those off-site tapes that you know are actually available for mounting.

ONLY – only off-site tapes will be selected.

Delivered default(*): OFFSITE=NO

OPCAP=

(used with SIMulate only) “nnnn” is a decimal number (1-9999) specifying the approximate uncompressed capacity of the output tapes, in gigabytes, that will be needed to copy the data sets selected during simulation. The output will display the approximate number of output tapes that will be required with no compression and with 3:1 compression, as well as a report showing the VOLSERs of the input tapes that will be needed for the copy job. For example, use OPCAP=10 if standard single-density 3590 tapes will be used for output.

Delivered default(*): OPCAP=10

OUTFSEQ=

Specifies the file sequence number (1-65535) to be assigned to the first file written to TAPEOUT. This should be used only when adding files to an existing output tape; specify a value one larger than the last file on the tape. You must also specify the volser of the tape you want to append to on the TAPEOUT DD statement.

Note that values up to 9999 can also be specified by the LABEL= operand on the TAPEOUT DD statement. OUTFSEQ= is mutually exclusive with the LASTAPE= operand.

Delivered default: OUTFSEQ=1

PUNCH

Specifies that you want to generate FATSCOPY job streams where each job consists of a limited number of SELECT ALLDSN,VOL= statements which can be run at a later time. These job streams are saved as members in a partitioned data set specified by the PUNCH DD (the “punch library”). The number of SELECT statements per job stream is specified by the MAXVOLS= keyword. The JCL to be used in each job stream is specified in the JCLMASK data set.

A job with PUNCH does not perform any data set selection. The data set selections are done when running the jobs generated in the punch library.

When the PUNCH keyword is specified, the PUNCH DD statement is required. PUNCH can be used only when SELECT ALLDSN,VOL= selection statements are used. PUNCH cannot be used with PHYSVOL=, ALLPHYS=, or SELECT CATDSN.

If the PUNCH keyword is used without also using a JCLMASK DD statement, then only FATSCOPY control statements are written to the members in the punch library.

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

REBLOCK=

nnnnnn is a decimal number (4-262144) specifying the target blocksize for data reblocking. When this keyword is specified, input files with blocksizes less than “n” will be reblocked as they are copied to blocksizes as close to n as possible.

FATSCOPY only reblocks to larger blocksizes. Input files with blocksizes larger than “n” will not be reblocked. (FATAR may be used to reblock to smaller blocksizes.) MAXRBLK= may be specified to bypass reblocking on files that already have an acceptably large blocksize.

Delivered default: Blocks are copied exactly as read from the input tapes, without reblocking.

RESTART

Used to restart a job using the data set created by a SIM job with the CHECKPT or a previous job that was stopped before all of the data sets selected for copying were copied. When RESTART is specified, FATSCOPY copies all of the data sets that weren't copied in the previous run. A DSNTABLE DD is required when RESTART is specified.All SELECT and EXCLUDE statements are ignored.

RETCODE

See ABEND|RETCODE above.

RETRY=

(RMM only) Specifies the maximum number of times FATSCOPY will retry a failed RMM update when RMMFAIL=RETRY has also been specified. FATSCOPY will wait 30 seconds for each retry attempt. “nnn” may be 0-255.

Delivered default(*): RETRY=0

RMMFAIL=

(RMM only) Determines how FATSCOPY is to proceed when an update of tape management information fails because RMM housekeeping happens to be running at the same time.

CONTINUE – FATSCOPY will issue a non-zero return code and an error message indicating that the RMM update failed, but continue copying any remaining data sets.

RETRY -- retry the failed update 'nnn' times based on the value of the RETRY= parameter. When the maximum number of retries is reached, FATSCOPY will issue a non-zero return code and an error message, and stop copying data sets. Note that, for each retry, FATSCOPY will wait 30 seconds.

STOP – immediately stop copying data sets after issuing a non-zero return code and an error message. (This works the same as RMMFAIL=RETRY with RETRY=0.)

Delivered default(*): RMMFAIL=CONTINUE

SELTERR=

If FATSCOPY finds that a SELECT or EXCLUDE statement was never referenced (no data set on any input tape was selected by the statement):

YES -- a U0300 ABEND error will be issued at step termination to call attention to a possible control statement error.

NO – an ABEND error is not to be issued at step termination. A return code of 0 will be issued. You might use SELTERR=NO when you expect some unmatched SELECT/EXCLUDE statements, perhaps because some data sets may not exist.

Delivered default(*): SELTERR=YES

SHOWNEWN

SHOWNEWN causes FATSCOPY to display in the Copy Report the new names of data sets assigned by the RENAME statement.

SORT=

The SORT keyword is used only when SELECT CATDSN has been used to select data sets.

YES will cause the data sets to be sorted by expiration date group, VOLSER, and file sequence number after they have been selected, and to be copied in that sorted sequence. SORT=YES usually minimizes the number of input and output tape mounts required.

NO turns off sorting by expiration date group, VOLSER, and file sequence number. When SORT=NO is specified, data sets are copied in the sequence they appear in the SELECT statements. This is used when you want the data sets to be copied in a specific order. It may result in many more input tape mounts being required during the copy process. If EXPDTGROUP=999 is not specified, many more output tape volumes may also be required than if SORT=YES is used.

When SELECT ALLDSN is specified, the SORT keyword is ignored. Volumes are copied in the order in which they are listed in the SELECT statements (unless part of a multivolume set, in which case the volumes in the multivolume set are processed in the order they occur in the set).

We recommend using the default value of SORT=YES.

Delivered default(*): SORT=YES

SUPULAB | NOSUPULAB

SUPULAB specifies that copying of user labels from the input file to the output file should be suppressed. If an input file has user labels, they will not be copied to the output file. This may be needed when you have an encryption product (such as CA Tape Encryption) that writes its own user labels that contain the file’s encryption keys.

NOSUPULAB specifies that user labels, if present, will be copied from the input file to the output file (i.e. copying of user labels will not be suppressed).

Delivered default(*): NOSUPULAB

THRESHOLD=

If LASTAPE= is specified, then THRESHOLD= specifies a percentage (1 to 99) used to determine when FATSCOPY will add another file to the current output tape. Before opening each new output file, the THRESHOLD= value is compared to the percentage used of the current volume, as reported by your tape management system. If the threshold is exceeded, FATSCOPY will close the current tape and call for a fresh scratch tape. Note that the percentage used may not be recorded by your tape management system for all types of tape. THRESHOLD= is mutually exclusive with the LASTMULT operand.

The THRESHOLD keyword is not supported when the tape management system is TLMS.

TMSDATA=

Specifies whether tape management data from each input file is to be copied to the output file after the input file is successfully copied.

COPY will copy the tape management data from the input file to the output file. This data includes: creation date, creating job name, and creating step name.

NOCOPY not copy the tape management data. The tape management records for the output file will show the current date as the creation date, and the FATSCOPY job/step as the creating job/step.

Delivered default(*): TMSDATA=COPY

TMSIN=

This keyword should be used ONLY if you have more than 1 active tape management system and you need to copy tapes using a tape management system different from what you have configured during FATSCOPY installation.

FATSCOPY will normally determine the tape management system used for the input tapes by testing which FATS tape management interface you have installed, but if you have multiple tape management systems on your system, you may specify which system controls the tapes you are copying:

RMM - the input tape management system is IBM's DFSMSrmm.

CA1 - the input tape management system is Broadcom/CA Technologies’ CA 1 (TMS).

Delivered default: If both interfaces are installed, DFSMSrmm is assumed to be the input tape management system. Otherwise, the installed interface is used.

TMSINPUT=

Specifies how the input tape files are to be handled by your tape management system after they are successfully copied.

KEEP will retain the input files. Note: if the retention of the file is “catalog control” and the file is re-cataloged to the output tape (via CAT=RECAT), the tape may still be scratched.

SCRATCH will expire each input file after it is copied. This value is not allowed if your tape management system is Zara. If all files on an input tape are scratched, your tape management system will return the tape to scratch status. By default, FATSCOPY will retain a volume 4 days before it is scratched. You can set this value higher or lower using the ADDXDAYS keyword.

When TLMS or CA 1 is the tape management system, special processing is used when scratching the control data set (TLMS) or first data set (CA 1). Since scratching this data set results in the entire volume (or multivolume set) being expired regardless of the expiration dates of the other data sets on the volume, FATSCOPY sets the expiration date of this data set to the highest expiration date of all the unexpired data sets remaining on the volume/ multivolume set. If FATSCOPY successfully copies all the files on the volume/multivolume set, it then goes back and resets the expiration date of the control data set (TLMS) or first data set (CA 1) to the scratch date.

SCRCOND will expire each input file only if the corresponding output file is successfully cataloged. If the cataloging of the output file fails, the input file will not be expired. This value is not allowed if your tape management system is Zara.

ZARASCR will expire each input file after it is copied. This value is valid only if your tape management system is Zara. If your installation has the Zara “Scratch by 1st” option set to “Y”, we advise against the use of TMSINPUT=ZARASCR. Using this option may result in unintended loss of data. If FATSCOPY expires the first data set on a tape, the volume will be scratched when “Scratch by 1st” is set to “Y”, even if other non-expired data sets remain on the volume.

Delivered default(*): TMSINPUT=KEEP

UNITIN=

Specifies an esoteric (e.g., UNITIN=TAPE), generic (e.g., UNITIN=3490) or specific (e.g., UNITIN=3A0) unit name to be used to dynamically allocate input tapes when SELECT ALLDSN,VOL=volser is specified. A leading slash is required when specifying a specific 4-digit tape device address (e.g., UNITIN=/14B0). The name can be any name that can be used in the JCL parameter UNIT=unitname. UNITIN= can be used whenever a special unit name is required to allocate the proper tape drive to the input tapes selected in this step, such as a drive in a tape library.

If your tape devices are SMS-managed, your ACS routines may override a device-specific tape mount requested by FATSCOPY and instead use another device in the same storage group.

Delivered default: FATSCOPY will query the “last used unit” (last tape device on which the tape was mounted) from your tape management system, determine the generic device type of that unit (e.g., 3590-1) and use that generic unit for dynamic allocation.

VIRTTYPE=

When using a Virtual Tape Server backed by physical tapes, specifies the type of VTS that contains the volumes to be copied. This keyword is used only when the PHYSVOL or ALLPHYS keyword is used on a SELECT statement, in which case VIRTTYPE= is required.

IBM - The tape server’s BVIR function will be used to determine all the logical volumes contained on the specified physical volume(s). When VIRTTYPE=IBM is used, the MAPTAPE DD statement is also required.

STK - The STK/Oracle Host Software Component (HSC) API will be used to determine all the logical volumes contained on the specified physical volume(s). The HSC link library JOBLIB DD statement is also required, if this library is not in the linklist.

Delivered default(*): none

VIRTUNIT=

Specifies the esoteric name (1-8 characters) assigned to CopyCross virtual tape drives, for example, VIRTUNIT=VT3590. The DEVTYPE=COPYCROS parameter must also be specified on the SELECT control statement.

VIRTZSTD

Specifies that compression statistics should be displayed in SYSPRINT when copying data sets to an IBM TS7700 Series virtual tape system that is at code level 8.41.200.xx or later (BVIR function version 8 or higher). When using this keyword, you must also:

• Ensure that the output device is a TS7700 Series device.
• Specify FREE=CLOSE,DISP=(,KEEP),UNIT=(,,DEFER) on the TAPEOUT DD statement.
• Specify a DATACLAS= value on the TAPEOUT DD statement that corresponds to the compression method to be used as determined by your SMS ACS routines. Using one of these compression methods can result in significant space savings for your copied data sets.
• Specify a MAPTAPE DD statement, using a DATACLAS= value that is the same as used on the TAPEOUT DD statement. FATSCOPY uses the MAPTAPE data set to retrieve compression information for the output volume from the TS7700 device. See MAPTAPE DD Statement for information about MAPTAPE.

The following compression information will be displayed in SYSPRINT in the “FATSCOPY FILE TOTALS” for each output data set under these headings:

• COMP BYTES – Compressed number of bytes
• METH – Compression method: FICN (FICON), LZ4, or ZSTD
• %CMP – Percent compression