Queue manager data conversion

Queue manager data conversion has always been available to non-JMS applications receiving messages from JMS clients. Since V7.0, JMS clients receiving messages also use queue manager data conversion. From 7.0.1.5, or 7.0.1.4 with APAR IC72897, queue manager data conversion is optional.

The queue manager can convert character and numeric data in message data using the values of CodedCharacterSetId, Encoding, and Format set for the message data. For non-JMS applications the conversion capability has always been available by setting the GetMessageOption, GMO_CONVERT. The queue manager conversion capability has not been available to a JMS application receiving a message until V7.0.

We can use queue manager conversion, before V7.0, with a JMS client application that sends a message. The JMS client builds a formatted record, sets the CodedCharacterSetId, Encoding, and Format attributes corresponding to the data placed in the message. A non-JMS receiving application reads the message using GMO_CONVERT, and causes a user-written data conversion exit to be called. The data conversion exit is a shared library that has the name set in the Format field.

Since V7.0, the queue manager is able to convert messages that are sent to JMS clients. From 7.0.0.0 to 7.0.1.4 inclusive, queue manager conversion is always called for JMS clients. From 7.0.1.5, or from 7.0.1.4 with APAR IC72897 applied, queue manager conversion is controlled by setting the destination property, WMQ_RECEIVE_CONVERSION, to WMQ_RECEIVE_CONVERSION_QMGR, or WMQ_RECEIVE_CONVERSION_CLIENT_MSG. WMQ_RECEIVE_CONVERSION_CLIENT_MSG is the default setting, matching the behavior of IBM MQ V6.0, which did not support queue manager data conversion for JMS clients. The application can change the destination setting:

Figure 1. Enable queue manager data conversion

((MQDestination)destination).setIntProperty(
              WMQConstants.WMQ_RECEIVE_CONVERSION, 
              WMQConstants.WMQ_RECEIVE_CONVERSION_QMGR);

Or,

((MQDestination)destination).setReceiveConversion
              (WMQConstants.WMQ_RECEIVE_CONVERSION_QMGR);

Queue manager data conversion for a JMS client takes place when the client calls a consumer.receive method. Text data is transformed into UTF-8 (1208) by default. Subsequent read and get methods decode text in the received data from UTF-8, creating Java text primitives in their internal Unicode encoding. UTF-8 is not the only target character set from queue manager data conversion. We can choose a different CCSID by setting the WMQ_RECEIVE_CCSID destination property.

An application can also change the destination setting, for example setting it to 437, DOS-US:

Figure 2. Set target coded character set for queue manager conversion

((MQDestination)destination).setIntProperty
(WMQConstants.WMQ_RECEIVE_CCSID, 437);

Or,

((MQDestination)destination).setReceiveCCSID(437);

The reason for changing WMQ_RECEIVE_CCSID is specialized; the chosen CCSID makes no difference to the text objects created in the JVM. However, some JVMs, on some platforms, might not be able to handle conversion from the CCSID of text in the message into Unicode. The option gives you a choice of CCSID for any text delivered to the client in the message. Some JMS client platforms have had problems with message text being delivered in UTF-8.

The JMS code is equivalent to the bold text in the C code in Figure 3,

Figure 3. Code snippet from amqsget0.c

gmo.Options = MQGMO_WAIT         /* wait for new messages            */
            | MQGMO_NO_SYNCPOINT /* no transaction                   */
            | MQGMO_CONVERT;     /* convert if necessary             */
   
     while (CompCode != MQCC_FAILED) {
     buflen = sizeof(buffer) - 1; /* buffer size available for GET   */
     memcpy(md.MsgId, MQMI_NONE, sizeof(md.MsgId));
     memcpy(md.CorrelId, MQCI_NONE, sizeof(md.CorrelId));
     md.Encoding       = MQENC_NATIVE;
     md.CodedCharSetId = MQCCSI_Q_MGR;
     
           MQGET(Hcon,          /* connection handle                 */
           Hobj,                /* object handle                     */
           &md,                 /* message descriptor                */
           &gmo,                /* get message options               */
           buflen,              /* buffer length                     */ 
           buffer,              /* message buffer                    */
           &messlen,            /* message length                    */  
           &CompCode,           /* completion code                   */
           &Reason);            /* reason code                       */

Note:

Queue manager conversion is only performed on the message data that has a known IBM MQ format. MQSTR, or MQCIH are examples of known formats that are predefined. A known format can also be user-defined format, as long as we have supplied a data-conversion exit.

Messages constructed as JMSTextMessage, JMSMapMessage and JMSStreamMessage, have a MQSTR format, and can be converted by the queue manager.