MQCHARV (Variable Length String) on IBM i

Use the MQCHARV structure to describe a variable length string.

Overview

Character set and encoding: Data in the MQCHARV must be in the encoding of the local queue manager that is given by ENNAT and the character set of the VCHRC field within the structure. If the application is running as an IBM MQ MQI client, the structure must be in the encoding of the client. Some character sets have a representation that depends on the encoding. If VCHRC is one of these character sets, the encoding used is the same encoding as that of the other fields in the MQCHARV. The character set identified by VSCCSID can be a double-byte character set (DBCS).

Usage: The MQCHARV structure addresses data that might be discontiguous with the structure containing it. To address this data, fields declared with the pointer data type can be used.

• Fields
• Initial values
• RPG declaration
• Redefinition of CSAPL

Fields

The MQCHARV structure contains the following fields; the fields are described in alphabetical order:

VCHRC (10-digit signed integer)

This is the character set identifier of the variable length string addressed by the VCHRP or VCHRO field.

The initial value of this field is CSAPL. This is defined by IBM MQ to indicate that it should be changed by the queue manager to the true character set identifier of the queue manager. This is in the same way as CSQM behaves. As a result, the value CSAPL is never associated with a variable length string. The initial value of this field can be changed by defining a different value for the constant CSAPL for the compile unit by the appropriate means for the application's programming language.

VCHRL (10-digit signed integer)

The length in bytes of the variable length string addressed by the VCHRP or VCHRO field.

The initial value of this field is 0. The value must be either greater than or equal to zero or the following special value which is recognized:

VSNLT

If VSNLT is not specified, VCHRL bytes are included as part of the string. If null characters are present they do not delimit the string.

If VSNLT is specified, the string is delimited by the first null encountered in the string. The null itself is not included as part of that string.

Note: The null character used to terminate a string if VSNLT is specified is a null from the code set specified by VCHRC.

For example, in UTF-16 (CCSIDs 1200, 13488, and 17584), this is the 2-byte Unicode encoding where a null is represented by a 16 bit number of all zeros. In UTF-16 it is common to find single bytes set to all zero which are part of characters (7-bit ASCII characters for example), but the strings will only be null terminated when two 'zero' bytes are found on an even byte boundary. It is possible to get two 'zero' bytes on an odd boundary when they are each part of valid characters. For example, x'01' x'00' x'00' x'30' represents two valid Unicode characters and does not null terminate the string.

VCHRO (10-digit signed integer)

The offset in bytes of the variable length string from the start of the MQCHARV, or the structure containing it.

When the MQCHARV structure is embedded within another structure, this value is the offset in bytes of the variable length string from the start of the structure that contains this MQCHARV structure. When the MQCHARV structure is not embedded within another structure, for example, if it is specified as a parameter on a function call, the offset is relative to the start of the MQCHARV structure.

The offset can be positive or negative. We can use either the VCHRP or VCHRO field to specify the variable length string, but not both.

The initial value of this field is 0.

VCHRP (pointer)

This is a pointer to the variable length string.

We can use either the VCHRP or VCHRO field to specify the variable length string, but not both.

The initial value of this field is a null pointer or null bytes.

VCHRS (10-digit signed integer)

The size in bytes of the buffer addressed by the VCHRP or VCHRO field.

When the MQCHARV structure is used as an output field on a function call, this field must be initialized with the length of the buffer provided. If the value of VCHRL is greater than VCHRS then only VCHRS bytes of data will be returned to the caller in the buffer.

The value must be greater than or equal to zero or the following special value which is recognized:

VSUSL

If VSUSL is specified, the length of the buffer is taken from the VCHRL field in the MQCHARV structure. This special value is not appropriate when the structure is used as an output field and a buffer is provided. This is the initial value of this field.

Initial values

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7.. 
     D* MQCHARV Structure
     D*
     D* Address of variable length string
     D VCHRP                   1     16*
     D* Offset of variable length string
     D VCHRO                  17     20I 0
     D* Size of buffer
     D VCHRS                  21     24I 0
     D* Length of variable length string
     D VCHRL                  25     28I 0
     D* CCSID of variable length string
     D VCHRC                  29     32I 0

Redefinition of CSAPL

Unlike the programming languages supported on other platforms, RPG does not have a way of redefining a defined constant, so we must set each VCHRC specifically if we want to use a value other than CSAPL.