MQGET options and read ahead

Not all MQGET options are supported when read ahead is enabled; some options are required to be consistent between MQGET calls.

When you call MQOPEN with MQOO_READ_AHEAD, the IBM® MQ client only enables read-ahead if certain conditions are met. These conditions include:
  • Both the client and remote queue manager must be at WebSphere® MQ Version 7 or later.
  • The client application must be compiled and linked against the threaded IBM MQ MQI client libraries.
  • The client channel must be using TCP/IP protocol
  • The channel must have a non-zero SharingConversations (SHARECNV) setting in both the client and server channel definitions.
The following table indicates which options are supported for use with read ahead and whether they can be altered between MQGET calls.
Table 1. MQGET options and read ahead
  Permitted when read ahead is enabled and can be altered between MQGET calls 5 Permitted when read ahead is enabled but cannot be altered between MQGET calls 1 MQGET Options that are not permitted when read ahead is enabled 2
MQGET MQMD values
MsgId 3
CorrelId 3
Encoding
CodedCharSetId
  
MQGET MQGMO Options
  • MQGMO_NO_WAIT
  • MQGMO_BROWSE_MESSAGE _UNDER_CURSOR
  • MQGMO_BROWSE_FIRST
  • MQGMO_BROWSE_NEXT
  • MQGMO_FAIL_IF_QUIESCING
  • MQGMO_SYNCPOINT_IF _PERSISTENT
  • MQGMO_NO_SYNCPOINT
  • MQGMO_ACCEPT_TRUNCATED _MSG
  • MQGMO_CONVERT
  • MQGMO_SET_SIGNAL
  • MQGMO_SYNCPOINT
  • MQGMO_MARK_SKIP _BACKOUT
  • MQGMO_MSG_UNDER _CURSOR 4
  • MQGMO_LOCK
  • MQGMO_UNLOCK
  • MQGMO_LOGICAL_ORDER
  • MQGMO_COMPLETE_MSG
  • MQGMO_ALL_MSGS_AVAILABLE
  • MQGMO_ALL_SEGMENTS_ AVAILABLE
Notes:
  1. If these options are altered between MQGET calls, an MQRC_OPTIONS_CHANGED reason code is returned.
  2. If these options are specified on the first MQGET call then read ahead is disabled. If these options are specified on a subsequent MQGET call a reason code MQRC_OPTIONS_ERROR is returned.
  3. If a client application alters MsgId and CorrelId values between MQGET calls, messages with the previous values might already have been sent to the client and will remain in the client read ahead buffer until consumed (or automatically purged).
  4. MQGMO_MSG_UNDER_CURSOR is not possible with read ahead. Read ahead is disabled when both MQOO_BROWSE and one of the MQOO_INPUT_SHARED or MQOO_INPUT_EXCLUSIVE options are specified when opening the queue.
  5. When read ahead is enabled, the first MQGET determines whether messages are to be browsed or got from a queue. If the client application then uses MQGET with changed options, such as attempting to browse following an initial get, or attempting to get following an initial browse, an MQRC_OPTIONS_CHANGED reason code is returned.

If a client alters its selection criteria between MQGET calls, messages being stored in the read ahead buffer that match the initial selection criteria are not consumed by the client application, and remain stranded in the client read ahead buffer. In situations where the client read ahead buffer contains many stranded messages, the benefits associated with read ahead are lost and a separate request to the server is required for each message consumed. To determine whether read ahead is being used efficiently you can use the connection status parameter, READA.

Read ahead can be inhibited when requested by an application due to incompatible options specified on the first MQGET call. In this situation the connection status shows read ahead as being inhibited.

If, because of these restrictions on MQGET, you decide that a client application design is not suited to read ahead, specify the MQOPEN option MQOO_READ_AHEAD_NO. Alternatively set the default read ahead value of the queue being opened altered to either NO or DISABLED.