Oracle Built−in Packages- P151 pps

comment IN VARCHAR2) Parameters are summarized in the following table. Name Description gname Name of the replication group containing the priority group name Name of the site priority group comment Comment sname (Oracle7 only) Not used 16.4.2.3.1 Exceptions The COMMENT_ON_SITE_PRIORITY procedure may raise the following exceptions: Name Number Description missingpriority −1403 Site priority group name does not exist missingrepgroup −23373 Replication group gname does not exist nonmasterdef −23312 Calling site is not master definition site 16.4.2.3.2 Restrictions You must call DBMS_REPCAT.COMMENT_ON_SITE_PRIORITY from the master definition site. 16.4.2.3.3 Example The following example shows how to replace a comment on a site priority group: BEGIN DBMS_REPCAT.COMMENT_ON_SITE_PRIORITY( gname => 'SPROCKET', name => 'SP_NORTH_AMERICA', comment => 'Comment added on '||sysdate|| ' by '|| user); END; 16.4.3 Maintaining Site Priorities Once you have created a site priority group as described in the previous section, you can add and drop sites (with ADD_SITE_PRIORITY_SITE and DROP_SITE_PRIORITY_SITE) and modify their priority values (with ALTER_SITE_PRIORITY and ALTER_SITE_PRIORITY_SITE). You can query the data dictionary table DBA_REPPRIORITY for information about site priority group members and their priorities. 16.4.3.1 The DBMS_REPCAT.ADD_SITE_PRIORITY_SITE procedure The ADD_SITE_PRIORITY_SITE procedure adds a new site to a site priority group. Specifications for Oracle7 and Oracle8 differ as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.ADD_SITE_PRIORITY_SITE (gname IN VARCHAR2 := '', name IN VARCHAR2, site IN VARCHAR2, priority IN NUMBER, [Appendix A] What's on the Companion Disk? 16.4.2 Creating, Maintaining, and Dropping Site Priorities 741 sname IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DBMS_REPCAT.ADD_SITE_PRIORITY_SITE (gname IN VARCHAR2 := '', name IN VARCHAR2, site IN VARCHAR2, priority IN NUMBER); Parameters are summarized in the following table. Name Description gname Name of the replication group to which site priority group name belongs name Name of the site priority group site Global name of the new site priority Priority designated to site sname (Oracle7 only) Not used 16.4.3.1.1 Exceptions The ADD_SITE_PRIORITY_SITE procedure may raise the following exceptions: Name Number Description duplicatepriority −23335 Another site is already designated with priority specified by priority parameter duplicatesite −23338 Site is already in the site priority group name missingpriority −1403 Site does not exist missingrepgroup −23373 Replication group gname does not exist nonmasterdef −23312 Calling site is not the master definition site 16.4.3.1.2 Restrictions Note the following restrictions on calling ADD_SITE_PRIORITY_SITE: • You must call the ADD_SITE_PRIORITY_SITE procedure from the master definition site. • The new priority must be unique within the site priority group. 16.4.3.1.3 Example This example adds four sites to the site priority group SP_NORTH_AMERICA: BEGIN DBMS_REPCAT.ADD_SITE_PRIORITY_SITE( gname => 'SPROCKET', name => 'SP_NORTH_AMERICA', site => 'D7OH.BIGWHEEL.COM', priority => 10); DBMS_REPCAT.ADD_SITE_PRIORITY_SITE( gname => 'SPROCKET', name => 'SP_NORTH_AMERICA', site => 'D7NY.BIGWHEEL.COM', priority => 20); [Appendix A] What's on the Companion Disk? 16.4.3 Maintaining Site Priorities 742 DBMS_REPCAT.ADD_SITE_PRIORITY_SITE( gname => 'SPROCKET', name => 'SP_NORTH_AMERICA', site => 'D7HI.BIGWHEEL.COM', priority => 30); DBMS_REPCAT.ADD_SITE_PRIORITY_SITE( gname => 'SPROCKET', name => 'SP_NORTH_AMERICA', site => 'D7CA.BIGWHEEL.COM', priority => 40); END; TIP: As with the ADD_PRIORITY_<datatype> procedure, it is a good idea to use multiples of 10 or more for the priority values so that you have some flexibility for future changes and additions. After making these calls, we can query DBA_REPPRIORITY to confirm that Oracle added the sites. SQL> SELECT gname, 2 priority_group, 3 varchar2_value site_name, 4 priority 5 FROM dba_reppriority 6 WHERE priority_group = 'SP_NORTH_AMERICA' 7 ORDER BY priority; GNAME PRIORITY_GROUP SITE_NAME PRIORITY −−−−−−−− −−−−−−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−− −−−−−−−− SPROCKET SP_NORTH_AMERICA D7OH.BIGWHEEL.COM 10 SPROCKET SP_NORTH_AMERICA D7NY.BIGWHEEL.COM 20 SPROCKET SP_NORTH_AMERICA D7HI.BIGWHEEL.COM 30 Although DBA_REPPRIORITY reflects the changes from the ADD_SITE_PRIORITY_SITE call, you must call DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT for an object in the replication group for the changes to propagate to the other master sites. This is the case for all of the DBMS_REPCAT procedures pertaining to site priority groups. 16.4.3.2 The DBMS_REPCAT.DROP_SITE_PRIORITY_SITE procedure The DROP_SITE_PRIORITY_SITE procedure removes a site from a site priority group. Specifications for Oracle7 and Oracle8 differ as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.DROP_SITE_PRIORITY_SITE (gname IN VARCHAR2 := '', name IN VARCHAR2, site IN VARCHAR2, sname IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DBMS_REPCAT.DROP_SITE_PRIORITY_SITE (gname IN VARCHAR2 := '', name IN VARCHAR2, site IN VARCHAR2); Parameters are summarized in the following table. Name Description [Appendix A] What's on the Companion Disk? 16.4.3 Maintaining Site Priorities 743 gname Name of the replication group to which site priority group name belongs name Name of the site priority group site Global name of the new site sname (Oracle7 only) Not used 16.4.3.2.1 Exceptions The DROP_SITE_PRIORITY_SITE procedure may raise the following exceptions: Name Number Description missingpriority −1403 Site priority does not exist missingrepgroup −23373 Replication group gname does not exist nonmasterdef −23312 Calling site is not the master definition site 16.4.3.2.2 Restrictions You must call DROP_SITE_PRIORITY_SITE from the master definition site. 16.4.3.2.3 Example Here we drop D7TX.BIGWHEEL.COM from the SP_NORTH_AMERICA site priority: BEGIN DBMS_REPCAT.DROP_SITE_PRIORITY_SITE( gname => 'SPROCKET', name => 'SP_NORTH_AMERICA', site => 'D7TX.BIGWHEEL.COM'); END; As with the other site priority procedures, you must call GENERATE_REPLICATION_SUPPORT for an object in the replication group to propagate this change to other master sites. Can I Drop a Site Priority Referenced by Priority Level? You may have noticed that there is no procedure that will drop a member of a site priority referenced by priority level −− that is, there is no analog to DBMS_REPCAT.DROP_PRIORITY. Perhaps the team at Oracle decided that a procedure name like DROP_SITE_PRIORITY_PRIORITY is too cumbersome. However, you can use DBMS_REPCAT.DROP_PRIORITY to drop a site priority referenced by priority level! Pass the name of the site priority to the pgroup parameters, and the priority value to the priority_num parameter. Site priority groups really are priority groups in disguise. 16.4.3.3 The DBMS_REPCAT.ALTER_SITE_PRIORITY procedure Just as you can change the priority of a value in a priority group, you can change the priority of a site in a site priority group. Use the ALTER_SITE_PRIORITY procedure to do this. The specifications for Oracle7 and Oracle8 differ as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.ALTER_SITE_PRIORITY (gname IN VARCHAR2 := '', name IN VARCHAR2, [Appendix A] What's on the Companion Disk? 16.4.3 Maintaining Site Priorities 744 old_priority IN NUMBER, new_priority IN NUMBER, sname IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DBMS_REPCAT.ALTER_SITE_PRIORITY (gname IN VARCHAR2 := '', name IN VARCHAR2, old_priority IN NUMBER, new_priority IN NUMBER); site IN VARCHAR2); Parameters are summarized in the following table. Name Description gname Name of the replication group to which the site priority group name belongs name Name of the site priority group old_priority Site's current priority new_priority Site's new priority sname (Oracle7 only) Not used 16.4.3.3.1 Exceptions The ALTER_SITE_PRIORITY procedure may raise the following exceptions: Name Number Description duplicatepriority −1 Priority new_priority already exists for the site priority group name missingpriority −1403 Priority old_priority is not associated with any sites missingrepgroup −23373 Replication group gname does not exist missingvalue −23337 Value old_value does not already exist nonmasterdef −23312 Calling site is not the master definition site paramtype −23325 Parameter new_value is incorrect datatype 16.4.3.3.2 Restrictions Note the following restrictions on calling ALTER_SITE_PRIORITY: • You must run this procedure from the master definition site. • The new priority must be unique within the site priority group. 16.4.3.3.3 Example In this example, we move D7NY.BIGWHEEL.COM (from a previous example) to a higher priority, between D7HI.BIGWHEEL.COM and D7CA.BIGWHEEL.COM: BEGIN DBMS_REPCAT.ALTER_SITE_PRIORITY( gname => 'SPROCKET', name => 'SP_NORTH_AMERICA', old_priority => 20, [Appendix A] What's on the Companion Disk? 16.4.3 Maintaining Site Priorities 745 . procedure adds a new site to a site priority group. Specifications for Oracle7 and Oracle8 differ as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.ADD_SITE_PRIORITY_SITE (gname. procedure removes a site from a site priority group. Specifications for Oracle7 and Oracle8 differ as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.DROP_SITE_PRIORITY_SITE . Use the ALTER_SITE_PRIORITY procedure to do this. The specifications for Oracle7 and Oracle8 differ as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.ALTER_SITE_PRIORITY (gname