CHECK_REPLICATION_CRITERIA scalar function

The CHECK_REPLICATION_CRITERIA scalar function returns an indication of the replication inclusion state for an object. Rules defined in the Replication Criteria List (RCL) are applied against the object identified by the iasp-name, library-name, object-type, and object-name parameters.

This function will find the best match among the existing rules in the RCL using the iasp-name, library-name, object-type, and object-name criteria to determine the replication inclusion state. The fully qualified object does not need to exist.

Authorization: For the authority needed to use this function, see Authorization.

The schema is QSYS2.

iasp-name

A character or graphic string expression that identifies the name of the auxiliary storage pool (ASP) group. Can contain the following special value:

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

library-name

A character or graphic string expression that identifies the library name.

object-type

A character or graphic string expression that identifies the object type.

Any system object type can be specified. However, only the following type values are eligible for replication. All others will return INELIGIBLE as the function's result.

*AUTL: Authorization list. library-name must be QSYS.
*DTAARA: Data area
*DTAQ: Data queue
*ENVVAR: System-level environment variable. library-name must be QSYS.
*FCNUSG: Function usage
*FILE: Database file
*JOBD: Job description
*JOBQ: Job queue
*JRN: Journal
*LIB: Library
*OUTQ: Output queue
*PGM: Program
*SECATR: Security attribute
*SQLPKG: SQL package
*SQLUDT: SQL user-defined type
*SQLXSR: SQL XML schema repository
*SRVPGM: Service program
*SYSVAL: System value. library-name must be QSYS.
*USRIDX: User index
*USRPRF: User profile. library-name must be QSYS.
*USRSPC: User space

object-name

A character or graphic string expression that identifies the system name of the object, system-level environment variable, or system value. When the object-type is *SECATR, object-name must be omitted. In all other cases, object-name is required.

apply-state

A character or graphic string expression that indicates the replication criteria rules to use for evaluating the inclusion state for the object.

ACTIVE: Only consider active replication criteria rules. This is the default.
PENDING: Consider active replication criteria rules and any pending replication criteria rules that have a matching apply-label. Using this option allows a set of replication rules to be evaluated prior to making them active.

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 defined by add or remove requests. Rules with this label will be considered when apply-state has a value of PENDING.

*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 VARCHAR(19).

The result is one of the following values:

DEFINITION: The object is included in replication. Only the object definition is replicated.; The object's current replication state is ACTIVE or Db2® Mirror has not completed its initial configuration.
DEFINITION-BLOCKED: The object is included in replication. Only the object definition is replicated.; The object's current replication state is BLOCKED.
DEFINITION-TRACKING: The object is included in replication. Only the object definition is replicated.; The object's current replication state is TRACKING.
EXCLUDE: The object is excluded from replication.
INCLUDE: The object is included in replication. Both the object definition and the object data are replicated.; The object's current replication state is ACTIVE or Db2 Mirror has not completed its initial configuration.
INCLUDE-BLOCKED: The object is included in replication. Both the object definition and the object data are replicated.; The object's current replication state is BLOCKED.
INCLUDE-TRACKING: The object is included in replication. Both the object definition and the object data are replicated.; The object's current replication state is TRACKING.
INELIGIBLE: The object is not eligible to be included in replication. Either the object-type or an attribute of the object identified by iasp-name, library-name, object-type, and object-name makes it ineligible.

Examples

Check the replication inclusion state for library APPLIB1. This checks the inclusion state for the library but not for any of the objects in the library.

VALUES QSYS2.CHECK_REPLICATION_CRITERIA(IASP_NAME    => '*SYSBAS',
                                        LIBRARY_NAME => 'QSYS',
                                        OBJECT_TYPE  => '*LIB', 
                                        OBJECT_NAME  => 'APPLIB1');

Check the replication inclusion state for file MYTABLE in library APPLIB1.

