Oracle Built−in Packages- P40 pot

Alert names are limited to 30 bytes and are case−insensitive. • Alert names beginning with "ORA$" are reserved for use by Oracle Corporation. 3.2.2.1.3 Example In this example, the session will be registered to be notified of the EMP_INSERT alert, which is raised whenever INSERTs are performed on the EMP table: BEGIN DBMS_ALERT.REGISTER('EMP_INSERT'); END; 3.2.2.2 The DBMS_ALERT.REMOVE procedure The REMOVE procedure unregisters a session's interest in receiving notification of a specific alert. It has the following header, PROCEDURE DBMS_ALERT.REMOVE (name IN VARCHAR2); where name is the name of the alert to unregister from notification. The REMOVE procedure does not raise any package exceptions, nor does it assert a purity level with the RESTRICT_REFERENCES pragma. 3.2.2.2.1 Example The following example unregisters for the EMP_INSERT alert: BEGIN DBMS_ALERT.REMOVE('EMP_INSERT'); END; 3.2.2.3 The DBMS_ALERT.REMOVEALL procedure The REMOVEALL procedure unregisters the session from receiving notification of any and all alerts that have been previously registered. Here's the header: PROCEDURE DBMS_ALERT.REMOVEALL; The REMOVEALL procedure does not raise package exceptions, nor does it assert a purity level with the RESTRICT_REFERENCES pragma. 3.2.2.3.1 Example This example stops all alert notifications to the session: SQL> execute DBMS_ALERT.REMOVALL; 3.2.2.4 The DBMS_ALERT.SET_DEFAULTS procedure The SET_DEFAULTS procedure is used to set session configurable settings used by the DBMS_ALERT package. Currently, the polling loop interval sleep time is the only session setting that can be modified using [Appendix A] What's on the Companion Disk? 3.2.2 The DBMS_ALERT Interface 186 this procedure. The header for this procedure is, PROCEDURE DBMS_ALERT.SET_DEFAULTS (sensitivity IN NUMBER); where sensitivity is the polling interval sleep time in seconds. The SET_DEFAULTS procedure does not raise any package exceptions. 3.2.2.4.1 Example The following example sets the polling interval to one second: SQL> execute DBMS_ALERT.SET_DEFAULTS(600); Setting the polling interval is relevant primarily to users of DBMS_ALERT under Oracle Parallel Server (OPS), since under OPS a polling loop is required to check for alerts issued from another Oracle instance. 3.2.2.5 The DBMS_ALERT.SIGNAL procedure The SIGNAL procedure posts notification of the occurrence of an alert, which is then propagated to all sessions registered for the alert. Alert notification happens only if and when the signaling transaction COMMITs. Here's the header: PROCEDURE DBMS_ALERT.SIGNAL (name IN VARCHAR2 ,message IN VARCHAR2); Parameters are summarized in the following table. Name Description name Name of the alert to signal message Message to associate and pass on with the alert When you are signaling alerts using SIGNAL, it is important to COMMIT (or ROLLBACK) the signaling transaction as soon as possible. Several problems can develop when signaling transactions are held open too long, including the following: • Other sessions signaling this alert will block and wait until the COMMIT. • Under the multithreaded server, a shared server will be bound to the session until the COMMIT. • The signaling session will receive an error if it waits on the alert prior to a COMMIT. If the signaling transaction is rolled back, no sessions will be notified of the alert. Thus the alerts in DBMS_ALERT are strictly transaction−based. Multiple sessions can signal the same alert. Note that this process is serialized using DBMS_LOCK (described in Chapter 4, User Lock and Transaction Management) and can add significant wait times unless transactions are closed quickly (as noted earlier). [Appendix A] What's on the Companion Disk? 3.2.2 The DBMS_ALERT Interface 187 3.2.2.5.1 Exceptions This program does not raise any package exceptions. It will raise an ORA−20000 exception for specific error conditions, with message text indicating the error as follows: ORU−10001 Lock request error, status: n ORU−10016 Error: n sending on pipe `pipename' ORU−10017 Error: n receiving on pipe `pipename' ORU−10022 Lock request error, status: n 3.2.2.5.2 Restrictions Note the following restrictions on calling SIGNAL: • Alert names are limited to 30 bytes and are case−insensitive. • Alert names beginning with "ORA$" are reserved for use by Oracle Corporation. • RESTRICT_REFERENCES cannot be called in SQL. 3.2.2.5.3 Example This trigger will signal the EMP_INSERT alert when rows are inserted into the EMP table. The empid column is passed as the alert message for receivers of the alert to use: CREATE OR REPLACE TRIGGER emp_ARI AFTER INSERT ON emp FOR EACH ROW BEGIN /* || signal alert that emp has been inserted, || passing the empid as alert message */ DBMS_ALERT.SIGNAL('EMP_INSERT', :NEW.empid); END IF; END emp_ARI; / 3.2.2.6 The DBMS_ALERT.WAITANY procedure The WAITANY procedure waits for notification of any alerts for which the session is registered. The procedure call will complete when the first alert is signaled or when the wait timeout is reached. Here's the header: PROCEDURE DBMS_ALERT.WAITANY (name OUT VARCHAR2 ,message OUT VARCHAR2 [Appendix A] What's on the Companion Disk? 3.2.2 The DBMS_ALERT Interface 188 ,status OUT INTEGER ,timeout IN NUMBER DEFAULT MAXWAIT); Parameters are summarized in the following table. Name Description name Name of the alert that occurred message Message attached to alert when signaled status Status of WAITANY call: 0 means alert; 1 means timeout timeout Time in seconds to wait for alerts When multiple alerts for which the session is registered have been signaled, the call to WAITANY will return the most recent alert that has occurred. If a session waits on an alert that it has also signaled, a lock request exception will occur unless a COMMIT has taken place between the calls to the SIGNAL and WAITANY procedures. The WAITANY call uses a polling loop to detect alerts. This avoids notification problems that could otherwise occur when signaled, but uncommitted alerts mask notification of subsequent committed alerts. The polling loop begins with a 1−second interval that increases exponentially to 30 seconds. 3.2.2.6.1 Exceptions The program does not raise any package exceptions. The program will raise an ORA−20000 exception for specific error conditions, with message text indicating the error as follows: ORU−10002 Lock request error, status: n ORU−10015 Error: n waiting for pipe status ORU−10020 Error: n waiting on lock request ORU−10024 No alerts registered 3.2.2.6.2 Restrictions Note the following restrictions on WAITANY: • The message parameter is limited to 1800 bytes in length. • WAITANY cannot be called in SQL. 3.2.2.6.3 Example This example waits five minutes to receive the next alert for which the session is registered. If an alert is received, it is displayed. If the EMP_INSERT alert is received, the employee id should be the message, and the employee status is changed without displaying the alert. [Appendix A] What's on the Companion Disk? 3.2.2 The DBMS_ALERT Interface 189 DECLARE alert_msg VARCHAR2(1800); alert_status INTEGER; alert_name; BEGIN DBMS_ALERT.WAITANY(alert_name, alert_msg, alert_status, 300); IF alert_status = 1 THEN DBMS_OUTPUT.PUT_LINE('timed out'); ELSIF alert_name = 'EMP_INSERT' THEN UPDATE emp SET status = 'REGISTERED' WHERE empid := alert_msg; ELSE DBMS_OUTPUT.PUT_LINE('received alert: '||alert_name); END IF; END; / 3.2.2.7 The DBMS_ALERT.WAITONE procedure The WAITONE procedure waits to be notified of an occurrence of the specified alert. The procedure call will complete when the alert is signaled or when the wait timeout is reached. Here's the header: PROCEDURE DBMS_ALERT.WAITONE (name IN VARCHAR2 ,message OUT VARCHAR2 ,status OUT INTEGER ,timeout IN NUMBER DEFAULT MAXWAIT); Parameters are summarized in the following table. Name Description name Name of the alert to wait for message Message attached to alert when signaled status Status of WAITONE call: 0 means alert; 1 means timeout timeout Time in seconds to wait for alerts Note the following special cases: • If the alert has been registered and signaled prior to the call to the WAITONE procedure, the call will return immediately with the most recent occurrence of the alert. • When multiple instances of the alert have been signaled, the call to WAITONE will return the most recent occurrence of the alert. • If a session waits for and has also signaled the alert, a lock request exception will occur unless a COMMIT has taken place between the calls to the SIGNAL and WAITONE procedures. [Appendix A] What's on the Companion Disk? 3.2.2 The DBMS_ALERT Interface 190 . primarily to users of DBMS_ALERT under Oracle Parallel Server (OPS), since under OPS a polling loop is required to check for alerts issued from another Oracle instance. 3.2.2.5 The DBMS_ALERT.SIGNAL. and are case−insensitive. • Alert names beginning with "ORA$" are reserved for use by Oracle Corporation. 3.2.2.1.3 Example In this example, the session will be registered to be notified. and are case−insensitive. • Alert names beginning with "ORA$" are reserved for use by Oracle Corporation. • RESTRICT_REFERENCES cannot be called in SQL. 3.2.2.5.3 Example This trigger