MQCFSF - PCF string filter parameter
The MQCFSF structure describes a string filter parameter. The format name in the message descriptor is MQFMT_ADMIN.
The MQCFSF structure is used in Inquire commands to provide a filter condition. This filter condition is used to filter the results of the Inquire command and return to the user only those objects that satisfy the filter condition.
On z/OS®, a single filter parameter only is allowed. If multiple MQCFIF, MQCFSF and MQCFBF, or MQCFBF parameters are specified, the PCF command fails with error MQRCCF_TOO_MANY_FILTERS (MQRCCF 3248).
The results of filtering character strings on EBCDIC-based systems might be different from those results achieved on ASCII-based systems. This difference is because comparison of character strings is based on the collating sequence of the internal built-in values representing the characters.
When an MQCFSF structure is present, the Version field in the MQCFH structure at the start of the PCF must be MQCFH_VERSION_3 or higher.
Fields for MQCFSF
- Type (MQLONG)
- Structure type.
This indicates that the structure is an MQCFSF structure describing a string filter parameter. The value must be:
- MQCFT_STRING_FILTER
- Structure defining a string filter.
- StrucLength (MQLONG)
- Structure length.
This is the length in bytes of the MQCFSF structure. The value must be:
- MQCFSF_STRUC_LENGTH
- MQCFSF_STRUC_LENGTH is the length, in bytes, of the MQCFSF structure, including the string at the end of the structure (the FilterValue field). The length must be a multiple of 4, and must be sufficient to contain the string. Bytes between the end of the string 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 FilterValue field:
- MQCFSF_STRUC_LENGTH_FIXED
- Length of fixed part of command format filter string-parameter structure.
- Parameter (MQLONG)
- Parameter identifier.
This identifies the parameter that is to be filtered on. The value of this identifier depends on the parameter to be filtered on. Any of the parameters which can be used in the Inquire command can be used in this field.
The parameter is from the following groups of parameters:- MQCA_*
- MQCACF_*
- MQCAMO_*
- MQCACH_*
- Operator (MQLONG)
- Operator identifier.
This identifies the operator that is being used to evaluate whether the parameter satisfies the filter-value.
Possible values are:
- MQCFOP_GREATER
- Greater than
- MQCFOP_LESS
- Less than
- MQCFOP_EQUAL
- Equal to
- MQCFOP_NOT_EQUAL
- Not equal to
- MQCFOP_NOT_LESS
- Greater than or equal to
- MQCFOP_NOT_GREATER
- Less than or equal to
- MQCFOP_LIKE
- Matches a generic string
- MQCFOP_NOT_LIKE
- Does not match a generic string
- MQCFOP_CONTAINS
- Contains a specified string. Use MQCFOP_CONTAINS when filtering on lists of strings.
- MQCFOP_EXCLUDES
- Does not contain a specified string. Use MQCFOP_EXCLUDES when filtering on lists of strings.
- MQCFOP_CONTAINS_GEN
- Contains an item which matches a generic string. Use MQCFOP_CONTAINS_GEN when filtering on lists of strings.
- MQCFOP_EXCLUDES_GEN
- Does not contain any item which matches a generic string. Use MQCFOP_EXCLUDES_GEN when filtering on lists of strings.
See the FilterValue description for details telling you which operators can be used in which circumstances.
- CodedCharSetId (MQLONG)
- Coded character set identifier.
This specifies the coded character set identifier of the data in the FilterValue 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 the CodedCharSetId field in the MQMD if the MQCFH structure is at the start of the message.
- FilterValueLength (MQLONG)
- Length of filter-value string.
This is the length, in bytes, of the data in the FilterValue field. This parameter must be zero or greater, and does not need to be a multiple of 4.
Note: On z/OS there is a 256 character limit for the filter-value of the MQSC WHERE clause. This limit is not in place for other platforms.
- FilterValue (MQCHAR x FilterValueLength)
- Filter value.
This specifies the filter-value that must be satisfied. Depending on the parameter, the value and the permitted operators can be:
- An explicit string value.
We can only use the following operators:
- MQCFOP_GREATER
- MQCFOP_LESS
- MQCFOP_EQUAL
- MQCFOP_NOT_EQUAL
- MQCFOP_NOT_GREATER
- MQCFOP_NOT_LESS
- A generic string value. This field is a character string with an asterisk at the end, for example ABC*. The operator must be either MQCFOP_LIKE or MQCFOP_NOT_LIKE. The characters must be valid for the attribute you are testing. If the operator is MQCFOP_LIKE, all items where the attribute value begins with the string (ABC in the example) are listed. If the operator is MQCFOP_NOT_LIKE, all items where the attribute value does not begin with the string are listed.
- If the parameter takes a list of string values, the operator can be:
- MQCFOP_CONTAINS
- MQCFOP_EXCLUDES
- MQCFOP_CONTAINS_GEN
- MQCFOP_EXCLUDES_GEN
- If the specified string is shorter than the standard length of the parameter in MQFMT_ADMIN command messages, the omitted characters are assumed to be blanks. If the specified string is longer than the standard length, it is an error.
- When the queue manager reads an MQCFSF 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.
- On z/OS there is a 256 character limit for the filter-value of the MQSC WHERE clause. This limit is not in place for other platforms.
The filter value must be a valid value for the parameter being tested.
- An explicit string value.
We can only use the following operators:
C language declaration
typedef struct tagMQCFSF { MQLONG Type; /* Structure type */ MQLONG StrucLength; /* Structure length */ MQLONG Parameter; /* Parameter identifier */ MQLONG Operator; /* Operator identifier */ MQLONG CodedCharSetId; /* Coded character set identifier */ MQLONG FilterValueLength /* Filtervalue length */ MQCHAR[1] FilterValue; /* Filter value */ } MQCFSF;
COBOL language declaration
** MQCFSF structure 10 MQCFSF. ** Structure type 15 MQCFSF-TYPE PIC S9(9) BINARY. ** Structure length 15 MQCFSF-STRUCLENGTH PIC S9(9) BINARY. ** Parameter identifier 15 MQCFSF-PARAMETER PIC S9(9) BINARY. ** Operator identifier 15 MQCFSF-OPERATOR PIC S9(9) BINARY. ** Coded character set identifier 15 MQCFSF-CODEDCHARSETID PIC S9(9) BINARY. ** Filter value length 15 MQCFSF-FILTERVALUE PIC S9(9) BINARY.
PL/I language declaration ( z/OS only)
dcl 1 MQCFSF based, 3 Type fixed bin(31), /* Structure type */ 3 StrucLength fixed bin(31), /* Structure length */ 3 Parameter fixed bin(31), /* Parameter identifier */ 3 Operator fixed bin(31) /* Operator identifier */ 3 CodedCharSetId fixed bin(31) /* Coded character set identifier */ 3 FilterValueLength fixed bin(31); /* Filter value length */
System/390 assembler-language declaration ( z/OS only)
MQCFSF DSECT MQCFSF_TYPE DS F Structure type MQCFSF_STRUCLENGTH DS F Structure length MQCFSF_PARAMETER DS F Parameter identifier MQCFSF_OPERATOR DS F Operator identifier MQCFSF_CODEDCHARSETID DS F Coded character set identifier MQCFSF_FILTERVALUELENGTH DS F Filter value length MQCFSF_LENGTH EQU *-MQCFSF Length of structure ORG MQCFSF MQCFSF_AREA DS CL(MQCFSF_LENGTH)
Visual Basic language declaration ( Windows only)
Type MQCFSF Type As Long ' Structure type StrucLength As Long ' Structure length Parameter As Long ' Parameter identifier Operator As Long ' Operator identifier CodedCharSetId As Long ' Coded character set identifier FilterValueLength As Long ' Operator identifier FilterValue As String*1 ' Condition value -- first character End Type Global MQCFSF_DEFAULT As MQCFSF
RPG language declaration ( IBM® i only)
D* MQCFSF Structure D* D* Structure type D FISTYP 1 4I 0 INZ(3) D* Structure length D FSFLEN 5 8I 0 INZ(16) D* Parameter identifier D FSFPRM 9 12I 0 INZ(0) D* Reserved field D FSFRSV 13 16I 0 INZ(0) D* Parameter value D FSFVAL 17 16 D* Structure type D FSFTYP 17 20I 0 D* Structure length D FSFLEN 21 24I 0 D* Parameter value D FSFPRM 25 28I 0 D* Operator identifier D FSFOP 29 32I 0 D* Coded character set identifier D FSFCSI 33 36I 0 D* Length of condition D FSFFVL 37 40 0 D* Condition value -- first character D FSFFV 41 41 D*