16.3.2.1.1 Exceptions

The DEFINE_PRIORITY_GROUP procedure may raise the following exceptions:

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:

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;

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.1 Exceptions

The DROP_PRIORITY_GROUP procedure may raise the following exceptions:

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.1 Exceptions

The COMMENT_ON_PRIORITY_GROUP procedure may raise the following exceptions:

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.1.1 Exceptions

This procedure may raise the following exceptions:

16.3.3.1.2 Restrictions

Note the following restrictions on calling ADD_PRIORITY_ <datatype>:

• The new value must be unique within the priority group.

• The new priority must be unique within the priority group.

• ADD_PRIORITY_<datatype> must be called from the master definition site.

16.3.3.1.3 Example

To associate priorities with each of the five possible values of PRODUCTION_STATUS, we must make five calls to ADD_PRIORITY_VARCHAR2. After making these calls and a call to DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT, the column group is completely configured.

	BEGIN
		DBMS_REPCAT.ADD_PRIORITY_VARCHAR2(
		    gname	=> 'SPROCKET',
		    pgroup	=> 'PG_PRODUCTION_STATUS',

                    value	=> 'CONCEPT',
		    priority    => 10);

		DBMS_REPCAT.ADD_PRIORITY_VARCHAR2(
			gname	=> 'SPROCKET',
			pgroup	=> 'PG_PRODUCTION_STATUS',

			value	=> 'DEVELOPMENT',
			priority=> 20);

		DBMS_REPCAT.ADD_PRIORITY_VARCHAR2(
			gname	=> 'SPROCKET',
			pgroup	=> 'PG_PRODUCTION_STATUS',

			value	=> 'BETA',
			priority=> 30);

		DBMS_REPCAT.ADD_PRIORITY_VARCHAR2(
			gname	=> 'SPROCKET',
			pgroup	=> 'PG_PRODUCTION_STATUS',

			value	=> 'PRODUCTION',
			priority=> 40);

		DBMS_REPCAT.ADD_PRIORITY_VARCHAR2(
			gname	=> 'SPROCKET',
			pgroup	=> 'PG_PRODUCTION_STATUS',

			value	=> 'DISCONTINUED',
			priority=> 50);
	END;

TIP: It is a good idea to number priorities in multiples of 10 or more so that you can easily add new priority values later as requirements change.

16.3.3.2.1 Exceptions

The ALTER_PRIORITY procedure may raise the following exceptions:

16.3.3.2.2 Restrictions

Note the following restrictions on calling ALTER_PRIORITY:

• You must call the ALTER_PRIORITY procedure from the master definition site.

• The new priority must be unique within the priority group.

16.3.3.2.3 Examples

Suppose that our requirements change such that we want the PRODUCTION_STATUS value DEVELOPMENT to have higher priority than BETA. We can accomplish this by changing the priority associated with DEVELOPMENT from 30 to 45.

	BEGIN
		DBMS_REPCAT.ALTER_PRIORITY(
			gname		=> 'SPROCKET',
			pgroup		=> 'PG_PRODUCTION_STATUS',
			old_priority	=> 30,
			new_priority	=> 45);
	END;

As with the call to ADD_PRIORITY_<datatype>, this change takes effect after the next call to DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT.

16.3.3.3.1 Exceptions

The ALTER_PRIORITY_<datatype> procedure may raise the following exceptions:

16.3.3.3.2 Restrictions

Note the following restrictions on calling ALTER_PRIORITY_<datatype>:

• You must call the ALTER_PRIORITY_<datatype> procedure from the master definition site.

• The new priority must be unique within the priority group.

16.3.3.3.3 Example

Suppose that we want to change the data value associated with priority 50 from DISCONTINUED to OBSOLETE. We would make the following call:

	BEGIN
		DBMS_REPCAT.ALTER_PRIORITY_VARCHAR2(
			gname		=> 'SPROCKET',
			pgroup		=> 'PG_PRODUCTION_STATUS',
			old_value	=> 'DISCONTINUED',
			new_value	=> 'OBSOLETE');
	END;

This call would take effect after the next call to GENERATE_REPLICATION_SUPPORT for an object in the SPROCKET replication group.

16.3.4.1.1 Exceptions

The DROP_PRIORITY procedure may raise the following exceptions:

16.3.4.1.2 Restrictions

You must call the DROP_PRIORITY procedure from the master definition site.

16.3.4.1.3 Example

In the following example, we drop the member of the PG_PRODUCTION_STATUS priority group whose priority is 50:

	BEGIN
		DBMS_REPCAT.DROP_PRIORITY(
			gname		=> 'SPROCKET',
			pgroup		=> 'PG_PRODUCTION_STATUS',
			priority	=> 50);
	END;

This change takes effect the next time we run DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT for an object in the SPROCKET replication group.

16.3.4.2.1 Exceptions

The DROP_PRIORITY_<datatype> procedure may raise the following exceptions:

16.3.4.2.2 Restrictions

You must call DROP_PRIORITY_<datatype> from the master definition site.

16.3.4.2.3 Example

You can specify the member to be dropped by its data value rather than its priority (as was done with DROP_PRIORITY). In the following example, we drop the member of the PG_PRODUCTION_STATUS priority group whose value is CONCEPT:

	BEGIN
		DBMS_REPCAT.DROP_PRIORITY_VARCHAR2(
			gname	=> 'SPROCKET',
			pgroup	=> 'PG_PRODUCTION_STATUS',
			value	=> 'CONCEPT');
	END;

As with DROP_PRIORITY, this change takes effect after DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT has been run for any object in the replication group.