Writing data-conversion exits

This collection of topics contains information about how to write data-conversion exits.

When you do an MQPUT, your application creates the message descriptor (MQMD) of the message. Because IBM® MQ needs to be able to understand the contents of the MQMD regardless of the platform it is created on, it is converted automatically by the system.

Application data, however, is not converted automatically. If character data is being exchanged between platforms where the CodedCharSetId and Encoding fields differ, for example, between ASCII and EBCDIC, the application must arrange for conversion of the message. Application data conversion can be performed by the queue manager itself or by a user exit program, referred to as a data-conversion exit. The queue manager can perform data conversion itself, using one of its built-in conversion routines, if the application data is in one of the built-in formats (such as MQFMT_STRING). This topic contains information about the data-conversion exit facility that IBM MQ provides for when the application data is not in a built-in format.

Control can be passed to the data-conversion exit during an MQGET call. This avoids converting across different platforms before reaching the final destination. However, if the final destination is a platform that does not support data conversion on the MQGET, you must specify CONVERT(YES) on the sender channel that sends the data to its final destination. This ensures that IBM MQ converts the data during transmission. In this case, your data-conversion exit must reside on the system where the sender channel is defined.

The MQGET call is issued directly by the application. Set the CodedCharSetId and Encoding fields in the MQMD to the character set and encoding required. If your application uses the same character set and encoding as the queue manager, set CodedCharSetId to MQCCSI_Q_MGR, and Encoding to MQENC_NATIVE. After the MQGET call completes, these fields have the values appropriate to the message data returned. These might differ from the values required if the conversion was not successful. Your application should reset these fields to the values required before each MQGET call.

The conditions required for the data-conversion exit to be called are defined for the MQGET call in MQGET.

For a description of the parameters that are passed to the data-conversion exit, and detailed usage notes, see Data conversion for the MQ_DATA_CONV_EXIT call and the MQDXP structure.

Programs that convert application data between different machine encodings and CCSIDs must conform to the IBM MQ data conversion interface (DCI).

With the introduction of Multicast clients, API exits and data-conversion exits need to be able to run on the client-side because some messages might not go through the queue manager. The following libraries are now part of the client packages as well as the server packages:

Table 1. Libraries that are now in the client and server packages

Operating system	Libraries
Windows	32 bit & 64 bit: mqm.dll & mqm.pdb
Linux® & HP-UX	32 bit & 64 bit: libmqm.so & libmqm_r.so
AIX®	32 bit & 64 bit: libmqm.a & libmqm_r.a
Solaris	32 bit & 64 bit: libmqm.so
IBM i	LIBMQM & LIBMQM_R