Oracle® Database PL/SQL Packages and Types Reference 10g Release 2 (10.2) Part Number B14258-01 |
|
|
View PDF |
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 propagationsThis chapter contains the following topic:
Table 74-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 |
START_PROPAGATION Procedure |
Starts a propagation |
STOP_PROPAGATION Procedure |
Stops a propagation |
Note:
All subprograms commit unless specified otherwise.This procedure adds, alters, or removes a rule set for a propagation.
See Also:
Oracle Streams Concepts and Administration and Chapter 92, "DBMS_RULE_ADM" for more information about rules and rule setsSyntax
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 74-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 messages.
If you want to use a positive rule set for the propagation, then you must specify an existing rule set in the form 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 If you specify |
remove_rule_set |
If TRUE , then the procedure 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 messages.
If you remove a positive rule set for a propagation, and a negative rule set exists for the propagation, then the propagation propagates all messages in its queue that are not discarded by the negative rule set. If If the |
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 messages.
If you want to use a negative rule set for the propagation, then you must specify an existing rule set in the form 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 If you specify 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 the procedure 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 messages.
If you remove a negative rule set for a propagation, and a positive rule set exists for the propagation, then the propagation propagates all messages in its queue that are not discarded by the positive rule set. If If the |
This procedure creates a propagation and specifies the source queue, destination queue, and any rule set for the propagation. A propagation propagates messages in a local source queue to a destination queue. The destination queue might or might not be in the same database as the source queue.
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, queue_to_queue IN BOOLEAN DEFAULT NULL);
Parameters
Table 74-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 |
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 |
destination_queue |
The name of the destination queue, specified as [ schema_name .] queue_name .
For example, to specify a destination queue named |
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 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 messages.
If you want to use a positive rule set for the propagation, then you must specify an existing rule set in the form 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 If you specify If you specify |
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 messages.
If you want to use a negative rule set for the propagation, then you must specify an existing rule set in the form 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 If you specify If you specify If you specify both a positive and a negative rule set for a propagation, then the negative rule set is always evaluated first. |
queue_to_queue |
If TRUE , then the propagation is a queue to queue propagation. A queue-to-queue propagation always has its own propagation job and uses a service for automatic failover when the destination queue is a buffered queue in a Real Application Clusters (RAC) database.
If See Also: Oracle Streams Concepts and Administration for more information about queue-to-queue propagations |
Usage Notes
This procedure starts propagation and might create a propagation job. If this procedure creates a propagation job, then it establishes a default schedule for the propagation job.
The user who owns the source queue is the user who propagates messages. This user must have the necessary privileges to propagate messages.
See Also:
Oracle Streams Concepts and Administration for more information about propagations, the privileges required to propagate messages, propagation jobs, and propagation schedules
This procedure drops a propagation and deletes all captured and user-enqueued 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, drop_unused_rule_sets IN BOOLEAN DEFAULT FALSE);
Parameters
Table 74-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 the procedure 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 |
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 viewsThe 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.This procedure starts a propagation.
Syntax
DBMS_PROPAGATION_ADM.START_PROPAGATION( propagation_name IN VARCHAR2);
Parameter
Table 74-5 START_PROPAGATION Procedure Parameter
Parameter | Description |
---|---|
propagation_name |
The name of the propagation you are starting. You must specify an existing propagation name. Do not specify an owner. |
Usage Notes
The propagation status is persistently recorded. Hence, if the status is ENABLED
, then the propagation is started upon database instance startup.
This procedure stops a propagation.
Syntax
DBMS_PROPAGATION_ADM.STOP_PROPAGATION( propagation_name IN VARCHAR2, force IN BOOLEAN DEFAULT FALSE);
Parameter
Table 74-6 STOP_PROPAGATION Procedure Parameter
Parameter | Description |
---|---|
propagation_name |
The name of the propagation you are stopping. You must specify an existing propagation name. Do not specify an owner. |
force |
If TRUE , then the procedure stops the propagation and clears the statistics for the propagation.
If |
Usage Notes
The propagation status is persistently recorded. Hence, if the status is DISABLED
or ABORTED
, then the propagation is not started upon database instance startup.