RENAME

This command is required. The RENAME step renames and catalogs the data sets from the COPY step onto target volumes. RENAME-MASKS are processed in order. The first occurrence of the source data set name is the one that is used for the target data set name.

RENAME command syntax

RENAME
Required keywords:
{JOURNAL-DSN (data set name) | JOURNAL-DDN(ddname)}
RENAME-MASKS (mask pairs	)
RENAME-MASKS-DDN (ddname)
Optional Keywords:
DATACLAS (data class | SOURCE) | 
DATACLAS-PAIRS( 
  Sourcedataclas1, Targetdataclas1,  
  Sourcedataclas2, Targetdataclas2, …
DEFAULT_IF_NO_MATCH,
  Targetdataclasd | SOURCE )
DRIVEACS 
EXCLUDE-SRCNAME (RC (0 | NOTRENAMED-RC) )
EXCLUDE-SRCNAME-MASKS(masks) | EXCLUDE-SRCNAME-MASKS-DDN(ddname)  
GDG-ALL-MIGRATED(SKIP) | GDG-ALL-MIGRATED(RETAIN, RC(0 | 4))
GDG-EMPTY(SKIP) | GDG-EMPTY(RETAIN, RC(0 | 4))
GDG-MIGRATED(ERROR) | GDG-MIGRATED(RETAIN, RC(0 | 4))
GDG-TAPE(ERROR) | GDG-TAPE(RETAIN, RC(0 | 4))
ISSUE-VCLOSE(NO) | ISSUE-VCLOSE(YES | BEFORE | AFTER [ , LOCAL | SYSPLEX])  
MAX-TASKS(nnn | 1)
MGMTCLAS( mgmt_class | SOURCE ) | 
MGMTCLAS-PAIRS( 
  Sourcemgmtclas1, Targetmgmtclas1,  
  Sourcemgmtclas2, Targetmgmtclas2, …   
  DEFAULT_IF_NO_MATCH,
  Targetmgmtclasd | SOURCE) 
MISSINGUCAT(DELETE | KEEP [ , RC(0 | 4 | 8)])
NOTRENAMED(DELETE | KEEP [ , RC( 0 | 4 | 8)])
ORPHANCATENTRY(DELETE | KEEP [,RC(0 | 4 | 8)])
RECATALOG(Y | N)	
RENAME-AUDIT-LOG(N | SMF(nnn))
RENAME-ERROR(ABORT) | RENAME-ERROR(CONTINUE, RC(0 | 4 | 8)) 
RENAME-LIST(Y | N)
RERUN
SAFE | SPEED
SIMULATE
STORCLAS( stor_class | SOURCE ) |
STORCLAS-PAIRS( 
  Sourcestorclas1, Targetstorclas1, 
  Sourcestorclas2, Targetstorclas2, … 
  DEFAULT_IF_NO_MATCH,
  Targetstorclasd | SOURCE)  
TEMPDSN(DELETE | KEEP [ , RC (0 | 4 | 8)])
UPDATE-IAM-ASSOCIATIONS (Y | N) 
VALIDATE-SMS-CLASSES ( Y | N ) 
VOLBKUP-DDN(ddname)

Rename considerations

  • The work data sets and output data sets created by the RENAME job step cannot reside on target volumes.
  • RENAME-MASKS are processed in order. The first occurrence of the source data set name is the one that is used for the target data set name.
  • Name lengths: Whether changing a qualifier to a longer new name qualifier, or applying the + feature to add qualifiers, ensure that new names do not exceed 44 characters. Ensure that GDG base names do not exceed 35 characters.
  • Catalog aliases and new names: Catalog aliases must be set up to match names that are results of renaming.
  • Rename collisions: Be sure rename masks cannot cause two or more old names to rename to the same new name.
  • If all data sets on all volumes that are copied should be renamed, use the NOTRENAMED option with a return code of 8, assuming that the application that uses the target volumes requires less than an 8 return code from RENAME.
  • If non-VSAM data set aliases are used, ensure that if a rename mask matches a data set, the same mask, or other masks, match all aliases that are defined for the data set.
  • An ICF catalog can be renamed but it cannot be used as an ICF catalog.

Oldname syntax

Use the old name filter mask to select the data sets to apply the RENAME new name mask. The following table provides a list of the allowable filter characters and a description of each character.
Table 1. Filter characters allowed for old name filter masks:
Character Description
* A single asterisk represents exactly one DSN qualifier of any value. For example: *. or .*. or .* . * combined with valid DSN characters or % means 0 to nn characters of any value.
** A double asterisk represents 0 to nn DSN qualifiers of any value. For example: **. or .**. or .** ** cannot appear with any other characters within a qualifier. Three or more adjacent * are not allowed within a qualifier. ** can be used more than once in an 'old name' mask. Example: **.abcd.** or abc.**.defg.**
% A percent sign represents one non-blank character.
! An exclamation point represents one national character. @ # $
< A less-than sign represents one non-numeric character, national symbols included.
> A greater-than sign represents one numeric character.
For example, Filter = **.PAYROLL*.%%%%%23*.DATA would match DSN = TLQ050.PAYROLL.CYCLE23.DATA

