DBMS_CAPTURE_ADM, 2 of 2

Summary of DBMS_CAPTURE_ADM Subprograms

Table 8-1 DBMS_CAPTURE_ADM Subprograms

Subprogram	Description
"ABORT_GLOBAL_INSTANTIATION Procedure"	Reverses the effects of running the `PREPARE_GLOBAL_INSTANTIATION` procedure
"ABORT_SCHEMA_INSTANTIATION Procedure"	Reverses the effects of running the `PREPARE_SCHEMA_INSTANTIATION` procedure
"ABORT_TABLE_INSTANTIATION Procedure"	Reverses the effects of running the `PREPARE_TABLE_INSTANTIATION` procedure
"ALTER_CAPTURE Procedure"	Alters a capture process
"CREATE_CAPTURE Procedure"	Creates a capture process
"DROP_CAPTURE Procedure"	Drops a capture process
"PREPARE_GLOBAL_INSTANTIATION Procedure"	Performs the synchronization necessary for instantiating all the tables in the database at another database
"PREPARE_SCHEMA_INSTANTIATION Procedure"	Performs the synchronization necessary for instantiating all tables in the schema at another database
"PREPARE_TABLE_INSTANTIATION Procedure"	Performs the synchronization necessary for instantiating the table at another database
"SET_PARAMETER Procedure"	Sets a capture process parameter to the specified value
"START_CAPTURE Procedure"	Starts the capture process, which mines redo logs and enqueues the mined redo information into the associated queue
"STOP_CAPTURE Procedure"	Stops the capture process from mining redo logs

Note:

All procedures commit unless specified otherwise.

ABORT_GLOBAL_INSTANTIATION Procedure

Reverses the effects of running the PREPARE_GLOBAL_INSTANTIATION procedure.

Specifically, running this procedure removes data dictionary information related to the database instantiation.

Syntax

DBMS_CAPTURE_ADM.ABORT_GLOBAL_INSTANTIATION();

ABORT_SCHEMA_INSTANTIATION Procedure

Reverses the effects of running the PREPARE_SCHEMA_INSTANTIATION procedure.

Specifically, running this procedure removes data dictionary information related to the schema instantiation.

Syntax

DBMS_CAPTURE_ADM.ABORT_SCHEMA_INSTANTIATION(
   schema_name    IN   VARCHAR2);

Parameter

Table 8-2 ABORT_SCHEMA_INSTANTIATION Procedure Parameter

Parameter	Description
`schema_name`	The name of the schema for which to abort the effects of preparing instantiation.

ABORT_TABLE_INSTANTIATION Procedure

Reverses the effects of running the PREPARE_TABLE_INSTANTIATION procedure.

Specifically, running this procedure removes data dictionary information related to the table instantiation.

Syntax

DBMS_CAPTURE_ADM.ABORT_TABLE_INSTANTIATION(
   table_name    IN   VARCHAR2);

Parameter

Table 8-3 ABORT_TABLE_INSTANTIATION Procedure Parameter

Parameter	Description
`table_name`	The name of the table for which to abort the effects of preparing instantiation, specified as `[``schema_name``.]``object_name`. For example, `hr.employees`. If the schema is not specified, then the current user is the default.

ALTER_CAPTURE Procedure

Alters a capture process.

Syntax

DBMS_CAPTURE_ADM.ALTER_CAPTURE(
   capture_name      IN VARCHAR2,
   rule_set_name     IN VARCHAR2  DEFAULT NULL,
   remove_rule_set   IN BOOLEAN   DEFAULT false,
   start_scn         IN NUMBER    DEFAULT NULL);

Parameters

Table 8-4 ALTER_CAPTURE Procedure Parameters

Parameter	Description
`capture_name`	The name of the capture process being altered. You must specify an existing capture process name.
`rule_set_name`	The name of the rule set that contains the capture rules for this capture process. If you want to use a rule set for the capture process, then you must specify an existing rule set in the form `[``schema_name``.]``rule_set_name`. For example, to specify a rule set in the `hr` schema named `job_capture_rules`, enter `hr.job_capture_rules`. If the schema is not specified, then the current user is the default. An error is returned if the specified rule set does not exist. You can create a rule set and add rules to it using the `DBMS_RULE_ADM` package. See Also: Oracle9i Streams for more information about the changes that can be captured by a capture process
`remove_rule_set`	If `true`, then removes the rule set for the specified capture process. If you remove a rule set for a capture process, then the capture process captures all supported changes to all objects in the database, excluding database objects in the `SYS` and `SYSTEM` schemas. If `false`, then retains any rule set for the specified capture process. If the `rule_set_name` parameter is non-`NULL`, then this parameter should be set to `false`.
`start_scn`	A valid past SCN for the database where the capture process is capturing changes. The capture process will capture changes starting at the SCN specified. The SCN value specified must be from a point-in-time after the first capture process was created for the database. The first capture process for the database may or may not be the capture process being altered. An error is returned if an invalid SCN is specified. Note: When you change the start SCN for a capture process, the capture process is stopped and restarted automatically.

