MQGMO (Get-message options) on IBM i

The MQGMO structure allows the application to specify options that control how messages are removed from queues.

Overview

Purpose: The structure is an input/output parameter on the MQGET call.
Version: The current version of MQGMO is GMVER4. Fields that exist only in the more-recent versions of the structure are identified as such in the descriptions that follow.
The COPY file provided contains the most recent version of MQGMO that is supported by the environment, but with the initial value of the GMVER field set to GMVER1. To use fields that are not present in the version-1 structure, the application must set the GMVER field to the version number of the version required.
Character set and encoding: Data in MQGMO must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT. However, if the application is running as an IBM MQ client, the structure must be in the character set and encoding of the client.

Fields
Initial values
RPG declaration

Fields

The MQGMO structure contains the following fields; the fields are described in alphabetical order:

GMGST (1 byte character string)

Flag indicating whether message retrieved is in a group.

It has one of the following values:

GSNIG: Message is not in a group.
GSMIG: Message is in a group, but is not the last in the group.
GSLMIG: Message is the last in the group.
This value is also the value returned if the group consists of only one message.

This field is an output field. The initial value of this field is GSNIG. This field is ignored if GMVER is less than GMVER2.

GMMH (10 digit signed integer)

Message Handle

If the GMPRAQ option is specified and the PRPCTL queue attribute is not set to PRPRFH then this is the handle to a message which is populated with the properties of the message being retrieved from the queue. The handle is created by an MQCRTMH call. Any properties already associated with the handle are cleared before retrieving a message.

The following value can also be specified:
MQHM_NONE
No message handle supplied.

No message descriptor is required on the MQGET call if a valid message handle is supplied and used on output to contain the message properties, the message descriptor associated with the message handle is used for input fields.

If a message descriptor is specified on the MQGET call, it always takes precedence over the message descriptor associated with a message handle.

If GMPRRF is specified, or the GMPRAQ is specified and the PRPCTL queue attribute is PRPRFH then the call fails with reason code RC2026 when no message descriptor parameter is specified.

On return from the MQGET call, the properties and message descriptor associated with this message handle are updated to reflect the state of the message retrieved (as well as the message descriptor if one was supplied on the MQGET call). The properties of the message can then be inquired using the MQINQMP call.

Except for message descriptor extensions, when present, a property that can be inquired with the MQINQMP call is not contained in the message data; if the message on the queue contained properties in the message data these are removed from the message data before the data is returned to the application.

If no message handle is provided or Version is less than GMVER4 then we must supply a valid message descriptor on the MQGET call. Any message properties (except those properties contained in the message descriptor) are returned in the message data subject to the value of the property options in the MQGMO structure and the PRPCTL queue attribute.

This field is an always an input field. The initial value of this field is HMNONE. This field is ignored if GMVER is less than GMVER4.

GMMO (10 digit signed integer)

Options controlling selection criteria used for MQGET.

These options allow the application to choose which fields in the MSGDSC parameter is used to select the message returned by the MQGET call. The application sets the required options in this field, and then sets the corresponding fields in the MSGDSC parameter to the values required for those fields. Only messages that have those values in the MQMD for the message are candidates for retrieval using that MSGDSC parameter on the MQGET call. Fields for which the corresponding match option is not specified are ignored when selecting the message to be returned. If no selection criteria are to be used on the MQGET call (that is, any message is acceptable), GMMO should be set to MONONE.

If GMLOGO is specified, only certain messages are eligible for return by the next MQGET call:

If there is no current group or logical message, only messages that have MDSEQ equal to 1 and MDOFF equal to 0 are eligible for return. In this situation, one or more of the following options can be used to select which of the eligible messages is the one returned:
- MOMSGI
- MOCORI
- MOGRPI
If there is a current group or logical message, only the next message in the group or next segment in the logical message is eligible for return, and this cannot be altered by specifying MO* options.

In both cases, match options which are not applicable can still be specified, but the value of the relevant field in the MSGDSC parameter must match the value of the corresponding field in the message to be returned; the call fails with reason code RC2247 is this condition is not satisfied.

