commfailure −23317 Unable to communicate with one or more master sites missinggroup −23331 Replication group gname does not exist nonmasterdef −23312 Calling site is not master definition site 15.3.2.3.2 Restrictions The COMMENT_ON_REPGROUP procedure must be called from the master definition site. 15.3.2.3.3 Example This call adds or replaces the comment in DBA_REPGROUP for the SPROCKET replication group: BEGIN DBMS_REPCAT.COMMENT_ON_REPGROUP( gname 'SPROCKET', comment => 'Comment added on '||sysdate|| ' by '||user); END; COMMENT_ON_REPGROUP queues an RPC to update the field at all other master sites. 15.3.3 Replicated Objects with DBMS_REPCAT After you have created your replication group(s) (with or without comments), you are ready to add, alter, and remove member objects. Here are the procedures you need: DBMS_REPCAT.CREATE_MASTER_REPOBJECT DBMS_REPCAT.SET_COLUMNS DBMS_REPCAT.DROP_MASTER_REPOBJECT DBMS_REPCAT.COMMENT_ON_REPOBJECT DBMS_REPCAT.ALTER_MASTER_REPOBJECT DBMS_REPCAT.EXECUTE_DDL The following sections describe these programs in detail. 15.3.3.1 The DBMS_REPCAT.CREATE_MASTER_REPOBJECT procedure The CREATE_MASTER_REPOBJECT procedure creates a replicated object. Its specification follows: PROCEDURE DBMS_REPCAT.CREATE_MASTER_REPOBJECT( sname IN VARCHAR2, oname IN VARCHAR2, type IN VARCHAR2, use_existing_object IN BOOLEAN := TRUE, ddl_text IN VARCHAR2 := NULL, comment IN VARCHAR2 := '', retry IN BOOLEAN := FALSE, copy_rows IN BOOLEAN := TRUE, gname IN VARCHAR2 := ''); Parameters are summarized in the following table. Name Description sname Name of the schema to which oname belongs. oname Name of the object to be added. type [Appendix A] What's on the Companion Disk? 15.3.2 Replication Groups with DBMS_REPCAT 656 Object type. Valid types: TABLE, INDEX, SYNONYM, TRIGGER, VIEW, PROCEDURE, FUNCTION, PACKAGE, and PACKAGE BODY. use_existing_object Set to TRUE to reuse existing objects with the same name and structure at master sites. ddl_text Text of DDL statement to create object oname (use this parameter if and only if object does not already exist). comment Comment on replicated object, visible in DBA_REPOBJECT data dictionary view. retry Flag indicating that this call is a reattempt of an earlier call. An attempt is made to create object only at master sites where it does not exist with a status of valid. copy_rows Populate tables and other master sites with data from master definition site. gname Name of the replication group to which oname should be added. 15.3.3.1.1 Exceptions The CREATE_MASTER_REPOBJECT procedure may raise the following exceptions: Name Number Description commfailure −23317 Not all master sites are reachable ddlfailure −23309 Object oname already exists in replication group gname, and retry is not set to TRUE duplicateobject −23374 Replication group gname already exists missingobject −23308 Object oname does not exist nonmasterdef −23373 Calling site is not the master definition site for replication group gname notquiesced −23310 Replication group gname is not quiesced typefailure −23319 The type is not supported 15.3.3.1.2 Restrictions Note the following restrictions on calling CREATE_MASTER_REPOBJECT: • This procedure must be called from the master definition site. • The replication group must already exist and be quiesced. 15.3.3.1.3 Example This section contains a series of examples showing how to create replication objects. 15.3.3.1.4 Adding an existing table to a replication group This call adds table SPROCKET. PRODUCTS to the replication group SPROCKET: BEGIN DBMS_REPCAT.CREATE_MASTER_REPOBJECT(sname => 'SPROCKET', oname => 'PRODUCTS', type => 'TABLE', gname => 'SPROCKET'); END; Since we have not specified ddl_text in this example, the table must already exist. [Appendix A] What's on the Companion Disk? 15.3.3 Replicated Objects with DBMS_REPCAT 657 15.3.3.1.5 Creating an object at the master definition site In this next example, we use CREATE_MASTER_REPOBJECT to create an object at the master definition site and add it to the replication group: BEGIN DBMS_REPCAT.CREATE_MASTER_REPOBJECT( sname => 'SPROCKET', oname => 'STATES', type => 'TABLE' ddl_text => 'CREATE TABLE sprocket.states(state_id VARCHAR2(2), state_name VARCHAR2(20))', gname => 'SPROCKET'); END; Notice that the CREATE TABLE statement in this example specifies the owner of the table. Typically, the replication administrator account uses DBMS_REPCAT, not the owner of the replicated schema. When this is the case, you must be sure to specify the schema in which to create objects. One of the privileges granted through DBMS_REPCAT_ADMIN.GRANT_ADMIN_ANY_REPGROUP is CREATE ANY TABLE. In all likelihood, you will not create objects with the CREATE_MASTER_REPOBJECT procedure very often, because doing so is rather clumsy for all but the most simple objects. But it's there if you want it. Setting the retry and use_existing_object parameters to TRUE in this third example creates the table PRODUCTS at all master sites where it does not already exist; setting copy_rows to TRUE copies the data from the master definition site to the master sites. BEGIN DBMS_REPCAT.CREATE_MASTER_REPOBJECT( sname => 'SPROCKET', oname => 'PRODUCTS', type => 'TABLE', use_existing_object => TRUE, retry => TRUE, copy_rows => TRUE, gname => 'SPROCKET'); END; If tables exist at master sites, but do not have the same definition as at the master definition site, Oracle returns an error. NOTE: If you are incorporating an existing database into a replication group, you should consider precreating all of the objects at the new site manually, especially if the objects have interdependencies. At my sites, we always run a "catalog" script to create all schema objects, including triggers, primary and foreign key definitions, check constraints, etc. We then let Oracle generate the replication support objects. This methodology gives us complete control over how the schema is created, and we can easily reproduce the objects in other environments. 15.3.3.1.6 Replicating a package In this final example, we replicate a package. To replicate a package, you must make two calls to CREATE_MASTER_REPOBJECT, one for the package, and one for the package body. BEGIN DBMS_REPCAT.CREATE_MASTER_REPOBJECT sname => 'SPROCKET', oname => 'PRODUCTMAINT', type => 'PACKAGE', [Appendix A] What's on the Companion Disk? 15.3.3 Replicated Objects with DBMS_REPCAT 658 use_existing_object => TRUE, comment => 'Added on '||sysdate, retry => FALSE, gname => 'SPROCKET'); DBMS_REPCAT.CREATE_MASTER_REPOBJECT sname => 'SPROCKET', oname => 'PRODUCTMAINT', type => 'PACKAGE BODY', use_existing_object => TRUE, comment => 'Added on '||sysdate, retry => FALSE, gname => 'SPROCKET'); END; For an additional example, see the repobjs.sql file on the companion disk. The example queries the DBA_REPOBJECT data dictionary view and lists all replicated objects in the database. 15.3.3.2 The DBMS_REPCAT.SET_COLUMNS procedure When you replicate a table, Oracle must be able to uniquely identify each record in the table so that it can propagate changes to the correct row or rows. By default, the advanced replication facility uses the primary key to identify rows. However, if your table does not have a primary key, or if you wish to use a different criteria to uniquely identify records, you can use SET_COLUMNS to designate a pseudo−primary key. Here's the specification for the package: PROCEDURE DBMS_REPCAT.SET_COLUMNS (sname IN VARCHAR2, oname IN VARCHAR2, column_list IN VARCHAR2 | column_table IN dbms_utility.name_array); Parameters are summarized in the following table. Name Description sname Name of the schema that owns the replicated table. oname Name of the table with the column_group. column_list A comma−delimited list of column names to use as the pseudo−primary key. Use either column_list or column_table. column_table A PL/SQL table of column names. Use either column_list or column_table. 15.3.3.2.1 Exceptions DBMS_REPCAT.SET_COLUMNS may raise the following exceptions: Name Number Description nonmasterdef −23312 Invoking site is not master definition site missingobject −23308 Table oname does not exist missingcolumn −23334 Column(s) specified do not exist in table oname 15.3.3.2.2 Restrictions Note the following restrictions on calling DBMS_REPCAT.SET_COLUMNS. • [Appendix A] What's on the Companion Disk? 15.3.3 Replicated Objects with DBMS_REPCAT 659 DBMS_REPCAT.SET_COLUMNS must be run from the master definition site. • The changes do not take effect until the next call to DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT. 15.3.3.2.3 Example The following call designates columns COLOR, MODEL, and YEAR as the pseudo−primary key columns in table SPROCKET.PRODUCTS: BEGIN DBMS_REPCAT.SET_COLUMNS(sname => 'SPROCKET', oname => 'PRODUCTS', column_list => 'COLOR,MODEL,YEAR'); END; 15.3.3.3 The DBMS_REPCAT.DROP_MASTER_REPOBJECT procedure The DROP_MASTER_REPOBJECT procedure drops a replicated object at the master site. The specification follows: PROCEDURE DBMS_REPOBJECT.DROP_MASTER_REPOBJECT (sname IN VARCHAR2, oname IN VARCHAR2, type IN VARCHAR2, drop_objects IN BOOLEAN := FALSE); Parameters are summarized in the following table. Name Description sname Name of the schema to which oname belongs. oname Name of the object to be added. type Object type. Valid types: TABLE, INDEX, SYNONYM, TRIGGER, VIEW, PROCEDURE, FUNCTION, PACKAGE, and PACKAGE BODY. drop_objects If TRUE, drop the object at all master sites; default is FALSE. 15.3.3.3.1 Exceptions The DROP_MASTER_REPOBJECT procedure may raise the following exceptions: Name Number Description commfailure −23317 Not all master sites are reachable missingobject −23308 Object oname does not exist nonmasterdef −23373 Calling site is not the master definition site for replication group gname typefailure −23319 The type is not supported 15.3.3.3.2 Restrictions Note the following restrictions on calling DROP_MASTER_REPOBJECT: • This procedure must be called from the master definition site. • [Appendix A] What's on the Companion Disk? 15.3.3 Replicated Objects with DBMS_REPCAT 660 . tables exist at master sites, but do not have the same definition as at the master definition site, Oracle returns an error. NOTE: If you are incorporating an existing database into a replication. objects, including triggers, primary and foreign key definitions, check constraints, etc. We then let Oracle generate the replication support objects. This methodology gives us complete control over. objects in the database. 15.3.3.2 The DBMS_REPCAT.SET_COLUMNS procedure When you replicate a table, Oracle must be able to uniquely identify each record in the table so that it can propagate changes