EVALUATE_PENDING_REPLICATION_CRITERIA table function

The EVALUATE_PENDING_REPLICATION_CRITERIA table function returns one row for each object found that matches any of the replication criteria rules from the Replication Criteria List (RCL) identified by the apply-label parameter. Only objects whose replication action will be changed by the replication criteria rules will be returned. This list of objects can be examined to understand the replication action that would be applied to each object when the pending rules are committed.

Each row describes a single object that is eligible for replication that matches one or more of the replication criteria rules identified by the apply-label parameter. The function will identify objects that exist on either node and indicates the replication action that would be performed against the object. Additional information about the object is returned in the OBJECT_INFO column. When a node or an IASP is not accessible, only those objects that can be identified from the current node will be returned. No comparison of the objects can be performed when a node is inaccessible.

When the compare-objects parameter is set to YES and an object that will require replication is found on both nodes, the objects are compared and the result is returned in the COMPARE_RESULT column. While rows are returned for all object types eligible for replication, only some types support comparisons. All others return the null value for the comparison result. If any object's COMPARE_RESULT is DIFFERENT, the OBJECT_INFO column will contain additional information about why this object will prevent the pending replication criteria rules from being committed. Rows where COMPARE_RESULT is the null value could cause failures when replication processing occurs.

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

For the authority needed to use this procedure, see Authorization.
*EXECUTE authority on the QSYS2 library.
*OBJOPR and *READ authority on QSYS2/MIRROR_RCL

The schema is QSYS2.

iasp-name

A character or graphic string expression that identifies the name of the auxiliary storage pool (ASP) group used to locate the replication criteria rules that will identify the objects with a pending replication change. Can contain the following special value:

*SYSBAS: The replication criteria rules are associated with the system ASP (ASP 1) and any basic user ASPs (ASPs 2-32).

compare-objects

A character or graphic string expression that indicates whether the objects will be compared when an object with a pending replication change to DEFINITION or INCLUDE is located on both nodes.

NO

No comparisons will be performed when an object exists on both nodes.

YES

The pending replication objects will be compared when an object exists on both nodes. This is the default.

Only the following object types support comparisons while evaluating the pending rules:

*DTAARA: Data area
*DTAQ: Data queue
*ENVVAR: System-level environment variable
*JOBD: Job description
*JOBQ: Job queue
*LIB: Library
*OUTQ: Output queue
*PGM: Program
*SRVPGM: Service program
*SYSVAL: System value
*USRIDX: User index
*USRSPC: User space

apply-label

A character or graphic string expression that identifies a label for the pending replication criteria rules to be considered.

The apply-label identifies pending replication criteria rules that have been created by add or remove requests with this label.

*GENERATE: Use the apply-label generated by the system for this job. The generated value is always the same for a specific job. This behavior allows multiple rule changes within a job to be added or removed in PENDING state and then processed in a single operation. This is the default.
label-identifier: An apply-label value that identifies a set of pending rules.

The result of the function is a table containing rows with the format shown in the following table. All columns are nullable.

