Skip Headers

Oracle9i Streams
Release 2 (9.2)

Part Number A96571-02
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 Go to next page
View PDF

8
Streams Tags

This chapter explains the concepts related to Streams tags.

This chapter contains these topics:

Introduction to Tags

Every redo entry in the redo log has a tag associated with it. The datatype of the tag is RAW. By default, when a user or application generates redo entries, the value of the tag is NULL for each redo entry, and a NULL tag consumes no space in the redo entry. The size limit for a tag value is 2000 bytes.

You can configure how tag values are interpreted. For example, a tag can be used to determine whether an LCR contains a change that originated in the local database or at a different database, so that you can avoid change cycling (sending an LCR back to the database where it originated). Tags may be used for other LCR tracking purposes as well. You can also use tags to specify the set of destination databases for each LCR.

You can control the value of the tags generated in the redo log in the following ways:

These tags become part of the LCRs captured by a capture process retrieving changes from the redo log. Based on the rules in the rule set for the capture process, the tag value in the redo entry for a change may determine whether or not the change is captured.

Similarly, once a tag is part of an LCR, the value of the tag may determine whether a propagation propagates the LCR and whether an apply process applies the LCR. The behavior of a transformation, DML handler, or error handler can also depend on the value of the tag. In addition, you can set the tag value for an existing LCR using the SET_TAG member procedure for the LCR. For example, you may set a tag in an LCR during a transformation.

See Also:

Oracle9i Supplied PL/SQL Packages and Types Reference for more information about the SET_TAG member procedure for LCRs

Tags and Rules Created by the DBMS_STREAMS_ADM Package

When you use a procedure in the DBMS_STREAMS_ADM package to create rules, by default each rule contains a condition that evaluates to TRUE only if the tag is NULL. In DML rules, the condition is the following:

:dml.is_null_tag()='Y'

In DDL rules, the condition is the following:

:ddl.is_null_tag()='Y'

Consider a rule set with a single rule and assume the rule contains such a condition. In this case, Streams capture processes, propagations, and apply processes behave in the following way:

Specifically, the following procedures in the DBMS_STREAMS_ADM package create rules that contain one of these conditions by default:

If you do not want the created rules to contain such a condition, then set the include_tagged_lcr parameter to true when you run these procedures. This setting results in no conditions relating to tags in the rules. Therefore, rule evaluation of the LCR does not depend on the value of the tag.

For example, consider a table-level rule that evaluates to TRUE for all DML changes to the hr.locations table that originated at the dbs1.net source database.

Assume the ADD_TABLE_RULES procedure is run to generate this rule:

BEGIN DBMS_STREAMS_ADM.ADD_TABLE_RULES(
   table_name               =>  'hr.locations',
   streams_type             =>  'capture',
   streams_name             =>  'capture',
   queue_name               =>  'streams_queue',
   include_tagged_lcr       =>  false,  -- Note parameter setting
   source_database          =>  'dbs1.net',
   include_dml              =>  true,
   include_ddl              =>  false);
END;
/

Notice that the include_tagged_lcr parameter is set to false, which is the default. The ADD_TABLE_RULES procedure generates a rule with a rule condition similar to the following:

(((:dml.get_object_owner() = 'HR' and :dml.get_object_name() = 'LOCATIONS')) 
and :dml.is_null_tag() = 'Y' and :dml.get_source_database_name() = 'DBS1.NET' )

If a capture process uses a rule set that contains this rule, then the rule evaluates to FALSE if the tag for a change in a redo entry is a non-NULL value, such as '0' or '1'. So, if a redo entry contains a row change to the hr.locations table, then the change is captured only if the tag for the redo entry is NULL.

However, suppose the include_tagged_lcr parameter is set to true when ADD_TABLE_RULES is run:

BEGIN DBMS_STREAMS_ADM.ADD_TABLE_RULES(
   table_name               =>  'hr.locations',
   streams_type             =>  'capture',
   streams_name             =>  'capture',
   queue_name               =>  'streams_queue',
   include_tagged_lcr       =>  true,   -- Note parameter setting
   source_database          =>  'dbs1.net',
   include_dml              =>  true,
   include_ddl              =>  false);
END;
/

In this case, the ADD_TABLE_RULES procedure generates a rule with a rule condition similar to the following:

(((:dml.get_object_owner() = 'HR' and :dml.get_object_name() = 'LOCATIONS')) 
and :dml.get_source_database_name() = 'DBS1.NET' )

Notice that there is no condition relating to the tag. If a capture process uses a rule set that contains this rule, then the rule evaluates to TRUE if the tag in a redo entry for a DML change to the hr.locations table is a non-NULL value, such as '0' or '1'. The rule also evaluates to TRUE if the tag is NULL. So, if a redo entry contains a DML change to the hr.locations table, then the change is captured regardless of the value for the tag.

If you want to modify the is_null_tag condition in a system-created rule, then you should use an appropriate procedure in the DBMS_STREAMS_ADM package to create a new rule that is the same as the rule you want to modify, except for the is_null_tag condition. Then, use the REMOVE_RULE procedure in the DBMS_STREAMS_ADM package to remove the old rule from the appropriate rule set.

If you created a rule with the DBMS_RULE_ADM package, then you can add, remove, or modify the is_null_tag condition in the rule by using the ALTER_RULE procedure in this package.

If you are using global rules to capture and apply DDL changes for an entire database, then online backup statements will be captured, propagated, and applied by default. Typically, database administrators do not want to replicate online backup statements. Instead, they only want them to run at the database where they are executed originally. To avoid replicating online backup statements, you can use one of the following strategies:

Tags and an Apply Process

