SELECT and EXCLUDE Statements for Data Set Restore

SELECT and EXCLUDE statements syntax

SELECT statement

This statement is used with RESTORE TYPE=ABR and selects the data sets to be restored from full-volume or incremental backups. The SELECT statement identifies the individual data set name or group of data sets to be processed. The EXCLUDE statement identifies data sets from within those selected by SELECT statements that are not to be processed. As described in Data Set Restore in Data-Set-Selection, ABR selects the backups of the selected data sets using information in the VTOC of the data set's volume or the ABR scratch catalog, locates the indicated backup on tape or DASD, and restores it. EXCLUDE statements should only contain the operands DSN=, DD=, ALLDSN, VOL=, or TAPEDD=. A maximum of 100 of these control statements may be used in one execution unless overridden by MAXCARDS=.

The control statements are always scanned in the order in which they were input, so in general, EXCLUDE statements should precede SELECT statements. Since ABR only restores data sets that are selected, EXCLUDE statements are required only to exclude certain data sets from within a larger group on a SELECT statement.

Example 1. Select all data sets with a first index of “A” except those with a second index of “B”:

EXCLUDE DSN=A.B.** SELECT DSN=A.**

Example 2: Select all data sets on the backup of volume TSO001 (generation 27, cycle 00) except those beginning with “ABC”:

EXCLUDE DSN=ABC** SELECT ALLDSN,VOL=TSO001,GEN=27,CYCLE=00

NEWNAME / NEWGROUP / NEWINDEX for VSAM

If you are restoring to a preallocated VSAM cluster, where the cluster name is the same as the original, but the components may be named, you must specify the cluster name as both DSN= and NEWNAME=; this causes ABR to LOCATE the new component names. NEWNAME= cannot be specified for clusters with more than one alternate index.

If restoring a VSAM cluster to a new name and the new cluster is to be allocated, specify NEWGROUP= or NEWINDEX=. ABR modifies both the cluster and component names.

VSAM catalogs and VVDSs cannot be restored to a NEWNAME.

For more information, see VSAM-Special-Considerations.

SELECT and EXCLUDE statement operands

Specifies a fully-qualified data set name or a filter to be used for generic data set selection, as described in Generic-Data-Set-Name-Selection. This name or filter is used when scanning the names of data sets on the backups to be restored. For VSAM clusters, only the cluster name is compared; you cannot select by component name. For example:

DSN=USER1.JCL.CNTL

DSN=**LIST

DSN=PROD++.**.LIB*

DSN= cannot select GDGs by relative generation number; use CATDSN= or DD= for that purpose.

If DSN= specifies a fully-qualified name, ABR attempts to locate the requested backup of that data set as described in Data-Set-Selection, and restore it.

If DSN= specifies a filter (any wild-card characters), one specific backup file must be identified, either by the VOL=, GEN=, and CYCLE= operands, or the TAPEDD= operand; ABR reads only that specific backup and does not search for the other backups.

CATDSN=

Specifies a fully-qualified data set name or a filter to be used for generic data set selection from system catalogs, as described in Generic-Data-Set-Name-Selection.

If a fully-qualified name is specified, that name is located in the system catalogs, and the volume serials from the catalog become an implied VOL= parameter, causing ABR to look on those volumes for the DSCB containing backup information). Specification of a relative generation number for GDG data sets is supported, for example, CATDSN=A.B(-1).

If a filter is specified, then catalogs are scanned for all cataloged data sets matching the filter, and they are processed as if a SELECT DSN=dsn,VOL=vol was present for each of them. It may be necessary to specify MAXCARDS=nnnnn if a large number of data sets are selected by the filter.

Additional considerations for CATDSN=filter are explained in Generic-Data-Set-Name-Selection. For VSAM clusters, the filter is only compared to the base cluster name. Component names, PATH names and AIX (alternate index) cluster and component names are not tested.

CATDSN= is supported only on SELECT statements. However, a preceding EXCLUDE statement with DSN= and/or VOL= can exclude data sets from selection by CATDSN=.

If the VOL= operand is also specified on a SELECT statement with CATDSN=, then only data sets cataloged to those volumes are selected. For example,

CATDSN=USER1.JCL.CNTL

CATDSN=PAY**MASTER(0)

CATDSN=PROD++.**.LIB*

