MQ_DATA_CONV_EXIT - Data conversion exit

The MQ_DATA_CONV_EXIT call describes the parameters that are passed to the data-conversion exit.

No entry point called MQ_DATA_CONV_EXIT is provided by the queue manager (see usage note 11 ).

This definition is part of the IBM MQ Data Conversion Interface (DCI), which is one of the IBM MQ framework interfaces.


Syntax

MQ_DATA_CONV_EXIT (DataConvExitParms, MsgDesc, InBufferLength, InBuffer, OutBufferLength, OutBuffer)


Parameters

    DataConvExitParms
    Type: MQDXP - input/output

    This structure contains information relating to the invocation of the exit. The exit sets information in this structure to indicate the outcome of the conversion. See MQDXP - Data-conversion exit parameter for details of the fields in this structure.

    MsgDesc
    Type: MQMD - input/output

    On input to the exit, this is the message descriptor associated with the message data passed to the exit in the InBuffer parameter.

    Note: The MsgDesc parameter passed to the exit is always the most recent version of MQMD supported by the queue manager which invokes the exit. If the exit is intended to be portable between different environments, the exit will check the Version field in MsgDesc to verify that the fields that the exit needs to access are present in the structure.

    In the following environments, the exit is passed a version-2 MQMD: AIX , HP-UX, IBM i, Solaris, Linux , Windows. In all other environments that support the data conversion exit, the exit is passed a version-1 MQMD.

    On output, the exit will change the Encoding and CodedCharSetId fields to the values requested by the application, if conversion was successful; these changes are reflected back to the application. Any other changes that the exit makes to the structure are ignored; they are not reflected back to the application.

    If the exit returns MQXDR_OK in the ExitResponse field of the MQDXP structure, but does not change the Encoding or CodedCharSetId fields in the message descriptor, the queue manager returns for those fields the values that the corresponding fields in the MQDXP structure had on input to the exit.

    InBufferLength
    Type: MQLONG - input

    Length in bytes of InBuffer.

    This is the length of the input buffer InBuffer, and specifies the number of bytes to be processed by the exit. InBufferLength is the lesser of the length of the message data before conversion, and the length of the buffer provided by the application on the MQGET call.

    The value is always greater than zero.

    InBuffer
    Type: MQBYTExInBufferLength - input

    Buffer containing the unconverted message.

    This contains the message data before conversion. If the exit is unable to convert the data, the queue manager returns the contents of this buffer to the application after the exit has completed.

    Note: The exit should not alter InBuffer ; if this parameter is altered, the results are undefined.

    In the C programming language, this parameter is defined as a pointer-to-void.

    OutBufferLength
    Type: MQLONG - input

    Length in bytes of OutBuffer.

    This is the length of the output buffer OutBuffer, and is the same as the length of the buffer provided by the application on the MQGET call.

    The value is always greater than zero.

    OutBuffer
    Type: MQBYTExOutBufferLength - output

    Buffer containing the converted message.

    On output from the exit, if the conversion was successful (as indicated by the value MQXDR_OK in the ExitResponse field of the DataConvExitParms parameter), OutBuffer contains the message data to be delivered to the application, in the requested representation. If the conversion was unsuccessful, any changes that the exit has made to this buffer are ignored.

    In the C programming language, this parameter is defined as a pointer-to-void.


