IBM Support

Updates to IMS Cloning Tool User's Guide (SC19-3757-02)

Product Documentation


Abstract

Updates to IMS Cloning Tool User's Guide (SC19-3757-02)

Content

The most recent updates appear at the top of the list.

Update 5
Date of change: June 2020
Change description: Documentation changes for APAR PH25830, which provides the IIUIN control statements of IMS Index Builder to rebuild non-recoverable indexes or to correct invalid REORG# in partition data set.
Topics: Changes apply to multiple topics.

============================

Topic: Reference: Database refresh commands > IMSDBREFRESH

DD definition has been added as follows:

IMSDBREFRESH command syntax

:

IMSDBREFRESH command & keyword definitions

:

Start of change

IMSDBREFRESH DD definition

GCLIIUIN

Optional DD that specifies the output data set where IMS Cloning Tool will put the control statements of IMS Index Builder for the target databases that have indexes to be rebuilt. Those control statements will be passed to the IMS Index Builder step for rebuilding target indexes before using the target databases. The specified data set should be LRECL=80, RECFM=FB and DSORG=PO. For each DBD, the control statements for each primary database are built into the specified PDS. 

When LOG-APPLY(Y) keyword is specified, IMS Cloning Tool applies log updates to the primary target database after copying the source database. When the primary target database has either a non-recoverable secondary index, or ILDS or Primary Index for a HALDB, IMS log records are not generated from these indexes, so they may be out of sync after IMS Cloning Tool applied log updates to the associated primary target database.

If this DD is omitted, IMS Cloning Tool will not build the IIUIN control statements. GCL34539W message will be printed for the target database or non-recoverable secondary indexes to be rebuilt. GCL34183W and GCL34179E messages will be printed and the indicated HALDB will not be copied when the REORG# in partition data set will be smaller than the REORG# in target RECON. 

Default: None

Required: No

Example: The following example shows the control statements of IMS Index Builder that is built in IMSDBREFRESH command. For detailed description about the generated control statements, see "Required control statements" in the IMS Index Builder User's Guide.           
  PROC BLD_PRIMARY,dbdname
  PROC BLD_ILDS,dbdname
  INPUT IBSCAN,DBRC=Y      

End of change

IMSDBREFRESH Step JCL Example

:

============================

Topic: Reference: IMS Cloning Tool Messages

The following messages have been added:

Start of change

GCL34030E DSN IS NOT PDS

Explanation: The specified data set is not a PDS.

User response: Specify the correct data set name that is a PDS data set.

End of change

---

Start of change

GCL34183W REORG#: nnnn IN SOURCE HALDB dbname PARTITION partname IS SMALLER THAN REROG#: mmmm IN TARGET RECON

Explanation: The REORG# in the target partition data set will become smaller than the REORG# in the target RECON if copying the source HALDB. The refreshing of the target HALDB stops.

User response: Specify the GCLIIUIN DD statement to continue the refreshing process.

End of change

---

Start of change

GCL34550W REORG#: nnnn IN TARGET HALDB dbname PARTITION partname IS SMALLER THAN REROG#: mmmm IN RECON

Explanation: The REORG# in the target partition data set is smaller than the REORG# in the target RECON after copying the source HALDB. Also, the target HALDB partition is inconsistent with the indirect data set (ILDS).

User response: IMS Index Builder must be processed with the IIUIN control statements explained in message GCL34560I before using the target HALDB. If GCL34560I message is not printed, you must resolve the inconsistency before you use the HALDB partition. To resolve the inconsistency, it is recommended that you rebuild the ILDS of the HALDB partition with the HALDB Index/ILDS rebuild utility (DFSPREC0) or a functionally equivalent utility. By using such a utility, you can correct inconsistencies in the partition data set, the RECON data sets, and the ILDS at once.

End of change

---

Start of change

GCL34560I IIUIN CONTROL STATEMENTS ARE BUILT FOR dbdname

Explanation: IMSDBREFRESH command builds the IIUIN control statements for the primary target database.

User response: IMS Index Builder must be processed with the IIUIN control statements to rebuild either a non-recoverable secondary index, ILDS or Primary Index explained either in GCL34539W or GCL34550W message before using the target database.

