Operational Interface: Basic Operations, 8 of 19

Listening to One (Many) Queue(s)

Figure 11-7 Use Case Diagram: Listening to One(Many) Queue(s)

Text description of adq11qop17.gif follows

Text description of the illustration adq11qop17.gif

To refer to the table of all basic operations having to do with the Operational Interface see:

"Use Case Model: Operational Interface -- Basic Operations"

Purpose

To monitor one or more queues on behalf of a list of agents.

Usage Notes

The call takes a list of agents as an argument. You specify the queue to be monitored in the address field of each agent listed. You also must specify the name of the agent when monitoring multiconsumer queues. For single-consumer queues, an agent name must not be specified. Only local queues are supported as addresses. Protocol is reserved for future use.

This is a blocking call that returns when there is a message ready for consumption for an agent in the list. If there are messages for more than one agent, only the first agent listed is returned. If there are no messages found when the wait time expires, an error is raised.

A successful return from the listen call is only an indication that there is a message for one of the listed agents in one the specified queues. The interested agent must still dequeue the relevant message.

Note that you cannot call listen on nonpersistent queues.

Syntax

See Chapter 3, "AQ Programmatic Environments" for a list of available functions in each programmatic environment. Use the following syntax references for each programmatic environment:

PL/SQL (DBMS_AQ Package): Oracle9i Supplied PL/SQL Packages and Types Reference DBMS_AQ, LISTEN procedure
Visual Basic (OO4O) (Oracle Objects for OLE (OO4O) Online Help): From Help Topics, Contents tab, select OO4O Automation Server > OBJECTS > OraAQ Object > Monitoring Messages
Java (JDBC): Oracle9i Supplied Java Packages Reference, AQSession.listen

Examples

See Chapter 3, "AQ Programmatic Environments" for a list of available functions in each programmatic environment. Examples in the following programmatic environments are provided: