4 Streams Apply Process

This chapter explains the concepts and architecture of the Streams apply process.

This chapter contains these topics:

See Also:

Chapter 13, "Managing an Apply Process"

Introduction to the Apply Process

An apply process is an optional Oracle background process that dequeues messages from a specific queue. These messages can be logical change records (LCRs) or user messages. An apply process either applies each message directly or passes it as a parameter to an apply handler. An apply handler is a user-defined procedure used by an apply process for customized processing of messages. The LCRs dequeued by an apply process contain the results of data manipulation language (DML) changes or data definition language (DDL) changes that an apply process can apply to database objects in a destination database. A user-enqueued message dequeued by an apply process is of type ANYDATA and can contain any message, including an LCR or a user message.

Note:

An apply process can only dequeue messages from an ANYDATA queue, not a typed queue.

Apply Process Rules

An apply process applies changes based on rules that you define. Each rule specifies the database objects and types of changes for which the rule evaluates to TRUE. You can place these rules in the positive rule set or negative rule set for the apply process.

If a rule evaluates to TRUE for a change, and the rule is in the positive rule set for an apply process, then the apply process applies the change. If a rule evaluates to TRUE for a change, and the rule is in the negative rule set for an apply process, then the apply process discards the change. If an apply process has both a positive and a negative rule set, then the negative rule set is always evaluated first.

You can specify apply process rules for LCRs at the following levels:

  • A table rule applies or discards either row changes resulting from DML changes or DDL changes to a particular table. Subset rules are table rules that include a subset of the row changes to a particular table.

  • A schema rule applies or discards either row changes resulting from DML changes or DDL changes to the database objects in a particular schema.

  • A global rule applies or discards either all row changes resulting from DML changes or all DDL changes in the queue associated with an apply process.

For non-LCR messages, you can create rules to control apply process behavior for specific types of messages.

See Also:

Message Processing with an Apply Process

An apply process is a flexible mechanism for processing the messages in a queue. You have options to consider when you configure one or more apply processes for your environment. The following sections discuss the types of messages that an apply process can apply and the ways in which it can apply them.

Processing Captured or User-Enqueued Messages with an Apply Process

A single apply process can dequeue either of the following types of messages:

  • Captured message: A message that was captured implicitly by a capture process. A captured message contains a logical change record (LCR).

  • User-enqueued message: A message that was enqueued explicitly by an application, a user, or an apply process. A user-enqueued message can contain either an LCR or a user message.

A single apply process cannot dequeue both captured and user-enqueued messages. If a queue at a destination database contains both captured and user-enqueued messages, then the destination database must have at least two apply processes to process the messages.

A single apply process can apply user-enqueued messages that originated at multiple databases. However, a single apply process can apply captured messages from only one source database, because processing these LCRs requires knowledge of the dependencies, meaningful transaction ordering, and transactional boundaries at the source database. For a captured message, the source database is the database where the change encapsulated in the LCR was generated in the redo log.

Captured messages from multiple databases can be sent to a single destination queue. However, if a single queue contains captured messages from multiple source databases, then there must be multiple apply processes retrieving these LCRs. Each of these apply processes should be configured to receive captured messages from exactly one source database using rules. Oracle recommends that you use a separate ANYDATA queue for captured messages from each source database.

Also, each apply process can apply captured messages from only one capture process. If multiple capture processes are running on a source database, and LCRs from more than one of these capture processes are applied at a destination database, then there must be one apply process to apply changes from each capture process. In such an environment, Oracle recommends that each ANYDATA queue used by a capture process, propagation, or apply process have captured messages from at most one capture process from a particular source database. A queue can contain LCRs from more than one capture process if each capture process is capturing changes that originated at a different source database.

See Also:

Message Processing Options for an Apply Process

Your options for message processing depend on whether or not the message received by an apply process is an LCR.

Figure 4-1 shows the message processing options for an apply process.

Figure 4-1 Apply Process Message Processing Options

Description of Figure 4-1 follows
Description of "Figure 4-1 Apply Process Message Processing Options"

The following sections describe these message processing options:

LCR Processing

You can configure an apply process to process each LCR that it dequeues in the following ways:

Apply the LCR Directly

If you use this option, then an apply process applies the LCR without running a user procedure. The apply process either successfully applies the change in the LCR or, if a conflict or an apply error is encountered, tries to resolve the error with a conflict handler or a user-specified procedure called an error handler.