Normally CATDSN= does not display the data sets it selects from the catalogs, you see the names only when FDRCOPY actually finds and selects the data sets in the VTOCs of the volumes they are cataloged to. To display all of the data sets selected specify PCATDSN=filter.

ddn

Specifies that a data set name is to be taken from a DD statement. ABR looks for that data set name on the backups. This operand must point to the ddname of a JCL statement. Using this option lets you specify a non-standard data set name or a Generation Data Group (GDG)) relative generation. For example:

SELECT DD=DD1

//DD1 DD DSN=A.B.C(0),DISP=SHR

All data sets found on a specified backup file are to be restored. To use ALLDSN, one specific backup file must be identified, either by the VOL=, GEN=, and CYCLE= operands, or the TAPEDD= operand; ABR reads only that specific backup and does not search for the other backups.

Selected PS and PO data sets are to be reblocked during the restore. See BLKF= in Set-RESTORE-Statement for details.

Default: Data sets are not reblocked unless BLKF= was specified on the RESTORE statement.

catn

Specifies the name of a user catalog (CATALOG=) or alternate master catalog (MCATALOG=) to search when CATDSN= is specified. See Generic-Data-Set-Name-Selection for details.

Default: The catalog search start with the active master catalog. User catalogs are searched if their assigned aliases match the CATDSN=filter.

May be used with CATDSN=filter to limit the selection of GDGs from the catalogs. It does not affect the selection of cataloged non-GDG data sets, but if the filter selects a GDG then:

n

Causes only the most recently created “n” generations to be selected.

–n

Causes only generation (–n) to be selected.

Default: All the generations of selected GDGs are selected (unless a relative generation number is specified at the end of the filter, for example, CATDSN=filter(-2)).

CATNEWN=

