Skip Headers

PL/SQL Packages and Types Reference
10g Release 1 (10.1)

Part Number B10802-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

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

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.


CREATE_PROPAGATION Procedure

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:

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:

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:

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

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: