Parameters

The MQXCNVC call has the following parameters.

Hconn (MQHCONN) - input

Connection handle.

This handle represents the connection to the queue manager.

In a data-conversion exit, Hconn should normally be the handle passed to the data-conversion exit in the Hconn field of the MQDXP structure; this handle is not necessarily the same as the handle specified by the application which issued the MQGET call.

On i5/OS, the following special value can be specified for Hconn:

MQHC_DEF_HCONN
Default connection handle.

Options (MQLONG) - input

Options that control the action of MQXCNVC.

Zero or more of the options described below can be specified. If more than one is required, the values can be:

Default-conversion option: The following option controls the use of default character conversion:

MQDCC_DEFAULT_CONVERSION
Default conversion.

This option specifies that default character conversion can be used if one or both of the character sets specified on the call is not supported. This allows the queue manager to use an installation-specified default character set that approximates the specified character set, when converting the string.

Note:
The result of using an approximate character set to convert the string is that some characters may be converted incorrectly. This can be avoided by using in the string only characters which are common to both the specified character set and the default character set.

The default character sets are defined by a configuration option when the queue manager is installed or restarted.

If MQDCC_DEFAULT_CONVERSION is not specified, the queue manager uses only the specified character sets to convert the string, and the call fails if one or both of the character sets is not supported.

This option is supported in the following environments: AIX, HP-UX, OS/2, i5/OS, Solaris, Linux, Windows.

Padding option: The following option allows the queue manager to pad the converted string with blanks or discard insignificant trailing characters, in order to make the converted string fit the target buffer:

MQDCC_FILL_TARGET_BUFFER
Fill target buffer.

This option requests that conversion take place in such a way that the target buffer is filled completely:

If this option is not specified:

This option is supported in the following environments: AIX, HP-UX, OS/2, i5/OS, Solaris, Linux, Windows.

Encoding options: The options described below can be used to specify the integer encodings of the source and target strings. The relevant encoding is used only when the corresponding character set identifier indicates that the representation of the character set in main storage is dependent on the encoding used for binary integers. This affects only certain multibyte character sets (for example, UCS-2 character sets).

The encoding is ignored if the character set is a single-byte character set (SBCS), or a multibyte character set whose representation in main storage is not dependent on the integer encoding.

Only one of the MQDCC_SOURCE_* values should be specified, combined with one of the MQDCC_TARGET_* values:

MQDCC_SOURCE_ENC_NATIVE
Source encoding is the default for the environment and programming language.
MQDCC_SOURCE_ENC_NORMAL
Source encoding is normal.
MQDCC_SOURCE_ENC_REVERSED
Source encoding is reversed.
MQDCC_SOURCE_ENC_UNDEFINED
Source encoding is undefined.
MQDCC_TARGET_ENC_NATIVE
Target encoding is the default for the environment and programming language.
MQDCC_TARGET_ENC_NORMAL
Target encoding is normal.
MQDCC_TARGET_ENC_REVERSED
Target encoding is reversed.
MQDCC_TARGET_ENC_UNDEFINED
Target encoding is undefined.

The encoding values defined above can be added directly to the Options field. However, if the source or target encoding is obtained from the Encoding field in the MQMD or other structure, the following processing must be done:

  1. The integer encoding must be extracted from the Encoding field by eliminating the float and packed-decimal encodings; see Analyzing encodings for details of how to do this.
  2. The integer encoding resulting from step 1 must be multiplied by the appropriate factor before being added to the Options field. These factors are:

The following illustrates how this might be coded in the C programming language:


Options = (MsgDesc.Encoding & MQENC_INTEGER_MASK) * MQDCC_SOURCE_ENC_FACTOR + (DataConvExitParms.Encoding & MQENC_INTEGER_MASK) * MQDCC_TARGET_ENC_FACTOR;