Table 1. EVALUATE_PENDING_REPLICATION_CRITERIA table function
Column Name	Data Type	Description
IASP_NAME	VARCHAR(10)	Name of the independent ASP group associated with the object. Contains either the name of the ASP group or the following special value: *SYSBAS The object is stored in either the system ASP (ASP 1) and any basic user ASPs (ASPs 2-32).
LIBRARY_NAME	VARCHAR(10)	Name of the library that contains the object.
OBJECT_NAME	VARCHAR(128)	System name of the object, system-level environment variable, or system value.
OBJECT_TYPE	VARCHAR(8)	Type of object. DTAARA Data area DTAQ Data queue ENVVAR System-level environment variable FILE Database file JOBD Job description JOBQ Job queue JRN Journal LIB Library OUTQ Output queue PGM Program SQLPKG SQL package SQLUDT SQL user-defined type SQLXSR SQL XML schema repository SRVPGM Service program SYSVAL System value USRIDX User index *USRSPC User space
INCLUSION_STATE	VARCHAR(10)	The existing replication inclusion state for this object. DEFINITION Only the definition of the object is replicated. EXCLUDE The object is excluded from any replication action. INCLUDE The object is included in any replication action. INELIGIBLE The object is not eligible to be included in replication.
PENDING_INCLUSION_STATE	VARCHAR(10)	The replication inclusion state for this object if all the pending replication criteria rules identified by apply-label are committed. DEFINITION Only the definition of the object is replicated. EXCLUDE The object is excluded from any replication action. INCLUDE The object is included in any replication action. INELIGIBLE The object is not eligible to be included in replication. PROCESSING This rule responsible for this object's replication inclusion state is currently being committed to the RCL. Its final inclusion state has not been determined.
OBJECT_ON_PRIMARY	VARCHAR(3)	Indicates whether the object was found on the primary node. NO This object was not found on the primary node. YES This object was found on the primary node. Contains the null value if the primary node or IASP is not available.
OBJECT_ON_SECONDARY	VARCHAR(3)	Indicates whether the object was found on the secondary node. NO This object was not found on the secondary node. YES This object was found on the secondary node. Contains the null value if the secondary node or IASP is not available.
COMPARE_RESULT	VARCHAR(10)	The result of the compare operation performed on the object. DIFFERENT At least one eligible attribute compared differently. IDENTICAL All the eligible attributes compared identical. Contains the null value if the compare-object parameter is `NO`, if the object does not exist on both nodes, or if the object is not eligible to be compared. Either the object-type or an attribute of the object can make the object ineligible to be compared.
OBJECT_INFO	INTEGER	Additional information about the object with a pending replication change. Values are listed in the Notes section. Contains the null value if no additional information is available.
OBJECT_INFO_TEXT	VARCHAR(1024)	Descriptive text corresponding to `OBJECT_INFO`. Contains the null value if no additional information is available.

Notes

The following values can be returned to provide additional information about an object with a pending replication change: Values greater than 200 are errors. Values less than 200 are warnings.

Table 2. OBJECT_INFO values that do not prevent rules from being committed
OBJECT_INFO	OBJECT_INFO_TEXT
101	Object not compared because its inclusion state is changing from INCLUDE or DEFINITION to EXCLUDE.
102	Object found on both nodes but was not compared because NO was specified for COMPARE_OBJECTS.
103	Object not found on primary or secondary node, or retrieve from primary or secondary node failed with return code <value>.
104	Object partially compared because user is not authorized to some information.
105	Object replication has been disabled by product object replication controls.

Table 3. OBJECT_INFO values that prevent rules from being committed
OBJECT_INFO	OBJECT_INFO_TEXT
201	Objects of this type are not allowed to exist on both nodes.
202	An attribute of the object prevents it from being compared.
203	Object found on both nodes prevents replication from being activated for this object.
204	Error received while comparing objects.

Examples

List all the objects with a pending replication change that match one of the replication criteria rules associated with apply-label TESTGROUP1. Do not perform any comparisons on objects that are found on both nodes.

SELECT * 
FROM TABLE(QSYS2.EVALUATE_PENDING_REPLICATION_CRITERIA(IASP_NAME => '*SYSBAS',
                                                       APPLY_LABEL => 'TESTGROUP1', 
                                                       COMPARE_OBJECTS => 'NO')) 
ORDER BY LIBRARY_NAME, OBJECT_TYPE, OBJECT_NAME;

Determine if any of the objects with a pending replication change that match one of the replication criteria rules associated with apply-label TESTGROUP2 will prevent the rules from being committed because existing objects already exist on both nodes.
```
SELECT COMPARE_RESULT, LIBRARY_NAME, OBJECT_TYPE, OBJECT_NAME, 
       OBJECT_INFO, OBJECT_INFO_TEXT 
FROM TABLE(QSYS2.EVALUATE_PENDING_REPLICATION_CRITERIA(IASP_NAME => '*SYSBAS', 
                                                       APPLY_LABEL => 'TESTGROUP2', 
                                                       COMPARE_OBJECTS => 'YES')) 
WHERE COMPARE_RESULT IN ('DIFFERENT') OR OBJECT_INFO > 200
ORDER BY LIBRARY_NAME, OBJECT_TYPE, OBJECT_NAME;
```
Only objects with a pending replication change that exist on both nodes and that cannot be compared identical will be returned. These objects will prevent the pending replication criteria rules from being committed.

¹ For each database IASP, a separate RCL table exists in library QSYS2nnnnn/MIR_RCLnnn; the authorization rules apply to these tables as well.