Skip Headers
Oracle® Streams Concepts and Administration
11g Release 1 (11.1)

B28321-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

12 Configuring Implicit Apply

An Oracle Streams apply process dequeues logical change records (LCRs) and user messages 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:

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 create 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 a number of 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. Therefore, if a single apply process applies captured LCRs, then it cannot apply persistent LCRs or persistent user messages. However, a single apply process can apply both persistent LCRs and persistent user messages.

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

  • 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.

  • To create an apply process, a user must be granted DBA role.

  • If Oracle Database Vault is installed, then the user who creates the apply process must be granted the BECOME USER system privilege. Granting this privilege to the user is not required if Oracle Database Vault is not installed. You can revoke the BECOME USER system privilege from the user after the apply process is created, if necessary.

See Also:

Creating an Apply Process Using the DBMS_STREAMS_ADM Package

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

Creating an Apply Process for Captured LCRs

The following example runs the ADD_SCHEMA_RULES procedure in the DBMS_STREAMS_ADM package to create an apply process that applies captured LCRs:

BEGIN
  DBMS_STREAMS_ADM.ADD_SCHEMA_RULES(
    schema_name        => 'hr',
    streams_type       => 'apply',
    streams_name       => 'strm01_apply',
    queue_name         => '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 an existing queue named streams_queue.

  • 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 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). 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 messages 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 for User Messages

The following example runs the ADD_MESSAGE_RULE procedure in the DBMS_STREAMS_ADM package to create an apply process that dequeues and processes user messages in a persistent queue:

BEGIN
  DBMS_STREAMS_ADM.ADD_MESSAGE_RULE(
    message_type       => 'oe.order_typ',
    rule_condition     => ':msg.order_status = 1',
    streams_type       => 'apply',
    streams_name       => 'strm02_apply',
    queue_name         => 'strm02_queue',
    inclusion_rule     => TRUE);
END;
/

Running this procedure performs the following actions:

  • Creates an apply process named strm02_apply that dequeues user messages of oe.order_typ type and sends them to the message handler for the apply process. The apply process is created only if it does not already exist.

  • Associates the apply process with an existing queue named strm02_queue.

  • 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 name is system generated, and the rule set does not use an evaluation context.

  • Creates one rule that evaluates to TRUE for user messages that satisfy the rule condition. The rule uses a system-created evaluation context for the message type. The rule name and the evaluation context name are 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). Redo entries generated by the apply process, including any redo entries generated by a message handler, have a tag with this value.

Note:

You can use the ALTER_APPLY procedure in the DBMS_APPLY_ADM package to specify a message handler for an apply process.

Creating an Apply Process Using the DBMS_APPLY_ADM Package

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

See Also:

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 LCRs:

BEGIN
  DBMS_APPLY_ADM.CREATE_APPLY(
    queue_name             => 'strm03_queue',
    apply_name             => 'strm03_apply',
    rule_set_name          => 'strmadmin.strm03_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 strm03_apply. An apply process with the same name must not exist.

  • Associates the apply process with an existing queue named strm03_queue.

  • Associates the apply process with an existing rule set named strm03_rule_set. 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. The user who runs the CREATE_APPLY procedure must have EXECUTE privilege on the history_ddl PL/SQL procedure. An example in the Oracle Streams Replication Administrator's Guide creates this procedure.

  • Specifies that the user who applies the 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'.

  • Specifies that the apply process applies captured LCRs, and not persistent LCRs or persistent user messages. Therefore, if an LCR that was constructed by a user application, not by a capture process, is staged in the queue for the apply process, then this apply process does not apply 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 messages 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 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 LCRs:

BEGIN
  DBMS_APPLY_ADM.CREATE_APPLY(
    queue_name             => 'strm04_queue',
    apply_name             => 'strm04_apply',
    rule_set_name          => 'strmadmin.strm04_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 strm04_apply. An apply process with the same name must not exist.

  • Associates the apply process with an existing queue named strm04_queue.

  • Associates the apply process with an existing rule set named strm04_rule_set. 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.

  • 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 queue.

  • Specifies that the apply process does not use a precommit handler.

  • Specifies that the apply process does not use a negative rule set.

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.

Creating an Apply Process for Persistent User Messages 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 user messages:

BEGIN
  DBMS_APPLY_ADM.CREATE_APPLY(
    queue_name             => 'strm05_queue',
    apply_name             => 'strm05_apply',
    rule_set_name          => 'strmadmin.strm05_rule_set',
    message_handler        => 'strmadmin.mes_handler',
    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 strm05_apply. An apply process with the same name must not exist.

  • Associates the apply process with an existing queue named strm05_queue.

  • Associates the apply process with an existing rule set named strm05_rule_set. This rule set is the positive rule set for the apply process.

  • Specifies that the message handler is the mes_handler PL/SQL procedure in the strmadmin schema. The user who runs the CREATE_APPLY procedure must have EXECUTE privilege on the mes_handler PL/SQL procedure.

  • 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.

  • 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 queue.

  • Specifies that the apply process does not use a precommit handler.

  • Specifies that the apply process does not use a negative rule set.