MQCFST - PCF string parameter
The MQCFST PCF structure describes a string parameter in a message that is a command or a response to a command. In either case, the format name in the message descriptor is MQFMT_ADMIN.
The MQCFST structure can also be used for user-defined message data. In this case the message descriptor Format
field is MQFMT_PCF (see Message descriptor for a PCF command ). Also in this case, not all the fields in the structure are meaningful. The supplied initial values can be used for most fields, but the application must set the StrucLength
, StringLength
, and String
fields to the values appropriate to the data.
The structure ends with a variable-length character string; see the
String
field section for further details.
See PCF structures: Usage notes for further information about how to use the structure.
Fields for MQCFST
- Type (MQLONG)
- Structure type.
This indicates that the structure is an MQCFST structure describing a string parameter. The value must be:
- MQCFT_STRING
- Structure defining a string.
- StrucLength (MQLONG)
- Structure length.
This is the 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 theStrucLength
field are not significant.The following constant gives the length of the fixed part of the structure, that is the length excluding theString
field:- MQCFST_STRUC_LENGTH_FIXED
- Length of fixed part of command format string-parameter structure.
- Parameter (MQLONG)
- Parameter identifier.
This identifies the parameter with a value that is contained in the structure. The values that can occur in this field depend on the value of the
Command
field in the MQCFH structure; see MQCFH - PCF header for details.The parameter is from the following groups of parameters:- MQCA_*
- MQCACF_*
- MQCAMO_*
- MQCACH_*
- CodedCharSetId (MQLONG)
- Coded character set identifier.
This specifies the coded character set identifier of the data in the
String
field. The following special value can be used:- MQCCSI_DEFAULT
- Default character set identifier.
The string data is in the character set defined by the
CodedCharSetId
field in the MQ header structure that precedes the MQCFH structure, or by theCodedCharSetId
field in the MQMD if the MQCFH structure is at the start of the message.
- StringLength (MQLONG)
- Length of string.
This is the length in bytes of the data in the
String
field; it must be zero or greater. This length does not need to be a multiple of four. - String (MQCHAR x StringLength)
- String value.
This is the value of the parameter identified by the
Parameter
field:- In MQFMT_ADMIN command messages, if the specified string is shorter than the standard length of the parameter, the omitted characters are assumed to be blanks. If the specified string is longer than the standard length, it is an error.
- In MQFMT_ADMIN response messages, string parameters might be returned padded with blanks to the standard length of the parameter.
- In MQFMT_EVENT messages, trailing blanks might be omitted from string parameters (that is, the string can be shorter than the standard length of the parameter).
StringLength
depends on whether, when the specified string is shorter than the standard length, padding blanks have been added to the string. If so, the value ofStringLength
is the sum of the actual length of the string plus the padded blanks.The string can contain any characters that are in the character set defined by
CodedCharSetId
, and that are valid for the parameter identified byParameter
.Note: When the queue manager reads an MQCFST structure in an MQFMT_ADMIN message from the command input queue, the queue manager processes the string as though it had been specified on an MQI call. This processing means that within the string, the first null and the characters following it (up to the end of the string) are treated as blanks.In responses and all other cases, a null character in the string is treated as normal data, and does not act as a delimiter for the string. This treatment means that when a receiving application reads a MQFMT_PCF, MQFMT_EVENT, or MQFMT_ADMIN message, the receiving application receives all the data specified by the sending application.
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 must be allocated dynamically, and pointers used to address the fields within it.
- For the COBOL, PL/I, and System/390 assembler programming languages, the field is omitted from the structure declaration. When an instance of the structure is declared, the user must include MQCFST in a larger structure, and declare an additional field or additional fields following MQCFST, to represent the
String
field as required.
C language declaration
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;
COBOL language declaration
** 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 ( z/OS® only)
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 */
System/390 assembler-language declaration ( z/OS only)
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 ( Windows only)
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
RPG language declaration ( IBM® i only)
D* MQCFST Structure
D*
D* Structure type
D STTYP 1 4I 0 INZ(4)
D* Structure length
D STLEN 5 8I 0 INZ(20)
D* Parameter identifier
D STPRM 9 12I 0 INZ(0)
D* Coded character set identifier
D STCSI 13 16I 0 INZ(0)
D* Length of string
D STSTL 17 20I 0 INZ(0)
D*