Reclone a single replicated object

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

The RECLONE_OBJECT procedure is used to copy a single replicated object and its network of dependent replicated objects from one Db2® Mirror node, known as the source node, to the other node, known as the copy node. This contrasts with software reclone which reclones all replicated objects and hardware reclone which reclones an entire replicated node.

When calling RECLONE_OBJECT the user identifies the object to reclone. RECLONE_OBJECT finds all dependent objects for the identified object. The identified object and all replicated dependent objects are deleted on the copy node and replaced by the version of the objects from the source node. Any entries in the Object Tracking List (OTL) for the specified object and its dependent objects, including failure entries, are deferred.

RECLONE_OBJECT can be run when both the primary and secondary nodes have a replication state of ACTIVE or the primary node has a replication state of TRACKING and the secondary node is BLOCKED. The following behavior occurs based upon the replication state:

Node replication state is ACTIVE
- RECLONE_OBJECT can be run from either node. The node the procedure is run from is the source node.
- The reclone operation is performed immediately. All dependent objects are identified, any existing OTL entries for the object and dependent objects are deferred, the copy node objects are deleted, and the objects are copied from the source node to the copy node.
- When the RECLONE_OBJECT is complete, the objects are in sync.
Node replication state is TRACKING
- RECLONE_OBJECT object can only be run on the primary node which has a replication state of TRACKING. If the secondary node is not available, the RECLONE_OBJECT will fail.
- When RECLONE_OBJECT is run, the dependent objects are identified, any existing OTL entries for the object and dependent objects are deferred, and the copy node objects are deleted. Tracking entries are written to the OTL that will cause the objects to be recloned during the next resynchronization.
- The objects will be resynchronized after Resynchronization is run and both nodes return to an ACTIVE replication state. During the resynchronization, the tracked objects will be copied from the source to the copy node. After resynchronization is complete, the objects are in sync.
Node replication state is BLOCKED
- RECLONE_OBJECT object cannot be run on the secondary node which has a replication state of BLOCKED.

The RECLONE_OBJECT procedure is used to correct replication problems such as recovering from a failure that was recorded for an object in the OTL. Since RECLONE_OBJECT relies upon save and restore technology, another use case is to overcome a situation where a large percentage of active rows are out of sync.

RECLONE_OBJECT considerations

Only *FILE objects are supported by the RECLONE_OBJECT procedure. Tables, views, indexes, physical files, and logical files can be recloned. It may not always be possible to reclone an object. The following is a list of RECLONE_OBJECT considerations and restrictions.

Object Tracking List

Certain OTL entries can prevent a RECLONE_OBJECT from running. This happens when there is an OTL entry for the object being recloned that affects an object outside of the dependency network that will be recloned. When this occurs, an SQLSTATE of 57033 is returned. To recover, the user should inspect the OTL entries for the replicated object and determine if additional objects need to be recloned using a separate call to RECLONE_OBJECT. After inspecting the OTL entries, manually defer the entries using CHANGE_RESYNC_ENTRIES procedure or the Db2 Mirror GUI. Careful consideration should be taken before deferring OTL entries, as it will potentially cause entries that should be processed to be removed from resynchronization consideration. Once the OTL entries are deferred, rerun RECLONE_OBJECT against the original object.

Replication Criteria List

While RECLONE_OBJECT is running, replication criteria rules cannot be added or removed from the Replication Criteria List (RCL) and rules in a pending RCL group cannot be changed or applied.

Object locking

During RECLONE_OBJECT, the objects on the source node are locked using *EXCLRD if the replication state is ACTIVE and *SHRNUP if the replication state is TRACKING. On the copy node the objects are locked using *EXCL. Therefore, the following restrictions apply:

I/O operations on the source node are restricted to read only for the object being recloned and its replicated dependent objects.
I/O operations on the copy node are prevented for the object being recloned and its replicated dependent objects.
All DDL changes are prevented on both the source and copy nodes for the object being recloned and its replicated dependent objects.

Commitment control

Any pending transactions within a job will prevent RECLONE_OBJECT from running. All active work must be committed before RECLONE_OBJECT can be run.

Non-replicated dependent objects

Non-replicated dependent objects that only exist on the source node are not recloned to the copy node. If a non-replicated dependent object has a dependent replicated object, the RECLONE_OBJECT will fail.

Non-replicated dependent objects may exist on the copy node. These objects are deleted when the based-on object is deleted by RECLONE_OBJECT. However, the non-replicated object on the copy node is first saved before being deleted and restored if possible after the replicated based-on object is recloned from the source.

Important:

Non-replicated dependent objects are not always able to be restored on the copy node. If the format of the replicated based-on object was changed in such a way that the non-replicated dependent object is invalid, the deferred restore will fail.

An example of this phenomenon is when an index exists on the copy node, is not replicated, has an index key over column FIRSTNM, and the column was renamed to FIRSTNAME as part of the RECLONE_OBJECT.

Evaluating the impact of a RECLONE_OBJECT

It is important to understand what objects will be deleted on the copy node. Some objects that are deleted are not recreated.

The replicated *FILE object passed to the RECLONE_OBJECT procedure is deleted on the copy node. This object is replaced by the version of the object from the source node.
A list is generated on the source node of the replicated objects that are dependent on the object specified on the RECLONE_OBJECT procedure. Dependent objects include history tables, indexes, logical files, Materialized Query Tables (MQTs), and views. This list is passed to the copy node, and the dependent objects are deleted on the copy node. The dependent objects are then recloned from the source node. The recloned object may differ from the original dependent object on the copy node but matches the object on the source node.
Replicated dependent objects that only exist on the copy node will be deleted and not recreated. Replicated dependent objects may exist only on the copy node if, for example, the object was deleted by an application, the deletion was tracked on the OTL on the source node, and that delete has not yet been processed.
Non-replicated dependent objects that only exist on the copy node will saved, and then deleted. These objects will be restored if possible. If they cannot be restored by RECLONE_OBJECT, it is up to the user to manually recreate them.
- The user can run the Restore Deferred Objects (RSTDFROBJ) CL command on the copy node to recreate the non-replicated dependent objects that were not restored on the copy node. A unique DFRID generated by RECLONE_OBJECT can be found in RESYNC_TYPE_DESCRIPTION column of the copy node OTL when the TRACKING_REASON column contains the value RECLONE OBJECT. Use this DFRID on the RSTDFROBJ command to manually attempt to restore the objects.
- If the RSTDFROBJ fails, it may be necessary to manually recreate the dependent object with a definition that is compatible with the recloned objects.