GMOPT (10-digit signed integer)

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:

GMWT

Wait for message to arrive.

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.

Note:
In the description below, a browse MQGET call is one which specifies one of the browse options, but not GMLK; an MQGET call specifying the GMLK option is treated as a nonbrowse call.

  • If one or more nonbrowse MQGET calls is waiting, but no browse MQGET calls are waiting, one is activated.

  • If one or more browse MQGET calls is waiting, but no nonbrowse MQGET calls are waiting, all are activated.

  • If one or more nonbrowse MQGET calls, and one or more browse MQGET calls are waiting, one nonbrowse MQGET call is activated, and none, some, or all of the browse MQGET calls. (The number of browse MQGET calls activated cannot be predicted, because it depends on the scheduling considerations of the operating system, and other factors.)

If more than one nonbrowse MQGET call is waiting on the same queue, only one is activated; in this situation the queue manager attempts to give priority to waiting nonbrowse calls in the following order:

  1. Specific get-wait requests that can be satisfied only by certain messages, for example, ones with a specific MDMID or MDCID (or both).

  2. General get-wait requests that can be satisfied by any message.

The following points should be noted:

  • Within the first category, no additional priority is given to more specific get-wait requests, for example those that specify both MDMID and MDCID.

  • Within either category, it cannot be predicted which application is selected. In particular, the application waiting longest is not necessarily the one selected.

  • Path length, and priority-scheduling considerations of the operating system, can mean that a waiting application of lower operating system priority than expected retrieves the message.

  • It may also happen that an application that is not waiting retrieves the message in preference to one that is.

GMWT is ignored if specified with GMBRWC or GMMUC; no error is raised.

GMNWT

Return immediately if no suitable message.

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.

GMFIQ

Fail if queue manager is quiescing.

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:

  • The wait is canceled and the call returns completion code CCFAIL with reason code RC2161.

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:

GMSYP

Get message with syncpoint control.

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:

  • GMBRWF

  • GMBRWC

  • GMBRWN

  • GMLK

  • GMNSYP

  • GMPSYP

  • GMUNLK

GMPSYP

Get message with syncpoint control if message is persistent.

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.

  • If the message is persistent, the queue manager processes the call as though the application had specified GMSYP (see above for details).

  • If the message is not persistent, the queue manager processes the call as though the application had specified GMNSYP (see below for details).

This option is not valid with any of the following options:

  • GMBRWF

  • GMBRWC

  • GMBRWN

  • GMCMPM

  • GMNSYP

  • GMSYP

  • GMUNLK

GMNSYP

Get message without syncpoint control.

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:

  • GMSYP

  • GMPSYP

Browse options: The following options relate to browsing messages on the queue:

GMBRWF

Browse from start of 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:

  • GMBRWC

  • GMBRWN

  • GMMUC

  • GMSYP

  • GMPSYP

  • GMUNLK

It is also an error if the queue was not opened for browse.

GMBRWN

Browse from current position in queue.

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:

  • FIFO within priority (MSPRIO), or

  • FIFO regardless of priority (MSFIFO)

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.

Note:
Special care is needed if an MQGET call is used to browse beyond the end of a message group (or logical message not in a group) when GMLOGO is not specified. For example, if the last message in the group happens to precede the first message in the group on the queue, using GMBRWN to browse beyond the end of the group, specifying MOSEQN with MDSEQ set to 1 (to find the first message of the next group) would return again the first message in the group already browsed. This could happen immediately, or a number of MQGET calls later (if there are intervening groups).

The possibility of an infinite loop can be avoided by opening the queue twice for browse:

  • Use the first handle to browse only the first message in each group.

  • Use the second handle to browse only the messages within a specific group.

  • Use the MO* options to move the second browse cursor to the position of the first browse cursor, before browsing the messages in the group.

  • Do not use GMBRWN to browse beyond the end of a group.

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:

  • GMBRWF

  • GMBRWC

  • GMMUC

  • GMSYP

  • GMPSYP

  • GMUNLK

It is also an error if the queue was not opened for browse.

GMBRWC

Browse message under browse cursor.

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 there is already a message locked, it must be the one under the cursor, so that is returned without unlocking and relocking it; the message remains locked.

  • If there is no locked message, the message under the browse cursor (if there is one) is locked and returned to the application; if there is no message under the browse cursor the call fails.