An apply process generates entries in the redo log of a destination database when it applies DML or DDL changes. For example, if the apply process applies a change that updates a row in a table, then that change is recorded in the redo log at the destination database. You can control the tags in these redo entries by setting the apply_tag parameter in the CREATE_APPLY or ALTER_APPLY procedure in the DBMS_APPLY_ADM package. For example, an apply process may generate redo tags that are equivalent to the hexadecimal value of '0' (zero) or '1'.

The default tag value generated in the redo log by an apply process is '00' (double zero). This value is the default tag value for an apply process if you use a procedure in the DBMS_STREAMS_ADM package or the CREATE_APPLY procedure in the DBMS_APPLY_ADM package to create an apply process. There is nothing special about this value beyond the fact that it is a non-NULL value. The fact that it is a non-NULL value is important because rules created by the DBMS_STREAMS_ADM package by default contain a condition that evaluates to TRUE only if the tag is NULL in a redo entry or LCR. You can alter the tag value for an existing apply process using the ALTER_APPLY procedure in the DBMS_APPLY_ADM package.

If a DML handler, DDL handler, or message handler calls the SET_TAG procedure in the DBMS_STREAMS package, then any subsequent redo entries generated by the handler will include the tag specified in the SET_TAG call, even if the tag for the apply process is different. When the handler exits, any subsequent redo entries generated by the apply process have the tag specified for the apply process.

See Also:

Avoid Change Cycling with Tags

In a Streams environment that includes more than one database sharing data bidirectionally, you can use tags to avoid change cycling. Change cycling means sending a change back to the database where it originated. Typically, change cycling should be avoided because it can result in each change going through endless loops back to the database where it originated. Such loops can result in unintended data in the database and tax the networking and computer resources of an environment. By default, Streams is designed to avoid change cycling.

Using tags and appropriate rules for Streams capture processes, propagations, and apply processes, you can avoid such change cycles. The following sections describe various Streams environments and how tags and rules can be used to avoid change cycling in these environments:

Each Databases Is a Source and Destination Database for Shared Data

This scenario involves a Streams environment in which each database is a source database for every other database, and each database is a destination database of every other database. Each database communicates directly with every other database.

For example, consider an environment that replicates the database objects and data in the hr schema between three Oracle databases: mult1.net, mult2.net, and mult3.net. DML and DDL changes made to tables in the hr schema are captured at all three databases in the environment and propagated to each of the other databases in the environment, where changes are applied. Figure 8-1 illustrates an example environment in which each database is a source database.

Figure 8-1 Each Database Is a Source and Destination Database

Text description of strms025.gif follows
Text description of the illustration strms025.gif


You can avoid change cycles by configuring such an environment in the following way:

This configuration prevents change cycling because all of the changes applied by the apply processes are never recaptured (they were captured originally at the source databases). Each database sends all of its changes to the hr schema to every other database. So, in this environment, no changes are lost, and all databases are synchronized. Figure 8-2 illustrates how tags can be used in a database in a multiple source environment.

Figure 8-2 Tag Use When Each Database Is a Source and Destination Database

Text description of strms029.gif follows
Text description of the illustration strms029.gif


See Also:

Chapter 23, "Multiple Source Replication Example" illustrates this example

Primary Database Sharing Data with Several Secondary Databases

This scenario involves a Streams environment in which one database is the primary database, and this primary database shares data with several secondary databases. The secondary databases share data only with the primary database. The secondary databases do not share data directly with each other, but, instead, share data indirectly with each other through the primary database. This type of environment is sometimes called a "hub and spoke" environment, with the primary database being the hub and the secondary databases being the spokes.

In such an environment, changes are captured, propagated, and applied in the following way:

For example, consider an environment that replicates the database objects and data in the hr schema between one primary database named ps1.net and three secondary databases named ps2.net, ps3.net, and ps4.net. DML and DDL changes made to tables in the hr schema are captured at the primary database and at the three secondary databases in the environment. Then, these changes are propagated and applied as described previously. The environment uses apply forwarding, not queue forwarding, to share data between the secondary databases through the primary database. Figure 8-3 illustrates an example environment which has one primary database and multiple secondary databases.

Figure 8-3 Primary Database Sharing Data with Several Secondary Databases

Text description of strms030.gif follows
Text description of the illustration strms030.gif


You can avoid change cycles by configuring the environment in the following way:

This configuration prevents change cycling in the following way:

So, in this environment, no changes are lost, and all databases are synchronized.

Figure 8-4 illustrates how tags are used at the primary database ps1.net.

Figure 8-4 Tags Used at the Primary Database

Text description of strms023.gif follows
Text description of the illustration strms023.gif


Figure 8-5 illustrates how tags are used at one of the secondary databases (ps2.net).

Figure 8-5 Tags Used at a Secondary Database

Text description of strms028.gif follows
Text description of the illustration strms028.gif


Primary Database Sharing Data with Several Extended Secondary Databases

In this environment, one primary database shares data with several secondary databases, but the secondary databases have other secondary databases connected to them, which will be called remote secondary databases. This environment is an extension of the environment described in "Primary Database Sharing Data with Several Secondary Databases".

A remote secondary database does not share data directly with the primary database, but instead shares data indirectly with the primary database through a secondary database. So, the shared data exists at the primary database, at each secondary database, and at each remote secondary database. Changes made at any of these databases are captured and propagated to all of the other databases. Figure 8-6 illustrates an environment with one primary database and multiple extended secondary databases.

Figure 8-6 Primary Database and Several Extended Secondary Databases

Text description of strms024.gif follows
Text description of the illustration strms024.gif


In such an environment, you can avoid change cycling in the following way:

By configuring the environment in this way, you prevent change cycling, and no changes originating at any database are lost.