12
Configuring Heterogeneous Inbound Message Propagation

Overview of Inbound Message Propagation From MQSeries

Heterogeneous inbound propagation is accomplished in three steps:

1. by dequeuing the messages from the MQSeries source queue using the gateway

2. by translating the message service properties

3. by enqueuing the messages in the Oracle AQ destination queue.

After the propagation schedule has started for a source and/or destination tuple,  the propagation process will make the necessary gateway procedure calls to establish a connection with the MQSeries Queue Manager, to open the source queue as described for the schedule, to dequeue the message, and to close the queue again.

For every message that is dequeued, the MQSeries service properties that are associated with the message are translated to Oracle AQ properties when applicable. 

Translation of MQSeries/Oracle AQ Interfaces

IBM MQSeries provides a set of services that is comparable to Oracle AQ.  For inbound message propagation, Heterogeneous Message Propagation will provide dynamic, best-effort translations of MQSeries interfaces and message service properties into Oracle AQ properties.  This section lists the Oracle AQ interface and message service properties that Oracle AQ applications can retrieve upon dequeuing a message.  The next section also describes how those interface and message service properties are translated from MQI (the native API for MQSeries applications).

Messages that are propagated from non-Oracle message queuing systems are available to Oracle AQ applications.  These messages may be retrieved by dequeuing them from the Oracle AQ destination queues by using the dequeue() procedure (refer to the Oracle AQ documentation for more details on the dbms_aq package).  Inbound propagation for MQSeries will use the following translations:

• DBMS_AQ.DEQUEUE

• DBMS_AQ.DEQUEUE_OPTIONS_T

• DBMS_AQ.MESSAGE_PROPERTIES_T

Configuring Inbound Message Propagation

Configurations must be performed on the Oracle server, on the Oracle Procedural Gateway for IBM MQSeries, and on the IBM MQSeries to facilitate message propagation from an IBM MQSeries queue to an Oracle AQ queue. 

The following configuration is required in order to propagate a message from IBM MQSeries queue 'ny11' under queue manager 'mgr.ny.1' over to Oracle Advanced Queue 'aq12' under Oracle server 'ora1':

Operational Interface

Unlike outbound message propagation, as described in Chapter 11, no operational interface exists for Oracle applications to control inbound message propagation.  Control occurs at the administrative level only (refer to the next section), and the whole inbound message propagation process appears almost transparent to the receiving Oracle application.  Messages propagated into an Oracle AQ destination queue are dequeued in the same manner as any other message using the regular Oracle AQ interfaces as defined in the package DBMS_AQ.

Refer to the following code example with definitions of the Oracle AQ dequeue() procedure and the Oracle AQ types involved:

dbms_aq.dequeue(
      queue_name          IN    varchar2,
      dequeue_options     IN    enqueue_options_t,
      message_properties  OUT   message_properties_t,
      payload             OUT   raw,
      msgid               OUT   raw)

TYPE dequeue_options_t IS RECORD (
     consumer_name        varchar2(30),
     dequeue_mode         binary_integer,
     navigation           binary_integer,
     visibility           binary_integer,
     wait                 binary_integer,
     msgid                raw(16),
     correlation          varchar2(128)) 

TYPE message_properties_t IS RECORD (
     priority              binary_integer,
     delay                 binary_integer,
     expiration            binary_integer,
     correlation           varchar2(128),
     attempts              binary_integer,
     recipient_list        aq$_recipient_list,
     exception_queue       varchar2(51),
     enqueue_time          date,
     state                 binary_integer) 

Refer to the Oracle AQ documentation for detailed information on how to use the dequeue() procedure and its arguments.  For heterogeneous inbound message propagation, the usage is for the most part compatible with Oracle AQ propagation.  However, some arguments have different behavior due to the limited capabilities of non-Oracle message queuing systems.

The payload argument contains the application data.  The payload type should be compatible with the type of the queue specified in the queue_name argument, thus the payload type can be either an RAW or an ADT.  Heterogeneous inbound message propagation supports only RAW queues.  Therefore, only RAW payloads are supported. 

The msgid argument is a message identifier assigned to the message by the Oracle AQ system.  The msgid argument is globally unique within the Oracle domain.  Heterogeneous inbound message propagation cannot pass the original msgid along with the message to the Oracle AQ system.  For that reason, the msgid that is returned by the dequeue() procedure will not match the msgid that was assigned to messages by the non-Oracle message queuing system.  Similarly, the msgid that is specified in the dequeue_options argument should match the value that was assigned by the Oracle AQ system to the propagated message.  The msgid does not need to match the original value assigned by the non-Oracle message queuing system.

Although IBM MQSeries allows applications to set msgid, Oracle AQ and Microsoft MSMQ do not support this, because such propagation of msgid values cannot be supported.

Oracle AQ applications can use the correlation field for point-to-point message identification.  The values of correlation will be preserved when they are propagated from non-Oracle message queuing systems to Oracle AQ.

An example of an Oracle application that is using the dequeue() procedure for a propagated message from MQSeries would look like the following:

DECLARE

  dequeue_options DBMS_AQ.DEQUEUE_OPTIONS_T;
  message_properties DBMS_AQ.MESSAGE_PROPERTIES_T;
  message_handle RAW(16);
  message RAW(255);

