Message selector syntax

An IBM MQ message selector is a string with syntax that is based on a subset of the SQL92 conditional expression syntax.

The order in which a message selector is evaluated is from left to right within a precedence level. We can use parentheses to change this order. Predefined selector literals and operator names are written here in uppercase; however, they are not case-sensitive.

If the selector is provided via the API, IBM MQ verifies the syntactic correctness of a message selector at the time it is presented. If the syntax of the selection string is incorrect or a property name is not valid, and an extended message selection provider is not available, MQRC_SELECTION_NOT_AVAILABLE is returned to the application. If the syntax of the selection string is incorrect or a property name is not valid when a subscription is resumed, a MQRC_SELECTOR_SYNTAX_ERROR is returned to the application. If property name validation was disabled when the property was set (by setting MQCMHO_NONE instead of MQCMHO_VALIDATE) and an application subsequently puts a message with in invalid property name, this message is never selected.

No error is returned at the time the selector is presented if IBM MQ determines that an administratively defined subscription selector is using extended message syntax, as indicated by the DISPLAY SUB parameter SELTYPE having the value EXTENDED. In this case, the checking of the syntax of the selection string is deferred until publish time (see MQRC_SELECTION_NOT_AVAILABLE).

A selector can contain:

  • Literals:

    • String literals are enclosed in single quotation marks. Two consecutive single quotation marks represent a single quotation mark. Examples are 'literal' and 'literal''s'. Like Java string literals, these use the Unicode character encoding. We cannot use double quotation marks to enclose a string literal. Any sequence of bytes can be used between the single quotation marks.
    • A byte string is one or more pair of hexadecimal characters enclosed in double quotation marks and prefixed by 0x. Examples are 0x2F1C or 0XD43A. The length of a byte string must be at least one byte. If a selector byte string is matched to a message property of type MQTYPE_BYTE_STRING, no special action is taken on leading or trailing zero. The bytes are treated as another character. Endianness is also not considered. The length of both selector and property byte strings must be equal, and the sequence of bytes must be the same. Examples of byte string selections (assume myBytes = 0AFC23) which match are:

      • myBytes = 0x0AFC23 = TRUE

      The following string selections do not match:

      • myBytes = 0xAFC23 = MQRC_SELECTOR_SYNTAX_ERROR (because number of bytes is not multiple of two)
      • myBytes = 0x0AFC2300 = FALSE (because the trailing zero is significant in the comparison)
      • myBytes = 0x000AFC23 = FALSE (because leading zero is significant in the comparison)
      • myBytes = 0x23FC0A = FALSE (because endianness is not considered)

    • Hex numbers begin with a zero, followed by an uppercase or lowercase x. The remainder of the literal contains one or more valid hex characters. Examples are 0xA, 0xAF, 0X2020.
    • A leading zero followed by one or more digits in the range 0-7 is always interpreted as being the start of an octal number. We cannot represent a zero-prefixed decimal number like this, for example, 09 returns a syntax error because 9 is not a valid octal digit. Examples of octal numbers are 0177, 0713.
    • An exact numeric literal is a numeric value without a decimal point, such as 57, -957, and +62. An exact numeric literal can have a trailing uppercase or lowercase L; this does not affect how the number is stored or interpreted. IBM MQ supports exact numerals in the range -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.
    • An approximate numeric literal is a numeric value in scientific notation, such as 7E3 or -57.9E2, or a numeric value with a decimal, such as 7., -95.7, or +6.2. IBM MQ supports numbers in the range -1.797693134862315E+308 to 1.797693134862315E+308.

      The significand should follow an optional sign character ( + or -). The significand should be either an integer or a fraction. A fractional part of the significand need not have a leading digit.

      An uppercase or lowercase E indicates the start of an optional exponent. The exponent has a decimal radix and the number part of the exponent can be prefixed by an optional sign character.

      Approximate numeric literals can be terminated by an F or a D character (not case-sensitive). This syntax exists to support the cross-language method of tagging single or double precision numbers. These characters are optional and do not affect how an approximate numeric literal is stored or processed. These numbers are always stored and processed using double-precision.

    • The boolean literals TRUE and FALSE.

    Note: Non-finite IEEE-754 representations such as NaN, +Infinity, -Infinity are not supported in selection strings. It is therefore not possible to use these values as operands in an expression. Negative zero is treated the same as positive zero for mathematical operations.

  • Identifiers:

    An identifier is a variable-length character sequence that must begin with a valid identifier start character, followed by zero or more valid identifier part characters. The rules for identifier names are the same as those for message property names, see Property names and Property name restrictions for more information.

    Note: Selection can be performed on the message payload only if an extended message selection provider is available.

    Identifiers are either header field references or property references. The type of a property value in a message selector must correspond to the type used to set the property, although numeric promotion is performed where possible. If a type mismatch occurs then the result of the expression is FALSE. If a property that does not exist in a message is referenced, its value is NULL.

    Type conversions that apply to the get methods for properties do not apply when a property is used in a message selector expression. For example, if you set a property as a string value and then use a selector to query it as a numeric value, the expression returns FALSE.

    JMS field and property names that map to property names or MQMD field names are also valid identifiers in a selection string. IBM MQ maps the recognized JMS field and property names to the message property values. See Message selectors in JMS for more information. As an example, the selection string JMSPriority >= selects on the Pri property found in the jms folder of the current message.

  • Overflow/underflow: For both decimal and approximate numeric numbers, the following conditions are undefined:

    • Specify a number that is out of the defined range
    • Specify an arithmetic expression which would cause overflow or underflow

    No checks are performed for these conditions.

  • White space: Defined as a space, form-feed, newline, carriage return, horizontal tab, or vertical tab. The following Unicode characters are recognized as white space:

    • \u0009 to \u000D
    • \u0020
    • \u001C
    • \u001D
    • \u001E
    • \u001F
    • \u1680
    • \u180E
    • \u2000 to \u200A
    • \u2028
    • \u2029
    • \u202F
    • \u205F
    • \u3000

  • Expressions:

    • A selector is a conditional expression. A selector that evaluates to true matches; a selector that evaluates to false or unknown does not match.
    • Arithmetic expressions are composed of themselves, arithmetic operations, identifiers (identifier value is treated as a numeric literal), and numeric literals.
    • Conditional expressions are composed of themselves, comparison operations, and logical operations.

  • Standard bracketing (), to set the order in which expressions are evaluated, is supported.
  • Logical operators in precedence order: NOT, AND, OR.
  • Comparison operators: =, >, >=, <, <=, <> (not equal).

    • Two byte strings are equal only if the strings are of the same length and the sequence of bytes is equal.
    • Only values of the same type can be compared. One exception is that it is valid to compare exact numeric values and approximate numeric values, (the type conversion required is defined by the rules of Java numeric promotion). If there is an attempt to compare different types, the selector is always false.
    • String and boolean comparison is restricted to = and <>. Two strings are equal only if they contain the same sequence of characters.

  • Arithmetic operators in precedence order:

    • +, - unary.
    • * multiplication, and / division.
    • + addition, and - subtraction.
    • Arithmetic operations on a NULL value are not supported. If they are attempted, the complete selector is always false.
    • Arithmetic operations must use Java numeric promotion.

  • arithmetic-expr1 [ NOT ] BETWEEN arithmetic-expr2 and arithmetic-expr3 comparison operator:

    • Age BETWEEN 15 and 19 is equivalent to age>= 15 AND age <= 19.
    • Age NOT BETWEEN 15 and 19 is equivalent to age < 15 OR age > 19.
    • If any of the expressions of a BETWEEN operation are NULL, the value of the operation is false. If any of the expressions of a NOT BETWEEN operation are NULL, the value of the operation is true.

  • identifier [NOT] IN (string-literal1, string-literal2,...) comparison operator where identifier has a String or NULL value.

    • Country IN ('UK', 'US', 'France') is true for 'UK' and false for 'Peru'. It is equivalent to the expression (Country = 'UK') OR (Country = 'US') OR (Country = 'France').
    • Country NOT IN ('UK', 'US', 'France') is false for 'UK' and true for 'Peru'. It is equivalent to the expression NOT ((Country = 'UK') OR (Country = 'US') OR (Country = 'France')).
    • If the identifier of an IN or NOT IN operation is NULL, the value of the operation is unknown.

  • identifier [NOT] LIKE pattern-value [ESCAPE escape-character ] comparison operator, where identifier has a string value. pattern-value is a string literal, where _ stands for any single character and % stands for any sequence of characters (including the empty sequence). All other characters stand for themselves. The optional escape-character is a single character string literal that is used to escape the special meaning of the _ and % in pattern-value. The LIKE operator must be used only to compare two string values.

    • phone LIKE '12%3' is true for 123 and 12993 and false for 1234.
    • word LIKE 'l_se' is true for lose and false for loose.
    • underscored LIKE '\_%' ESCAPE '\' is true for _foo and false for bar.
    • phone NOT LIKE '12%3' is false for 123 and 12993 and true for 1234.
    • If the identifier of a LIKE or NOT LIKE operation is NULL, the value of the operation is unknown.

    Note: The LIKE operator must be used to compare two string values. The value of Root.MQMD.CorrelId is a 24-byte byte array, not a character string. The selector string Root.MQMD.CorrelId LIKE 'ABC%' is accepted by the parser as syntactically valid, but it is evaluated to false. When we are comparing a byte array with a character string, LIKE therefore cannot be used.

  • identifier IS NULL comparison operator tests for a NULL header field value, or a missing property value.
  • identifier IS NOT NULL comparison operator tests for the existence of a non-null header field value or a property value.
  • Null values The evaluation of selector expressions that contain NULL values is defined by SQL 92 NULL semantics, in summary:

    • SQL treats a NULL value as unknown.
    • Comparison or arithmetic with an unknown value always yields an unknown value.
    • The IS NULL and IS NOT NULL operators convert an unknown value into TRUE and FALSE values.

    The boolean operators use three-valued logic ( T=TRUE, F=FALSE, U=UNKNOWN)

    Operator A Operator B Outcome (A AND B)
    T F F
    T U U
    T T T
    F T F
    F U F
    F F F
    U T U
    U U U
    U F F

    Operator A Operator B Outcome (A OR B)
    T F T
    T U T
    T T T
    F T T
    F U U
    F F F
    U T T
    U U U
    U F U

    Operator A Outcome ( NOT A)
    T F
    F T
    U U

The following message selector selects messages with a message type of car, color of blue, and weight greater than 2500 lbs: 

"JMSType = 'car' AND color = 'blue' AND weight > 2500"

Although SQL supports fixed decimal comparison and arithmetic, message selectors do not. This is why exact numeric literals are restricted to those without a decimal. It is also why there are numerics with a decimal as an alternative representation for an approximate numeric value.

SQL comments are not supported.

Parent topic: Selecting messages from queues


Related concepts


Related information