Copy the selected data set with a new name. This is similar to the NEWNAME= operand (see NEWNAME= in SELECT and EXCLUDE Statements for Data Set Restore except that a catalog LOCATE is done on the name, and the result is saved as the new name. This is particularly useful if the new name is a GDG and you want to use a relative generation number, for example, CATNEWN=PROD.PAYROLL.MASTER(+1).

n

Specifies the copy (1-9) of the backup from which the restore is to be attempted. COPY=2 can be specified if a duplicate backup (TAPExx) created at backup time. Copies 2 through 9 can be created by the FDRTCOPY or FDRTSEL utilities (see FDR-and-ABR-Backup-Maintenance).

Default: The value from the RESTORE statement or from the FDR Global Options (see BKPCOPY in Set-RESTORE-Statement).

nn

Specifies the cycle number (0 to 63) of the backup ABR is to use to restore this data set. This cycle number is the last two digits of the backup data set name and is displayed in various ABR reports. Use this option if a data set was scratched and was not recorded in the ABR SCRATCH Catalog, or if you wish to restore from other than the most current backup. Its value can range from zero to 63. CYCLE= must be specified with GEN= and VOL=.

If OLDBACKUP was enabled on the data set's DASD volume when dumped, the OLDBACKUP= operand can also be used to request an older backup.

Restore all allocated tracks in each data set selected by this SELECT statement.

No data tracks are restored for any data set type. However, if output data sets need to be allocated, the restore uses the control information on the backup data set to allocate the data set; also, the characteristics of the data set are updated from the backup even if the data set was preallocated. This allows you to preallocate output data sets with a restore without restoring data and recover their contents from another source (such as a database backup). You must use DATA=NONE if the backup was done with DATA=NONE (see DATA= in Volume-Backup-SELECT-EXCLUDE-and-MOUNT-Statements), otherwise, you get error messages indicating data tracks were missing. Member DATANONE in the FDR Installation Control Library (ICL) has more information on the use of DATA=NONE.

Default: Restore only the used tracks of PS and PO data sets, unless DATA=ALL was specified on the RESTORE statement.

STORCLAS=

Specifies the SMS classes to be associated with the data set being restored, overriding the original classes of the data set (if any). The Storage Class and Management Class ACS routines are passed the appropriate class, and they may override them. The Data Class ACS routine is not invoked, and the data class characteristics are not used during allocation or restore.

NULLxxxxCLAS

Changes the specified class to null (not specified).

Default: The original SMS classes of the input data set (if any) is used for the output data set if it is allocated as SMS-managed. For a non SMS-managed input data set, null classes are set.

If the Storage Class ACS routine assigns a storage class to this data set or accepts the class passed, the data set is allocated as SMS-managed, and the SMS Storage Group ACS routine may be invoked to determine the actual target volume. If the Storage Class ACS routine returns a null (blank) storage class name, the data set is allocated as non SMS-managed and the restore procedures listed in ABR Data Set Restore Procedure in Set-RESTORE-Statement for volume selection must select a non-SMS target volume.

Bypass the data set enqueue for data sets selected by this SELECT statement.

Default: The enqueue option is determined by the DSNENQ= operand specified on the RESTORE statement.

GEN=

nnnn

Specifies the generation (1 to 9999) of the backup ABR is to use. If GEN= is used, CYCLE= must also be specified. This value is the “gggg” portion of the tape data set name that has the format FDRABR.Vvolser.Cnggggcc. This option is used to restore from a previous generation of backups or if the information ABR recorded is incorrect.

Default: ABR locates the most recent backup of the data set and restores it.

NEWNAME=

dsn

Restore the selected data set with a new name. Only use NEWNAME= with DSN= or DD=, and not with VSAM clusters unless they are preallocated. If the new name ends in a GDG relative generation number, use the CATNEWN= operand instead (see CATNEWN= in SELECT and EXCLUDE Statements for Data Set Restore).

NEWGROUP=

grp

Restore the selected data sets using a new group name. The characters specified replace the beginning of the input data set name. Take care when periods are used that index levels are not incorrectly changed. ABR checks the new names for valid IBM standards. For VSAM, the new group is applied to the cluster name and all component names. For example,

SELECT DSN=ABC**,NEWG=XYZ

Any data sets restored are renamed to start with characters XYZ.

NEWINDEX=

idx

Restore the selected data sets using a new name formed by adding or replacing one or more index levels in the original name; replacement index levels do not have to be the same length as the original indexes they replace. In the simplest case, each index level specified in NEWI= is used in place of the corresponding index in the original name. Any remaining index levels at the end of the name are copied unchanged. This can easily be used to change the first indexes of the name.

For example, if the input data set is A.B.C.D,

NEWI=D results in D.B.C.D (first index replaced)

NEWI=DD.E results in DD.E.C.D (first 2 indexes replaced)

If a period is specified without any preceding characters, one original index level is copied from the input data set name to the output. This allows easy modification of indexes in the middle of the name.

For example, if the input data set is A.B.C.D,

NEWI=..E results in A.B.E.D (third index replaced)

NEWI=FF...G results in FF.B.C.G (1^st & 4^th idxs replaced)

If + is specified before a new index level, that new index is inserted into the output data set name at that point. If ++ precedes the new index, it is added to the end of the name. If - is specified, the next input index level is dropped from (not copied to) the output name. For example, if the input data set is A.B.C.D,

NEWI=+F results in F.A.B.C.D (new first index added)

NEWI=..+F results in A.B.F.C.D (new third index added)

NEWI=++F results in A.B.C.D.F (new last index added)

NEWI=..– results in A.B.D (third index dropped)

NEWI=Q.–.+E results in Q.C.E.D (combination)

If the NEWI= value ends in a GDG relative generation number, for example, NEWI=..NEWMAST(-2), that relative number is added to the end of the new name, and a LOCATE done to get the proper absolute generation number.

NEWI= is a convenient way to rename every input data set, while using some index levels from the original name and replacing other indexes or adding new indexes. For VSAM, the NEWINDEX= is applied to the cluster name and all component names.

ddn

Specifies the name of a DD statement from which the new name of the output data set is obtained.

Overrides the cataloging options (NOCAT, RECAT, or default) specified on the RESTORE statement, for the data sets selected by this statement. See the description of NOCAT and “RECAT” in Section 50.8.

userid

Specifies that ABR is to notify the TSO user id specified at the completion of the restore. The user id is from 1 to 7 characters.

NVOL=

Specifies the volume serial numbers of output DASD volumes to which data sets selected by this statement are to be restored. You may specify:

• A single specific volume serial, for example, NVOL=ABC123
• A list of specific volume serials, enclosed in parentheses, for example, NVOL=(TSO001,TSO002,TSO003)
• A group of volumes by placing an asterisk at the end of the VOLSER prefix, for example, NVOL=TSO*
• A combination of specific and group, for example, NVOL=(TSO*,PROD*,ABC001)
• All online DASD volumes may be selected by NVOL=*

A list of online target volumes matching your specification is generated by scanning all DASD UCBs in the system UCB chains, but you cannot predict the order of the volume serials in the list. However, if the first or only specification is a specific volume serial, it is chosen as the first target volume, with other volumes placed after it in UCB chain order. If you are restoring a multi-volume data set (non-VSAM or SMS-managed VSAM), the volume sequence number of the piece of the data set being allocated is used to select a specification from your list. For example, if NVOL=(A,B,C), the second piece of the data set goes to volume B. If that specification is a group, the first volume in the UCB chain matching that group is tried. If the allocation is unsuccessful (such as insufficient free space), then other volumes in the NVOL= list are tried as described above.

The first target volume is checked to see if an output data set already exists there. If so, it restores over the existing allocation (unless PRESTAGE was specified). If not, it attempts to allocate the output data set on that volume. If the allocation fails, it is retried on successive volumes in the list until it succeeds or until it fails on 64 volumes. If the list contains several DASD device types, “like” volumes (same type as the data set being restored) is tried first, then unlike devices.

For multi-volume data sets, a target volume is bypassed if a piece of the data set already exists there but is not the right piece, so that it will not attempt to restore the third volume of a data set on top of the first volume. When it finds a target volume in the list that does not contain a piece of the data set, it is allocated.

Specifying multiple volume serial numbers or a volume group allows you to restore data sets in one pass even when no one volume has available space to contain them all; they are spread across many of the target volumes.

Default: The output volume is selected by rules defined in ABR Data Set Restore Procedure in Set-RESTORE-Statement.

NVOL= may be ignored if the data set does not exist on the volume specified and the data set is SMS-managed (see STORCLAS= in SELECT and EXCLUDE Statements for Data Set Restore).

nn

Specifies that ABR is to restore from a backup of this data set taken “nn” backups ago (0 to 13). OLDBACKUP= must be enabled in the ABR Model DSCB on the volume involved. “1” specifies the backup taken prior to the current backup for this data set, “2” the next oldest, and so on. If not specified (or 0) the most current backup is restored unless GEN= and CYCLE= or TAPEDD= are specified. See Data Set Restore in Data-Set-Selection for further explanation.

Specifies that selected data sets are not restored if the output data set already exists on the first target output volume. This may be used to avoid restoring data sets that have already been restored.

Default: Restore preallocated data sets, overlaying the existing contents of those data sets, unless PRESTAGE was specified on the RESTORE statement.

When used on a SELECT statement with CATDSN= it displays all of the alias names and user catalogs which were searched, if the mask provided causes the search to start in the master catalog.

%FREE=

See RLSE and %FREE= in Set-RESTORE-Statement. If these operands are specified on a SELECT statement, they override space allocation for data sets selected by the statement.

x

Specifies the same character as specified in a TAPEx DD statement. This option is used to override ABR’s selection of the backup tape from which to restore this data set. A TAPEx DD statement must be provided giving all the values necessary to point to the backup file to be restored from. For example:

Do not use DYNTAPE and TAPEDD= statement in the same execution.

nnnnn

If the data set selected by this SELECT statement must be allocated, CYL= or TRK= specifies the number of cylinders or tracks to be allocated to the data set. On PS or PO files when DATA=ALL was not specified, this value needs to be at least equal to the used portion of the data set. On all other types of files and when DATA=ALL is specified, this value needs to be equal to or greater than the original size of the file. For VSAM clusters, modifies the size of the base data component only. If the space is too small for a non-VSAM data set being restored, the data set is automatically extended. Maximum value that can be specified is 65535.

Default: Use the original size of the data set unless RLSE or %FREE= was specified.

vol

Specifies the DASD volume serial number from which the data set name was dumped. VOL= must be specified if the original data set is not cataloged or recorded in the Scratch Catalog.

(See Data-Set-Selection).

Allows VSAM clusters to be allocated and cataloged even if they already exist in the target catalog. See VRECAT in Set-RESTORE-Statement for details. If specified on a SELECT statement, applies only to clusters selected by that statement.