start_time Initial start date−time for the window of time in which messages are propagated from the source queue to the destination queue. duration Length of time in seconds that the propagation window will be open. If you supply a NULL value (the default), then the propagation window is open continually, or at least until the propagation is unscheduled through a call to DBMS_AQ.UNSCHEDULE_PROPAGATION. next_time An expression returning a date value that is used to compute the start of the next propagation window. If you supply a NULL value (the default), then propagation will stop when the current (initial) window closes. As an example, suppose you want to make sure the next propagation doesn't start until 24 hours after the last propagation window closed. You would then set next_time to SYSDATE + 1 − duration/86400. If you want to make sure the next propagation starts 24 hours after the last propagation window closed, provide a next_time value of `SYSDATE + 1'. latency The maximum wait in seconds that a message may sit in a queue after the start of a propagation window before it is propagated. The default amount of time is 60 seconds. This would mean, for example, that when the propagation window opens, the Queue Monitor propagates any messages present. It would then wait 60 seconds (or until the window closes due to the duration setting) before checking for the presence of and propagating any other messages. To summarize that relatively complex set of parameters and their interactions, when you schedule propagation you identify an initial start date/time and a span of time (number of seconds) in which messages are available to be propagated out of the queue to other queues. You can request that this window of time be opened on a regular basis (every day, once a week, every morning at 10 a.m., etc.). Finally, you can specify that the Queue Monitor check no less frequently than every N seconds (latency) during the time the propagation window is open to see if there are messages to propagate. 5.5.5.1.1 Example In this example, I schedule the propagation of a queue to the Boston brokerage office to occur every two hours. The propagation window is five minutes, and during that period of time, I want messages to be flushed out at least every 30 seconds. BEGIN DBMS_AQADM.SCHEDULE_PROPAGATION ('sell_orders', 'broker@boston', SYSDATE, 5 * 60, 'SYSDATE + 2/24', 30); END; / If I do not specify a destination, then propagation occurs to the same database in which the source queue is defined. The following call to DBMS_AQADM.SCHEDULE_PROPAGATION takes all default values (including a local destination database), except that it requests a latency of ten minutes by using named notation: BEGIN DBMS_AQADM.SCHEDULE_PROPAGATION ('share_the_blame', latency => 60 * 10); END; / [Appendix A] What's on the Companion Disk? 5.5.5 Managing Propagation of Messages 281 5.5.5.2 The DBMS_AQADM.UNSCHEDULE_PROPAGATION procedure You can stop or unschedule propagation of a queue with the UNSCHEDULE_PROPAGATION procedure: PROCEDURE DBMS_AQADM.UNSCHEDULE_PROPAGATION (src_queue_name IN VARCHAR2, destination IN VARCHAR2 DEFAULT NULL); Parameters are summarized in the following table: Name Description src_queue_name Name of the source queue whose messages are no longer to be propagated. This name should include the schema name if the queue is not located in the default schema, which is the schema name of the Oracle AQ administrator. destination Database link for the destination for which propagation will be terminated. If this argument is NULL, then the destination is the local database; messages will no longer be propagated to other queues in the local database as determined by the subscription or recipient lists. The maximum length for destination is currently 128 bytes. If the name is not fully qualified, then the default domain named will be used. 5.5.6 Verifying Queue Types 5.5.6.1 The DBMS_AQADM.VERIFY_QUEUE_TYPES procedure The VERIFY_QUEUE_TYPES procedure allows you to determine whether two different queues have the same payload type. Here's the header: PROCEDURE DBMS_AQADM.VERIFY_QUEUE_TYPES (src_queue_name IN VARCHAR2, dest_queue_name IN VARCHAR2 destination IN VARCHAR2 DEFAULT NULL, rc OUT BINARY_INTEGER); Parameters are summarized in the following table. Name Description src_queue_name Name of the source queue, usually one from which messages are to be propagated. This name should include the schema name if the queue is not located in the default schema, which is the schema name of the user. dest_queue_name Name of the destination queue, usually one to which messages are to be propagated. This name should include the schema name if the queue is not located in the default schema, which is the schema name of the user. destination Database link for the destination queue. If this argument is NULL, then the destination queue is located in the same database as the source queue. The maximum length for destination is currently 128 bytes. If the name is not fully qualified, then the default domain named will be used. rc Status code returned by the procedure. If there is no problem verifying the queue types and if the source and destination queue types match, then the result code is 0. If the queue types do not match (and there is no error), then the result code is 1. If an Oracle exception is raised, the SQLCODE is returned in rc. Whenever this program is run (either by Oracle AQ itself or by an AQ administrator), it updates the SYS.AQ$_MESSAGE_TYPES table. You can access this table (to verify the success of the type match after propagation has taken place) using the OID (Object ID) of the source queue and the address of the destination [Appendix A] What's on the Companion Disk? 5.5.5 Managing Propagation of Messages 282 queue. 5.5.7 Starting and Stopping the Queue Monitor If you want to use the delay and expiration features of AQ, you must have the Queue Monitor process running in the background. Before you can do this, you must add an AQ_TM_PROCESS parameter to your database initialization file (see Section 5.2, "Getting Started with Oracle AQ"" at the beginning of this chapter for more information). 5.5.7.1 The DBMS_AQADM.START_TIME_MANAGER procedure To start the Queue Monitor process, call the START_TIME_MANAGER procedure: PROCEDURE DBMS_AQADM.START_TIME_MANAGER; The operation takes effect when the call completes; there are no transactional dependencies. You can use the START_TIME_MANAGER to restart the Queue Monitor after you stopped it with a call to STOP_TIME_MANAGER. You can also use it to start the Queue Monitor process if the database initialization parameter was set to 0. In other words, you can override the default state of the database with this programmatic call. 5.5.7.2 The DBMS_AQADM.STOP_TIME_MANAGER procedure To stop the Queue Monitor process, call the STOP_TIME_MANAGER procedure: PROCEDURE DBMS_AQADM.STOP_TIME_MANAGER; The operation takes effect when the call completes; there are no transactional dependencies. The STOP_TIME_MANAGER procedure does not actually stop the physical process running in the background. This process is started when the database is initialized. The procedure simply disables the time management features of Oracle AQ in that database instance. 5.4 DBMS_AQ: Interfacing to Oracle AQ (Oracle8 only) 5.6 Oracle AQ Database Objects Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 5.5.7 Starting and Stopping the Queue Monitor 283 Chapter 5 Oracle Advanced Queuing 5.6 Oracle AQ Database Objects Oracle AQ relies on a variety of database objects to get its job done. Some objects are created for each queue table established. Other objects are created at the time that Oracle AQ is installed. 5.6.1 Objects Per Queue Table When a queue table is created, Oracle AQ defines a database table to hold all the messages for all queues in that queue table, as well as a view that allows a user to both query from and change (with caution and the guidance of Oracle Support) messages stored in queues of the queue table. 5.6.1.1 The database table for queue data The name of the database table has the following form, <queue_table> where queue_table is the name of the queue table created. Table 5.3 shows the columns of this view. Table 5.3: Columns in the Database Table for Queue Data Name Description Datatype Q_NAME Name of the queue (remember that you can have more than one queue in a queue table) VARCHAR2(30) MSGID Unique identifier of the message RAW(16) CORRID Optional correlation identifier value provided by the user VARCHAR2(30) PRIORITY Message priority NUMBER STATE Message state NUMBER DELAY The point in time to which the message is delayed for dequeuing DATE EXPIRATION Number of seconds in which the message will expire after its message state is set to READY NUMBER TIME_MANAGER_INFO For internal use only DATE LOCAL_ORDER_NO For internal use only NUMBER CHAIN_NO For internal use only NUMBER CSCN For internal use only NUMBER DSCN For internal use only NUMBER ENQ_TIME Date−time at which the message was enqueued DATE 284 ENQ_UID User ID of the session that enqueued the message NUMBER ENQ_TID ID number of the transaction that enqueued this message VARCHAR2(30) DEQ_TIME Date−time at which the message was dequeued DATE DEQ_UID User ID of the session that dequeued the message NUMBER DEQ_TID ID number of the transaction that dequeued this message VARCHAR2(30) RETRY_COUNT Number of retries at dequeuing the message NUMBER EXCEPTION_QSCHEMA Name of the schema containing the exception queue for this message VARCHAR2(30) EXCEPTION_QUEUE Name of the exception queue for this message VARCHAR2(30) STEP_NO For internal use only NUMBER RECIPIENT_KEY For internal use only NUMBER DEQUEUE_MSGID Message ID for the dequeue operation RAW(16) USER_DATA Payload of the queue (<user_data>); this might be a RAW value or the contents of the object that was placed in the queue RAW or <object_type> You will find it useful to execute queries directly against this base table when you need to examine dequeue status information for messages that reside in a multiple consumer queue. Here, for example, is the kind of query you might write to view the list of the agents that consumed a message with the following ID, 452F77CD652E11D1B999B14141A17646. SELECT consumer, transaction_id, deq_time, deq_user FROM THE (SELECT CAST (history AS SYS.AQ$_DEQUEUE_HISTORY_T) FROM msg_qtable WHERE msgid = 452F77CD652E11D1B999B14141A17646). where SYS.AQ$_DEQUEUE_HISTORY_T is a nested table of type SYS.AQ$_DEQUEUE_HISTORY. This dequeue history object type is defined in catqueue.sql as follows: CREATE TYPE sys.aq$_dequeue_history_t AS OBJECT ( consumer VARCHAR2(30), −− identifies dequeuer transaction_id VARCHAR2(22), −− M_LTID, transaction id of dequeuer deq_time DATE, −− time of dequeue deq_user NUMBER, −− user id of client performing dequeue remote_apps VARCHAR2(4000), −− string repn. of remote agents agent_naming NUMBER, −− how the message was sent to agent propagated_msgid RAW(16)); 5.6.1.2 The queue table view The name of the view for a queue table has the following form, AQ$<queue_table> where queue_table is the name of the queue table created. Table 5.4 shows the columns of this view. Notes about this view and its usage are included after the table. [Appendix A] What's on the Companion Disk? 5.6.1 Objects Per Queue Table 285 . simply disables the time management features of Oracle AQ in that database instance. 5.4 DBMS_AQ: Interfacing to Oracle AQ (Oracle8 only) 5.6 Oracle AQ Database Objects Copyright (c) 2000 O'Reilly. Companion Disk? 5.5.7 Starting and Stopping the Queue Monitor 283 Chapter 5 Oracle Advanced Queuing 5.6 Oracle AQ Database Objects Oracle AQ relies on a variety of database objects to get its job done is no error), then the result code is 1. If an Oracle exception is raised, the SQLCODE is returned in rc. Whenever this program is run (either by Oracle AQ itself or by an AQ administrator), it