CHANGE_IFS_MIGRATION_ENTRIES scalar function

The CHANGE_IFS_MIGRATION_ENTRIES scalar function removes or omits entries from the integrated file system tracking list (ITL).

Historical and active entries for the specified integrated file system object are removed or omitted in the ITL 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 the IFS_MIGRATION_LIST view. Historical entries can be examined in the MIGRATED_IFS view.

CHANGE_IFS_MIGRATION_ENTRIES will return an error if no entries for the specified object exist or the scalar function is run while entries are being synchronized from the ITL. The MIGRATION_MANAGER_INFO view can be queried to determine whether entries for the integrated file system tracking list are currently being synchronized.

SELECT ENTRY_TYPE, MIGRATION_PHASE_DETAIL
  FROM QSYS2.MIGRATION_MANAGER_INFO
  WHERE ENTRY_TYPE = 'IFS RESTORE';

If the MIGRATION_PHASE_DETAIL is ACTIVE, entries are currently being migrated from the ITL and this function will return a value of -1 indicating an error occurred.

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/QADBRSYIFS.

The schema is QSYS2.

path-name

An expression that returns the absolute path name identifying the integrated file system object whose entries will be removed or omitted.

If the object is a directory, entries for integrated file system objects within the directory subtree, including all subdirectories and objects within those subdirectories, are not affected. If the path name identifies an object that has hard links or is a hard link, it cannot be omitted or removed from the ITL and an error will be returned.

entry-action

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

OMIT: Active entries for the object will have their TRACKING_STATE column set to OMITTED in the IFS_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 integrated file system object in the MIGRATED_IFS view and active entries for the object in the IFS_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 integrated file system object will be removed from the MIGRATED_IFS 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 the historical entry from the integrated file system tracking list (ITL) for the directory /dir1/subdir1.

VALUES QSYS2.CHANGE_IFS_MIGRATION_ENTRIES(PATH_NAME    => '/dir1/subdir1', 
                                          ENTRY_ACTION => 'REMOVE HISTORICAL');

Omit tracking entries for the stream file /dir1/subdir1/myfile.txt. The stream file will not be migrated during data synchronization unless a subsequent change causes the object to be tracked again.

VALUES QSYS2.CHANGE_IFS_MIGRATION_ENTRIES(PATH_NAME    => '/dir1/subdir1/myfile.txt',
                                          ENTRY_ACTION => 'OMIT');

Remove all historical entries for all objects within the /usr/dir1 directory subtree tracked in the ITL.

SELECT PATH_NAME, 
       QSYS2.CHANGE_IFS_MIGRATION_ENTRIES(PATH_NAME    => MI.PATH_NAME, 
                                          ENTRY_ACTION => 'REMOVE HISTORICAL') AS ENTRY_REMOVED
  FROM QSYS2.MIGRATED_IFS MI
  WHERE MI.PATH_NAME LIKE '/usr/dir1/%'

Omit all active entries for all objects within the /usr/dir1 directory subtree tracked in the ITL.

SELECT PATH_NAME, 
       QSYS2.CHANGE_IFS_MIGRATION_ENTRIES(PATH_NAME    => IML.PATH_NAME, 
                                          ENTRY_ACTION => 'OMIT') AS ENTRY_OMITTED
  FROM QSYS2.IFS_MIGRATION_LIST IML
  WHERE IML.PATH_NAME LIKE '/usr/dir1/%';