GMMO is ignored if either GMMUC or GMBRWC is specified.

One or more of the following options can be specified:

MOMSGI

Retrieve message with specified message identifier.

This option specifies that the message to be retrieved must have a message identifier that matches the value of the MDMID field in the MSGDSC parameter of the MQGET call. This match is in addition to any other matches that might apply (for example, the correlation identifier).

If this option is not specified, the MDMID field in the MSGDSC parameter is ignored, and any message identifier matches.

Note: The message identifier MINONE is a special value that matches any message identifier in the MQMD for the message. Therefore, specifying MOMSGI with MINONE is the same as not specifying MOMSGI.

MOCORI

Retrieve message with specified correlation identifier.

This option specifies that the message to be retrieved must have a correlation identifier that matches the value of the MDCID field in the MSGDSC parameter of the MQGET call. This match is in addition to any other matches that might apply (for example, the message identifier).

If this option is not specified, the MDCID field in the MSGDSC parameter is ignored, and any correlation identifier matches.

Note: The correlation identifier CINONE is a special value that matches any correlation identifier in the MQMD for the message. Therefore, specifying MOCORI with CINONE is the same as not specifying MOCORI.

MOGRPI

Retrieve message with specified group identifier.

This option specifies that the message to be retrieved must have a group identifier that matches the value of the MDGID field in the MSGDSC parameter of the MQGET call. This match is in addition to any other matches that might apply (for example, the correlation identifier).

If this option is not specified, the MDGID field in the MSGDSC parameter is ignored, and any group identifier matches.

Note: The group identifier GINONE is a special value that matches any group identifier in the MQMD for the message. Therefore, specifying MOGRPI with GINONE is the same as not specifying MOGRPI.

MOSEQN

Retrieve message with specified message sequence number.

This option specifies that the message to be retrieved must have a message sequence number that matches the value of the MDSEQ field in the MSGDSC parameter of the MQGET call. This match is in addition to any other matches that might apply (for example, the group identifier).

If this option is not specified, the MDSEQ field in the MSGDSC parameter is ignored, and any message sequence number matches.

MOOFFS

Retrieve message with specified offset.

This option specifies that the message to be retrieved must have an offset that matches the value of the MDOFF field in the MSGDSC parameter of the MQGET call. This match is in addition to any other matches that might apply (for example, the message sequence number).

If this option is not specified, the MDOFF field in the MSGDSC parameter is ignored, and any offset matches.

If none of the options described is specified, the following option can be used:

MONONE

No matches.

This option specifies that no matches are to be used in selecting the message to be returned; therefore, all messages on the queue are eligible for retrieval (but subject to control by the GMAMSA, GMASGA, and GMCMPM options).

MONONE is defined to aid program documentation. It is not intended that this option in used with any other MO* option, but as its value is zero, such use cannot be detected.

This field is an input field. The initial value of this field is MOMSGI with MOCORI. This field is ignored if GMVER is less than GMVER2.

Note: The initial value of the GMMO field is defined for compatibility with earlier version queue managers. However, when reading a series of messages from a queue without using selection criteria, this initial value requires the application to reset the MDMID and MDCID fields to MINONE and CINONE before each MQGET call. The need to reset MDMID and MDCID can be avoided by setting GMVER to GMVER2, and GMMO to MONONE.

GMOPT (10 digit signed integer)

Options that control the action of MQGET.

Zero or more of the following described options can be specified. If more than one is required the values can be added (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 later in this section.

Note: In the following description, 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 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:

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

The following points must 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 might 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 this option or GMNSYP is not 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.
If the message is not persistent, the queue manager processes the call as though the application had specified GMNSYP (see the following section 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 this option and GMSYP are not 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 searches 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 then 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 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 before 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 is not 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 later 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.

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.

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 then 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 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 might 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 with a MDOFF field in MQMD that 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
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 with a MDOFF field in MQMD that 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 the message segments that make up the logical message are locked to the queue handle (if 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 is 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) on IBM i 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 might 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 large, system constraints might 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 typically 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 are 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 might 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 might 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 before 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 this topic. Table 1 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 before the call.
Cur log msg: Indicates whether a current logical message exists before 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.

Options you specify	Group and log-msg status before 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 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 might be returned out of order, or they might 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) on IBM i 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 needed, 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 must 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 might however succeed with a CCWARN completion code. Table 2 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).

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 might 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, 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, should not specify GMLOGO. This is because in a complex network with multiple paths between sending and receiving queue managers, the physical messages might arrive out of order. By not specifying GMLOGO and 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.

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 want to receive individual segments should therefore always specify GMCMPM.

