WAS v8.5 > Reference > Developer best practices

Map the message body to and from WebSphere MQ format

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


Exchanging messages between JMS programs through service integration and WebSphere MQ

Usually, we do not have to be aware of conversion between message formats to exchange JMS messages between service integration and WebSphere 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 WebSphere MQ programs.

If wer service integration applications exchange MapMessage objects with WebSphere MQ applications, you might have to specify a non-default map message encoding format.


WebSphere MQ message payload: format indications

The WebSphere 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 WebSphere MQ format, it automatically sets the appropriate value for the JMS message class.

  • When service integration converts a message from WebSphere 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 WebSphere MQ Use Java documentation.

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 the payload is character data (and can be translated to a different codepage by WebSphere MQ), or MQFMT_NONE, which indicates the payload is not character data. These values are suitable for most JMS messages, and when service integration converts a message to WebSphere 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 a WebSphere 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 WebSphere MQ application requires an additional header (for example, the MQCIH header for a CICS bridge application). Your 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 WebSphere 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 WebSphere MQ Application Programming Reference.


WebSphere 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 WebSphere 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 a WebSphere 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 WebSphere MQ library.

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

When the JMS message has a body not character data (BytesMessage or ObjectMessage), setting JMS_IBM_Character_Set does not cause service integration to convert the bytes; it indicates to WebSphere 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 WebSphere MQ recognises, it can convert that character data to the coded character set the receiving application requires.


When service integration converts a message from WebSphere 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.


Related concepts:

Point-to-point messaging with a WebSphere MQ network


Related


Specify whether messages are forwarded to WebSphere MQ as JMS messages


Reference:

How to process WebSphere MQ message headers


+

Search Tips   |   Advanced Search