Previous	Next		Contents	Index	Glossary

procedure Listen

    (p_agent_name in varchar2,

     p_wait in binary_integer default dbms_aq.no_wait,

     p_correlation in varchar2 default null,

     p_deq_condition in varchar2 default null);

Description

Monitors an agent for inbound event messages and dequeues messages using the agent's queue handler, in the database tier.

The standard WF_EVENT_QH queue handler sets the date and time when an event message is dequeued into the RECEIVE_DATE attribute of the event message. Custom queue handlers can also set the RECEIVE_DATE value if this functionality is included in the Dequeue API.

When an event is dequeued, the Event Manager searches for and executes any enabled subscriptions by the local system to that event with a source type of External, and also any enabled subscriptions by the local system to the Any event with a source type of External. If no enabled subscriptions exist for the event that was received (apart from subscriptions to the Any event), then Oracle Workflow executes any enabled subscriptions by the local system to the Unexpected event with a source type of External.

The Listen() procedure exits after all event messages on the agent's queue have been dequeued, unless you specify a wait period to block on the queue waiting for additional messages.

You must not call Listen() from within application code. If you want to call this procedure directly, you can run it from SQL*Plus. Otherwise, you can schedule PL/SQL agent listeners for your inbound agents from Oracle Applications Manager, Oracle Enterprise Manager, or other methods, depending on your version of Oracle Workflow. See: Scheduling Listeners for Local Inbound Agents, Oracle Workflow Administrator's Guide.

You can optionally restrict the event messages that the Listen() procedure will process by specifying an AQ correlation ID consisting of an event name, or a partial event name followed by a percent sign (%) as a wildcard character. Additionally, if your database version is Oracle9i Database or higher, you can also optionally restrict the event messages that the Listen() procedure will process by specifying a dequeue condition that references the properties or content of the message. However, you cannot specify both of these parameters at the same time. If you specify one, you must leave the other null.

Arguments (input)

p_agent_name	The name of the inbound agent.
p_wait	An optional wait period, in seconds, during which you want the agent listener to block on the agent's queue to wait for messages. By default an agent listener does not wait but exits after all messages on the queue have been dequeued.
p_correlation	Optionally specify an AQ correlation ID to identify the event messages that you want the agent listener to process. The AQ correlation ID for an event message in the Business Event System is usually specified as an event name, or as a partial event name followed by a percent sign (%) as a wildcard character. Consequently, by specifying an AQ correlation ID in this parameter, you can dedicate the agent listener to listen only for messages that are instances of the specified event or events. For example, you can specify oracle.apps.wf.notification% to listen for all events related to notifications whose names begin with that value. The default value for this correlation ID is null, which allows the agent listener to process messages that are instances of any event. If a dequeue condition is specified in the next parameter, this parameter must be null. See: Dequeue Methods, Oracle Application Developer's Guide - Advanced Queuing or Oracle Streams Advanced Queuing User's Guide and Reference.

Note: The AQ correlation ID is different than the correlation ID contained within the WF_EVENT_T event message structure.

p_deq_condition

Optionally specify a dequeue condition to identify the event messages that you want the agent listener to process. A dequeue condition is an expression that is similar in syntax to the WHERE clause of a SQL query. Dequeue conditions are expressed in terms of the attributes that represent message properties or message content. The messages in the queue are evaluated against the condition, so you can restrict the agent listener to listen only for messages that satisfy this condition. The default value is null, which does not place any restriction on the messages the agent listener can process. If an AQ correlation ID is specified in the previous parameter, this parameter must be null. See: Dequeue Methods, Oracle Application Developer's Guide - Advanced Queuing or Oracle Streams Advanced Queuing User's Guide and Reference.

See Also

Unexpected Event, Oracle Workflow Developer's Guide

Wfagtlst.sql, Oracle Workflow Administrator's Guide

Standard APIs for a Queue Handler, Oracle Workflow Developer's Guide