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 are true:

    • The GMCONV option is specified on the MQGET call

    • The MDFMT field in the message descriptor is not FMNONE

    • The message is not already in the required representation; that is, one or both of the message's MDCSI and MDENC 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 RCNONE or RC2079

  3. 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 GMATM option on the MQGET call.

      In this case, the DXREA field in the MQDXP parameter on input to the exit will have the value RC2079.

    • 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 DXREA field in the MQDXP parameter on input to the exit will have the value RCNONE (if the receiving application provided a buffer that was big enough for the message).

    Thus the value of the DXREA 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 INLEN parameter will be less than the length implied by the format name contained in the MDFMT field in the message descriptor. The exit should therefore check the value of INLEN 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 INLEN is less than the value expected, the exit should return XRFAIL in the DXRES field of the MQDXP parameter, with the DXCC and DXREA fields set to CCWARN and RC2110 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 INBUF. If the conversion completes successfully, the exit should leave the DXREA field in the MQDXP parameter unchanged. This has the effect of returning RC2079 if the message was truncated by the receiver's queue manager, and RCNONE 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 OUTBUF. In this case the exit must decide whether to truncate the message; the DXAOP field in the MQDXP parameter will indicate whether the receiving application specified the GMATM option.

  4. Generally it is recommended that all of the data in the message provided to the exit in INBUF 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 OUTBUF set 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. 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.

  6. A new copy of the exit is loaded when an application attempts to retrieve the first message that uses that MDFMT since the application 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.

  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 MDCSI or MDENC 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. MDFMT 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.

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

  10. The only MQI call which can be used by the exit is MQXCNVC; attempting to use other MQI calls fails with reason code RC2219, or other unpredictable errors.

  11. No entry point called MQCONVX is actually provided by the queue manager. The name of the exit should be the same as the format name (the name contained in the MDFMT field in MQMD), although this is not required in all environments.