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 we 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

      An item in a list of values. The value can be explicit or generic. If it is explicit, use MQCFOP_CONTAINS or MQCFOP_EXCLUDES as the operator. For example, if the value DEF is specified with the operator MQCFOP_CONTAINS, all items where one of the attribute values is DEF are listed. If it is generic, use MQCFOP_CONTAINS_GEN or MQCFOP_EXCLUDES_GEN as the operator. If ABC* is specified with the operator MQCFOP_CONTAINS_GEN, all items where one of the attribute values begins with ABC are listed.

    Note:

    1. 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.
    2. 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.
    3. 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.


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*
Parent topic: Structures for commands and responses