If GMBRWC is specified without GMLK:

  • If there is already a message locked, it must be the one under the cursor. This message is returned to the application and then unlocked. Because the message is now unlocked, there is no guarantee that it can be browsed again, or retrieved destructively (it may be retrieved destructively by another application getting messages from the queue).

  • If there is no locked message, the message under the browse cursor (if there is one) is returned to the application; if there is no message under the browse cursor the call fails.

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:

  • GMBRWF

  • GMBRWN

  • GMMUC

  • GMSYP

  • GMPSYP

  • GMUNLK

It is also an error if the queue was not opened for browse.

GMMUC

Get message under browse cursor.

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:

  • GMBRWF

  • GMBRWC

  • GMBRWN

  • GMUNLK

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:

GMLK

Lock message.

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:

  • GMBRWF

  • GMBRWN

  • GMBRWC

Only one message can be locked per queue handle, but this can be a logical message or a physical message:

  • If GMCMPM is specified, all of the message segments that comprise the logical message are locked to the queue handle (provided that they are all present on the queue and available for retrieval).

  • If GMCMPM is not specified, only a single physical message is locked to the queue handle. If this message happens to be a segment of a logical message, the locked segment prevents other applications using GMCMPM to retrieve or browse the logical 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:

  • Issuing another MQGET call for this handle, with either GMBRWF or GMBRWN specified (with or without GMLK); the message is unlocked if the call completes with CCOK or CCWARN, but remains locked if the call completes with CCFAIL. However, the following exceptions apply:

    • The message is not unlocked if CCWARN is returned with RC2080.

    • The message is unlocked if CCFAIL is returned with RC2033.

    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).

  • Issuing another MQGET call for this handle, with GMBRWC (without GMLK); the message is unlocked if the call completes with CCOK or CCWARN, but remains locked if the call completes with CCFAIL. However, the following exception applies:

    • The message is not unlocked if CCWARN is returned with RC2080.

  • Issuing another MQGET call for this handle with GMUNLK.

  • Issuing an MQCLOSE call for this handle (either explicitly, or implicitly by the application ending).

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:

  • GMSYP

  • GMPSYP

  • GMUNLK

GMUNLK

Unlock message.

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:

  • GMNWT

  • GMNSYP

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:

GMATM

Allow truncation of message data.

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:

  • When browsing messages, the browse cursor is advanced to the returned message.

  • When removing messages, the returned message is removed from the queue.

  • Reason code RC2079 is returned if no other error occurs.

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:

  • When browsing messages, the browse cursor is not advanced.

  • When removing messages, the message is not removed from the queue.

  • Reason code RC2080 is returned if no other error occurs.

GMCONV

Convert message data.

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.

  • If conversion is performed successfully, the MDCSI and MDENC fields specified in the MSGDSC parameter are unchanged on return from the MQGET call.

  • If conversion cannot be performed successfully (but the MQGET call otherwise completes without error), the message data is returned unconverted, and the MDCSI and MDENC fields in MSGDSC are set to the values for the unconverted message. The completion code is CCWARN in this case.

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:

Physical message

This is the smallest unit of information that can be placed on or removed from a queue; it often corresponds to the information specified or retrieved on a single MQPUT, MQPUT1, or MQGET call. Every physical message has its own message descriptor (MQMD). Generally, physical messages are distinguished by differing values for the message identifier (MDMID field in MQMD), although this is not enforced by the queue manager.

Logical message

This is a single unit of application information. In the absence of system constraints, a logical message would be the same as a physical message. But where logical messages are extremely large, system constraints may make it advisable or necessary to split a logical message into two or more physical messages, called segments.

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.

Message group

This is a set of one or more logical messages that have the same nonnull group identifier. The logical messages in the group are distinguished by differing values for the message sequence number, which is an integer in the range 1 through n, where n is the number of logical messages in the group. If one or more of the logical messages is segmented, there will be more than n physical messages in the group.

GMLOGO

Messages in groups and segments of logical messages are returned in logical order.

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.

