SUSPEND_MASTER_ACTIVITY Quiesces a replication group No WAIT_MASTER_LOG Determines whether asynchronous DML has been applied at a master site No 15.3.1.2 Exceptions Table 15.4 describes exceptions raised by the DBMS_REPCAT programs described in this chapter. Table 15.4: DBMS_REPCAT Exceptions Name Number Description commfailure −23317 Unable to communicate with remote site dbnotcompatible −23375 Operation not available for current version of RDBMS ddlfailure −23318 DDL failed during object creation or maintenance activity duplicateobject −23309 Replicated object already exists duplicateschema −23307 Attempt to create duplicate replication group fullqueue −23353 Attempt to drop replication group or schema for which RPC entries are queued invalidpropmode −23380 Invalid propagation mode (used internally) missingcolumn −23334 Reference to nonexistent column missinggroup −23331 Replication group does not exist missingobject −23308 Object does not exist missingrepgroup −23373 Replication group does not exist missingschema −23306 Schema does not exist missingvalue −23337 Missing value (used internally) nonmaster −23313 Site is not a master site nonmasterdef −23312 Site is not a master definition site nonsnapshot −23314 Site is not a snapshot site norepoption −23364 Replication option not installed notnormal −23311 Replication group is not in normal propagation mode notquiesced −23310 Replication group is not quiesced paramtype −23325 Invalid parameter type (used internally) reconfigerror −23316 Attempt to drop master definition site with REMOVE_MASTER_DATABASES repnotcompatible −23376 Replication versions not compatible (used internally) typefailure −23319 Attempt to replicate nonsupported datatype version −23315 Replication versions not compatible (used internally) 15.3.2 Replication Groups with DBMS_REPCAT Once you have created administrative accounts for your advanced replication environment and established the appropriate database links among your various sites, you are ready for the next step, which is to create a replication group. Here are the procedures you will use: [Appendix A] What's on the Companion Disk? 15.3.1 Getting Started with DBMS_REPCAT 651 DBMS_REPCAT.CREATE_MASTER_REPGROUP DBMS_REPCAT.DROP_MASTER_REPGROUP DBMS_REPCAT.COMMENT_ON_REPGROUP The following sections describe these programs in detail. Replication Groups versus Replication Schema Prior to Oracle 7.3, the concept of a replication group does not exist. Instead, you have to replicate replication schema groups. As you would suspect, schema groups can contain only objects from a single schema. In addition, the name of the group has to be the same as the name of the schema. In Version 7.3, Oracle introduced replication groups, which can contain objects from one or more schema. Replication groups do not have to have the same name as any of the schema they contain. In Oracle 8.0, Oracle improved the manageability of replication groups by allowing you to quiesce a single replication group at a time. (The syntax for quiescing a single group exists in 7.3, but it does not work!) As you configure and manage a replicated environment, you may notice that for each program that operates on a replication group, such as DBMS_REPCAT.GRANT_ADMIN_ANY_REPGROUP, there is a corresponding procedure that operates on a replication schema, such as DBMS_REPCAT.GRANT_ADMIN_ANY_REPSCHEMA. You may also notice that many of the Oracle 7.3 procedure calls contain an undocumented sname parameter. Oracle provided these procedures and parameters for backward compatibility only. Although the REPSCHEMA procedures exist in Versions 7.3 and 8.0, you are strongly encouraged not to use them, as their support will not continue indefinitely. The sname parameters are already gone from many programs in the first Oracle8 release. Figure 15.1 shows how replication groups work. Figure 15.1: . Replication groups [Appendix A] What's on the Companion Disk? 15.3.2 Replication Groups with DBMS_REPCAT 652 15.3.2.1 The DBMS_REPCAT.CREATE_MASTER_REPGROUP procedure The CREATE_MASTER_REPGROUP procedure creates a replication group at the master definition site. Here's the specification: PROCEDURE DBMS_REPCAT.CREATE_MASTER_REPGROUP (gname IN VARCHAR2, group_comment IN VARCHAR2 := '', master_comment IN VARCHAR2 := '', qualifier IN VARCHAR2 := ''); Parameters are summarized in the following table. Name Description gname Name of the new replication group group_comment Comment for new replication group visible in DBA_REPGROUP data dictionary view master_comment Comment for the calling site, visible in DBA_REPSITES data dictionary view qualifier For internal use 15.3.2.1.1 Exceptions The CREATE_MASTER_REPGROUP procedure may raise the following exceptions: Name Number Description ddlfailure −23318 Unable to create REP$WHAT_AM_I package or package body duplicaterepgroup −23374 Replication group gname already exists duplicateschema −23307 Schema gname is already a replication group missingrepgroup −23373 The gname was not specified correctly norepoption −23364 Replication option not installed dbnotcompatible −23375 The gname is not a schema name, and RDBMS is a pre−7.3 release 15.3.2.1.2 Restrictions You must be connected to the replication administrator account (typically REPADMIN) to call CREATE_MASTER_REPGROUP. 15.3.2.1.3 Example The following call creates a replication group named SPROCKET: BEGIN DBMS_REPCAT.CREATE_MASTER_REPGROUP( gname=> 'SPROCKET', − group_comment => 'Replication group SPROCKET created on '||sysdate|| ' by ' ||user, − master_comment => 'Master Definition Site created on '||sysdate|| ' by ' ||user); END; This call creates a replication group with no objects. The site from which you make the call is the master definition site for the group. For an additional example, see the repgroup.sql file on the companion disk. That example queries the DBA_REPGROUP data dictionary view and lists all replication groups in the database. [Appendix A] What's on the Companion Disk? 15.3.2 Replication Groups with DBMS_REPCAT 653 15.3.2.2 The DBMS_REPCAT.DROP_MASTER_REPGROUP procedure The DROP_MASTER_REPGROUP procedure drops one or more replication groups at the master definition site. Here's the specification: PROCEDURE DBMS_REPCAT.DROP_MASTER_REPGROUP (gname IN VARCHAR2, drop_contents IN BOOLEAN := FALSE, all_sites IN BOOLEAN := FALSE); Parameters are summarized in the following table. Name Description all_sites If TRUE and call is the master definition site, then drop the replication group from all sites in the environment drop_contents If TRUE, drop the objects in the replication group as well as the group itself gname Name of the new replication group 15.3.2.2.1 Exceptions The DROP_MASTER_REPGROUP procedure raises the following exceptions: Name Number Description commfailure −23317 Unable to communicate with all masters, and all_sites is TRUE fullqueue −23353 Outstanding transactions queued for replication group gname missingrepgroup −23373 gname is not specified correctly nonmaster −23313 Calling site is not a master site nonmasterdef −23312 Calling site is not a master definition site, and all_sites is TRUE 15.3.2.2.2 Restrictions Note the following restrictions on calling DROP_MASTER_REPGROUP: • You must be connected to the replication administrator account (typically REPADMIN) to call DROP_MASTER_REPGROUP. • DROP_MASTER_REPGROUP does not drop all snapshots if the gname parameter is the master of any snapshot groups. Dropping a master site does not necessarily remove it from the DBA_REPSITES at other masters. TIP: Before calling DROP_MASTER_REPGROUP, call DBMS_REPCAT.REMOVE_MASTER_DATABASES from the master definition site to remove all masters for which you plan to drop the group and that do not contain any other replication groups. In addition, you can avoid the full queue error by quiescing the replication group before attempting to drop the replication group. 15.3.2.2.3 Example This call, from the master definition site, drops a replication group from all sites where it exists: BEGIN [Appendix A] What's on the Companion Disk? 15.3.2 Replication Groups with DBMS_REPCAT 654 DBMS_REPCAT.DROP_MASTER_REPGROUP( gname => 'SPROCKET', all_sites => TRUE ); END; The next call drops a replication group and all of its objects from the calling site, assumed to be a master site (not a master definition site): BEGIN DBMS_REPCAT.DROP_MASTER_REPGROUP( gname => 'SPROCKET', drop_contents => TRUE ); END; If you want to drop a replication group from all master sites, along with the replicated objects, you can do the following: BEGIN DBMS_REPCAT.DROP_MASTER_REPGROUP( gname => 'SPROCKET', all_sites => TRUE drop_contents => TRUE ); END; 15.3.2.3 The DBMS_REPCAT.COMMENT_ON_REPGROUP procedure This procedure adds a new schema comment field to the DBA_REPCAT data dictionary view, or changes an existing one. The specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE DMBS_REPCAT.COMMENT_ON_REPGROUP (gname IN VARCHAR2 := '', comment IN VARCHAR2, sname IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DMBS_REPCAT.COMMENT_ON_REPGROUP (gname IN VARCHAR2, comment IN VARCHAR2); Parameters are summarized in the following table. Name Description gname Replication group to which comment is added comment Comment sname Not used NOTE: As noted in the earlier sidebar entitled the sidebar "Replication Groups versus Replication Schema"," you can see that Oracle has dispensed with the sname parameter in Oracle8. 15.3.2.3.1 Exceptions The COMMENT_ON_REPROUP procedure may raise the following exceptions: Name Number Description [Appendix A] What's on the Companion Disk? 15.3.2 Replication Groups with DBMS_REPCAT 655 . dictionary view, or changes an existing one. The specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE DMBS_REPCAT.COMMENT_ON_REPGROUP (gname IN. as DBMS_REPCAT.GRANT_ADMIN_ANY_REPSCHEMA. You may also notice that many of the Oracle 7.3 procedure calls contain an undocumented sname parameter. Oracle provided these procedures and parameters for backward compatibility. 7.3, Oracle introduced replication groups, which can contain objects from one or more schema. Replication groups do not have to have the same name as any of the schema they contain. In Oracle