Usage notes

Home
Usage notes
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.
The exit is invoked only if all of the following 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

When an exit is being written, consideration should be given to coding the exit in a way that will allow 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 will have 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 will have the value MQRC_NONE (if the receiving application provided a buffer that was big 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 will be 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 should 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 respectively.
If the exit has been written to convert truncated messages, the exit should 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 should leave the Reason field in the DataConvExitParms parameter unchanged. This has the effect of returning 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 will indicate whether the receiving application specified the MQGMO_ACCEPT_TRUNCATED_MSG option.
Generally it is recommended that all of 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 may be an incomplete item at the end of the buffer (for example: one byte of a double-byte character, or 3 bytes of a 4-byte integer). In this situation it is recommended that the incomplete item should be omitted, and unused bytes in OutBuffer set to nulls. However, complete elements or characters within an array or string should be converted.
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. It is recommended that the exit name, and the name of the object that contain the exit, should be identical, although not all environments require this.
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 may also be loaded at other times, if the queue manager has discarded a previously-loaded copy. For this reason, an exit should not attempt to use static storage to communicate information from one invocation of the exit to the next - the exit may be unloaded between the two invocations.
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).

The scope of the exit is environment-dependent. Format names should be chosen so as to minimize the risk of clashes with other formats. It is recommended that they start with characters that identify the application defining the format name.
The data-conversion exit runs in an environment similar to 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.
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.
No entry point called MQ_DATA_CONV_EXIT is actually 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 should 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 should 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 */
}
On z/OS, if an API-crossing exit is also in force, it is called after the data-conversion exit.
Home