Oracle Built−in Packages- P139 ppsx

The specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.RELOCATE_MASTERDEF (gname IN VARCHAR2 := '', old_masterdef IN VARCHAR2, new_masterdef IN VARCHAR2, notify_masters IN BOOLEAN := TRUE, include_old_masterdef IN BOOLEAN := TRUE, sname IN VARCHAR2 := '') Here is the Oracle8 specification: PROCEDURE DBMS_REPCAT.RELOCATE_MASTERDEF (gname IN VARCHAR2, old_masterdef IN VARCHAR2, new_masterdef IN VARCHAR2, notify_masters IN BOOLEAN := TRUE, include_old_masterdef IN BOOLEAN := TRUE); Parameters are summarized in the following table. Name Description gname Name of the replication group. old_masterdef Global name of the current master definition site. new_masterdef Global name of the new master definition site. notify_masters If TRUE (the default), synchronously multicast information about the change to all masters; if FALSE, do not inform masters. include_old_masterdef If TRUE (the default), notify current master definition site of the change. sname (Oracle7 only) Not used. 15.3.5.4.1 Exceptions The RELOCATE_MASTERDEF procedure may raise the following exceptions: Name Number Description commfailure −23317 Unable to communicate with master site(s) and notify_masters is TRUE nonmaster −23313 The new_masterdef is not a master site nonmasterdef −23312 The old_masterdef is not the master definition site 15.3.5.4.2 Restrictions You must call RELOCATE_MASTERDEF from a master or master definition site. 15.3.5.4.3 Example The following call relocates the master definition site for replication group SPROCKET from D7CA.BIGWHEEL.COM to D7NY.BIGWHEEL.COM, and informs all masters, as well as the master definition site, of the change: BEGIN DBMS_REPCAT.RELOCATE_MASTERDEF( gname => 'SPROCKET', old_master_def => 'D7CA.BIGWHEEL.COM', [Appendix A] What's on the Companion Disk? 15.3.5 Adding and Removing Master Sites with DBMS_REPCAT 681 new_master_def => 'D7NY.BIGWHEEL.COM', notify_masters => TRUE, include_old_masterdef=> TRUE); END; Suppose that the master definition site D7CA.BIGWHEEL.COM becomes permanently unavailable. We can convert another site, such as D7NY.BIGWHEEL.COM, into the master definition site without having to communicate with D7CA.BIGWHEEL.COM. We set the include_old_masterdef parameter to FALSE. BEGIN DBMS_REPCAT.RELOCATE_MASTERDEF( gname => 'SPROCKET', old_master_def => 'D7CA.BIGWHEEL.COM', new_master_def => 'D7NY.BIGWHEEL.COM', notify_masters => TRUE, include_old_masterdef=> FALSE); END; 15.3.6 Maintaining the Repcatlog Queue with DBMS_REPCAT The programs in this category maintain the "repcatlog" queue. You'll use these procedures: DBMS_REPCAT.DO_DEFERRED_REPCAT_ADMIN DBMS_REPCAT.WAIT_MASTER_LOG DBMS_REPCAT.PURGE_MASTER_LOG The following sections describe these programs. 15.3.6.1 The DBMS_REPCAT.DO_DEFERRED_REPCAT_ADMIN procedure Whenever you create or alter replicated objects −− for example, with the GENERATE_REPLICATION_SUPPORT or ALTER_MASTER_REPOBJECT procedure −− Oracle queues the changes in the "repcatlog" queue; the entries in this queue correspond to entries in the DBA_REPCATLOG data dictionary view. All DDL changes must originate at the master definition site, but the repcatlog queue exists at every master site. The DO_DEFERRED_REPCAT_ADMIN procedure processes entries in the repcatlog queue at all master sites. You may have noticed this job in the job queue, scheduled to run once every ten minutes. Oracle creates this scheduled job the first time you execute one of the packages that performs DDL. The specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.DO_DEFERRED_REPCAT_ADMIN (gname IN VARCHAR2 := '', all_sites IN BOOLEAN := FALSE, sname IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DBMS_REPCAT.DO_DEFERRED_REPCAT_ADMIN (gname IN VARCHAR2, all_sites IN BOOLEAN := FALSE); As with all of the other DBMS_REPCAT procedures, the Oracle8 version does not have the sname parameter. [Appendix A] What's on the Companion Disk? 15.3.6 Maintaining the Repcatlog Queue with DBMS_REPCAT 682 Parameters are summarized in the following table. Name Description gname Name of the replication group for which to push the repcatlog queue all_sites If TRUE, execute queued procedures at every master site sname (Oracle7 only) Not used 15.3.6.1.1 Exceptions The DO_DEFERRED_REPCAT_ADMIN procedure may raise the following exceptions: Name Number Description commfailure −23317 Unable to communicate with master site nonmaster −23312 Master site associated with snapshot group is no longer a master site 15.3.6.1.2 Restrictions The DO_DEFERRED_REPCAT_ADMIN procedure performs only the procedures that have been queued by the invoking user. Note that the job queue is used to perform the queued procedures automatically. 15.3.6.1.3 Example. If you want to run DO_DEFERRED_REPCAT_ADMIN manually, either because you do not have DBMS_JOB background processes running, or because you want to push the repcatlog queue immediately, you can do so. Here is an example: BEGIN DBMS_REPCAT.DO_DEFFERED_REPCAT_ADMIN ( gname => 'SPROCKET', all_sites => TRUE); END; For an additional example, see the catlog.sql file on the companion disk. The example lists entries in the repcatlog (DBA_REPCATLOG) with the time of submission in hours, minutes, and seconds. 15.3.6.2 The DBMS_REPCAT.WAIT_MASTER_LOG procedure You can use the WAIT_MASTER_LOG procedure to ascertain whether the changes in the repcatlog queue have reached the master sites. This procedure has an OUT parameter, true_count, which the procedure populates with the number of outstanding tasks. The specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.WAIT_MASTER_LOG (gname IN VARCHAR2 := '', record_count IN NATURAL, timeout IN NATURAL, true_count OUT NATURAL, sname IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DBMS_REPCAT.WAIT_MASTER_LOG (gname IN VARCHAR2, record_count IN NATURAL, timeout IN NATURAL, true_count OUT NATURAL); [Appendix A] What's on the Companion Disk? 15.3.6 Maintaining the Repcatlog Queue with DBMS_REPCAT 683 Parameters are summarized in the following table. Name Description gname Name of the replication group record_count Number of records to allow to be entered in the DBA_REPCATLOG data dictionary view before returning timeout Number of seconds to wait before returning true_count Output variable containing the actual number of incomplete activities queued in the DBA_REPCATLOG data dictionary view sname Not used There are no restrictions on calling WAIT_MASTER_LOG. 15.3.6.2.1 Exceptions The WAIT_MASTER_LOG procedure may raise the following exception: Name Number Description nonmaster −23312 Calling site is not a master site 15.3.6.2.2 Example The following call returns after 60 seconds, or after five entries have been entered into the DBA_REPCATLOG data dictionary view at the current master for replication group SPROCKET. The number of records (corresponding to incomplete tasks) is stored in the variable vRecCount. VARIABLE vRecCount NATURAL BEGIN DBMS_REPCAT.WAIT_MASTER_LOG(gname=> 'SPROCKET', record_count => 5, timeout => 60, true_count => vRecCount); END; NOTE: You might find it more convenient to query the DBA_REPCATLOG data dictionary view directly. 15.3.6.3 The DBMS_REPCAT.PURGE_MASTER_LOG procedure The DBA_REPCATLOG data dictionary view retains entries on DDL propagations that have failed; these entries are not removed when you resolve the problem that caused the failure. You may notice entries such as these: 1 SELECT source, status, request, to_char(timestamp, 'HH24:MI:SS') timestamp 2 FROM dba_repcatlog 3* ORDER BY id system@d7ca SQL> / Source Status Request Time −−−−−−−−−−−−−−−−−−−− −−−−−−− −−−−−−−−−−−−−−−−−−−−−−−− −−−−−−−−−−−−−−− D7CA.BIGWHEEL.COM ERROR CREATE_MASTER_REPOBJECT 23:13:07 D7CA.BIGWHEEL.COM ERROR CREATE_MASTER_REPOBJECT 23:13:07 D7CA.BIGWHEEL.COM ERROR CREATE_MASTER_REPOBJECT 23:25:20 D7CA.BIGWHEEL.COM ERROR CREATE_MASTER_REPOBJECT 23:25:20 D7CA.BIGWHEEL.COM ERROR CREATE_MASTER_REPOBJECT 23:26:53 D7CA.BIGWHEEL.COM ERROR CREATE_MASTER_REPOBJECT 23:26:53 D7CA.BIGWHEEL.COM ERROR DROP_MASTER_REPOBJECT 14:03:27 [Appendix A] What's on the Companion Disk? 15.3.6 Maintaining the Repcatlog Queue with DBMS_REPCAT 684 D7CA.BIGWHEEL.COM ERROR DROP_MASTER_REPOBJECT 14:03:27 8 rows selected. You must use the PURGE_MASTER_LOG procedure to remove these entries from DBA_REPCATLOG. You can specify records to delete by id, originating master, replication group, and schema. If a parameter is NULL, it is treated as a wildcard. Specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.PURGE_MASTER_LOG (id IN NATURAL, source IN VARCHAR2, gname IN VARCHAR2 := '', sname IN VARCHAR2 := ''); Here is the Oracle8 specification: PROCEDURE DBMS_REPCAT.PURGE_MASTER_LOG (id IN NATURAL, source IN VARCHAR2, gname IN VARCHAR2); Parameters are summarized in the following table. Name Description id Identification of the request (i.e., the ID field in DBA_REPCATLOG data dictionary view) source Global name of originating master gname Name of the replication group for which request was made sname (Oracle7 only) Not used 15.3.6.3.1 Exceptions The PURGE_MASTER_LOG procedure may raise the following exception: Name Number Description nonmaster −23312 The gname is NULL and calling site is not a master site 15.3.6.3.2 Restrictions The calling site must be a master site. 15.3.6.3.3 Example The following call removes all entries associated with replication group SPROCKET from the DBA_REPCATLOG data dictionary view: BEGIN DBMS_REPCAT.PURGE_MASTER_LOG(gname=> 'SPROCKET' ); END; For an additional example, see the caterr.sql file on the companion disk. The example lists entries in the repcatlog (DBA_REPCATLOG) containing errors, and displays the error message associated with each error. [Appendix A] What's on the Companion Disk? 15.3.6 Maintaining the Repcatlog Queue with DBMS_REPCAT 685 . minutes. Oracle creates this scheduled job the first time you execute one of the packages that performs DDL. The specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE. The specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.RELOCATE_MASTERDEF (gname IN. procedure populates with the number of outstanding tasks. The specifications differ for Oracle7 and Oracle8 as follows. Here is the Oracle7 specification: PROCEDURE DBMS_REPCAT.WAIT_MASTER_LOG (gname IN VARCHAR2