Oracle Built−in Packages- P40 pot

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_ALE

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

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)

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

,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

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