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.
- Name your message format. The name must fit in the
Format
field of the MQMD. TheFormat
name must not have leading blanks. Trailing blanks are ignored. The object's name must have no more than eight non-blank characters, because theFormat
is only eight characters long.A .DEF file called amqsvfcn.def is also supplied in the samples directory,
MQ_INSTALLATION_PATH
\Tools\C\SamplesMQ_INSTALLATION_PATH
is the directory where IBM MQ is installed. 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 that you send a message.
- Create a structure to represent your message. See Valid syntax for an example.
- 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 are written assuming that all structures are packed; amend them if this is not the case.
- Copy the supplied skeleton source file, amqsvfc0.c, renaming it to the name of your message format that you set in step 1.
amqsvfc0.c is in
MQ_INSTALLATION_PATH
\Tools\C\SamplesMQ_INSTALLATION_PATH
The skeleton includes a sample header file amqsvmha.h in the
MQ_INSTALLATION_PATH
\Tools\C\includeThe 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.
- Find the following comment boxes in the source file and insert code as described:
- Toward the end of the source file, a comment box starts with:
Here, insert the code fragment generated in step 3./* Insert the functions produced by the data-conversion exit */
- Near the middle of the source file, a comment box starts with:
This is followed by a commented-out call to the function/* Insert calls to the code fragments to convert the format's */
ConverttagSTRUCT
.Change the name of the function to the name of the function that you added in step 5.a. Remove the comment characters to activate the function. If there are several functions, create calls for each of them.
- Near the beginning of the source file, a comment box starts with:
Here, insert the function prototype statements for the functions added in step 3./* Insert the function prototypes for the functions produced by */
- Toward the end of the source file, a comment box starts with:
- Create the following command file:
wherecl -I
MQ_INSTALLATION_PATH
\Tools\C\Include -Tp \ MYFORMAT.C MYFORMAT.DEFMQ_INSTALLATION_PATH
is the directory where IBM MQ is installed. - Issue the command file to compile your exit as a DLL file.
- Place the output in the exit subdirectory below the IBM MQ data directory. The default directory for installing your exits on 32 bit systems is MQ_DATA_PATH\Exits and for 64 bit systems is MQ_DATA_PATH\Exits64
The path used to look for the data-conversion exits is given in the registry. The registry folder is:
and the registry key is:HKEY_LOCAL_MACHINE\SOFTWARE\IBM\WebSphere MQ\Installation\MQ_INSTALLATION_NAME\Configuration\ClientExitPath\
ExitsDefaultPath
. This path can be set for each queue manager and the exit is only looked for in that path or paths.
- If CRTMQCVX uses packed structures, all IBM MQ applications must be compiled in this way.
- Data-conversion exit programs must be reentrant.
- MQXCNVC is the only MQI call that can be issued from a data-conversion exit.