Options (MQLONG) for MQGMO

MQGMO options control the action of MQGET. We can specify zero or more of the options. For more than one optional value:

  • Add the values (do not add the same constant more than once), or
  • Combine the values using the bitwise OR operation (if the programming language supports bit operations).

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:

    MQGMO_WAIT
    The application waits until a suitable message arrives. The maximum time that the application waits is specified in WaitInterval . Important: There is no wait, or delay, if a suitable message is available immediately.

    If MQGET requests are inhibited, or MQGET requests become inhibited while waiting, the wait is canceled. The call completes with MQCC_FAILED and reason code MQRC_GET_INHIBITED, regardless of whether there are suitable messages on the queue.

    We can use MQGMO_WAIT with the MQGMO_BROWSE_FIRST or MQGMO_BROWSE_NEXT options.

    If several applications are waiting on the same shared queue, the following rules select which application is activated when a suitable message arrives:

    Number of MQGET calls waiting to be activated Result
    With a BROWSE option Without a BROWSE option 1
    None One or more One MQGET call without a BROWSE option is activated.
    One or more None All MQGET calls with a BROWSE option are activated.
    One or more One or more One MQGET call without a BROWSE option is activated. The number of MQGET calls with a BROWSE option that are activated is unpredictable.
    If more than one MQGET call without a BROWSE option is waiting on the same queue, only one is activated. The queue manager attempts to give priority to waiting calls in the following order:
    1. Specific get-wait requests that can be satisfied only by certain messages, for example, ones with a specific MsgId or CorrelId (or both).
    2. General get-wait requests that can be satisfied by any message.

    Note:

    • Within the first category, no additional priority is given to more specific get-wait requests. For example, requests that specify both MsgId and CorrelId .
    • 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 can also happen that an application that is not waiting retrieves the message in preference to one that is.

    On z/OS, the following points apply:

    • If we want the application to proceed with other work while waiting for the message to arrive, consider using the signal option (MQGMO_SET_SIGNAL) instead. However the signal option is environment-specific; applications that you to port between different environments must not use it.
    • If there is more than one MQGET call waiting for the same message, with a mixture of wait and signal options, each waiting call is considered equally. It is an error to specify MQGMO_SET_SIGNAL with MQGMO_WAIT. It is also an error to specify this option with a queue handle for which a signal is outstanding.
    • If you specify MQGMO_WAIT or MQGMO_SET_SIGNAL for a queue that has an IndexType of MQIT_MSG_TOKEN, no selection criteria are permitted. This means that:

      • If we are using a version-1 MQGMO, set the MsgId and CorrelId fields in the MQMD specified on the MQGET call to MQMI_NONE and MQCI_NONE.
      • If we are using a version-2 or later MQGMO, set the MatchOptions field to MQMO_NONE.

    • For an MQGET call on a shared queue and the call is a browse request, or a destructive get of a group message, and neither MsgId nor CorrelId are to be matched, your signal ECB is posted MQEC_MSG_ARRIVED after 200 milliseconds.

      This occurs, even though a suitable message might not have arrived on the queue, until the wait interval has expired, when the queue is posted with MQEC_WAIT_INTERVAL_EXPIRED. When MQEC_MSG_ARRIVED is posted, we must reissue a second MQGET call to retrieve the message, if one is available.

      This technique is used to ensure that we are informed in a timely manner of a message arrival, but can appear as an unexpected processing overhead when compared with a similar call sequence on a nonshared queue.

    MQGMO_WAIT is ignored if specified with MQGMO_BROWSE_MSG_UNDER_CURSOR or MQGMO_MSG_UNDER_CURSOR ; no error is raised.

    MQGMO_NO_WAIT
    The application does not wait if no suitable message is available. MQGMO_NO_WAIT is the opposite of the MQGMO_WAIT. MQGMO_NO_WAIT is defined to aid program documentation. It is the default if neither is specified.

    MQGMO_SET_SIGNAL
    Use this option with the Signal1 and Signal2 fields. It allows applications to proceed with other work while waiting for a message to arrive. It also allows (if suitable operating system facilities are available) applications to wait for messages arriving on more than one queue. Note: The MQGMO_SET_SIGNAL option is environment-specific; do not use it for applications that we want to port. In two circumstances, the call completes in the same way as if this option had not been specified:
    1. If a currently available message satisfies the criteria specified in the message descriptor.
    2. If a parameter error or other synchronous error is detected.

    If no message satisfying the criteria specified in the message descriptor is currently available, control returns to the application without waiting for a message to arrive. The CompCode and Reason parameters are set to MQCC_WARNING and MQRC_SIGNAL_REQUEST_ACCEPTED. Other output fields in the message descriptor and the output parameters of the MQGET call are not set. When a suitable message arrives later, the signal is delivered by posting the ECB.

    The caller must then reissue the MQGET call to retrieve the message. The application can wait for this signal, using functions provided by the operating system.

    If the operating system provides a multiple wait mechanism, we can use it to wait for a message arriving on any one of several queues.

    If a nonzero WaitInterval is specified, the signal is delivered after the wait interval expires. The queue manager can also cancel the wait, in which case the signal is delivered.

    More than one MQGET call can set a signal for the same message. The order in which applications are activated is the same as described for MQGMO_WAIT.

    If more than one MQGET call is waiting for the same message, each waiting call is considered equally. The calls can include a mixture of wait and signal options.

    Under certain conditions the MQGET call can retrieve a message, and a signal resulting from the arrival of the same message can be delivered. When a signal is delivered, an application must be prepared for no message to be available.

    A queue handle can have no more than one signal request outstanding.

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

    • MQGMO_UNLOCK
    • MQGMO_WAIT

    For an MQGET call on a shared queue and the call is a browse request, or a destructive get of a group message, and neither MsgId or CorrelId are to be matched, the user's signal ECB is posted MQEC_MSG_ARRIVED after 200 milliseconds.

    This occurs, even though a suitable message might not have arrived on the queue, until the wait interval has expired, when the queue is posted with MQEC_WAIT_INTERVAL_EXPIRED. When MQEC_MSG_ARRIVED is posted, we must reissue a second MQGET call to retrieve the message, if one is available.

    This technique is used to ensure that we are informed in a timely manner of a message arrival, but can appear as an unexpected processing overhead when compared with a similar call sequence on a nonshared queue.

    This is not an efficient method of message retrieval when messages are added infrequently. To avoid this overhead for the browse case, specify MsgId (if non-indexed or indexed by MsgId) or CorrelId (if indexed by CorrelId) matching on the MQGET call.

    This option is supported on z/OS only.

    MQGMO_FAIL_IF_QUIESCING
    Force the MQGET call to fail if the queue manager is in the quiescing state.

    On z/OS, this option also forces the MQGET call to fail if the connection (for a CICS or IMS application) is in the quiescing state.

    If this option is specified with MQGMO_WAIT or MQGMO_SET_SIGNAL, and the wait or signal is outstanding at the time the queue manager enters the quiescing state:

    • The wait is canceled and the call returns completion code MQCC_FAILED with reason code MQRC_Q_MGR_QUIESCING or MQRC_CONNECTION_QUIESCING.
    • The signal is canceled with an environment-specific signal completion code.

      On z/OS, the signal completes with event completion code MQEC_Q_MGR_QUIESCING or MQEC_CONNECTION_QUIESCING.

    If MQGMO_FAIL_IF_QUIESCING is not specified and the queue manager or connection enters the quiescing state, the wait or signal is not canceled.


