Event Monitoring: MQCFST - String parameter

MQCFST - String parameter

The MQCFST structure describes a string parameter in an event message.
The structure ends with a variable-length character string; see the String field below for further details.

Type

Description: Indicates that the structure type is MQCFST and describes a string parameter.

Datatype: MQLONG.

Initial value: MQCFT_STRING.

Valid value:

MQCFT_STRING

Structure defining a string.

StrucLength

Description: Length in bytes of the MQCFST structure, including the string at the end of the structure (the String field). The length must be a multiple of four, and must be sufficient to contain the string; any bytes between the end of the string and the length defined by the StrucLength field are not significant.

Datatype: MQLONG.

Initial value:

MQCFST_STRUC_LENGTH_FIXED.

Length of the fixed part of the MQCFST structure, excluding the String field.

Parameter

Description: Identifies the parameter whose value is contained in the structure.

Datatype: MQLONG.

Initial value: 0.

Valid values: Dependent on the event message.

CodedCharSetId

Description: Coded character set identifier of the data in the String field.

Datatype: MQLONG.

Initial value:

MQCCSI_DEFAULT.

Default coded character set identifier, indicating that character data is in the character set defined by the CodedCharSetId field in the MQ header structure that precedes the MQCFH structure, or by the CodedCharSetId field in the MQMD if the MQCFH structure is at the start of the message.

Valid values:

If all of the strings in an event message have the same coded character-set identifier, the CodedCharSetId field in the message descriptor MQMD or in the MQ header structure preceding MQCFH should be set to that identifier when the message is put, and the CodedCharSetId fields in the MQCFST structure within the message should be set to MQCCSI_DEFAULT.
If some of the strings in the message have different character-set identifiers, the CodedCharSetId field in MQMD or in the MQ header structure preceding MQCFH should be set to MQCCSI_EMBEDDED when the message is put, and the CodedCharSetId fields in the MQCFST structure within the message should be set to the identifiers that apply.

Do not specify MQCCSI_EMBEDDED in MQMD or in the MQ header structure preceding MQCFH when the message is put, with MQCCSI_DEFAULT in the MQCFST structure within the message, as this will prevent conversion of the message.

StringLength

Description: Length in bytes of the data in the String field; it must be zero or greater. This length need not be a multiple of four.

Datatype: MQLONG.

Initial value: 0.

String

Description: The value of the parameter identified by the Parameter field.
In MQFMT_EVENT messages, trailing blanks are omitted from string parameters (that is, the string may be shorter than the defined length of the parameter). StringLength gives the length of the string actually present in the message.

Datatype: MQCHAR×StringLength.

Initial value: In C, the initial value of this field is the null string.

Valid value: The string can contain any characters that are in the character set defined by CodedCharSetId, and that are valid for the parameter identified by Parameter.

Language
considerations: The way that this field is declared depends on the programming language:

For the C programming language, the field is declared as an array with one element. Storage for the structure should be allocated dynamically, and pointers used to address the fields within it.
For the COBOL, PL/I, System/390 assembler, and Visual Basic programming languages, the field is omitted from the structure declaration. When an instance of the structure is declared, the user should include MQCFST in a larger structure, and declare additional fields following MQCFST, to represent the String field as required.

Special note: A null character in the string is treated as normal data, and does not act as a delimiter for the string. This means that when a receiving application reads an MQFMT_EVENT message, the receiving application receives all of the data specified by the sending application. The data may, of course, have been converted between character sets (for example, by the receiving application specifying the MQGMO_CONVERT option on the MQGET call).

C language declaration (MQCFST)
typedef struct tagMQCFST {
  MQLONG  Type;            /* Structure type */
  MQLONG  StrucLength;     /* Structure length */
  MQLONG  Parameter;       /* Parameter identifier */
  MQLONG  CodedCharSetId;  /* Coded character set identifier */
  MQLONG  StringLength;    /* Length of string */
  MQCHAR  String[1];       /* String value - first
                              character */
 } MQCFST;
In the C programming language, the macro variable MQCFST_DEFAULT contains the initial values of the MQCFST structure. It can be used in the following way to provide initial values for the fields in the structure:
struct {
  MQCFST Hdr;
  MQCHAR Data[99];
} MyCFST = {MQCFST_DEFAULT};
COBOL language declaration (MQCFST)
**   MQCFST structure
  10 MQCFST.
**    Structure type
   15 MQCFST-TYPE           PIC S9(9) BINARY.
**    Structure length
   15 MQCFST-STRUCLENGTH    PIC S9(9) BINARY.
**    Parameter identifier
   15 MQCFST-PARAMETER      PIC S9(9) BINARY.
**    Coded character set identifier
   15 MQCFST-CODEDCHARSETID PIC S9(9) BINARY.
**    Length of string
   15 MQCFST-STRINGLENGTH   PIC S9(9) BINARY.
