MsgToken (MQBYTE16)
MsgToken field - MQGMO structure. This field is used by the queue manager to uniquely identify a message.
This is a byte string that is generated by the queue manager to identify a message uniquely on a queue. The message token is generated when the message is first placed on the queue manager, and remains with the message until the message is permanently removed from the queue manager, unless the queue manager is restarted.
When the message
is removed from the queue, the MsgToken
that
identified that instance of the message is no longer valid, and is
never reused. If the queue manager is restarted, the MsgToken
that
identified a message on the queue before restart might not be valid
after restart. However, the MsgToken
is
never reused to identify a different message instance. The MsgToken
is
generated by the queue manager and is not visible to any external
application.
When a message is returned by
a call to MQGET where a Version 3 or higher MQGMO is supplied, the MsgToken
identifying
the message on the queue is returned in the MQGMO by the queue manager.
There is one exception to this: when the message is being removed
from the queue outside syncpoint, the queue manager might not return
a MsgToken
because it is
not useful to identify the returned message on a subsequent MQGET
call. Applications should only use MsgToken
to
refer to the message on subsequent MQGET calls.
If a MsgToken
is
supplied and the MatchOption
MQMO_MATCH_MSG_TOKEN
is specified and neither MQGMO_MSG_UNDER_CURSOR nor MQGMO_BROWSE_MSG_UNDER_CURSOR
is specified, only the message identified by that MsgToken
can
be returned. The option is valid on all local queues regardless of
INDXTYPE, and on z/OS® you must use INDXTYPE(MSGTOKEN) only on
Workload Manager (WLM) queues.
Any other MatchOptions
specified
are checked, and if they do not match, MQRC_NO_MSG_AVAILABLE is returned.
If MQGMO_BROWSE_NEXT is coded with MQMO_MATCH_MSG_TOKEN, the message
identified by the MsgToken
is
returned only if it is beyond the browse-cursor for the calling handle.
If MQGMO_MSG_UNDER_CURSOR or MQGMO_BROWSE_MSG_UNDER_CURSOR is specified, MQMO_MATCH_MSG_TOKEN is ignored.
- MQGMO_WAIT
- MQGMO_SET_SIGNAL
For an MQGET call specifying MQMO_MATCH_MSG_TOKEN, an MQGMO of version 3 or later must be supplied to the call, otherwise MQRC_WRONG_GMO_VERSION is returned.
If the MsgToken
is
not valid at this time, MQCC_FAILED with MQRC_NO_MSG_AVAILABLE is
returned, unless there is another error.