MsgToken (MQBYTE16)

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.

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.