Writing a data-conversion exit program for WebSphere MQ for z/OS

Follow these steps:

  1. Take the supplied source skeleton CSQ4BAX9 (for non-CICS environments) or CSQ4CAX9 (for CICS) as your starting point.
  2. Run the CSQUCVX utility.
  3. Follow the instructions in the prolog of CSQ4BAX9 or CSQ4CAX9 to incorporate the routines generated by the CSQUCVX utility, in the order that the structures occur in the message you want to convert.
  4. The utility assumes that the data structures are not packed, that the implied alignment of the data is honored, and that the structures start on a full-word boundary, with bytes being skipped as required (as between ID and VERSION in the Example of valid syntax for the input data set). If the structures are packed, you will need to omit the CMQXCALA macros that are generated. You are therefore strongly recommended to declare your structures in such a way that all fields are named and no bytes are skipped; in the Example of valid syntax for the input data set, you would add a field "MQBYTE DUMMY;" between ID and VERSION.
  5. The supplied exit returns an error if the input buffer is shorter than the message format to be converted. Although the exit converts as many complete fields as possible, the error causes an unconverted message to be returned to the application. If you want to allow short input buffers to be converted as far as possible, including partial fields, change the TRUNC= value on the CSQXCDFA macro to YES: no error is returned, so the application receives a converted message. The application is responsible for handling the truncation.
  6. Add any other special processing code that you need.
  7. Rename the program to your data format name.
  8. Compile and link-edit your program like a batch application program (unless it is for use with CICS applications). The macros in the code generated by the utility are in the library, thlqual.SCSQMACS.

    If the message contains character data, the generated code will call MQXCNVC. If your exit uses this call, link-edit it with the exit stub program CSQASTUB. The stub is language-independent and environment-independent. Alternatively, you can load the stub dynamically using the dynamic call name CSQXCNVC. See Dynamically calling the WebSphere MQ stub for more information.

    Place the link-edited module in your application load library, and in a data set that is referenced by the CSQXLIB DD statement of your task procedure started by your channel initiator.

  9. If the exit is for use by CICS applications, compile and link-edit it like a CICS application program, including CSQASTUB if required. Place it in your CICS application program library. Define the program to CICS in the usual way, specifying EXECKEY(CICS) in the definition.
Note:
Although the LE/370 run-time libraries are needed for running the CSQUCVX utility (see step 2), they are not needed for link-editing or running the data-conversion exit itself (see steps 8 and 9).

See Writing WebSphere MQ-IMS bridge applications for information about data conversion within the WebSphere MQ-IMS bridge.



© IBM Corporation 1993, 2002. All Rights Reserved