MQCONVX (Data conversion exit) on IBM i

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 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 on IBM i 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 large 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 field set to CCWARN and the DXREA field set to RC2110.

   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 returns 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 might 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 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 RC2219, or other unpredictable errors.
11. No entry point called MQCONVX is 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.

MQDXP (MQDXP) - input/output

Data-conversion exit parameter block.

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) on IBM i for details of the fields in this structure.

MQMD (MQMD) - input/output

Message descriptor.

On input to the exit, this is the message descriptor that would be returned to the application if no conversion were performed. It therefore contains the MDFMT, MDENC, and MDCSI of the unconverted message contained in INBUF.

Note: The MQMD 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 should check the MDVER field in MQMD to verify that the fields that the exit needs to access are present in the structure.

On IBM i, the exit is passed a version-2 MQMD.

On output, the exit should change the MDENC and MDCSI fields to the values requested by the application, if conversion was successful; these changes will be 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 XROK in the DXRES field of the MQDXP structure, but does not change the MDENC or MDCSI 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.

INLEN (10-digit signed integer) - input

Length in bytes of INBUF.

This is the length of the input buffer INBUF, and specifies the number of bytes to be processed by the exit. INLEN 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.

INBUF (1-byte bit string x INLEN) - 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 INBUF ; if this parameter is altered, the results are undefined.

OUTLEN (10-digit signed integer) - input

Length in bytes of OUTBUF.

This is the length of the output buffer OUTBUF, 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.

OUTBUF (1-byte bit string x OUTLEN) - output

Buffer containing the converted message.

On output from the exit, if the conversion was successful (as indicated by the value XROK in the DXRES field of the MQDXP parameter), OUTBUF 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.

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     exitname(MQDXP : MQMD : INLEN :
     C                                        INBUF : OUTLEN : OUTBUF)

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     Dexitname         PR                  EXTPROC('exitname')
     D* Data-conversion exit parameter block
     D MQDXP                         44A
     D* Message descriptor
     D MQMD                         364A
     D* Length in bytes of INBUF
     D INLEN                         10I 0 VALUE
     D* Buffer containing the unconverted message
     D INBUF                           *   VALUE
     D* Length in bytes of OUTBUF
     D OUTLEN                        10I 0 VALUE
     D* Buffer containing the converted message
     D OUTBUF                          *   VALUE