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 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 want to use the
Version 2 fields or retrieve messages in logical order, specify MQGMO_VERSION_2.
If you want 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; 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(R) 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).