RENAME


>>-+-----------------------------------------+-----------------><
   '-REName--+-(pfx)-----------------------+-'   
             |    .-,-----------.          |     
             |    V             |          |     
             +-(----(--on,nn--)-+--)-------+     
             |          .-,-----------.    |     
             |          V             |    |     
             '-((pfx),----(--on,nn--)-+--)-'

RENAME specifies that, if a data set with the old name exists on the output DASD volume, DFSMSdss is to allocate a new data set with the new name and restore the data set. If the data set with the old name does not exist on the volume, the data set is restored with the old name. For a VSAM data set that already exists on another DASD volume and is cataloged, the VSAM data set is restored with the new name unless the new name also exists and is cataloged.

Start of change VSAM data sets can only be renamed during a physical data set restore by using the RENAMEUNCONDITIONAL keyword. If a data set is preallocated with the new name, it is not restored. If a data set is not preallocated, it is restored using the old name. This keyword only applies to movable data sets; therefore, unmovable data sets will not be renamed. RENAME and RENAMEUNCONDITIONAL are mutually exclusive; you cannot specify these keywords together. End of change

Note: If the RENAME keyword is specified in conjunction with the REPLACE keyword, only one of the keywords take effect for any particular data set. The RENAME keyword takes precedence over the REPLACE keyword. If a source data set name matches the RENAME criteria, then rename processing is performed and replace processing is not performed. If a preallocated target data set exists with the new name as chosen by the rename criteria, then the restore fails even if the REPLACE keyword was specified. If you want to replace a preallocated target with the new name, specify the REPLACEUNCONDITIONAL keyword. If a source data set name does not match the rename criteria, and a preallocated target data set with the source name exists, the preallocated target data set is replaced.

pfx: Specifies the prefix to be used to replace the first-level qualifier of the data set name. It is optional, but if specified, must be the first parameter in the list of subkeywords. The prefix is used only if the (on,nn) parameters are not specified or the old name filters do not match the data set name.
on: Specifies the old name to be used as filtering criteria for matching data set names on the target volume.
nn: Specifies the new name to be used to derive the new data set name if the data set name selected by the corresponding old name filtering criteria matches the name of a data set that already exists on the target volume.

If none of the old name filters match the data set name and the prefix is specified, the prefix is used to derive the new name. If old name filters do not match and the prefix is not specified, the data set is not renamed. If the old name filter matches and there is an error in the new name filter, the data set is not renamed.

The syntax for the prefix is as follows:

Single-level, fully qualified, unquoted DSNAME.
8 characters or less.
The first character must be alphabetic or national.
The remaining characters can be alphanumeric or national.

The syntax for the old name filter is exactly like that of the INCLUDE filter, and their rules match.

Examples of valid syntax for the new name filter are:

**: Restore the data set with the old name. This provides a powerful tool whereby some data sets can be restored with the old name and others can be restored with the new name.
*: If DSNAME has one level, then restore with old name.
A.**: First level of DSNAME replaced by A.
A.B.**: First two levels of DSNAME replaced by “A.B”.
*.A.**: Second level of DSNAME replaced by A.
**.BCD: Last level of DSNAME replaced by BCD.
DATE.**.LIST: First and last levels are replaced by DATE and LIST.
Q.*: If DSNAME has two levels, replace the first by Q.
Q.*.B: If DSNAME has three levels, replace the first and last by Q and B.
*.*.SYSLIST: If DSNAME has three levels, replace the last by SYSLIST.
ABC.DEF: No asterisk in substring; replace the entire name with “ABC.DEF”.

Examples of invalid syntax for the new name filter are:

**.DATA.**: Invalid (level to be replaced is ambiguous).
*SYS*: Invalid (a qualifier is not completely replaced).
SYS*: Invalid (a qualifier is not completely replaced).
*SYS: Invalid (a qualifier is not completely replaced).
SYS*TEM: Invalid (a qualifier is not completely replaced).
SYS.DAT%: Invalid (a qualifier is not completely replaced).
Restriction: The use of the wildcard character (%) is not supported for the new name filter of the RENAME, RENAMEU, or RENUNC keywords for the COPY or RESTORE operations.

You cannot change the number of qualifiers unless you use fully-qualified names, for example, RENUNC((A.B.C,A.B.C.D)).

If the new name filter has errors, the data set is not restored. The new name that is derived is truncated to fit 44 characters. If it ends with a period, that period is also truncated.

If the new name is not fully qualified, then it must contain the same number of qualifiers as the old name. For example, given the old name filter DATE.** and the new name filter DATE.*.*.LIST, DATE.MARCH.TODAY.OLDLIST would be renamed, but DATE.MARCH.OLDLIST would not.

If two or more rules match the old data set name, the resulting new name is the first match.

GDG relative generation filtering cannot be used for old or new names.

For more information about the use of the RENAME keyword, see Special considerations for RESTORE.

For more information about filtering, see Filtering by data set names.

INCLUDE.