If a conflict handler can resolve the conflict, then it either applies the LCR or it discards the change in the LCR. If the error handler can resolve the error, then it should apply the LCR, if appropriate. An error handler can resolve an error by modifying the LCR before applying it. If the conflict handler or error handler cannot resolve the error, then the apply process places the transaction, and all LCRs associated with the transaction, into the error queue.

Call a User Procedure to Process the LCR

If you use this option, then an apply process passes the LCR as a parameter to a user procedure for processing. The user procedure can process the LCR in a customized way.

A user procedure that processes row LCRs resulting from DML statements is called a DML handler. A user procedure that processes DDL LCRs resulting from DDL statements is called a DDL handler. An apply process can have many DML handlers but only one DDL handler, which processes all DDL LCRs dequeued by the apply process.

For each table associated with an apply process, you can set a separate DML handler to process each of the following types of operations in row LCRs:

  • INSERT

  • UPDATE

  • DELETE

  • LOB_UPDATE

For example, the hr.employees table can have one DML handler procedure to process INSERT operations and a different DML handler procedure to process UPDATE operations. Alternatively, the hr.employees table can use the same DML handler procedure for each type of operation.

A user procedure can be used for any customized processing of LCRs. For example, if you want each insert into a particular table at the source database to result in inserts into multiple tables at the destination database, then you can create a user procedure that processes INSERT operations on the table to accomplish this. Or, if you want to log DDL changes before applying them, then you can create a user procedure that processes DDL operations to accomplish this.

A DML handler should never commit and never roll back, except to a named savepoint that the user procedure has established. To execute a row LCR inside a DML handler, invoke the EXECUTE member procedure for the row LCR. To execute a DDL LCR inside a DDL handler, invoke the EXECUTE member procedure for the DDL LCR.

To set a DML handler, use the SET_DML_HANDLER procedure in the DBMS_APPLY_ADM package. You can either set a DML handler for a specific apply process, or you can set a DML handler to be a general DML handler that is used by all apply processes in the database. If a DML handler for an operation on a table is set for a specific apply process, and another DML handler is a general handler for the same operation on the same table, then the specific DML handler takes precedence over the general DML handler.

To associate a DDL handler with a particular apply process, use the ddl_handler parameter in the CREATE_APPLY or the ALTER_APPLY procedure in the DBMS_APPLY_ADM package.

You create an error handler in the same way that you create a DML handler, except that you set the error_handler parameter to true when you run the SET_DML_HANDLER procedure. An error handler is invoked only if an apply error results when an apply process tries to apply a row LCR for the specified operation on the specified table.

Typically, DML handlers and DDL handlers are used in Streams replication environments to perform custom processing of LCRs, but these handlers can be used in nonreplication environments as well. For example, such handlers can be used to record changes made to database objects without replicating these changes.

Attention:

Do not modify LONG, LONG RAW, or nonassembled LOB column data in an LCR with DML handlers, error handlers, or custom rule-based transformation functions. DML handlers and error handlers can modify LOB columns in row LCRs that have been constructed by LOB assembly.

Note:

When you run the SET_DML_HANDLER procedure, you specify the object for which the handler is used. This object does not need to exist at the destination database.

See Also:

Non-LCR User Message Processing

A user-enqueued message that does not contain an LCR is processed by the message handler specified for an apply process. A message handler is a user-defined procedure that can process user messages in a customized way for your environment.

The message handler offers advantages in any environment that has applications that need to update one or more remote databases or perform some other remote action. These applications can enqueue user messages into a queue at the local database, and Streams can propagate each user message to the appropriate queues at destination databases. If there are multiple destinations, then Streams provides the infrastructure for automatic propagation and processing of these messages at these destinations. If there is only one destination, then Streams still provides a layer between the application at the source database and the application at the destination database, so that, if the application at the remote database becomes unavailable, then the application at the source database can continue to function normally.

For example, a message handler can convert a user message into an electronic mail message. In this case, the user message can contain the attributes you would expect in an electronic mail message, such as from, to, subject, text_of_message, and so on. After converting a message into an electronic mail messages, the message handler can send it out through an electronic mail gateway.

