ADD_REPLICATION_CRITERIA procedure

The ADD_REPLICATION_CRITERIA procedure registers a replication criteria rule in the Replication Criteria List (RCL). The rules are used to determine which objects are included or excluded from replication through Db2® Mirror.

A new replication criteria rule will be added to the RCL when apply is set to ACTIVE and the combination of the iasp-name, library-name, object-type, and object-name values on this procedure invocation do not match a rule already registered in the RCL. If an existing replication criteria rule is found that exactly matches the input values, an error is returned.

A replication criteria rule is defined in either an active or pending state.

When apply is set to PENDING, the addition of a rule has no impact on active replication. The pending state provides the ability to make multiple changes to the replication rules and evaluate the impact of those rules before committing them into production. You can use the apply-label parameter to group pending rules together.

When apply is set to ACTIVE and there are pending rules that match the apply-label for the same iasp-name, both the new rule and any pending rules for the apply-label are committed.

When a rule with an INCLUSION_STATE value of INCLUDE is added to the RCL with apply set to ACTIVE, the rules are evaluated to determine whether any objects are now subject to replication. These identified objects are checked to ensure the replication action can be applied to the object without encountering an error and preventing the rule from being added. For more information about the cause of the failure, use the QSYS2.EVALUATE_PENDING_REPLICATION_CRITERIA table function.

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 *ADD authority on QSYS2/MIRROR_RCL

The schema is QSYS2.

inclusion-state

A character or graphic string expression that indicates the replication action for objects that best match this replication criteria rule.

DEFINITION: The object has only its definition included in replication. This option can only be specified when object-name is specified and object-type is *FILE, *DTAQ, or *LIB.
EXCLUDE: Objects identified by this rule are excluded from replication.
INCLUDE: Objects identified by this rule are replicated.

iasp-name

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

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

library-name

A character or graphic string expression that identifies the library name to associate with the replication criteria rule.

object-type

A character or graphic string expression that identifies the object type to associate with the replication criteria rule.

Supported types are:

*DTAARA: Data area
*DTAQ: Data queue
*ENVVAR: System-level environment variable. library-name must be QSYS.
*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. library-name must be QSYS.
*USRIDX: User index
*USRSPC: User space

If object-type is not specified, this replication criteria rule will be considered for all eligible object types that match iasp-name and library-name.

object-name

A character or graphic string expression that identifies the system name of the object, system-level environment variable, or system value to associate with the replication criteria rule. When object-name is specified, object-type must also be specified.

If object-name is not specified, this replication criteria rule will be considered for all eligible objects that match the iasp-name, library-name, and object-type.

apply

A character or graphic string expression that indicates whether this replication criteria rule should be applied to the RCL to implement the rule or placed in a pending state.

ACTIVE: This replication criteria rule as well as all pending rules with the same apply-label will be applied. This is the default.
PENDING: This replication criteria rule will be placed into a pending state identified by the apply-label.

apply-label

A character or graphic string expression that identifies a label to associate with this replication criteria rule. It can be up to 26 characters long. The name cannot contain the blank or equal sign (=) characters.

The apply-label is used to label a pending replication criteria rule so that it can be grouped with other pending rules with the same apply-label and iasp-name. This set of rules can be applied to the RCL in one operation when a rule with this apply-label and an apply value of ACTIVE is processed or by using the PROCESS_PENDING_REPLICATION_CRITERIA procedure.

An apply-label can group pending rules together that are generated from calls to the ADD_REPLICATION_CRITERIA and REMOVE_REPLICATION_CRITERIA procedures.

*GENERATE: An apply-label will be generated by the system. 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: The apply-label value that identifies this rule as a pending replication criteria rule or that identifies the set of existing rules to commit.

Examples

Change the inclusion state on an existing rule for LIB1/PGM1 type *PGM from EXCLUDE to INCLUDE. To do this requires two steps. The existing replication criteria rule needs to be removed and the new rule needs to be added. The order the rules are defined does not matter as long as the first rule specifies APPLY => 'PENDING' and the second rule specifies APPLY => 'ACTIVE'.

CALL QSYS2.REMOVE_REPLICATION_CRITERIA(IASP_NAME       => '*SYSBAS', 
                                       LIBRARY_NAME    => 'LIB1',
                                       OBJECT_TYPE     => '*PGM',
                                       OBJECT_NAME     => 'PGM1',
                                       APPLY           => 'PENDING',
                                       APPLY_LABEL     => 'PGM1');

CALL QSYS2.ADD_REPLICATION_CRITERIA(INCLUSION_STATE => 'INCLUDE',
                                    IASP_NAME       => '*SYSBAS', 
                                    LIBRARY_NAME    => 'LIB1',
                                    OBJECT_TYPE     => '*PGM',
                                    OBJECT_NAME     => 'PGM1',
                                    APPLY           => 'ACTIVE',
                                    APPLY_LABEL     => 'PGM1');

Add a pending replication criteria rule to the RCL that will include all objects in library APPLIB1 within the *SYSBAS name space. A system generated apply-label will be assigned.
```
CALL QSYS2.ADD_REPLICATION_CRITERIA(INCLUSION_STATE => 'INCLUDE',
                                    IASP_NAME       => '*SYSBAS', 
                                    LIBRARY_NAME    => 'APPLIB1',
                                    APPLY           => 'PENDING',
                                    APPLY_LABEL     => '*GENERATE');
```
Next, add a rule to exclude replication for a specific data queue. This rule will exclude replication of the data queue even though everything else in the library has been set to INCLUDE. Since this rule specifies APPLY => 'ACTIVE', both this rule and the previous rule for the library will be applied at the same time. By promoting both rules into use at the same time, the data queue will not be replicated.
```
CALL QSYS2.ADD_REPLICATION_CRITERIA(INCLUSION_STATE => 'EXCLUDE',
                                    IASP_NAME       => '*SYSBAS', 
                                    LIBRARY_NAME    => 'APPLIB1', 
                                    OBJECT_TYPE     => '*DTAQ', 
                                    OBJECT_NAME     => 'MYDTAQ',
                                    APPLY           => 'ACTIVE',
                                    APPLY_LABEL     => '*GENERATE');
```
If the add request for the library used APPLY => 'ACTIVE', the data queue would be replicated to the secondary node. The second add request to exclude the data queue would prevent future replication for the data queue, but the replicated data queue would remain on the secondary node.

Add an active replication criteria rule to the RCL that will be used to define the replication behavior for objects in library IASPLIB1 within the ASP34 name space that have no object specific rule.

CALL QSYS2.ADD_REPLICATION_CRITERIA(INCLUSION_STATE => 'INCLUDE',
                                    IASP_NAME => 'ASP34',
                                    LIBRARY_NAME => 'IASPLIB1');

This is equivalent to the following fully qualified procedure call.

CALL QSYS2.ADD_REPLICATION_CRITERIA(INCLUSION_STATE => 'INCLUDE', 
                                    IASP_NAME => 'ASP34',
                                    LIBRARY_NAME => 'QSYS',
                                    OBJECT_TYPE => '*LIB',
                                    OBJECT_NAME => 'IASPLIB1');

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