PL/I language declaration (MQCFST)
dcl
 1 MQCFST based,
  3 Type           fixed bin(31), /* Structure type */
  3 StrucLength    fixed bin(31), /* Structure length */
  3 Parameter      fixed bin(31), /* Parameter identifier */
  3 CodedCharSetId fixed bin(31), /* Coded character set identifier */
  3 StringLength   fixed bin(31); /* Length of string */
RPG/ILE declaration (MQCFST) (OS/400 only)
     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D* MQCFST Structure
     D*
     D* Structure type
     D  STTYP                  1      4I 0
     D* Structure length
     D  STLEN                  5      8I 0
     D* Parameter identifier
     D  STPRM                  9     12I 0
     D* Coded character set identifier
     D  STCSI                 13     16I 0
     D* Length of string
     D  STSTL                 17     20I 0
System/390 assembler-language declaration (MQCFST)
MQCFST                         DSECT
MQCFST_TYPE                    DS   F        Structure type
MQCFST_STRUCLENGTH             DS   F        Structure length
MQCFST_PARAMETER               DS   F        Parameter identifier
MQCFST_CODEDCHARSETID          DS   F        Coded character set
*                                            identifier
MQCFST_STRINGLENGTH            DS   F        Length of string
MQCFST_LENGTH                  EQU  *-MQCFST Length of structure
                               ORG  MQCFST
MQCFST_AREA                    DS   CL(MQCFST_LENGTH)
Visual Basic language declaration (MQCFST)
Type MQCFST
  Type As Long            ' Structure type
  StrucLength As Long     ' Structure length
  Parameter As Long       ' Parameter identifier
  CodedCharSetId As Long  ' Coded character set identifier
  StringLength As Long    ' Length of string
End Type
 
Global MQCFST_DEFAULT As MQCFST

Description:	Indicates that the structure type is MQCFST and describes a string parameter.
Datatype:	MQLONG.
Initial value:	MQCFT_STRING.
Valid value:	MQCFT_STRING Structure defining a string.

Description:	Length in bytes of the MQCFST structure, including the string at the end of the structure (the String field). The length must be a multiple of four, and must be sufficient to contain the string; any bytes between the end of the string and the length defined by the StrucLength field are not significant.
Datatype:	MQLONG.
Initial value:	MQCFST_STRUC_LENGTH_FIXED. Length of the fixed part of the MQCFST structure, excluding the String field.

Description:	Identifies the parameter whose value is contained in the structure.
Datatype:	MQLONG.
Initial value:	0.
Valid values:	Dependent on the event message.

Description:	Coded character set identifier of the data in the String field.
Datatype:	MQLONG.
Initial value:	MQCCSI_DEFAULT. Default coded character set identifier, indicating that character data is in the character set defined by the CodedCharSetId field in the MQ header structure that precedes the MQCFH structure, or by the CodedCharSetId field in the MQMD if the MQCFH structure is at the start of the message.
Valid values:	If all of the strings in an event message have the same coded character-set identifier, the CodedCharSetId field in the message descriptor MQMD or in the MQ header structure preceding MQCFH should be set to that identifier when the message is put, and the CodedCharSetId fields in the MQCFST structure within the message should be set to MQCCSI_DEFAULT. If some of the strings in the message have different character-set identifiers, the CodedCharSetId field in MQMD or in the MQ header structure preceding MQCFH should be set to MQCCSI_EMBEDDED when the message is put, and the CodedCharSetId fields in the MQCFST structure within the message should be set to the identifiers that apply. Do not specify MQCCSI_EMBEDDED in MQMD or in the MQ header structure preceding MQCFH when the message is put, with MQCCSI_DEFAULT in the MQCFST structure within the message, as this will prevent conversion of the message.

Description:	Length in bytes of the data in the String field; it must be zero or greater. This length need not be a multiple of four.
Datatype:	MQLONG.
Initial value:	0.

Description:	The value of the parameter identified by the Parameter field. In MQFMT_EVENT messages, trailing blanks are omitted from string parameters (that is, the string may be shorter than the defined length of the parameter). StringLength gives the length of the string actually present in the message.
Datatype:	MQCHAR×StringLength.
Initial value:	In C, the initial value of this field is the null string.
Valid value:	The string can contain any characters that are in the character set defined by CodedCharSetId, and that are valid for the parameter identified by Parameter.
Language considerations:	The way that this field is declared depends on the programming language: For the C programming language, the field is declared as an array with one element. Storage for the structure should be allocated dynamically, and pointers used to address the fields within it. For the COBOL, PL/I, System/390 assembler, and Visual Basic programming languages, the field is omitted from the structure declaration. When an instance of the structure is declared, the user should include MQCFST in a larger structure, and declare additional fields following MQCFST, to represent the String field as required.
Special note:	A null character in the string is treated as normal data, and does not act as a delimiter for the string. This means that when a receiving application reads an MQFMT_EVENT message, the receiving application receives all of the data specified by the sending application. The data may, of course, have been converted between character sets (for example, by the receiving application specifying the MQGMO_CONVERT option on the MQGET call).