Writing a data-conversion exit program

 

For z/OS, 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:

 

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 6.

Table 6. Skeleton source files

Platform
 File
AIX
 amqsvfc0.c
OS/400
 QMQMSAMP/QCSRC(AMQSVFC4)
AT&T GIS UNIX
 amqsvfcx.c
Compaq Tru64 UNIX
 amqsvfcx.c
Compaq OpenVMS Alpha
 AMQSVFCX.C
HP-UX
 amqsvfc0.c
Linux
 amqsvfc0.c
OS/2
 AMQSVFC0.C
z/OS
 CSQ4BAX8 (1)
CSQ4BAX9 (2)
CSQ4CAX9 (3)
SINIX and DC/OSx
 amqsvfcx.c
Solaris
 amqsvfc0.c
Compaq NonStop Kernel
 amqsvfcn
Windows systems
 amqsvfc0.c

Notes:

  1. Illustrates the MQXCVNC call.

  2. A wrapper for the code fragments generated by the utility for use in all environments except CICS.

  3. A wrapper for the code fragments generated by the utility for use in the CICS environment.

 

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. On z/OS, 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)

 

z/OS data definition statements

The CSQUCVX utility requires DD statements with the following DDnames:

SYSPRINT This specifies a data set or print spool class for reports and error messages.
CSQUINP This specifies the sequential data set containing the definitions of the data structures to be converted.
CSQUOUT This specifies the sequential data set where the conversion code fragments are to be written. The logical record length (LRECL) must be 80 and the record format (RECFM) must be FB.

 

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, 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);

 

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.