Invoking the data-conversion exit

A data-conversion exit is a user-written exit that receives control during the processing of an MQGET call.

• The MQGMO_CONVERT option is specified on the MQGET call.
• Some or all of the message data is not in the requested character set or encoding.
• The Format field in the MQMD structure associated with the message is not MQFMT_NONE.
• The BufferLength specified on the MQGET call is not zero.
• The message data length is not zero.
• The message contains data that has a user-defined format. The user-defined format can occupy the entire message, or be preceded by one or more built-in formats. For example, the user-defined format might be preceded by an MQFMT_DEAD_LETTER_HEADER format. The exit is invoked to convert only the user-defined format; the queue manager converts any built-in formats that precede the user-defined format.

  A user-written exit can also be invoked to convert a built-in format, but this happens only if the built-in conversion routines cannot convert the built-in format successfully.

There are some other conditions, described fully in the usage notes of the MQ_DATA_CONV_EXIT call in MQ_DATA_CONV_EXIT.

See MQGET for details of the MQGET call. Data-conversion exits cannot use MQI calls, other than MQXCNVC.

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. A new copy might also be loaded at other times if the queue manager has discarded a previously loaded copy.

The data-conversion exit runs in an environment like that of the program that issued the MQGET call. As well as user applications, the program can be an MCA (message channel agent) sending messages to a destination queue manager that does not support message conversion. The environment includes address space and user profile, where applicable. The exit cannot compromise the integrity of the queue manager, because it does not run in the queue manager's environment.

Data conversion on z/OS

• Exit programs can be written in assembly language only.
• Exit programs must be reentrant, and capable of running anywhere in storage.
• Exit programs must restore the environment on exit to that at entry, and must free any storage obtained.
• Exit programs must not WAIT, or issue ESTAEs or SPIEs.
• Exit programs are typically invoked as if by z/OS LINK in:
  • Non-authorized problem program state
  • Primary address space control mode
  • Non cross-memory mode
  • Non access-register mode
  • 31 bit addressing mode
  • TCB-PRB mode

• When used by a CICS application, the exit is invoked by EXEC CICS LINK, and must conform to the CICS programming conventions. The parameters are passed by pointers (addresses) in the CICS communication area (COMMAREA). Although not recommended, user exit programs can also use CICS API calls, with the following caution:
  • Do not issue sync points, as the results could influence units of work declared by the MCA.
  • Do not update any resources controlled by a resource manager other than IBM MQ for z/OS, including those controlled by CICS Transaction Server.

  For channels with CONVERT=YES, the exit is loaded from the data set referenced by the CSQXLIB DD statement. MQ-supplied exits CSQCBDCI and CSQCBDCO for the IBM MQ CICS Bridge are in SCSQAUTH.

Parent topic: Writing data-conversion exits