If not specified, the encoding options default to undefined (MQDCC_*_ENC_UNDEFINED). In most cases, this does not affect the successful completion of the MQXCNVC call. However, if the corresponding character set is a multibyte character set whose representation is dependent on the encoding (for example, a UCS-2 character set), the call fails with reason code MQRC_SOURCE_INTEGER_ENC_ERROR or MQRC_TARGET_INTEGER_ENC_ERROR as appropriate.

The encoding options are supported in the following environments: AIX, HP-UX, z/OS, OS/2, i5/OS, Solaris, Linux, Windows.

Default option: If none of the options described above is specified, the following option can be used:

MQDCC_NONE
No options specified.

MQDCC_NONE is defined to aid program documentation. It is not intended that this option be used with any other, but as its value is zero, such use cannot be detected.

SourceCCSID (MQLONG) - input

Coded character set identifier of string before conversion.

This is the coded character set identifier of the input string in SourceBuffer.

SourceLength (MQLONG) - input

Length of string before conversion.

This is the length in bytes of the input string in SourceBuffer; it must be zero or greater.

SourceBuffer (MQCHAR×SourceLength) - input

String to be converted.

This is the buffer containing the string to be converted from one character set to another.

TargetCCSID (MQLONG) - input

Coded character set identifier of string after conversion.

This is the coded character set identifier of the character set to which SourceBuffer is to be converted.

TargetLength (MQLONG) - input

Length of output buffer.

This is the length in bytes of the output buffer TargetBuffer; it must be zero or greater. It can be less than or greater than SourceLength.

TargetBuffer (MQCHAR×TargetLength) - output

String after conversion.

This is the string after it has been converted to the character set defined by TargetCCSID. The converted string can be shorter or longer than the unconverted string. The DataLength parameter indicates the number of valid bytes returned.

DataLength (MQLONG) - output

Length of output string.

This is the length of the string returned in the output buffer TargetBuffer. The converted string can be shorter or longer than the unconverted string.

CompCode (MQLONG) - output

Completion code.

It is one of the following:

MQCC_OK
Successful completion.
MQCC_WARNING
Warning (partial completion).
MQCC_FAILED
Call failed.

Reason (MQLONG) - output

Reason code qualifying CompCode.

If CompCode is MQCC_OK:

MQRC_NONE
(0, X'000') No reason to report.

If CompCode is MQCC_WARNING:

MQRC_CONVERTED_MSG_TOO_BIG
(2120, X'848') Converted data too big for buffer.

If CompCode is MQCC_FAILED:

MQRC_DATA_LENGTH_ERROR
(2010, X'7DA') Data length parameter not valid.
MQRC_DBCS_ERROR
(2150, X'866') DBCS string not valid.
MQRC_HCONN_ERROR
(2018, X'7E2') Connection handle not valid.
MQRC_OPTIONS_ERROR
(2046, X'7FE') Options not valid or not consistent.
MQRC_RESOURCE_PROBLEM
(2102, X'836') Insufficient system resources available.
MQRC_SOURCE_BUFFER_ERROR
(2145, X'861') Source buffer parameter not valid.
MQRC_SOURCE_CCSID_ERROR
(2111, X'83F') Source coded character set identifier not valid.
MQRC_SOURCE_INTEGER_ENC_ERROR
(2112, X'840') Source integer encoding not recognized.
MQRC_SOURCE_LENGTH_ERROR
(2143, X'85F') Source length parameter not valid.
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') Insufficient storage available.
MQRC_TARGET_BUFFER_ERROR
(2146, X'862') Target buffer parameter not valid.
MQRC_TARGET_CCSID_ERROR
(2115, X'843') Target coded character set identifier not valid.
MQRC_TARGET_INTEGER_ENC_ERROR
(2116, X'844') Target integer encoding not recognized.
MQRC_TARGET_LENGTH_ERROR
(2144, X'860') Target length parameter not valid.
MQRC_UNEXPECTED_ERROR
(2195, X'893') Unexpected error occurred.

For more information on these reason codes, see Appendix A. Return codes.