Newname syntax

Use the new name mask to rename the data sets selected by the old name filter mask. The following table provides a list of the allowable filter characters and a description of each character.
Table 2. Filter characters allowed for new name filter masks:
Character Description
* A single asterisk represents exactly one DSN qualifier. * cannot be used for a partial qualifier in a new name mask. Example: aaa.*bb.** is not valid.
** A double asterisk represents 0 to nn DSN qualifiers. ** cannot appear with any other characters within a qualifier. Three or more adjacent asterisks are not allowed within a qualifier. ** can only be used only once in a 'new name' mask. Example: **.abcd.** is not valid.
% A percent sign represents one non-blank character.
! An exclamation point represents one national character. @ # $
+cccccc A plus sign followed by 1 to 8 characters inserts those characters as a new qualifier
- A minus sign removes the qualifier from the new name.
For example: Original DSN or mask:GCLI.LAB9.DEMO1.SDS.ORIG, renamed to the following DSN or mask: GCLI.+TEST.XX%%.-.** New Name: GCLI.TEST.XXB9.SDS.ORIG

RENAME command & keyword definitions

RENAME
Renames and catalogs data sets on target volumes.
  • Required: Yes.
  • Restrictions: None.
JOURNAL-DSN (data set name)
or JOURNAL-DDN (ddname)
This parameter supplies either a data set name of the IMS Cloning Tool journal file or a DD name assumed via the JCL to point at a journal data set.
Note: The journal data set for the RENAME step must be the same data set specified for the COPY step.

If multiple IMS Cloning Tool setups are used for different volume groups, DO NOT use the same journal data set. Each IMS Cloning Tool application requires a different journal data set.

The journal is used to pass information between IMS Cloning Tool steps (for example, from the COPY step to the RENAME step). Therefore, as noted in the JCL comments, it must be cataloged in the COPY step while first created and referenced as OLD in subsequent steps. Do not delete the data set in the last step in case restarts or reruns require journal information. Instead, delete and replace the data set at the fresh start of a COPY.

  • Default: None
  • Required: Yes
  • Restrictions: None
RENAME-MASKS (mask pairs)
RENAME-MASKS are specified in old-name and new-name pairs. RENAME-MASKS are processed in order. The first occurrence of the source data set name is used for the target data set name.
  • Default: None
  • Required: Yes
  • Restrictions: Syntax.
RENAME-MASKS-DDN (ddname) 

This parameter specifies a DD name that points to a file that contains rename mask pairs. The pairs are the same format as in the RENAME-MASKS keyword. RENAME-MASKS-DDN must have an LRECL of 80 and must not contain sequence numbers in columns 73 - 80. 

  • Default: None
  • Required: Yes
  • Restrictions: Mutually exclusive with RENAME-MASKS. 
  • Short form: RM-DDN 
DATACLAS (data class | SOURCE)
or DATACLAS-PAIRS (Sourcedataclas1, Targetdataclas1, Sourcedataclas2, Targetdataclas2, … DEFAULT_IF_NO_MATCH, Targetdataclasd | SOURCE )
DATACLAS
Specifies the SMS DATACLAS to be used for all renamed data sets on SMS managed volumes if the value is in quotation marks, or if it is copied from the corresponding source volume data set if SOURCE is specified. The default is SOURCE.
DATACLAS-PAIRS
Specifies the source and target pairs for dataclas. If a data set has the specified source data class, the target data set uses the paired target data class.
DEFAULT_IF_NO_MATCH
Indicates a data class to be assigned to a target data set for which the source data class was not matched by another DATACLAS-PAIR entry.
SOURCE
Indicates such data sets should be assigned the data class that is used by the source data set. If you want to use an SMS data class, SOURCE, enter SOURCE in quotation marks.
  • Default: For DATACLAS, the default is SOURCE.
  • Required: No
  • Restrictions: DATACLAS and DATACLAS-PAIRS are mutually exclusive with DRIVEACS.
  • Short forms: DC, or DCP.
DRIVEACS
This keyword specifies that SMS class information for renamed data sets is derived by 'driving' ACS routines. Variables that are supplied to ACS include: DSN, STORCLAS, DATACLAS, MGMTCLAS, ACSENVIR (BATCH), XMODE (RENAME), JOB_ACCT, STEP_ACCT, USERID, GROUP, APPLIC, SYSNAME, SYSPLEX, JOBNAME, PGM, and NAME.

Using the DRIVEACS parameter can slow down the RENAME performance.

  • Default: None
  • Required: No
  • Restrictions: DRIVEACS is mutually exclusive with DATACLAS, DATACLAS-PAIRS, MGMTCLAS, MGMTCLAS-PAIRS, STORCLAS, and STORCLAS-PAIRS.
EXCLUDE-SRCNAME (RC (0 | NOTRENAMED-RC))
This parameter specifies the return code to be used for data sets that match entries in the EXCLUDE-SRCNAME-MASKS keyword.

