4
Converting Messages

Messaging Gateway converts the native message format of the source messaging system to the native message format of the destination messaging system during propagation. Messaging Gateway uses canonical types and an AQ-centric model for the conversion.

The following topics are discussed in this chapter:

• The Message Conversion Process

• Messaging Gateway Canonical Types

• Message Conversion for Advanced Queuing

• Message Conversion for MQSeries

• Message Header Conversions

• Messaging Gateway Examples: Using Header Properties

The Message Conversion Process

When a message is propagated by the gateway, the message is converted from the native format of the source queue to the native format of the destination queue.

A native message contains a message header and a message body. The header contains the fixed header fields that all messages in a messaging system have, such as message properties in Advanced Queuing and the fixed header in MQSeries. The body contains message contents, such as the AQ payload and the MQSeries message body. Messaging Gateway converts both message header and message body components.

Message conversion is done in two stages, as shown in Figure 4-1. A message is converted from the native format of the source queue to the gateway internal message format first, and then from the internal message format to the native format of the destination queue.

Figure 4-1 Message Conversion

Text description of the illustration adqmg003.gif

The gateway agent uses an internal message format consisting of a header that is the same as the AQ message properties and a body that is an object of the gateway canonical types.

Messaging Gateway Canonical Types

Messaging Gateway defines canonical types to support message conversion between Advanced Queuing and non-Oracle messaging systems. A canonical type is a message type representation in the form of a PL/SQL abstract data type (ADT) in the Oracle9i database. In release 9.0.1, the canonical type MGW_BASIC_MSG_T supports conversion between Advanced Queuing and MQSeries.

MGW_BASIC_MSG_T is used to represent messages that have a message header and a TEXT or RAW (bytes) message body. The message header is represented as a set of {name,value} pairs, which are objects of the MGW_NAME_VALUE_T type.

See Also: Chapter 6, "DBMS_MGWMSG" for Syntax and attribute information for MGW_BASIC_MSG_T Syntax and attribute information for MGW_NAME_VALUE_T A list of constants for the MGW_NAME_VALUE_T value types Helper routines for MGW_NAME_VALUE_ARRAY_T

Message Conversion for Advanced Queuing

Native AQ messages consist of AQ message properties and a message payload of either RAW or a user-defined ADT type.

The Messaging Gateway agent converts messages between the native AQ message format and the internal message format. Figure 4-2 illustrates the message conversion performed by the AQ driver.

Figure 4-2 AQ Message Conversion

Text description of the illustration adqmg004.gif

For outbound propagation, after dequeuing a message from an AQ queue, the gateway agent constructs an internal message by mapping the AQ message properties of the AQ message to the AQ message properties of the internal message and converting the AQ payload to an object of the canonical type.

For inbound propagation, after receiving an internal message from a non-Oracle driver, the gateway agent converts the canonical message to the AQ payload and then enqueues a message with that payload and the internal AQ message properties.

The agent can directly enqueue and dequeue messages with a payload of RAW or SYS.MGW_BASIC_MSG_T to and from AQ queues. The agent provides automatic mapping between the two payload types and the canonical type. For a payload type other than RAW or SYS.MGW_BASIC_MSG_T type, a user-supplied transformation must be provided for conversion between the AQ payload type and the canonical type.

In general, for outbound propagation, the AQ payload type or output of a user-supplied transformation must be either RAW or SYS.MGW_BASIC_MSG_T. For inbound propagation, the AQ payload or input type of a user-supplied transformation must be either RAW or SYS.MGW_BASIC_MSG_T.

Converting RAW AQ Payload Types

For outbound propagation, the following rules apply:

• An AQ payload of type RAW is always mapped to an MGW_BASIC_MSG_T canonical message with a RAW body. MGW_BASIC_MSG_T.header is set to NULL. This never results in a message conversion failure.

For inbound propagation, the following rules apply:

• An MGW_BASIC_MSG_T canonical message is mapped as follows:
  • For a RAW body of size <= 32k, the RAW body is mapped directly to the RAW payload. This never results in a message conversion failure.

  • For a RAW body of size > 32k, message conversion fails.

  • For a TEXT body, message conversion fails.

  • For a canonical message with both a TEXT and RAW body, message conversion fails.

Converting MGW_BASIC_MSG_T AQ Payload Types

For outbound propagation, the following rules apply:

• An AQ payload of type SYS.MGW_BASIC_MSG_T is always mapped to an MGW_BASIC_MSG_T canonical message.

• For a RAW body, if both small and large values are set, message conversion fails.

• For a TEXT body, if both small and large values are set, message conversion fails.

For inbound propagation, the following rules apply:

• An MGW_BASIC_MSG_T canonical message is mapped directly. This never results in a message conversion failure.

Using Transformations

