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 exit is invoked if the following are true:

• 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 the WebSphere MQ Application Programming Reference.

See the WebSphere MQ Application Programming Reference 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 may also be loaded at other times if the queue manager has discarded a previously-loaded copy.

The data-conversion exit runs in an environment similar to that of the program which 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 queue manager's integrity, since it does not run in the queue manager's environment.

In a client-server environment, the exit is loaded at the server, and conversion takes place there.

Data conversion on z/OS

On z/OS, you must also be aware of the following:

• Exit programs can be written in assembler language only.
• Exit programs must be re-entrant, 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 normally 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 should 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 make use of CICS API calls, with the following caution:

  • Do not issue syncpoints, as the results could influence units of work declared by the MCA.
  • Do not update any resources controlled by a resource manager other than WebSphere MQ for z/OS, including those controlled by CICS Transaction Server for z/OS.
• For distributed queuing without CICS, the exit is loaded from the data set referenced by the CSQXLIB DD statement. In other environments, the exit is loaded from the same place as application programs.
• For distributed queuing using CICS, data-conversion exits are not supported.