End of change


Update 4
Date of change: March 2020
Change description: Documentation changes for APAR PH21973.
Topics: Changes apply to multiple topics.

============================

Topic: Customizing IMS Cloning Tool > GCLINI configuration values > GCLINI keyword syntax and descriptions > :DB_COPY_OPTIONS section


The following new keyword has been added:

Start of change

COPY_IF_DIFFERENT_HALDB = N|Y

Optional keyword that indicates whether IMS Cloning Tool should redefine the target DBRC definitions of the target HALDB if the source and the target HALDBs have different definitions. The definitions that might be different are: the number of partitions, the partition ID, and the M-V data sets.

N

If 'N' is specified, the target HALDB will not be refreshed even if the source and the target HALDBs have different definitions.

Y

If 'Y' is specified, the target HALDB will be refreshed and redefined in the target DBRC so that it has the same definitions as the source HALDB. You must also specify the RENAME-MASKS keyword on the IMSDBREFRESH command to determine the new target data set names. 'Y' is applicable only if the DBRC-ACTION(REDEFINE) or DBRC-ACTION(REORG,HALDBREDEFINE) keyword is specified.

This value is used only if the COPY-IF-DIFFERENT-HALDB keyword is not specified on the IMSDBREFRESH command.

The default is N.

End of change

============================

Topic: Reference: Database refresh commands > IMSDBREFRESH

The following new keyword has been added to the IMSDBREFRESH command:

  AUTO-STOP-TARGET-DB(Y|N)

Start of changeCOPY-IF-DIFFERENT-HALDB(N|Y)End of change

  COPY-IF-NO-IMS-TARGET-DB(N|Y)

...

...

...

Start of change

COPY-IF-DIFFERENT-HALDB(N|Y)

Optional keyword that indicates whether IMS Cloning Tool should redefine the target DBRC definitions of the target HALDB if the source and the target HALDBs have different definitions. The definitions that might be different are: the number of partitions, the partition ID, and the M-V data sets.

N

If COPY-IF-DIFFERENT-HALDB(N) is specified, the target HALDB will not be refreshed even if the source and the target HALDBs have different definitions.

Y

If COPY-IF-DIFFERENT-HALDB(Y) is specified, the target HALDB will be refreshed and redefined in the target DBRC so that it has the same definitions as the source HALDB. You must also specify the RENAME-MASKS keyword to determine the new target data set names.

Default: N

Required: No

Restrictions:

  • If COPY-IF-DIFFERENT-HALDB(Y) is specified, RENAME-MASKS must also be specified.
  • COPY-IF-DIFFERENT-HALDB(Y) is used only if the DBRC-ACTION(REDEFINE) or DBRC-ACTION(REORG,HALDBREDEFINE) keyword is specified.
  • COPY-IF-DIFFERENT-HALDB(Y) is not allowed with the following keywords:
    • TGT-DBD
    • FUZZY-COPY(Y) and UNLOAD-FROM(SOURCE)
    • INDEXES(N) or INDEXES(P)
    • LOGICALLY-RELATED(N)
...
End of change
============================

Topic: Reference: IMS Cloning Tool Messages

The following messages have been added:

Start of change

GCL34971W The number of partitions in target HALDB xxxxxxxx is nnnn, which is different from source HALDB

Explanation: The source HALDB and the target HALDB have different numbers of partitions. The target HALDB will be redefined to have the same definitions as the source HALDB.
In the message text, nnnn is the number of partitions and xxxxxxxx is the name of the target HALDB.

User response: None.

---

GCL34974W The partition ID nn of target HALDB xxxxxxxx partition yyyyyyy is different from source partition

Explanation: The source HALDB and the target HALDB have different partition IDs. The target HALDB will be redefined to have the same definitions as the source HALDB.
In the message text, nn is the partition ID, xxxxxxxx is the target HALDB name, and yyyyyyy is the partition name.

User response: None.

---

GCL34975W Only ssssss HALDB xxxxxxxx partition yyyyyyy has the M-V data sets