Sync point options

The following options relate to the participation of the MQGET call within a unit of work:

    MQGMO_SYNCPOINT
    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. We can leave MQGMO_SYNCPOINT and MQGMO_NO_SYNCPOINT unset. In which case, the inclusion of the get request in unit-of-work protocols is determined by the environment running the queue manager. It is not determined by the environment running the application.

    • On z/OS, the get request is within a unit of work.
    • In all environments except z/OS, the get request is not within a unit of work.

    Because of these differences, an application that we want to port must not allow this option to default; specify MQGMO_SYNCPOINT or MQGMO_NO_SYNCPOINT explicitly.

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

    • MQGMO_BROWSE_FIRST
    • MQGMO_BROWSE_MSG_UNDER_CURSOR
    • MQGMO_BROWSE_NEXT
    • MQGMO_LOCK
    • MQGMO_NO_SYNCPOINT
    • MQGMO_SYNCPOINT_IF_PERSISTENT
    • MQGMO_UNLOCK

    MQGMO_SYNCPOINT_IF_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 MQPER_PERSISTENT in the Persistence field in MQMD.

    • If the message is persistent, the queue manager processes the call as though the application had specified MQGMO_SYNCPOINT.
    • If the message is not persistent, the queue manager processes the call as though the application had specified MQGMO_NO_SYNCPOINT.

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

    • MQGMO_BROWSE_FIRST
    • MQGMO_BROWSE_MSG_UNDER_CURSOR
    • MQGMO_BROWSE_NEXT
    • MQGMO_COMPLETE_MSG
    • MQGMO_MARK_SKIP_BACKOUT
    • MQGMO_NO_SYNCPOINT
    • MQGMO_SYNCPOINT
    • MQGMO_UNLOCK

    This option is supported in the following environments:

    • AIX
    • IBM i
    • Linux
    • z/OS

    and for IBM MQ MQI clients connected to these systems.

    MQGMO_NO_SYNCPOINT
    The request is to operate outside the normal unit-of-work protocols. If you get a message without a browse option, it is deleted from the queue immediately. The message cannot be made available again by backing out the unit of work.

    This option is assumed if we specify MQGMO_BROWSE_FIRST or MQGMO_BROWSE_NEXT.

    We can leave MQGMO_SYNCPOINT and MQGMO_NO_SYNCPOINT unset. In which case, the inclusion of the get request in unit-of-work protocols is determined by the environment running the queue manager. It is not determined by the environment running the application.

    • On z/OS, the get request is within a unit of work.
    • In all environments except z/OS, the get request is not within a unit of work.

    Because of these differences, an application that we want to port must not allow this option to default; specify either MQGMO_SYNCPOINT or MQGMO_NO_SYNCPOINT explicitly.

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

    • MQGMO_MARK_SKIP_BACKOUT
    • MQGMO_SYNCPOINT
    • MQGMO_SYNCPOINT_IF_PERSISTENT

    MQGMO_MARK_SKIP_BACKOUT
    Back out a unit of work without reinstating on the queue the message that was marked with this option.

    This option is supported only on z/OS.

    If this option is specified, MQGMO_SYNCPOINT must also be specified. MQGMO_MARK_SKIP_BACKOUT is not valid with any of the following options:

    • MQGMO_BROWSE_FIRST
    • MQGMO_BROWSE_MSG_UNDER_CURSOR
    • MQGMO_BROWSE_NEXT
    • MQGMO_LOCK
    • MQGMO_NO_SYNCPOINT
    • MQGMO_SYNCPOINT_IF_PERSISTENT
    • MQGMO_UNLOCK

    Note: On IMS and CICS, you might have to issue an extran IBM MQ call after backing out a unit of work containing a message marked with MQGMO_MARK_SKIP_BACKOUT. We must issue an IBM MQ call before you commit the new unit of work containing the marked message. The call can be any IBM MQ call you like.

    1. On IMS, if you have not applied IMS APAR PN60855 and we are running an IMS MPP or BMP application.
    2. On CICS, if we are running any application.

    In both cases, issue any IBM MQ call before committing the new unit of work containing the backed out message. Note: Within a unit of work, there can be only one get request marked as skipping backout, as well as none or several unmarked get requests.

    If an application backs out of a unit of work, a message that was retrieved using MQGMO_MARK_SKIP_BACKOUT is not restored to its previous state. Other resource updates are backed out. The message is treated as if it had been retrieved in a new unit of work started by the backout request. The message is retrieved without the MQGMO_MARK_SKIP_BACKOUT option.

    MQGMO_MARK_SKIP_BACKOUT is useful if, after some resources have been changed, it becomes apparent that the unit of work cannot complete successfully. If we omit this option, backing out the unit of work reinstates the message on the queue. The same sequence of events occurs again, when the message is next retrieved.

    However, if we specify MQGMO_MARK_SKIP_BACKOUT on the original MQGET call, backing out the unit of work backs out the updates to the other resources. The message is treated as if it had been retrieved under a new unit of work. The application can perform appropriate error handling. It can send a report message to the sender of the original message, or place the original message on the dead-letter queue. It can then commit the new unit of work. Committing the new unit of work removes the message permanently from the original queue.

    MQGMO_MARK_SKIP_BACKOUT marks a single physical message. If the message belongs to a message group, the other messages in the group are not marked. Similarly, if the marked message is a segment of a logical message, the other segments in the logical message are not marked.

    Any message in a group can be marked, but if messages are retrieved using MQGMO_LOGICAL_ORDER, it is advantageous to mark the first message in the group. If the unit of work is backed out, the first (marked) message is moved to the new unit of work. The second and later messages in the group are reinstated on the queue. The messages left on the queue cannot be retrieved by another application using MQGMO_LOGICAL_ORDER. The first message in the group is no longer on the queue. However, the application that backed the unit of work out can retrieve the second and later messages into the new unit of work using the MQGMO_LOGICAL_ORDER option. The first message has been retrieved already.

    Occasionally you might need to back out the new unit of work. For example, because the dead-letter queue is full and the message must not be discarded. Backing out the new unit of work reinstates the message on the original queue, which prevents the message being lost. However, in this situation processing cannot continue. After backing out the new unit of work, the application must inform the operator or administrator that there is an unrecoverable error, and then finish.

    MQGMO_MARK_SKIP_BACKOUT only works if the unit of work containing the get request is interrupted by the application backing it out. If the unit of work containing the get request is backed out because the transaction or system fails, MQGMO_MARK_SKIP_BACKOUT is ignored. Any message retrieved using this option is reinstated on the queue in the same way as messages retrieved without this option.


