Browsing messages on a queue
To use the MQGET call to browse the messages on a queue:
- Call MQOPEN to open the queue for browsing, specifying the MQOO_BROWSE option.
- To browse the first message on the queue, call MQGET with the MQGMO_BROWSE_FIRST option. To find the message you want, you can call MQGET repeatedly with the MQGMO_BROWSE_NEXT option to step through many messages.
You must set the MsgId and CorrelId fields of the MQMD structure to null after each MQGET call in order to see all messages.
- Call MQCLOSE to close the queue.
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. You can think of the browse cursor as a logical pointer that is positioned before the first message on the queue.
You 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.
In both 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, you can use the MQGMO_BROWSE_NEXT option to browse the first message; you 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
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 you are browsing, as a queue in this sequence will have messages placed at the end. When the cursor has recognized that it has reached the end of the queue, the browse cursor will stay where it is and return with MQRC_NO_MSG_AVAILABLE. You may 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 has the highest priority at the time the MQOPEN call is issued.
Use MQGMO_BROWSE_NEXT to read the messages in the queue.
The browse cursor will point to the next message, working from the priority of the first message to finish with the message at the lowest priority. It will browse any messages put to the queue during this time as long as they are of equal or lower priority to the message identified by the current browse cursor.
Any messages put to the queue of higher priority can only be browsed by:
- Opening the queue for browse again, at which point a new browse cursor is established
- Using 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 you 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 subsequently take the default priority of the queue.
Use of the queue's index
Only supported in WebSphere MQ for z/OS.
When you browse an indexed queue that only contains messages of a single priority (either persistent or non-persistent or both), the queue manager performs the browse by making use of the index, when any of the following forms of browse are used:
- If the queue is indexed by MSGID, and the above condition is true, then browse requests that pass a MSGID in the MQMD structure will be processed using the index to find the target message.
- If the queue is indexed by CORRELID, and the above condition is true, then browse requests that pass a CORRELID in the MQMD structure will be processed using the index to find the target message.
- If the queue is indexed by GROUPID, and the above condition is true, then browse requests that pass a GROUPID in the MQMD structure will be 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, and the queue is indexed, and a message is returned, then the index entry for the message must be found, and information within it is used to update the browse cursor. If you use a very wide selection of index values, then this extra processing will add very little overhead to the browse request.
Browsing messages when message length unknown
To browse a message when you do not know the size of the message, and you do not wish to use the MsgId, CorrelId, or GroupId fields to locate the message, you can use the MQGMO_BROWSE_MSG_UNDER_CURSOR option :
- Issue an MQGET with:
- Either the MQGMO_BROWSE_FIRST or MQGMO_BROWSE_NEXT option
- The MQGMO_ACCEPT_TRUNCATED_MSG option
- Buffer length zero
- Note:
- If another program is likely to get the same message, consider using the MQGMO_LOCK option as well. MQRC_TRUNCATED_MSG_ACCEPTED should be returned.
- Use the returned DataLength to allocate the storage needed.
- Issue an MQGET with the MQGMO_BROWSE_MSG_UNDER_CURSOR.
The message pointed to is the last one that was retrieved; the browse cursor will not have moved. You can choose either to lock the message using the MQGMO_LOCK option, or to unlock a locked message using MQGMO_UNLOCK option.
The call fails if no MQGET with either the MQGMO_BROWSE_FIRST or MQGMO_BROWSE_NEXT options has been issued successfully since the queue was opened.
Restriction MQGMO_LOCK and MQGMO_UNLOCK are not available on MQSeries for Compaq NonStop Kernel.
Removing a message you have browsed
You can remove from the queue a message you have already browsed provided you have opened the queue for removing messages as well as for browsing. (You must specify one of the MQOO_INPUT_* options, as well as the MQOO_BROWSE option, on your MQOPEN call.)
To remove the message, call MQGET again, but in the Options field of the MQGMO structure, specify MQGMO_MSG_UNDER_CURSOR. In this case, the MQGET call ignores the MsgId, CorrelId, and GroupId fields of the MQMD structure.
In the time between your browsing and removal steps, another program may have removed messages from the queue, including the message under your browse cursor. In this case, your MQGET call returns a reason code to say that the message is not available.
WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.
IBM is a trademark of the IBM Corporation in the United States, other countries, or both.