CREATE_CAPTURE Procedure

Creates a capture process.

The user who runs the CREATE_CAPTURE procedure is the user who captures changes. This user must have the necessary privileges to capture changes. These privileges include the following:

Execute privilege on the rule set used by the capture process
Execute privilege on all transformation functions used in the rule set
Enqueue privilege on the queue used by the capture process

Note:
Creation of the first capture process in a database may take some time because the data dictionary is duplicated during this creation.

See Also:
Oracle9i Streams and Chapter 64, "DBMS_RULE_ADM" for more information about rules and rule sets

Syntax

DBMS_CAPTURE_ADM.CREATE_CAPTURE(
   queue_name      IN VARCHAR2,
   capture_name    IN VARCHAR2,
   rule_set_name   IN VARCHAR2  DEFAULT NULL,
   start_scn       IN NUMBER    DEFAULT NULL);

Parameters

Table 8-5 CREATE_CAPTURE Procedure Parameters

Parameter	Description
`queue_name`	The name of the queue into which the capture process enqueues changes. You must specify an existing queue in the form `[``schema_name``.]``queue_name`. For example, to specify a queue in the `hr` schema named `streams_queue`, enter `hr.streams_queue`. If the schema is not specified, then the current user is the default. Note: The `queue_name` setting cannot be altered after the capture process is created.
`capture_name`	The name of the capture process being created. A `NULL` specification is not allowed. Note: The `capture_name` setting cannot be altered after the capture process is created.
`rule_set_name`	The name of the rule set that contains the capture rules for this capture process. If you want to use a rule set for the capture process, then you must specify an existing rule set in the form `[``schema_name``.]``rule_set_name`. For example, to specify a rule set in the `hr` schema named `job_capture_rules`, enter `hr.job_capture_rules`. If the schema is not specified, then the current user is the default. An error is returned if the specified rule set does not exist. You can create a rule set and add rules to it using the `DBMS_RULE_ADM` package. If you specify `NULL`, then the capture process captures all supported changes to all objects in the database, excluding database objects in the `SYS` and `SYSTEM` schemas. See Also: Oracle9i Streams for more information about the changes that can be captured by a capture process
`start_scn`	A valid past SCN for the database where the capture process is capturing changes. The capture process will capture changes starting at the SCN specified. The SCN value specified must be from a point in time after the first capture process was created for the database. If the capture process being created is the first capture process ever created for the current database, then you must specify `NULL` for the `start_scn`. An error is returned if an invalid SCN is specified.

DROP_CAPTURE Procedure

Drops a capture process.

Syntax

DBMS_CAPTURE_ADM.DROP_CAPTURE(
   capture_name    IN VARCHAR2);

Parameter

Table 8-6 DROP_CAPTURE Procedure Parameter

Parameter	Description
`capture_name`	The name of the capture process being dropped. Specify an existing capture process name.

PREPARE_GLOBAL_INSTANTIATION Procedure

Performs the synchronization necessary for instantiating all the tables in the database at another database. Run this procedure at the source database.

This procedure records the lowest SCN of each object in the database for instantiation. SCNs subsequent to the lowest SCN for an object can be used for instantiating the object. Running this procedure prepares all current and future objects in the database for instantiation.

Syntax

DBMS_CAPTURE_ADM.PREPARE_GLOBAL_INSTANTIATION;

PREPARE_SCHEMA_INSTANTIATION Procedure

Performs the synchronization necessary for instantiating all tables in the schema at another database. Run this procedure at the source database.

This procedure records the lowest SCN of each object in the schema for instantiation. SCNs subsequent to the lowest SCN for an object can be used for instantiating the object. Running this procedure prepares all current and future objects in the schema for instantiation.

Syntax

DBMS_CAPTURE_ADM.PREPARE_SCHEMA_INSTANTIATION(
   schema_name  IN VARCHAR2);

Parameter

Table 8-7 PREPARE_SCHEMA_INSTANTIATION Procedure Parameter

Parameter	Description
`schema_name`	The name of the schema. For example, `hr`.

PREPARE_TABLE_INSTANTIATION Procedure

Performs the synchronization necessary for instantiating the table at another database. Run this procedure at the source database.

This procedure records the lowest SCN of the table for instantiation. SCNs subsequent to the lowest SCN for an object can be used for instantiating the object.

Syntax

DBMS_CAPTURE_ADM.PREPARE_TABLE_INSTANTIATION(
   table_name  IN VARCHAR2);

Parameters

Table 8-8 PREPARE_TABLE_INSTANTIATION Procedure Parameter