Browse options

The following options relate to browsing messages on the queue:

    MQGMO_BROWSE_FIRST
    When a queue is opened with the MQOO_BROWSE option, a browse cursor is established, positioned logically before the first message on the queue. We can then use MQGET calls specifying the MQGMO_BROWSE_FIRST, MQGMO_BROWSE_NEXT, or MQGMO_BROWSE_MSG_UNDER_CURSOR option 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 MQGMO_BROWSE_NEXT searches for a suitable message. MQGMO_BROWSE_FIRST is not valid with any of the following options:

    • MQGMO_BROWSE_MSG_UNDER_CURSOR
    • MQGMO_BROWSE_NEXT
    • MQGMO_MARK_SKIP_BACKOUT
    • MQGMO_MSG_UNDER_CURSOR
    • MQGMO_SYNCPOINT
    • MQGMO_SYNCPOINT_IF_PERSISTENT
    • MQGMO_UNLOCK

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

    An MQGET call with MQGMO_BROWSE_FIRST ignores the previous position of the browse cursor. The first message on the queue that satisfies the conditions specified in the message descriptor is retrieved. The message remains on the queue, and the browse cursor is positioned on this message.

    After this call, the browse cursor is positioned on the message that has been returned. The message might be removed from the queue before the next MQGET call with MQGMO_BROWSE_NEXT is issued. In this case, the browse cursor remains at the position in the queue that the message occupied, even though that position is now empty.

    Use the MQGMO_MSG_UNDER_CURSOR option with a non-browse MQGET call, to remove the message from the queue.

    The browse cursor is not moved by a non-browse MQGET call, even if using the same Hobj handle. Nor is it moved by a browse MQGET call that returns a completion code of MQCC_FAILED, or a reason code of MQRC_TRUNCATED_MSG_FAILED.

    Specify the MQGMO_LOCK option with this option, to lock the message that is browsed.

    We can specify MQGMO_BROWSE_FIRST with any valid combination of the MQGMO_* and MQMO_* options that control the processing of messages in groups and segments of logical messages.

    If you specify MQGMO_LOGICAL_ORDER, the messages are browsed in logical order. If we omit that option, the messages are browsed in physical order. If you specify MQGMO_BROWSE_FIRST, we can switch between logical order and physical order. Subsequent MQGET calls using MQGMO_BROWSE_NEXT browse the queue in the same order as the most recent call that specified MQGMO_BROWSE_FIRST for the queue handle.

    The queue manager retains two sets of group and segment information for MQGET calls. The group and segment information for browse calls are retained separately from the information for calls that remove messages from the queue. If you specify MQGMO_BROWSE_FIRST, the queue manager ignores the group and segment information for browsing. It scans the queue as though there were no current group and no current logical message. If the MQGET call is successful, completion code MQCC_OK or MQCC_WARNING, the group and segment information for browsing is set to that of the message returned. If the call fails, the group and segment information remain the same as they were before the call.

    MQGMO_BROWSE_NEXT
    Advance the browse cursor 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.
    MQGMO_BROWSE_NEXT is not valid with any of the following options:

    • MQGMO_BROWSE_FIRST
    • MQGMO_BROWSE_MSG_UNDER_CURSOR
    • MQGMO_MARK_SKIP_BACKOUT
    • MQGMO_MSG_UNDER_CURSOR
    • MQGMO_SYNCPOINT
    • MQGMO_SYNCPOINT_IF_PERSISTENT
    • MQGMO_UNLOCK

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

    MQGMO_BROWSE_NEXT behaves the same way as MQGMO_BROWSE_FIRST, if it is the first call to browse a queue, after the queue has been opened for browse.

    The message under cursor might be removed from the queue before the next MQGET call with MQGMO_BROWSE_NEXT is issued. The browse cursor logically remains at the position in the queue that the message occupied, even though that position is now empty.

    Messages are stored on the queue in one of two ways:

    • FIFO within priority (MQMDS_PRIORITY), or
    • FIFO regardless of priority (MQMDS_FIFO)

    The MsgDeliverySequence queue attribute indicates which method applies (see Attributes for queues for details).

    A queue might have a MsgDeliverySequence of MQMDS_PRIORITY. A message arrives on the queue that is of a higher priority than the one currently pointed to by the browse cursor. In which case, the higher priority message is not found during the current sweep of the queue using MQGMO_BROWSE_NEXT. It can be found only after the browse cursor has been reset with MQGMO_BROWSE_FIRST, or by reopening the queue.

    The MQGMO_MSG_UNDER_CURSOR option can be used with a non-browse MQGET call if required, to remove the message from the queue.

    The browse cursor is not moved by non-browse MQGET calls using the same Hobj handle.

    Specify the MQGMO_LOCK option with this option to lock the message that is browsed.

    We can specify MQGMO_BROWSE_NEXT with any valid combination of the MQGMO_* and MQMO_* options that control the processing of messages in groups and segments of logical messages.

    If you specify MQGMO_LOGICAL_ORDER, the messages are browsed in logical order. If we omit that option, the messages are browsed in physical order. If you specify MQGMO_BROWSE_FIRST, we can switch between logical order and physical order. Subsequent MQGET calls using MQGMO_BROWSE_NEXT browse the queue in the same order as the most recent call that specified MQGMO_BROWSE_FIRST for the queue handle. The call fails with reason code MQRC_INCONSISTENT_BROWSE if this condition is not satisfied.

    Note: Take special care when using an MQGET call to browse beyond the end of a message group if MQGMO_LOGICAL_ORDER is not specified. For example, suppose that the last message in the group precedes the first message in the group on the queue. Using MQGMO_BROWSE_NEXT to browse beyond the end of the group, specifying MQMO_MATCH_MSG_SEQ_NUMBER with MsgSeqNumber set to 1 returns the first message in the group already browsed. This result can happen immediately, or a number of MQGET calls later if there are intervening groups. The same consideration applies for a logical message not in a group.

    The group and segment information for browse calls are retained separately from the information for calls that remove messages from the queue.

    MQGMO_BROWSE_MSG_UNDER_CURSOR
    Retrieve the message pointed to by the browse cursor nondestructively, regardless of the MQMO_* options specified in the MatchOptions field in MQGMO.
    MQGMO_BROWSE_MSG_UNDER_CURSOR is not valid with any of the following options:

    • MQGMO_BROWSE_FIRST
    • MQGMO_BROWSE_NEXT
    • MQGMO_MARK_SKIP_BACKOUT
    • MQGMO_MSG_UNDER_CURSOR
    • MQGMO_SYNCPOINT
    • MQGMO_SYNCPOINT_IF_PERSISTENT
    • MQGMO_UNLOCK

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

    The message pointed to by the browse cursor is the one that was last retrieved using either the MQGMO_BROWSE_FIRST or the MQGMO_BROWSE_NEXT option. The call fails if neither of these calls has been issued for this queue since it was opened. The call also fails if the message that was under the browse cursor has since been retrieved destructively.

    The position of the browse cursor is not changed by this call.

    The MQGMO_MSG_UNDER_CURSOR option can be used with a non-browse MQGET call, to remove the message from the queue.

    The browse cursor is not moved by a non-browse MQGET call, even if using the same Hobj handle. Nor is it moved by a browse MQGET call that returns a completion code of MQCC_FAILED, or a reason code of MQRC_TRUNCATED_MSG_FAILED.

    If MQGMO_BROWSE_MSG_UNDER_CURSOR is specified with MQGMO_LOCK:

    • If there is already a message locked, it must be the one under the cursor, so that is returned without unlocking and locking again. The message remains locked.
    • If there is no locked message and there is a message under the browse cursor, it is locked and returned to the application. If there is no message under the browse cursor, the call fails.

    If MQGMO_BROWSE_MSG_UNDER_CURSOR is specified without MQGMO_LOCK:

    • If there is already a message locked, it must be the one under the cursor. The 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 by the same application. It might have been retrieved destructively by another application getting messages from the queue.
    • If there is no locked message and there is a message under the browse cursor, it is returned to the application. If there is no message under the browse cursor the call fails.

    If MQGMO_COMPLETE_MSG is specified with MQGMO_BROWSE_MSG_UNDER_CURSOR, the browse cursor must identify a message whose Offset field in MQMD is zero. If this condition is not satisfied, the call fails with reason code MQRC_INVALID_MSG_UNDER_CURSOR.

    The group and segment information for browse calls are retained separately from the information for calls that remove messages from the queue.

    MQGMO_MSG_UNDER_CURSOR
    Retrieve the message pointed to by the browse cursor, regardless of the MQMO_* options specified in the MatchOptions 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 MQGMO_BROWSE_FIRST or the MQGMO_BROWSE_NEXT option.

    If MQGMO_COMPLETE_MSG is specified with MQGMO_MSG_UNDER_CURSOR, the browse cursor must identify a message whose Offset field in MQMD is zero. If this condition is not satisfied, the call fails with reason code MQRC_INVALID_MSG_UNDER_CURSOR.

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

    • MQGMO_BROWSE_FIRST
    • MQGMO_BROWSE_MSG_UNDER_CURSOR
    • MQGMO_BROWSE_NEXT
    • MQGMO_UNLOCK

    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.

    MQGMO_MARK_BROWSE_HANDLE
    The message that is returned by a successful MQGET, or identified by the returned MsgToken, is marked. The mark is specific to the object handle used in the call.

    The message is not removed from the queue.

    MQGMO_MARK_BROWSE_HANDLE is valid only if one of the following options is also specified:

    • MQGMO_BROWSE_FIRST
    • MQGMO_BROWSE_MSG_UNDER_CURSOR
    • MQGMO_BROWSE_NEXT

    MQGMO_MARK_BROWSE_HANDLE is not valid with any of the following options:

    • MQGMO_ALL_MSGS_AVAILABLE
    • MQGMO_ALL_SEGMENTS_AVAILABLE
    • MQGMO_COMPLETE_MSG
    • MQGMO_LOCK
    • MQGMO_LOGICAL_ORDER
    • MQGMO_UNLOCK

    The message remains in this state until one of the following events occurs:

    • The object handle concerned is closed, either normally or otherwise.
    • The message is unmarked for this handle by a call to MQGET with the option MQGMO_UNMARK_BROWSE_HANDLE.
    • The message is returned from a call to destructive MQGET, which completes with MQCC_OK or MQCC_WARNING. The message state remains changed even if the MQGET is later rolled-back.
    • The message expires.

    MQGMO_MARK_BROWSE_CO_OP
    The message that is returned by a successful MQGET, or identified by the returned MsgToken, is marked for all handles in the cooperating set.

    The cooperative level mark is in addition to any handle level mark that might have been set.

    The message is not removed from the queue.

    MQGMO_MARK_BROWSE_CO_OP is valid only if the object handle used was returned by a call to MQOPEN that specified MQOO_CO_OP. We must also specify one of the following MQGMO options:

    • MQGMO_BROWSE_FIRST
    • MQGMO_BROWSE_MSG_UNDER_CURSOR
    • MQGMO_BROWSE_NEXT

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

    • MQGMO_ALL_MSGS_AVAILABLE
    • MQGMO_ALL_SEGMENTS_AVAILABLE
    • MQGMO_COMPLETE_MSG
    • MQGMO_LOCK
    • MQGMO_LOGICAL_ORDER
    • MQGMO_UNLOCK

    If the message is already marked, and the option MQGMO_UNMARKED_BROWSE_MSG is not specified, the call fails with MQCC_FAILED and reason code MQRC_MSG_MARKED_BROWSE_CO_OP.

    The message remains in this state until one of the following events occurs:

    • All object handles in the cooperating set are closed.
    • The message is unmarked for cooperating browsers by a call to MQGET with the option MQGMO_UNMARK_BROWSE_CO_OP.
    • The message is automatically unmarked by the queue manager.
    • The message is returned from a call to a non-browse MQGET. The message state remains changed even if the MQGET is later rolled-back.
    • The message expires.

    MQGMO_UNMARKED_BROWSE_MSG
    A call to MQGET that specifies MQGMO_UNMARKED_BROWSE_MSG returns a message that is considered to be unmarked for its handle. It does not return a message if the message was marked for its handle. It also does not return the message if the queue was opened by a call to MQOPEN, with the option MQOO_CO_OP, and the message has been marked by a member of the cooperating set. This option is not valid with any of the following options:

    • MQGMO_ALL_MSGS_AVAILABLE
    • MQGMO_ALL_SEGMENTS_AVAILABLE
    • MQGMO_COMPLETE_MSG
    • MQGMO_LOCK
    • MQGMO_LOGICAL_ORDER
    • MQGMO_UNLOCK

    MQGMO_UNMARK_BROWSE_CO_OP
    After a call to MQGET that specifies this option, the message is no longer considered by any open handles in the set of cooperating handles to be marked for the cooperating set. The message is still considered to be marked at handle level if it was marked at handle level before this call.

    Use MQGMO_UNMARK_BROWSE_CO_OP is valid only with a handle returned by a successful call to MQOPEN with the option MQOO_CO_OP. The MQGET succeeds even if the message is not considered to be marked by the cooperating set of handles.

    MQGMO_UNMARK_BROWSE_CO_OP is not valid on a non-browse MQGET call, or with any of the following options:

    • MQGMO_ALL_MSGS_AVAILABLE
    • MQGMO_ALL_SEGMENTS_AVAILABLE
    • MQGMO_COMPLETE_MSG
    • MQGMO_LOCK
    • MQGMO_LOGICAL_ORDER
    • MQGMO_MARK_BROWSE_CO_OP
    • MQGMO_UNLOCK
    • MQGMO_UNMARKED_BROWSE_MSG

    MQGMO_UNMARK_BROWSE_HANDLE
    After a call to MQGET that specifies this option, the message located is no longer considered to be marked by this handle.

    The call succeeds even if the message is not marked for this handle.

    This option is not valid on a non-browse MQGET call, or with any of the following options:

    • MQGMO_ALL_MSGS_AVAILABLE
    • MQGMO_ALL_SEGMENTS_AVAILABLE
    • MQGMO_COMPLETE_MSG
    • MQGMO_LOCK
    • MQGMO_LOGICAL_ORDER
    • MQGMO_MARK_BROWSE_CO_OP
    • MQGMO_UNLOCK
    • MQGMO_UNMARKED_BROWSE_MSG


