Writing data-conversion exits
This collection of topics contains information about how to write data-conversion exits.
Note: Not supported in MQSeries for VSE/ESA.When you do an MQPUT, the 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, we 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).
For 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 part of the client packages as well as the server packages:| Operate system | Libraries |
|---|---|
| AIX | 32 bit & 64 bit: libmqm.a & libmqm_r.a |
| IBM i | LIBMQM & LIBMQM_R |
| Linux | 32 bit & 64 bit: libmqm.so & libmqm_r.so |
| Windows | 32 bit & 64 bit: mqm.dll & mqm.pdb |
- Invoking the data-conversion exit
A data-conversion exit is a user-written exit that receives control during the processing of an MQGET call. - Writing a data-conversion exit program for IBM i
Information about steps to consider when writing MQ data-conversion exit programs for IBM i. - Writing a data-conversion exit program for IBM MQ for z/OS
Information about steps to consider when writing data-conversion exit programs for IBM MQ for z/OS . - Writing a data-conversion exit for IBM MQ on UNIX and Linux systems
Information about steps to consider when writing data-conversion exit programs for IBM MQ on UNIX and Linux systems. - Writing a data-conversion exit for IBM MQ for Windows
Information about steps to consider when writing data-conversion exit programs for IBM MQ for Windows. - Exit and switch load files on Windows operating systems
The IBM WebSphere MQ for Windows Version 7.5 queue manager processes are 32-bit. As a result, when using 64-bit applications, some types of exit and XA switch load files also need to have a 32-bit version available for use by the queue manager. If the 32-bit version of the exit or XA switch load file is required and is not available, then the relevant API call or command fails.
Parent topic: User exits, API exits, and IBM MQ installable services