How to process IBM MQ message headers

IBM MQ message headers

IBM MQ messages always include a message descriptor (MQMD). They can also include headers that contain additional information about the messages; for example, messages to or from JMS applications usually include an MQRFH2 header that contains message properties. IBM MQ defines the format and usage of some headers (for example, MQRFH2) and also allows users and third-party software providers to define their own custom headers.

Typically it is not necessary for application programs to process IBM MQ message headers. Most IBM MQ applications either do not use headers at all, or only use the MQRFH2 header, and the service integration and IBM MQ messaging providers automatically process the MQRFH2 header when you are communicating with these applications. However, if you are communicating with an IBM MQ application that uses or creates additional or different headers, then your WebSphere Application Server application can use the com.ibm.mq.headers classes to create the headers in messages it sends, and process them in messages it receives.

In the IBM MQ message, the headers (if there are headers) are at the start of the message, before the message payload. Each header contains fields that describe the following header, or the payload if there are no more headers; the MQMD contains the fields that describe the first header, or the payload if there are no headers. The MQMD and the MQRFH2 header do not normally appear in a JMS message. When the messaging provider converts a IBM MQ message into a JMS message, it uses information from the MQMD and MQRFH2 header to set JMS header fields and properties. Similarly, when the messaging provider converts a JMS message into an IBM MQ message, it uses the JMS header fields and properties to construct the MQMD and MQRFH2 header.

The JMS provider handles other headers in IBM MQ messages by converting the IBM MQ message to or from a JMS BytesMessage; the headers appear at the start of the message body, followed by the IBM MQ message payload (if any). The JMS_IBM_Format property of the JMS message indicates the format of the data in the message body (in this case, first header) and the JMS_IBM_Encoding and JMS_IBM_Character_Set properties indicate its encoding and CCSID.

Processing IBM MQ message headers in a JMS BytesMessage

The com.ibm.mq.headers package contains classes and interfaces that you can use to parse and manipulate IBM MQ headers in the body of a JMS BytesMessage. The MQHeader interface provides general-purpose methods for accessing header fields and for reading and writing message content. Each header type has its own class that implements the MQHeader interface and adds getter and setter methods for individual fields. For example, the MQCIH class represents the MQCIH (CICS® Bridge) header type. The header classes perform any necessary data conversion automatically, and can read or write data in any specified numeric encoding or character set (CCSID).

Every header class implements the MQHeader interface, which provides the methods int read (java.io.DataInput message, int encoding, int characterSet) and int write (java.io.DataOutput message, int encoding, int characterSet). The java.io.DataInputStream and java.io.DataOutputStream classes implement DataInput and DataOutput respectively. You can obtain DataInput and DataOutput objects from byte arrays carried in JMS messages, as in the following example, which processes a single MQCIH header:

import java.io.*;
import javax.jms.*;
import com.ibm.mq.headers.*;
...
BytesMessage bytesMessage = (BytesMessage) msg; // Message received from JMS consumer
byte[] bytes = new byte [(int) bytesMessage.getBodyLength ()];
bytesMessage.readBytes (bytes);
DataInput in = new DataInputStream (new ByteArrayInputStream (bytes));
MQCIH cih = new MQCIH (in, 
   bytesMessage.getIntProperty("JMS_IBM_Encoding"), 
   819); 

Alternatively, you can use the MQHeaderIterator class to process a sequence of headers, replacing the line starting MQCIH cih = new MQCIH with:

MQHeaderIterator it = new MQHeaderIterator (in, 
   bytesMessage.getStringProperty("JMS_IBM_Format"), 
   bytesMessage.getIntProperty("JMS_IBM_Encoding"), 
   819);
while (it.hasNext()) {
   MQHeader item = (MQHeader) it.next();
   ...
}

This example creates a single header (an MQCIH type header) and adds it into a BytesMessage:

import java.io.*;
import javax.jms.*;
import com.ibm.mq.constants.CMQC;
import com.ibm.mq.headers.*;
...
MQCIH header = new MQCIH();
ByteArrayOutputStream out = new ByteArrayOutputStream ();

header.write (new DataOutputStream (out), CMQC.MQENC_NATIVE, 819);
byte[] bytes = out.toByteArray ();
BytesMessage newMsg = origSes.createBytesMessage();
newMsg.writeBytes(bytes);

This example uses the MQHeaderList class to add two headers into a BytesMessage:

import java.io.*;
import javax.jms.*;
import com.ibm.mq.constants.CMQC;
import com.ibm.mq.headers.*;
...
byte[] outheaders = null;
byte[] outbody = ...
try {
    MQHeaderList it = new MQHeaderList ();
    MQHeader header1 = ... // Could be any header type
    MQHeader header2 = ... // Could be any header type
    ByteArrayOutputStream out = new ByteArrayOutputStream ();
    DataOutput dout = new DataOutputStream(out);
    it.add(header1);
    it.add(header2); 
    it.write(dout);
    outheaders = out.toByteArray();
} catch (Exception e) {
    System.out.println("error generating MQ message headers : " + e);
}
BytesMessage newMsg = origSes.createBytesMessage();
newMsg.writeBytes(outheaders);
newMsg.writeBytes(bytes);

newMsg.setStringProperty("JMS_IBM_Format", "MQCICS"); 
newMsg.setIntProperty("JMS_IBM_Encoding", CMQC.MQENC_NATIVE); 
newMsg.setIntProperty("JMS_IBM_Character_Set", 819);

Always use the correct values for the encoding and characterSet arguments. When you read headers, specify the encoding and CCSID with which the byte content was originally written. When writing headers, specify the encoding and CCSID that you want to produce. The data conversion is performed automatically by the header classes.

More information about the com.ibm.mq.headers classes

You can also define classes representing your own headers.