Lock options

The following options relate to locking messages on the queue:

    MQGMO_LOCK
    Lock 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:

    • MQGMO_BROWSE_FIRST
    • MQGMO_BROWSE_NEXT
    • MQGMO_BROWSE_MSG_UNDER_CURSOR

    Only one message can be locked for each queue handle. The message can be a logical message or a physical message:

    • If you specify MQGMO_COMPLETE_MSG, all the message segments that make up the logical message are locked to the queue handle. The messages must all be present on the queue and available for retrieval.
    • If we omit MQGMO_COMPLETE_MSG, 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 MQGMO_COMPLETE_MSG to retrieve or browse the logical message.

    The locked message is always the one under the browse cursor. The message can be removed from the queue by a later MQGET call that specifies the MQGMO_MSG_UNDER_CURSOR option. Other MQGET calls using the queue handle can also remove the message (for example, a call that specifies the message identifier of the locked message).

    If the call returns completion code MQCC_FAILED, or MQCC_WARNING with reason code MQRC_TRUNCATED_MSG_FAILED, no message is locked.

    If the application does not remove the message from the queue, the lock is released by one of the following actions:

    • Issuing another MQGET call for this handle, specifying either MQGMO_BROWSE_FIRST or MQGMO_BROWSE_NEXT. The lock is released if the call completes with MQCC_OK or MQCC_WARNING. The message remains locked if the call completes with MQCC_FAILED. However, the following exceptions apply:

      • The message is not unlocked if MQCC_WARNING is returned with MQRC_TRUNCATED_MSG_FAILED.
      • The message is unlocked if MQCC_FAILED is returned with MQRC_NO_MSG_AVAILABLE.

      If you also specify MQGMO_LOCK, the message returned is locked. If we omit MQGMO_LOCK, there is no locked message after the call.

      If you specify MQGMO_WAIT, and no message is immediately available, the original message is unlocked before the start of the wait.

    • Issuing another MQGET call for this handle, with MQGMO_BROWSE_MSG_UNDER_CURSOR, without MQGMO_LOCK. The lock is released if the call completes with MQCC_OK or MQCC_WARNING. The message remains locked if the call completes with MQCC_FAILED. However, the following exception applies:

      • The message is not unlocked if MQCC_WARNING is returned with MQRC_TRUNCATED_MSG_FAILED.

    • Issuing another MQGET call for this handle with MQGMO_UNLOCK.
    • Issuing an MQCLOSE call using the handle. The MQCLOSE might be implicit, caused by the application ending.

    No special MQOPEN option is required to specify MQGMO_LOCK, other than MQOO_BROWSE, which is needed to specify an accompanying browse option. MQGMO_LOCK is not valid with any of the following options:

    • MQGMO_MARK_SKIP_BACKOUT
    • MQGMO_SYNCPOINT
    • MQGMO_SYNCPOINT_IF_PERSISTENT
    • MQGMO_UNLOCK

    MQGMO_LOCK is not possible when we are using an IBM MQ client for HP Integrity NonStop Server to a z/OS queue manager when coordinated by TMF.

    MQGMO_UNLOCK
    The message to be unlocked must have been previously locked by an MQGET call with the MQGMO_LOCK option. If there is no message locked for this handle, the call completes with MQCC_WARNING and MQRC_NO_MSG_LOCKED.

    The MsgDesc, BufferLength, Buffer, and DataLength parameters are not checked or altered if we specify MQGMO_UNLOCK. No message is returned in Buffer.

    No special open option is required to specify MQGMO_UNLOCK (although MQOO_BROWSE is needed to issue the lock request in the first place).

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

    • MQGMO_NO_WAIT
    • MQGMO_NO_SYNCPOINT

    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:

    MQGMO_ACCEPT_TRUNCATED_MSG
    If the message buffer is too small to hold the complete message, allow the MQGET call to fill the buffer. MQGET fills the buffer with as much of the message it can. It issues a warning completion code, and completes its processing. This means that:

    • 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 MQRC_TRUNCATED_MSG_ACCEPTED 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 that:

    • When browsing messages, the browse cursor is not advanced.
    • When removing messages, the message is not removed from the queue.
    • Reason code MQRC_TRUNCATED_MSG_FAILED is returned if no other error occurs.

    MQGMO_CONVERT
    This option converts the application data in the message to conform to the CodedCharSetId and Encoding values specified in the MsgDesc parameter on the MQGET call. The data is converted before it is copied to the Buffer parameter. The Format field specified when the message was put is assumed by the conversion process to identify the nature of the data in the message. The message data is converted by the queue manager for built-in formats, and by a user-written exit for other formats. See Data conversion for details of the data-conversion exit.

    • If conversion is successful, the CodedCharSetId and Encoding fields specified in the MsgDesc parameter are unchanged on return from the MQGET call.
    • If only conversion fails the message data is returned unconverted The CodedCharSetId and Encoding fields in MsgDesc are set to the values for the unconverted message. The completion code is MQCC_WARNING in this case.

    In either case, these fields describe the character-set identifier and encoding of the message data that is returned in the Buffer parameter.

    See the Format field described in MQMD - Message descriptor for a list of format names for which the queue manager performs the conversion.


