7 DBMS_XSTREAM_ADM

This DBMS_XSTREAM_ADM package, one of a set of Oracle Streams packages, provides interfaces for streaming database changes between an Oracle database and another system. XStream is a programmatic interface to Oracle Streams. XStream enables applications to stream out or stream in database changes.

This chapter contains the following topic:

Using DBMS_XSTREAM_ADM
- Overview
- Security Model
- Operational Notes
Summary of DBMS_XSTREAM_ADM Subprograms

See Also:

Using DBMS_XSTREAM_ADM

This section contains topics which relate to using the DBMS_XSTREAM_ADM package.

Overview
Security Model
Operational Notes

Overview

The package provides interfaces for configuring outbound servers that stream database changes from an Oracle database to another system. The package also provides interfaces for configuring inbound servers that stream database changes from another system to an Oracle database.

In both cases, the database changes are encapsulated in logical change records (LCRs). Also, the other system can be an Oracle system or a non-Oracle system, such as a non-Oracle database.

XStream outbound servers can stream out LCRs from an Oracle database programmatically using C or Java. After receiving the LCRs, the other system can save the contents of the LCRs to a file, send the LCRs to an Oracle database through an XStream inbound server, or generate SQL statements and execute them on any Oracle or non-Oracle databases.

XStream inbound servers accept LCRs from another system and either apply them to an Oracle database or process them in a customized way.

See Also:

Chapter 1, "XStream Concepts"

Security Model

To ensure that the user who runs the subprograms in this package has the necessary privileges, configure an Oracle Streams administrator and connect as the Oracle Streams administrator when using this package.

An administrator must be granted the DBA role when the administrator is performing any of the following actions:

Running the ADD_OUTBOUND procedure while connected as a user that is different than the configured connect user for an outbound server
Running the ALTER_OUTBOUND procedure to change the capture user for a capture process or the connect user for an outbound server
Running the CREATE_OUTBOUND procedure because this procedure creates a capture process
Running the ALTER_INBOUND procedure to change the apply user for an inbound server
Running the ADD_INBOUND procedure while connected as a user that is different than the configured apply user for an inbound server

When the administrator does not need to perform these tasks, DBA role is not required.

See Also:

Oracle Streams Replication Administrator's Guide for information about configuring an Oracle Streams administrator
"XStream and Security" for more information about XStream and security

Operational Notes

Some subprograms in the DBMS_APPLY_ADM package can manage XStream outbound servers, and some subprograms in the DBMS_APPLY_ADM package can manage XStream inbound servers.

See Also:

Chapter 8, "Addendum To DBMS_APPLY_ADM" for details about which subprograms can manage outbound servers and inbound servers

Summary of DBMS_XSTREAM_ADM Subprograms

Table 7-1 DBMS_XSTREAM_ADM Package Subprograms

Subprogram	Description
ADD_OUTBOUND Procedure	Creates an XStream outbound server that dequeues logical change records (LCRs) from the specified queue
ADD_SUBSET_OUTBOUND_RULES Procedure	Adds subset rules to an outbound server configuration
ALTER_INBOUND Procedure	Modifies an XStream inbound server
ALTER_OUTBOUND Procedure	Modifies an XStream outbound server
CREATE_INBOUND Procedure	Creates an XStream inbound server and its queue
CREATE_OUTBOUND Procedure	Creates an XStream outbound server, queue, and capture process to enable client applications to stream out Oracle database changes encapsulated in logical change records (LCRs)
DROP_INBOUND Procedure	Removes an inbound server configuration
DROP_OUTBOUND Procedure	Removes an outbound server configuration
REMOVE_SUBSET_OUTBOUND_RULES Procedure	Removes subset rules from an outbound server configuration

Note:

All subprograms commit unless specified otherwise.

ADD_OUTBOUND Procedure

This procedure creates an XStream outbound server that dequeues logical change records (LCRs) from the specified queue. The outbound server streams out the LCRs to a client application.

This procedure creates neither a capture process nor a queue. To create an outbound server, a capture process, and a queue with one procedure call, use the CREATE_OUTBOUND Procedure.

To create the capture process individually, use one of the following packages:

DBMS_STREAM_ADM
DBMS_CAPTURE_ADM