BEGIN

  /* Specify correlation as assigned by the MQSeries appl.  */

  dequeue_options.correlation := 'AMQ qmgr.phx1029';

  /* dequeue the message from the AQ destination queue.  */

  DBMS_AQ.DEQUEUE(queue_name => 'aq2',
                  dequeue_options => queue_options,
                  message_properties => message_properties,
                  payload => message,
                  msgid => message_handle);

  COMMIT;

END;
/

Assuming that the Oracle AQ queue 'aq2' was used as the destination of an inbound message propagation schedule, the above example shows an Oracle AQ application attempting to dequeue a specific message from the destination queue by using correlation.  Because the messages in 'aq2' were sent by an MQSeries application, the specified correlation should match a value that was assigned to the messages by this application.  Considering this method of assigning correlation values, the Oracle application needs to take into account that the length of correlation values that are assigned by non-Oracle applications may differ from the length of correlation values that are assigned by an Oracle AQ.  Other dequeue options and message properties may have similar issues. 

Administrative Interface

For propagation in a homogeneous Oracle AQ environment, the administrator uses the Oracle AQ package, DBMS_AQADM, with procedures to schedule a propagation job.  Specifying an Oracle AQ propagation job requires specifying three items:

1. an Oracle AQ source queue name

2. the destination

3. the scheduling times

As noted previously, inbound message propagation does not exist in homogeneous Oracle AQ propagation.  Therefore, the inbound message propagation mechanism has defined its own API with procedures to schedule/unschedule propagation.  The heterogeneous inbound administrative interface resembles the interface of homogeneous Oracle AQ propagation.

The procedures maintain schedules in dictionary tables.  These procedures are read by the inbound message propagation process to determine when a queue, and which queue, is due for another round of message propagation.  The schedule information is available through a view named DBA_INBOUND_SCHEDULES (refer to Appendix D, " Heterogeneous Message Propagation DBA Views").  The package that contains the scheduling procedures (both outbound and inbound) is named DBMS_AQADM.  The following two procedures for inbound message propagation scheduling are defined in this package:

• SCHEDULE_INBOUND_PROPAGATION

• UNSCHEDULE_INBOUND_PROPAGATION

The two inbound scheduling procedures that are in the package are each composed of: name, purpose, syntax, usage, and error messages.  These two inbound scheduling procedures are described next.

dbms_hqadm.schedule_inbound_propagation(
      queue_name    in     varchar2,
      consumer      in     sys.aq$_agent,
      protocol      in     number,
      source        in     varchar2 default NULL,
      start_time    in     date default SYSDATE,
      duration      in     number default NULL,
      next_time     in     varchar2 default NULL,
      latency       in     number default 60 )

dbms_hqadm.unschedule_propagation(
      queue_name   in      varchar2,
      protocol     in      number,
      source       in      varchar2 default NULL,
      force        in      boolean default FALSE)

BEGIN

  /* schedule propagation for AQ */

  DBMS_AQADM.SCHEDULE_PROPAGATION(queue_name  => 'aq1',
                                  destination => 'remoteAq');

  /* schedule outbound propagation for MQSeries */

  DBMS_HQADM.SCHEDULE_PROPAGATION(
                         queue_name => 'mq1',
                         protocol => DBMS_HQADM.MQSERIES_OUTBOUND,
                         destination =>'mq1@mqseries');

  /* schedule inbound propagation from MQSeries */

  DBMS_HQADM.SCHEDULE_INBOUND_PROPAGATION(
                        queue_name => 'aq2',
                        consumer   => 'JOE',
                        protocol   => DBMS_HQADM.MQSERIES_INBOUND,
                        source     => 'mq2@mqseries');
                        
END;
/

Security

Heterogeneous Message Propagation does not impose new authorization requirements on either Oracle AQ or non-Oracle operational applications.  For inbound message propagation, a non-Oracle application enqueues the message to the designated source queue at the non-Oracle message queuing system, but does not require authorization for the recipient queue controlled by Oracle AQ.  Alternatively, the Oracle consumer application requires authorization only for the Oracle AQ destination queue.

At the administration level, the user who schedules inbound message propagation for a src_address and/or destination tuple:

• requires authorization to access the Oracle AQ destination queue

• requires access to a database link for a gateway in order to access the source queue at the non-Oracle message queuing system

The user name and password that were specified for the database link require access privileges at the message queuing system of the source queue.  If the database link does not specify a user name and password, then it will implicitly use the ID of the current Oracle user

Given these privileges, the propagation process can dequeue the messages from the source queue using the gateway and can enqueue them into the Oracle AQ destination queue.  This ensures that the security issue for inbound message propagation remains transparent to both sender and consumer applications.

Exception Handling

If the inbound message propagation process cannot propagate messages from the non-Oracle source queue to the Oracle AQ destination queue, the messages will be moved to a Òpropagation exceptionÓ queue.

Schedule Status

Status Information can be obtained for an inbound message propagation schedule and for individual messages.

SELECT ERROR_TIME, ERROR, ERROR_MSG 
FROM DBA_INBOUND_SCHEDULES
WHERE DISABLED = 'Y';