You can specify a message handler for an apply process using the message_handler parameter in the CREATE_APPLY or the ALTER_APPLY procedure in the DBMS_APPLY_ADM package. A Streams apply process always assumes that a non-LCR message has no dependencies on any other messages in the queue. If parallelism is greater than 1 for an apply process that applies user-enqueued messages, then these messages can be dequeued by a message handler in any order. Therefore, if dependencies exist between these messages in your environment, then Oracle recommends that you set apply process parallelism to 1.

See Also:

"Managing the Message Handler for an Apply Process"

Audit Commit Information for Messages Using Precommit Handlers

You can use a precommit handler to audit commit directives for captured messages and transaction boundaries for user-enqueued messages. A precommit handler is a user-defined PL/SQL procedure that can receive the commit information for a transaction and process the commit information in any customized way. A precommit handler can work with a DML handler or a message handler.

For example, a handler can improve performance by caching data for the length of a transaction. This data can include cursors, temporary LOBs, data from a message, and so on. The precommit handler can release or execute the objects cached by the handler when a transaction completes.

A precommit handler executes when the apply process commits a transaction. You can use the commit_serialization apply process parameter to control the commit order for an apply process.

Commit Directives for Captured Messages

When you are using a capture process, and a user commits a transaction, the capture process captures an internal commit directive for the transaction if the transaction contains row LCRs that were captured. Once enqueued into a queue, these commit directives can be propagated to destination queues, along with the LCRs in a transaction. A precommit handler receives the commit SCN for these internal commit directives in the queue of an apply process before they are processed by the apply process.

Transaction Boundaries for User-Enqueued Messages

A user or application can enqueue messages into a queue and then issue a COMMIT statement to end the transaction. The enqueued messages are organized into a message group. Once enqueued into a queue, the messages in a message group can be propagated to other queues. When an apply process is configured to process user-enqueued messages, it generates a single transaction identifier and commit SCN for all the messages in a message group. Transaction identifiers and commit SCN values generated by an individual apply process have no relation to the source transaction, or to the values generated by any other apply process. A precommit handler configured for such an apply process receives the commit SCN supplied by the apply process.

See Also:

"Managing the Precommit Handler for an Apply Process"

Considerations for Apply Handlers

The following are considerations for using apply handlers:

  • DML handlers, DDL handlers, and message handlers can execute an LCR by calling the LCR's EXECUTE member procedure.

  • All applied DDL LCRs commit automatically. Therefore, if a DDL handler calls the EXECUTE member procedure of a DDL LCR, then a commit is performed automatically.

  • If necessary, an apply handler can set a Streams session tag.

  • An apply handler can call a Java stored procedure that is published (or wrapped) in a PL/SQL procedure.

  • If an apply process tries to invoke an apply handler that does not exist or is invalid, then the apply process aborts.

  • If an apply handler invokes a procedure or function in an Oracle-supplied package, then the user who runs the apply handler must have direct EXECUTE privilege on the package. It is not sufficient to grant this privilege through a role.

See Also:

Summary of Message Processing Options

Table 4-1 summarizes the message processing options available when you are using one or more of the apply handlers described in the previous sections. Apply handlers are optional for row LCRs and DDL LCRs because an apply process can apply these messages directly. However, a message handler is required for processing user messages. In addition, an apply process dequeues a message only if the message satisfies the rule sets for the apply process. In general, a message satisfies the rule sets for an apply process if no rules in the negative rule set evaluate to TRUE for the message, and at least one rule in the positive rule set evaluates to TRUE for the message.

Table 4-1 Summary of Message Processing Options

Apply Handler Type of Message Default Apply Process Behavior Scope of User Procedure

DML Handler or Error Handler

Row LCR

Execute DML

One operation on one table

DDL Handler

DDL LCR

Execute DDL

Entire apply process

Message Handler

User Message

Create error transaction (if no message handler exists)

Entire apply process

Precommit Handler

Commit directive for transactions that include row LCRs or user messages

Commit transaction

Entire apply process

In addition to the message processing options described in this section, you can use the SET_ENQUEUE_DESTINATION procedure in the DBMS_APPLY_ADM package to instruct an apply process to enqueue messages into a specified destination queue. Also, you can control message execution using the SET_EXECUTE procedure in the DBMS_APPLY_ADM package.

See Also:

Datatypes Applied

