Writing a data-conversion exit program

For z/OS, you must write data-conversion exits in assembler language. For other platforms, it is recommended that you use the C programming language.

To help you create a data-conversion exit program, the following are supplied:

• A skeleton source file
• A convert characters call
• A utility that creates a fragment of code that performs data conversion on data type structures This utility takes C input only. On z/OS, it produces assembler code.

These are described in subsequent sections.

For the procedure for writing the programs see:

• Writing a data-conversion exit program for WebSphere MQ for iSeries
• Writing a data-conversion exit program for WebSphere MQ for z/OS
• Writing a data-conversion exit for MQSeries for Compaq NonStop Kernel
• Writing a data-conversion exit for WebSphere MQ on UNIX systems and Compaq OpenVMS Alpha
• Writing a data-conversion exit for WebSphere MQ for Windows

Skeleton source file

These can be used as your starting point when writing a data-conversion exit program. The files supplied are listed in Table 7.

Table 7. Skeleton source files

Convert characters call

The MQXCNVC (Convert characters) call can be used from within a data-conversion exit program to convert character message data from one character set to another. For certain multibyte character sets (for example, UCS2 character sets), the appropriate options must be used.

No other MQI calls can be made from within the exit; an attempt to make such a call fails with reason code MQRC_CALL_IN_PROGRESS.

See WebSphere MQ Application Programming Reference for further information on the MQXCNVC call and appropriate options.

Utility for creating conversion-exit code

The commands for creating conversion-exit code are:

iSeries

CVTMQMDTA (Convert WebSphere MQ Data Type)

OS/2, Compaq OpenVMS Alpha, Compaq NonStop Kernel, Windows systems, and UNIX systems

crtmqcvx (Create WebSphere MQ conversion-exit)

z/OS

CSQUCVX

The command for your platform produces a fragment of code that performs data conversion on data type structures, for use in your data-conversion exit program. The command takes a file containing one or more C language structure definitions. On z/OS, it then generates a data set containing assembler code fragments and conversion functions. On other platforms, it generates a file with a C function to convert each structure definition. The utility requires access to the LE/370 run-time library SCEERUN.

Invoking the CSQUCVX utility on z/OS

Figure 13 shows an example of the JCL used to invoke the CSQUCVX utility.

Figure 13. Sample JCL used to invoke the CSQUCVX utility

//CVX    EXEC PGM=CSQUCVX
//STEPLIB  DD DISP=SHR,DSN=thlqual.SCSQANLE
//         DD DISP=SHR,DSN=thlqual.SCSQLOAD
//         DD DISP=SHR,DSN=le370qual.SCEERUN
//SYSPRINT DD SYSOUT=*
//CSQUINP  DD DISP=SHR,DSN=MY.MQSERIES.FORMATS(MSG1)
//CSQUOUT  DD DISP=OLD,DSN=MY.MQSERIES.EXITS(MSG1)

Data definition statements

The CSQUCVX utility requires DD statements with the following DDnames:

Error messages in OS/2, Windows systems, and UNIX systems

The crtmqcvx command returns messages in the range AMQ7953 through AMQ7970. These are listed in WebSphere MQ Messages for MQSeries or WebSphere MQ Version 5 products. For other platforms, see the appropriate System Management Guide for your platform.

There are two main types of error:

• Major errors, such as syntax errors, when processing cannot continue.

  A message is displayed on the screen giving the line number of the error in the input file. The output file may have been partially created.

• Other errors when a message is displayed stating that a problem has been found but parsing of the structure can continue.

  The output file has been created and contains error information on the problems that have occurred. This error information is prefixed by #error so that the code produced will not be accepted by any compiler without intervention to rectify the problems.

Valid syntax

Your input file for the utility must conform to the C language syntax. If you are unfamiliar with C, refer to Example of valid syntax for the input data set.

In addition, you must be aware of the following rules:

• typedef is recognized only before the struct keyword.
• A structure tag is required on your structure declarations.
• Empty square brackets [ ] may be used to denote a variable length array or string at the end of a message.
• Multidimensional arrays and arrays of strings are not supported.
• The following additional data types are recognized:

  MQBYTE

  MQCHAR

  MQSHORT

  MQLONG

  MQCHAR fields are code page converted, but MQBYTE is left untouched. If the encoding is different, MQSHORT and MQLONG are converted accordingly.

• The following should not be used:

  float

  double

  pointers

  bit-fields

  This is because the utility for creating conversion-exit code does not provide the facility to convert these data types. To overcome this, you can write your own routines and call them from the exit.

Other points to note:

• Do not use sequence numbers in the input data set.
• If there are fields for which you want to provide your own conversion routines, declare them as MQBYTE, and then replace the generated CMQXCFBA macros with your own conversion code.

Example of valid syntax for the input data set

  struct TEST { MQLONG    SERIAL_NUMBER;
                MQCHAR    ID[5];
                MQSHORT   VERSION;
                MQBYTE    CODE[4];
                MQLONG    DIMENSIONS[3];
                MQCHAR    NAME[24];
              } ;

This corresponds to the following declarations in other programming languages:

COBOL

       10 TEST.
        15 SERIAL-NUMBER  PIC S9(9) BINARY.
        15 ID             PIC X(5).
        15 VERSION        PIC S9(4) BINARY.
      * CODE IS NOT TO BE CONVERTED
        15 CODE           PIC X(4).
        15 DIMENSIONS     PIC S9(9) BINARY OCCURS 3 TIMES.
        15 NAME           PIC X(24).

System/390 assembler

Only supported in WebSphere MQ for z/OS.

TEST           EQU *
SERIAL_NUMBER  DS  F
ID             DS  CL5
VERSION        DS  H
CODE           DS  XL4
DIMENSIONS     DS  3F
NAME           DS  CL24

PL/I

Supported on AIX, z/OS, OS/2 and Windows systems only

 DCL 1 TEST,
       2 SERIAL_NUMBER  FIXED BIN(31),
       2 ID             CHAR(5),
       2 VERSION        FIXED BIN(15),
       2 CODE           CHAR(4),        /* not to be converted */
       2 DIMENSIONS(3)  FIXED BIN(31),
       2 NAME           CHAR(24);