DSF SELECT and EXCLUDE Statement – for RESTORE

SELECT and EXCLUDE statement syntax

SELECT and EXCLUDE statement for RESTORE

This statement selects the data sets and/or tracks to be restored.

A SELECT statement identifies an individual data set, group of data sets, or range of tracks to be processed. An EXCLUDE statement identifies data sets from within those selected by SELECT statements that are not to be processed. All data sets in the backup files specified by TAPEx DD statements are compared to these control statements to identify those to be restored; each data set is compared to each control statement until a match is found. EXCLUDE statements should only contain the operands DSN=, DD=, ALLDSN, FROM/TO, and TAPEDD=. A maximum of 250 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 DSF 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, and can also be used to EXCLUDE certain tracks.

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 set except those beginning with “SYS” on TAPE2:

    EXCLUDE DSN=SYS**,TAPEDD=2 

         SELECT ALLDSN

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 are named differently, you must specify the cluster name as both DSN= and NEWNAME=; this causes DSF 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 must be allocated, specify NEWGROUP= or NEWINDEX=. DSF modifies both the cluster and component names. This is illustrated in Restore Clusters to New Names Example.

VSAM catalogs and VVDSs cannot be restored to a NEWNAME. DSF properly restores a VSAM catalog even if it has been re-allocated thereby generating a new CATINDEX name.

SELECT and EXCLUDE statement operands

ALLDSN

Specifies that all of the data sets on the backup are restored.

DD=

Specifies that a data set name is to be taken from a DD statement; DSF 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

DSN=

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 DD= for that purpose.

FROM

TO

Identifies a range of track addresses for an absolute track restore. See FROM for details on the syntax and usage.

Absolute track restores are normally used with backups created by absolute track dumps, so that you know what tracks are on the backup. However, you can do absolute track restores from data set or full-volume backups if you know the track addresses available on the backup (a COMPAKTOR MAP or FDRABRP PRINT VTOC can identify those tracks). FROM/TO can be useful for restoring VM mini-disks from a full-volume or absolute track backup of a VM volume; get the limits of the mini-disk from the VM directory.

When selecting an output volume for a absolute track restore, the rules defined in Target DASD volume selection rules are used except for cataloged output data set name (since there is none); normally a DISKx DD statement or NVOL= operand are used to identify the output volume. If the output volume is not the original volume, use FROM/TO with care to avoid overlaying valid data sets.

BLKF=

nn-Selected PS and PO data sets are to be re-blocked during the restore. For more information, see BLKF=.

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

CATNEWN=

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).

DATA=

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 is 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, otherwise you get error messages indicating data tracks were missing. Member DATANONE in the FDR Installation FDRSAMP has more information on the use of DATA=NONE.

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

DATACLAS=

MGMTCLAS=

STORCLAS=

NULLDATACLAS

NULLMGMTCLAS

NULLSTORCLAS

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 will not be invoked, and the data class characteristics will not be 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 DSF rules listed in Target DASD volume selection rules for volume selection must select a non-SMS target volume.

DSNENQ=

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 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. DSF checks the new names for valid IBM standards.

Example:

   SELECT DSN=ABC**,NEWG=XYZ

Any data sets restored is renamed to start with characters “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 (3rd index replaced)

      NEWI=FF...G results in FF.B.C.G (1st & 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 first index added)

      NEWI=..+F      results in A.B.F.C.E  (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.

NEWDD=

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

NEWTOCYL=

NEWTOTRK=

For an absolute track copy (FROM/TO), specifies the starting cylinder and track (in decimal) where the tracks should be copied. Both operands should be specified. The first track specified by the FROM operand is copied to this location, and other tracks selected by this SELECT are copied relative to that location.

If omitted, the tracks are copied to their original locations.

For example, to move 10 tracks from cylinder 10 track 5 on VOL001 to cylinder 20 track 0 on VOL002, specify:

NOCAT

RECAT

Overrides the cataloging options (NOCAT, RECAT, or default) specified on the RESTORE statement, for the data sets selected by this statement. See “NOCAT” in Section 20.8 for more information.

NVOL=

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 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 will go 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 Target DASD Volume Selection Rules. When NVOL= is specified, and data sets are selected that are currently allocated and cataloged, DSF restores them to the new volumes, and not to the volume where they are cataloged.

On a system with SMS active, NVOL= may be ignored if the data set does not exist on the volume specified and the data set is SMS-managed (see STORCLAS=).

PRESTAGE

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.

RLSE

%FREE=

See RLSE for more information. If these operands are specified on a SELECT statement, they override space allocation for data sets selected by the statement.

TAPEDD=

x

Specifies a single character matching the “x” in a TAPEx DD statement. If this operand is specified, this statement will apply only to data sets in the backup file pointed to by TAPEx.

Default: Data sets specified are restored from any or all of the backup files specified by the TAPEx DD statements on which they are found.

TRK=

CYL=

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, 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= is specified.

VRECAT

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