Messaging Gateway can use AQ message transformation to convert between an AQ queue payload and a gateway canonical type. After a transformation is created using the DBMS_TRANSFORM package, a Messaging Gateway administrator can use DBMS_MGWADM.ADD_SUBSCRIBER and DBMS_MGWADM.ALTER_SUBSCRIBER to configure a gateway subscriber to use the transformation.

For outbound propagation, the transformation is invoked when the gateway agent dequeues messages from the AQ queue. For inbound propagation, the transformation is invoked when the gateway agent enqueues messages to the AQ queue.

The transformation is always in the context of the gateway agent, which means that the gateway agent user must have execute privileges on the transformation function and the AQ payload type. This can be accomplished by granting the EXECUTE privilege to PUBLIC, or by granting the EXECUTE privilege directly to the gateway agent user.

See Also: Oracle9i Application Developer's Guide - Advanced Queuing for information on the transformation feature

Message Conversion for MQSeries

The Messaging Gateway MQSeries driver converts between the internal message format and the MQSeries native message format. MQSeries native messages consist of a fixed message header and a message body. The message body is treated as either a TEXT value or RAW (bytes) value.

Figure 4-3 illustrates the message conversion performed by the MQSeries driver. For outbound propagation, the driver maps the AQ message properties and canonical message to a native message having a fixed header and message body. For inbound propagation, the driver maps a native message to a set of AQ message properties and a canonical message.

Figure 4-3 MQSeries Message Conversion

Text description of the illustration adqmg005.gif

For outbound propagation, an MGW_BASIC_MSG_T canonical message is mapped to an MQSeries native message as follows:

• The MQSeries fixed header fields are based on the internal AQ message properties and the MGW_BASIC_MSG_T.header attribute of the canonical message.

  Refer to Table 4-1 for the default mapping for certain MQSeries header fields based on the AQ message properties, if a value is not specified.

  The driver looks in MGW_BASIC_MSG_T.header for the {name,value} pairs described in Table 4-4 and, for each one found, uses that value for the MQSeries header field. Any {name,value} pairs with an unrecognized name or incorrect value type are ignored.

• If the canonical message has a TEXT body, the MQSeries format header field is set to MQFMT_STRING and the message body is set to the TEXT value.

• If the canonical message has a RAW body, the MQSeries format header field is set to "MGW_Byte" and the message body is set to the RAW value.

• If the canonical message has both a TEXT and RAW body, message conversion fails.

• If the canonical message has neither a TEXT nor RAW body, no message body is set and the MQSeries format header field is MQFMT_NONE.

For inbound propagation, the MQSeries native message is mapped to an MGW_BASIC_MSG_T canonical message as follows:

• Specific MQSeries header fields are mapped to AQ message properties as described in Table 4-1.

• The MGW_BASIC_MSG_T.header attribute of the canonical message is set to {name,value} pairs based on the MQSeries header fields, as described in Table 4-4.

• If the MQSeries format header field is MQFMT_STRING, the MQSeries message body is treated as TEXT and its value is mapped to MGW_BASIC_MSG_T.text_body. For any other format value, the message body is treated as RAW and its value is mapped to MGW_BASIC_MSG_T.raw_body.

Message Header Conversions

Messaging Gateway provides default mappings between AQ message properties and non-Oracle message header fields that have a counterpart in AQ message properties with the same semantics. Where Messaging Gateway does not provide a mapping, the message header fields are set to a default value, usually the default value defined by the messaging system.

Messaging Gateway defines {name, value} pairs for AQ message properties and the header fields of non-Oracle messaging systems to convert native message headers and allow users to override the default values. The {name, value} pairs are called header properties. Whether or not you can access the header properties for a given propagation job depends on the messaging systems involved and the AQ payload type or transformation.

Default Message Header Mapping

Table 4-1 describes the default mapping between AQ message properties and MQSeries header fields. (Refer to "Notes on Table 4-1" for an explanation of the numbers in parentheses.)

Table 4-1 Default Mapping Between AQ Message Properties and MQSeries Header Fields

AQ Message Property	MQSeries Header Field	Outbound Mapping (AQ Value to MQSeries Value)	Inbound Mapping (MQSeries Value to AQ Value)
priority	priority	AQ values 0,1,2,3,4,5,6, 7,8,9 are mapped respectively to MQSeries values 9,8,7,6,5,4,3,2, 1,0 AQ values < 0 are mapped as MQSeries value 9 AQ values >=10 are mapped to MQSeries value 0	MQSeries values 0,1,2,3, 4,5,6,7,8,9 are mapped respectively to AQ values 9,8,7,6,5,4,3,2,1,0
expiration	expiry	Time unit is mapped to tenths of a second (1) AQ value NEVER is mapped to MQEI_UNLIMITED	Time unit is mapped to seconds (1) MQEI_UNLIMITED is mapped to NEVER

