Writing a data-conversion exit for WebSphere MQ for Windows

 

Follow these steps:

  1. Name your message format. The name must fit in the Format field of the MQMD. The Format name should 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.

    A .DEF file called amqsvfcn.def is also supplied in the samples directory, <drive:\directory>\Program Files\IBM\WebSphere MQ\Tools\C\Samples. Take a copy of this file and rename it, for example, to MYFORMAT.DEF. Make sure that the name of the DLL being created and the name specified in MYFORMAT.DEF are the same. Overwrite the name FORMAT1 in MYFORMAT.DEF with the new format name.

    Remember to use this name each time you send a message.

  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 CVTMQCVX command use macros which are written assuming that all structures are packed; they should be amended if this is not the case.

  4. Take a copy of the supplied skeleton source file, amqsvfc0.c, renaming it to the name of your message format that you decided on in step 1 (that is, MYFORMAT).

    amqsvfc0.c is in <drive:\directory>\Tools\C\Samples where <drive:\directory> is the directory specified on installation. (The default installation directory is C:\Program Files\IBM\WebSphere MQ.)

    The skeleton includes a sample header file amqsvmha.h in the same directory. 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, then these macros call MQXCNVC.

  5. Find the following comment boxes in the source file and insert code as described:

    1. Towards the bottom 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 you added in step 5a above. Remove the comment characters to activate the function. If there are several functions, create calls for each of them.

    3. Near the top 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 5a above.

  6. Resolve this call by linking the routine with the library MQMVX.LIB, in the directory <drive:\directory>\Program Files\IBM\WebSphere MQ\Tools\Lib.

  7. Create the following command file: 
      cl -I <drive:\directory>\Program Files\IBM\WebSphere MQ\Tools\C\Include -Tp   \
  MYFORMAT.C -LD -DEFAULTLIB \
  <drive:\directory>\Program Files\IBM\WebSphere MQ\Tools\Lib\mqm.lib  \
  <drive:\directory>\Program Files\IBM\WebSphere MQ\Tools\Lib\mqmvx.lib   \
  MYFORMAT.DEF

    where <drive:\directory> is specified at installation,

    Issue the command file to compile your exit as a DLL file.

  8. Place the output in the Exits subdirectory below the WebSphere MQ data directory. Unless you have modified the ExitsDefaultPath, the default directory for installing your exits is: 
    C:\Program Files\IBM\WebSphere MQ\Exits

    The path used to look for the data-conversion exits is given in the registry. The registry folder is: 

    HKEY_LOCAL_MACHINE\SOFTWARE\IBM\MQSeries\CurrentVersion\Configuration\ClientExitPath\

    and the registry key is: ExitsDefaultPath. This path can be set for each queue manager and the exit is only looked for in that path or paths.

Notes:

  1. If CVTMQCVX uses packed structures, all WebSphere MQ applications must be compiled in this way.

  2. Data-conversion exit programs must be reentrant.

  3. MQXCNVC is the only MQI call that may be issued from a data-conversion exit.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.