Selectors
A message selector is a variable-length string used by an application to register its interest in only those messages that have properties that satisfy the Structured Query Language (SQL) query that the selection string represents.
Selection using the MQSUB and MQOPEN function calls
You use the SelectionString, which is a structure of type MQCHARV, to make selections using the MQSUB and MQOPEN calls.
The SelectionString structure is used to pass a variable-length selection string to the queue manager.
The CCSID associated with the selector string is set via the VSCCSID field of the MQCHARV structure. The value used must be a CCSID that is supported for selector strings. See Code page conversion for a list of supported code pages.
Specify a CCSID for which there is no IBM MQ supported Unicode conversion, results in an error of MQRC_SOURCE_CCSID_ERROR. This error is returned at the time that the selector is presented to the queue manager, that is, on the MQSUB, MQOPEN, or MQPUT1 call.
The default value for the VSCCSID field is MQCCSI_APPL, which indicates that the CCSID of the selection string is equal to the queue manager CCSID, or the client CCSID if connected through a client. The MQCCSI_APPL constant can however be overridden by an application redefining it before compiling.
If the MQCHARV selector represents a NULL string, no selection takes place for that message consumer and messages are delivered as if a selector had not been used.
The maximum length of a selection string is limited only by what can be described by the MQCHARV field VSLength.
The SelectionString is returned on the output from an MQSUB call using the MQSO_RESUME subscribe option, if you have provided a buffer and there is a positive buffer length in VSBufSize. If we do not provide a buffer, only the length of the selection string is returned in the VSLength field of the MQCHARV. If the buffer provided is smaller than the space required to return the field, only VSBufSize bytes are returned in the provided buffer.
An application cannot alter a selection string without first closing either the handle to the queue (for MQOPEN), or subscription (for MQSUB). A new selection string can then be specified on a subsequent MQOPEN or MQSUB call.
- MQOPEN
- Use MQCLOSE to close the opened handle, then specify a new selection string on a subsequent MQOPEN call.
- MQSUB
- Use MQCLOSE to close the returned subscription handle (hSub), then specify a new selection string on a subsequent MQSUB call.
Figure 1 shows the process of selection using the MQSUB call.
A selector can be passed in on the call to MQSUB by using the SelectionString field in the MQSD structure. The effect of passing in a selector on the MQSUB is that only those messages published to the topic being subscribed to, that match a supplied selection string, are made available on the destination queue.
Figure 2 shows the process of selection using the MQOPEN call.
A selector can be passed in on the call to MQOPEN by using the SelectionString field in the MQOD structure. The effect of passing in a selector on the MQOPEN call is that only those messages on the opened queue, that match a selector, are delivered to the message consumer.
The main use for the selector on the MQOPEN call is for the point-to-point case where an application can elect to receive only those messages on a queue that match a selector. The previous example shows a simple scenario where two messages are put to a queue opened by MQOPEN but only one is received by the application getting it, as it is the only one that matches a selector.
Note that subsequent MQGET calls result in MQRC_NO_MSG_AVAILABLE as no further messages exist on the queue that match the given selector.
Parent topic: Selecting messages from queuesRelated concepts