Group and segment options

The following options relate to the processing of messages in groups and segments of logical messages. Before the option descriptions, here are some definitions of important terms:

    Physical message
    A physical message 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. Typically, physical messages are distinguished by differing values for the message identifier, the MsgId field in MQMD. The queue manager does not enforce different values.

    Logical message
    A logical message is a single unit of application information. In the absence of system constraints, a logical message is the same as a physical message. If 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, GroupId field in MQMD. They have the same message sequence number, MsgSeqNumber field in MQMD. The segments are distinguished by differing values for the segment offset, Offset field in MQMD. The segment offset is 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 different message identifiers.

    A logical message that has not been segmented, but for which segmentation has been permitted by the sending application, also has a nonnull group identifier. In this case there is only one physical message with that group identifier if the logical message does not belong to a message group. Logical messages, for which segmentation has been inhibited by the sending application, have a null group identifier, MQGI_NONE, unless the logical message belongs to a message group.

    Message group
    A message group 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 different values for the message sequence number. The sequence number 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.

    MQGMO_LOGICAL_ORDER
    MQGMO_LOGICAL_ORDER controls the order in which messages are returned by successive MQGET calls for the queue handle. The option must be specified on each call.

    If MQGMO_LOGICAL_ORDER is specified for successive MQGET calls for the same queue handle, messages in groups are returned in the order of their message sequence numbers. 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 MQGMO_LOGICAL_ORDER 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. It is safe to specify MQGMO_LOGICAL_ORDER when retrieving messages from queues that 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. The group and segment information identifies the current message group and current logical message for the queue handle. It also identifies the current position within the group and logical message, and whether the messages are being retrieved within a unit of work. Because the queue manager retains this information, the application does not need to set the group and segment information before each MQGET call. Specifically, it means that the application does not need to set the GroupId, MsgSeqNumber, and Offset fields in MQMD. However, the application must set the MQGMO_SYNCPOINT or MQGMO_NO_SYNCPOINT option correctly on each call.

    When the queue is opened, there is no current message group and no current logical message. A message group becomes the current message group when a message that has the MQMF_MSG_IN_GROUP flag is returned by the MQGET call. With MQGMO_LOGICAL_ORDER specified on successive calls, that group remains the current group until a message is returned that has:

    • MQMF_LAST_MSG_IN_GROUP without MQMF_SEGMENT (that is, the last logical message in the group is not segmented), or
    • MQMF_LAST_MSG_IN_GROUP with MQMF_LAST_SEGMENT (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 the MQGET call there is no longer a current group. In a similar way, a logical message becomes the current logical message when a message that has the MQMF_SEGMENT flag is returned by the MQGET call. The logical message is terminated when the message that has the MQMF_LAST_SEGMENT flag is returned. If no selection criteria are specified, successive MQGET calls return, in the correct order, the messages for the first message group on the queue. They then return the messages for the second message group, and so on, until there are no more messages available. It is possible to select the particular message groups returned by specifying one or more of the following options in the MatchOptions field:

    • MQMO_MATCH_MSG_ID
    • MQMO_MATCH_CORREL_ID
    • MQMO_MATCH_GROUP_ID

    However, these options are effective only when there is no current message group or logical message. See the MatchOptions field described in MQGMO - Get-message options for further details. Table 2 shows the values of the MsgId, CorrelId, GroupId, MsgSeqNumber, and Offset fields that the queue manager looks for when attempting to find a message to return on the MQGET call. The rules apply both to removing messages from the queue, and browsing messages on the queue. In the table, Either means Yes or No:

      LOG ORD
      Indicates whether the MQGMO_LOGICAL_ORDER 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 MsgId CorrelId GroupId MsgSeqNumber Offset
    Yes No No Controlled by MatchOptions Controlled by MatchOptions Controlled by MatchOptions 1 0
    Yes No Yes Any message identifier Any correlation identifier Previous group identifier 1 Previous offset + previous segment length
    Yes Yes No Any message identifier Any correlation identifier Previous group identifier Previous sequence number + 1 0
    Yes Yes Yes Any message identifier Any correlation identifier Previous group identifier Previous sequence number Previous offset + previous segment length
    No Either Either Controlled by MatchOptions Controlled by MatchOptions Controlled by MatchOptions Controlled by MatchOptions Controlled by MatchOptions

    If multiple message groups are present on the queue and eligible for return, the groups are returned in the order determined by the position on the queue of the first segment of the first logical message in each group. That is, the physical messages that have message sequence numbers of 1, and offsets of 0, determine the order in which eligible groups are returned.

    The MQGMO_LOGICAL_ORDER option affects units of work as follows:

    • If 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, and the same queue handle is used, none of the other logical messages and segments in the group can be retrieved within a unit of work.

    If these conditions are not satisfied, the MQGET call fails with reason code MQRC_INCONSISTENT_UOW.

    When MQGMO_LOGICAL_ORDER is specified, the MQGMO supplied on the MQGET call must not be less than MQGMO_VERSION_2, and the MQMD must not be less than MQMD_VERSION_2. If this condition is not satisfied, the call fails with reason code MQRC_WRONG_GMO_VERSION or MQRC_WRONG_MD_VERSION, as appropriate.

    If MQGMO_LOGICAL_ORDER is not specified for successive MQGET calls for the queue handle, messages are returned without regard for whether they belong to message groups, or whether they are segments of logical messages. This means that messages or segments from a particular group or logical message might be returned out of order, or intermingled with messages or segments from other groups or logical messages, or with messages that are not in groups and are not segments. In this situation, the particular messages that are returned by successive MQGET calls is controlled by the MQMO_* options specified on those calls (see the MatchOptions field described in MQGMO - Get-message options for details of these options).

    This is the technique that can be used to restart a message group or logical message in the middle, after a system failure has occurred. When the system restarts, the application can set the GroupId, MsgSeqNumber, Offset, and MatchOptions fields to the appropriate values, and then issue the MQGET call with MQGMO_SYNCPOINT or MQGMO_NO_SYNCPOINT set, but without specifying MQGMO_LOGICAL_ORDER. If this call is successful, the queue manager retains the group and segment information, and subsequent MQGET calls using that queue handle can specify MQGMO_LOGICAL_ORDER as normal.

    The group and segment information that the queue manager retains for the MQGET call is separate from the group and segment information that it retains for the MQPUT call. In addition, the queue manager retains separate information for:

    • MQGET calls that remove messages from the queue.
    • MQGET calls that browse messages on the queue.

    For any given queue handle, the application can mix MQGET calls that specify MQGMO_LOGICAL_ORDER with MQGET calls that do not. However, note the following points:

    • If we omit MQGMO_LOGICAL_ORDER, 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 we omit MQGMO_LOGICAL_ORDER, the call does not fail if there is a current message group or logical message; the call might succeed with an MQCC_WARNING completion code. Table 3 shows the various cases that can arise. In these cases, if the completion code is not MQCC_OK, the reason code is one of the following (as appropriate):

      • MQRC_INCOMPLETE_GROUP
      • MQRC_INCOMPLETE_MSG
      • MQRC_INCONSISTENT_UOW

      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 MQCC_OK (assuming no other errors).

    Current call is Previous call was MQGET with MQGMO_LOGICAL_ORDER Previous call was MQGET without MQGMO_LOGICAL_ORDER
    MQGET with MQGMO_LOGICAL_ORDER MQCC_FAILED MQCC_FAILED
    MQGET without MQGMO_LOGICAL_ORDER MQCC_WARNING MQCC_OK
    MQCLOSE with an unterminated group or logical message MQCC_WARNING MQCC_OK

    Applications that want to retrieve messages and segments in logical order are recommended to specify MQGMO_LOGICAL_ORDER, as this is the simplest option to use. This option relieves the application of the need to manage the group and segment information, because the queue manager manages that information. However, specialized applications might need more control than that provided by the MQGMO_LOGICAL_ORDER option, and this can be achieved by not specifying that option. The application must then ensure that the MsgId, CorrelId, GroupId, MsgSeqNumber, and Offset fields in MQMD, and the MQMO_* options in MatchOptions in MQGMO, are set correctly, before each MQGET call.

    For example, an application that wants to forward physical messages that it receives, without regard for whether those messages are in groups or segments of logical messages, must not specify MQGMO_LOGICAL_ORDER. In a complex network with multiple paths between sending and receiving queue managers, the physical messages might arrive out of order. By specifying neither MQGMO_LOGICAL_ORDER, nor the corresponding MQPMO_LOGICAL_ORDER on the MQPUT call, the forwarding application can retrieve and forward each physical message as soon as it arrives, without having to wait for the next one in logical order to arrive.

    We can specify MQGMO_LOGICAL_ORDER with any of the other MQGMO_* options, and with various of the MQMO_* options in appropriate circumstances (see preceding section).

    • On z/OS, this option is supported for private and shared queues, but the queue must have an index type of MQIT_GROUP_ID. For shared queues, the CFSTRUCT object that the queue maps to must be at CFLEVEL(3) or higher.
    • This option is supported for all local queues for the following platforms:

      • AIX
      • Linux
      • IBM i
      • Windows

      and for IBM MQ MQI clients connected to these systems,.

    MQGMO_COMPLETE_MSG
    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 must always specify MQGMO_COMPLETE_MSG.

    To use this option, the application must provide a buffer that is big enough to accommodate the complete message, or specify the MQGMO_ACCEPT_TRUNCATED_MSG option.

    If the queue contains segmented messages with some of the segments missing (perhaps because they have been delayed in the network and have not yet arrived), specifying MQGMO_COMPLETE_MSG prevents the retrieval of segments belonging to incomplete logical messages. However, those message segments still contribute to the value of the CurrentQDepth queue attribute; this means that there might be no retrievable logical messages, even though CurrentQDepth is greater than zero.

    For persistent messages, the queue manager can reassemble the segments only within a unit of work:

    • If the MQGET call is operating within a user-defined unit of work, that unit of work is used. If the call fails during 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 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 exists, the queue manager cannot reassemble. If the message does not require reassembly, the call can still succeed. But if the message requires reassembly, the call fails with reason code MQRC_UOW_NOT_AVAILABLE.

    For nonpersistent messages, the queue manager does not require a unit of work to be available to perform reassembly.

    Each physical message that is a segment has its own message descriptor. For the segments constituting a single logical message, most of the fields in the message descriptor are the same for all segments in the logical message; typically it is only the MsgId, Offset, and MsgFlags fields that differ between segments in the logical message. However, if a segment is placed on a dead-letter queue at an intermediate queue manager, the DLQ handler retrieves the message specifying the MQGMO_CONVERT option, and this can result in the character set or encoding of the segment being changed. If the DLQ handler successfully sends the segment on its way, the segment might have a character set or encoding that differs from the other segments in the logical message when the segment arrives at the destination queue manager.

    A logical message consisting of segments in which the CodedCharSetId and Encoding fields differ cannot be reassembled by the queue manager into a single logical message. Instead, the queue manager reassembles and returns the first few consecutive segments at the start of the logical message that have the same character-set identifiers and encodings, and the MQGET call completes with completion code MQCC_WARNING and reason code MQRC_INCONSISTENT_CCSIDS or MQRC_INCONSISTENT_ENCODINGS, as appropriate. This happens regardless of whether MQGMO_CONVERT is specified. To retrieve the remaining segments, the application must reissue the MQGET call without the MQGMO_COMPLETE_MSG option, retrieving the segments one by one. MQGMO_LOGICAL_ORDER can be used to retrieve the remaining segments in order.

    An application that puts segments can also set other fields in the message descriptor to values that differ between segments. However, there is no advantage in doing this if the receiving application uses MQGMO_COMPLETE_MSG to retrieve the logical message. When the queue manager reassembles a logical message, it returns in the message descriptor the values from the message descriptor for the first segment; the only exception is the MsgFlags field, which the queue manager sets to indicate that the reassembled message is the only segment.

    If MQGMO_COMPLETE_MSG is specified for a report message, the queue manager performs special processing. The queue manager checks the queue to see if all the report messages of that report type relating to the different segments in the logical message are present on the queue. If they are, they can be retrieved as a single message by specifying MQGMO_COMPLETE_MSG. For this to be possible, either the report messages must be generated by a queue manager or MCA which supports segmentation, or the originating application must request at least 100 bytes of message data (that is, the appropriate MQRO_*_WITH_DATA or MQRO_*_WITH_FULL_DATA options must be specified). If less than the full amount of application data is present for a segment, the missing bytes are replaced by nulls in the report message returned.

    If MQGMO_COMPLETE_MSG is specified with MQGMO_MSG_UNDER_CURSOR or MQGMO_BROWSE_MSG_UNDER_CURSOR, the browse cursor must be positioned on a message whose Offset field in MQMD has a value of 0. If this condition is not satisfied, the call fails with reason code MQRC_INVALID_MSG_UNDER_CURSOR.

    MQGMO_COMPLETE_MSG implies MQGMO_ALL_SEGMENTS_AVAILABLE, which need not therefore be specified.

    MQGMO_COMPLETE_MSG can be specified with any of the other MQGMO_* options apart from MQGMO_SYNCPOINT_IF_PERSISTENT, and with any of the MQMO_* options apart from MQMO_MATCH_OFFSET.

    • On z/OS, this option is supported for private and shared queues, but the queue must have an index type of MQIT_GROUP_ID. For shared queues, the CFSTRUCT object that the queue map to must be at CFLEVEL(3) or higher.
    • On the following platforms:

      • AIX
      • IBM i
      • Linux
      • Windows

      and for IBM MQ MQI clients connected to these systems, this option is supported for all local queues.

    MQGMO_ALL_MSGS_AVAILABLE
    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 MQGMO_ALL_MSGS_AVAILABLE 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 MQRC_NO_MSG_AVAILABLE is returned after the specified wait interval (if any) has expired. The processing of MQGMO_ALL_MSGS_AVAILABLE depends on whether MQGMO_LOGICAL_ORDER is also specified:

    • If both options are specified, MQGMO_ALL_MSGS_AVAILABLE has an effect only when there is no current group or logical message. If there is a current group or logical message, MQGMO_ALL_MSGS_AVAILABLE is ignored. This means that MQGMO_ALL_MSGS_AVAILABLE can remain on when processing messages in logical order.
    • If MQGMO_ALL_MSGS_AVAILABLE is specified without MQGMO_LOGICAL_ORDER, MQGMO_ALL_MSGS_AVAILABLE 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 MQGMO_ALL_MSGS_AVAILABLE means that at the time that the MQGET call was issued, all the messages in the group were on the queue. However, be aware that other applications can still remove messages from the group (the group is not locked to the application that retrieves the first message in the group).

    If we omit this option, messages belonging to groups can be retrieved even when the group is incomplete.

    MQGMO_ALL_MSGS_AVAILABLE implies MQGMO_ALL_SEGMENTS_AVAILABLE, which need not therefore be specified.

    MQGMO_ALL_MSGS_AVAILABLE can be specified with any of the other MQGMO_* options, and with any of the MQMO_* options.

    • On z/OS, this option is supported for private and shared queues, but the queue must have an index type of MQIT_GROUP_ID. For shared queues, the CFSTRUCT object that the queue map to must be at CFLEVEL(3) or higher.
    • On the following platforms:

      • AIX
      • IBM i
      • Linux
      • Windows

      and for IBM MQ MQI clients connected to these systems, this option is supported for all local queues.

    MQGMO_ALL_SEGMENTS_AVAILABLE
    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 MQGMO_ALL_SEGMENTS_AVAILABLE 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 MQRC_NO_MSG_AVAILABLE is returned after the specified wait interval (if any) has expired.

    The processing of MQGMO_ALL_SEGMENTS_AVAILABLE depends on whether MQGMO_LOGICAL_ORDER is also specified:

    • If both options are specified, MQGMO_ALL_SEGMENTS_AVAILABLE has an effect only when there is no current logical message. If there is a current logical message, MQGMO_ALL_SEGMENTS_AVAILABLE is ignored. This means that MQGMO_ALL_SEGMENTS_AVAILABLE can remain on when processing messages in logical order.
    • If MQGMO_ALL_SEGMENTS_AVAILABLE is specified without MQGMO_LOGICAL_ORDER, MQGMO_ALL_SEGMENTS_AVAILABLE 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 MQGMO_COMPLETE_MSG and MQGMO_ALL_SEGMENTS_AVAILABLE require all segments to be available before any of them can be retrieved, the former returns the complete message, whereas the latter allows the segments to be retrieved one by one.

    If MQGMO_ALL_SEGMENTS_AVAILABLE is specified for a report message, the queue manager checks the queue to see if there is at least one report message for each of the segments that make up the complete logical message. If there is, the MQGMO_ALL_SEGMENTS_AVAILABLE condition is satisfied. However, the queue manager does not check the type of the report messages present, and so there might be a mixture of report types in the report messages relating to the segments of the logical message. As a result, the success of MQGMO_ALL_SEGMENTS_AVAILABLE does not imply that MQGMO_COMPLETE_MSG will succeed. If there is a mixture of report types present for the segments of a particular logical message, those report messages must be retrieved one by one.

    We can specify MQGMO_ALL_SEGMENTS_AVAILABLE with any of the other MQGMO_* options, and with any of the MQMO_* options.

    • On z/OS, this option is supported for private and shared queues, but the queue must have an index type of MQIT_GROUP_ID. For shared queues, the CFSTRUCT object that the queue map to must be at CFLEVEL(3) or higher.
    • On the following platforms:

      • AIX
      • IBM i
      • Linux
      • Windows

      and for IBM MQ MQI clients connected to these systems, this option is supported for all local queues.


Property options

The following options relate to the properties of the message:

    MQGMO_PROPERTIES_AS_Q_DEF

    Properties of the message, except those contained in the message descriptor (or extension) should be represented as defined by the PropertyControl queue attribute. If a MsgHandle is provided this option is ignored and the properties of the message are available via the MsgHandle, unless the value of the PropertyControl queue attribute is MQPROP_FORCE_MQRFH2.

    This is the default action if no property options are specified.

    MQGMO_PROPERTIES_IN_HANDLE

    Properties of the message should be made available via the MsgHandle. If no message handle is provided the call fails with reason MQRC_HMSG_ERROR.

    Note: If the message is later read by an application that does not create a message handle, the queue manager places any message properties into an MQRFH2 structure. We might find that the presence of an unexpected MQRFH2 header disrupts the behavior of an existing application.

    MQGMO_NO_PROPERTIES

    No properties of the message, except those contained in the message descriptor (or extension) will be retrieved. If a MsgHandle is provided it will be ignored.

    MQGMO_PROPERTIES_FORCE_MQRFH2

    Properties of the message, except those contained in the message descriptor (or extension) should be represented using MQRFH2 headers. This provides compatibility with earlier version for applications which are expecting to retrieve properties but are unable to be changed to use message handles. If a MsgHandle is provided it is ignored.

    MQGMO_PROPERTIES_COMPATIBILITY
    If the message contains a property with a prefix of "mcd.", "jms.", "usr.", or "mqext.", all message properties are delivered to the application in an MQRFH2 header. Otherwise all properties of the message, except those contained in the message descriptor (or extension), are discarded and are no longer accessible to the application.


Default option

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

    MQGMO_NONE
    Use this value to indicate that no other options have been specified; all options assume their default values. MQGMO_NONE aids 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 Options field is MQGMO_NO_WAIT plus MQGMO_PROPERTIES_AS_Q_DEF.

Parent topic: Fields for MQGMO 1 An MQGET call specifying the MQGMO_LOCK option is treated as a nonbrowse call.