0 specifies that a return code of zero is returned for data sets that match entries in the EXCLUDE-SRCNAME-MASKS keyword.

NOTRENAMED-RC specifies that the return code specified in the NOTRENAMED keyword is used for data sets that match entries in the EXCLUDE-SRCNAME-MASKS keyword.

Using RC(0) addresses the situation in which known data sets on the volumes are not renamed and you do not want to use NOTRENAMED (RC(8)) to know whether unknown data sets are on the volumes.

  • Default: NOTRENAMED-RC
  • Required: No
  • Restrictions: Only used when EXCLUDE-SRCNAME-MASKS is specified. 
  • Short form: XS
EXCLUDE-SRCNAME-MASKS (masks)
This parameter supplies a list of source data set names to be excluded from renaming.

Data sets that are not renamed because of this keyword are treated as if no rename masks matched. The disposition of these not-renamed data sets is controlled by the NOTRENAMED keyword. The return code that is generated is specified by the EXCLUDE-SRCNAME keyword.

To exclude a GDG and its GDS entries, use two masks. For the first mask, use the GDG base name. For the second mask, used the GDG base name plus G>>>>v>>.

For example: GDG.BASE.NAME GDG.BASE.NAME.G>>>>V>>

Using two masks of this form is necessary because of the different ways that the data set names are stored in the volume VTOC and ICF catalog.

  • Default: None
  • Required: No
  • Restrictions: Mutually exclusive with EXCLUDE-SRCNAME-MASKS-DDN. See Oldname Syntax.
  • Short form: XSM
EXCLUDE-SRCNAME-MASKS-DDN(ddname)
This parameter specifies the DD name that points to a file that contains EXCLUDE SRCNAME MASKS. The entries are the same format as in the EXCLUDE-SRCNAME-MASKS keyword. EXCLUDE-SRCNAME-MASKS-DDN must have an LRECL of 80, and must not contain sequence numbers in columns 73 - 80.
  • Default: None
  • Required: No
  • Restrictions: Mutually exclusive with EXCLUDE-SRCNAME-MASKS. See Oldname Syntax.
  • Short form: XSM-DDN
GDG-ALL-MIGRATED(SKIP)
or GDG-ALL-MIGRATED (RETAIN, RC (0 | 4))
This command supports DFSMShsm, FDR, and CA-Disk. This option addresses the situation in which a GDG matches a RENAME mask and all the source generations were migrated.
The GDG entry can be skipped, or the GDS entries in the GDG base record can be RETAINED with a corresponding return code of 0 or 4. If not specified in the control statements, the defaults are obtained from the GCLINI member of SGCLPARM.
Note: If RETAIN is used, the migrated generations do not exist under the new name. Subsequent access to the generations fail whether one is accessed by name or by base name. This option is provided to retain relativity.
Note: To avoid destroying the relativity of active generations, IMS Cloning Tool does NOT allow removing selected generations. For data that is migrated and required on the target volumes, they must be recalled before the COPY.
  • Default: The default is SKIP. For RETAIN, the default is RC(4)
  • Required: No
  • Restrictions: RC is mutually exclusive with SKIP.
GDG-EMPTY(SKIP)
or GDG-EMPTY (RETAIN, RC (0 | 4))
This option addresses an empty base GDG that matches a RENAME mask.

The GDG entry can be skipped, or the new base entry can be added to the target user catalog. If not specified in the control statements, the defaults are obtained from the GCLINI member of SGCLPARM.

  • Default: The default is SKIP. For RETAIN, the default is RC(4)
  • Required: No
  • Restrictions: RC is mutually exclusive with SKIP.
GDG-MIGRATED(ERROR)
or GDG-MIGRATED (RETAIN, RC(0 | 4))
This option addresses the situation in which a GDG matches a rename mask and at least one generation is indeed found on a volume, yet one or more generations are migrated. The migrated generation can be treated as an ERROR. Or, the GDS entry in the GDG base record can be RETAINED with a corresponding return code of 0 or 4.
If not specified in the control statements, the defaults are obtained from the GCLINI member of SGCLPARM.
Note: If RETAINED, the migrated generation does not exist under the new name. Subsequent access to the generation fails whether it is accessed by name or by base name.

To avoid destroying the relativity of active generations, IMS Cloning Tool does not allow removing selected generations. Retaining non-existent migrated generations can be suitable for situations such as overstated GDG limits, where it is normal for older generations to be migrated and rarely accessed. It can also be suitable for log files, when only the current generation is kept, and older migrated generations are kept as a backup.

  • Default: The default is ERROR. For RETAIN, the default is RC(4)
  • Required: No
  • Restrictions: RC is mutually exclusive with ERROR.
GDG-TAPE(ERROR)
or GDG-TAPE (RETAIN, RC (0 | 4))
This option addresses the situation in which a GDG matches a rename mask and at least one generation is indeed found on a volume, yet one or more generations are on tape. The tape generation can be treated as an ERROR, or the GDS entry in the GDG base record can be RETAINED with a corresponding return code of 0 or 4.

If not specified in the control statements, the defaults are obtained from the GCLINI member of SGCLPARM.