Explanation: Either the target or the source HALDB partition does not have M-V data sets. The target HALDB will be redefined to have the same definitions as the source HALDB.
In the message text, ssssss is either 'source' or 'target', xxxxxxxx is the HALDB name, and yyyyyyy is the partition name.

User response: None.

---

GCL34088E COPY-IF-DIFFERENT-HALDB(Y) not allowed with xxxxx

Explanation: The COPY-IF-DIFFERENT-HALDB(Y) keyword is not allowed with the following keywords:

  • TGT-DBD
  • FUZZY-COPY(Y) and UNLOAD-FROM(SOURCE)
  • INDEXES(N) or INDEXES(P)
  • LOGICALLY-RELATED(N)

User response: If the target HALDB needs to be refreshed, specify the INDEXES(Y) and LOGICALLY-RELATED(Y) keywords.

End of change

Update 3
Date of change: October 2019
Change description: Documentation updates for APAR PH17323.

============================

Topic: Reference: IMS Cloning Tool Messages
 

The following messages have been added: GCL34075E, GCL34076E, and GCL34077I.
 

Start of changeGCL34075E IMSDBREFRESH: The following data sets were not processed

Explanation: This message is followed by a summary report that shows the database data sets that were not processed. Compatibility check of the source and target DBDs failed for the database data sets that are listed in the report.

User response: See the message listed under the Status column of the report, and check the reason of the error.

The following figure shows an example of the report:

GCL34075E 03:25:23 IMSDBREFRESH: The following data sets were not processed

Source                                                Target                                                           

Database Data set                                     Database Data set                                     Status     

-------- -------------------------------------------- -------- -------------------------------------------- -----------

DBHDO00  IMSFA2DB.DBHDO00.DBHDO00                                                                           GCL34179E



---

GCL34076E IMSDBREFRESH: The following data sets were not copied successfully

Explanation: This message is followed by a report that summarizes the status of each database data set whose associated database is in error.

This message is displayed in one of the following situations:

  •     The copy processing failed for the database data sets that are listed in the report.
  •     Invocation of the DFSMSdss COPY command or EMC SNAPI was skipped for the database data sets that are listed in the report.


The following figure shows an example of the report:

GCL34076E 03:25:23 IMSDBREFRESH: The following data sets were not copied successfully  

Source                                                Target                                                           

Database Data set                                     Database Data set                                     Status     

-------- -------------------------------------------- -------- -------------------------------------------- -----------

DBHDO02  IMSFA2DB.DBHDO02.DBHDO021                    DBHDO02  RSIMS.IFA9DB.DBHDO02.DBHDO021                COPIED     

         IMSFA2DB.DBHDO02.DBHDO022                             RSIMS.IFA9DB.DBHDO02.DBHDO022                COPY FAILED

DBHDV00  IMSFA2DB.DBHDV00.DBHDV001                    DBHDV00  RSIMS.IFA9DB.DBHDV00.DBHDV001                COPIED     

         IMSFA2DB.DBHDV00.DBHDV002                             RSIMS.IFA9DB.DBHDV00.DBHDV002                NOT COPIED

         IMSFA2DB.DBHDV00.DBHDV003                             RSIMS.IFA9DB.DBHDV00.DBHDV003                NOT COPIED

DBHDVS21 IMSFA2DB.DBHDVS21.DBHDVS21                   DBHDVS21 RSIMS.IFA9DB.DBHDVS21.DBHDVS21               NOT COPIED

DBHDVS22 IMSFA2DB.DBHDVS22.DBHDVS22                   DBHDVS22 RSIMS.IFA9DB.DBHDVS22.DBHDVS22               NOT COPIED

DBHDOS21 IMSFA2DB.DBHDOS21.DBHDOS21                   DBHDOS21 RSIMS.IFA9DB.DBHDOS21.DBHDOS21               NOT COPIED

DBHDOS22 IMSFA2DB.DBHDOS22.DBHDOS22                   DBHDOS22 RSIMS.IFA9DB.DBHDOS22.DBHDOS22               NOT COPIED

In the report, the Status column shows the status of each data set, as follows:

COPIED
This database data set was successfully copied, but one or more related data sets were not copied successfully.

NOT COPIED
The copy process was skipped for this database data set.