To use this option, the application must provide a buffer which is large 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 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:

If the MQGET call is operating within a user-defined unit of work, that unit of work is used. If the call fails part way 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 is the same for all segments in the logical message - typically 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 might 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 finally arrives at the destination queue manager.

A logical message consisting of segments in which the MDCSI, MDENC, or both 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 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 with a MDOFF field in MQMD that 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 might 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 affects 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 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 might 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 make up 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 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 GMASGA does not imply that GMCMPM succeeds. 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 are 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 is used with any other, but as its value is zero, such use cannot be detected.

The initial value of the GMOPT field is GMNWT.

GMRE1 (1 byte character string)

Reserved.

This is a reserved field. The initial value of this field is a blank character. This field is ignored if GMVER is less than GMVER2.

GMRL (10 digit signed integer)

Length of message data returned (bytes).

This is an output field that is set by the queue manager to the length in bytes of the message data returned by the MQGET call in the BUFFER parameter. If the queue manager does not support this capability, GMRL is set to the value RLUNDF.

When messages are converted between encodings or character sets, the message data can sometimes change size. On return from the MQGET call:

If GMRL is not RLUNDF, the number of bytes of message data returned is given by GMRL.
If GMRL has the value RLUNDF, the number of bytes of message data returned is typically given by the smaller of BUFLEN and DATLEN, but can be less than this if the MQGET call completes with reason code RC2079 . If this happens, the insignificant bytes in the BUFFER parameter are set to nulls.

The following special value is defined:

RLUNDF: Length of returned data not defined.

The initial value of this field is RLUNDF. This field is ignored if GMVER is less than GMVER3.

GMRQN (48 byte character string)

Resolved name of destination queue.

This is an output field which is set by the queue manager to the local name of the queue from which the message was retrieved, as defined to the local queue manager. This is different from the name used to open the queue if:

An alias queue was opened (in which case, the name of the local queue to which the alias resolved is returned), or
A model queue was opened (in which case, the name of the dynamic local queue is returned).

The length of this field is given by LNQN. The initial value of this field is 48 blank characters.

GMRS2 (1 byte character string)

Reserved.

This is a reserved field. The initial value of this field is a blank character. This field is ignored if GMVER is less than GMVER4.

GMSEG (1 byte character string)

Flag indicating whether further segmentation is allowed for the message retrieved.

It has one of the following values:

SEGIHB: Segmentation not allowed.
SEGALW: Segmentation allowed.

This is an output field. The initial value of this field is SEGIHB. This field is ignored if GMVER is less than GMVER2.

GMSG1 (10 digit signed integer)

Signal.

This is a reserved field; its value is not significant. The initial value of this field is 0.

GMSG2 (10 digit signed integer)

Signal identifier.

This is a reserved field; its value is not significant.

GMSID (4 byte character string)

Structure identifier.

The value must be:

GMSIDV: Identifier for get-message options structure.

This field is always an input field. The initial value of this field is GMSIDV.

GMSST (1 byte character string)

Flag indicating whether message retrieved is a segment of a logical message.

It has one of the following values:

SSNSEG: Message is not a segment.
SSSEG: Message is a segment, but is not the last segment of the logical message.
SSLSEG: Message is the last segment of the logical message.
This is also the value returned if the logical message consists of only one segment.

This field is an output field. The initial value of this field is SSNSEG. This field is ignored if GMVER is less than GMVER2.

GMTOK (16 byte bit string)

Message token.

This is a reserved field; its value is not significant. The following special value is defined:

