These options control the action of MQGET. You can specify none or more of the options described below. If you need more than one the values can be:
Combinations of options that are not valid are noted; all other combinations are valid.
Wait options: The following options relate to waiting for messages to arrive on the queue:
If MQGET requests are inhibited, or MQGET requests become inhibited while waiting, the wait is canceled and the call completes with MQCC_FAILED and reason code MQRC_GET_INHIBITED, regardless of whether there are suitable messages on the queue.
You can use this option with the MQGMO_BROWSE_FIRST or MQGMO_BROWSE_NEXT options.
If several applications are waiting on the same shared queue, the applications that are activated when a suitable message arrives are described below.
Note the following points:
On z/OS, the following points apply:
MQGMO_WAIT is ignored if specified with MQGMO_BROWSE_MSG_UNDER_CURSOR or MQGMO_MSG_UNDER_CURSOR; no error is raised.
If a currently available message satisfies the criteria specified in the message descriptor, or if a parameter error or other synchronous error is detected, the call completes in the same way as if this option had not been specified.
If no message satisfying the criteria specified in the message descriptor is currently available, control returns to the application without waiting for a message to arrive. The output fields in the message descriptor and the output parameters of the MQGET call are not set, other than the CompCode and Reason parameters (which are set to MQCC_WARNING and MQRC_SIGNAL_REQUEST_ACCEPTED respectively). When a suitable message arrives subsequently, the signal is delivered by posting the ECB.
The caller must then reissue the MQGET call to retrieve the message. The application can wait for this signal, using functions provided by the operating system.
If the operating system provides a multiple wait mechanism, the application can use this technique to wait for a message arriving on any one of several queues.
If a nonzero WaitInterval is specified, after this time the signal is delivered. The queue manager can also cancel the wait, in which case the signal is delivered.
If more than one MQGET call has set a signal for the same message, the order in which applications are activated is the same as that described for MQGMO_WAIT.
If there is more than one MQGET call waiting for the same message, with a mixture of wait and signal options, each waiting call is considered equally.
Under certain conditions the MQGET call can retrieve a message, and a signal resulting from the arrival of the same message can be delivered. When a signal is delivered, an application must be prepared for no message to be available.
A queue handle can have no more than one signal request outstanding.
This option is not valid with any of the following options:
This option is supported on z/OS only.
On z/OS, this option also forces the MQGET call to fail if the connection (for a CICS or IMS application) is in the quiescing state.
If this option is specified with MQGMO_WAIT or MQGMO_SET_SIGNAL, and the wait or signal is outstanding at the time the queue manager enters the quiescing state:
On z/OS, the signal completes with event completion code MQEC_Q_MGR_QUIESCING or MQEC_CONNECTION_QUIESCING.
If MQGMO_FAIL_IF_QUIESCING is not specified and the queue manager or connection enters the quiescing state, the wait or signal is not canceled.
Syncpoint options: The following options relate to the participation of the MQGET call within a unit of work:
If neither this option nor MQGMO_NO_SYNCPOINT is specified, the inclusion of the get request in unit-of-work protocols is determined by the environment:
Because of these differences, an application that you want to port must not allow this option to default; specify MQGMO_SYNCPOINT or MQGMO_NO_SYNCPOINT explicitly.
This option is not valid with any of the following options:
This option is not valid with any of the following options:
This option is supported in the following environments: AIX, HP-UX, z/OS, i5/OS, Solaris, and Linux, plus WebSphere MQ clients connected to these systems.
This option is assumed if you specify MQGMO_BROWSE_FIRST or MQGMO_BROWSE_NEXT.
If you specify neither this option nor MQGMO_SYNCPOINT, the inclusion of the get request in unit-of-work protocols is determined by the environment:
Because of these differences, an application that you want to port must not allow this option to default; specify either MQGMO_SYNCPOINT or MQGMO_NO_SYNCPOINT explicitly.
This option is not valid with any of the following options:
When an application requests the backout of a unit of work containing a get request, a message that was retrieved using this option is not restored to its previous state. (Other resource updates, however, are still backed out.) Instead, the message is treated as if it had been retrieved by a get request without this option, in a new unit of work started by the backout request.
This is useful if the application retrieves a message, but only after some resources have been changed does it become apparent that the unit of work cannot complete successfully. If you omit this option, backing out the unit of work reinstates the message on the queue, so that the same sequence of events occurs when the message is next retrieved. However, if you specify this option on the original MQGET call, backing out the unit of work backs out the updates to the other resources, but treats the message as if it had been retrieved under a new unit of work. The application can perform appropriate error handling (such as sending a report message to the sender of the original message, or placing the original message on the dead-letter queue), and then commit the new unit of work. Committing the new unit of work removes the message permanently from the original queue.
MQGMO_MARK_SKIP_BACKOUT marks a single physical message. If the message belongs to a message group, the other messages in the group are not marked. Similarly, if the marked message is a segment of a logical message, the other segments in the logical message are not marked. Any message in a group can be marked, but if messages are retrieved using MQGMO_LOGICAL_ORDER, it is advantageous to mark the first message in the group. When the unit of work is backed out, the first (marked) message is moved to the new unit of work, while the second and later messages in the group are reinstated on the queue. However, that group is no longer eligible for retrieval by an application using MQGMO_LOGICAL_ORDER, because the first message in the group is no longer on the queue. This prevents a second instance of the application inadvertently processing messages in that group. However, the first instance of the application can retrieve the second and later messages into the new unit of work using the MQGMO_LOGICAL_ORDER option as normal.
Occasionally you might need to back out the new unit of work (for example, because the dead-letter queue is full and the message must not be discarded). Backing out the new unit of work reinstates the message on the original queue, which prevents the message being lost. However, in this situation processing cannot continue. After backing out the new unit of work, the application must inform the operator or administrator that there is an unrecoverable error, and then terminate.
This option has an effect only if the unit of work containing the get request is terminated by the application backing it out. (Such requests use calls or commands that depend on the environment.) This option has no effect if the unit of work containing the get request is backed out for any other reason (for example, because the transaction or system abends). In this situation, any message retrieved using this option is reinstated on the queue in the same way as messages retrieved without this option.
Within a unit of work, there can be only one get request marked as skipping backout, as well as none or several unmarked get requests.
If this option is specified, MQGMO_SYNCPOINT must also be specified. MQGMO_MARK_SKIP_BACKOUT is not valid with any of the following options:
This option is supported only on z/OS.
Browse options: The following options relate to browsing messages on the queue:
An MQGET call with MQGMO_BROWSE_FIRST ignores the previous position of the browse cursor. The first message on the queue that satisfies the conditions specified in the message descriptor is retrieved. The message remains on the queue, and the browse cursor is positioned on this message.
After this call, the browse cursor is positioned on the message that has been returned. If the message is removed from the queue before the next MQGET call with MQGMO_BROWSE_NEXT is issued, the browse cursor remains at the position in the queue that the message occupied, even though that position is now empty.
The MQGMO_MSG_UNDER_CURSOR option can subsequently be used with a nonbrowse MQGET call if required, to remove the message from the queue.
The browse cursor is not moved by a nonbrowse MQGET call using the same Hobj handle. Nor is it moved by a browse MQGET call that returns a completion code of MQCC_FAILED, or a reason code of MQRC_TRUNCATED_MSG_FAILED.
Specify the MQGMO_LOCK option with this option, to lock the message that is browsed.
You can specify MQGMO_BROWSE_FIRST with any valid combination of the MQGMO_* and MQMO_* options that control the processing of messages in groups and segments of logical messages.
If you specify MQGMO_LOGICAL_ORDER, the messages are browsed in logical order. If you omit that option, the messages are browsed in physical order. When you specify MQGMO_BROWSE_FIRST, you can switch between logical order and physical order, but subsequent MQGET calls using MQGMO_BROWSE_NEXT must browse the queue in the same order as the most-recent call that specified MQGMO_BROWSE_FIRST for the queue handle.
The group and segment information that the queue manager retains for MQGET calls that browse messages on the queue is separate from the group and segment information that the queue manager retains for MQGET calls that remove messages from the queue. When you specify MQGMO_BROWSE_FIRST, the queue manager ignores the group and segment information for browsing, and scans the queue as though there were no current group and no current logical message. If the MQGET call is successful (completion code MQCC_OK or MQCC_WARNING), the group and segment information for browsing is set to that of the message returned; if the call fails, the group and segment information remains the same as it was before the call.
This option is not valid with any of the following options:
It is also an error if the queue was not opened for browse.
After a queue has been opened for browse, the first browse call using the handle has the same effect whether it specifies the MQGMO_BROWSE_FIRST or MQGMO_BROWSE_NEXT option.
If the message is removed from the queue before the next MQGET call with MQGMO_BROWSE_NEXT is issued, the browse cursor logically remains at the position in the queue that the message occupied, even though that position is now empty.
Messages are stored on the queue in one of two ways:
The MsgDeliverySequence queue attribute indicates which method applies (see Attributes for queues for details).
If the queue has a MsgDeliverySequence of MQMDS_PRIORITY, and a message arrives on the queue that is of a higher priority than the one currently pointed to by the browse cursor, that message is not found during the current sweep of the queue using MQGMO_BROWSE_NEXT. It can be found only after the browse cursor has been reset with MQGMO_BROWSE_FIRST (or by reopening the queue).
The MQGMO_MSG_UNDER_CURSOR option can subsequently be used with a nonbrowse MQGET call if required, to remove the message from the queue.
The browse cursor is not moved by nonbrowse MQGET calls using the same Hobj handle.
Specify the MQGMO_LOCK option with this option to lock the message that is browsed.
You can specify MQGMO_BROWSE_NEXT with any valid combination of the MQGMO_* and MQMO_* options that control the processing of messages in groups and segments of logical messages.
If you specify MQGMO_LOGICAL_ORDER, the messages are browsed in logical order. If you omit that option, the messages are browsed in physical order. When you specify MQGMO_BROWSE_FIRST, you can switch between logical order and physical order, but subsequent MQGET calls using MQGMO_BROWSE_NEXT must browse the queue in the same order as the most-recent call that specified MQGMO_BROWSE_FIRST for the queue handle. The call fails with reason code MQRC_INCONSISTENT_BROWSE if this condition is not satisfied.
To avoid the possibility of an infinite loop, open the queue twice for browse:
The group and segment information that the queue manager retains for MQGET calls that browse messages on the queue is separate from the group and segment information that it retains for MQGET calls that remove messages from the queue.
This option is not valid with any of the following options:
It is also an error if the queue was not opened for browse.
The message pointed to by the browse cursor is the one that was last retrieved using either the MQGMO_BROWSE_FIRST or the MQGMO_BROWSE_NEXT option. The call fails if neither of these calls has been issued for this queue since it was opened, or if the message that was under the browse cursor has since been retrieved destructively.
The position of the browse cursor is not changed by this call.
The MQGMO_MSG_UNDER_CURSOR option can subsequently be used with a nonbrowse MQGET call if required, to remove the message from the queue.
The browse cursor is not moved by a nonbrowse MQGET call using the same Hobj handle. Nor is it moved by a browse MQGET call that returns a completion code of MQCC_FAILED, or a reason code of MQRC_TRUNCATED_MSG_FAILED.
If MQGMO_BROWSE_MSG_UNDER_CURSOR is specified with MQGMO_LOCK:
If MQGMO_BROWSE_MSG_UNDER_CURSOR is specified without MQGMO_LOCK:
If MQGMO_COMPLETE_MSG is specified with MQGMO_BROWSE_MSG_UNDER_CURSOR, the browse cursor must identify a message whose Offset field in MQMD is zero. If this condition is not satisfied, the call fails with reason code MQRC_INVALID_MSG_UNDER_CURSOR.
The group and segment information that the queue manager retains for MQGET calls that browse messages on the queue is separate from the group and segment information that it retains for MQGET calls that remove messages from the queue.
This option is not valid with any of the following options:
It is also an error if the queue was not opened for browse.
The message pointed to by the browse cursor is the one that was last retrieved using either the MQGMO_BROWSE_FIRST or the MQGMO_BROWSE_NEXT option.
If MQGMO_COMPLETE_MSG is specified with MQGMO_MSG_UNDER_CURSOR, the browse cursor must identify a message whose Offset field in MQMD is zero. If this condition is not satisfied, the call fails with reason code MQRC_INVALID_MSG_UNDER_CURSOR.
This option is not valid with any of the following options:
It is also an error if the queue was not opened both for browse and for input. If the browse cursor is not currently pointing to a retrievable message, an error is returned by the MQGET call.
Lock options: The following options relate to locking messages on the queue:
Only one message can be locked for each queue handle, but this can be a logical message or a physical message:
The locked message is always the one under the browse cursor, and the message can be removed from the queue by a later MQGET call that specifies the MQGMO_MSG_UNDER_CURSOR option. Other MQGET calls using the queue handle can also remove the message (for example, a call that specifies the message identifier of the locked message).
If the call returns completion code MQCC_FAILED, or MQCC_WARNING with reason code MQRC_TRUNCATED_MSG_FAILED, no message is locked.
If the application does not remove the message from the queue, the lock is released by:
If you also specify MQGMO_LOCK, the message returned is locked. If you omit MQGMO_LOCK, there is no locked message after the call.
If you specify MQGMO_WAIT, and no message is immediately available, the unlock on the original message occurs before the start of the wait (providing the call is otherwise free from error).
No special open option is required to specify this option, other than MQOO_BROWSE, which is needed to specify the accompanying browse option.
This option is not valid with any of the following options:
The MsgDesc, BufferLength, Buffer, and DataLength parameters are not checked or altered if you specify MQGMO_UNLOCK. No message is returned in Buffer.
No special open option is required to specify this option (although MQOO_BROWSE is needed to issue the lock request in the first place).
This option is not valid with any options except the following:
Both of these options are assumed whether specified or not.
Message-data options: The following options relate to the processing of the message data when the message is read from the queue:
The Format field specified when the message was put is assumed by the conversion process to identify the nature of the data in the message. The message data is converted by the queue manager for built-in formats, and by a user-written exit for other formats. See Appendix F. Data conversion for details of the data-conversion exit.
In either case, these fields describe the character-set identifier and encoding of the message data that is returned in the Buffer parameter.
See the Format field described in MQMD - Message descriptor for a list of format names for which the queue manager performs the conversion.
This option is not supported on z/OS using CICS Version 2.
Group and segment options: The following options relate to the processing of messages in groups and segments of logical messages. Before the option descriptions, here are some definitions of important terms:
A logical message that has been segmented consists of two or more physical messages that have the same nonnull group identifier (GroupId field in MQMD), and the same message sequence number (MsgSeqNumber field in MQMD). The segments are distinguished by differing values for the segment offset (Offset field in MQMD), which gives the offset of the data in the physical message from the start of the data in the logical message. Because each segment is a physical message, the segments in a logical message usually have different message identifiers.
A logical message that has not been segmented, but for which segmentation has been permitted by the sending application, also has a nonnull group identifier, although in this case there is only one physical message with that group identifier if the logical message does not belong to a message group. Logical messages for which segmentation has been inhibited by the sending application have a null group identifier (MQGI_NONE), unless the logical message belongs to a message group.
If MQGMO_LOGICAL_ORDER is specified for successive MQGET calls for the queue handle, messages in groups are returned in the order given by their message sequence numbers, and segments of logical messages are returned in the order given by their segment offsets. This order might be different from the order in which those messages and segments occur on the queue.
To return the messages in the required order, the queue manager retains the group and segment information between successive MQGET calls. This information identifies the current message group and current logical message for the queue handle, the current position within the group and logical message, and whether the messages are being retrieved within a unit of work. Because the queue manager retains this information, the application does not need to set the group and segment information before each MQGET call. Specifically, it means that the application does not need to set the GroupId, MsgSeqNumber, and Offset fields in MQMD. However, the application must set the MQGMO_SYNCPOINT or MQGMO_NO_SYNCPOINT option correctly on each call.
When the queue is opened, there is no current message group and no current logical message. A message group becomes the current message group when a message that has the MQMF_MSG_IN_GROUP flag is returned by the MQGET call. With MQGMO_LOGICAL_ORDER specified on successive calls, that group remains the current group until a message is returned that has:
When such a message is returned, the message group is terminated, and on successful completion of that MQGET call there is no longer a current group. In a similar way, a logical message becomes the current logical message when a message that has the MQMF_SEGMENT flag is returned by the MQGET call, and that logical message is terminated when the message that has the MQMF_LAST_SEGMENT flag is returned.
If no selection criteria are specified, successive MQGET calls return (in the correct order) the messages for the first message group on the queue, then the messages for the second message group, and so on, until there are no more messages available. It is possible to select the particular message groups returned by specifying one or more of the following options in the MatchOptions field:
However, these options are effective only when there is no current message group or logical message; see the MatchOptions field described in MQGMO - Get-message options for further details.
Table 38 shows the values of the MsgId, CorrelId, GroupId, MsgSeqNumber, and Offset fields that the queue manager looks for when attempting to find a message to return on the MQGET call. This applies both to removing messages from the queue, and browsing messages on the queue. In the table, Either means Yes or No:
Options you specify | Group and log-msg status prior to call | Values the queue manager looks for | |||||
---|---|---|---|---|---|---|---|
LOG ORD | Cur grp | Cur log msg | MsgId | CorrelId | GroupId | MsgSeqNumber | Offset |
Yes | No | No | Controlled by MatchOptions | Controlled by MatchOptions | Controlled by MatchOptions | 1 | 0 |
Yes | No | Yes | Any message identifier | Any correlation identifier | Previous group identifier | 1 | Previous offset + previous segment length |
Yes | Yes | No | Any message identifier | Any correlation identifier | Previous group identifier | Previous sequence number + 1 | 0 |
Yes | Yes | Yes | Any message identifier | Any correlation identifier | Previous group identifier | Previous sequence number | Previous offset + previous segment length |
No | Either | Either | Controlled by MatchOptions | Controlled by MatchOptions | Controlled by MatchOptions | Controlled by MatchOptions | Controlled by MatchOptions |
When multiple message groups are present on the queue and eligible for return, the groups are returned in the order determined by the position on the queue of the first segment of the first logical message in each group (that is, the physical messages that have message sequence numbers of 1, and offsets of 0, determine the order in which eligible groups are returned).
The MQGMO_LOGICAL_ORDER option affects units of work as follows:
If these conditions are not satisfied, the MQGET call fails with reason code MQRC_INCONSISTENT_UOW.
When MQGMO_LOGICAL_ORDER is specified, the MQGMO supplied on the MQGET call must not be less than MQGMO_VERSION_2, and the MQMD must not be less than MQMD_VERSION_2. If this condition is not satisfied, the call fails with reason code MQRC_WRONG_GMO_VERSION or MQRC_WRONG_MD_VERSION, as appropriate.
If MQGMO_LOGICAL_ORDER is not specified for successive MQGET calls for the queue handle, messages are returned without regard for whether they belong to message groups, or whether they are segments of logical messages. This means that messages or segments from a particular group or logical message might be returned out of order, or intermingled with messages or segments from other groups or logical messages, or with messages that are not in groups and are not segments. In this situation, the particular messages that are returned by successive MQGET calls is controlled by the MQMO_* options specified on those calls (see the MatchOptions field described in MQGMO - Get-message options for details of these options).
This is the technique that can be used to restart a message group or logical message in the middle, after a system failure has occurred. When the system restarts, the application can set the GroupId, MsgSeqNumber, Offset, and MatchOptions fields to the appropriate values, and then issue the MQGET call with MQGMO_SYNCPOINT or MQGMO_NO_SYNCPOINT set, but without specifying MQGMO_LOGICAL_ORDER. If this call is successful, the queue manager retains the group and segment information, and subsequent MQGET calls using that queue handle can specify MQGMO_LOGICAL_ORDER as normal.
The group and segment information that the queue manager retains for the MQGET call is separate from the group and segment information that it retains for the MQPUT call. In addition, the queue manager retains separate information for:
For any given queue handle, the application can mix MQGET calls that specify MQGMO_LOGICAL_ORDER with MQGET calls that do not. However, note the following points:
Current call is | Previous call was MQGET with MQGMO_LOGICAL_ORDER | Previous call was MQGET without MQGMO_LOGICAL_ORDER |
---|---|---|
MQGET with MQGMO_LOGICAL_ORDER | MQCC_FAILED | MQCC_FAILED |
MQGET without MQGMO_LOGICAL_ORDER | MQCC_WARNING | MQCC_OK |
MQCLOSE with an unterminated group or logical message | MQCC_WARNING | MQCC_OK |
Applications that want to retrieve messages and segments in logical order are recommended to specify MQGMO_LOGICAL_ORDER, as this is the simplest option to use. This option relieves the application of the need to manage the group and segment information, because the queue manager manages that information. However, specialized applications might need more control than that provided by the MQGMO_LOGICAL_ORDER option, and this can be achieved by not specifying that option. The application must then ensure that the MsgId, CorrelId, GroupId, MsgSeqNumber, and Offset fields in MQMD, and the MQMO_* options in MatchOptions in MQGMO, are set correctly, before each MQGET call.
For example, an application that wants to forward physical messages that it receives, without regard for whether those messages are in groups or segments of logical messages, must not specify MQGMO_LOGICAL_ORDER. In a complex network with multiple paths between sending and receiving queue managers, the physical messages might arrive out of order. By specifying neither MQGMO_LOGICAL_ORDER, nor the corresponding MQPMO_LOGICAL_ORDER on the MQPUT call, the forwarding application can retrieve and forward each physical message as soon as it arrives, without having to wait for the next one in logical order to arrive.
You can specify MQGMO_LOGICAL_ORDER with any of the other MQGMO_* options, and with various of the MQMO_* options in appropriate circumstances (see above).
To use this option, the application must provide a buffer that is big enough to accommodate the complete message, or specify the MQGMO_ACCEPT_TRUNCATED_MSG option.
If the queue contains segmented messages with some of the segments missing (perhaps because they have been delayed in the network and have not yet arrived), specifying MQGMO_COMPLETE_MSG prevents the retrieval of segments belonging to incomplete logical messages. However, those message segments still contribute to the value of the CurrentQDepth queue attribute; this means that there might be no retrievable logical messages, even though CurrentQDepth is greater than zero.
For persistent messages, the queue manager can reassemble the segments only within a unit of work:
For nonpersistent messages, the queue manager does not require a unit of work to be available to perform reassembly.
Each physical message that is a segment has its own message descriptor. For the segments constituting a single logical message, most of the fields in the message descriptor sre the same for all segments in the logical message; usually it is only the MsgId, Offset, and MsgFlags fields that differ between segments in the logical message. However, if a segment is placed on a dead-letter queue at an intermediate queue manager, the DLQ handler retrieves the message specifying the MQGMO_CONVERT option, and this can result in the character set or encoding of the segment being changed. If the DLQ handler successfully sends the segment on its way, the segment might have a character set or encoding that differs from the other segments in the logical message when the segment arrives at the destination queue manager.
A logical message consisting of segments in which the CodedCharSetId and Encoding fields differ cannot be reassembled by the queue manager into a single logical message. Instead, the queue manager reassembles and returns the first few consecutive segments at the start of the logical message that have the same character-set identifiers and encodings, and the MQGET call completes with completion code MQCC_WARNING and reason code MQRC_INCONSISTENT_CCSIDS or MQRC_INCONSISTENT_ENCODINGS, as appropriate. This happens regardless of whether MQGMO_CONVERT is specified. To retrieve the remaining segments, the application must reissue the MQGET call without the MQGMO_COMPLETE_MSG option, retrieving the segments one by one. MQGMO_LOGICAL_ORDER can be used to retrieve the remaining segments in order.
An application that puts segments can also set other fields in the message descriptor to values that differ between segments. However, there is no advantage in doing this if the receiving application uses MQGMO_COMPLETE_MSG to retrieve the logical message. When the queue manager reassembles a logical message, it returns in the message descriptor the values from the message descriptor for the first segment; the only exception is the MsgFlags field, which the queue manager sets to indicate that the reassembled message is the only segment.
If MQGMO_COMPLETE_MSG is specified for a report message, the queue manager performs special processing. The queue manager checks the queue to see if all the report messages of that report type relating to the different segments in the logical message are present on the queue. If they are, they can be retrieved as a single message by specifying MQGMO_COMPLETE_MSG. For this to be possible, either the report messages must be generated by a queue manager or MCA which supports segmentation, or the originating application must request at least 100 bytes of message data (that is, the appropriate MQRO_*_WITH_DATA or MQRO_*_WITH_FULL_DATA options must be specified). If less than the full amount of application data is present for a segment, the missing bytes are replaced by nulls in the report message returned.
If MQGMO_COMPLETE_MSG is specified with MQGMO_MSG_UNDER_CURSOR or MQGMO_BROWSE_MSG_UNDER_CURSOR, the browse cursor must be positioned on a message whose Offset field in MQMD has a value of 0. If this condition is not satisfied, the call fails with reason code MQRC_INVALID_MSG_UNDER_CURSOR.
MQGMO_COMPLETE_MSG implies MQGMO_ALL_SEGMENTS_AVAILABLE, which need not therefore be specified.
MQGMO_COMPLETE_MSG can be specified with any of the other MQGMO_* options apart from MQGMO_SYNCPOINT_IF_PERSISTENT, and with any of the MQMO_* options apart from MQMO_MATCH_OFFSET.
The processing of MQGMO_ALL_MSGS_AVAILABLE depends on whether MQGMO_LOGICAL_ORDER is also specified:
Successful completion of an MQGET call specifying MQGMO_ALL_MSGS_AVAILABLE means that at the time that the MQGET call was issued, all the messages in the group were on the queue. However, be aware that other applications can still remove messages from the group (the group is not locked to the application that retrieves the first message in the group).
If you omit this option, messages belonging to groups can be retrieved even when the group is incomplete.
MQGMO_ALL_MSGS_AVAILABLE implies MQGMO_ALL_SEGMENTS_AVAILABLE, which need not therefore be specified.
MQGMO_ALL_MSGS_AVAILABLE can be specified with any of the other MQGMO_* options, and with any of the MQMO_* options.
The processing of MQGMO_ALL_SEGMENTS_AVAILABLE depends on whether MQGMO_LOGICAL_ORDER is also specified:
If this option is not specified, message segments can be retrieved even when the logical message is incomplete.
While both MQGMO_COMPLETE_MSG and MQGMO_ALL_SEGMENTS_AVAILABLE require all segments to be available before any of them can be retrieved, the former returns the complete message, whereas the latter allows the segments to be retrieved one by one.
If MQGMO_ALL_SEGMENTS_AVAILABLE is specified for a report message, the queue manager checks the queue to see if there is at least one report message for each of the segments that comprise the complete logical message. If there is, the MQGMO_ALL_SEGMENTS_AVAILABLE condition is satisfied. However, the queue manager does not check the type of the report messages present, and so there might be a mixture of report types in the report messages relating to the segments of the logical message. As a result, the success of MQGMO_ALL_SEGMENTS_AVAILABLE does not imply that MQGMO_COMPLETE_MSG will succeed. If there is a mixture of report types present for the segments of a particular logical message, those report messages must be retrieved one by one.
You can specify MQGMO_ALL_SEGMENTS_AVAILABLE with any of the other MQGMO_* options, and with any of the MQMO_* options.
Default option: If none of the options described above is required, the following option can be used:
The initial value of the Options field is MQGMO_NO_WAIT.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
js00862 |