COPY FAILED
The copy process failed for this database data set.


User response: Check the ADRDSSU or EMC SNAPI messages for the cause of the 'COPY FAILED' status that is displayed under the Status column of the report. After 'COPY FAILED' is resolved and the job is rerun. the 'NOT COPIED' status should be resolved.
 

---

GCL34077I IMSDBREFRESH: The following data sets were copied successfully

Explanation: The database data sets that are listed in the report that follows this message were copied successfully.

The following figure shows an example of the report:

GCL34077I 03:25:23 IMSDBREFRESH: The following data sets were copied successfully

Source                                                Target                                                           

Database Data set                                     Database Data set                                     Status     

-------- -------------------------------------------- -------- -------------------------------------------- -----------

DBHDV02  IMSFA2DB.DBHDV02.DBHDV02                     DBHDV02  RSIMS.IFA9DB.DBHDV02.DBHDV02                 COPIED   

User response: None.

End of change


Update 2
Date of change: June 2019
Change description: Documentation updates for APAR PH12011.
Topics: Changes apply to multiple topics.

============================

Topic: Reference: IMS Cloning Tool Messages

The following messages have been added.

Start of changeGCLACH22E UNABLE TO COMMUNICATE WITH IMS SSID = ssid

Explanation: Connection with target IMS ssid failed when trying to apply updates to the target database.

User response: Make sure that the target IMS has been started correctly, specify an appropriate operand for the IMSPLEX keyword in the GCLIN DD statement, and rerun the job. If you cannot resolve the problem, contact IMS Software Support.

 

GCL34962W TARGET IMSPLEX NOT SPECIFIED, NOT ABLE TO DYNAMICALLY ADD TARGET DB DEFINITIONS

Explanation: You issued an IMSDBREFRESH command with COPY-IF-NO-IMS-TARGET-DB(Y) specified, and an attempt was made to add a database definition to the target IMS, but the IMSPLEX keyword was missing from the GCLIN DD statement.

User response: If the database needs to be defined to the target IMS, you must run the IMSDBREFRESH command with the IMSPLEX keyword defined in the GCLIN DD statement.

 

GCL34073E NON-RECOVERABLE DATABASE dbname CANNOT BE REFRESHED WITH LOG-APPLY(Y)

Explanation: An IMSDBREFRESH job with FUZZY-COPY(Y) and LOG-APPLY(Y) detected a nonrecoverable database. The job cannot process nonrecoverable databases unless the ALLOW-NONRECOV keyword is specified for the IMSDBREFRESH command.  

User response: If the nonrecoverable database needs to be refreshed, specify the ALLOW-NONRECOV(CONTINUE) keyword for the IMSDBREFRESH command; otherwise, specify ALLOW-NONRECOV(SKIP). Then, rerun the job.

 

GCL34074W NON-RECOVERABLE DATABASE dbname CANNOT BE REFRESHED WITH LOG-APPLY(Y)

Explanation: An IMSDBREFRESH job with FUZZY-COPY(Y) and LOG-APPLY(Y) detected a nonrecoverable database.  If ALLOW-NONRECOV(SKIP) is specified, the nonrecoverable database will be bypassed, and processing continues with other databases. If ALLOW-NONRECOV(CONTINUE) is specified, the nonrecoverable database will be refreshed without any updates applied to it.

User response: None. This message is informational.

 

GCL34079E NON-RECOVERABLE INDEX dbname CANNOT BE REFRESHED WITH LOG-APPLY(Y) WITHOUT PRIMARY DB

Explanation: An IMSDBREFRESH job with FUZZY-COPY(Y) and LOG-APPLY(Y) detected a nonrecoverable index, but the associated primary database was not found.

User response: If the primary database is a recoverable database, add it to the job because it also needs to be refreshed, and rerun the job. If the primary database is a nonrecoverable database, add it to the job, specify the ALLOW-NONRECOV(CONTINUE) keyword, and then rerun the job.

End of change

============================

Topic: Reference: Database refresh commands > IMSDBREFRESH

The following optional keywords have been added or changed.

IMSDBREFRESH command syntax

Optional keywords

Start of change

ALLOW-NONRECOV(ABORT | CONTINUE[,RC(nn)] | SKIP[,RC(nn)])

End of change

IMSDBREFRESH command & keyword definitions

Start of change

ALLOW-NONRECOV(ABORT | CONTINUE[,RC(nn)] | SKIP[,RC(nn)])        

Optional keyword that specifies whether the IMSDBREFRESH command should continue processing even if non-recoverable primary databases are detected when LOG-APPLY(Y) is specified on the IMSDBREFRESH command.

Valid values are:

  • ABORT - (the default) The IMSDBREFRESH command terminates with RC=8 and message GCL34073E.
  • CONTINUE - The IMSDBREFRESH command refreshes the non-recoverable primary databases and returns message GCL34074W and a return code of nn. Even if LOG-APPLY(Y) is specified, the IMSDBREFRESH command does not apply any logs to the target data sets of the non-recoverable primary databases after the data sets have been copied. The return code nn must be a numeric value 0 - 4095.
  • SKIP - The IMSDBREFRESH command skips refreshing the non-recoverable primary databases and returns message GCL34074W. It then continues to refresh the other databases and ends the job with a return code of nn. The return code nn must be a numeric value 0 - 4095.

  • Default: ABORT. For CONTINUE and SKIP, the default for RC(nn) is RC(4).
  • Required: No
  • Restriction: If ABORT is specified, RC is ignored. 
End of change

DBD(dbdname1 ,dbdname2, dbdname3, ...)  

Start of changeRequired keyword that specifies up to 3,200 database names to be refreshed from the source IMS subsystem to the target IMS subsystem. If the TGT-DBD parameter is omitted, then the target DBD name will be the same as the source DBD name. End of change

  • Default: None
  • Required: Yes
  • Restrictions: None

============================

Topic: Customizing IMS Cloning Tool > GCLINI configuration values > GCLINI keyword syntax and descriptions > :DB_COPY_OPTIONS section

The following keyword parameters have been added:

Start of change

ALLOW_NONRECOV=ABORT | CONTINUE | SKIP
This option specifies how the IMSDBREFRESH command processes a non-recoverable primary database. The value you specify is applicable only if the corresponding ALLOC-NONRECOV keyword is not specified on the IMSDBREFRESH command.

Valid values are:

  • ABORT - (the default) Terminates processing with a return code of 8 after the first non-recoverable primary database is detected.
  • CONTINUE - Continues processing the non-recoverable primary databases without applying logs to them, and ends the job with return code nnnn, which is specified in the ALLOW_NONRECOV_RC option.
  • SKIP - Skips processing the non-recoverable primary databases and continues processing other databases, and ends the job with return code nnnn, which is specified in the ALLOW_NONRECOV_RC option.

ALLOW_NONRECOV_RC=nnnn

Specifies the return code to be used if ALLOW_NONRECOV=CONTINUE or SKIP is specified. This value is applicable only if the corresponding ALLOW-NONRECOV keyword is not specified on the IMSDBREFRESH command. The return code nnnn must be a numeric value 0 - 4095. The default value is 4.

End of change


Update 1
Date of change: March 2019
Change description: Correction of documentation for the RENAME command syntax. This techdoc fixes some of the incorrect documentation changes that were made to this topic in SC19-3757-02.

============================

Topic: Reference: IMS Cloning Tool Commands > RENAME

 

This topic has been updated as follows:

RENAME command syntax

RENAME

Required keywords:

Required keywords

Optional Keywords:

Optional keywords

RENAME command & keyword definitions

.....

Start of changeMGMTCLAS( 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 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. SOURCE is the default. 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).
  • End of change

    .....

    Start of changeSTORCLAS( 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)
  • End of change

    Publication Number

    SC19-3757-02

    Original Publication Date

    20 February 2013

    Document Location

    Worldwide

    [{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SSNLC4","label":"IMS Cloning Tool for z\/OS"},"ARM Category":[{"code":"a8m0z000000cvYHAAY","label":"IMS Cloning Tool"}],"ARM Case Number":"","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"1.2.0"}]

    Document Information

    Modified date:
    24 June 2020

    UID

    ibm10875956