Usage notes

  1. A data-conversion exit is a user-written exit which receives control during the processing of an MQGET call. The function performed by the data-conversion exit is defined by the provider of the exit; however, the exit must conform to the rules described here, and in the associated parameter structure MQDXP.

    The programming languages that can be used for a data-conversion exit are determined by the environment.

  2. The exit is invoked only if all of the following statements are true:

    • The MQGMO_CONVERT option is specified on the MQGET call
    • The Format field in the message descriptor is not MQFMT_NONE
    • The message is not already in the required representation; that is, one or both of the message's CodedCharSetId and Encoding is different from the value specified by the application in the message descriptor supplied on the MQGET call
    • The queue manager has not already done the conversion successfully
    • The length of the application's buffer is greater than zero
    • The length of the message data is greater than zero
    • The reason code so far during the MQGET operation is MQRC_NONE or MQRC_TRUNCATED_MSG_ACCEPTED
  3. When an exit is being written, consider coding the exit in a way that allows it to convert messages that have been truncated. Truncated messages can arise in the following ways:

    • The receiving application provides a buffer that is smaller than the message, but specifies the MQGMO_ACCEPT_TRUNCATED_MSG option on the MQGET call.

      In this case, the Reason field in the DataConvExitParms parameter on input to the exit has the value MQRC_TRUNCATED_MSG_ACCEPTED.

    • The sender of the message truncated it before sending it. This can happen with report messages, for example (see Conversion of report messages for more details).

      In this case, the Reason field in the DataConvExitParms parameter on input to the exit has the value MQRC_NONE (if the receiving application provided a buffer that was large enough for the message).

    Thus the value of the Reason field on input to the exit cannot always be used to decide whether the message has been truncated.

    The distinguishing characteristic of a truncated message is that the length provided to the exit in the InBufferLength parameter is less than the length implied by the format name contained in the Format field in the message descriptor. The exit should therefore check the value of InBufferLength before attempting to convert any of the data; the exit should not assume that the full amount of data implied by the format name has been provided.

    If the exit has not been written to convert truncated messages, and InBufferLength is less than the value expected, the exit will return MQXDR_CONVERSION_FAILED in the ExitResponse field of the DataConvExitParms parameter, with the CompCode and Reason fields set to MQCC_WARNING and MQRC_FORMAT_ERROR.

    If the exit has been written to convert truncated messages, the exit will convert as much of the data as possible (see next usage note), taking care not to attempt to examine or convert data beyond the end of InBuffer. If the conversion completes successfully, the exit will leave the Reason field in the DataConvExitParms parameter unchanged. This returns MQRC_TRUNCATED_MSG_ACCEPTED if the message was truncated by the receiver's queue manager, and MQRC_NONE if the message was truncated by the sender of the message.

    It is also possible for a message to expand during conversion, to the point where it is bigger than OutBuffer. In this case the exit must decide whether to truncate the message; the AppOptions field in the DataConvExitParms parameter indicates whether the receiving application specified the MQGMO_ACCEPT_TRUNCATED_MSG option.

  4. Generally, all the data in the message provided to the exit in InBuffer is converted, or that none of it is. An exception to this, however, occurs if the message is truncated, either before conversion or during conversion; in this case there can be an incomplete item at the end of the buffer (for example: 1 byte of a double-byte character, or 3 bytes of a 4-byte integer). In this situation, consider omitting the incomplete item and set the unused bytes in the OutBuffer to nulls. However, complete elements or characters within an array or string should be converted.
  5. When an exit is needed for the first time, the queue manager attempts to load an object that has the same name as the format (apart from extensions). The object loaded must contain the exit that processes messages with that format name. Consider making the exit name, and the name of the object that contains the exit identical, although not all environments require this.
  6. A new copy of the exit is loaded when an application attempts to retrieve the first message that uses that Format since the application connected to the queue manager. For CICS® or IMS applications, this means when the CICS or IMS subsystem connected to the queue manager. A new copy can also be loaded at other times, if the queue manager has discarded a previously loaded copy. For this reason, an exit must not attempt to use static storage to communicate information from one invocation of the exit to the next - the exit can be unloaded between the two invocations.
  7. If there is a user-supplied exit with the same name as one of the built-in formats supported by the queue manager, the user-supplied exit does not replace the built-in conversion routine. The only circumstances in which such an exit is invoked are:

    • If the built-in conversion routine cannot handle conversions to or from either the CodedCharSetId or Encoding involved, or
    • If the built-in conversion routine has failed to convert the data (for example, because there is a field or character which cannot be converted).
  8. The scope of the exit is environment-dependent. Format names must be chosen to minimize the risk of clashes with other formats. Consider starting with characters that identify the application defining the format name.
  9. The data-conversion exit runs in an environment like that of the program which issued the MQGET call; environment includes address space and user profile (where applicable). The program could be a message channel agent sending messages to a destination queue manager that does not support message conversion. The exit cannot compromise the queue manager's integrity, since it does not run in the queue manager's environment.
  10. The only MQI call which can be used by the exit is MQXCNVC; attempting to use other MQI calls fails with reason code MQRC_CALL_IN_PROGRESS, or other unpredictable errors.
  11. No entry point called MQ_DATA_CONV_EXIT is provided by the queue manager. However, a typedef is provided for the name MQ_DATA_CONV_EXIT in the C programming language, and this can be used to declare the user-written exit, to ensure that the parameters are correct. The name of the exit must be the same as the format name (the name contained in the Format field in MQMD), although this is not required in all environments. The following example illustrates how the exit that processes the format MYFORMAT can be declared in the C programming language: 
    #include "cmqc.h"
