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 help you to fill in some of the fields of this structure. There is a description of the structure in the 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

Vdescribes the version number of the structure. MQGMO_VERSION_1 is the default. If you want to use the V2 fields or retrieve messages in logical order, specify MQGMO_VERSION_2. If you want to use the V3 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, 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 syncpoint, allowing fast messaging

  • On 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

  • On WebSphere MQ for z/OS, whether to allow the call to complete. This option also 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

  • On 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
i5/OS No
UNIX systems No
z/OS Yes
Windows systems No

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

On 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 use the MQGMO_SET_SIGNAL option to request that your application is notified when a suitable message arrives, you 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 that you have retrieved is in a group.

SegmentStatus

SegmentStatus indicates whether the item that 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).

 

Parent topic:

Getting messages from a queue using the MQGET call


fg12580_