When applying row LCRs resulting from DML changes to tables, an apply process applies changes made to columns of the following datatypes:

  • VARCHAR2

  • NVARCHAR2

  • NUMBER

  • LONG

  • DATE

  • BINARY_FLOAT

  • BINARY_DOUBLE

  • TIMESTAMP

  • TIMESTAMP WITH TIME ZONE

  • TIMESTAMP WITH LOCAL TIME ZONE

  • INTERVAL YEAR TO MONTH

  • INTERVAL DAY TO SECOND

  • RAW

  • LONG RAW

  • CHAR

  • NCHAR

  • CLOB

  • NCLOB

  • BLOB

  • UROWID

An apply process does not apply row LCRs containing the results of DML changes in columns of the following datatypes: BFILE, ROWID, and user-defined type (including object types, REFs, varrays, nested tables, and Oracle-supplied types). Also, an apply process cannot apply changes to columns if the columns have been encrypted using transparent data encryption. An apply process raises an error if it attempts to apply a row LCR that contains information about a column of an unsupported datatype. Next, the apply process moves the transaction that includes the LCR into the error queue.

See Also:

Streams Apply Processes and RESTRICTED SESSION

When restricted session is enabled during system startup by issuing a STARTUP RESTRICT statement, apply processes do not start, even if they were running when the database shut down. When the restricted session is disabled, each apply process that was not stopped is started.

When restricted session is enabled in a running database by the SQL statement ALTER SYSTEM ENABLE RESTRICTED SESSION, it does not affect any running apply processes. These apply processes continue to run and apply messages. If a stopped apply process is started in a restricted session, then the apply process does not actually start until the restricted session is disabled.

Streams Apply Processes and Oracle Real Application Clusters

You can configure a Streams apply process to apply changes in an Oracle Real Application Clusters (RAC) environment. Each apply process is started and stopped on the owner instance for its ANYDATA queue, even if the start or stop procedure is run on a different instance.

If the owner instance for a queue table containing a queue used by an apply process becomes unavailable, then queue ownership is transferred automatically to another instance in the cluster. Also, an apply process will follow its queue to a different instance if the current owner instance becomes unavailable. The queue itself follows the rules for primary instance and secondary instance ownership. In addition, if the apply process was enabled when the owner instance became unavailable, then the apply process is restarted automatically on the new owner instance. If the apply process was disabled when the owner instance became unavailable, then the apply process remains disabled on the new owner instance.

The DBA_QUEUE_TABLES data dictionary view contains information about the owner instance for a queue table. Also, in a RAC environment, an apply coordinator process, its corresponding apply reader server, and all of its apply servers run on a single instance.

See Also:

Apply Process Architecture

You can create, alter, start, stop, and drop an apply process, and you can define apply process rules that control which messages an apply process dequeues from its queue. Messages are applied in the security domain of the apply user for an apply process. The apply user dequeues all messages that satisfy the apply process rule sets. The apply user can apply messages directly to database objects. In addition, the apply user runs all custom rule-based transformations specified by the rules in these rule sets. The apply user also runs user-defined apply handlers.

The apply user must have the necessary privileges to apply changes, including EXECUTE privilege on the rule sets used by the apply process, EXECUTE privilege on all custom rule-based transformation functions specified for rules in the positive rule set, EXECUTE privilege on any apply handlers, and privileges to dequeue messages from the apply process queue. An apply process can be associated with only one user, but one user can be associated with many apply processes.

See Also:

"Configuring a Streams Administrator" for information about the required privileges

This section discusses the following topics:

Apply Process Components

An apply process consists of the following components:

  • A reader server that dequeues messages. The reader server is a parallel execution server that computes dependencies between LCRs and assembles messages into transactions. The reader server then returns the assembled transactions to the coordinator process, which assigns them to idle apply servers.

  • A coordinator process that gets transactions from the reader server and passes them to apply servers. The coordinator process name is annn, where nnn is a coordinator process number. Valid coordinator process names include a001 through a999. The coordinator process is an Oracle background process.

  • One or more apply servers that apply LCRs to database objects as DML or DDL statements or that pass the LCRs to their appropriate apply handlers. For non-LCR messages, the apply servers pass the messages to the message handler. Apply servers can also enqueue LCR and non-LCR messages into a queue specified by the DBMS_APPLY_ADM.SET_ENQUEUE_DESTINATION procedure. Each apply server is a parallel execution server. If an apply server encounters an error, then it then tries to resolve the error with a user-specified conflict handler or error handler. If an apply server cannot resolve an error, then it rolls back the transaction and places the entire transaction, including all of its messages, in the error queue.

    When an apply server commits a completed transaction, this transaction has been applied. When an apply server places a transaction in the error queue and commits, this transaction also has been applied.

