comment Comment. sname (Oracle7 only) Not used. 16.3.2.1.1 Exceptions The DEFINE_PRIORITY_GROUP procedure may raise the following exceptions: Name Number Description duplicateprioritygroup −23335 Priority group pgroup already exists missingschema −23306 Schema does not exist nonmasterdef −23312 Calling site is not the master definition site typefailure −23319 Datatype not supported 16.3.2.1.2 Restrictions Note the following restrictions on calling DEFINE_PRIORITY_GROUP: • You must call the DEFINE_PRIORITY_GROUP procedure from the master definition site. • You must call GENERATE_REPLICATION_SUPPORT for any object in the replication group for the new priority group to become active. 16.3.2.1.3 Example Since priority groups are meant to work with a specific range of values, you must specify the datatype of these values when you create the group. Valid datatypes follow: CHAR NCHAR (Oracle8 only) VARCHAR2 NUMBER DATE RAW If the data type is CHAR, then you must also specify the length of the data with the fixed_length parameter. After you create a priority group, you must run DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT for any object in the same replication group to propagate the new priority group to other master sites. (Since priority groups are not associated with a specific object, it does not matter what object you use in the call the GENERATE_REPLICATION_SUPPORT.) 16.3.2.1.4 Creating a priority group for datatype CHAR This call creates a priority group for a CHAR datatype. For the sake of this example, assume that the range of values is GREEN, YELLOW, RED, and the longest string is six characters long. BEGIN DBMS_REPCAT.DEFINE_PRIORITY_GROUP( gname => 'SPROCKET', pgroup => 'PG_SIGNAL_COLORS', datatype => 'CHAR', fixed_length => 6, comment => 'PG_SIGNAL_COLORS created '||sysdate); END; [Appendix A] What's on the Companion Disk? 16.3.2 Creating, Maintaining, and Dropping Priority Groups 726 16.3.2.1.5 Creating a priority group for datatype VARCHAR For all other datatypes, the use of the fixed_length parameter does not apply. This statement creates a priority group for use with the PRODUCTION_STATUS field in the PRODUCTS table: BEGIN DBMS_REPCAT.DEFINE_PRIORITY_GROUP( gname => 'SPROCKET', pgroup => 'PG_PRODUCTION_STATUS', datatype => 'VARCHAR', comment => 'PG_PRODUCTION_STATUS created '||sysdate); END; 16.3.2.2 The DBMS_REPCAT.DROP_PRIORITY_GROUP procedure The DROP_PRIORITY_GROUP procedure lets you drop a priority group that you have defined. The specifications differ for Oracle7 and Oracle8 as follows. here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.DROP_PRIORITY_GROUP (gname IN VARCHAR2 := '', pgroup IN VARCHAR2, sname IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DBMS_REPCAT.DROP_PRIORITY_GROUP (gname IN VARCHAR2 := '', pgroup IN VARCHAR2); Parameters are summarized in the following table. Name Description gname Name of the replication group containing the priority group pgroup Name of the priority group to drop sname (Oracle7 only) Not used WARNING: Do not drop a priority group that you have designated as an UPDATE conflict resolution method for a column group. You must first use DROP_UPDATE_RESOLUTION for the column group. Records in the data dictionary view DBA_REPRESOLUTION indicate if and where the priority group is used. Attempting to drop a priority group that is in use raises the referenced exception. 16.3.2.2.1 Exceptions The DROP_PRIORITY_GROUP procedure may raise the following exceptions: Name Number Description missingrepgroup −23373 Replication group gname does not exist nonmasterdef −23312 Calling site is not the master definition site referenced −23332 Priority group pgroup is used by existing conflict resolution methods [Appendix A] What's on the Companion Disk? 16.3.2 Creating, Maintaining, and Dropping Priority Groups 727 16.3.2.2.2 Restrictions You must call DBMS_REPCAT.DROP_PRIORITY_GROUP from the master definition site. 16.3.2.2.3 Example You can use DBMS_REPCAT.DROP_PRIORITY_GROUP as follows to remove a particular priority group from the replication group: BEGIN DBMS_REPCAT.DROP_PRIORITY_GROUP( gname =>'SPROCKET', pgroup =>'PG_PRODUCTION_STATUS'); END; 16.3.2.3 The DBMS_REPCAT.COMMENT_ON_PRIORITY_GROUP procedure The COMMENT_ON_PRIORITY_GROUP procedure allows you to create or replace the comment for a priority group (as seen in the DBA_REPPRIORITY_GROUP data dictionary view). The specifications for Oracle7 and Oracle8 differ as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.COMMENT_ON_PRIORITY_GROUP (gname IN VARCHAR2 := '', pgroup IN VARCHAR2, comment IN VARCHAR2, sname IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DBMS_REPCAT.COMMENT_ON_PRIORITY_GROUP (gname IN VARCHAR2 := '', pgroup IN VARCHAR2, comment IN VARCHAR2); Parameters are summarized in the following table. Name Description gname Name of the replication group containing the priority group pgroup Name of the priority group comment Comment sname (Oracle7 only) Not used 16.3.2.3.1 Exceptions The COMMENT_ON_PRIORITY_GROUP procedure may raise the following exceptions: Name Number Description missingprioritygroup −23336 Priority group pgroup does not exist missingrepgroup −23373 Replication group gname does not exist nonmasterdef −23312 Calling site is not the master definition site [Appendix A] What's on the Companion Disk? 16.3.2 Creating, Maintaining, and Dropping Priority Groups 728 16.3.2.3.2 Restrictions You must call COMMENT_ON_PRIORITY_GROUP from the master definition site. 16.3.2.3.3 Example The following illustrates how you can replace the comment for the PG_SIGNAL_COLORS priority group: BEGIN DBMS_REPCAT.COMMENT_ON_PRIORITY_GROUP( gname => 'SPROCKET', comment => 'Valid values are GREEN, YELLOW, and RED'); END; 16.3.3 Creating and Maintaining Priorities Within a Priority Group The next step after creating a priority group is to add priorities to it. This task entails specifying every possible value for the data in the priority group, and assigning a priority to each value. For example, recall the PRODUCTION_STATUS field we described earlier, which has this range of five possible values: 1. CONCEPT 2. DEVELOPMENT 3. BETA 4. PRODUCTION 5. DISCONTINUED We want to resolve conflicts for this data by accepting the data that is furthest in the production cycle. If a conflict arises in which one update has PRODUCTION_STATUS set to "BETA," and another update has it set to "PRODUCTION," we would take the data from the latter update. The examples in the following sections illustrate exactly how to implement this priority group. We will show the following packages: DBMS_REPCAT.ADD_PRIORITY_<datatype> DBMS_REPCAT.ALTER_PRIORITY DBMS_REPCAT.ALTER_PRIORITY_<datatype> DBMS_REPCAT.DROP_PRIORITY DBMS_REPCAT.DROP_PRIORITY_<datatype> NOTE: Each of the procedures containing the <datatype> suffix actually has five different versions in Oracle7, one for each of the datatypes CHAR, VARCHAR2, NUMBER, RAW, and DATE. Oracle8 adds support for two more datatypes: NCHAR and NVARCHAR2. The usage of each of these packages is identical. Most of the examples in the following sections will use the VARCHAR2 version of these packages. [Appendix A] What's on the Companion Disk? 16.3.2 Creating, Maintaining, and Dropping Priority Groups 729 16.3.3.1 The DBMS_REPCAT.ADD_PRIORITY_<datatype> procedure The ADD_PRIORITY_<datatype> procedure adds a member (of the specified datatype) to an existing priority group. The specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.ADD_PRIORITY_<datatype> (gname IN VARCHAR2 := '', pgroup IN VARCHAR2, value IN {CHAR|VARCHAR2|NUMBER|DATE|RAW, priority IN NUMBER, sname IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DBMS_REPCAT.ADD_PRIORITY_<datatype> (gname IN VARCHAR2 := '', pgroup IN VARCHAR2, value IN {CHAR|NCHAR|VARCHAR2|NUMBER|DATE|RAW, priority IN NUMBER) In these specifications, <datatype> can be any of the following, and value can be any of these types: CHAR VARCHAR2 NUMBER DATE RAW NCHAR (Oracle8 only) NVARCHAR2 (Oracle8 only) Parameters are summarized in the following table. Name Description gname Name of the replication group to which priority group pgroup belongs pgroup Priority group to which new value and priority are being added value Literal value that is being assigned added to pgroup priority Priority designated to value sname (Oracle7 only) Not used 16.3.3.1.1 Exceptions This procedure may raise the following exceptions: Name Number Description duplicatepriority −23335 Another value is already designated with priority priority duplicatevalue −23338 Value is already in the priority group pgroup missingprioritygroup −23336 Priority group pgroup does not exist missingrepgroup −23373 Replication group gname does not exist nonmasterdef −23312 Calling site is not the master definition site typefailure −23319 Datatype of value is not the same as the datatype for priority group pgroup [Appendix A] What's on the Companion Disk? 16.3.3 Creating and Maintaining Priorities Within a Priority Group 730 . drop a priority group that you have defined. The specifications differ for Oracle7 and Oracle8 as follows. here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.DROP_PRIORITY_GROUP (gname IN. the DBA_REPPRIORITY_GROUP data dictionary view). The specifications for Oracle7 and Oracle8 differ as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.COMMENT_ON_PRIORITY_GROUP . specified datatype) to an existing priority group. The specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.ADD_PRIORITY_<datatype>