NOTE: If you change the propagation mode, you must also regenerate the replication support triggers for all replicated tables; ALTER_MASTER_PROPAGATION does not do this automatically. After altering the propagation method, you must call DBMS_REPCAT.GENERATE_REPLICATION_TRIGGERS for all replicated tables in the replication group. 15.3.8.3 The DBMS_REPCAT.SEND_AND_COMPARE_OLD_VALUES procedure (Oracle8 only) The default behavior of advanced replication is to send the old and new values of every column to participating master sites whenever you update a row in a replicated table. At the destination sites, Oracle uses this information to ensure that the version of the row that you updated matches the version of the row currently at the destination. However, if you know that certain columns in a table will never change, you can avoid sending the data in these columns when you propagate updates to participating master sites. Using the SEND_AND_COMPARE_OLD_VALUES procedure (available only in Oracle8) in this way, you'll reduce propagation overhead. Here is the specification: PROCEDURE DBMS_REPCAT.SEND_AND_COMPARE_OLD_VALUES (sname IN VARCHAR2 oname IN VARCHAR2, {column_list IN VARCHAR2 | column_table IN dbms_repcat.varchar2s}, operation IN VARCHAR2 := 'UPDATE', send IN BOOLEAN := TRUE); Parameters are summarized in the following table. Name Description sname Name of the replication group whose propagation mode is being altered oname Table being altered column_list Comma−separated list of columns whose propagation mode is being altered; "*" indicates all nonkey columns column_table PL/SQL table of containing columns whose propagation is being altered operation Operation for which this change applies; this may be UPDATE, DELETE, or "*" (indicating both updates and deletes) send If TRUE (the default), then the old values for the columns are sent; if FALSE, then old values are not sent NOTE: The configuration changes you specify with this procedure do not take effect unless the min_communication parameter is TRUE for the table in question. That is, you must have executed DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT for the table with min_communication = TRUE. 15.3.8.3.1 Exceptions The SEND_AND_COMPARE_OLD_VALUES procedure may raise the following exceptions: Name Number Description missingobject −23308 Object oname does not exist missingcolumn −23334 Column(s) specified do not exist in table oname nonmasterdef −23312 Calling site is not the master definition site notquiesced −23310 Replication group gname is not quiesced [Appendix A] What's on the Companion Disk? 15.3.8 Miscellaneous DBMS_REPCAT Procedures 691 typefailure −23319 The oname is not a table 15.3.8.3.2 Restrictions Note the following restrictions on calling SEND_AND_COMPARE_OLD_VALUES: • You must call this procedure from the master definition site. • The replication group sname must be quiesced. 15.2 DBMS_REPCAT_ADMIN: Setting Up More Administrator Accounts 15.4 DBMS_OFFLINE_OG: Performing Site Instantiation Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 15.3.8 Miscellaneous DBMS_REPCAT Procedures 692 Chapter 15 Advanced Replication 15.4 DBMS_OFFLINE_OG: Performing Site Instantiation When you add a new site to your replicated environment, you must not only create the replicated objects, but also populate snapshots and replicated tables with a copy of the current data. Although you can set the copy_rows parameter to TRUE in your call to the DBMS_REPCAT package's CREATE_MASTER_REPOBJECT or ADD_MASTER_DATABASE procedure, this option is not practical for schemas that are large or complex. The DBMS_OFFLINE_OG package provides a more feasible method of site instantiation. The general idea is that you export data from an existing master site and import it into the new master site. While the import is taking place, the existing master sites queue data updates to the new site, but do not actually send the updates until the load is complete. 15.4.1 Getting Started with DBMS_OFFLINE_OG The DBMS_OFFLINE_OG package is created when the Oracle database is installed. The dbmsofln.sql script (found in the built−in packages source directory, as described in Chapter 1) contains the source code for this package's specification. This script is called by catrep.sql, which must be run to install the advanced replication packages. The wrapped sql script prvtofln.plb creates the public synonym DBMS_OFFLINE_OG. No EXECUTE privileges are granted on DBMS_OFFLINE_OG; only the owner (SYS) and those with the EXECUTE ANY PROCEDURE system privilege may execute the package. The programs in DBMS_OFFLINE_OG are listed in Table 15.5. Table 15.5: DBMS_OFFLINE_OG: Programs Name Description Use in SQL? BEGIN_INSTANTIATION Call from master definition site to flag beginning of offline instantiation No BEGIN_LOAD Call from new master site prior to importing data No END_INSTANTIATION Call from master definition site to flag end of offline instantiation No END_LOAD Call from new master site after importing data No RESUME_SUBSET_OF_MASTERS Call from master definition site to resume replication activity for existing sites while new site is No 693 instantiated 15.4.2 DBMS_OFFLINE_OG Interface This section describes the programs available in the DBMS_OFFLINE_OG package. 15.4.2.1 The DBMS_OFFLINE_OG.BEGIN_INSTANTIATION procedure The BEGIN_INSTANTIATION procedure is called from the master definition site to flag the beginning of offline instantiation. Here's the specification: PROCEDURE DBMS_OFFLINE_OG.BEGIN_INSTANTIATION (gname IN VARCHAR2, new_site IN VARCHAR2); Parameters are summarized in the following table. Name Description gname The replication group to which the site is being added new_site The global_name of the new_site 15.4.2.1.1 Exceptions The BEGIN_INSTANTIATION procedure may raise the following exceptions: Name Number Description badargument −23430 gname is NULL or ` ' missingrepgroup −23373 Group gname does not exist nonmasterdef −23312 Routine is not being called from master definition site sitealreadyexists −23432 New_site already exists wrongstate −23431 Group gname is not in NORMAL state at master definition site 15.4.2.1.2 Restrictions The procedures in DBMS_OFFLINE_OG must be called in the appropriate order from the appropriate sites. The following example illustrates the proper use of this package. 15.4.2.1.3 Example The following table summarizes the steps you should follow when you use the procedures in the DBMS_OFFLINE_OG package. Step Where Performed Activity 1 Master definition site DBMS_REPCAT.ADD_MASTER_DATABASE 2 Master definition site DBMS_REPCAT.SUSPEND_MASTER_ACTIVITY 3 Master definition site DBMS_OFFLINE_OG.BEGIN_INSTANTIATION 4 Any master site Export replicated schema 5 Master definition site DBMS_OFFLINE_OG.RESUME_SUBSET_OF_MASTERS 6 New site DBMS_OFFLINE_OG.BEGIN_LOAD [Appendix A] What's on the Companion Disk? 15.4.2 DBMS_OFFLINE_OG Interface 694 7 New site Import data from step 4 8 New site DBMS_OFFLINE_OG.END_LOAD 9 Master definition site DBMS_OFFLINE_OG.END_INSTANTIATION The following scenario shows how instantiate a new site. Here we add the site D7NY.BIGWHEEL.COM to the replication group SPROCKET using DBMS_OFFLINE_OG. Assume that the master definition site is D7CA.BIGWHEEL.COM. 1. From master definition site D7CA.BIGWHEEL.COM, we add the new master site, quiesce the replication group, and call DBMS_OFFLINE_OG.BEGIN_INSTANTIATION. BEGIN DBMS_REPCAT.ADD_MASTER_DATABASE( gname => 'SPROCKET', master =>'D7NY.BIGWHEEL.COM');; DBMS_REPCAT.SUSPEND_MASTER_ACTIVITY(gname => 'SPROCKET'); DBMS_OFFLINE_OG.BEGIN_INSTANTIATION( gname => 'SPROCKET', new_site => 'D7NY.BIGWHEEL.COM'); END; 2. Perform export of schema SPROCKET from any existing master site. 3. Call RESUME_SUBSET_OF_MASTERS at master definition site. 4. Call BEGIN_LOAD from the new master site D7NY.BIGWHEEL.COM. BEGIN DBMS_OFFLINE_OG.BEGIN_LOAD( gname => 'SPROCKET', new_site=> 'D7NY.BIGWHEEL.COM'); END; 5. Import the SPROCKET schema into D7NY.BIGWHEEL.COM using the export file created in step 2. 6. Call END_LOAD from the new master site, D7NY.BIGWHEEL.COM. BEGIN DBMS_OFFLINE_OG.END_LOAD( gname => 'SPROCKET', new_site=> 'D7NY.BIGWHEEL.COM'); END; 7. Call END_INSTANTIATION from the master definition site. BEGIN DBMS_OFFLINE_OG.END_INSTANTIATION( gname => 'SPROCKET', new_site => 'D7NY.BIGWHEEL.COM'); END; [Appendix A] What's on the Companion Disk? 15.4.2 DBMS_OFFLINE_OG Interface 695 . DBMS_OFFLINE_OG The DBMS_OFFLINE_OG package is created when the Oracle database is installed. The dbmsofln.sql script (found in the built−in packages source directory, as described in Chapter 1). to participating master sites whenever you update a row in a replicated table. At the destination sites, Oracle uses this information to ensure that the version of the row that you updated matches the. participating master sites. Using the SEND_AND_COMPARE_OLD_VALUES procedure (available only in Oracle8 ) in this way, you'll reduce propagation overhead. Here is the specification: PROCEDURE