7 Configuring Implicit Apply

In a replication environment, Oracle Streams apply process dequeues logical change records (LCRs) from a specific queue and either applies each one directly or passes it as a parameter to a user-defined procedure called an apply handler.

The following topics describe configuring implicit apply:

Overview of Apply Process Creation
Creating an Apply Process for Captured LCRs Using DBMS_STREAMS_ADM
Creating an Apply Process Using DBMS_APPLY_ADM

Each task described in this chapter should be completed by an Oracle Streams administrator that has been granted the appropriate privileges, unless specified otherwise.

See Also:

Overview of Apply Process Creation

You can use any of the following procedures to configure an apply process:

Each of the procedures in the DBMS_STREAMS_ADM package creates an apply process with the specified name if it does not already exist, creates either a positive rule set or negative rule set for the apply process if the apply process does not have such a rule set, and can add table rules, schema rules, global rules, or a message rule to the rule set.

The CREATE_APPLY procedure in the DBMS_APPLY_ADM package creates an apply process, but does not create a rule set or rules for the apply process. However, the CREATE_APPLY procedure enables you to specify an existing rule set to associate with the apply process, either as a positive or a negative rule set, and several other options, such as apply handlers, an apply user, an apply tag, and whether to dequeue messages from a buffered queue or a persistent queue.

A single apply process must either dequeue messages from a buffered queue or a persistent queue. Logical change records that were captured by a capture process are called captured LCRs, and they are always in buffered queues. Therefore, if a single apply process applies LCRs that were captured by a capture process, then it cannot apply persistent LCRs or persistent user messages.

Alternatively, LCRs that were captured by a synchronous capture are persistent LCRs, and they are always in persistent queues. Therefore, if a single apply process applies LCRs that were captured by a synchronous capture, then it cannot apply LCRs captured by a capture process. However, a single apply process can apply both persistent LCRs and persistent user messages because both types of messages are staged in a persistent queue.

The examples in this chapter create apply processes that apply captured LCRs, persistent LCRs, and persistent user messages. Before you create an apply process, create an ANYDATA queue to associate with the apply process, if one does not exist.

Note:

You can configure an entire Oracle Streams environment, including apply processes, using procedures in the DBMS_STREAMS_ADM package or Oracle Enterprise Manager. See Chapter 2, "Simple Oracle Streams Replication Configuration".
Depending on the configuration of the apply process you create, supplemental logging might be required at the source database on columns in the tables for which an apply process applies changes. See "Specifying Supplemental Logging".
Oracle Streams Concepts and Administration for more information about the captured LCRs and persistent LCRs

Preparing to Create an Apply Process

The following tasks must be completed before you create an apply:

Complete the following tasks in "Tasks to Complete Before Configuring Oracle Streams Replication".
Create an ANYDATA queue to associate with the apply process, if one does not exist. See "Creating an ANYDATA Queue" for instructions. The examples in this chapter assume that the queue used by the apply process is strmadmin.streams_queue. Create the queue on the same database that will run the apply process.

Creating an Apply Process for Captured LCRs Using DBMS_STREAMS_ADM

The following example runs the ADD_SCHEMA_RULES procedure in the DBMS_STREAMS_ADM package to create an apply process that applies captured logical change records (LCRs). This apply process can apply LCRs that were captured by a capture process.

Complete the following steps:

Complete the tasks in "Preparing to Create an Apply Process".
In SQL*Plus, connect to the database that will run the apply process as the Oracle Streams administrator.

See Oracle Database Administrator's Guide for instructions about connecting to a database in SQL*Plus.
Create the apply process:
```
BEGIN
  DBMS_STREAMS_ADM.ADD_SCHEMA_RULES(
    schema_name        => 'hr',
    streams_type       => 'apply',
    streams_name       => 'strm01_apply',
    queue_name         => 'strmadmin.streams_queue',
    include_dml        => TRUE,
    include_ddl        => FALSE,
    include_tagged_lcr => FALSE,
    source_database    => 'dbs1.example.com',
    inclusion_rule     => TRUE);
END;
/
```
Running this procedure performs the following actions:
- Creates an apply process named strm01_apply that applies captured LCRs to the local database. The apply process is created only if it does not already exist.
- Associates the apply process with the existing queue strmadmin.streams_queue. This queue must exist.
- Creates a positive rule set and associates it with the apply process, if the apply process does not have a positive rule set, because the inclusion_rule parameter is set to TRUE. The rule set uses the SYS.STREAMS$_EVALUATION_CONTEXT evaluation context. The rule set name is system generated.
- Creates one rule that evaluates to TRUE for row LCRs that contain the results of data manipulation language (DML) changes to database objects in the hr schema. The rule name is system generated.
- Adds the rule to the positive rule set associated with the apply process because the inclusion_rule parameter is set to TRUE.
- Sets the apply_tag for the apply process to a value that is the hexadecimal equivalent of '00' (double zero). This is the default apply tag value. Redo entries generated by the apply process have a tag with this value.
- Specifies that the apply process applies a row LCR only if it has a NULL tag, because the include_tagged_lcr parameter is set to FALSE. This behavior is accomplished through the system-created rule for the apply process.
- Specifies that the LCRs applied by the apply process originate at the dbs1.example.com source database. The rules in the apply process rule sets determine which LCRs are dequeued by the apply process. If the apply process dequeues an LCR with a source database other than dbs1.example.com, then an error is raised.

Creating an Apply Process Using DBMS_APPLY_ADM

This section contains the following examples that create an apply process using the DBMS_APPLY_ADM package:

Creating an Apply Process for Captured LCRs with DBMS_APPLY_ADM
Creating an Apply Process for Persistent LCRs with DBMS_APPLY_ADM

See Also:

"Change Apply in an Oracle to Non-Oracle Environment" for information about configuring an apply process to apply messages to a non-Oracle database using the apply_database_link parameter
Oracle Streams Concepts and Administration

Creating an Apply Process for Captured LCRs with DBMS_APPLY_ADM

The following example runs the CREATE_APPLY procedure in the DBMS_APPLY_ADM package to create an apply process that applies captured logical change records (LCRs). This apply process can apply LCRs that were captured by a capture process.

Complete the following steps:

Complete the tasks in "Preparing to Create an Apply Process".
In SQL*Plus, connect to the database that will run the apply process as the Oracle Streams administrator.

Ensure that the Oracle Streams administrator is granted DBA role. DBA role is required because this example sets the apply user to a user other than the Oracle Streams administrator.

See Oracle Database Administrator's Guide for instructions about connecting to a database in SQL*Plus.
Create the rule set that will be used by the apply process if it does not exist. In this example, assume that the rule set is strmadmin.strm02_rule_set. Optionally, you can also add rules to the rule set. See Oracle Streams Concepts and Administration for instructions.
Create any apply handlers that will be used by the apply process if they do not exist. In this example, assume that the DDL handler is the strmadmin.history_ddl procedure. An example in the Oracle Streams Concepts and Administration creates this procedure.
Create the apply process:
```
BEGIN
  DBMS_APPLY_ADM.CREATE_APPLY(
    queue_name             => 'strmadmin.streams_queue',
    apply_name             => 'strm02_apply',
    rule_set_name          => 'strmadmin.strm02_rule_set',
    message_handler        => NULL,     
    ddl_handler            => 'strmadmin.history_ddl',
    apply_user             => 'hr',
    apply_database_link    => NULL,
    apply_tag              => HEXTORAW('5'),
    apply_captured         => TRUE,
    precommit_handler      => NULL,
    negative_rule_set_name => NULL,
    source_database        => 'dbs1.example.com');
END;
/
```
Running this procedure performs the following actions:
- Creates an apply process named strm02_apply. An apply process with the same name must not exist.
- Associates the apply process with the queue strmadmin.streams_queue. This queue must exist.
- Associates the apply process with the rule set strmadmin.strm02_rule_set. This rule set must exist. This rule set is the positive rule set for the apply process.
- Specifies that the apply process does not use a message handler.
- Specifies that the DDL handler is the history_ddl PL/SQL procedure in the strmadmin schema. This procedure must exist, and the user who runs the CREATE_APPLY procedure must have EXECUTE privilege on the history_ddl PL/SQL procedure.
- Specifies that the user who applies changes is hr, and not the user who is running the CREATE_APPLY procedure (the Oracle Streams administrator).
- Specifies that the apply process applies changes to the local database because the apply_database_link parameter is set to NULL.
- Specifies that each redo entry generated by the apply process has a tag that is the hexadecimal equivalent of '5'. See Chapter 10, "Oracle Streams Tags" for more information about tags.
- Specifies that the apply process applies captured LCRs, not persistent LCRs or persistent user messages. Therefore, if an LCR that was constructed by a synchronous capture or a user application, not by a capture process, and is staged in the queue for the apply process, then this apply process does not dequeue the LCR.
- Specifies that the apply process does not use a precommit handler.
- Specifies that the apply process does not use a negative rule set.
- Specifies that the LCRs applied by the apply process originate at the dbs1.example.com source database. The rules in the apply process rule sets determine which LCRs are dequeued by the apply process. If the apply process dequeues an LCR with a source database other than dbs1.example.com, then an error is raised.

