Getting messages from a queue using the MQGET call
The MQGET call gets a message from an open local queue. It cannot get a message from a queue on another system.
As input to the MQGET call, supply:
- A connection handle.
- A queue handle.
- A description of the message you want to get from the queue. This is in the form of a message descriptor (MQMD) structure.
- Control information in the form of a Get Message Options (MQGMO) structure.
- The size of the buffer you have assigned to hold the message (MQLONG).
- The address of the storage in which the message must be put.
The output from MQGET is:
- A reason code
- A completion code
- The message in the buffer area you specified, if the call completes successfully
- Your options structure, modified to show the name of the queue from which the message was retrieved
- Your message descriptor structure, with the contents of the fields modified to describe the message that was retrieved
- The length of the message (MQLONG)
There is a description of the MQGET call in WebSphere MQ Application Programming Reference.
The following sections describe the information supply as input to the MQGET call.
Specifying connection handles
For CICS on z/OS and VSE/ESA applications, you can specify the constant MQHC_DEF_HCONN (which has the value zero), or use the connection handle returned by the MQCONN or MQCONNX call. For other applications, always use the connection handle returned by the MQCONN or MQCONNX call.
Use the queue handle (Hobj) that is returned when you call MQOPEN.
Describing messages using the MQMD structure and the MQGET call
To identify the message you want to get from a queue, use the message descriptor structure (MQMD). This is an input/output parameter for the MQGET call. There is an introduction to the message properties that MQMD describes in Chapter 3, WebSphere MQ messages, and there is a description of the structure itself in WebSphere MQ Application Programming Reference.
If you know which message you want to get from the queue, see Getting a particular message.
If you do not specify a particular message, MQGET retrieves the first message in the queue. The order in which messages are retrieved from a queue describes how the priority of a message, the MsgDeliverySequence attribute of the queue, and the MQGMO_LOGICAL_ORDER option determine the order of the messages in the queue.
- Note:
- If you want to use MQGET more than once (for example, to step through the messages in the queue), set the MsgId and CorrelId fields of this structure to null after each call. This clears these fields of the identifiers of the message that was retrieved.
However, if you want to group your messages, the GroupId should be the same for messages in the same group, so that the call will look for a message having the same identifiers as the previous message in order to make up the whole group.
Specifying MQGET options using the MQGMO structure
The MQGMO structure is an input/output variable for passing options to the MQGET call.
The following sections give you help on filling in some of the fields of this structure. There is a description of the structure in WebSphere MQ Application Programming Reference.
- StrucId
- StrucId is a 4-character field used to identify the structure as a get-message options structure. Always specify MQGMO_STRUC_ID.
- Version
- Version describes the version number of the structure. MQGMO_VERSION_1 is the default. If you wish to use the Version 2 fields or retrieve messages in logical order, specify MQGMO_VERSION_2. If you wish to use the Version 3 fields or retrieve messages in logical order, specify MQGMO_VERSION_3. MQGMO_CURRENT_VERSION sets your application to use the most recent level.
- Options
- Within your code, you can select the options in any order as each option is represented by a bit in the Options field.
The Options field controls:
- Whether the MQGET call waits for a message to arrive on the queue before it completes (see Waiting for messages)
- Whether the get operation is included in a unit of work.
- Whether a nonpersistent message is retrieved outside syncpoint, allowing fast messaging
- In WebSphere MQ for z/OS, whether the message retrieved is marked as skipping backout (see Skipping backout)
- Whether the message is removed from the queue, or merely browsed
- Whether to select a message by using a browse cursor or by other selection criteria
- Whether the call succeeds even if the message is longer than your buffer
- In WebSphere MQ for z/OS, whether to allow the call to complete, and sets a signal to indicate that you want to be notified when a message arrives
- Whether the call fails if the queue manager is in a quiescing state
- In WebSphere MQ for z/OS, whether the call fails if the connection is in a quiescing state
- Whether application message data conversion is required (see Application data conversion)
- The order in which messages and (with the exception of WebSphere MQ for z/OS) segments are retrieved from a queue
- Except on WebSphere MQ for z/OS, whether complete, logical messages only are retrievable
- Whether messages in a group can be retrieved only when all messages in the group are available
- Except on WebSphere MQ for z/OS, whether segments in a logical message can be retrieved only when all segments in the logical message are available
If you leave the Options field set to the default value (MQGMO_NO_WAIT), the MQGET call operates this way:
- If there is no message matching your selection criteria on the queue, the call does not wait for a message to arrive, but completes immediately. Also, in WebSphere MQ for z/OS, the call does not set a signal requesting notification when such a message arrives.
- The way that the call operates with syncpoints is determined by the platform:
Platform Under syncpoint control OS/400 No UNIX systems No z/OS Yes OS/2 No Compaq NonStop Kernel Yes VSE/ESA Yes Windows systems No
- In WebSphere MQ for z/OS, the message retrieved is not marked as skipping backout.
- The selected message is removed from the queue (not browsed).
- No application message data conversion is required.
- The call fails if the message is longer than your buffer.
- WaitInterval
- The WaitInterval field specifies the maximum time (in milliseconds) that the MQGET call waits for a message to arrive on the queue when you use the MQGMO_WAIT option. If no message arrives within the time specified in WaitInterval, the call completes and returns a reason code showing that there was no message that matched your selection criteria on the queue.
In WebSphere MQ for z/OS, if you use the MQGMO_SET_SIGNAL option, the WaitInterval field specifies the time for which the signal is set.
For more information on these options, see Waiting for messages and Signaling.
- Signal1
- Signal1 is supported on WebSphere MQ for z/OS and MQSeries for Compaq NonStop Kernel only.
If you have chosen to use the MQGMO_SET_SIGNAL option to request that your application is notified when a suitable message arrives, specify the type of signal in the Signal1 field. In WebSphere MQ on all other platforms, the Signal1 field is reserved and its value is not significant.
For more information, see Signaling.
- Signal2
- The Signal2 field is reserved on all platforms and its value is not significant.
For more information, see Signaling.
- ResolvedQName
- ResolvedQName is an output field in which the queue manager returns the name of the queue (after resolution of any alias) from which the message was retrieved.
- MatchOptions
- MatchOptions controls the selection criteria for MQGET.
- GroupStatus
- GroupStatus indicates whether the message you have retrieved is in a group.
- SegmentStatus
- SegmentStatus indicates whether the item you have retrieved is a segment of a logical message.
- Segmentation
- Segmentation indicates whether segmentation is allowed for the message retrieved.
- MsgToken
- Only supported in WebSphere MQ for z/OS.
MsgToken uniquely identifies a message.
For more information, see WebSphere MQ Workflow.
- ReturnedLength
- ReturnedLength is an output field in which the queue manager returns the length of message data returned (in bytes).
Specifying the size of the buffer area
In the BufferLength parameter of the MQGET call, specify the size of the buffer area you want to use to hold the message data that you retrieve. There are three ways to decide how big this should be:
- You may already know what length of messages to expect from this program. If so, specify a buffer of this size.
However, you can use the MQGMO_ACCEPT_TRUNCATED_MSG option in the MQGMO structure if you want the MQGET call to complete even if the message is too big for the buffer. In this case:
- The buffer is filled with as much of the message as it can hold
- The call returns a warning completion code
- The message is removed from the queue (discarding the remainder of the message), or the browse cursor is advanced (if you are browsing the queue)
- The real length of the message is returned in DataLength
Without this option, the call still completes with a warning, but it does not remove the message from the queue (or advance the browse cursor).
- Estimate a size for the buffer (or even specify a size of zero bytes) and do not use the MQGMO_ACCEPT_TRUNCATED_MSG option. If the MQGET call fails (for example, because the buffer is too small), the length of the message is returned in the DataLength parameter of the call. (The buffer is still filled with as much of the message as it can hold, but the processing of the call is not completed.) Store the MsgId of this message, then repeat the MQGET call, specifying a buffer area of the correct size, and the MsgId you noted from the first call.
If your program is serving a queue that is also being served by other programs, one of those other programs may remove the message you want before your program can issue another MQGET call. Your program could waste time searching for a message that no longer exists. To avoid this, first browse the queue until you find the message you want, specifying a BufferLength of zero and using the MQGMO_ACCEPT_TRUNCATED_MSG option. This positions the browse cursor under the message you want. You can then retrieve the message by calling MQGET again, specifying the MQGMO_MSG_UNDER_CURSOR option. If another program removes the message between your browse and removal calls, your second MQGET fails immediately (without searching the whole queue), because there is no message under your browse cursor.
- The MaxMsgLength queue attribute determines the maximum length of messages accepted for that queue` and the MaxMsgLength queue manager attribute determines the maximum length of messages accepted for that queue manager. If you do not know what length of message to expect, you can inquire about the MaxMsgLength attribute (using the MQINQ call), then specify a buffer of this size.
Try to make the buffer size as close as possible to the actual message size to avoid reduced performance.
For further information about the MaxMsgLength attribute, see Increasing the maximum message length.
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.