Note: If RETAIN is specified, accessing a target tape GDS causes a S813 abend whether it is accessed by name or by base name.

To avoid destroying the relativity of active generations, IMS Cloning Tool does not allow removing selected generations. Retaining non-existent tape generations can be suitable for situations such as overstated GDG limits where older generations were created on tape.

  • Default: The default is ERROR. For RETAIN, the default is RC(4)
  • Required: No
  • Restrictions: RC is mutually exclusive with ERROR.
ISSUE-VCLOSE(NO)
or ISSUE-VCLOSE (YES | BEFORE | AFTER [, LOCAL | SYSPLEX ])
This keyword specifies whether a catalog modify command, F CATALOG,VCLOSE(targetvolser), is issued as part of the volume RENAME processing. The Catalog Address Space (CAS), caches VVDS information. The modify command requests that the VVDS information cached for the target volume being refreshed.

NO specifies that the modify command is NOT issued.

BEFORE specifies that the modify command is issued only before the VVDS is updated.

AFTER specifies that the modify command is issued only after the VVDS is updated.

YES specifies that the modify command is issued both before the VVDS is updated and after the VVDS is updated.

If not specified in the control statements, the defaults are obtained from the GCLINI member of SGCLPARM.

LOCAL – the catalog modify command, F CATALOG,VCLOSE(targetvolser), is issued only on the system that RENAME is running on.

SYSPLEX – the catalog modify command, F CATALOG,VCLOSE(targetvolser), is issued on the local system, and the modify command is routed to all the other systems in the sysplex, via an MVS ROUTE *OTHER command, after the VVDS is updated.

  • Default: YES, LOCAL
  • Required: No
  • Restrictions: LOCAL and SYSPLEX are mutually exclusive with NO.
MAX-TASKS (nnn | 1)
This keyword specifies the maximum subtasks that are used for volume processing in the RENAME step. Increasing the number of subtasks can greatly reduce the volume processing time. Provide a reasonably large region size and increase the number of subtasks until a point of no gain is realized. Because contention issues can contribute to the point of no gain varies by installation, experiment with this parameter to determine the optimum setting. Although the RENAME step can be rerun, because volume VTOCs, VTOC indexes, and VVDSs are restored when RERUN is specified, comparative times are distorted. Hence, while experimenting, run the process from the COPY step. This exercise can also be a good time to experiment with the COPY COPYCMDLIMIT option.

Another factor to consider is the cataloging time. The cataloging is performed by a subtask of RENAME that runs in parallel with the volume processing subtasks. If the number of data sets involved is high compared to the number of volumes, because the cataloging subtask can take longer than all volume processing subtasks, increasing the volume processing MAX-TASKS can have no effect on the complete run time of RENAME. The time the cataloging process ends, relative to the end time of the entire step, can be found in the output.

The maximum value is 255.

  • Default: 1
  • Required: No
  • Restrictions: None.
MGMTCLAS( mgmt_class | SOURCE )
or MGMTCLAS-PAIRS ( Sourcemgmtclas1, Targetmgmtclas1, Sourcemgmtclas2, Targetmgmtclas2, … DEFAULT_IF_NO_MATCH, Targetmgmtclasd | SOURCE )
MGMTCLAS
Specifies the SMS management class to be assigned to the renamed data sets.
mgmt_class
Indicates that the specified SMS management class is to be used for all renamed data sets on SMS managed volumes.
SOURCE
Indicates that the SMS management class will be copied from the corresponding source volume data set. This is the default.
MGMTCLAS-PAIRS
Specifies source and target pairs for the SMS management class.
Sourcemgmtclas1, Targetmgmtclas1, ...
If a data set has the specified source management class (Sourcemgmtclasn), the target data set uses the paired target management class (Targetmgmtclasn).
DEFAULT_IF_NO_MATCH
Indicates, in the subsequent parameter, which management class is to be assigned to a target data set whose source management class does not match any MGMTCLAS-PAIRS entries.
Targetmgmtclasd
Indicates that such data sets should be assigned the specified target management class.
SOURCE
Indicates such data sets should be assigned the management class that is used by the source data set. This is the default.
  • Default: The default for MGMTCLAS is SOURCE. The default for DEFAULT_IF_NO_MATCH is SOURCE.
  • Required: No
  • Restrictions: MGMTCLAS, MGMTCLAS-PAIRS, and DRIVEACS are mutually exclusive.
  • Short forms: MC (for MGMTCLAS) or MCP (for MGMTCLAS-PAIRS).
MISSINGUCAT (DELETE | KEEP [, RC (0 | 4 | 8) ])
This keyword specifies the disposition and return code to be generated for data sets found on a volume, where the data set name matches a rename mask, but the catalog back-pointer is not one of the 'source' catalogs that are specified in the corresponding COPY command. If not otherwise specified in the control statements, the default disposition and return code are obtained from this token in the GCLINI member of the SGCLPARM library.

Only data sets with VVDS records have a catalog back-pointer. A return code of 8 is suggested because MISSINGUCAT errors are likely because of the omission of a catalog name in the COPY step.

Catalog back-pointers could be in error from the start. To avoid continual review of pre-existing catalog back-pointer errors when using a return code of 8, it is suggested to run an IDCAMS DIAGNOSE function to diagnose and correct these errors. Correcting pre-existing catalog back-pointer errors help ensure that when a MISSINGUCAT error is detected that a user catalog was omitted in the COPY step.

  • Default: KEEP, RC(4)
  • Required: No
  • Restrictions: None.
NOTRENAMED (DELETE | KEEP [, RC (0 | 4 | 8 )])
This keyword specifies the disposition of data sets that do not match a rename mask, and the return code to be generated if at least one occurrence is detected. If not otherwise specified in the control statements, the default disposition and return code are obtained from this token in the GCLINI member of the SGCLPARM library.

If you require that rename masks match all data sets on all volumes, and if they do not, you want the entire process to fail, specify a return code of 8 and the corresponding conditional use of the target volumes set for execution only if the return code is less than 8. If the RENAME and or COPY step will be rerun, specify KEEP as the disposition.

If you want the process to fail when the target volumes contain data sets not needed by the application that is accessing the target volumes (without renaming these non-application data sets), specify a return code of 8. Additionally, specify EXCLUDE-SRCNAME(RC(0)) and EXCLUDE-SRCNAME-MASKS with entries that identify the expected non-application data sets. If all of the data sets on the volumes are renamed, or if they match an entry in EXCLUDE-SRCNAME-MASKS, the return code is 0. If data sets on the volume are not renamed, and they do not match an entry in EXCLUDE-SRCNAME-MASKS, the return code is 8 and the process fails. Because the data sets that match an entry in EXCLUDE-SRCNAME-MASKS are not renamed or cataloged, you should specify the DELETE option (especially for SMS-managed volumes). Specifying DELETE frees up space if allocations occur on target volumes.

If volumes contain data sets that are not needed by the application to access target volumes, and rename masks may not match all data sets, specify a return code of 0 or 4. Because not-renamed data sets are not cataloged, especially for SMS-managed volumes, you should specify the DELETE option. This also frees up the space if allocations can occur on target volumes.

If not all of the data sets are renamed, and an acceptable return code (0 or 4) is set, the list of not-renamed data sets must be reviewed for assurance that needed data sets are indeed renamed. Obviously, it is best if the application involved 'owns' the volumes and hence all data sets should be renamed. In a compromise situation, where the volumes are used by other applications, if feasible, the advantage of renaming data sets that are not required, is that the NOTRENAMED return code can be set to 8 to avoid reviewing the list of not-renamed data sets each cycle.

If you use effective naming conventions, a single, or few rename masks match all required data sets. If, for instance, all data sets belonging to the application match the mask A1.**, it is safe to ignore data sets that do not match the mask.

  • Default: KEEP, RC(8)
  • Required: No
  • Restrictions: None.
ORPHANCATENTRY (DELETE | KEEP [, RC(0 | 4 | 8 )])
This keyword specifies the disposition and return code to be generated for data sets that are found in a catalog but one or more catalog volume cells are not in the list of volumes copied. If not otherwise specified in the control statements, the default disposition and return code are obtained from this token in the GCLINI member of the SGCLPARM library.
  • Default: KEEP, RC(8)
  • Required: No
  • Restrictions: None.
RECATALOG(Y | N)
This keyword specifies that IMS Cloning Tool can replace an existing catalog entry without considering it an error. If RECATALOG is not specified, and a target catalog entry for a renamed data set is found to exist, the process fails. If not specified in the control statements, the defaults are obtained from the GCLINI member of SGCLPARM.

Because an incorrect rename 'to' mask could accidentally replace a catalog entry for a data set not involved with the process, the setup should be established such that RECATALOG is not required. This setup can be achieved by utilizing a target catalog that is used only for target data sets. Because catalog entries for data sets used in each cycle of the process are 'orphaned' by the target volumes to be reused, at the beginning of the next cycle, delete and redefine the catalog, or use the IMS Cloning Tool BCSCLEAN command to delete catalog entries from the previous cycle.

If a target catalog is populated with entries not involved with the copy process, use the BCSCLEAN command sometime between the time target volume usage ends and before the next copy process starts. By eliminating catalog entries from the previous cycle, omitting the RECATALOG option should not result in errors – unless rename 'to' masks are wrong, in which case the replacement of a catalog entry should indeed be prevented.

  • Default: N
  • Required: No
  • Restrictions: None.
RENAME-AUDIT-LOG (N | SMF(nnn))
This keyword specifies whether an audit log of the data sets being renamed is to be created by RENAME volume processing.

SMF(nnn) specifies that the audit log is created and written to SMF with a record type of nnn. Valid values for nnn are 128 - 255 inclusive. SMF must be recording the specified record type. The layout of the records that are written can be found in member RENSMF of the IMS Cloning Tool SGCLJCL library.

  • Default: N
  • Required: No
  • Restrictions: None.
RENAME-ERROR(ABORT)
or RENAME-ERROR(CONTINUE, RC(0 | 4 | 8))
This option specifies how processing proceeds when a RENAME error is encountered.

