65
DBMS_PROPAGATION_ADM

The DBMS_PROPAGATION_ADM package, one of a set of Streams packages, provides administrative interfaces for configuring a propagation from a source queue to a destination queue.

See Also:

Oracle Streams Concepts and Administration and Oracle Streams Replication Administrator's Guide for more information about this package and propagations

This chapter contains the following topic:

Summary of DBMS_PROPAGATION_ADM Subprograms

Summary of DBMS_PROPAGATION_ADM Subprograms

Table 65-1 DBMS_PROPAGATION_ADM Package Subprograms

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

Note:

All procedures commit unless specified otherwise.

ALTER_PROPAGATION Procedure

This procedure adds, alters, or removes a rule set for a propagation.

See Also:

Oracle Streams Concepts and Administration and Chapter 82, "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  DEFAULT NULL,
     remove_rule_set           IN  BOOLEAN   DEFAULT false,
     negative_rule_set_name    IN  VARCHAR2  DEFAULT NULL,
     remove_negative_rule_set  IN  BOOLEAN   DEFAULT false);

Parameters

Table 65-2 ALTER_PROPAGATION Procedure Parameters

Parameter	Description
`propagation_name`	The name of the propagation you are altering. You must specify an existing propagation name. Do not specify an owner.
`rule_set_name`	The name of the positive rule set for the propagation. The positive rule set contains the rules that instruct the propagation to propagate events. If you want to use a positive rule set for the propagation, then you must specify an existing rule set in the form `[``schema_name``.]``rule_set_name`. For example, to specify a positive 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_STREAMS_ADM` package or the `DBMS_RULE_ADM` package. If you specify `NULL` and the `remove_rule_set` parameter is set to `false`, then retains any existing positive rule set. If you specify `NULL` and the `remove_rule_set` parameter is set to `true`, then removes any existing positive rule set.
`remove_rule_set`	If `true`, then removes the positive rule set for the specified propagation. If you remove a positive rule set for a propagation, and the propagation does not have a negative rule set, then the propagation propagates all events. If you remove a positive rule set for a propagation, and a negative rule set exists for the propagation, then the propagation propagates all events in its queue that are not discarded by the negative rule set. If `false`, then retains the positive rule set for the specified propagation. If the `rule_set_name` parameter is non-`NULL`, then this parameter should be set to `false`.
`negative_rule_set_name`	The name of the negative rule set for the propagation. The negative rule set contains the rules that instruct the propagation to discard events. If you want to use a negative rule set for the propagation, then you must specify an existing rule set in the form `[``schema_name``.]``rule_set_name`. For example, to specify a negative rule set in the `hr` schema named `neg_rules`, enter `hr.neg_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_STREAMS_ADM` package or the `DBMS_RULE_ADM` package. If you specify `NULL` and the `remove_negative_rule_set` parameter is set to `false`, then retains any existing negative rule set. If you specify `NULL` and the `remove_negative_rule_set` parameter is set to `true`, then removes any existing negative rule set. If you specify both a positive and a negative rule set for a propagation, then the negative rule set is always evaluated first.
`remove_negative_rule_set`	If `true`, then removes the negative rule set for the specified propagation. If you remove a negative rule set for a propagation, and the propagation does not have a positive rule set, then the propagation propagates all events. If you remove a negative rule set for a propagation, and a positive rule set exists for the propagation, then the propagation propagates all events in its queue that are not discarded by the positive rule set. If `false`, then retains the negative rule set for the specified propagation. If the `negative_rule_set_name` parameter is non-`NULL`, then this parameter should be set to `false`.

This procedure creates a propagation and specifies the source queue, destination queue, and any rule set for the propagation. A propagation 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.

This procedure also starts propagation and establishes a default schedule for its 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.
See Also:

Chapter 82, "DBMS_RULE_ADM"

Oracle Streams Concepts and Administration

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,
     negative_rule_set_name  IN  VARCHAR2  DEFAULT NULL);

Parameters

Table 65-3 CREATE_PROPAGATION Procedure Parameters

Parameter	Description
`propagation_name`	The name of the propagation you are creating. A `NULL` setting is not allowed. Do not specify an owner. Note: The `propagation_name` setting cannot be altered after the propagation is created.
`source_queue`	The name of the source queue, specified as `[``schema_name``.]``queue_name`. The current database must contain the source queue. For example, to specify a source 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.
`destination_queue`	The name of the destination queue, specified as `[``schema_name``.]``queue_name`. For example, to specify a destination 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.
`destination_dblink`	The name of the database link that will be used by the propagation. 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 positive rule set for the propagation. The positive rule set contains the rules that instruct the propagation to propagate events. If you want to use a positive rule set for the propagation, then you must specify an existing rule set in the form `[``schema_name``.]``rule_set_name`. For example, to specify a positive 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_STREAMS_ADM` package or the `DBMS_RULE_ADM` package. If you specify `NULL`, and no negative rule set exists for the propagation, then the propagation propagates all events in its queue. If you specify `NULL`, and a negative rule set exists for the propagation, then the propagation propagates all events in its queue that are not discarded by the negative rule set.
`negative_rule_set_name`	The name of the negative rule set for the propagation. The negative rule set contains the rules that instruct the propagation to discard events. If you want to use a negative rule set for the propagation, then you must specify an existing rule set in the form `[``schema_name``.]``rule_set_name`. For example, to specify a negative rule set in the `hr` schema named `neg_rules`, enter `hr.neg_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_STREAMS_ADM` package or the `DBMS_RULE_ADM` package. If you specify `NULL`, and no positive rule set exists for the propagation, then the propagation propagates all events in its queue. If you specify `NULL`, and a positive rule set exists for the propagation, then the propagation propagates all events in its queue that are not discarded by the positive rule set. If you specify both a positive and a negative rule set for a propagation, then the negative rule set is always evaluated first.

