BEFORE INSERT OR UPDATE ON countries FOR EACH ROW DECLARE vGlobalName VARCHAR2(30) := DBMS_REPUTIL.GLOBAL_NAME; BEGIN IF NOT (DBMS_SNAPSHOT.I_AM_A_REFRESH) THEN BEGIN :new.audit_date := SYSDATE; :new.audit_user := USER; :new.global_name := vGlobalName; END IF; END; This trigger fires when an application performs an INSERT or UPDATE, but not when the DML is propagated from other sites. NOTE: All row−level replication triggers are AFTER ROW triggers. Although a table can have multiple triggers of the same type, you cannot control the order in which they are fired. Therefore, it is safest to use BEFORE ROW triggers to perform auditing on replicated tables; in this way, you are guaranteed that BEFORE ROW triggers fire before AFTER ROW triggers. 14.1.2.2 The DBMS_SNAPSHOT.SET_I_AM_A_REFRESH procedure The SET_I_AM_A_REFRESH procedure sets the I_AM_A_REFRESH package variable. The header for the procedure is: PROCEDURE DBMS_SNAPSHOT.SET_I_AM_A_REFRESH (value IN BOOLEAN); where value is the value (Y or N) being set. This procedure does not raise any exceptions. 14.1.2.2.1 Example If you need to enable and disable replication triggers at the session level, you can do so with the SET_I_AM_A_REFRESH procedure. To enable the triggers, specify the following: DBMS_SNAPSHOT.SET_I_AM_A_REFRESH( value => FALSE ) To disable them, specify the following: DBMS_SNAPSHOT.SET_I_AM_A_REFRESH( value => TRUE ) Use this package carefully, because disabling replication triggers effectively disables any conflict resolution mechanisms you may have defined. (See Chapter 17, Deferred Transactions and Remote Procedure Calls, for a discussion of these mechanisms.) 14.1.3 Refreshing Snapshots Calling the REFRESH procedure from a snapshot site forces the refresh of the specified snapshot(s). Typically, this procedure is used to refresh an individual snapshot, or a group of snapshots that are not in the same snapshot refresh group. 14.1.3.1 The DBMS_SNAPSHOT.REFRESH procedure Call the REFRESH procedure to force a snapshot refresh. The specifications for the Oracle7 and Oracle8 versions of the REFRESH procedure differ. Note that the Version 8.0 implementation adds parameters that [Appendix A] What's on the Companion Disk? 14.1.2 Using the I_AM_A_REFRESH Package State Variable 606 support parallelism, and drops the execute_as_user parameter. Both versions are overloaded, allowing you to specify the list of snapshots as a comma−delimited string in the list parameter, or as a PL/SQL table in the tab parameter. The other parameters are identical for the two versions. Here is the Oracle7 specification: PROCEDURE DBMS_SNAPSHOT.REFRESH (list IN VARCHAR2, method IN VARCHAR2 DEFAULT NULL, rollback_seg IN VARCHAR2 DEFAULT NULL, push_deferred_rpc IN BOOLEAN DEFAULT TRUE, refresh_after_errors IN BOOLEAN DEFAULT FALSE, execute_as_user IN BOOLEAN DEFAULT FALSE ); PROCEDURE DBMS_SNAPSHOT.REFRESH (tab IN OUT dbms_utility.uncl_array, method IN VARCHAR2 DEFAULT NULL, rollback_seg IN VARCHAR2 DEFAULT NULL, push_deferred_rpc IN BOOLEAN DEFAULT TRUE, refresh_after_errors IN BOOLEAN DEFAULT FALSE, execute_as_user IN BOOLEAN DEFAULT FALSE ); Here is the Oracle8 specification: PROCEDURE DBMS_SNAPSHOT.REFRESH (list IN VARCHAR2, method IN VARCHAR2 := NULL, rollback_seg IN VARCHAR2 := NULL, push_deferred_rpc IN BOOLEAN := TRUE, refresh_after_errors IN BOOLEAN := FALSE, purge_option IN BINARY_INTEGER := 1, parallelism IN BINARY_INTEGER := 0, heap_size IN BINARY_INTEGER := 0); PROCEDURE DBMS_SNAPSHOT.REFRESH (tab IN OUT dbms_utility.uncl_array, method IN VARCHAR2 := NULL, rollback_seg IN VARCHAR2 := NULL, push_deferred_rpc IN BOOLEAN := TRUE, refresh_after_errors IN BOOLEAN := FALSE, purge_option IN BINARY_INTEGER := 1, parallelism IN BINARY_INTEGER := 0, heap_size IN BINARY_INTEGER := 0); Parameters are summarized in the following table. Name Description list Comma−separated list of snapshots to be refreshed. Use list or tab. tab PL.SQL table of snapshots to be refreshed. Use list or tab. method Refresh method: `?' uses the default refresh method. If you specified a refresh method when you created the snapshot, that is the default method. Otherwise, Oracle uses a fast refresh if possible, and a complete refresh if not. `F' or `f' uses fast refresh if possible, and returns ORA−12004 if not. `C' or `c' uses a COMPLETE refresh. This parameter should include a single character for each snapshot specified in list or tab, in the same order as the snapshot names [Appendix A] What's on the Companion Disk? 14.1.2 Using the I_AM_A_REFRESH Package State Variable 607 appear. If list or tab contains more snapshots than the method list, the additional snapshots are refreshed with their default method. rollback_seg Optional; specifies the rollback segment to use for the refresh. push_deferred_rpc Optional; for updateable snapshots only. If TRUE (the default), then local updates are sent back to the master site before the snapshot is refreshed (otherwise, local updates will be temporarily overwritten). refresh_after_errors Optional; for updateable snapshots only. If TRUE, proceed with the refresh even if outstanding errors (conflicts) are logged in the DEFERROR data dictionary view at the master site. Default is FALSE. execute_as_user (Version 7 only) If FALSE (the default) then the call to the remote system is performed under the privilege domain of the user that created the snapshot. If TRUE, the call is performed as the user calling the refresh procedure. purge_option (Oracle8 only) If push_deferred_rpc is TRUE, this designates the purge method; default is 1. • 0 No purge • 1 Lazy purge (optimized for time) • 2 Aggressive purge (complete) parallelism (Oracle8 only) If push_defered_rpc is TRUE, this determines the maximum degree of parallelism; default is 1. • 0 Serial • 1 Parallel with one slave • N Parallel with N slaves (N > 1) heap_size (Oracle8 only) Used only if parallelism > 0. Sets the maximum number of transactions to be examined simultaneously for determining parallel scheduling. Oracle determines this value internally; you are advised not to use it. The REFRESH procedure does not raise any exceptions. All of the snapshots passed to list or tab are refreshed as a single transaction; all or none are refreshed. In addition, the refreshed snapshots will respect all integrity constraints that exist among the master tables. You might want to force a manual refresh of a snapshot if the next scheduled refresh is too far in the future, or if you have repaired a problem that caused the scheduled refresh job to break. Forcing a manual refresh of a snapshot does not alter its refresh schedule. A FAST refresh requires a snapshot log on the master table, and is possible only for simple snapshots in Oracle7; Oracle8 supports fast refreshes subquery snapshots meeting certain conditions. Fast refreshes read the snapshot log to determine which rows have changed since the last refresh, and only those rows are updated. [Appendix A] What's on the Companion Disk? 14.1.2 Using the I_AM_A_REFRESH Package State Variable 608 If you are concerned about the amount of rollback the refresh will require, you can use the rollback_seg parameter to designate a rollback segment that is suitably sized for the transaction. However, you are not guaranteed that no other transactions will use this rollback segment. In general, you should consider making relatively large rollback segments if you anticipate frequent refreshes of large snapshots. 14.1.3.1.1 Restrictions You can call REFRESH only from a snapshot site. 14.1.3.1.2 Examples Once you are familiar with the various parameters to the REFRESH procedure, it becomes simple to use, as the following examples illustrate. 14.1.3.1.3 Read−only snapshot This example shows a refresh as a read−only snapshot named PRICE_LIST: BEGIN DBMS_SNAPSHOT.REFRESH (list => 'PRICES'); END; This is the simplest possible refresh method. Note that since we have not provided a schema name, this would have to be executed from the snapshot owner's account. 14.1.3.1.4 Related read−only snapshots In the next example, we refresh a set of related read−only snapshots. DECLARE vSnapshotList dbms_utility.uncl_array BEGIN vSnapshotList(1) = 'COUNTRIES' vSnapshotList(2) = 'STATES' vSnapshotList(3) = 'POSTAL_CODES' vSnapshotList(4) = 'CUSTOMER_ADDRESSES' DBMS_SNAPSHOT.REFRESH( tab => vSnapShotList, method => 'CCF?', rollback_segment => 'RB1' execute_as_user => FALSE); END; This example illustrates several points: 1. You can provide the list of snapshots as a PL/SQL table. Oracle will refresh all of the snapshots in one atomic transaction; either all or none of the snapshots are refreshed. All referential consistencies among the master tables will be preserved in the snapshot tables. 2. You can specify different refresh methods for each snapshot. This example performs a complete refresh on COUNTRIES and STATES, a full refresh on POSTAL_CODES, and a fast refresh (if possible) on CUSTOMER_ADDRESSES. If Oracle cannot use a fast refresh on the CUSTOMER_ADDRESS table, it will perform a complete refresh instead. 3. You can designate a specific, suitably sized rollback segment for the refresh. 4. [Appendix A] What's on the Companion Disk? 14.1.3 Refreshing Snapshots 609 You can set the parameter, execute_as_user, to FALSE to force Oracle to refresh the snapshot under the privilege domain of the snapshot owner. 14.1.3.1.5 Updateable snapshot. In the next example, we refresh the updateable snapshot DAILY_STORE_SALES. DECLARE vSnapshotList dbms_utility.uncl_array BEGIN vSnapshotList(1) = 'DAILY_STORE_SALES' DBMS_SNAPSHOT.REFRESH( tab => vSnapShotList, method => '?' push_deferred_rpc => FALSE); END; Since we set push_deferred_rpc to FALSE (the default is TRUE), the refresh will overwrite any local changes. The local changes will be visible again after the remote procedure call (RPC) pushes them to the master site and snapshot is refreshed again. 14.1.3.1.6 Parallel refreshes In this example, the parallelism feature of Oracle8 allows us to use four processes to refresh the updateable snapshot DAILY_STORE_SALES: DECLARE vSnapshotList dbms_utility.uncl_array BEGIN vSnapshotList(1) = 'DAILY_STORE_SALES' DBMS_SNAPSHOT.REFRESH( tab => vSnapShotList, method => '?' parallelism => 4, purge_option = 2); END; The purge_option parameter controls how Oracle purges the snapshot site's deferred transaction queue; Oracle8 does not purge the queue automatically when the transactions propagate, so you must use DBMS_DEFER_SYS.SCHEDULE_PURGE (described in Chapter 17) to schedule a job to purge the queue, lest it become large and unmanageable. The purge_option parameter in REFRESH provides an opportunity to purge the queue of transactions associated with the updateable snapshot(s) you are refreshing. NOTE: Purging the deferred transaction queue is not the same thing as purging a snapshot log! 14.1.4 Purging the Snapshot Log The PURGE_LOG procedure deletes records from the snapshot log on a master table. You may wish to do this if the snapshot log becomes very large, or if you drop a subset of the snapshots for which the table is a master. 14.1.4.1 The DBMS_SNAPSHOT.PURGE.LOG procedure Call the PURGE_LOG procedure to delete snapshot log records. The specification for the PURGE_LOG procedure follows: PROCEDURE DBMS_SNAPSHOT.PURGE_LOG [Appendix A] What's on the Companion Disk? 14.1.3 Refreshing Snapshots 610 . procedure Call the REFRESH procedure to force a snapshot refresh. The specifications for the Oracle7 and Oracle8 versions of the REFRESH procedure differ. Note that the Version 8.0 implementation. procedure. purge_option (Oracle8 only) If push_deferred_rpc is TRUE, this designates the purge method; default is 1. • 0 No purge • 1 Lazy purge (optimized for time) • 2 Aggressive purge (complete) parallelism (Oracle8 . > 1) heap_size (Oracle8 only) Used only if parallelism > 0. Sets the maximum number of transactions to be examined simultaneously for determining parallel scheduling. Oracle determines this