CHANGE_LIBRARY_MIGRATION_ENTRIES scalar function

The CHANGE_LIBRARY_MIGRATION_ENTRIES scalar function removes or omits entries from the library tracking list (LTL) and object tracking list (OTL).

Historical and active entries for the specified object are removed or omitted from the LTL and OTL according to the entry-action parameter value. Active entries are entries for objects that have not yet been migrated or need to be synchronized. Historical entries are entries for objects that have been successfully migrated and synchronized to the target node. Active entries can be examined in LIBRARY_MIGRATION_LIST view. Historical entries can be examined in the MIGRATED_LIBRARY view. If no entries for the specified object exist, an error is returned.

CHANGE_LIBRARY_MIGRATION_ENTRIES will return an error if no entries for the specified object exist in either tracking list. For Db2® Mirror replication-eligible objects types, CHANGE_LIBRARY_MIGRATION_ENTRIES will return an error if run while entries are being synchronized from the OTL. For non-Db2 Mirror replication-eligible object types, CHANGE_LIBRARY_MIGRATION_ENTRIES will return an error if run while entries are being synchronized from the LTL.

The MIGRATION_MANAGER_INFO view can be queried to determine whether entries are currently being synchronized from either tracking list.

SELECT ENTRY_TYPE, MIGRATION_PHASE_DETAIL
  FROM QSYS2.MIGRATION_MANAGER_INFO
  WHERE ENTRY_TYPE IN ('OBJECT MIRROR', 'OBJECT RESTORE');

The row with an ENTRY_TYPE of OBJECT MIRROR indicates whether entries are being migrated from the object tracking list. If the MIGRATION_PHASE_DETAIL is ACTIVE, entries are being migrated from the OTL.

This function will return a value of -1 indicating an error occurred if the object-type parameter value represents a Db2 Mirror replication-eligible object type and OTL entries are currently being migrated.
The row with an ENTRY_TYPE of OBJECT RESTORE indicates whether entries are being migrated from the library tracking list. If the MIGRATION_PHASE_DETAIL is ACTIVE, entries are being migrated from the LTL.

This function will return a value of -1 indicating an error occurred of the object-type parameter value represents a non-Db2 Mirror replication-eligible object type and LTL entries are currently being migrated.

Authorization: The privileges held by the authorization ID of the statement must include the following:

For the authority needed to use this function, see Db2 Mirror services authorization.
Authorization to the QIBM_DB2_MIRROR function usage identifier.
*EXECUTE authority on the QRECOVERY library.
*OBJOPR, *READ, *DLT, *ADD and *UPD authority on QRECOVERY/QADBRSYSTS.
*OBJOPR, *READ, *DLT, *ADD and *UPD authority on QRECOVERY/QADBRSYNM.

The schema is QSYS2.

library-name

A character or graphic string that identifies the library containing the objects whose entries will be removed or omitted.

object-name

A character or graphic string that identifies the object whose entries will be removed or omitted.

object-type

A character or graphic string that identifies the object type of the object whose entries will be removed or omitted.

entry-action

A character or graphic string value that indicates which entries will be removed or omitted.

OMIT: Active entries for the object will have their TRACKING_STATE column set to OMITTED in the LIBRARY_TRACKING_LIST view. An entry that has a tracking state of omitted will not be processed during data synchronization. Subsequent changes to the object will be tracked and migrated.; Warning: This option should be used with extreme caution as it will cause Migrate While Active to not migrate the corresponding changed object.
REMOVE ALL: Historical entries for the object in the MIGRATED_LIBRARY view and active entries for the object in the LIBRARY_TRACKING_LIST view will be removed. Subsequent changes to the object will be tracked and migrated.; Warning: This option should be used with extreme caution as it will cause Migrate While Active to not migrate the corresponding changed object.
REMOVE HISTORICAL: Historical entries for the object will be removed from the MIGRATED_LIBRARY view. Historical entries are entries for objects that have been successfully migrated to the target node.

The result of the function is an integer. If the entries are removed or omitted successfully, the function returns a value of 1. If the entries cannot be removed or omitted because of an error, the function returns a value of -1.

Examples

Remove all historical entries for file APPLIB1/TABLE1.

VALUES QSYS2.CHANGE_LIBRARY_MIGRATION_ENTRIES(LIBRARY_NAME => 'APPLIB1', 
                                              OBJECT_NAME  => 'TABLE1', 
                                              OBJECT_TYPE  => '*FILE',
                                              ENTRY_ACTION => 'REMOVE HISTORICAL');

Omit all tracking entries for user-defined message file APPLIB1/APPMSGS.

VALUES QSYS2.CHANGE_LIBRARY_MIGRATION_ENTRIES(LIBRARY_NAME => 'APPLIB1', 
                                              OBJECT_NAME  => 'APPMSGS', 
                                              OBJECT_TYPE  => '*MSGF',
                                              ENTRY_ACTION => 'OMIT');

Remove all historical entries in the library tracking list for message file objects in library TEMPLIB.

SELECT LIBRARY_NAME, OBJECT_NAME, OBJECT_TYPE,
       QSYS2.CHANGE_LIBRARY_MIGRATION_ENTRIES(LIBRARY_NAME => ML.LIBRARY_NAME, 
                                              OBJECT_NAME  => ML.OBJECT_NAME, 
                                              OBJECT_TYPE  => ML.OBJECT_TYPE,
                                              ENTRY_ACTION => 'REMOVE HISTORICAL') AS ENTRY_REMOVED   
  FROM QSYS2.MIGRATED_LIBRARY ML
  WHERE ML.LIBRARY_NAME = 'TEMPLIB'
    AND ML.OBJECT_TYPE = '*MSGF';