Oracle Built−in Packages- P128 potx

Chapter 14 Snapshots 14.3 DBMS_OFFLINE_SNAPSHOT: Performing Offline Snapshot Instantiation The DBMS_OFFLINE_SNAPSHOT package allows you to instantiate snapshots without having to run the CREATE SNAPSHOT command or the DBMS_REPEAT.SNAPSHOT_REPOBJECT procedure over the network (those methods are described under DBMS_REPCAT, later in this chapter). Doing offline instantiation in this way is particularly useful in cases where you wish to instantiate a snapshot site with a large amount of data in an advanced replication environment. Offline instantiation refers to the population of snapshots with the import and export utilities, as opposed to using the DBMS_SNAPSHOT.REFRESH procedure. This technique is less time−consuming and less taxing on your network, and it minimizes the time your environment must be quiesced. You will typically use DBMS_OFFLINE_SNAPSHOT's BEGIN_LOAD and END_LOAD procedures in conjunction with the DBMS_REPCAT package's CREATE_SNAPSHOT_REPGROUP procedure; this procedure creates a new replicated snapshot group. The following sections summarize the syntax of the calls to BEGIN_LOAD and END_LOAD. See the later section Section 14.4, "DBMS_REPCAT: Managing Snapshot Replication Groups"" for a discussion of the DBMS_REPCAT procedure and how these procedures work together to instantiate snapshots in an advanced replication environment. 14.3.1 Getting Started with DBMS_OFFLINE_SNAPSHOT The DBMS_OFFLINE_SNAPSHOT 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_SNAPSHOT. No EXECUTE privileges are granted on DBMS_OFFLINE_SNAPSHOT; only the owner (SYS) and those with the EXECUTE ANY PROCEDURE system privilege may execute the package. 14.3.1.1 DBMS_OFFLINE_SNAPSHOT programs Table 14.4 summarizes the programs available through DBMS_OFFLINE_SNAPSHOT. Table 14.4: DBMS_OFFLINE_SNAPSHOT Programs Name Description Use in SQL? BEGIN_LOAD Call before beginning to load data from an export file No END_LOAD Call after the load is complete No 626 14.3.1.2 DBMS_OFFLINE_SNAPSHOT exceptions The DBMS_OFFLINE_SNAPSHOT package raises the following exceptions: Name Number Description badargument −23430 The gname, sname, master_site, or snapshot_oname parameter is NULL or". missingremotesnap −23361 The snapshot_oname parameter does not exist at the remote master site (master_site parameter). snaptabmismatch −23363 The base table name of the snapshot at master site and snapshot site do not match. 14.3.2 DBMS_OFFLINE_SNAPSHOT Interface This section describes the programs available through the DBMS_OFFLINE_SNAPSHOT package. 14.3.2.1 The DBMS_OFFLINE_SNAPSHOT.BEGIN_LOAD procedure Call the BEGIN_LOAD procedure before beginning to load data from an export file. The specifications for the Oracle7 and Oracle8 versions differ as follows. Here is the Oracle7 specification: PROCEDURE DBMS_OFFLINE_SNAPSHOT.BEGIN_LOAD (gname IN VARCHAR2, sname IN VARCHAR2, master_site IN VARCHAR2, snapshot_oname IN VARCHAR2, storage_c IN VARCHAR2 := '', comment IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DBMS_OFFLINE_SNAPSHOT.BEGIN_LOAD (gname IN VARCHAR2, sname IN VARCHAR2, master_site IN VARCHAR2, snapshot_oname IN VARCHAR2, storage_c IN VARCHAR2 := '', comment IN VARCHAR2 := '', min_communicatio IN BOOLEAN := TRUE ); Parameters are summarized in the following table. Name Description gname The replication group to which the new snapshot belongs. sname The schema that owns the new snapshot. master_site The global name of the snapshot master site. snapshot_oname The name of the temporary snapshot created at the master site. storage_c Optional storage clause for the new snapshot. comment Optional comment for the snapshot; stored with entry in DBA_SNAPSHOTS if supplied. min_communication The min_communication parameter controls how the update trigger on updateable snapshots queues changes back to the master site. If this parameter is set to TRUE (the [Appendix A] What's on the Companion Disk? 14.3.1 Getting Started with DBMS_OFFLINE_SNAPSHOT 627 (Oracle8 only) default), then old column values are sent only if the update changes their value. New column values are sent only if the column is part of primary key, or if the column is in a column group that has been modified. The BEGIN_LOAD procedure does not raise any exceptions. 14.3.2.2 The DBMS_OFFLINE_SNAPSHOT.END_LOAD procedure Call the END_LOAD procedure after the data import (initiated by the BEGIN_LOAD procedure) is complete. The specification is the same for Oracle7 and Oracle8: PROCEDURE DBMS_OFFLINE_SNAPSHOT.END_LOAD (gname IN VARCHAR2, sname IN VARCHAR2, snapshot_oname IN VARCHAR2); Parameters have the same meanings as for the BEGIN_LOAD procedure (see the previous section). The END_LOAD procedure does not raise any exceptions. 14.2 DBMS_REFRESH: Managing Snapshot Groups 14.4 DBMS_REPCAT: Managing Snapshot Replication Groups Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 14.3.2 DBMS_OFFLINE_SNAPSHOT Interface 628 Chapter 14 Snapshots 14.4 DBMS_REPCAT: Managing Snapshot Replication Groups Although most of the procedures in the DBMS_REPCAT package are used to create and maintain the advanced replication environment, some of the procedures let you manipulate snapshot replication groups. This section describes only the snapshot−related programs. The bulk of the DBMS_REPCAT programs are described in Chapters 15 and 16. The procedures in DBMS_REPCAT used for manipulating snapshot replication groups are in large measure analogous to the procedures DBMS_REFRESH provides for manipulating simple snapshot groups. 14.4.1 Getting Started with DBMS_REPCAT The DBMS_REPCAT package is created when the Oracle database is installed. The dbmsrepc.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 script creates the public synonym DBMS_REPCAT. The package procedure DBMS_REPCAT_AUTH.GRANT_SURROGATE_REPCAT grants EXECUTE privileges on the package to the specified grantee. In addition, the package owner (SYS) and users with the EXECUTE ANY PROCEDURE system privilege may execute it. 14.4.1.1 DBMS_REPCAT programs Table 14.5 lists only the DBMS_REPCAT snapshot−related programs; see Tables 15−3 and 16−10 for the remaining DBMS_REPCAT programs. Table 14.5: DBMS_REPCAT Programs (Snapshots Only) Name Description Use in SQL ALTER_SNAPSHOT_PROPAGATION Changes a snapshot replication group's propagation mode No CREATE_SNAPSHOT_REPGROUP Creates a snapshot replication group No CREATE_SNAPSHOT_REPOBJECT Adds an object to a snapshot replication group No DROP_SNAPSHOT_REPGROUP Drops a snapshot replication group No DROP_SNAPSHOT_REPOBJECT Drops an object from a snapshot replication group No REFRESH_SNAPSHOT_REPGROUP Refreshes a snapshot replication group No SWITCH_SNAPSHOT_MASTER Remasters a snapshot site to another master site No 629 14.4.1.2 DBMS_REPCAT exceptions DBMS_REPCAT defines the following exceptions for the programs listed in Table 14.6. Table 14.6: DBMS_REPCAT Exceptions Name Number Description commfailure −23317 Unable to communicate with master dbnotcompatible −23375 Attempt to use SYNCHRONOUS propagation in Pre−7.3 database ddlfailure −23318 Unable to perform DDL duplicateobject −23309 Object oname already exists duplicaterepgroup −23374 Replication group gname already exists missingobject −23308 Object oname does not exist in master's replication group gname missingremoteobject −23381 Master site has not generated replication support for oname missingrepgroup −23373 Replication group gname does not exist missingschema −23306 Schema sname does not exist misssnapobject −23355 Object oname does not exist at master nonmaster −23312 Master site associated with snapshot group is no longer a master site nonsnapshot −23314 Calling site is not a snapshot site norepoption −23364 Replication option not installed typefailure −23319 propagation_mode not specified correctly 14.4.2 Creating and Dropping Snapshot Replication Groups The CREATE_SNAPSHOT_REPGROUP and DROP_SNAPSHOT_REPGROUP procedures allow you to create and destroy snapshot replication groups. 14.4.2.1 The DBMS_REPCAT.CREATE_SNAPSHOT_REPGROUP procedure This procedure creates a new, empty snapshot replication group. You must invoke it from the snapshot site. The program specification follows: PROCEDURE DBMS_REPCAT.CREATE_SNAPSHOT_REPGROUP (gname IN VARCHAR2, master IN VARCHAR2, comment IN VARCHAR2 := '', propagation_mode IN VARCHAR2 := 'ASYNCHRONOUS'); Parameters are summarized in the following table. Name Description gname Name of the new snapshot group master Global name of master site comment Comment for the snapshot group; visible in DBA_REPSITES data dictionary view propagation_mode Snapshot propagation mode (SYNCHRONOUS, or ASYNCHRONOUS) [Appendix A] What's on the Companion Disk? 14.4.1 Getting Started with DBMS_REPCAT 630 . beginning to load data from an export file. The specifications for the Oracle7 and Oracle8 versions differ as follows. Here is the Oracle7 specification: PROCEDURE DBMS_OFFLINE_SNAPSHOT.BEGIN_LOAD . DBMS_OFFLINE_SNAPSHOT The DBMS_OFFLINE_SNAPSHOT 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). import (initiated by the BEGIN_LOAD procedure) is complete. The specification is the same for Oracle7 and Oracle8 : PROCEDURE DBMS_OFFLINE_SNAPSHOT.END_LOAD (gname IN VARCHAR2, sname IN VARCHAR2,