Mapping the message body to and from IBM MQ format

Exchanging messages between JMS programs through service integration and IBM MQ

Usually, you 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, you 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 your service integration applications exchange MapMessage objects with IBM MQ applications, you 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 that contains 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 your application constructs messages for an IBM MQ application that requires a different format value, you 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). Your application constructs a BytesMessage object that contains 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 your application constructs messages for an IBM MQ application that requires a different character or numeric encoding, you 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 you 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 that 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, your 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, your 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.