After creating the apply process, run the ADD_TABLE_RULES or ADD_SUBSET_RULES procedure to add rules to the apply process rule set. These rules direct the apply process to apply LCRs for the specified tables.

See Also:

Oracle Streams Concepts and Administration for more information about rules

Creating an Apply Process for Persistent LCRs with DBMS_APPLY_ADM

The following example runs the CREATE_APPLY procedure in the DBMS_APPLY_ADM package to create an apply process that applies persistent logical change records (LCRs). This apply process can apply LCRs that were captured by a synchronous capture or constructed by an application.

Complete the following steps:

Complete the tasks in "Preparing to Create an Apply Process".
In SQL*Plus, connect to the database that will run the apply process as the Oracle Streams administrator.

See Oracle Database Administrator's Guide for instructions about connecting to a database in SQL*Plus.
Create the rule set that will be used by the apply process if it does not exist. In this example, assume that the rule set is strmadmin.strm03_rule_set. Optionally, you can also add rules to the rule set. See Oracle Streams Concepts and Administration for instructions.
Create any apply handlers that will be used by the apply process if they do not exist. The apply process created in this example does not used apply handlers.
Create the apply process:
```
BEGIN
  DBMS_APPLY_ADM.CREATE_APPLY(
    queue_name             => 'strmadmin.streams_queue',
    apply_name             => 'strm03_apply',
    rule_set_name          => 'strmadmin.strm03_rule_set',
    message_handler        => NULL,
    ddl_handler            => NULL,
    apply_user             => NULL,
    apply_database_link    => NULL,
    apply_tag              => NULL,
    apply_captured         => FALSE,
    precommit_handler      => NULL,
    negative_rule_set_name => NULL);
END;
/
```
Running this procedure performs the following actions:
- Creates an apply process named strm03_apply. An apply process with the same name must not exist.
- Associates the apply process with the queue named strmadmin.streams_queue. This queue must exist.
- Associates the apply process with the rule set strmadmin.strm03_rule_set. This rule set must exist. This rule set is the positive rule set for the apply process.
- Specifies that the apply process does not use a message handler.
- Specifies that the apply process does not use a DDL handler.
- Specifies that the user who applies the changes is the user who runs the CREATE_APPLY procedure, because the apply_user parameter is NULL.
- Specifies that the apply process applies changes to the local database, because the apply_database_link parameter is set to NULL.
- Specifies that each redo entry generated by the apply process has a NULL tag. See Chapter 10, "Oracle Streams Tags" for more information about tags.
- Specifies that the apply process does not apply captured LCRs. Therefore, the apply process can apply persistent LCRs or persistent user messages that are in the persistent queue portion of the apply process's queue.
- Specifies that the apply process does not use a precommit handler.
- Specifies that the apply process does not use a negative rule set.

See Also:

Oracle Streams Concepts and Administration for more information about rules