Usage Notes

If no propagation job exists for the database link specified when this procedure is run, then a propagation job is created for use by the propagation. If a propagation job is created, then the user who runs this procedure owns the propagation job. If a propagation job already exists for the specified database link, then the existing propagation job is used.

You can administer a propagation job 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 propagations that use the propagation job.

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
Execute privilege on all rule-based 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 propagates events to a destination queue in a remote database, then the owner of the source queue must be able to use the propagation'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 is used by multiple propagations to propagate 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.

DROP_PROPAGATION Procedure

This procedure drops a propagation and deletes all captured and user-enqueued events 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,
   drop_unused_rule_sets  IN  BOOLEAN  DEFAULT false);

Parameters

Table 65-4 DROP_PROPAGATION Procedure Parameters

Parameter Description

Parameter	Description
`propagation_name`	The name of the propagation you are dropping. You must specify an existing propagation name. Do not specify an owner.
`drop_unused_rule_sets`	If `true`, then drops any rule sets, positive and negative, used by the specified propagation if these rule sets are not used by any other Streams client, which includes capture processes, propagations, apply processes, and messaging clients. If this procedure drops a rule set, then this procedure also drops any rules in the rule set that are not in another rule set. If `false`, then does not drop the rule sets used by the specified propagation, and the rule sets retain their rules.

propagation_name

The name of the propagation you are dropping. You must specify an existing propagation name. Do not specify an owner.

drop_unused_rule_sets

If true, then drops any rule sets, positive and negative, used by the specified propagation if these rule sets are not used by any other Streams client, which includes capture processes, propagations, apply processes, and messaging clients. If this procedure drops a rule set, then this procedure also drops any rules in the rule set that are not in another rule set.

If false, then does not drop the rule sets used by the specified propagation, and the rule sets retain their rules.

Usage Notes

When you use this procedure to drop a propagation, information about rules created for the propagation using the DBMS_STREAMS_ADM package is removed from the data dictionary views for Streams rules. Information about such a rule is removed even if the rule is not in either rule set for the propagation.

See Also:

Oracle Streams Concepts and Administration for more information about Streams data dictionary views

The following are the data dictionary views for Streams rules:

ALL_STREAMS_GLOBAL_RULES
DBA_STREAMS_GLOBAL_RULES
ALL_STREAMS_MESSAGE_RULES
DBA_STREAMS_MESSAGE_RULES
ALL_STREAMS_SCHEMA_RULES
DBA_STREAMS_SCHEMA_RULES
ALL_STREAMS_TABLE_RULES
DBA_STREAMS_TABLE_RULES

Note:
When you drop a propagation, the propagation job used by the propagation is dropped automatically, if no other propagations are using the propagation job.

65 DBMS_PROPAGATION_ADM

Summary of DBMS_PROPAGATION_ADM Subprograms

Table 65-1 DBMS_PROPAGATION_ADM Package Subprograms

ALTER_PROPAGATION Procedure

Syntax

Parameters

Table 65-2 ALTER_PROPAGATION Procedure Parameters

CREATE_PROPAGATION Procedure

Syntax

Parameters

Table 65-3 CREATE_PROPAGATION Procedure Parameters

Usage Notes

DROP_PROPAGATION Procedure

Syntax

Parameters

Table 65-4 DROP_PROPAGATION Procedure Parameters

Usage Notes

65
DBMS_PROPAGATION_ADM