MTKNON: No message token.
The value is binary zero for the length of the field.

The length of this field is given by LNMTOK. The initial value of this field is MTKNON. This field is ignored if GMVER is less than GMVER3.

GMVER (10 digit signed integer)

Structure version number.

The value must be one of the following:

GMVER1: Version-1 get-message options structure.
GMVER2: Version-2 get-message options structure.
GMVER3: Version-3 get-message options structure.
GMVER4: Version-4 get-message options structure.

Fields that exist only in the more-recent versions of the structure are identified as such in the descriptions of the fields. The following constant specifies the version number of the current version:

GMVERC: Current version of get-message options structure.

This field is always an input field. The initial value of this field is GMVER1.

GMVER (10 digit signed integer)

Structure version number.

The value must be one of the following:

GMVER1: Version-1 get-message options structure.
GMVER2: Version-2 get-message options structure.
GMVER3: Version-3 get-message options structure.
GMVER4: Version-4 get-message options structure.

GMVERC: Current version of get-message options structure.

This field is always an input field. The initial value of this field is GMVER1.

GMWI (10 digit signed integer)

Wait interval.

This is the approximate time, expressed in milliseconds, that the MQGET call waits for a suitable message to arrive (that is, a message satisfying the selection criteria specified in the MSGDSC parameter of the MQGET call; see the MDMID field described in MQMD (Message descriptor) on IBM i for more details). If no suitable message has arrived after this time has elapsed, the call completes with CCFAIL and reason code RC2033.

GMWI is used with the GMWT option. It is ignored if this option is not specified. If it is specified, GMWI must be greater than or equal to zero, or the following special value:

WIULIM: Unlimited wait interval.

The initial value of this field is 0.

Initial values

Field name	Name of constant	Value of constant
GMSID	GMSIDV	'GMO¬'
GMVER	GMVER1	1
GMOPT	GMNWT	0
GMWI	None	0
GMSG1	None	0
GMSG2	None	0
GMRQN	None	Blanks
GMMO	MOMSGI + MOCORI	3
GMGST	GSNIG	'࿢'
GMSST	SSNSEG	'࿢'
GMSEG	SEGIHB	'࿢'
GMRE1	None	'࿢'
GMTOK	MTKNON	Nulls
GMRL	RLUNDF	-1
GMRS2	None	'࿢'
GMMH	HMNONE	0

Notes:

The symbol ¬ represents a single blank character.

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D*
     D* MQGMO Structure
     D*
     D* Structure identifier
     D  GMSID                  1      4    INZ('GMO ')
     D* Structure version number
     D  GMVER                  5      8I 0 INZ(1)
     D* Options that control the action ofMQGET
     D  GMOPT                  9     12I 0 INZ(0)
     D* Wait interval
     D  GMWI                  13     16I 0 INZ(0)
     D* Signal
     D  GMSG1                 17     20I 0 INZ(0)
     D* Signal identifier
     D  GMSG2                 21     24I 0 INZ(0)
     D* Resolved name of destination queue
     D  GMRQN                 25     72    INZ
     D* Options controlling selection criteriaused for MQGET
     D  GMMO                  73     76I 0 INZ(3)
     D* Flag indicating whether messageretrieved is in a group
     D  GMGST                 77     77    INZ(' ')
     D* Flag indicating whether messageretrieved is a segment of a
     D* logicalmessage
     D  GMSST                 78     78    INZ(' ')
     D* Flag indicating whether furthersegmentation is allowed for themessage
     D* retrieved
     D  GMSEG                 79     79    INZ(' ')
     D* Reserved
     D  GMRE1                 80     80    INZ
     D* Message token
     D  GMTOK                 81     96    INZ(X'00000000000000-
     D                                     000000000000000000')
     D* Length of message data returned(bytes)
     D  GMRL                  97    100I 0 INZ(-1)
     D* Reserved
     D  GMRS2                101    104I 0 INZ(0) 
     D* Message handle
     D  GMMH                 105    112I 0 INZ(0)

Parent topic: Data type descriptions on IBM i