REMOVE_REPLICATION_CRITERIA procedure

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

The replication criteria rule will be removed from the RCL when either of the following sets of parameters on this procedure invocation exactly matches a rule that exists in the RCL.

the combination of iasp-name, library-name, object-type, and object-name
the combination of iasp-name and rule-identifier

If no replication criteria rule 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 removal 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 an active replication criteria rule with an INCLUSION_STATE value of EXCLUDE is removed from the RCL with apply set to ACTIVE, the remaining 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 removed. 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 *DLT 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 rule. 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 used to locate the replication criteria rule. When library-name is specified, rule-identifier cannot be specified. Either library-name or rule-identifier must be specified.

object-type

A character or graphic string expression that identifies the object type used to locate the replication criteria rule. When object-type is specified, library-name must also be specified.

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, a matching replication criteria rule will be located using the values of 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 used to locate the replication criteria rule. When object-name is specified, object-type must also be specified.

If object-name is not specified, a matching replication criteria rule will be located using the values of iasp-name, library-name, and object-type.

rule-identifier

A numeric value that identifies a specific replication criteria rule to remove. The value is defined in the RULE_IDENTIFIER column of the REPLICATION_CRITERIA_INFO view. When rule-identifier is specified, library-name, object-type, and object-name cannot be specified. Either library-name or rule-identifier must be specified.

When specifying rule-identifier:

If apply is set to ACTIVE, the matching replication criteria rule will be removed immediately from the RCL. The rule can be in an active or a pending state.
If apply is set to PENDING, the matching active replication criteria rule will be used to define a new PENDING REMOVE rule.

apply

A character or graphic string expression that indicates whether this replication criteria rule should be removed from the RCL immediately 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 for the same 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

Remove a replication criteria rule from the RCL that was used to define the replication behavior for objects in library APPLIB1 that have no object specific rule.

CALL QSYS2.REMOVE_REPLICATION_CRITERIA(IASP_NAME => '*SYSBAS',
                                       LIBRARY_NAME => 'APPLIB1');

This is equivalent to the following procedure call.

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

Remove a fully qualified replication criteria rule from the RCL.

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

Update the RCL to initiate replication against all tables in library APPLIB1. Previously, one fully qualified table in APPLIB1 was being actively replicated. This individual replication rule is no longer needed, so it should be removed.

Performing the changes in the following way ensures that the fully qualified table remains replicated, avoiding unnecessary object resynchronization. This process makes use of the apply and apply-label parameters on both the remove and add operations. The order in which these rules are defined is not important. They will both be processed when APPLY => 'ACTIVE' is requested using the common apply-label.

CALL QSYS2.ADD_REPLICATION_CRITERIA(INCLUSION_STATE => 'INCLUDE',
                                    IASP_NAME => '*SYSBAS', 
                                    LIBRARY_NAME=> 'APPLIB1', 
                                    OBJECT_TYPE => '*FILE', 
                                    APPLY => 'PENDING',
                                    APPLY_LABEL => 'GROUP1');

CALL QSYS2.REMOVE_REPLICATION_CRITERIA(IASP_NAME => '*SYSBAS', 
                                       LIBRARY_NAME => 'APPLIB1', 
                                       OBJECT_NAME => 'MYTABLE',
                                       OBJECT_TYPE => '*FILE',
                                       APPLY => 'ACTIVE',
                                       APPLY_LABEL => 'GROUP1');

Remove a PENDING replication criteria rule from the RCL. The replication criteria rule as defined in REPLICATION_CRITERIA_INFO has a RULE_IDENTIFIER value of 168 and an APPLY_STATE value of PENDING ADD.
An existing replication criteria rule with a value of PENDING ADD or PENDING REMOVE in its APPLY_STATE column can only be removed by using the rule-identifier parameter for that pending rule and an apply parameter value of ACTIVE.
```
CALL QSYS2.REMOVE_REPLICATION_CRITERIA(IASP_NAME => '*SYSBAS', 
                                       RULE_IDENTIFIER => 168, 
                                       APPLY => 'ACTIVE',
                                       APPLY_LABEL => 'CLEAR_RULE');
```
This procedure uses a unique apply-label rather than using *GENERATE to prevent any other pending rule changes for this job from being affected.
Remove the specific replication criteria rules from the RCL for all output queues in libraries APPLIB1 and APPLIB2. Suppose that the rules that enable replication of the output queues are identified by RULE_IDENTIFIER values of 211 and 213 within the RCL.
Both methods of identifying existing replication criteria rules to be placed into a PENDING state are illustrated in this example. The methods are equivalent and can be used interchangeably.
The first replication criteria rule for library APPLIB1 is identified through its rule-identifier value.
```
CALL QSYS2.REMOVE_REPLICATION_CRITERIA(IASP_NAME => '*SYSBAS', 
                                       RULE_IDENTIFIER => 211, 
                                       APPLY => 'PENDING', 
                                       APPLY_LABEL => '*GENERATE'); 
```
The second replication criteria rule is identified through its library-name and object-type parameters. A generated apply-label value is used to identify both PENDING changes.
```
CALL QSYS2.REMOVE_REPLICATION_CRITERIA(IASP_NAME => '*SYSBAS', 
                                       LIBRARY_NAME => 'APPLIB2', 
                                       OBJECT_TYPE => '*OUTQ', 
                                       APPLY => 'PENDING', 
                                       APPLY_LABEL => '*GENERATE'); 
```
These changes can be applied to the RCL by using the PROCESS_PENDING_REPLICATION_CRITERIA procedure specifying the generated apply-label value.
```
CALL QSYS2.PROCESS_PENDING_REPLICATION_CRITERIA(IASP_NAME => '*SYSBAS', 
                                                APPLY_ACTION => 'COMMIT', 
                                                APPLY_LABEL => '*GENERATE');
```

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