To create a queue individually, use the SET_UP_QUEUE procedure in the DBMS_STREAMS_ADM package.

This procedure is overloaded. One table_names parameter is type VARCHAR2 and the other table_names parameters is type DBMS_UTILITY.UNCL_ARRAY. Also, one schema_names parameter is type VARCHAR2 and the other schema_names parameters is type DBMS_UTILITY.UNCL_ARRAY. These parameters enable you to enter the lists of tables and schemas in different ways and are mutually exclusive.

Note:

Only one client application at a time can attach to an outbound server. See Part IV, "XStream OCI API Reference" and Oracle Streams XStream Java API Reference for information about attaching to an outbound server.
This procedure enables the outbound server that it creates.

Syntax

DBMS_XSTREAM_ADM.ADD_OUTBOUND(
   server_name     IN  VARCHAR2,
   queue_name      IN  VARCHAR2,
   source_database IN  VARCHAR2  DEFAULT NULL,
   table_names     IN  DBMS_UTILITY.UNCL_ARRAY,
   schema_names    IN  DBMS_UTILITY.UNCL_ARRAY,
   connect_user    IN  VARCHAR2  DEFAULT NULL,
   comment         IN  VARCHAR2  DEFAULT NULL);

DBMS_XSTREAM_ADM.ADD_OUTBOUND(
   server_name     IN VARCHAR2,
   queue_name      IN VARCHAR2,
   source_database IN VARCHAR2  DEFAULT NULL,
   table_names     IN VARCHAR2  DEFAULT NULL,
   schema_names    IN VARCHAR2  DEFAULT NULL,
   connect_user    IN VARCHAR2  DEFAULT NULL,
   comment         IN VARCHAR2  DEFAULT NULL);

Parameters

Table 7-2 ADD_OUTBOUND Procedure Parameters

Parameter	Description
`server_name`	The name of the outbound server being created. A `NULL` specification is not allowed. Do not specify an owner. The specified name must not match the name of an existing outbound server, inbound server, apply process, or messaging client. Note: The `server_name` setting cannot be altered after the outbound server is created.
`queue_name`	The name of the local queue from which the outbound server dequeues logical change records (LCRs), specified as `[schema_name.]queue_name`. The current database must contain the queue, and the queue must be `ANYDATA` type. For example, to specify a queue named `streams_queue` in the `strmadmin` schema, enter `strmadmin.streams_queue` for this parameter. If the schema is not specified, then the current user is the default.
`source_database`	The global name of the source database. The source database is where the changes being captured originated. If you do not include the domain name, then the procedure appends it to the database name automatically. For example, if you specify `DBS1` and the domain is `.EXAMPLE.COM`, then the procedure specifies `DBS1.EXAMPLE.COM` automatically. If `NULL`, then this procedure does not add a condition regarding the source database to the generated rules. Otherwise, a condition regarding the source database is added.
`table_names`	The tables for which data manipulation language (DML) and data definition language (DDL) changes are streamed out to the XStream Out client application. The tables can be specified in the following ways: Comma-delimited list of type `VARCHAR2` A PL/SQL index-by table of type `DBMS_UTILITY.UNCL_ARRAY`, where each element is the name of a table. The first table should be in position 1. The last position must be `NULL`. Each table should be specified as `[schema_name.]table_name`. For example, `hr.employees`. If the schema is not specified, then the current user is the default. See Also: "Usage Notes" for more information about this parameter.
`schema_names`	The schemas for which DML and DDL changes are streamed out to the XStream Out client application. The schemas can be specified in the following ways: Comma-delimited list of type `VARCHAR2` A PL/SQL index-by table of type `DBMS_UTILITY.UNCL_ARRAY`, where each element is the name of a schema. The first schema should be in position 1. The last position must be `NULL`. See Also: "Usage Notes" for more information about this parameter.
`connect_user`	The user who can attach to the specified outbound server to retrieve the LCR stream. The client application must attach to the outbound server as the specified connect user. See "CREATE_OUTBOUND Procedure" for information about the privileges required by a connect user. If `NULL`, then the current user is the default.
`comment`	An optional comment associated with the outbound server.

Usage Notes

The following list describes the behavior of the outbound server for various combinations of the table_names and schema_names parameters:

