Oracle Built−in Packages- P59 pptx

start_time Initial start date−time for the window of time in which messages are propagated from thesource queue to the destination queue.. latency The maximum wait in seconds that a mess

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.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:

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

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

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.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

Q_NAME Name of the queue (remember that you can have more than

one queue in a queue table)

VARCHAR2(30)

CORRID Optional correlation identifier value provided by the user VARCHAR2(30)

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

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_TID ID number of the transaction that dequeued this message VARCHAR2(30)

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)

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?