Home

 

MsgId (MQBYTE24)

This is a byte string that is used to distinguish one message from another. Generally, no two messages should have the same message identifier, although this is not disallowed by the queue manager. The message identifier is a permanent property of the message, and persists across restarts of the queue manager. Because the message identifier is a byte string and not a character string, the message identifier is not converted between character sets when the message flows from one queue manager to another.

For the MQPUT and MQPUT1 calls, if MQMI_NONE or MQPMO_NEW_MSG_ID is specified by the application, the queue manager generates a unique message identifier 2 when the message is put, and places it in the message descriptor sent with the message. The queue manager also returns this message identifier in the message descriptor belonging to the sending application. The application can use this value to record information about particular messages, and to respond to queries from other parts of the application.

If the message is being put to a distribution list, the queue manager generates unique message identifiers as necessary, but the value of the MsgId field in MQMD is unchanged on return from the call, even if MQMI_NONE or MQPMO_NEW_MSG_ID was specified. If the application needs to know the message identifiers generated by the queue manager, the application must provide MQPMR records containing the MsgId field.

The sending application can also specify a value for the message identifier other than MQMI_NONE; this stops the queue manager generating a unique message identifier. An application that is forwarding a message can use this to propagate the message identifier of the original message.

The queue manager does not use this field except to:

When the queue manager or a message channel agent generates a report message, it sets the MsgId field in the way specified by the Report field of the original message, either MQRO_NEW_MSG_ID or MQRO_PASS_MSG_ID. Applications that generate report messages must also do this.

For the MQGET call, MsgId is one of the five fields that can be used to retrieve a particular message from the queue. Normally the MQGET call returns the next message on the queue, but a particular message can be obtained by specifying one or more of the five selection criteria, in any combination; these fields are:

The application sets one or more of these field to the values required, and then sets the corresponding MQMO_* match options in the MatchOptions field in MQGMO to use those fields as selection criteria. Only messages that have the specified values in those fields are candidates for retrieval. The default for the MatchOptions field (if not altered by the application) is to match both the message identifier and the correlation identifier.

On z/OS, the selection criteria that we can use are restricted by the type of index used for the queue. See the IndexType queue attribute for further details.

Normally, the message returned is the first message on the queue that satisfies the selection criteria. But if MQGMO_BROWSE_NEXT is specified, the message returned is the next message that satisfies the selection criteria; the scan for this message starts with the message following the current cursor position.

Note:
The queue is scanned sequentially for a message that satisfies the selection criteria, so retrieval times are slower than if no selection criteria are specified, especially if many messages have to be scanned before a suitable one is found.

See Table 38 for more information about how selection criteria are used in various situations.

Specifying MQMI_NONE as the message identifier has the same effect as not specifying MQMO_MATCH_MSG_ID, that is, any message identifier matches.

This field is ignored if the MQGMO_MSG_UNDER_CURSOR option is specified in the GetMsgOpts parameter on the MQGET call.

On return from an MQGET call, the MsgId field is set to the message identifier of the message returned (if any).

The following special value can be used:

MQMI_NONE

No message identifier is specified.

The value is binary zero for the length of the field.

For the C programming language, the constant MQMI_NONE_ARRAY is also defined; this has the same value as MQMI_NONE, but is an array of characters instead of a string.

This is an input/output field for the MQGET, MQPUT, and MQPUT1 calls. The length of this field is given by MQ_MSG_ID_LENGTH. The initial value of this field is MQMI_NONE.

2.
A MsgId generated by the queue manager consists of a 4-byte product identifier (AMQ  or CSQ  in either ASCII or EBCDIC, where   represents a blank), followed by a product-specific implementation of a unique string. In WebSphere MQ this contains the first 12 characters of the queue-manager name, and a value derived from the system clock. All queue managers that can intercommunicate must therefore have names that differ in the first 12 characters, in order to ensure that message identifiers are unique. The ability to generate a unique string also depends on the system clock not being changed backward. To eliminate the possibility of a message identifier generated by the queue manager duplicating one generated by the application, the application must avoid generating identifiers with initial characters in the range A through I in ASCII or EBCDIC (X'41' through X'49' and X'C1' through X'C9'). However, the application is not prevented from generating identifiers with initial characters in these ranges.



 

Home