Notes on Table 4-1

1. For outbound propagation, the AQ expiration value is used to calculate the remaining time-to-live because the AQ expiration value represents the expiration time specified when the message is enqueued. For inbound propagation, a direct mapping is done because the MQSeries expiration value already represents the remaining time-to-live.

Advanced Queuing Header Properties

Table 4-2 defines the Messaging Gateway {name,value} pairs used to describe the AQ message properties. The header property names for the AQ properties are prefixed with "MGW_AQ_".

When a message is dequeued from an AQ queue, the AQ driver generates {name,value} pairs based on the dequeued message header. When a message is enqueued, the AQ driver sets the AQ message properties from {name,value} pairs for these properties.

Table 4-2 Messaging Gateway Names for AQ Message Properties

MGW Name MGW_NAME_VALUE_T.name	MGW Type MGW_NAME_VALUE_T.type	AQ Message Property	Used For
"MGW_AQ_priority"	INTEGER_VALUE	priority	Enqueue Dequeue
"MGW_AQ_expiration"	INTEGER_VALUE	expiration	Enqueue Dequeue
"MGW_AQ_delay"	INTEGER_VALUE	delay	Enqueue Dequeue
"MGW_AQ_correlation"	TEXT_VALUE (size 128)	correlation	Enqueue Dequeue
"MGW_AQ_exception_queue"	TEXT_VALUE (size 61)	exception_queue	Enqueue Dequeue
"MGW_AQ_enqueue_time"	DATE_VALUE	enqueue_time	Dequeue
"MGW_AQ_original_msgid"	RAW_VALUE (size 16)	original_msgid	Dequeue

When a message is enqueued to an AQ queue, the AQ driver sets the default values for the AQ message properties that have no default mappings (refer to Table 4-1). Corresponding header properties are set as shown in Table 4-3.

Table 4-3 AQ Message Property Default Values

AQ Message Property Name	Default Value
priority	1
expiration	NEVER
delay	NO_DELAY
correlation	NULL
exception_queue	NULL

See Also: Oracle9i Application Developer's Guide - Advanced Queuing for more information on AQ header properties

MQSeries Header Properties

This section describes the message properties supported for the MQSeries messaging system. Table 4-4 defines the Messaging Gateway {name,value} pairs used to describe the MQSeries header properties. (Refer to "Notes on Table 4-4" for an explanation of the numbers in parentheses.) The Messaging Gateway names for the MQSeries properties are prefixed with "MGW_MQ_".

When a message is dequeued from the MQSeries messaging system, the MQSeries driver generates {name,value} pairs based on the dequeued message header and stores them in the header part of the canonical message of the MGW_BASIC_MSG_T type. When a message is enqueued to MQSeries, the MQSeries driver sets the message header and enqueue options from {name,value} pairs for these properties stored in the header part of the MGW_BASIC_MSG_T canonical message.

Table 4-4 Messaging Gateway Names for MQSeries Header Values

Messaging Gateway Name mgw_name_value_t.NAME	Messaging Gateway Type MGW_NAME_VALUE_T.type	MQSeries Property Name	Used For
"MGW_MQ_priority"	INTEGER_VALUE	priority	Enqueue, Dequeue
"MGW_MQ_expiry"	INTEGER_VALUE	expiry	Enqueue, Dequeue
"MGW_MQ_correlationId"	RAW_VALUE (size 24)	correlationId	Enqueue (1), Dequeue
"MGW_MQ_persistence"	INTEGER_VALUE	persistence	Dequeue
"MGW_MQ_report"	INTEGER_VALUE	report	Enqueue (1), Dequeue
"MGW_MQ_messageType"	INTEGER_VALUE	messageType	Enqueue, Dequeue
"MGW_MQ_feedback"	INTEGER_VALUE	feedback	Enqueue, Dequeue
"MGW_MQ_encoding"	INTEGER_VALUE	encoding	Enqueue, Dequeue
"MGW_MQ_characterSet"	INTEGER_VALUE	characterSet	Enqueue, Dequeue
"MGW_MQ_format"	TEXT_VALUE (size 8)	format	Enqueue (1), Dequeue
"MGW_MQ_backoutCount"	INTEGER_VALUE	backoutCount	Dequeue
"MGW_MQ_replyToQueueName"	TEXT_VALUE (size 48)	replyToQueueName	Enqueue, Dequeue
"MGW_MQ_replyToQueueManagerName"	TEXT_VALUE (size 48)	replyToQueueManagerName	Enqueue, Dequeue
"MGW_MQ_userId"	TEXT_VALUE (size 12)	userId	Enqueue, Dequeue
"MGW_MQ_accountingToken"	RAW_VALUE (size 32)	accountingToken	Enqueue (1), Dequeue
"MGW_MQ_applicationIdData"	TEXT_VALUE (size 32)	applicationIdData	Enqueue (1), Dequeue
"MGW_MQ_putApplicationType"	INTEGER_VALUE	putApplicationType	Enqueue (1), Dequeue
"MGW_MQ_putApplicationName"	TEXT_VALUE (size 28)	putApplicationName	Enqueue (1), Dequeue
"MGW_MQ_putDateTime"	DATE_VALUE	putDateTime	Dequeue
"MGW_MQ_applicationOriginData"	TEXT_VALUE (size 4)	applicationOriginData	Enqueue (1), Dequeue
"MGW_MQ_groupId"	RAW_VALUE (size 24)	groupId	Enqueue (1), Dequeue
"MGW_MQ_messageSequenceNumber"	INTEGER_VALUE	messageSequenceNumber	Enqueue, Dequeue
"MGW_MQ_offset"	INTEGER_VALUE	offset	Enqueue, Dequeue
"MGW_MQ_messageFlags"	INTEGER_VALUE	messageFlags	Enqueue, Dequeue
"MGW_MQ_originalLength"	INTEGER_VALUE	originalLength	Enqueue, Dequeue
"MGW_MQ_putMessageOptions"	INTEGER_VALUE	putMessageOptions (2)	Enqueue (1)

Notes on Table 4-4

1. This use is subject to MQSeries restrictions. For example, if MGW_MQ_accountingToken is set for an outgoing message, MQSeries overrides its value unless MGW_MQ_putMessageOptions is set to the MQSeries constant MQPMD_SET_ALL_CONTEXT.

2. MGW_MQ_putMessageOptions is used as the putMessageOptions argument to the MQSeries Base Java Queue.put() method. It is not part of the MQSeries header information and therefore is not an actual message property.

   The value for the openOptions argument of the MQSeries Base Java MQQueueManager.accessQueue method is specified when the MQSeries queue is registered using the DBMS_MGWADM.REGISTER_FOREIGN_QUEUE call. Dependencies may exist between the two. For instance, for MGW_MQ_putMessageOptions to include MQPMD_SET_ALL_CONTEXT, the MQ_openMessageOptions queue option must include MQOO_SET_CONTEXT.

The gateway agent adds the value MQPMO_SYNCPOINT to any value that you can specify.

Table 4-5 describes the default values set by the gateway agent for the MQSeries message header when a message is enqueued in an MQSeries queue. For all other header fields, the gateway agent does not set a default value.

Table 4-5 MQSeries Header Default Values

MQSeries Property Name	Default Value
messageType	MQMT_DATAGRAM
putMessageOption	MQPMO_SYNCPOINT will always be added; refer to (2) in "Notes on Table 4-4".

Messaging Gateway Examples: Using Header Properties

The following propagation scenarios exemplify the use of header properties.

Using MGW_BASIC_MSG_T for Outbound Propagation: Example

Consider an outbound propagation job from an AQ queue to an MQSeries queue. Because the MQSeries driver supports only the MGW_BASIC_MSG_T type, the propagation job must be configured so that the AQ driver converts the AQ payload to an MGW_BASIC_MSG_T canonical message. To accomplish this, either the source queue payload type must be SYS.MGW_BASIC_MSG_T, or a transformation whose output (to) type is SYS.MGW_BASIC_MSG_T must be supplied.

For outbound propagation, use the MGW_BASIC_MSG_T.header attribute to specify native message header properties that are used when the message is enqueued to the destination queue. In this example, it will contain {name,value} pairs for MQSeries header properties, as described in Table 4-4.

Although the AQ driver generates {name,value} pairs for the AQ message properties (refer to Table 4-2), the information is lost because the MQSeries message format does not allow you to specify user-defined message property information.

Using MGW_BASIC_MSG_T for Inbound Propagation: Example

For an inbound propagation job from an MQSeries queue to an AQ queue, the MQSeries driver always converts its native message to an MGW_BASIC_MSG_T canonical message. Therefore, the propagation job should be configured so that the AQ driver converts the canonical message to a SYS.MGW_BASIC_MSG_T payload type. To accomplish this, either the destination queue payload type must be SYS.MGW_BASIC_MSG_T, or a transformation whose input (from) type is SYS.MGW_BASIC_MSG_T must be supplied.

When used for inbound propagation, the MGW_BASIC_MSG_T.header attribute contains {name,value} pairs for the native message header properties of the message dequeued from the source queue. In this example, it will contain {name,value} pairs for MQSeries header properties, as described in Table 4-4.

Because the MQSeries native message format does not allow you to specify user-defined message property information, you cannot specify values that the gateway MQSeries driver interprets as values to use for AQ message properties. As a result, the AQ message properties of the message enqueued to the destination queue are based on the default mappings described in Table 4-1 and the default values for the remaining (nonmapped) AQ properties.