ABORT terminates with an RC=8 after the first error to preserve integrity. ABORT is recommended.

CONTINUE continues processing after most errors and the RENAME command completes with the specified return code unless an error not handled by the CONTINUE logic is encountered.
Note: The use of CONTINUE can cause inconsistencies between the contents of the volumes and catalogs. Possible problems include:
  • data sets could be cataloged but are not renamed on disk
  • data sets could be renamed on disk but are not cataloged
  • data sets that are not renamed on disk cannot be deleted from disk
  • GDG base and GDS entries will not exist in the catalog when there is a missing GDS
  • a catalog entry may not point at the correct volume
  • a catalog entry may be invalid
  • leave uncataloged data sets on SMS managed volumes.

If this keyword is specified, IMS Cloning Tool cannot guarantee integrity and the specific results are not fixed by IMS Cloning Tool.

If not specified in the control statements, the defaults are obtained from the GCLINI member of SGCLPARM.

  • Default: ABORT. For CONTINUE, the default is RC(8)
  • Required: No
  • Restrictions: RC is mutually exclusive with ABORT.
RENAME-LIST(Y | N)
This option specifies whether a list of the renamed data sets is to be produced by RENAME volume processing.
  • Default: N if SIMULATE is not specified. Y if SIMULATE is specified.
  • Required: No
  • Restrictions: None.
RERUN
This option specifies that the RENAME step is being run a second time with the same target volumes that resulted from the COPY step. Rerun of the RENAME step only is not possible unless SAFE was specified in first execution.

SAFE causes a backup during the RENAME step of the portions of volumes that are changed during the volume processing – VTOC, VTOCIX, and VVDS. This backup data is used on a rerun to restore volumes that were changed to the state they were in following the COPY step.

Certain errors, such as incorrect rename masks, where the list of volumes that were copied and the catalogs that were backed up are correct, can be corrected by rerunning the RENAME step.

Examine the problem to determine if a rerun of the RENAME step can resolve the problem or if the COPY step must be rerun. Errors resulting from an omitted volume or an omitted catalog in the COPY step requires a rerun of the COPY step.

The BCSRECS and VOLBKUP data sets must not be deleted by the JCL running the RENAME RERUN. The contents of the BCSRECS and VOLBKUP must be from the prior run of RENAME with either the SAFE or RERUN keywords. If the BCSRECS or VOLBKUP data sets are deleted, you need to run the COPY step again.

  • Default: None.
  • Required: No
  • Restrictions: RERUN is mutually exclusive with SAFE and SPEED.
SAFE | SPEED
SAFE allows a rerun of the RENAME command by backing up critical volume structures that are changed during the volume processing – the VTOC, VTOCIX, and VVDS. This backup data is used on a rerun to restore volumes that are changed to the state they were in following the COPY step. This adds slight execution time for RENAME to capture the portions of target volumes that are modified by RENAME.

Incorrect rename masks cause a necessary rerun the RENAME step. If multiple and complicated masks are required, this option is recommended. Additionally, the renaming is affected by whether the data set naming conventions that are used by the application are static or subject to frequently change – inferring that rename masks must be watched.

SAFE requires the VOLBKUP parameter. Note the JCL comments that warn about making sure the VOLBKUP data set is not deleted before a rerun of RENAME. If the VOLBKUP data set is lost, you need to run the COPY step again, if the opportunity for correct point-in-time images has not been lost.

If source volume access is not resumed until the entire process is complete (implying that the same point-in-time images can be recopied), the time to rerun the COPY step can be insignificant compared to adding overhead with the SAFE option for every cycle.

SPEED is the opposite of SAFE. The RERUN option for the RENAME step is rejected if attempted. Error correction requires the COPY and RENAME step to be run again.

  • Default: SPEED.
  • Required: No
  • Restrictions: SAFE is mutually exclusive with SPEED and RERUN. SPEED is mutually exclusive with SAFE and RERUN.
SIMULATE
This option specifies that only non-destructive RENAME activities are to be performed. RENAME SIMULATE must be used with a COPY as the volumes and catalogs are specified only in the COPY step and are passed via the journal to the RENAME step. The COPY execution can be with or without SIMULATE.

Scenario 1 – a real COPY (without SIMULATE) followed by a RENAME SIMULATE uses only the target volumes.

Scenario 2 – a COPY SIMULATE followed by a RENAME SIMULATE uses only the source volumes because no target volumes exist yet.

