+

Search Tips   |   Advanced Search

Mapping the message body to and from IBM MQ format

The IBM MQ message header (MQRFH2) and descriptor (MQMD) can contain information about the format of the IBM MQ message body. Service integration uses information contained in the MQRFH2 and MQMD when converting a message from IBM MQ format, and puts information into the QRFH2 and MQMD when converting a message to IBM MQ format.


Exchanging messages between JMS programs through service integration and IBM MQ

Usually, we do not have to be aware of conversion between message formats to exchange JMS messages between service integration and IBM MQ, because service integration performs the appropriate conversion automatically, including character and numeric encoding. However, we might have to learn about message conversion if your JMS applications do not behave as expected, or if your service integration configuration includes JMS programs or mediations that process messages to or from non-JMS IBM MQ programs.

If our service integration applications exchange MapMessage objects with IBM MQ applications, we might have to specify a non-default map message encoding format.


IBM MQ message payload: format indications

The IBM MQ format message contains the following two indications of the payload format:

MQRFH2 <mcd> folder, Msd field

This field can contain information about the payload format. This is the "JMS format" information.

  • When service integration converts a message to IBM MQ format, it automatically sets the appropriate value for the JMS message class.

  • When service integration converts a message from IBM MQ format, it uses the value in this field (if there is an MQRFH2 containing the field) to set the JMS message class.

JMS message class MQRFH2 <mcd> folder, Msd field ("JMS format")
TextMessage jms_text
BytesMessage jms_bytes
StreamMessage jms_stream
MapMessage jms_map
ObjectMessage jms_object
Message jms_none

If the "JMS format" information is not available, for example if there is no MQRFH2, service integration sets the JMS message class based on the "MQ format".

For more information about the MQRFH2 <mcd> folder, see the IBM MQ documentation on using Java.

MQRFH2 (or MQMD) format field

The MQRFH2 (or the MQMD if there is no MQRFH2) format field contains information about the payload format. This is the "MQ format" information. Typically it contains MQFMT_STRING, which indicates that the payload is character data (and can be translated to a different codepage by IBM MQ), or MQFMT_NONE, which indicates that the payload is not character data. These values are suitable for most JMS messages, and when service integration converts a message to IBM MQ format it automatically sets this field to one of the following values:

JMS message class MQRFH2 (or MQMD) format field ("MQ format")
TextMessage MQFMT_STRING
BytesMessage MQFMT_NONE
StreamMessage MQFMT_STRING
MapMessage MQFMT_STRING
ObjectMessage MQFMT_NONE
Message MQFMT_NONE

If the application constructs messages for an IBM MQ application that requires a different format value, we can override the value from the previous table by setting the JMS_IBM_Format property to the required value. A particular example is when the IBM MQ application requires an additional header (for example, the MQCIH header for a CICS bridge application). The application constructs a BytesMessage object containing the header followed by any other message data, then replaces the default "MQ format" (MQFMT_NONE) by setting the JMS_IBM_Format property to the appropriate value for the header (for example, MQFMT_CICS for an MQCIH header).

When service integration converts a message from IBM MQ format, it sets the JMS_IBM_Format property to the value in the "MQ format" field. If the "JMS format" is not available, for example if there is no MQRFH2, service integration sets the JMS message class to TextMessage if the "MQ format" is MQFMT_STRING and to BytesMessage otherwise.

For more information about the MQRFH2 (or MQMD) format field, see the IBM MQ Application Programming Reference.


IBM MQ message payload: character and numeric encoding

In addition to the format field, the MQRFH2 (or the MQMD if there is no MQRFH2) contains fields that identify the character encoding and numeric encoding for the message payload.

When service integration converts a message to IBM MQ format, it automatically selects default values (UTF-8 character encoding and big-endian numeric encoding) that are suitable for most JMS messages. If the application constructs messages for an IBM MQ application that requires a different character or numeric encoding, we can override the character encoding value by setting the JMS_IBM_Character_Set property to the required coded character set ID (CCSID), or the JMS_IBM_Encoding property to the required numeric format, or both. For information about the values we can use for JMS_IBM_Character_Set and JMS_IBM_Encoding, see the documentation in the IBM MQ library.

When the JMS message has a body that is encoded as character data in IBM MQ (TextMessage, StreamMessage, or MapMessage), setting JMS_IBM_Character_Set causes service integration to convert the text to that coded character set in the IBM MQ message body.

When the JMS message has a body that is not character data (BytesMessage or ObjectMessage), setting JMS_IBM_Character_Set does not cause service integration to convert the bytes; it indicates to IBM MQ any character data in the message body is already encoded using the specified coded character set. If the value of the JMS_IBM_Format is a format that IBM MQ recognises, it can convert that character data to the coded character set that the receiving application requires.

When service integration converts a message from IBM MQ format, it sets the JMS_IBM_Character_Set and JMS_IBM_Encoding properties from the fields in the MQRFH2 (or the MQMD if there is no MQRFH2). If the JMS message is a TextMessage, StreamMessage, MapMessage, or ObjectMessage, the application makes no use of the values of the JMS_IBM_Character_Set and JMS_IBM_Encoding properties. If the JMS message is a BytesMessage, then the body of the JMS message is binary data. In this case, the application must be aware of the values of the JMS_IBM_Character_Set and JMS_IBM_Encoding properties, because they indicate the encoding of any character data or numeric data that is embedded within the binary data of the message.