If a transaction being handled by an apply server has a dependency on another transaction that is not known to have been applied, then the apply server contacts the coordinator process and waits for instructions. The coordinator process monitors all of the apply servers to ensure that transactions are applied and committed in the correct order.

See Also:

Oracle Streams Replication Administrator's Guide for more information about apply processes and dependencies

Reader Server States

The state of a reader server describes what the reader server is doing currently. You can view the state of the reader server for an apply process by querying the V$STREAMS_APPLY_READER dynamic performance view. The following reader server states are possible:

  • INITIALIZING - Starting up

  • IDLE - Performing no work

  • DEQUEUE MESSAGES - Dequeuing messages from the apply process queue

  • SCHEDULE MESSAGES - Computing dependencies between messages and assembling messages into transactions

  • SPILLING - Spilling unapplied messages from memory to hard disk

  • PAUSED - Waiting for a DDL LCR to be applied

See Also:

"Displaying Information About the Reader Server for Each Apply Process" for a query that displays the state of an apply process reader server

Coordinator Process States

The state of a coordinator process describes what the coordinator process is doing currently. You can view the state of a coordinator process by querying the V$STREAMS_APPLY_COORDINATOR dynamic performance view. The following coordinator process states are possible:

  • INITIALIZING - Starting up

  • APPLYING - Passing transactions to apply servers

  • SHUTTING DOWN CLEANLY - Stopping without an error

  • ABORTING - Stopping because of an apply error

See Also:

"Displaying General Information About Each Coordinator Process" for a query that displays the state of a coordinator process

Apply Server States

The state of an apply server describes what the apply server is doing currently. You can view the state of each apply server for an apply process by querying the V$STREAMS_APPLY_SERVER dynamic performance view. The following apply server states are possible:

  • INITIALIZING - Starting up.

  • IDLE - Performing no work.

  • RECORD LOW-WATERMARK - Performing an administrative action that maintains information about the apply progress, which is used in the ALL_APPLY_PROGRESS and DBA_APPLY_PROGRESS data dictionary views.

  • ADD PARTITION - Performing an administrative action that adds a partition that is used for recording information about in-progress transactions.

  • DROP PARTITION - Performing an administrative action that drops a partition that was used to record information about in-progress transactions.

  • EXECUTE TRANSACTION - Applying a transaction.

  • WAIT COMMIT - Waiting to commit a transaction until all other transactions with a lower commit SCN are applied. This state is possible only if the COMMIT_SERIALIZATION apply process parameter is set to a value other than none and the PARALELLISM apply process parameter is set to a value greater than 1.

  • WAIT DEPENDENCY - Waiting to apply an LCR in a transaction until another transaction, on which it has a dependency, is applied. This state is possible only if the PARALELLISM apply process parameter is set to a value greater than 1.

  • WAIT FOR NEXT CHUNK - Waiting for the next set of LCRs for a large transaction.

  • TRANSACTION CLEANUP - Cleaning up an applied transaction, which includes removing LCRs from the apply process queue.

See Also:

"Displaying Information About the Apply Servers for Each Apply Process" for a query that displays the state of each apply process apply server

Apply Process Creation

You can create an apply process using the DBMS_STREAMS_ADM package or the DBMS_APPLY_ADM package. Using the DBMS_STREAMS_ADM package to create an apply process is simpler because defaults are used automatically for some configuration options. Alternatively, using the DBMS_APPLY_ADM package to create an apply process is more flexible.

When you create an apply process by running the CREATE_APPLY procedure in the DBMS_APPLY_ADM package, you can specify nondefault values for the apply_captured, apply_database_link, and apply_tag parameters. Then you can use the procedures in the DBMS_STREAMS_ADM package or the DBMS_RULE_ADM package to add rules to a rule set for the apply process.

If you create more than one apply process in a database, then the apply processes are completely independent of each other. These apply processes do not synchronize with each other, even if they apply LCRs from the same source database.

Table 4-2 describes the differences between using the DBMS_STREAMS_ADM package and the DBMS_APPLY_ADM package for apply process creation.

Table 4-2 DBMS_STREAMS_ADM and DBMS_APPLY_ADM Apply Process Creation