If COPY DATAMOVER(PGM(NONE) was used with SIMULATE, it can be followed by a RENAME SIMULATE.

SIMULATE performs the masking comparisons to both catalog and volume records. Errors can be discovered such as not all data sets renamed, incomplete renaming of VSAM sphere associations and components, multivolume data sets not wholly contained in the volume list, GDG generations that stray outside of the volume list, catalog entries that match a mask but one or volumes were not copied.

Because omitting one or more catalogs or volumes in the COPY step is not detected until the RENAME step, it is recommended to use SIMULATE whenever significant changes are made to the involved applications. This is true especially when resumption of source volume access is triggered by completion of the COPY step – that is, the opportunity for recapturing point-in-time images has been lost.

  • Default: None.
  • Required: No.
  • Restrictions: None.
  • Short form: SIM
STORCLAS( stor_class | SOURCE )
or STORCLAS-PAIRS (Sourcestorclas1, Targetstorclas1, Sourcestorclas2, Targetstorclas2, … DEFAULT_IF_NO_MATCH, Targetstorclasd | SOURCE)
STORCLAS
Specifies the SMS storage class to be assigned to the renamed data sets.
stor_class
Indicates that the specified SMS storage class is to be used for all renamed data sets on SMS managed volumes.
SOURCE
Indicates that the SMS storage class will be copied from the corresponding source volume data set. This is the default.
STORCLAS-PAIRS
Specifies source and target pairs for the storage class.
Sourcestorclas1, Targetstorclas1, ...
If a data set has the specified source storage class (Sourcestorclasn), the target data set uses the paired target storage class (Targetstorclasn).
DEFAULT_IF_NO_MATCH
Indicates, in the subsequent parameter, which storage class is to be assigned to a target data set whose source storage class does not match any STORCLAS-PAIRS entries.
Targetstorclasd
Indicates that such data sets should be assigned the specified target storage class.
SOURCE
Indicates such data sets should be assigned the storage class that is used by the source data set. This is the default.
  • Default: The default for STORCLAS is SOURCE. The default for DEFAULT_IF_NO_MATCH is SOURCE.
  • Required: No.
  • Restrictions: STORCLAS, STORCLAS-PAIRS, and DRIVEACS are mutually exclusive.
  • Short forms: SC (for STORCLAS) or SCP (for STORCLAS-PAIRS)
TEMPDSN (DELETE | KEEP [,RC(0 | 4 | 8 )])
This option specifies the disposition of temporary data sets and the return code to be generated if at least one occurrence is discovered. If not otherwise specified in the control statements, the default disposition and return code are obtained from this token in the GCLINI member of THE SGCLPARM LIBRARY.
  • Default: DELETE, RC(4)
  • Required: No.
  • Restrictions: None.
UPDATE-IAM-ASSOCIATIONS (Y | N) 

This option specifies whether IAM data set associations are to be updated as part of RENAME processing. IAM must be active on the system for the updates to happen.  This option addresses the situation in which IAM data sets are being cloned that include AIXes and PATHs, and it is desired to update the associations to correspond with the new data set names. The association information for IAM data sets is determined and updated by internally using IDCAMS LISTCAT and IDCAMS DEFINE RECATALOG commands.  When RERUN is used, it is possible to get missing component errors when rename mask entries that cover IAM data sets were changed. This is because the IAM association data not being in the ICF catalog, VTOC, VTOCIX, or VVDS, so IMS Cloning Tool is unable to properly determine the changed IAM associations. When SIMULATE is used, it is not possible for IMS Cloning Tool to determine the IAM associations and verify that all the associated cloned IAM data sets. 

  • Default: N
  • Required: No
  • Restrictions: None
  • Short form: UIA 
VALIDATE-SMS-CLASSES ( Y | N )
Specifies whether the SMS class names specified in the DATACLAS, DATACLAS-PAIRS, MGMTCLAS, MGMTCLAS-PAIRS, STORCLAS, and STORCLAS-PAIRS keywords will be validated as being defined to SMS (Y) or not (N).

This option addresses the situation where the target SMS class names are not defined on the system where RENAME is run.

  • Default: Y
  • Required: No.
  • Restrictions: None.
VOLBKUP-DDN (ddname)
This option specifies the DD name for the backup data set to be used for backing up target volume VTOCs, VTOCIXs, and VVDSs, to be used in the event of a rerun of the RENAME step. SAFE is required with this parameter.
  • Default: None
  • Required: No.
  • Restrictions: None.
Note: Variables that are supplied to ACS do not include data set attributes. IMS Cloning Tool catalogs target data sets concurrently with changing target volumes, as opposed to cataloging data sets only after volumes are modified. This method greatly improves the performance of RENAME, at the expense of the cataloging task not being aware of data set attributes that are normally supplied when driving ACS.

If SMS treatment of target volume data sets is special, specific SMS classes can be supplied with the DATACLAS, MGMTCLAS, and STORCLAS keywords, or you can also set up a construct that triggers the IMS Cloning Tool job name.

RENAME Step JCL Example

For completeness and to illustrate where JCL parameters and IMS Cloning Tool control statements must match, the following JCL includes sample IMS Cloning Tool control statements.

The RENAME step JCL is shown in the following example. The numbers that precede the JCL correspond to the notes that follow the sample JCL. 

   //??????? JOB ,'GCL RENAME',CLASS=A,MSGCLASS=X
   //S0      EXEC PGM=IDCAMS                                             
   //SYSPRINT DD  SYSOUT=*                                               
   //SYSIN    DD  *                                                      
1    DEL GCL.WRK.VOLDUMP                                             
1    DEL GCL.WRK.BCSRECS                                             
2  //S1      EXEC PGM=GCL00010,REGION=8M                                 
3  //STEPLIB  DD  DSN=HLQ?.SGCLLOAD,DISP=SHR                              
4  //GCLINI   DD  DSN=HLQ?.SGCLPARM(GCLINI),DISP=SHR        
5  //SORTMSG  DD  SYSOUT=*
6  //SORTWK01 DD  UNIT=SYSALLDA,SPACE=(CYL,(10,10))
   //SORTWK02 DD  UNIT=SYSALLDA,SPACE=(CYL,(10,10))
   //SORTWK03 DD  UNIT=SYSALLDA,SPACE=(CYL,(10,10))
   //SORTWK04 DD  UNIT=SYSALLDA,SPACE=(CYL,(10,10))
   //SORTWK05 DD  UNIT=SYSALLDA,SPACE=(CYL,(10,10))
   //SORTWK06 DD  UNIT=SYSALLDA,SPACE=(CYL,(10,10))
7  //DRSTATS  DD  SYSOUT=*                                               
8  //GCLPRINT DD  SYSOUT=*                                               
   //SYSUDUMP DD  SYSOUT=*                                               
9  //JOURNAL  DD  DSN=GCL.JRNL,DISP=OLD
10 //BCSRECS  DD  DSN=GCL.WRK.BCSRECS,UNIT-SYSALLDA,DISP=(,CATLG),
   //             SPACE=(CYL,(10,10))                             
11 //VOLDUMP  DD  DSN=GCL.WRK.VOLDUMP,UNIT=SYSALLDA,DISP=(,CATLG),      
   //             SPACE=(CYL,(10,10))                                   
   //GCLIN    DD  *                                           
     RENAME                                              -               
11       SAFE                                            -               
11       VOLBKUP-DDN(VOLDUMP)                            -               
         MAX-TASKS(5)                                    -               
9        JOURNAL-DDN(JOURNAL)                            -               
         NOTRENAMED(DELETE,RC(4))                        -               
         MISSINGUCAT(DELETE,RC(8))                       -               
         ORPHANCATENTRY(KEEP,RC(8))                      -               
         RECATALOG(N)                                    -               
         DATACLAS(TGTDATA)                               -
         MGMTCLAS(TGTMGMT)                               -
         STORCLAS-PAIRS(SRCSTOR1,TGTSTOR1                - 
                        SRCSTOR2,TGTSTOR2                -
                        DEFAULT_IF_NO_MATCH,TGTSTORX)    -              
         RENAME-MASKS(                                   -               
            ASRC.** ATGT.**                              -
            BSRC.** BTGT.**                              -
            PROD.** TEST.**                              -
                     )                                                   
   //*
  1. Deletion of volume memory dumps and BCSRECS in anticipation of allocating new for each execution. Because these data sets recover target volume information and remove BCS entries during a rerun of the RENAME step, DO NOT set up the rerun JCL to delete these data sets.
  2. Execution of IMS Cloning Tool main program.
  3. The IMS Cloning Tool SGCLLOAD library must be authorized.
  4. DD for GCLINI member of the HLQ?.SGCLPARM library. This member provides variables to the IMS Cloning Tool programs and contains the product security license codes.
  5. DD for sort messages.
  6. DDs for sort work data sets. Sort data sets are provided if needed by the sort product used.
  7. DD for DRSTATS, SAFE option memory dump and Restore output.
  8. DD for GCLPRINT, mainline RENAME output.
  9. Journal data set that is used by IMS Cloning Tool commands. This VSAM data set is used to pass information between IMS Cloning Tool steps, and to log information that is derived from the step executions. The journal file is allocated and cataloged in the COPY step, and used as input and output by the RENAME step. The specified data set name must match the data set allocated in the COPY step. If multiple IMS Cloning Tool processes are created for different applications, each must use a unique journal data set. In the sample JCL, the control statement JOURNAL-DDN(JOURNAL) specifies that a DD with the name JOURNAL is being used, rather than a data set name.
  10. DD for BCSRECS. The data set pointed at by this DD is used to store data set names that are used if RENAME is rerun, and for the BCSCLEAN command. Required regardless of whether rerunning is anticipated or BCSCLEAN is expected to be used. The data set specified in the RENAME step must match the name that is used in the corresponding BCSCLEAN step. However, if multiple IMS Cloning Tool processes are created for different applications, each must have a unique BCSRECS data set.
    Note: This file cannot be striped.
  11. VOLDUMP DD statement. This DD points to a data set used to back up information about target volumes, in case a rerun of the RENAME step is required. This data set is used only if the SAFE parameter is specified.

    The normal and abnormal disposition must be CATLG.

    In the sample JCL, the control statement VOLBKUP-DDN(VOLDUMP) specifies that a DD with the name VOLDUMP is being used rather that a data set name. If the number of volumes that are involved is high, and the VTOCs, VVDSs, and VTOC indexes are large, this data set may require a substantial amount of space.

    Note: The RENAME output also includes output for each volume that is processed with dynamically allocated DD names of VVOLSERX.