9 Addendum To DBMS_STREAMS_ADM

Inbound Server Creation and Apply User

The following procedures in the DBMS_STREAMS_ADM package can create an XStream inbound server:

• ADD_GLOBAL_RULES procedure

• ADD_SCHEMA_RULES procedure

• ADD_SUBSET_RULES procedure

• ADD_TABLE_RULES procedure

If the streams_name parameter in one of these procedures is set to NULL, if the streams_type parameter is set to apply, and if one relevant apply process, inbound server, or outbound server exists, then the procedure uses the relevant apply process, inbound server, or outbound server. The relevant apply process, inbound server, or outbound server is identified in one of the following ways:

• If one existing apply process or outbound server has the source database specified in the source_database parameter and uses the queue specified in the queue_name parameter, then the procedure uses this apply process or outbound server.

• If the source_database parameter is set to NULL and one existing apply process, inbound server, or outbound server is using the queue specified in the queue_name parameter, then the procedure uses this apply process, inbound server, or outbound server.

• If the streams_name parameter is set to NULL and no relevant apply process, inbound server, or outbound server exists, then the procedure creates an apply process automatically with a system-generated name.

  The apply process remains an apply process if it receives captured LCRs from a capture process. The apply process can become an inbound server if an XStream client application attaches to it before it receives captured LCRs from a capture process. After the initial contact, an apply process cannot be changed into an inbound server, and an inbound server cannot be changed into an apply process.

• If the streams_name parameter is set to NULL and multiple relevant apply processes, inbound servers, or outbound servers exist, then the procedure raises an error.

If one of these procedures creates an inbound server, then it configures the current user as the apply user. The apply user is the user in whose security domain an XStream client application attaches to an Oracle database.

An apply user applies changes directly to database objects, runs custom rule-based transformations configured for inbound server rules, and runs apply handlers configured for the inbound server. This user must have the necessary privileges to apply changes. The procedure grants the apply user DEQUEUE privilege on the queue used by the inbound server and configures the user as a secure queue user of the queue.

Each inbound server must have a unique name. The name cannot be used by an apply process, outbound server, or messaging client in the same database, and the name cannot be used by another inbound server in the same database.

XStream Inbound Server Rules for LCRs

The following procedures add rules to a rule set of an XStream inbound server when you specify apply for the streams_type parameter and an inbound server for the streams_name parameter:

• The ADD_GLOBAL_RULES procedure adds rules whose rule condition evaluates to TRUE for all LCRs in the inbound server's queue.

• The ADD_SCHEMA_RULES procedure adds rules whose rule condition evaluates to TRUE for LCRs in the inbound server's queue containing changes made to a specified schema.

• The ADD_SUBSET_RULES procedure adds rules whose rule condition evaluates to TRUE for row LCRs in the inbound server's queue containing the results of DML changes made to a subset of rows in a specified table.

• The ADD_TABLE_RULES procedure adds rules whose rule condition evaluates to TRUE for LCRs in the inbound server's queue containing changes made to a specified table.

If one of these procedures adds rules to the positive rule set for the inbound server, then the rules specify that the inbound server applies LCRs sent to it by the XStream client application. If one of these procedures adds rules to the negative rule set for the inbound server, then the rules specify that the discards LCRs sent to it by the XStream client application. For inbound server rules, you should execute these procedures at the database to which the XStream client application attaches. If an inbound server has no rule sets, then it applies all of the messages sent to it by the XStream client application.

Changes applied by an inbound server created by one of these procedures generate tags in the redo log at the destination database with a value of '00' (double zero). You can use the ALTER_APPLY procedure in the DBMS_APPLY_ADM package to alter the tag value after the inbound server is created, if necessary.

The rules in the XStream inbound server rule sets determine which messages are either applied or discarded after the messages are received from the XStream client application. An inbound server can only process LCRs sent from an XStream client application.

When one of these procedures creates rules for an inbound server, the procedure ignores the source_database parameter.

XStream Outbound Server Rules for LCRs

The following procedures add rules to a rule set of an XStream outbound server when you specify apply for the streams_type parameter and an outbound server for the streams_name parameter:

• The ADD_GLOBAL_RULES procedure adds rules whose rule condition evaluates to TRUE for all LCRs in the outbound server's queue.

• The ADD_SCHEMA_RULES procedure adds rules whose rule condition evaluates to TRUE for LCRs in the outbound server's queue containing changes made to a specified schema.

• The ADD_SUBSET_RULES procedure adds rules whose rule condition evaluates to TRUE for row LCRs in the outbound server's queue containing the results of DML changes made to a subset of rows in a specified table.

• The ADD_TABLE_RULES procedure adds rules whose rule condition evaluates to TRUE for LCRs in the outbound server's queue containing changes made to a specified table.

If one of these procedures adds rules to the positive rule set for the outbound server, then the rules specify that the outbound server sends LCRs in its queue to the XStream client application. If one of these procedures adds rules to the negative rule set for the outbound server, then the rules specify that the outbound server discards LCRs in its queue. For outbound server rules, you should execute these procedures at the database to which the XStream client application attaches.

An outbound server can process captured LCRs from only one source database. The source database is the database where the changes originated. If one of these procedures creates an outbound server, then specify the source database for the outbound server using the source_database parameter. If the source_database parameter is NULL, and one of these procedures creates an outbound server, then the source database name of the first LCR received by the outbound server is used for the source database.

The rules in the outbound server's rule sets determine which messages are dequeued by the outbound server. When you create rules with one of these procedures, and you specify a value for the source_database parameter, then the rules include conditions for the specified source database. If the outbound server dequeues an LCR with a source database that is different than the source database for the outbound server, then an error is raised. In addition, when adding rules to an existing outbound server, the database specified in the source_database parameter cannot be different than the source database for the outbound server. You can determine the source database for an outbound server by querying the DBA_XSTREAM_OUTBOUND data dictionary view.