#include "cmqxc.h"

MQ_DATA_CONV_EXIT MYFORMAT;

void MQENTRY MYFORMAT(
     PMQDXP   pDataConvExitParms, /* Data-conversion exit parameter
                                     block */
     PMQMD    pMsgDesc,           /* Message descriptor */
     MQLONG   InBufferLength,     /* Length in bytes of InBuffer */
     PMQVOID  pInBuffer,          /* Buffer containing the unconverted
                                     message */
     MQLONG   OutBufferLength,    /* Length in bytes of OutBuffer */
     PMQVOID  pOutBuffer)         /* Buffer containing the converted
                                     message */
{
  /* C language statements to convert message */
}
  12. On z/OS®, if an API-crossing exit is also in force, it is called after the data-conversion exit.


C invocation

exitname (&DataConvExitParms, &MsgDesc, InBufferLength,
         InBuffer, OutBufferLength, OutBuffer);
The parameters passed to the exit are declared as follows: 
MQDXP   DataConvExitParms;  /* Data-conversion exit parameter block */
MQMD    MsgDesc;            /* Message descriptor */
MQLONG  InBufferLength;     /* Length in bytes of InBuffer */
MQBYTE  InBuffer[n];        /* Buffer containing the unconverted
                               message */
MQLONG  OutBufferLength;    /* Length in bytes of OutBuffer */
MQBYTE  OutBuffer[n];       /* Buffer containing the converted
                               message */


COBOL declaration ( IBM i only)

     CALL 'exitname' USING DATACONVEXITPARMS, MSGDESC, INBUFFERLENGTH,
                           INBUFFER, OUTBUFFERLENGTH, OUTBUFFER.
The parameters passed to the exit are declared as follows: 
**   Data-conversion exit parameter block
 01  DATACONVEXITPARMS.
     COPY CMQDXPV.
**   Message descriptor
 01  MSGDESC.
     COPY CMQMDV.
**   Length in bytes of INBUFFER
 01  INBUFFERLENGTH     PIC S9(9) BINARY.
**   Buffer containing the unconverted message
 01  INBUFFER           PIC X(n).
**   Length in bytes of OUTBUFFER
 01  OUTBUFFERLENGTH    PIC S9(9) BINARY.
**   Buffer containing the converted message
 01  OUTBUFFER          PIC X(n).


System/390 assembler declaration

         CALL EXITNAME,(DATACONVEXITPARMS,MSGDESC,INBUFFERLENGTH,      X
               INBUFFER,OUTBUFFERLENGTH,OUTBUFFER)
The parameters passed to the exit are declared as follows: 
DATACONVEXITPARMS  CMQDXPA  ,      Data-conversion exit parameter block
MSGDESC            CMQMDA   ,      Message descriptor
INBUFFERLENGTH     DS       F      Length in bytes of INBUFFER
INBUFFER           DS       CL(n)  Buffer containing the unconverted
*                                  message
OUTBUFFERLENGTH    DS       F      Length in bytes of OUTBUFFER
OUTBUFFER          DS       CL(n)  Buffer containing the converted
*                                  message