If both the table_names and schema_names parameters are NULL, then the outbound server streams all DML and DDL changes to the client application.
If both the table_names and schema_names parameters are specified, then the outbound server streams DML and DDL changes for the specified tables and schemas.
If the table_names parameter is specified and the schema_names parameter is NULL, then the outbound server streams DML and DDL changes for the specified tables.
If the table_names parameter is NULL and the schema_names parameter is specified, then the outbound server streams DML and DDL changes for the specified schema.

ADD_SUBSET_OUTBOUND_RULES Procedure

This procedure adds subset rules to an outbound server configuration. Subset rules instruct the outbound server to stream out a subset of the changes in the specified tables. Outbound servers can stream out a subset of both rows and columns.

This procedure is overloaded. One column_list parameter is type VARCHAR2 and the other column_list parameters is type DBMS_UTILITY.LNAME_ARRAY. These parameters enable you to enter the list of columns in different ways and are mutually exclusive.

Note:

This procedure does not add rules to the outbound server's capture process.

Syntax

DBMS_XSTREAM_ADM.ADD_SUBSET_OUTBOUND_RULES(
   server_name IN VARCHAR2,
   table_name  IN VARCHAR2,
   condition   IN VARCHAR2,
   column_list IN DBMS_UTILITY.LNAME_ARRAY,
   keep        IN BOOLEAN   DEFAULT TRUE);

DBMS_XSTREAM_ADM.ADD_SUBSET_OUTBOUND_RULES(
   server_name IN VARCHAR2,
   table_name  IN VARCHAR2,
   condition   IN VARCHAR2,
   column_list IN VARCHAR2  DEFAULT NULL, 
   keep        IN BOOLEAN   DEFAULT TRUE);

Parameters

Table 7-3 ADD_SUBSET_OUTBOUND_RULES Procedure Parameters

Parameter	Description
`server_name`	The name of the outbound server to which rules are being added. Specify an existing outbound server. Do not specify an owner.
`table_name`	The name of the table specified as `[schema_name.]object_name`. For example, `hr.employees`. If the schema is not specified, then the current user is the default. If the outbound server configuration uses a local capture process, then the table must exist at the local source database. If the outbound server configuration uses a downstream capture process, then the table must exist at both the source database and at the local downstream capture database. The specified table cannot have any LOB, `LONG`, or `LONG` `RAW` columns currently or in the future.
`condition`	The subset condition. Specify this condition similar to the way you specify conditions in a `WHERE` clause in SQL. For example, to specify rows in the `hr.employees` table where the `salary` is greater than `4000` and the `job_id` is `SA_MAN`, enter the following as the condition: `' salary > 4000 and job_id = ''SA_MAN'' '` If `NULL`, then the procedure raises an error. Note: The quotation marks in the preceding example are all single quotation marks.
`column_list`	The list of columns either to include in the outbound server configuration or to exclude from the outbound server configuration. Whether the columns are included or excluded depends on the setting for the `keep` parameter. The columns can be specified in the following ways: Comma-delimited list of type `VARCHAR2` A PL/SQL index-by table of type `DBMS_UTILITY.LNAME_ARRAY`, where each element is the name of a column. The first column should be in position 1. The last position must be `NULL`. If `NULL`, then all of the columns are included.
`keep`	If `TRUE`, then the columns specified in the `column_list` parameter are kept as part of the outbound server configuration. Therefore, changes to these columns that satisfy the condition in the `condition` parameter are streamed to the outbound server client application. If `FALSE`, then the columns specified in the `column_list` parameter are excluded from the outbound server configuration. Therefore, changes to these columns are not streamed to the outbound server client application. See Also: "Usage Notes"

Usage Notes

When column_list is non-NULL and keep is set to TRUE, this procedure creates a keep columns declarative rule-based transformation for the columns listed in column_list.

When column_list is non-NULL and keep is set to FALSE, this procedure creates a delete column declarative rule-based transformation for each column listed in column_list.

See Also:

Oracle Streams Concepts and Administration for information about declarative rule-based transformations

ALTER_INBOUND Procedure

This procedure modifies an XStream inbound server.

Syntax

DBMS_XSTREAM_ADM.ALTER_INBOUND(
   server_name IN VARCHAR2,
   apply_user  IN VARCHAR2  DEFAULT NULL,  
   comment     IN VARCHAR2  DEFAULT NULL);

Parameters

Table 7-4 ALTER_INBOUND Procedure Parameters

Parameter Description

Parameter	Description
`server_name`	The name of the inbound server being altered. Specify an existing inbound server. Do not specify an owner.
`apply_user`	The user who applies all data manipulation language (DML) and data definition language (DDL) changes that satisfy the inbound server rule sets, who runs user-defined apply handlers, and who runs custom rule-based transformations configured for inbound server rules. The client application must attach to the inbound server as the apply user. Specify a user to change the apply user. In this case, the user who invokes the `ALTER_INBOUND` procedure must be granted `DBA` role. Only the `SYS` user can set the `connect_user` to `SYS`. If `NULL`, then the apply user is not changed. See "CREATE_INBOUND Procedure" for information about the required privileges for an apply user.
`comment`	An optional comment associated with the inbound server. If non-`NULL`, then the specified comment replaces the existing comment. If `NULL`, then the existing comment is not changed.

server_name

The name of the inbound server being altered. Specify an existing inbound server. Do not specify an owner.

apply_user

The user who applies all data manipulation language (DML) and data definition language (DDL) changes that satisfy the inbound server rule sets, who runs user-defined apply handlers, and who runs custom rule-based transformations configured for inbound server rules.

The client application must attach to the inbound server as the apply user.

Specify a user to change the apply user. In this case, the user who invokes the ALTER_INBOUND procedure must be granted DBA role. Only the SYS user can set the connect_user to SYS.

If NULL, then the apply user is not changed.

See "CREATE_INBOUND Procedure" for information about the required privileges for an apply user.

comment

An optional comment associated with the inbound server.

If non-NULL, then the specified comment replaces the existing comment.

If NULL, then the existing comment is not changed.

ALTER_OUTBOUND Procedure

This procedure modifies an XStream outbound server configuration.

This procedure always alters the specified outbound server. This procedure can also alter the outbound server's capture process when either of the following conditions are met:

The capture process was created by the CREATE_OUTBOUND procedure in this package
The queue used by the capture process was created by the CREATE_OUTBOUND procedure.

To check whether this procedure can alter the outbound server's capture process, query the CAPTURE_NAME column in the DBA_XSTREAM_OUTBOUND view. When the name of the capture process appears in the CAPTURE_NAME column of this view, the ALTER_OUTBOUND procedure can manage the capture process's rules or change the capture user for the capture process.

This procedure is overloaded. One table_names parameter is type VARCHAR2 and the other table_names parameters is type DBMS_UTILITY.UNCL_ARRAY. Also, one schema_names parameter is type VARCHAR2 and the other schema_names parameters is type DBMS_UTILITY.UNCL_ARRAY. These parameters enable you to enter the list of tables and schemas in different ways and are mutually exclusive.

Syntax

DBMS_XSTREAM_ADM.ALTER_OUTBOUND(
   server_name    IN VARCHAR2,
   table_names    IN DBMS_UTILITY.UNCL_ARRAY,
   schema_names   IN DBMS_UTILITY.UNCL_ARRAY,
   add            IN BOOLEAN   DEFAULT TRUE,
   capture_user   IN VARCHAR2  DEFAULT NULL,
   connect_user   IN VARCHR2   DEFAULT NULL,
   comment        IN VARCHAR2  DEFAULT NULL,  
   inclusion_rule IN BOOLEAN   DEFAULT TRUE);

DBMS_XSTREAM_ADM.ALTER_OUTBOUND(
   server_name    IN VARCHAR2,
   table_names    IN VARCHAR2  DEFAULT NULL,
   schema_names   IN VARCHAR2  DEFAULT NULL,
   add            IN BOOLEAN   DEFAULT TRUE,
   capture_user   IN VARCHAR2  DEFAULT NULL,
   connect_user   IN VARCHAR2  DEFAULT NULL,
   comment        IN VARCHAR2  DEFAULT NULL,  
   inclusion_rule IN BOOLEAN   DEFAULT TRUE);

Parameters

Table 7-5 ALTER_OUTBOUND Procedure Parameters

Parameter	Description
`server_name`	The name of the outbound server being altered. Specify an existing outbound server. Do not specify an owner.
`table_names`	The tables that are either added to or removed from the XStream Out configuration. Whether the tables are added or removed depends on the setting for the `add` parameter. The tables can be specified in the following ways: Comma-delimited list of type `VARCHAR2` A PL/SQL index-by table of type `DBMS_UTILITY.UNCL_ARRAY`, where each element is the name of a table. The first table should be in position 1. The last position must be `NULL`. Each table should be specified as `[schema_name.]table_name`. For example, `hr.employees`. If the schema is not specified, then the current user is the default.
`schema_names`	The schemas that are either added to or removed from the XStream Out configuration. Whether the schemas are added or removed depends on the setting for the `add` parameter. The schemas can be specified in the following ways: Comma-delimited list of type `VARCHAR2` A PL/SQL index-by table of type `DBMS_UTILITY.UNCL_ARRAY`, where each element is the name of a schema. The first schema should be in position 1. The last position must be `NULL`.
`add`	If `TRUE`, then the procedure adds to the XStream Out configuration the tables specified in the `table_names` parameter and the schemas specified in the `schema_names` parameter. If `FALSE`, then the procedure removes from the XStream Out configuration the tables specified in the `table_names` parameter and the schemas specified in the `schema_names` parameter.
`capture_user`	The user in whose security domain a capture process captures changes that satisfy its rule sets and runs custom rule-based transformations configured for capture process rules. Specify a user to change the capture user. In this case, the user who invokes the `ALTER_OUTBOUND` procedure must be granted `DBA` role. Only the `SYS` user can set the `capture_user` to `SYS`. If `NULL`, then the capture user is not changed. If you change the capture user, then this procedure grants the new capture user enqueue privilege on the queue used by the capture process and configures the user as a secure queue user of the queue. Ensure that the capture user is granted the other required privileges. See "CREATE_OUTBOUND Procedure" for information about the privileges required by a capture user. The capture process is stopped and restarted automatically when you change the value of this parameter. Note: If the specified user is dropped using `DROP` `USER...` `CASCADE`, then the `capture_user` setting for the capture process is set to `NULL` automatically. You must specify a capture user before the capture process can run.
`connect_user`	The user who can attach to the specified outbound server to retrieve the change stream. The client application must attach to the outbound server as the specified connect user. Specify a user to change the connect user. In this case, the user who invokes the `ALTER_OUTBOUND` procedure must be granted `DBA` role. Only the `SYS` user can set the `connect_user` to `SYS`. If `NULL`, then the connect user is not changed. If you change the connect user, then this procedure grants the new connect user dequeue privilege on the queue used by the outbound server and configures the user as a secure queue user of the queue. Ensure that the connect user is granted the other required privileges. See "CREATE_OUTBOUND Procedure" for information about the privileges required by a connect user.
`comment`	An optional comment associated with the outbound server. If non-`NULL`, then the specified comment replaces the existing comment. If `NULL`, then the existing comment is not changed.
`inclusion_rule`	If `TRUE` and the `ADD` parameter is set to `TRUE`, then the procedure adds rules for the tables specified in the `table_names` parameter and the schemas specified in the `schema_names` parameter to the positive rule sets in the XStream Out configuration. When rules for tables and schemas are in positive rule sets, the XStream Out configuration streams data manipulation language (DML) and data definition language (DDL) changes to the tables out to the client application. If `TRUE` and the `ADD` parameter is set to `FALSE`, then the procedure removes rules for the tables specified in the `table_names` parameter and the schemas specified in the `schema_names` parameter from the positive rule sets in the XStream Out configuration. If `FALSE` and the `ADD` parameter is set to `TRUE`, then the procedure adds rules for the tables specified in the `table_names` parameter and the schemas specified in the `schema_names` parameter to the negative rule sets in the XStream Out configuration. When rules for tables and schemas are in negative rule sets, the XStream Out configuration does not stream changes to the tables out to the client application. If `FALSE` and the `ADD` parameter is set to `FALSE`, then the procedure removes rules for the tables specified in the `table_names` parameter and the schemas specified in the `schema_names` parameter from the negative rule sets in the XStream Out configuration.

CREATE_INBOUND Procedure

This procedure creates an XStream inbound server and its queue.

Note:

A client application can attach to only one inbound server at a time. See Part IV, "XStream OCI API Reference" and Oracle Streams XStream Java API Reference for information about attaching to an inbound server.
This procedure enables the inbound server that it creates.

Syntax

DBMS_XSTREAM_ADM.CREATE_INBOUND(
   server_name IN VARCHAR2,
   queue_name  IN VARCHAR2,
   apply_user  IN VARCHAR2  DEFAULT NULL,  
   comment     IN VARCHAR2  DEFAULT NULL);

Parameters

Table 7-6 CREATE_INBOUND Procedure Parameters

Parameter	Description
`server_name`	The name of the inbound server being created. A `NULL` specification is not allowed. Do not specify an owner. The specified name must not match the name of an existing outbound server, inbound server, apply process, or messaging client. Note: The `server_name` setting cannot be altered after the inbound server is created.
`queue_name`	The name of the local queue used by the inbound server, specified as `[schema_name.]queue_name`. If the specified queue exists, then it is used. If the specified queue does not exist, then the procedure creates it. For example, to specify a queue named `streams_queue` in the `strmadmin` schema, enter `strmadmin.streams_queue` for this parameter. If the schema is not specified, then the current user is the default. Note: An inbound server's queue is only used to store error transactions.
`apply_user`	The apply user. If `NULL`, then the current user is the default. The client application must attach to the inbound server as the apply user. The apply user is the user in whose security domain an inbound server evaluates whether LCRs satisfy its rule sets, applies data manipulation language (DML) and data definition language (DDL) 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 perform these actions. This 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. In addition to the privileges granted by this procedure, you also should grant the following privileges to the apply user: The necessary privileges to perform DML and DDL changes on the apply objects `EXECUTE` privilege on the rule sets used by the apply process `EXECUTE` privilege on all rule-based transformation functions used in the rule set `EXECUTE` privilege on all apply handler procedures These privileges can be granted directly to the apply user, or they can be granted through roles. In addition, the apply user must be granted `EXECUTE` privilege on all packages, including Oracle-supplied packages, that are invoked in subprograms run by the apply process. These privileges must be granted directly to the apply user. They cannot be granted through roles. Note: If the specified user is dropped using `DROP` `USER...` `CASCADE`, then the `apply_user` setting for the inbound server is set to `NULL` automatically. You must specify an apply user before the inbound server can run.
`comment`	An optional comment associated with the inbound server.

Usage Notes

By default, an inbound server does not use rules or rule sets. Therefore, an inbound server applies all of the LCRs sent to it by a client application. However, to filter the LCRs sent to an inbound server, you can add rules and rule sets to an inbound server using the DBMS_STREAMS_ADM and DBMS_RULE_ADM packages.

CREATE_OUTBOUND Procedure

This procedure creates an XStream outbound server, queue, and capture process to enable client applications to stream out Oracle database changes.

This procedure is overloaded. One table_names parameter is type VARCHAR2 and the other table_names parameters is type DBMS_UTILITY.UNCL_ARRAY. Also, one schema_names parameter is type VARCHAR2 and the other schema_names parameters is type DBMS_UTILITY.UNCL_ARRAY. These parameters enable you to enter the list of tables and schemas in different ways and are mutually exclusive.

Note:

Only one client application at a time can attach to an outbound server. See "OCIXStreamOutAttach()" and Oracle Streams XStream Java API Reference for information about attaching to an outbound server.
This procedure automatically generates a name for the capture process and the queue that it creates.
This procedure enables both the capture process and outbound server that it creates.

Syntax

DBMS_XSTREAM_ADM.CREATE_OUTBOUND(
   server_name     IN VARCHAR2,
   source_database IN VARCHAR2  DEFAULT NULL,
   table_names     IN DBMS_UTILITY.UNCL_ARRAY,
   schema_names    IN DBMS_UTILITY.UNCL_ARRAY,
   capture_user    IN VARCHAR2  DEFAULT NULL,
   connect_user    IN VARCHAR2  DEFAULT NULL,
   comment         IN VARCHAR2  DEFAULT NULL);

DBMS_XSTREAM_ADM.CREATE_OUTBOUND(
   server_name     IN VARCHAR2,
   source_database IN VARCHAR2  DEFAULT NULL,
   table_names     IN VARCHAR2  DEFAULT NULL,
   schema_names    IN VARCHAR2  DEFAULT NULL,
   capture_user    IN VARCHAR2  DEFAULT NULL,
   connect_user    IN VARCHAR2  DEFAULT NULL,
   comment         IN VARCHAR2  DEFAULT NULL);

Parameters

Table 7-7 CREATE_OUTBOUND Procedure Parameters

Parameter	Description
`server_name`	The name of the outbound server being created. A `NULL` specification is not allowed. Do not specify an owner. The specified name must not match the name of an existing outbound server, inbound server, apply process, or messaging client. Note: The `server_name` setting cannot be altered after the outbound server is created.
`source_database`	The global name of the source database. The source database is where the changes to be captured originated. If you do not include the domain name, then the procedure appends it to the database name automatically. For example, if you specify `DBS1` and the domain is `.EXAMPLE.COM`, then the procedure specifies `DBS1.EXAMPLE.COM` automatically. If `NULL`, or if the specified name is the same as the global name of the current database, then local capture is assumed. If non-`NULL` and the specified name is different from the global name of the current database, then downstream capture is assumed. In this case, configure the transmission of redo data from the source database to the downstream database before running the `CREATE_OUTBOUND` procedure. See Oracle Streams Replication Administrator's Guide for instructions.
`table_names`	The tables for which data manipulation language (DML) and data definition language (DDL) changes are streamed out to the XStream Out client application. The tables can be specified in the following ways: Comma-delimited list of type `VARCHAR2` A PL/SQL index-by table of type `DBMS_UTILITY.UNCL_ARRAY`, where each element is the name of a table. The first table should be in position 1. The last position must be `NULL`. Each table should be specified as `[schema_name.]table_name`. For example, `hr.employees`. If the schema is not specified, then the current user is the default. See Also: "Usage Notes" for more information about this parameter.
`schema_names`	The schemas for which DML and DDL changes are streamed out to the XStream Out client application. The schemas can be specified in the following ways: Comma-delimited list of type `VARCHAR2` A PL/SQL index-by table of type `DBMS_UTILITY.UNCL_ARRAY`, where each element is the name of a schema. The first schema should be in position 1. The last position must be `NULL`. See Also: "Usage Notes" for more information about this parameter.
`capture_user`	The user in whose security domain a capture process captures changes that satisfy its rule sets and runs custom rule-based transformations configured for capture process rules. If `NULL`, then the current user is the default. This procedure grants the capture user enqueue privilege on the queue used by the capture process and configures the user as a secure queue user of the queue. In addition, ensure that the capture user has the following privileges: `EXECUTE` privilege on the rule sets used by the capture process `EXECUTE` privilege on all rule-based transformation functions used in the positive rule set These privileges can be granted directly to the capture user, or they can be granted through roles. In addition, the capture user must be granted `EXECUTE` privilege on all packages, including Oracle-supplied packages, that are invoked in rule-based transformations run by the capture process. These privileges must be granted directly to the capture user. They cannot be granted through roles. Only a user who is granted `DBA` role can set a capture user. Only the `SYS` user can set the `capture_user` to `SYS`. A capture user does not require privileges on a database object to capture changes to the database object. The capture process can pass these changes to a custom rule-based transformation function. Therefore, ensure that you consider security implications when you configure a capture process.
`connect_user`	The user who can attach to the specified outbound server to retrieve the change stream. The client application must attach to the outbound server as the specified connect user. If `NULL`, then the current user is the default. The connect user is the user in whose security domain an outbound server dequeues LCRs that satisfy its rule sets and runs custom rule-based transformations configured for outbound server rules. This user must have the necessary privileges to perform these actions. This procedure grants the connect user dequeue privilege on the queue used by the outbound server and configures the user as a secure queue user of the queue. In addition to the privileges granted by this procedure, you also should grant the following privileges to the apply user: `EXECUTE` privilege on the rule sets used by the apply process `EXECUTE` privilege on all rule-based transformation functions used in the rule set These privileges can be granted directly to the connect user, or they can be granted through roles. In addition, the connect user must be granted `EXECUTE` privilege on all packages, including Oracle-supplied packages, that are invoked in subprograms run by the apply process. These privileges must be granted directly to the apply user. They cannot be granted through roles.
`comment`	An optional comment associated with the outbound server.

Usage Notes

The following list describes the behavior of the outbound server for various combinations of the table_names and schema_names parameters:

If both the table_names and schema_names parameters are NULL, then the outbound server streams all DML and DDL changes to the client application.
If both the table_names and schema_names parameters are specified, then the outbound server streams DML and DDL changes for the specified tables and schemas.
If the table_names parameter is specified and the schema_names parameter is NULL, then the outbound server streams DML and DDL changes for the specified tables.
If the table_names parameter is NULL and the schema_names parameter is specified, then the outbound server streams DML and DDL changes for the specified schema.

DROP_INBOUND Procedure

This procedure removes an inbound server configuration.

This procedure always removes the specified inbound server. This procedure also removes the queue for the inbound server if all of the following conditions are met:

One call to the CREATE_INBOUND procedure created the queue.
The inbound server is the only subscriber to the queue.

See Also:

"CREATE_INBOUND Procedure"

Syntax

DBMS_XSTREAM_ADM.DROP_INBOUND(
   server_name IN VARCHAR2);

Parameters

Table 7-8 DROP_INBOUND Procedure Parameters

Parameter	Description
`server_name`	The name of the inbound server being removed. Specify an existing inbound server. Do not specify an owner.

DROP_OUTBOUND Procedure

This procedure removes an outbound server configuration.

This procedure always drops the specified outbound server. This procedure also drops the queue used by the outbound server if both of the following conditions are met:

The queue was created by the CREATE_OUTBOUND procedure in this package.
The outbound server is the only subscriber to the queue.

If either one of these conditions is not met, then the DROP_OUTBOUND procedure only drops the outbound server. It does not drop the queue.

This procedure also drops the capture process for the outbound server if both of the following conditions are met:

The procedure can drop the outbound server's queue.
The capture process was created by the CREATE_OUTBOUND procedure.

If the procedure can drop the queue but cannot manage the capture process, then it drops the queue without dropping the capture process.

See Also:

"ADD_OUTBOUND Procedure"
"CREATE_OUTBOUND Procedure"

Syntax

DBMS_XSTREAM_ADM.DROP_OUTBOUND(
   server_name IN VARCHAR2);

Parameters

Table 7-9 DROP_OUTBOUND Procedure Parameters

Parameter	Description
`server_name`	The name of the outbound server being removed. Specify an existing outbound server. Do not specify an owner.

REMOVE_SUBSET_OUTBOUND_RULES Procedure

This procedure removes subset rules from an outbound server configuration.

The names of the specified insert, update, and delete rules must match those generated by the ADD_SUBSET_OUTBOUND_RULES procedure. To view the rule names for subset rules, run the following query:

SELECT RULE_OWNER, SUBSETTING_OPERATION, RULE_NAME 
   FROM DBA_XSTREAM_RULES 
   WHERE SUBSETTING_OPERATION IS NOT NULL;

Note:

This procedure removes the declarative rule-based transformation associated with each rule it removes.
This procedure does not remove rules from the outbound server's capture process.

See Also:

"ADD_SUBSET_OUTBOUND_RULES Procedure"

Syntax

DBMS_XSTREAM_ADM.REMOVE_SUBSET_OUTBOUND_RULES(
   server_name      IN VARCHAR2,
   insert_rule_name IN VARCHAR2, 
   update_rule_name IN VARCHAR2, 
   delete_rule_name IN VARCHAR2);

Parameters

Table 7-10 REMOVE_SUBSET_OUTBOUND_RULES Procedure Parameters

Parameter	Description
`server_name`	The name of the outbound server from which rules are being removed. Specify an existing outbound server. Do not specify an owner.
`insert_rule_name`	The name of the insert rule being removed, specified as `[schema_name.]rule_name`. For example, to specify a rule in the `hr` schema named `prop_rule1`, enter `hr.prop_rule1`. If the schema is not specified, then the current user is the default. If `NULL`, then the procedure raises an error.
`update_rule_name`	The name of the update rule being removed, specified as `[schema_name.]rule_name`. If `NULL`, then the procedure raises an error.
`delete_rule_name`	The name of the delete rule being removed, specified as `[schema_name.]rule_name`. If `NULL`, then the procedure raises an error.