The browse cursor
When you open (MQOPEN) a queue for browsing, the call establishes a browse cursor for use with MQGET calls that use one of the browse options. We can think of the browse cursor as a logical pointer that is positioned before the first message on the queue.
We can have more than one browse cursor active (from a single program) by issuing several MQOPEN requests for the same queue.
When you call MQGET for browsing, use one of the following options in your MQGMO structure:
- MQGMO_BROWSE_FIRST
- Gets a copy of the first message that satisfies the conditions specified in your MQMD structure.
- MQGMO_BROWSE_NEXT
- Gets a copy of the next message that satisfies the conditions specified in your MQMD structure.
- MQGMO_BROWSE_MSG_UNDER_CURSOR
- Gets a copy of the message currently pointed to by the cursor, that is, the one that was last retrieved using either the MQGMO_BROWSE_FIRST or the MQGMO_BROWSE_NEXT option.
In all cases, the message remains on the queue.
When you open a queue, the browse cursor is positioned logically just before the first message on the queue. This means that if you make your MQGET call immediately after your MQOPEN call, we can use the MQGMO_BROWSE_NEXT option to browse the first message; we do not have to use the MQGMO_BROWSE_FIRST option.
The order in which messages are copied from the queue is determined by the MsgDeliverySequence attribute of the queue. (For more information, see The order in which messages are retrieved from a queue.)
- Queues in FIFO (first in, first out) sequence
- Queues in priority sequence
- Uncommitted messages
- Change to queue sequence
- Use the queue's index
Queues in FIFO (first in, first out) sequence
The first message in a queue in this sequence is the message that has been on the queue the longest.
Use MQGMO_BROWSE_NEXT to read the messages sequentially in the queue. You will see any messages put to the queue while we are browsing, as a queue in this sequence has messages placed at the end. When the cursor recognizes that it has reached the end of the queue, the browse cursor stays where it is and returns with MQRC_NO_MSG_AVAILABLE. We can then either leave it there waiting for further messages or reset it to the beginning of the queue with a MQGMO_BROWSE_FIRST call.
Queues in priority sequence
The first message in a queue in this sequence is the message that has been on the queue the longest and that has the highest priority at the time that the MQOPEN call is issued.
Use MQGMO_BROWSE_NEXT to read the messages in the queue.
The browse cursor points to the next message, working from the priority of the first message to finish with the message at the lowest priority. It browses any messages put to the queue during this time as long as they are of priority equal to, or lower than, the message identified by the current browse cursor.
Any messages put to the queue of higher priority can be browsed only by:
- Opening the queue for browse again, at which point a new browse cursor is established
- Use the MQGMO_BROWSE_FIRST option
Uncommitted messages
An uncommitted message is never visible to a browse; the browse cursor skips past it.
Messages within a unit-of-work cannot be browsed until the unit-of-work is committed. Messages do not change their position on the queue when committed, so skipped, uncommitted messages will not be seen, even when they are committed, unless we use the MQGMO_BROWSE_FIRST option and work though the queue again.
Change to queue sequence
If the message delivery sequence is changed from priority to FIFO while there are messages on the queue, the order of the messages that are already queued is not changed. Messages added to the queue later, take the default priority of the queue.
Use the queue's index
When you browse an indexed queue that contains only messages of a single priority (either persistent or nonpersistent or both), the queue manager uses the index to browse when certain forms of browse are used.
Note: Supported only on IBM MQ for z/OS .Any of the following forms of browse are used when an indexed queue contains only messages of single priority:
- If the queue is indexed by MSGID, browse requests that pass a MSGID in the MQMD structure are processed using the index to find the target message.
- If the queue is indexed by CORRELID, browse requests that pass a CORRELID in the MQMD structure are processed using the index to find the target message.
- If the queue is indexed by GROUPID, browse requests that pass a GROUPID in the MQMD structure are processed using the index to find the target message.
If the browse request does not pass a MSGID, CORRELID, or GROUPID in the MQMD structure, the queue is indexed, and a message is returned, the index entry for the message must be found, and information within it used to update the browse cursor. If we use a wide selection of index values, this does not add significant extra processing to the browse request.
Parent topic: Browsing messages on a queue