DBMS_STREAMS_ADM Package DBMS_APPLY_ADM Package

A rule set is created automatically for the apply process and rules can be added to the rule set automatically. The rule set is a positive rule set if the inclusion_rule parameter is set to true (the default). It is a negative rule set if the inclusion_rule parameter is set to false. You can use the procedures in the DBMS_STREAMS_ADM and DBMS_RULE_ADM package to manage rule sets and rules for the apply process after the apply process is created.

You create one or more rule sets and rules for the apply process either before or after it is created. You can use the procedures in the DBMS_RULE_ADM package to create rule sets and add rules to rule sets either before or after the apply process is created. You can use the procedures in the DBMS_STREAMS_ADM package to create rule sets and add rules to rule sets for the apply process after the apply process is created.

The apply process can apply messages only at the local database.

You specify whether the apply process applies messages at the local database or at a remote database during apply process creation.

Changes applied by the apply process generate tags in the redo log at the destination database with a value of 00 (double zero).

You specify the tag value for changes applied by the apply process during apply process creation.

See Also:

Streams Data Dictionary for an Apply Process

When a database object is prepared for instantiation at a source database, a Streams data dictionary is populated automatically at the database where changes to the object are captured by a capture process. The Streams data dictionary is a multiversioned copy of some of the information in the primary data dictionary at a source database. The Streams data dictionary maps object numbers, object version information, and internal column numbers from the source database into table names, column names, and column datatypes. This mapping keeps each captured message as small as possible because a captured message can often use numbers rather than names internally.

Unless a captured message is passed as a parameter to a custom rule-based transformation during capture or propagation, the mapping information in the Streams data dictionary at the source database is needed to interpret the contents of the LCR at any database that applies the captured message. To make this mapping information available to an apply process, Oracle automatically populates a multiversioned Streams data dictionary at each destination database that has a Streams apply process. Oracle automatically propagates relevant information from the Streams data dictionary at the source database to all other databases that apply captured messages from the source database.

See Also:

Apply Process Parameters

After creation, an apply process is disabled so that you can set the apply process parameters for your environment before starting the process for the first time. Apply process parameters control the way an apply process operates. For example, the time_limit apply process parameter specifies the amount of time an apply process runs before it is shut down automatically. After you set the apply process parameters, you can start the apply process.

See Also:

Apply Process Parallelism

The parallelism apply process parameter specifies the number of apply servers that can concurrently apply transactions. For example, if parallelism is set to 5, then an apply process uses a total of five apply servers. The reader server is a parallel execution server. So, if parallelism is set to 5, then an apply process uses a total of six parallel execution servers, assuming six parallel execution servers are available in the database. An apply process always uses two or more parallel execution servers.

Note:

  • Resetting the parallelism parameter automatically stops and restarts the apply process when the currently executing transactions are applied. This operation can take some time depending on the size of the transactions.

  • Setting the parallelism parameter to a number higher than the number of available parallel execution servers can disable the apply process. Make sure the PROCESSES and PARALLEL_MAX_SERVERS initialization parameters are set appropriately when you set the parallelism apply process parameter.

See Also:

Commit Serialization

Apply servers can apply nondependent transactions at the destination database in an order that is different from the commit order at the source database. Dependent transactions are always applied at the destination database in the same order as they were committed at the source database.

You control whether the apply servers can apply nondependent transactions in a different order at the destination database using the commit_serialization apply parameter. This parameter has the following settings:

  • full: An apply process always commits all transactions in the order in which they were committed at the source database. This setting is the default.

  • none: An apply process can commit nondependent transactions in any order. An apply process always commits dependent transactions in the order in which they were committed at the source database. Performance is best if you specify this value.

If you specify none, then it is possible that a destination database commits changes in a different order than the source database. For example, suppose two nondependent transactions are committed at the source database in the following order:

  1. Transaction A

  2. Transaction B

At the destination database, these transactions might be committed in the opposite order:

  1. Transaction B

  2. Transaction A

Automatic Restart of an Apply Process

You can configure an apply process to stop automatically when it reaches certain predefined limits. The time_limit apply process parameter specifies the amount of time an apply process runs, and the transaction_limit apply process parameter specifies the number of transactions an apply process can apply. The apply process stops automatically when it reaches these limits.

