MQCFSL - PCF string list parameter
The MQCFSL structure describes a string-list parameter in a message which is a command or a response to a command. In either case, the format name in the message descriptor is MQFMT_ADMIN.
The MQCFSL 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, Count, StringLength, and Strings fields to the values appropriate to the data.
The structure ends with a variable-length array of character strings; see the Strings field section for further details.
See Usage notes for further information about how to use the structure.
Fields for MQCFSL
- Type (MQLONG)
- Structure type.
This indicates that the structure is an MQCFSL structure describing a string-list parameter. The value must be:
- MQCFT_STRING_LIST
- Structure defining a string list.
- StrucLength (MQLONG)
- Structure length.
This is the length in bytes of the MQCFSL structure, including the data at the end of the structure (the Strings field). The length must be a multiple of four, and must be sufficient to contain all the strings; any bytes between the end of the strings and the length defined by the StrucLength field are not significant.
The following constant gives the length of the fixed part of the structure, that is the length excluding the Strings field:- MQCFSL_STRUC_LENGTH_FIXED
- Length of fixed part of command format string-list parameter structure.
- Parameter (MQLONG)
- Parameter identifier.
This identifies the parameter with values that are 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 Strings field. The following special value can be used:
- Count (MQLONG)
- Count of parameter values.
This is the number of strings present in the Strings field; it must be zero or greater.
- StringLength (MQLONG)
- Length of one string.
This is the length in bytes of one parameter value, that is the length of one string in the Strings field; all the strings are this length. The length must be zero or greater, and need not be a multiple of four.
- Strings (MQCHAR x StringLength x Count)
- String values.
This is a set of string values for the parameter identified by the Parameter field. The number of strings is given by the Count field, and the length of each string is given by the StringLength field. The strings are concatenated together, with no bytes skipped between adjacent strings. The total length of the strings is the length of one string multiplied by the number of strings present (that is, StringLength x Count).
- 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 might be shorter than the standard length of the parameter).
In all cases, StringLength gives the length of the string present in the message.
The strings can contain any characters that are in the character set defined by CodedCharSetId, and that are valid for the parameter identified by Parameter.
Note: When the queue manager reads an MQCFSL structure in an MQFMT_ADMIN message from the command input queue, the queue manager processes each string in the list as though it had been specified on an MQI call. This processing means that within each 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 a 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, RPG, and System/390 assembler programming languages, the field is omitted from the structure declaration. When an instance of the structure is declared, we must include MQCFSL in a larger structure, and declare additional fields following MQCFSL, to represent the Strings field as required.
C language declaration
typedef struct tagMQCFSL {
MQLONG Type; /* Structure type */
MQLONG StrucLength; /* Structure length */
MQLONG Parameter; /* Parameter identifier */
MQLONG CodedCharSetId; /* Coded character set identifier */
MQLONG Count; /* Count of parameter values */
MQLONG StringLength; /* Length of one string */
MQCHAR Strings[1]; /* String values - first
character */
} MQCFSL;
COBOL language declaration
** MQCFSL structure 10 MQCFSL. ** Structure type 15 MQCFSL-TYPE PIC S9(9) BINARY. ** Structure length 15 MQCFSL-STRUCLENGTH PIC S9(9) BINARY. ** Parameter identifier 15 MQCFSL-PARAMETER PIC S9(9) BINARY. ** Coded character set identifier 15 MQCFSL-CODEDCHARSETID PIC S9(9) BINARY. ** Count of parameter values 15 MQCFSL-COUNT PIC S9(9) BINARY. ** Length of one string 15 MQCFSL-STRINGLENGTH PIC S9(9) BINARY.
PL/I language declaration ( z/OS only)
dcl 1 MQCFSL 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 Count fixed bin(31), /* Count of parameter values */ 3 StringLength fixed bin(31); /* Length of one string */
System/390 assembler-language declaration ( z/OS only)
MQCFSL DSECT
MQCFSL_TYPE DS F Structure type
MQCFSL_STRUCLENGTH DS F Structure length
MQCFSL_PARAMETER DS F Parameter identifier
MQCFSL_CODEDCHARSETID DS F Coded character set
* identifier
MQCFSL_COUNT DS F Count of parameter values
MQCFSL_STRINGLENGTH DS F Length of one string
MQCFSL_LENGTH EQU *-MQCFSL Length of structure
ORG MQCFSL
MQCFSL_AREA DS CL(MQCFSL_LENGTH)
Visual Basic language declaration ( Windows only)
Type MQCFSL Type As Long ' Structure type StrucLength As Long ' Structure length Parameter As Long ' Parameter identifier CodedCharSetId As Long ' Coded character set identifier Count As Long ' Count of parameter values StringLength As Long ' Length of one string End Type Global MQCFSL_DEFAULT As MQCFSL
RPG language declaration ( IBM i only)
D* MQCFSL Structure D* D* Structure type D SLTYP 1 4I 0 INZ(6) D* Structure length D SLLEN 5 8I 0 INZ(24 D* Parameter identifier D SLPRM 9 12I 0 INZ(0) D* Coded character set identifier D SLCSI 13 16I 0 INZ(0) D* Count of parameter values D SLCNT 17 20I 0 INZ(0) D* Length of one string D SLSTL 21 24I 0 INZ(0)Parent topic: Structures for commands and responses