MQCHARV - Variable Length String

Use the MQCHARV structure to describe a variable length string.

Availability

The MQCHARV structure is available on the following platforms:

AIX®
IBM® i
Linux®
Windows

and for IBM MQ MQI clients connected to these systems.

Character set and encoding

Data in the MQCHARV must be in the encoding of the local queue manager that is given by MQENC_NATIVE and the character set of the VSCCSID field within the structure. If the application is running as an MQ client, the structure must be in the encoding of the client. Some character sets have a representation that depends on the encoding. If VSCCSID 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. Be aware that COBOL does not support the pointer data type in all environments. Because of this, the data can also be addressed using fields that contain the offset of the data from the start of the structure containing the MQCHARV.

Fields

Note: In the following table, the fields are grouped by usage rather than alphabetically.

Table 1. Fields in MQCHARV
Field name and description	Name of constant	Initial value (if any) of constant
VSPtr (pointer to the variable length string)	None	Null pointer or null bytes.
VSOffset (offset in bytes of the variable length string from the start of the structure that contains this MQCHARV structure)	None	0
VSBufSize (size in bytes of the buffer addressed by the VSPtr or VSOffset field)	MQVS_USE_VSLENGTH	0
VSLength (length in bytes of the variable length string addressed by the VSPtr or VSOffset field)	None	0
VSCCSID (character set identifier of the variable length string addressed by the VSPtr or VSOffset field)	MQCCSI_APPL	-3
Note: In the C programming language, the macro variable MQCHARV_DEFAULT contains the values that are listed in the table. It can be used in the following way to provide initial values for the fields in the structure: `MQCHARV MyVarStr = {MQCHARV_DEFAULT};`

Language declarations

C declaration for MQCHARV

typedef struct tagMQCHARV MQCHARV;
struct tagMQCHARV {
  MQPTR     VSPtr;               /* Address of variable length string */
  MQLONG    VSOffset;            /* Offset of variable length string */
  MQLONG    VSBufSize;           /* Size of buffer */
  MQLONG    VSLength;            /* Length of variable length string */
  MQLONG    VSCCSID;             /* CCSID of variable length string */
};

COBOL declaration for MQCHARV

** MQCHARV structure
 10  MQCHARV.
** Address of variable length string
 15  MQCHARV-VSPTR        POINTER.
** Offset of variable length string
 15  MQCHARV-VSOFFSET     PIC S9(9) BINARY.
** Size of buffer
 15  MQCHARV-VSBUFSIZE    PIC S9(9) BINARY.
** Length of variable length string
 15  MQCHARV-VSLENGTH     PIC S9(9) BINARY.
** CCSID of variable length string
 15  MQCHARV-VSCCSID      PIC S9(9) BINARY.

Note: If you want to port a COBOL application between environments, you must find out if the pointer data type is available in all the intended environments. If not, the application must address the data using the offset fields instead of the pointer fields. In environments where pointers are not supported, you can declare the pointer fields as byte strings of the appropriate length, with the initial value being the all-null byte string. Do not alter this initial value if you are using the offset fields. One way to do this without changing the supplied copy books is to use the following:

COPY CMQCHRVV REPLACING POINTER BY ==BINARY PIC S9(9)==.

where CMQCHRVV can be exchanged for the copy book to be used.

PL/I declaration for MQCHARV

dcl
 1 MQCHARV based,
  3 VSPtr       pointer,       /* Address of variable length string */
  3 VSOffset    fixed bin(31), /* Offset of variable length string */
  3 VSBufSize   fixed bin(31), /* Size of buffer */
  3 VSLength    fixed bin(31), /* Length of variable length string */
  3 VSCCSID     fixed bin(31); /* CCSID of variable length string */

High Level Assembler declaration for MQCHARV

MQCHARV             DSECT
MQCHARV_VSPTR       DS   F     Address of variable length string 
MQCHARV_VSOFFSET    DS   F     Offset of variable length string 
MQCHARV_VSBUFSIZE   DS   F     Size of buffer
MQCHARV_VSLENGTH    DS   F     Length of variable length string
MQCHARV_VSCCSID     DS   F     CCSID of variable length string
*
MQCHARV_LENGTH      EQU  *-MQCHARV
                    ORG  MQCHARV
MQCHARV_AREA        DS   CL(MQCHARV_LENGTH)