SELECT and EXCLUDE Statements

SELECT and EXCLUDE statements

This statement is used with RESTORE TYPE=ARC and selects the data sets to be restored from archive backups. The SELECT statement identifies an individual data set name or group of data sets to be restored. The EXCLUDE statement identifies data sets from within those selected by SELECT statements that are not to be processed. As described in Restore From Archive Backup in FDRABR Data Set Selection, ABR selects the backups of the selected data sets using records in the Archive Control File, locate the indicated backup on tape or DASD, and restore it. EXCLUDE statements should only contain the operands DSN=, DD=, ALLDSN, or VOL=. A maximum of 100 of these control statements may be used in one execution unless overridden by MAXCARDS=.

SELECT and EXCLUDE statements syntax

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 will only restore 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”:

Example 2: Select all data sets that were archived from volume TSO001 except those beginning with “ABC”:

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 have different names from the original cluster, 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, if the new cluster must be allocated, you should specify NEWGROUP= or NEWINDEX=. ABR modifies both the cluster and component names.

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 backup tapes to be restored. For VSAM clusters, only the cluster name is compared; you cannot select by component name. For example:

DSN=USER1.JCL.CNTLDSN=**LISTDSN=PROD++.**.LIB*

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

Specifies that a data set name is to be taken from a DD statement. ABR looks for that data set name in the Archive Control File. This operand must point to the ddname of a JCL statement. Using this option enables you to 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

By itself, ALLDSN restores the most recent copy of every data set in the Archive Control File. You usually use ALLDSN with ADATE=, to request that all data sets archived on the date specified are to be restored.

Only data sets that were archived on the Julian date specified “yyddd or yyyyddd” are selected. Used to qualify a data set on the Archive Control File if the same data set name was archived multiple times. 2-digit year values “yy” less than 70 are assumed to be in the 21st century, for example, ADATE=20123 means 2020.123.

If the data set was archived multiple times on the same day, OLDBACKUP= may also be specified to indicate which to restore.

Selected PS and PO data sets are to be re-blocked during the restore; see BLKF= in Archive-RESTORE-statement for details.

Default: Data sets are not re-blocked unless BLKF= is specified on the RESTORE statement.

Specifies the copy of the backup from which the restore is to be attempted. COPY=2 can only be specified if a duplicate backup (COPY 2) was created during archival or by FDRTCOPY.

Default: COPY=1 unless COPY1 was not created or has expired, then COPY2 is the default if it exists. The default can be made COPY2 in the FDR Global Options (see BKPCOPY in ABR-Options) or by COPY=2 on the RESTORE statement.

Restore the selected data set with a new name. This is similar to the NEWNAME= operand 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).

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

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

STORCLAS=

NULLxxxxCLAS

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 Archive Restore Procedure in Archive-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.

NEWNAME=

Restore the selected data set with a new name. NEWNAME should only be used with DSN= or DD=, and should not be used for VSAM clusters unless they are preallocated. If the new name ends in a GDG relative generation number, use the CATNEWN= operand, documented above, instead.

NEWGROUP=

Restore the selected data sets using a new group name. The characters specified replace the beginning of the input data set name. Care should be taken 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

NEWINDEX=

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 two 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 you to easily modify 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  (1st and 4th 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 1st index added)

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

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

NEWI=..-        results in A.B.D      (3rd 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 is 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.

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 NOCAT in Archive-RESTORE-statement.

Specifies that ABR is to notify the TSO user ID specified at the completion of the restore. The user ID is from one to seven characters.

Specifies the volume serials 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 volume 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) are 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 does 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 Set-RESTORE-Statement. When NVOL= is specified, and data sets are selected that are currently allocated and cataloged, ABR restores them to the new volumes, and not to the volume on which they are cataloged.

SMS may override NVOL= 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).

nnn

When a given data set has been archived more than once, specifies which versions to restore. 0 restores the most recently archived version, 1 the next most recent, and so on, up to a maximum of 127. If ADATE= is also specified, OLDBACKUP= selects from multiple backups of the data set on that date only. (0 selects the last one archived on that date, and so on).

Default: 0.

Specifies that selected data sets will not be 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.

ABR will not restore a data set if it is marked in the Archive Control File as having been previously restored.

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

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 should 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 should 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 will automatically be 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 archived. This operand is used to further delineate a data set on the Archive Control File if the data set name was archived multiple times. (See FDRABR Data Set Selection for a more detailed explanation).

VRECAT

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