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); 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, p_message_count in out nocopy number, p_max_error_count in out nocopy number);
There are two implementations of Listen(). Both implementations monitor an agent for inbound event messages and dequeue 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 first implementation of the Listen() procedure exits after it has dequeued all event messages on the agent's queue, unless you specify a wait period to block on the queue waiting for additional messages.
The second implementation of the Listen() procedure exits after it has dequeued the specified maximum number of event messages. However, if errors occur during processing, the Listen() procedure exits after it encounters the specified maximum number of errors. If there are fewer than the maximum number of event messages on the queue, and fewer than the maximum number of errors occur, then the procedure exits after it has dequeued all the event messages on the queue, 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. See: Scheduling Listeners for Local Inbound Agents.
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. 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.
| 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 if 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 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 Streams Advanced Queuing User's Guide and Reference. |
| p_message_count | The maximum number of event messages the agent listener can process in one batch. Increasing the value of this parameter can help improve performance if you need to process large volumes of event messages. |
| p_max_error_count | The maximum number of errors the agent listener can encounter before it exits. |