Writing a data-conversion exit program for IBM i

Information about steps to consider when writing MQ data-conversion exit programs for IBM i.

Follow these steps:

1. Name your message format. The name must fit in the Format field of the MQMD. The Format name must not have leading embedded blanks, and 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 (our example uses the name Format).
2. Create a structure to represent your message. See Valid syntax for an example.
3. Run this structure through the CVTMQMDTA command to create a code fragment for the data-conversion exit.

   The functions generated by the CVTMQMDTA command use macros that are shipped in the file QMQM/H(AMQSVMHA). These macros are written assuming that all structures are packed; amended them if this is not the case.

4. Take a copy of the supplied skeleton source file, QMQMSAMP/QCSRC(AMQSVFC4) and rename it. (Our example uses the name EXIT_MOD.)
5. 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 5.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 5.a.

   If the message contains character data, the generated code calls MQXCNVC; this can be resolved by binding the service program QMQM/LIBMQM.

6. Compile the source module, EXIT_MOD, as follows:

     CRTCMOD MODULE(library/EXIT_MOD) +
     SRCFILE(QCSRC) +
     TERASPACE(*YES *TSIFC)
   

7. Create/link the program. For nonthreaded applications, use the following:

     CRTPGM PGM(library/Format)  +
        MODULE(library/EXIT_MOD)  +
        BNDSRVPGM(QMQM/LIBMQM)  +
        ACTGRP(QMQM)  +
        USRPRF(*USER)
   

   In addition to creating the data-conversion exit for the basic environment, another is required in the threaded environment. This loadable object must be followed by _R. Use the LIBMQM_R library to resolve calls to the MQXCNVC. Both loadable objects are required for a threaded environment.

     CRTPGM PGM(library/Format_R)  +
        MODULE(library/EXIT_MOD)  +
        BNDSRVPGM(QMQM/LIBMQM_R)  +
        ACTGRP(QMQM)  +
        USRPRF(*USER)
   

8. Place the output in the library list for the IBM MQ job. It is recommended that, for production, data-conversion exit programs be stored in QSYS.

Note:

1. If CVTMQMDTA uses packed structures, all IBM MQ applications must use the _Packed qualifier.
2. Data-conversion exit programs must be reentrant.
3. MQXCNVC is the only MQI call that can be issued from a data-conversion exit.
4. Compile the exit program with the user profile compiler option set to *USER, so that the exit runs with the authority of the user.
5. Teraspace memory enablement is required for all user exits with IBM MQ for IBM i ; specify TERASPACE(*YES *TSIFC) in the CRTCMOD and CRTBNDC commands.

Parent topic: Writing data-conversion exits