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, we might have to learn about message conversion if the JMS applications do not behave as expected, or if the service integration configuration includes JMS programs or mediations that process messages to or from non-JMS WebSphere MQ programs.
If the service integration applications exchange MapMessage objects with WebSphere MQ applications, we 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 that the payload is character data (and can be translated to a different codepage by WebSphere 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 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 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 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 that 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 embedded within the binary data of the message.
Related concepts
Point-to-point messaging with a WebSphere MQ network
Related tasks
Specify whether messages are forwarded to WebSphere MQ as JMS messages
How to process WebSphere MQ message headers