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.

Follow these steps:
  1. Name your message format. The name must fit in the Format field of the MQMD, and be in uppercase, for example, MYFORMAT. The Format name must not have leading blanks. Trailing blanks are ignored. The object's name must have no more than eight non-blank characters, because the Format is only eight characters long. Remember to use this name each time that you send a message.

    If the data conversion exit is used in a threaded environment, the loadable object must be followed by _r to indicate that it is a threaded version.

  2. Create a structure to represent your message. See Valid syntax for an example.
  3. Run this structure through the crtmqcvx command to create a code fragment for your data-conversion exit.

    The functions generated by the crtmqcvx command use macros that assume that all structures are packed; amend them if this is not the case.

  4. Copy the supplied skeleton source file, renaming it to the name of your message format that you set in step 1. The skeleton source file, and the copy, are read-only.

    The skeleton source file is called amqsvfc0.c.

  5. On IBM MQ for AIX®, a skeleton export file called amqsvfc.exp is also supplied. Copy this file, renaming it to MYFORMAT.EXP.
  6. The skeleton includes a sample header file, amqsvmha.h, in the directory MQ_INSTALLATION_PATH/inc, where MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed.. Make sure that your include path points to this directory to pick up this file.

    The amqsvmha.h file contains macros that are used by the code generated by the crtmqcvx command. If the structure to be converted contains character data, these macros call MQXCNVC.

  7. Find the following comment boxes in the source file and insert code as described:
    1. Toward the end of the source file, a comment box starts with: 
      
/* Insert the functions produced by the data-conversion exit */
      Here, insert the code fragment generated in step 3.
    2. Near the middle of the source file, a comment box starts with: 
      
/* Insert calls to the code fragments to convert the format's */
      This is followed by a commented-out call to the function ConverttagSTRUCT.

      Change the name of the function to the name of the function that you added in step 7.a. Remove the comment characters to activate the function. If there are several functions, create calls for each of them.

    3. Near the beginning of the source file, a comment box starts with: 
      
/* Insert the function prototypes for the functions produced by */
      Here, insert the function prototype statements for the functions added in step 3.
  8. Compile your exit as a shared library, using MQStart as the entry point. To do this, see Compiling data-conversion exits on UNIX and Linux systems.
  9. Place the output in the exit directory. The default exit directory is /var/mqm/exits for 32 bit systems and /var/mqm/exits64, for 64 bit systems. You can change these directories in the qm.ini or mqclient.ini file. This path can be set for each queue manager and the exit is only looked for in that path or paths.
Note:
  1. If crtmqcvx uses packed structures, all IBM MQ applications must be compiled in this way.
  2. Data-conversion exit programs must be reentrant.
  3. MQXCNVC is the only MQI call that can be issued from a data-conversion exit.