(:jobno ,'smart_job(180,''NO_RESTART'',next_date,broken,job);' ,SYSDATE + 1/1440 ,'SYSDATE + 1'); COMMIT WORK; END; / print jobno BEGIN /* || Test the ability to break itself. */ DBMS_JOB.ISUBMIT (99 ,'smart_job(180,''RESTART'',next_date,broken,job);' ,SYSDATE + 1/1440 ,'SYSDATE + 1'); COMMIT WORK; END; / After executing the test script in SQL*Plus, the following jobs are in the queue: SQL> SELECT job,last_date,next_date,broken FROM user_jobs; JOB LAST_DATE NEXT_DATE B −−−−−−−−− −−−−−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−− − 307 1997:11:25:11:50:39 N 308 1997:11:25:11:50:39 N 99 1997:11:25:11:50:40 N A few minutes later, the job queue looks like this: SQL> SELECT job,last_date,next_date,broken FROM user_jobs; JOB LAST_DATE NEXT_DATE B −−−−−−−−− −−−−−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−− − 307 1997:11:25:11:50:42 1997:11:25:14:50:42 N 99 1997:11:25:11:50:42 1997:11:26:11:50:42 Y The tests worked! Job 308 ran once and was removed from the queue for having a NULL next_date. Job 307 ran and rescheduled itself three hours later, which is different from the interval specified in the call to DBMS_JOB.SUBMIT. Finally, job 99 set itself to broken status because its job number was less than 100. 13.3 Tips on Using DBMS_JOB IV. Distributed Database Packages Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 13.4.3 Self−Modifying and Self−Aware Jobs 601 Chapter 14 602 14. Snapshots Contents: DBMS_SNAPSHOT: Managing Snapshots DBMS_REFRESH: Managing Snapshot Groups DBMS_OFFLINE_SNAPSHOT: Performing Offline Snapshot Instantiation DBMS_REPCAT: Managing Snapshot Replication Groups Oracle provides a number of packages that let you perform various types of administrative operations on snapshots and snapshot logs. Most of these administrative operations are relevant only if you are using snapshot groups or the Oracle advanced replication option. This chapter describes the following packages: DBMS_SNAPSHOT Lets you maintain snapshots and snapshot logs. DBMS_OFFLINE_SNAPSHOT Allows you to instantiate snapshots without having to run the CREATE SNAPSHOT command over the network. This package is particularly useful if you need to instantiate extremely large snapshots. DBMS_REFRESH Administers snapshot groups at a snapshot site. DBMS_REPCAT Performs a number of advanced replication operations. This chapter describes only the DBMS_REPCAT programs that deal with snapshots; all other programs are described in Chapter 15, Advanced Replication. Even if you are using PL/SQL's built−in snapshot packages, you will continue to use the CREATE SNAPSHOT command to create your snapshots. 14.1 DBMS_SNAPSHOT: Managing Snapshots The DBMS_SNAPSHOT package contains programs that allow you to maintain snapshots and snapshot logs, and to set and query package state variables associated with the advanced replication option. 14.1.1 Getting Started with DBMS_SNAPSHOT The DBMS_SNAPSHOT package is created when the Oracle database is installed. The dbmssnap.sql script (found in the built−in packages source directory, as described in Chapter 1, Introduction) contains the source code for this package's specification. This script is called by catproc.sql, which is normally run immediately after database creation. The script creates the public synonym DBMS_SNAPSHOT for the package and grants EXECUTE privilege on the package to public. All Oracle users can reference and make use of this package. Table 14−1 lists the programs contained in the DBMS_SNAPSHOT package. Table 14.1: DBMS_SNAPSHOT Packages Name Description Use in SQL? No 14. Snapshots 603 BEGIN_TABLE_REORGANIZATION (Oracle8 only) Called prior to reorganizing a master table (e.g., through export/import); saves data required to refresh snapshots END_TABLE_REORGANIZATION (Oracle8 only) Called after reorganizing a master table (e.g., through export/import); validates data required to refresh snapshots No I_AM_A_REFRESH Returns value of REP$WHAT_AM_I.I_AM_A_SNAPSHOT No PURGE_LOG Purges snapshot log No REFRESH Refreshes a snapshot No REGISTER_SNAPSHOT (Oracle8 only) Records information about snapshots at the master site in the DBA_REGISTERED_SNAPSHOTS data dictionary view No SET_I_AM_A_REFRESH Sets REP$WHAT_AM_I.I_AM_A_SNAPSHOT to specified value No UNREGISTER_SNAPSHOT (Oracle8 only) Removes information about snapshots at the master site from the DBA_REGISTERED_SNAPSHOTS data dictionary view No DBMS_SNAPSHOT does not define any exceptions. NOTE: All of the programs in DBMS_SNAPSHOT are available regardless of whether you are using snapshot groups or the advanced replication option. 14.1.2 Using the I_AM_A_REFRESH Package State Variable The I_AM_A_REFRESH and SET_I_AM_A_REFRESH programs query and set Oracle's REP$I_AM_A_REFRESH package variable. Oracle uses this variable in replication triggers and elsewhere internally to determine whether a given DML statement should be replicated to other master sites. 14.1.2.1 The DBMS_SNAPSHOT.I_AM_A_REFRESH function The I_AM_A_REFRESH function queries the REP$I_AM_A_REFRESH package variable. If this variable equals "Y," then the session is refreshing a snapshot or applying propagated DML to a replicated table. The header for the function follows: FUNCTION DBMS_SNAPSHOT.I_AM_A_REFRESH RETURN BOOLEAN; The function does not raise any exceptions. 14.1.2.1.1 Examples Let's look at several examples of querying the I_AM_A_REFRESH package variable. 14.1.2.1.2 Generating replication support Suppose now that you are replicating a table named COUNTRIES in the SPROCKET schema: SQL> DESC sprocket.countries Name Null? Type −−−−−−−−−−−−−−− −−−−−−−−− −−−−−−−−−−−−−− [Appendix A] What's on the Companion Disk? 14.1.2 Using the I_AM_A_REFRESH Package State Variable 604 COUNTRY_ID NOT NULL NUMBER(6) ISO3166_NUMBER NOT NULL NUMBER(3) ISO3166_NAME NOT NULL VARCHAR2(50) ISO2_CODE NOT NULL VARCHAR2(2) ISO3_CODE NOT NULL VARCHAR2(3) AUDIT_DATE NOT NULL DATE AUDIT_USER NOT NULL VARCHAR2(30) GLOBAL_NAME NOT NULL VARCHAR2(20) When you generate replication support for this table with DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT (described in Chapter 15), Oracle creates an AFTER ROW trigger named COUNTRIES$RT, which queues DML to other master sites. The text of the trigger follows: after delete or insert or update on "SPROCKET"."COUNTRIES" for each row declare flag char; begin if "COUNTRIES$TP".active then if inserting then flag := 'I'; elsif updating then flag := 'U'; elsif deleting then flag := 'D'; end if; "COUNTRIES$TP".replicate( :old."AUDIT_DATE",:new."AUDIT_DATE", :old."AUDIT_USER",:new."AUDIT_USER", :old."COUNTRY_ID",:new."COUNTRY_ID", :old."GLOBAL_NAME",:new."GLOBAL_NAME", :old."ISO2_CODE",:new."ISO2_CODE", :old."ISO3166_NAME",:new."ISO3166_NAME", :old."ISO3166_NUMBER",:new."ISO3166_NUMBER", :old."ISO3_CODE",:new."ISO3_CODE", flag); end if; end; As you can see, this trigger replicates DML only if the function COUNTRIES$TP.active is TRUE. This ACTIVE function uses DBMS_SNAPSHOT.I_AM_A_REFRESH as follows: function active return boolean is begin return (not((is_snapshot and dbms_snapshot.I_am_a_refresh) or not dbms_reputil.replication_is_on)); end active; Oracle uses the active function, which calls DBMS_SNAPSHOT.I_AM_A_REFRESH, to distinguish between your application's DML operations and the DML that is being propagated from another master site. The base table of an updateable snapshot has a trigger that also uses the I_AM_A_REFRESH function. 14.1.2.1.3 Auditing triggers Under some circumstances, you may need to determine the source of DML statements. For example, you will notice that the countries table has a number of fields used for auditing: audit_date, audit_user, and global_name. We have a BEFORE ROW trigger that populates these fields. CREATE OR REPLACE TRIGGER countries_audit [Appendix A] What's on the Companion Disk? 14.1.2 Using the I_AM_A_REFRESH Package State Variable 605 . with DBMS_SNAPSHOT The DBMS_SNAPSHOT package is created when the Oracle database is installed. The dbmssnap.sql script (found in the built−in packages source directory, as described in Chapter 1,. 603 BEGIN_TABLE_REORGANIZATION (Oracle8 only) Called prior to reorganizing a master table (e.g., through export/import); saves data required to refresh snapshots END_TABLE_REORGANIZATION (Oracle8 only) Called. Variable The I_AM_A_REFRESH and SET_I_AM_A_REFRESH programs query and set Oracle& apos;s REP$I_AM_A_REFRESH package variable. Oracle uses this variable in replication triggers and elsewhere internally