Parameter	Description
`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.

SET_PARAMETER Procedure

Sets a capture process parameter to the specified value.

When you alter a parameter value, a short amount of time may pass before the new value for the parameter takes effect.

Syntax

DBMS_CAPTURE_ADM.SET_PARAMETER(
   capture_name   IN VARCHAR2,
   parameter      IN VARCHAR2,
   value          IN VARCHAR2);

Parameters

Table 8-9 SET_PARAMETER Procedure Parameters

Parameter	Description
`capture_name`	The name of the capture process. The capture process uses LogMiner to capture changes from the redo logs.
`parameter`	The name of the parameter you are setting. See "Capture Process Parameters" for a list of these parameters.
`value`	The value to which the parameter is set

Capture Process Parameters

The following table lists the parameters for the capture process.

Table 8-10 Capture Process Parameters (Page 1 of 2)

Parameter Name	Possible Values	Default	Description
`disable_on_limit`	`Y` or `N`	`N`	If `Y`, then the capture process is disabled if the capture process terminates because it reached a value specified by the `time_limit` parameter or `message_limit` parameter. If `N`, then the capture process is restarted immediately after stopping because it reached a limit.
`maximum_scn`	A valid SCN or `infinite`	`infinite`	The capture process is disabled before capturing a change record with an SCN greater than or equal to the value specified. If `infinite`, then the capture process runs regardless of the SCN value.
`message_limit`	A positive integer or `infinite`	`infinite`	The capture process stops after capturing the specified number of messages. If `infinite`, then the capture process continues to run regardless of the number of messages captured.
`parallelism`	A positive integer	`1`	The number of parallel execution servers that may concurrently mine the redo log Note: When you change the value of this parameter, the capture process is stopped and restarted automatically. Setting the `parallelism` parameter to a number higher than the number of available parallel execution servers may disable the capture process. Make sure the `PROCESSES` and `PARALLEL_MAX_SERVERS` initialization parameters are set appropriately when you set the `parallelism` capture process parameter.
`startup_seconds`	`0`, a positive integer, or `infinite`	`0`	The maximum number of seconds to wait for another instantiation of the same capture process to finish. If the other instantiation of the same capture process does not finish within this time, then the capture process does not start. If `infinite`, then a capture process does not start until another instantiation of the same capture process finishes.
`time_limit`	A positive integer or `infinite`	`infinite`	The capture process stops as soon as possible after the specified number of seconds since it started. If `infinite`, then the capture process continues to run until it is stopped explicitly.
`trace_level`	`0` or a positive integer	`0`	Set this parameter only under the guidance of Oracle Support Services.
`write_alert_log`	`Y` or `N`	`Y`	If `Y`, then the capture process writes a message to the alert log on exit. If `N`, then the capture process does not write a message to the alert log on exit. The message specifies the reason the capture process stopped.

Note:

For all parameters that are interpreted as positive integers, the maximum possible value is 4,294,967,295. Where applicable, specify infinite for larger values.
For parameters that require an SCN setting, any valid SCN value can be specified.

START_CAPTURE Procedure

Starts the capture process, which mines redo logs and enqueues the mined redo information into the associated queue.

The start status is persistently recorded. Hence, if the status is ENABLED, then the capture process is started upon database instance startup.

The capture process is a background Oracle process and is prefixed by CP.

The enqueue and dequeue state of DBMS_AQADM.START_QUEUE and DBMS_AQADM.STOP_QUEUE have no effect on the start status of a capture process.

You can create the capture process using the following procedures:

DBMS_CAPTURE_ADM.CREATE_CAPTURE
DBMS_STREAMS_ADM.ADD_GLOBAL_RULES
DBMS_STREAMS_ADM.ADD_SCHEMA_RULES
DBMS_STREAMS_ADM.ADD_TABLE_RULES

See Also:
Chapter 73, "DBMS_STREAMS_ADM"

Syntax

DBMS_CAPTURE_ADM.START_CAPTURE(
   capture_name  IN VARCHAR2);

Parameter

Table 8-11 START_CAPTURE Procedure Parameter

Parameter	Description
`capture_name`	The name of the capture process. The capture process uses LogMiner to capture changes in the redo information. A `NULL` setting is not allowed.

STOP_CAPTURE Procedure

Stops the capture process from mining redo logs.

The stop status is persistently recorded. Hence, if the status is DISABLED, then the capture process is not started upon database instance startup.

The enqueue and dequeue state of DBMS_AQADM.START_QUEUE and DBMS_AQADM.STOP_QUEUE have no effect on the stop status of a capture process.

Syntax

DBMS_CAPTURE_ADM.STOP_CAPTURE(
   capture_name  IN VARCHAR2,
   force         IN BOOLEAN  DEFAULT false);

Parameters

Table 8-12 STOP_CAPTURE Procedure Parameters

Parameter Description

Parameter	Description
`capture_name`	The name of the capture process. A `NULL` setting is not allowed.
`force`	If `TRUE`, then stops the capture process instantly. If `FALSE`, then stops the capture process after the capture process captures its current transaction.

capture_name

The name of the capture process. A NULL setting is not allowed.

force

If TRUE, then stops the capture process instantly.

If FALSE, then stops the capture process after the capture process captures its current transaction.