VALUES QSYS2.CHECK_REPLICATION_CRITERIA(IASP_NAME    => '*SYSBAS',
                                        LIBRARY_NAME => 'APPLIB1',
                                        OBJECT_TYPE  => '*FILE', 
                                        OBJECT_NAME  => 'MYTABLE');

Check if any of the pending replication criteria rules that are part of MYGROUP change the inclusion state for file MYTABLE in library APPLIB1.

VALUES QSYS2.CHECK_REPLICATION_CRITERIA(IASP_NAME    => '*SYSBAS',
                                        LIBRARY_NAME => 'APPLIB1',
                                        OBJECT_TYPE  => '*FILE',  
                                        OBJECT_NAME  => 'MYTABLE',
                                        APPLY_STATE  => 'PENDING',
                                        APPLY_LABEL  => 'MYGROUP');

Check the replication inclusion state for all objects in library APPLIB1.

WITH OBJECTS AS (SELECT OBJNAME AS OBJECT_NAME,
                        OBJTYPE AS OBJECT_TYPE,
                        OBJLIB  AS OBJECT_LIBRARY,
                        IASP_NAME 
       FROM TABLE(QSYS2.OBJECT_STATISTICS('APPLIB1', '*ALL', '*ALLSIMPLE')) X)
SELECT IASP_NAME,
       OBJECT_LIBRARY,
       OBJECT_TYPE,
       OBJECT_NAME,
       QSYS2.CHECK_REPLICATION_CRITERIA(
                     IASP_NAME    => IASP_NAME,
                     LIBRARY_NAME => OBJECT_LIBRARY,
                     OBJECT_TYPE  => OBJECT_TYPE,
                     OBJECT_NAME  => OBJECT_NAME) AS INCLUSION_STATE
    FROM OBJECTS  
    ORDER BY OBJECT_TYPE,
             OBJECT_NAME;

For library APPLIB1, find all the objects that would change their replication inclusion state if the set of pending rules identified by MYGROUP were to be added to production. This query finds all the objects in the library using the QSYS2.OBJECT_STATISTICS table function. For each object, the QSYS2.CHECK_REPLICATION_CRITERIA scalar function is invoked twice to return the current inclusion state and the inclusion state that would result from applying the rules with the MYGROUP apply label. These two states are compared so that only objects where the value would change are returned.

WITH OBJECTS AS 
      (SELECT OBJNAME AS OBJECT_NAME,
              OBJTYPE AS OBJECT_TYPE,
              OBJLIB AS OBJECT_LIBRARY,
              IASP_NAME,
              QSYS2.CHECK_REPLICATION_CRITERIA(
                         IASP_NAME => IASP_NAME,
                         LIBRARY_NAME => OBJLIB,
                         OBJECT_TYPE => OBJTYPE,
                         OBJECT_NAME => OBJNAME) AS CURRENT_INCLUSION_STATE, 
              QSYS2.CHECK_REPLICATION_CRITERIA(
                         IASP_NAME => IASP_NAME,
                         LIBRARY_NAME => OBJLIB,
                         OBJECT_TYPE => OBJTYPE,
                         OBJECT_NAME => OBJNAME,
                         APPLY_STATE => 'PENDING',
                         APPLY_LABEL => 'MYGROUP') AS PENDING_INCLUSION_STATE
       FROM TABLE(QSYS2.OBJECT_STATISTICS('APPLIB1', '*ALL', '*ALLSIMPLE')) X)
SELECT IASP_NAME,
       OBJECT_LIBRARY,
       OBJECT_TYPE,
       OBJECT_NAME,
       CURRENT_INCLUSION_STATE,
       PENDING_INCLUSION_STATE
    FROM OBJECTS
    WHERE CURRENT_INCLUSION_STATE <> PENDING_INCLUSION_STATE
    ORDER BY PENDING_INCLUSION_STATE,
  	    OBJECT_TYPE,
  	    OBJECT_NAME;