To use the MQGET call to browse the messages on a queue:
You must set the MsgId and CorrelId fields of the MQMD structure to null after each MQGET call in order to see all messages.
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:
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.)
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.
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:
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.
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.
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 the following
forms of browse are used:
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.Use of the queue's index
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 :
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. |
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.