Note:
Specifying GMLOGO has no adverse consequences on messages that do not belong to groups and that are not segments. In effect, such messages are treated as though each belonged to a message group consisting of only one message. Thus it is perfectly safe to specify GMLOGO when retrieving messages from queues that may contain a mixture of messages in groups, message segments, and unsegmented messages not in groups.

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:

  • MFLMIG without MFSEG (that is, the last logical message in the group is not segmented), or

  • MFLMIG with MFLSEG (that is, the message returned is the last segment of the last logical message in the group).

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:

  • MOMSGI

  • MOCORI

  • MOGRPI

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:

LOG ORD

Indicates whether the GMLOGO option is specified on the call.

Cur grp

Indicates whether a current message group exists prior to the call.

Cur log msg

Indicates whether a current logical message exists prior to the call.

Other columns

Show the values that the queue manager looks for. "Previous" denotes the value returned for the field in the previous message for the queue handle.
Table 16. MQGET options relating to messages in groups and segments of logical messages
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 the first logical message or segment in a group is retrieved within a unit of work, all of the other logical messages and segments in the group must be retrieved within a unit of work, if the same queue handle is used. However, they need not be retrieved within the same unit of work. This allows a message group consisting of many physical messages to be split across two or more consecutive units of work for the queue handle.

  • If the first logical message or segment in a group is not retrieved within a unit of work, none of the other logical messages and segments in the group can be retrieved within a unit of work, if the same queue handle is used.

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:

  • MQGET calls that remove messages from the queue.

  • MQGET calls that browse messages on the queue.

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:

  • If GMLOGO is not specified, each successful MQGET call causes the queue manager to set the saved group and segment information to the values corresponding to the message returned; this replaces the existing group and segment information retained by the queue manager for the queue handle. Only the information appropriate to the action of the call (browse or remove) is modified.

  • If GMLOGO is not specified, the call does not fail if there is a current message group or logical message; the call may however succeed with a CCWARN completion code. Table 17 shows the various cases that can arise. In these cases, if the completion code is not CCOK, the reason code is one of the following:

    • RC2241

    • RC2242

    • RC2245

    Note:
    The queue manager does not check the group and segment information when browsing a queue, or when closing a queue that was opened for browse but not input; in those cases the completion code is always CCOK (assuming no other errors).

Table 17. Outcome when MQGET or MQCLOSE call is not consistent with group and segment information
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).

GMCMPM

Only complete logical messages are retrievable.

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.

Note:
This is the only option that causes the queue manager to reassemble message segments. If not specified, segments are returned individually to the application if they are present on the queue (and they satisfy the other selection criteria specified on the MQGET call). Applications that do not wish to receive individual segments should therefore always specify GMCMPM.

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:

  • If the MQGET call is operating within a user-defined unit of work, that unit of work is used. If the call fails partway through the reassembly process, the queue manager reinstates on the queue any segments that were removed during reassembly. However, the failure does not prevent the unit of work being committed successfully.

  • If the call is operating outside a user-defined unit of work, and there is no user-defined unit of work in existence, the queue manager creates a unit of work just for the duration of the call. If the call is successful, the queue manager commits the unit of work automatically (the application does not need to do this). If the call fails, the queue manager backs out the unit of work.

  • If the call is operating outside a user-defined unit of work, but a user-defined unit of work does exist, the queue manager is unable to perform reassembly. If the message does not require reassembly, the call can still succeed. But if the message does require reassembly, the call fails with reason code RC2255.

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.

GMAMSA

All messages in group must be available.

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:

  • If both options are specified, GMAMSA has an effect only when there is no current group or logical message. If there is a current group or logical message, GMAMSA is ignored. This means that GMAMSA can remain on when processing messages in logical order.

  • If GMAMSA is specified without GMLOGO, GMAMSA always has an effect. This means that the option must be turned off after the first message in the group has been removed from the queue, in order to be able to remove the remaining messages in the group.

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.

GMASGA

All segments in a logical message must be available.

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 both options are specified, GMASGA has an effect only when there is no current logical message. If there is a current logical message, GMASGA is ignored. This means that GMASGA can remain on when processing messages in logical order.

  • If GMASGA is specified without GMLOGO, GMASGA always has an effect. This means that the option must be turned off after the first segment in the logical message has been removed from the queue, in order to be able to remove the remaining segments in the logical message.

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:

GMNONE

No options specified.

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.