Options that control the action of MQGET.
Zero or more of the options described below can be specified. If more than one is required the values can be added together (do not add the same constant more than once). 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:
The application is to wait until a suitable message arrives. The maximum time the application waits is specified in GMWI.
If MQGET requests are inhibited, or MQGET requests become inhibited while waiting, the wait is canceled and the call completes with CCFAIL and reason code RC2016, regardless of whether there are suitable messages on the queue.
This option can be used with the GMBRWF or GMBRWN options.
If several applications are waiting on the same shared queue, the application, or applications, that are activated when a suitable message arrives are described below.
The following points should be noted:
GMWT is ignored if specified with GMBRWC or GMMUC; no error is raised.
The application is not to wait if no suitable message is available. This is the opposite of the GMWT option, and is defined to aid program documentation. It is the default if neither is specified.
This option forces the MQGET call to fail if the queue manager is in the quiescing state.
If this option is specified together with GMWT, and the wait is outstanding at the time the queue manager enters the quiescing state:
If GMFIQ is not specified and the queue manager enters the quiescing state, the wait is not canceled.
Syncpoint options: The following options relate to the participation of the MQGET call within a unit of work:
The request is to operate within the normal unit-of-work protocols. The message is marked as being unavailable to other applications, but it is deleted from the queue only when the unit of work is committed. The message is made available again if the unit of work is backed out.
If neither this option nor GMNSYP is specified, the get request is not within a unit of work.
This option is not valid with any of the following options:
The request is to operate within the normal unit-of-work protocols, but only if the message retrieved is persistent. A persistent message has the value PEPER in the MDPER field in MQMD.
This option is not valid with any of the following options:
The request is to operate outside the normal unit-of-work protocols. The message is deleted from the queue immediately (unless this is a browse request). The message cannot be made available again by backing out the unit of work.
This option is assumed if GMBRWF or GMBRWN is specified.
If neither this option nor GMSYP is specified, the get request is not within a unit of work.
This option is not valid with any of the following options:
Browse options: The following options relate to browsing messages on the queue:
When a queue is opened with the OOBRW option, a browse cursor is established, positioned logically before the first message on the queue. Subsequent MQGET calls specifying the GMBRWF, GMBRWN or GMBRWC option can be used to retrieve messages from the queue nondestructively. The browse cursor marks the position, within the messages on the queue, from which the next MQGET call with GMBRWN will search for a suitable message.
An MQGET call with GMBRWF causes the previous position of the browse cursor to be ignored. 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 GMBRWN is issued, the browse cursor remains at the position in the queue that the message occupied, even though that position is now empty.
The GMMUC option can subsequently be used with a nonbrowse MQGET call if required, to remove the message from the queue.
Note that 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 CCFAIL, or a reason code of RC2080.
The GMLK option can be specified together with this option, to cause the message that is browsed to be locked.
GMBRWF can be specified with any valid combination of the GM* and MO* options that control the processing of messages in groups and segments of logical messages.
If GMLOGO is specified, the messages are browsed in logical order. If that option is omitted, the messages are browsed in physical order. When GMBRWF is specified, it is possible to switch between logical order and physical order, but subsequent MQGET calls using GMBRWN must browse the queue in the same order as the most recent call that specified GMBRWF 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 GMBRWF is specified, 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 CCOK or CCWARN), 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 prior to 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.
The browse cursor is advanced to the next message on the queue that satisfies the selection criteria specified on the MQGET call. The message is returned to the application, but remains on the queue.
After a queue has been opened for browse, the first browse call using the handle has the same effect whether it specifies the GMBRWF or GMBRWN option.
If the message is removed from the queue before the next MQGET call with GMBRWN 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 MSPRIO, 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 will not be found during the current sweep of the queue using GMBRWN. It can only be found after the browse cursor has been reset with GMBRWF (or by reopening the queue).
The GMMUC option can subsequently be used with a nonbrowse MQGET call if required, to remove the message from the queue.
Note that the browse cursor is not moved by nonbrowse MQGET calls using the same HOBJ handle.
The GMLK option can be specified together with this option, to cause the message that is browsed to be locked.
GMBRWN can be specified with any valid combination of the GM* and MO* options that control the processing of messages in groups and segments of logical messages.
If GMLOGO is specified, the messages are browsed in logical order. If that option is omitted, the messages are browsed in physical order. When GMBRWF is specified, it is possible to switch between logical order and physical order, but subsequent MQGET calls using GMBRWN must browse the queue in the same order as the most recent call that specified GMBRWF for the queue handle. The call fails with reason code RC2259 if this condition is not satisfied.
The possibility of an infinite loop can be avoided by opening 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.
This option causes the message pointed to by the browse cursor to be retrieved nondestructively, regardless of the MO* options specified in the GMMO field in MQGMO.
The message pointed to by the browse cursor is the one that was last retrieved using either the GMBRWF or the GMBRWN 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 GMMUC option can subsequently be used with a nonbrowse MQGET call if required, to remove the message from the queue.
Note that 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 CCFAIL, or a reason code of RC2080.
If GMBRWC is specified with GMLK:
If GMBRWC is specified without GMLK:
If GMCMPM is specified with GMBRWC, the browse cursor must identify a message whose MDOFF field in MQMD is zero. If this condition is not satisfied, the call fails with reason code RC2246.
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.
This option causes the message pointed to by the browse cursor to be retrieved, regardless of the MO* options specified in the GMMO field in MQGMO. The message is removed from the queue.
The message pointed to by the browse cursor is the one that was last retrieved using either the GMBRWF or the GMBRWN option.
If GMCMPM is specified with GMMUC, the browse cursor must identify a message whose MDOFF field in MQMD is zero. If this condition is not satisfied, the call fails with reason code RC2246.
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:
This option locks the message that is browsed, so that the message becomes invisible to any other handle open for the queue. The option can be specified only if one of the following options is also specified:
Only one message can be locked per 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 GMMUC 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 CCFAIL, or CCWARN with reason code RC2080, no message is locked.
If the application decides not to remove the message from the queue, the lock is released by:
If GMLK is also specified, the message returned is locked. If GMLK is not specified, there is no locked message after the call.
If GMWT is specified, 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 OOBRW, which is needed in order to specify the accompanying browse option.
This option is not valid with any of the following options:
The message to be unlocked must have been previously locked by an MQGET call with the GMLK option. If there is no message locked for this handle, the call completes with CCWARN and RC2209.
The MSGDSC, BUFLEN, BUFFER, and DATLEN parameters are not checked or altered if GMUNLK is specified. No message is returned in BUFFER.
No special open option is required to specify this option (although OOBRW 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:
If the message buffer is too small to hold the complete message, this option allows the MQGET call to fill the buffer with as much of the message as the buffer can hold, issue a warning completion code, and complete its processing. This means:
Without this option, the buffer is still filled with as much of the message as it can hold, a warning completion code is issued, but processing is not completed. This means:
This option requests that the application data in the message should be converted, to conform to the MDCSI and MDENC values specified in the MSGDSC parameter on the MQGET call, before the data is copied to the BUFFER parameter.
The MDFMT field specified when the message was put is assumed by the conversion process to identify the nature of the data in the message. Conversion of the message data is by the queue manager for built-in formats, and by a user-written exit for other formats.
In either case, therefore, these fields describe the character-set identifier and encoding of the message data that is returned in the BUFFER parameter.
See the MDFMT field described in MQMD - Message descriptor for a list of format names for which the queue manager performs the conversion.
Group and segment options: The following options relate to the processing of messages in groups and segments of logical messages. These definitions may be of help in understanding the options:
A logical message that has been segmented consists of two or more physical messages that have the same nonnull group identifier (MDGID field in MQMD), and the same message sequence number (MDSEQ field in MQMD). The segments are distinguished by differing values for the segment offset (MDOFF 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 differing 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 (GINONE), unless the logical message belongs to a message group.
This option controls the order in which messages are returned by successive MQGET calls for the queue handle. The option must be specified on each of those calls in order to have an effect.
If GMLOGO 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 may 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 prior to each MQGET call. Specifically, it means that the application does not need to set the MDGID, MDSEQ, and MDOFF fields in MQMD. However, the application does need to set the GMSYP or GMNSYP 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 MFMIG flag is returned by the MQGET call. With GMLOGO 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 MFSEG flag is returned by the MQGET call, and that logical message is terminated when the message that has the MFLSEG 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 GMMO field:
However, these options are effective only when there is no current message group or logical message; see the GMMO field described in MQGMO - Get-message options for further details.
Table 16 shows the values of the MDMID, MDCID, MDGID, MDSEQ, and MDOFF 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. The columns in the table have the following meanings:
Options you specify | Group and log-msg status prior to call | Values the queue manager looks for | |||||
---|---|---|---|---|---|---|---|
LOG ORD | Cur grp | Cur log msg | MDMID | MDCID | MDGID | MDSEQ | MDOFF |
Yes | No | No | Controlled by GMMO | Controlled by GMMO | Controlled by GMMO | 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 GMMO | Controlled by GMMO | Controlled by GMMO | Controlled by GMMO | Controlled by GMMO |
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 GMLOGO option affects units of work as follows:
If these conditions are not satisfied, the MQGET call fails with reason code RC2245.
When GMLOGO is specified, the MQGMO supplied on the MQGET call must not be less than GMVER2, and the MQMD must not be less than MDVER2. If this condition is not satisfied, the call fails with reason code RC2256 or RC2257, as appropriate.
If GMLOGO 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 may be returned out of order, or they may be 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 MO* options specified on those calls (see the GMMO 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 MDGID, MDSEQ, MDOFF, and GMMO fields to the appropriate values, and then issue the MQGET call with GMSYP or GMNSYP set as desired, but without specifying GMLOGO. If this call is successful, the queue manager retains the group and segment information, and subsequent MQGET calls using that queue handle can specify GMLOGO 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 is free to mix MQGET calls that specify GMLOGO with MQGET calls that do not, but the following points should be noted:
Current call is | Previous call was MQGET with GMLOGO | Previous call was MQGET without GMLOGO |
---|---|---|
MQGET with GMLOGO | CCFAIL | CCFAIL |
MQGET without GMLOGO | CCWARN | CCOK |
MQCLOSE with an unterminated group or logical message | CCWARN | CCOK |
Applications that simply want to retrieve messages and segments in logical order are recommended to specify GMLOGO, 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 may need more control than provided by the GMLOGO option, and this can be achieved by not specifying that option. If this is done, the application must ensure that the MDMID, MDCID, MDGID, MDSEQ, and MDOFF fields in MQMD, and the MO* options in GMMO in MQGMO, are set correctly, prior to 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, should not specify GMLOGO. This is because in a complex network with multiple paths between sending and receiving queue managers, the physical messages may arrive out of order. By specifying neither GMLOGO, nor the corresponding PMLOGO 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.
GMLOGO can be specified with any of the other GM* options, and with various of the MO* options in appropriate circumstances (see above).
This option specifies that only a complete logical message can be returned by the MQGET call. If the logical message is segmented, the queue manager reassembles the segments and returns the complete logical message to the application; the fact that the logical message was segmented is not apparent to the application retrieving it.
To use this option, the application must provide a buffer which is big enough to accommodate the complete message, or specify the GMATM 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 GMCMPM 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 may 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 in order 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 will be the same for all segments in the logical message - usually it is only the MDMID, MDOFF, and MDMFL 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 GMCONV option, and this may 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 may have a character set or encoding that differs from the other segments in the logical message when the segment finally arrives at the destination queue manager.
A logical message consisting of segments in which the MDCSI and/or MDENC 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 CCWARN and reason code RC2243 or RC2244, as appropriate. This happens regardless of whether GMCONV is specified. To retrieve the remaining segments, the application must reissue the MQGET call without the GMCMPM option, retrieving the segments one by one. GMLOGO can be used to retrieve the remaining segments in order.
It is also possible for an application which puts segments to 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 GMCMPM 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 MDMFL field, which the queue manager sets to indicate that the reassembled message is the only segment.
If GMCMPM is specified for a report message, the queue manager performs special processing. The queue manager checks the queue to see if all of 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 GMCMPM. 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 RO*D or RO*F 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 GMCMPM is specified with GMMUC or GMBRWC, the browse cursor must be positioned on a message whose MDOFF field in MQMD has a value of 0. If this condition is not satisfied, the call fails with reason code RC2246.
GMCMPM implies GMASGA, which need not therefore be specified.
GMCMPM can be specified with any of the other GM* options apart from GMPSYP, and with any of the MO* options apart from MOOFFS.
This option specifies that messages in a group become available for retrieval only when all messages in the group are available. If the queue contains message groups with some of the messages missing (perhaps because they have been delayed in the network and have not yet arrived), specifying GMAMSA prevents retrieval of messages belonging to incomplete groups. However, those messages still contribute to the value of the CurrentQDepth queue attribute; this means that there may be no retrievable message groups, even though CurrentQDepth is greater than zero. If there are no other messages that are retrievable, reason code RC2033 is returned after the specified wait interval (if any) has expired.
The processing of GMAMSA depends on whether GMLOGO is also specified:
Successful completion of an MQGET call specifying GMAMSA means that at the time that the MQGET call was issued, all of the messages in the group were on the queue. However, be aware that other applications are still able to remove messages from the group (the group is not locked to the application that retrieves the first message in the group).
If this option is not specified, messages belonging to groups can be retrieved even when the group is incomplete.
GMAMSA implies GMASGA, which need not therefore be specified.
GMAMSA can be specified with any of the other GM* options, and with any of the MO* options.
This option specifies that segments in a logical message become available for retrieval only when all segments in the logical message are available. 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 GMASGA prevents retrieval of segments belonging to incomplete logical messages. However those segments still contribute to the value of the CurrentQDepth queue attribute; this means that there may be no retrievable logical messages, even though CurrentQDepth is greater than zero. If there are no other messages that are retrievable, reason code RC2033 is returned after the specified wait interval (if any) has expired.
The processing of GMASGA depends on whether GMLOGO is also specified:
If this option is not specified, message segments can be retrieved even when the logical message is incomplete.
While both GMCMPM and GMASGA 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 GMASGA is specified for a report message, the queue manager performs special processing. 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 GMASGA condition is satisfied. However, the queue manager does not check the type of the report messages present, and so there may be a mixture of report types in the report messages relating to the segments of the logical message. As a result, the success of GMASGA does not imply that GMCMPM 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.
GMASGA can be specified with any of the other GM* options, and with any of the MO* options.
Default option: If none of the options described above is required, the following option can be used:
This value can be used to indicate that no other options have been specified; all options assume their default values. GMNONE is defined to aid program documentation; it is not intended that this option be used with any other, but as its value is zero, such use cannot be detected.
The initial value of the GMOPT field is GMNWT.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
js50730 |