:DB_COPY_OPTIONS section

GCLINI contains a :DB_COPY_OPTIONS section.

Purpose

This section defines the options that IMS Cloning Tool uses for the database and data set copy operations. You can use the IMSDBREFRESH command options to override these settings.

Parameters

ALLOW_HALDB_REDEFINE = N|Y
This parameter specifies whether HALDB definitions in DBRC can be deleted and redefined as part of the database cloning process when there are differences in the partition between source and target databases. Valid values include:
  • N – Do not allow IMS Cloning Tool to clone HALDBs if doing so would require deleting and redefining the target database in DBRC.
  • Y – IMS Cloning Tool can delete and redefine a target database in DBRC to complete the cloning process. This parameter is only applicable when DBRC_ACTION = REORG is in effect.

The default value is N.

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.
ALLOW_PARTIAL = N|Y
Optional keyword that indicates whether IMS Cloning Tool should continue processing even if an error is encountered with one of the databases (for example, if one of the databases that is being refreshed had a compatibility issue). Valid values are:
  • N – Stop the IMSDBREFRESH process when an error is encountered with any of the databases.
  • Y – Continue processing other databases when an error is encountered with one or more databases.

The default value is N.

ALLOW_TGTDBD = N|Y
Optional keyword that indicates whether the TGT-DBD keyword can be specified when COPY-IF-DIFFERENT-HALDB(Y) is specified on the IMSDBREFRESH command. This value is applicable only if the second operand of the COPY-IF-DIFFERENT-HALDB keyword is not specified on the IMSDBREFRESH command.
  • N – If 'N' is specified, the TGT-DBD keyword is not allowed when Y is specified for the first operand on the COPY-IF-DIFFERENT-HALDB(Y) keyword.
  • Y – If 'Y' is specified, the TGT-DBD keyword can be specified when Y is specified for the first operand on the COPY-IF-DIFFERENT-HALDB(Y) keyword.

The default value is N.

ARCHIVE_WAIT_TIME = n
Optional keyword that indicates how long IMS Cloning Tool waits for an online log data set to be archived before the IMSDBREFRESH job terminates abnormally. The wait time must be a numeric value between 0 and 999. The value specified indicates the number of minutes to wait.

This value is only applicable if LOG-APPLY(Y) was specified and is only used if the ARCHIVE-WAIT keyword is not specified on an IMSDBREFRESH command. The default value is 5.

ARCHIVE_WAIT_RC = n
Optional keyword that indicates the return code to use when an online log data set containing updates for the source databases has not been archived in the amount of time specified by ARCHIVE_WAIT_TIME. The return code must be a numeric value from 0 through 4095.

This value is only applicable if LOG-APPLY(Y) was specified and is only used if the ARCHIVE-WAIT keyword is not specified on an IMSDBREFRESH command. The default value is 8.

AUTO_START_SOURCE_DB = Y|N
Indicates whether IMSDBREFRESH can optionally start each source IMS database after the copy process is complete. Valid values are:
  • Y – Start the source databases after the copy process is complete.
  • N – Remain stopped after the copy process is complete.
The default value is Y.
AUTO_START_TARGET_DB = Y|N
Indicates whether to automatically issue the START DB command for the database.

This token determines if IMSDBREFRESH processing issues an IMS START DATABASE command for the databases being processed after all of the Sync I/O to the data set is complete. This value determines the value of the START-DB command in each invocation of the IMSDBREFRESH command.

The AUTO-START-TARGET-DB value from the IMSDBREFRESH command overrides the value from the GCLINI member in the SGCLPARM library.

The default value is Y.

AUTO_STOP_TARGET_DB = Y|N
Indicates whether to automatically issue a DBR DB DATABASE IMS command for each target database. Valid values are:
  • Y – Issue the DBR command. Because IMS Cloning Tool must have exclusive control of the target database data sets, the DBR command must complete before the copy processing can begin.
  • N – Assume that the database is already stopped and do not issue the DBR command before the copying begins. If the database is not stopped, DFSMSdss gets an allocation error.
The AUTO-STOP-TARGET-DB value from the IMSDBREFRESH command overrides the value from the SGCLPARM library.

The default value is Y.

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 value is N.

COPY_IF_NO_IMS_TARGET_DB = N|Y
Optional keyword that indicates whether IMS Cloning Tool defines elements for target databases on the target IMS if they do not currently exist. These elements would include DBRC definitions, MDA members, and ACB members, and a CREATE DB command is submitted to define the database to the target IMS system. The process to perform the CREATE DB command requires the CSL and the target IMS system to be active.

If COPY_IF_NO_IMS_TARGET_DB = N and elements for the target database are not found, IMS Cloning Tool does not refresh the database. If COPY_IF_NO_IMS_TARGET_DB = Y, the RENAME-MASKS keyword is required to determine the target data set names. The RENAME-MASKS keyword is also required to determine the target DBD and DD names if the target database is in the same IMS system as the source database. If IMSPLEX is specified, then databases can be created using the CREATE DB command on the target IMS. If IMSPLEX is not specified, then the CREATE DB command is skipped.

This value is used only if the COPY-IF-NO-IMS-TARGET-DB keyword is not specified on the IMSDBREFRESH command.
The default value is N.
DATA_MOVER = ADRDSSU | EMCAPI | NONE
Optional keyword that specifies the program to be used to initiate copies and copy options.
  • ADRDSSU - (the default) specifies that COPY is to initiate FlashCopy® or SnapShot under the covers via execution of DSS.
  • EMCAPI - specifies that IMS Cloning Tool Database Refresh is to invoke EMC TimeFinder/Clone to make the copies using the data set snap facility. Refer to the DATA-MOVER keyword in IMSDBREFRESH for additional information.
  • NONE - specifies that no DATA-MOVER is to be invoked by the IMSDBREFRESH command. NONE infers that data set copies will be initiated by the user. When NONE is specified, IMSDBREFRESH still validates necessary IMS database characteristics, stops the source databases if requested, and builds the list of data sets as input to the user copy

The default value is ADRDSSU.

DBRC_ACTION = REDEFINE | REORG
Optional keyword that indicates the DBRC action to perform for the target databases after refreshing them. If DBRC_ACTION = REORG is specified, IMS Cloning Tool performs a NOTIFY.REORG for all database data sets that were refreshed. If DBRC_ACTION = REDEFINE is specified, IMS Cloning Tool performs a LIST.DB to provide a reference for current DBRC definitions, followed by a DELETE.DB, INIT.DB, and any INIT.DBDS, INIT.PART, and INIT.AREA commands to redefine the target database. This value is only used if the DBRC-ACTION keyword is not specified on an IMSDBREFRESH command.
The default value is REDEFINE.
FASTREP = PREF | REQ | NONE

Optional keyword that indicates whether fast replication is preferred (PREF), required (REQ), or not required (NONE).

The default value is PREF.

FCTOPPRCPRIMARY = PRESMIRNONE | PRESMIRREQ | PRESMIRPREF

Optional keyword that indicates what action to perform for preserving mirror when a FlashCopy target volume can also be a PPRC primary volume.

  • PRESMIRREQ - Require the use of Preserve Mirror. If a Preserve Mirror operation cannot be accomplished, the FlashCopy operation will not be completed.
  • PRESMIRPREF - Prefer the use of Preserve Mirror. If a Preserve Mirror operation cannot be accomplished, the FlashCopy operation is still performed
  • PRESMIRNONE - Do not use Preserve Mirror.

This parameter applies to ESS devices only; it does not apply when FASTREP(NONE) is also specified. The default value is PRESMIRNONE.

DSNS_PER_COPY = 255
Specifies the number of data sets to include in each DFSMSdss copy command. The valid range of values is from 1 through 255. By changing this value, you may be able to improve performance.

The default value is 255.

DSS_COPY_COMMANDS = 8

The DSS_COPY_COMMANDS parameter specifies the number of DSS copy commands to send to DSS in a single invocation. Valid values are 1 to 256; specifying a large value may result in storage shortage abends.

The default value is 8.

LOG_APPLY = N | Y

Optional keyword that indicates if IMS Cloning Tool should apply log updates from the source databases to the target databases after copying the source databases. If ‘Y' is specified, IMS Cloning Tool applies logs to complete any in-flight updates to the target databases after copying them. If ‘N' is specified, IMS Cloning Tool does not apply any updates to the target databases after copying the data sets. This could result in in-flight updates existing in the target databases if FUZZY-COPY(Y) was specified.

This value is only used if the LOG-APPLY keyword is not specified on an IMSDBREFRESH command.

The default value is N.

LOG_APPLY_MONITOR = 0
When this optional keyword is used, IMS Cloning Tool outputs messages every nnn minutes indicating the amount of log apply activity that has occurred in the previous specified number of minutes.

nnn can be any numeric value from 0 to 999, and indicates the interval, in minutes, in which IMS Cloning Tool should issue messages showing log apply activity. When 0 is specified, no messages showing log apply activity are issued.

MAX_COPY_RC = 0|4|8
Specifies the maximum return code that can be returned from data set copy processing before causing the IMSDBREFRESH to stop. This token value will allow one or more DFSMSdss copy operations to fail while other copy operations continue.

For example, STOP JOB WHEN > MAX_COPY_RC OCCURS WHEN COPYING DATA specifies that, when copying data, IMS Cloning Tool should stop the job when a return code from a copy function is greater than the value specified in the MAC_COPY_RC keyword.

The default value is zero. If 0 is specified, any data set copy requests that end with a return code greater than zero will cause the IMS Cloning Tool command to terminate.

MAX_RC = 0|4
Specifies the maximum value that a return code from an IMS Cloning Tool process can have for a job to continue running. This token value does not apply to data set copy processing. (See the MAX_COPY_RC keyword for the maximum return code for data set copy processing.)

For example, STOP JOB WHEN > MAX_RC specifies that IMS Cloning Tool should stop the database refresh processing when a return code from any process is greater then the value specified by the MAX_RC keyword. If this keyword is set to zero and some IMS databases are not found on the target, no source databases will be copied. Set MAX_RC to 4 if you want to complete the cloning process for the databases that can be copied, even if the other the databases cannot be cloned.

The default value is zero.

For example, to stop a job when any warning message is issued, set MAX_RC=0. To allow IMS Cloning Tool to complete if one or more warning messages are issued, set MAX_RC=4.

NULLSTORCLAS = Y|N
Optional keyword that determines input to the automatic class selection (ACS) routine when copying data sets with ADRDSSU. If 'Y' is specified, a null storage class will be passed to the ACS. This allows the ACS routine to assign storage classes to the target data sets. If 'N' is specified, input to the ACS will be storage class of the source data sets. For more information on this keyword, consult the z/OS® DFSMSdss Storage Administration documentation.

The default value is Y.

NOAUTH_TARGETS = N|Y
Optional keyword that indicates that IMS Cloning Tool sets PROHIBIT AUTH=ON in the target RECONs for the target databases before starting the data set copy process. This prevents other IMS jobs from authorizing the target databases until the database refresh process has completed. If IMS Cloning Tool sets PROHIBIT AUTH=ON, the flag is reset after the data set copy process is complete. Valid values include 'Y' (prevent IMS jobs from authorizing the target databases until the database refresh process is complete), and 'N' (do not set PROHIBIT AUTH=ON).
The default value is N.
RECALL_MIGRAT_DS = N|Y
Optional keyword that indicates whether IMS Cloning Tool recalls a migrated database data set.
  • N – Retain a migrated database data set.
  • Y – Recall a migrated database data set before the copy process starts.
The default value is N.
REGISTER_DBRC = N|Y
Optional keyword that indicates whether to register the target database to DBRC after creating a new database on the target IMS system. When 'N' is specified, the new database is not registered to DBRC. When 'Y' is specified, the new database is registered to DBRC. If 'Y' is specified, the source database must be registered to DBRC. The new data set names and the DBRC definitions are copied from the source database. This keyword does not apply to HALDBs as they will always be registered.
This value is only applicable if the COPY-IF-NO-IMS-TARGET-DB(Y) keyword was specified and is only used if the REGISTER-DBRC keyword is not specified on an IMSDBREFRESH command.
The default value is N.
REPLACE_TARGET_DS = Y|N
Indicates whether IMS Cloning Tool should replace the data set on the target if it already exists.
  • Y – To have IMS Cloning Tool overlay the existing target data set with the source data set.
  • N – To have IMS Cloning Tool fail if the target data set already exists.
The default value is Y.
SET_IC_NEEDED_OFF = Y | N
Optional keyword that indicates whether IMS Cloning Tool resets the image copy needed flag for a target database after it has been refreshed and a NOTIFY.REORG was issued. A value of ‘Y' indicates that IMS Cloning Tool resets the image copy needed flag. A value of ‘N' indicates that IIMS Cloning Tool does not reset the image copy needed flag after doing the NOTIFY.REORG. This value is only used if the DBRC-ACTION keyword is not specified on the IMSDBREFRESH command and REORG is specified for the DBRC_ACTION keyword in GCLINI.
The default value is Y.
STOP_COMMAND = DBR |DBD | QUIESCE
Optional keyword that indicates the IMS command to be used to stop the source databases. When DBR is specified, the DBRECOVER command is used, and all access to the source databases will be stopped. When DBD is specified, the DBDUMP command will be issued and the full function source databases will be put into read-only mode, and a DBRECOVER command will be issued for DEDBs. When QUIESCE is specified, an UPDATE DB QUIESCE command will be used and IMS will only pause access to the source databases for the duration of the copy. The default value is DBR.
SWITCH_OLDS = N | Y

Optional keyword that dictates if IMS Cloning Tool issues a /SWI OLDS command to the source IMS system after copying the database data sets and prior to reading the archive log data sets in order to fine log records to apply to the target databases. When "Y" is specified, IMS Cloning Tool issues a /SWI OLDS command. When "N" is specified, IMS Cloning Tool does not issue a /SWI OLDS command after copying the database data sets.

This value is only applicable if LOG-APPLY(Y) was specified and is only used if the SWITCH-OLDS keyword is not specified on an IMSDBREFRESH command.

The default value is Y.

VERIFY_NO_UPDATERS = N|Y
This parameter specifies whether IMS Cloning Tool verifies that the source databases are not currently authorized by an IMS subsystem or batch job that could be updating the source databases. This check is only applicable if IMS Cloning Tool will be doing a fuzzy copy of the source databases.
Note: The VERIFY-NO-UPDATERS value from the IMSDBREFRESH command overrides this value from the GCLINI member in the SGCLPARM library.
The default value is N.