RECLONE_OBJECT procedure

The RECLONE_OBJECT procedure reclones a single replicated object and its replicated dependent objects.

This procedure can be used to reclone an object by specifying the library-name, object-name, and object-type for the replicated object to be recloned. If the specified object has replicated objects that are dependent upon it then the dependent objects are also recloned. These dependent objects can be views, logical files, indexes, history tables, or materialized query tables. Objects are replicated from the node where the procedure is run, called the source node, to a second node, called the copy node.

The reclone is accomplished by:

Deleting the specified object and the object's dependent objects, both replicated and not replicated, on the copy node.
Deferring the Object Tracking List (OTL) entries for the specified object and the object's replicated dependent objects on the source node.
Saving the specified object and the object's replicated dependent objects from the source node.
Restoring the specified object and the object's replicated dependent objects on the copy node.
Recreating the deleted non-replicated dependent objects on the copy node. It may not be possible to recreate the non-replicated dependent objects due to incompatibilities with the restored replicated objects.
- The Restore Deferred Objects (RSTDFROBJ) CL command is used to restore dependent objects on the copy node that are not replicated. A unique Defer ID (DFRID) is generated for every RECLONE_OBJECT invocation. This unique DFRID is saved in the RESYNC_TYPE_DESCRIPTION column of the OTL on the copy node when the TRACKING_REASON column contains the value RECLONE OBJECT.
- After the replicated objects are restored on the copy node, the RSTDFROBJ command is run on the copy node to restore any objects that were not replicated.
- If any non-replicated objects fail to restore, a failure message id is recorded in the OTL entry. A failure to restore an object that was not replicated does not affect the successful completion of RECLONE_OBJECT. Restore information for these objects remain in the QRECOVERY/QADBRSDFR table and can be identified by the unique DFRID from the OTL entry. You can correct any errors and attempt to manually run the RSTDFROBJ command again. If the objects are no longer needed, the Remove Defer ID (RMVDFRID) CL command can be used to remove the information from the QADBRSDFR table.
- The SYSTOOLS.RELATED_OBJECTS and CHECK_REPLICATION_CRITERIA services can be used before recloning an object to identify any dependent objects on the copy node which are not replicated. As explained in the previous bullet, these objects will be deleted on the copy node and may not successfully be recreated.

When library-name is in *SYSBAS:

If the replication state is ACTIVE, RECLONE_OBJECT can be initiated from either node.
If the replication state is not ACTIVE, RECLONE_OBJECT must be initiated on the primary node and the replication state must be TRACKING. The replication detail must be SUSPENDED.

When library-name is not in *SYSBAS:

The IASP must be varied-on with a configuration status of ACTIVE on both the source node and the copy node.
If the replication state of the IASP is ACTIVE, RECLONE_OBJECT can be initiated from either node.
If the replication state is not ACTIVE, RECLONE_OBJECT must be initiated on the primary node and the replication state must be TRACKING. The replication detail must be SUSPENDED.

Refer to Reclone a single replicated object to understand the considerations, locking requirements, and related details associated with RECLONE_OBJECT.

Restrictions: The following restrictions apply:

RECLONE_OBJECT can only be performed against a table, view, physical file, logical file, MQT, or index.
RECLONE_OBJECT cannot be performed against:
- An object that is not replicated or is ineligible for replication.
- A table with a foreign key constraint. Remove the foreign key constraint, run the RECLONE_OBJECT, then add the constraint back. Use RMVPFCST RMVCST(*KEEP) to avoid having the index deleted.
- A table that is the parent table for a referential constraint. Remove the foreign key constraint from the dependent table, run the RECLONE_OBJECT, then add the constraint back.
- A table that is a history table. Instead, specify the temporal table on the call to RECLONE_OBJECT. This will cause both the temporal table and the dependent history table to be recloned.
- A catalog or cross reference table or an object based on a catalog or cross reference table that exists within a user created library.
- An object with a dependency network containing more that 65534 dependent objects.
- An object that has a dependent object that is not replicated and the not replicated object has a dependent object that is replicated.
RECLONE_OBJECT cannot be performed unless both the source node and copy node are on IBM® i 7.6.
RECLONE_OBJECT must be run at a commit boundary. Pending changes cannot exist for the job that runs the procedure. Commit any pending changes and retry the RECLONE_OBJECT.
Some OTL entry types on the source node can result in an out-of-sync condition when deferred. This happens when a tracked operation is deferred that affects objects that are not dependent on the object being recloned. Therefore, if the OTL contains one of the below entry types for the object being recloned or any of its dependent objects, the RECLONE_OBJECT will fail. The OTL entry types that cannot be deferred by RECLONE_OBJECT are:
- ALTER TABLE DETACH PARTITION
- MOVOBJ
- RNMOBJ or RENAME
- DLTF or DROP TABLE/VIEW
To resolve, run Resynchronization to process all OTL entries then retry the RECLONE_OBJECT for the object. Alternatively, analyze the problem OTL entries on the source node, manually defer the OTL entries for the object, and then retry the RECLONE_OBJECT.
Deferring OTL entries on the copy node can result in the loss of changes to an object because the objects on the copy node are replaced by the objects from the source node. Therefore, if there are OTL entries on the copy node for the object being recloned or any of its dependent objects, the RECLONE_OBJECT will fail. The user must analyze the OTL entries on the copy node, determine if it's okay for those tracked changes to be lost, then defer the OTL entries manually. Once the OTL entries are deferred, retry the RECLONE_OBJECT.
Due to locking requirements, only one call to RECLONE_OBJECT for objects in a dependency network can be running on the Db2 Mirror node pair at a time. Multiple RECLONE_OBJECT requests are allowed as long at their dependency networks do not contain a common object. While RECLONE_OBJECT is running, the Replication Criteria List cannot be modified.
If the replication state is TRACKING, Db2 Mirror cannot resume replication until the RECLONE_OBJECT procedure completes.

Authorization: The privileges held by the authorization ID of the statement must include *ALLOBJ special authority. For additional authorities needed to use this procedure, see Authorization.

The schema is QSYS2.

library-name: A character or graphic string that identifies the library containing object-name.
object-name: A character or graphic string that identifies the object to be recloned.
object-type: A character or graphic string that identifies the system object type of object-name. The value must be *FILE.

Example

Reclone file APPLIB1/TABLE1.

CALL QSYS2.RECLONE_OBJECT(LIBRARY_NAME => 'APPLIB1', 
                          OBJECT_NAME  => 'TABLE1', 
                          OBJECT_TYPE  => '*FILE');