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, we must supply:

  • A connection handle.
  • A queue handle.
  • A description of the message that we 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 that we have assigned to hold the message (MQLONG).
  • The address of the storage in which to put the message.

The output from MQGET is:

  • A reason code
  • A completion code
  • The message in the buffer area that 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 MQGET.

The following sections describe the information we must supply as input to the MQGET call.


Specify connection handles

For CICS on z/OS applications, we 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 that we 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 IBM MQ messages, and there is a description of the structure itself in MQMD.

If you know which message we want to get from the queue, see Getting a particular message.

If we 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: To use MQGET more than once (for example, to step through the messages in the queue), we must 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 we want to group your messages, the GroupId must be the same for messages in the same group, so that the call looks for a message having the same identifiers as the previous message in order to make up the whole group.


Specify MQGET options using the MQGMO structure

The MQGMO structure is an input/output variable for passing options to the MQGET call. The following sections help you to complete some of the fields of this structure.

There is a description of the MQGMO structure in MQGMO.

    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. To use the Version 2 fields or retrieve messages in logical order, specify MQGMO_VERSION_2. To use the Version 3 fields or retrieve messages in logical order, specify MQGMO_VERSION_3. MQGMO_CURRENT_VERSION sets the application to use the most recent level.

    Options
    Within your code, we can select the options in any order; 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 sync point, allowing fast messaging
    • On IBM 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
    • On IBM MQ for z/OS, whether to allow the call to complete. This option also sets a signal to indicate that we want to be notified when a message arrives
    • Whether the call fails if the queue manager is in a quiescing state
    • On IBM 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 segments are retrieved from a queue (except for IBM MQ for z/OS )
    • Whether complete, logical messages only are retrievable (except for IBM MQ for z/OS )
    • Whether messages in a group can be retrieved only when all messages in the group are available
    • Whether segments in a logical message can be retrieved only when all segments in the logical message are available (except for IBM MQ for z/OS )

    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 IBM 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 sync points is determined by the platform:

    Platform Under sync point control
    IBM i No
    UNIX and Linux systems No
    z/OS Yes
    Windows systems No

    • On IBM 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 we 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.

    On IBM MQ for z/OS, if we use the MQGMO_SET_SIGNAL option, the WaitInterval field specifies the time for which the signal is set.

    For more information about these options, see Waiting for messages and Signaling .

    Signal1
    Signal1 is supported only on IBM MQ for z/OS and MQSeries for HP Integrity NonStop Server.

    If we use the MQGMO_SET_SIGNAL option to request that the application is notified when a suitable message arrives, you specify the type of signal in the Signal1 field. In IBM 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 that we have retrieved is in a group.

    SegmentStatus
    SegmentStatus indicates whether the item that we have retrieved is a segment of a logical message.

    Segmentation
    Segmentation indicates whether segmentation is allowed for the message retrieved.

    MsgToken

    MsgToken uniquely identifies a message.

    ReturnedLength
    ReturnedLength is an output field in which the queue manager returns the length of message data returned (in bytes).

    MsgHandle
    The handle to a message that is to be populated with the properties of the message being retrieved from the queue. The handle has previously been created by an MQCRTMH call. Any properties already associated with the handle are cleared before retrieving a message.


Specify the size of the buffer area

In the BufferLength parameter of the MQGET call, specify the size of the buffer area to hold the message data that you retrieve. You decide how large this should be in three ways:
  1. We might already know what length of messages to expect from this program. If so, specify a buffer of this size. However, we can use the MQGMO_ACCEPT_TRUNCATED_MSG option in the MQGMO structure if we want the MQGET call to complete even if the message is too large 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 we 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).

  2. 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 that 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 might remove the message that we 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 that we want, specifying a BufferLength of zero and using the MQGMO_ACCEPT_TRUNCATED_MSG option. This positions the browse cursor under the message that we want. We 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.

  3. The MaxMsgLength queue attribute determines the maximum length of messages accepted for that queue; the MaxMsgLength queue manager attribute determines the maximum length of messages accepted for that queue manager. If we do not know what length of message to expect, we 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.

Parent topic: Getting messages from a queue