The disable_on_limit parameter controls whether an apply process becomes disabled or restarts when it reaches a limit. If you set the disable_on_limit parameter to y, then the apply process is disabled when it reaches a limit and does not restart until you restart it explicitly. If, however, you set the disable_on_limit parameter to n, then the apply process stops and restarts automatically when it reaches a limit.

When an apply process is restarted, it gets a new session identifier, and the parallel execution servers associated with the apply process also get new session identifiers. However, the coordinator process number (annn) remains the same.

Stop or Continue on Error

Using the disable_on_error apply process parameter, you can instruct an apply process to become disabled when it encounters an error or to continue applying transactions after it encounters an error.

See Also:

"The Error Queue"

Multiple Apply Processes in a Single Database

If you run multiple apply processes in a single database, consider increasing the size of the System Global Area (SGA). In a Real Application Clusters environment, consider increasing the size of the SGA for each instance. Use the SGA_MAX_SIZE initialization parameter to increase the SGA size. Also, if the size of the Streams pool is not managed automatically in the database, then you should increase the size of the Streams pool by 1 MB for each apply process parallelism. For example, if you have two apply processes running in a database, and the parallelism parameter is set to 4 for one of them and 1 for the other, then increase the Streams pool by 5 MB (4 + 1 = 5 parallelism).

Note:

The size of the Streams pool is managed automatically if the SGA_TARGET initialization parameter is set to a nonzero value.

See Also:

Persistent Apply Process Status upon Database Restart

An apply process maintains a persistent status when the database running the apply process is shut down and restarted. For example, if an apply process is enabled when the database is shut down, then the apply process automatically starts when the database is restarted. Similarly, if an apply process is disabled or aborted when a database is shut down, then the apply process is not started and retains the disabled or aborted status when the database is restarted.

The Error Queue

The error queue contains all of the current apply errors for a database. If there are multiple apply processes in a database, then the error queue contains the apply errors for each apply process. To view information about apply errors, query the DBA_APPLY_ERROR data dictionary view or use Enterprise Manager.

The error queue stores information about transactions that could not be applied successfully by the apply processes running in a database. A transaction can include many messages. When an unhandled error occurs during apply, an apply process automatically moves all of the messages in the transaction that satisfy the apply process rule sets to the error queue.

You can correct the condition that caused an error and then reexecute the transaction that caused the error. For example, you might modify a row in a table to correct the condition that caused an error.

When the condition that caused the error has been corrected, you can either reexecute the transaction in the error queue using the EXECUTE_ERROR or EXECUTE_ALL_ERRORS procedure, or you can delete the transaction from the error queue using the DELETE_ERROR or DELETE_ALL_ERRORS procedure. These procedures are in the DBMS_APPLY_ADM package.

When you reexecute a transaction in the error queue, you can specify that the transaction be executed either by the user who originally placed the error in the error queue or by the user who is reexecuting the transaction. Also, the current Streams tag for the apply process is used when you reexecute a transaction in the error queue.

A reexecuted transaction uses any relevant apply handlers and conflict resolution handlers. If, to resolve the error, a row LCR in an error queue must be modified before it is executed, then you can configure a DML handler to process the row LCR that caused the error in the error queue. In this case, the DML handler can modify the row LCR in some way to avoid a repetition of the same error. The row LCR is passed to the DML handler when you reexecute the error containing the row LCR.

The error queue contains information about errors encountered at the local destination database only. It does not contain information about errors for apply processes running in other databases in a Streams environment.

The error queue uses the exception queues in the database. When you create an ANYDATA queue using the SET_UP_QUEUE procedure in the DBMS_STREAMS_ADM package, the procedure creates a queue table for the queue if one does not already exist. When a queue table is created, an exception queue is created automatically for the queue table. Multiple queues can use a single queue table, and each queue table has one exception queue. Therefore, a single exception queue can store errors for multiple queues and multiple apply processes.

An exception queue only contains the apply errors for its queue table, but the Streams error queue contains information about all of the apply errors in each exception queue in a database. You should use the procedures in the DBMS_APPLY_ADM package to manage Streams apply errors. You should not dequeue apply errors from an exception queue directly.

Note:

If a messaging client encounters an error when it is dequeuing messages, then the messaging client moves these messages to the exception queue associated with the its queue table. However, information about messaging client errors is not stored in the error queue. Only information about apply process errors is stored in the error queue.

See Also: