DBMS_PROPAGATION_ADM, 2 of 2

Summary of DBMS_PROPAGATION_ADM Subprograms

Table 47-1 DBMS_PROPAGATION_ADM Subprograms

Subprogram	Description
"ALTER_PROPAGATION Procedure"	Adds, alters, or removes a rule set for a propagation job
"CREATE_PROPAGATION Procedure"	Creates a propagation job and specifies the source queue, destination queue, and rule set for the propagation job.
"DROP_PROPAGATION Procedure"	Drops a propagation job

Note:

All procedures commit unless specified otherwise.

ALTER_PROPAGATION Procedure

Adds, alters, or removes a rule set for a propagation job.

See Also:

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

Syntax

  DBMS_PROPAGATION_ADM.ALTER_PROPAGATION(
     propagation_name   IN VARCHAR2,
     rule_set_name      IN VARCHAR2);

Parameters

Table 47-2 ALTER_PROPAGATION Procedure Parameters

Parameter Description

Parameter	Description
`propagation_name`	The name of the propagation job being altered. You must specify an existing propagation job name.
`rule_set_name`	The name of the rule set that contains the propagation rules for this propagation job. If you want to use a rule set for the propagation job, 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 `prop_rules`, enter `hr.prop_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 propagation job propagates all LCRs and user messages in its queue.

propagation_name

The name of the propagation job being altered. You must specify an existing propagation job name.

rule_set_name

The name of the rule set that contains the propagation rules for this propagation job. If you want to use a rule set for the propagation job, 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 prop_rules, enter hr.prop_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 propagation job propagates all LCRs and user messages in its queue.

CREATE_PROPAGATION Procedure

Creates a propagation job and specifies the source queue, destination queue, and any rule set for the propagation job. A propagation job propagates events in a local source queue to a destination queue. The destination queue may or may not be in the same database as the source queue. The user who runs this procedure owns the propagation job.

This procedure also starts propagation and establishes a default schedule for the propagation job. The default schedule has the following properties:

The start time is SYSDATE().
The duration is NULL, which means infinite.
The next time is NULL, which means that propagation restarts as soon as it finishes the current duration.
The latency is five seconds, which is the wait time for a message to be propagated to a destination queue after it is enqueued into a queue with no messages requiring propagation to the same destination queue.

After the propagation job is created, you can administer it using the following procedures in the DBMS_AQADM package:

To alter the default schedule for a propagation job, use the ALTER_PROPAGATION_SCHEDULE procedure.
To stop propagation, use the DISABLE_PROPAGATION_SCHEDULE procedure and specify the source queue for the queue_name parameter and the database link for the destination parameter.
To restart propagation, use the ENABLE_PROPAGATION_SCHEDULE procedure and specify the source queue for the queue_name parameter and the database link for the destination parameter. Restarting propagation may be necessary if a propagation job is disabled automatically due to errors.

These types of changes affect all propagation jobs on the database link for the source queue.

The user who owns the source queue is the user who propagates events. This user must have the necessary privileges to propagate events. These privileges include the following:

Execute privilege on the rule set used by the propagation job
Execute privilege on all transformation functions used in the rule set
Enqueue privilege on the destination queue if the destination queue is in the same database

If the propagation job propagates events to a destination queue in a remote database, then the owner of the source queue must be able to use the propagation job's database link and the user to which the database link connects at the remote database must have enqueue privilege on the destination queue.

Note:

Currently, a single propagation job propagates all events that use a particular database link, even if the database link propagates events to multiple destination queues.
The source queue owner performs the propagation, but the propagation job is owned by the user who creates it. These two users may or may not be the same.

See Also:

Syntax

  DBMS_PROPAGATION_ADM.CREATE_PROPAGATION(
     propagation_name         IN VARCHAR2,
     source_queue             IN VARCHAR2,
     destination_queue        IN VARCHAR2,
     destination_dblink       IN VARCHAR2  DEFAULT NULL,
     rule_set_name            IN VARCHAR2  DEFAULT NULL);

Parameters

Table 47-3 CREATE_PROPAGATION Procedure Parameters

Parameter	Description
`propagation_name`	The name of the propagation job being created. A `NULL` setting is not allowed.
`source_queue`	The name of the source queue. The current database must contain the source queue.
`destination_queue`	The name of the destination queue
`destination_dblink`	The name of the database link that will be used by the propagation job. The database link is from the database that contains the source queue to the database that contains the destination queue. If `NULL`, then the source queue and destination queue must be in the same database. Note: Connection qualifiers are not allowed.
`rule_set_name`	The name of the rule set that contains the propagation rules for this propagation job. 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 `prop_rules`, enter `hr.prop_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 propagation job propagates all LCRs and user messages in its queue.

DROP_PROPAGATION Procedure

Drops a propagation job and deletes all messages for the destination queue in the source queue. This procedure also removes the schedule for propagation from the source queue to the destination queue.

Syntax

DBMS_PROPAGATION_ADM.DROP_PROPAGATION(
   propagation_name      IN VARCHAR2);

Parameter

Table 47-4 DROP_PROPAGATION Procedure Parameter

Parameter	Description
`propagation_name`	The name of the propagation job being dropped. You must specify an existing propagation job name.