GroupId (MQBYTE24)

This is a byte string that is used to identify the particular message group or logical message to which the physical message belongs. GroupId is also used if segmentation is allowed for the message. In all these cases, GroupId has a non-null value, and one or more of the following flags is set in the MsgFlags field:

  • MQMF_MSG_IN_GROUP
  • MQMF_LAST_MSG_IN_GROUP
  • MQMF_SEGMENT
  • MQMF_LAST_SEGMENT
  • MQMF_SEGMENTATION_ALLOWED

If none of these flags is set, GroupId has the special null value MQGI_NONE. The application does not need to set this field on the MQPUT or MQGET call if:

  • On the MQPUT call, MQPMO_LOGICAL_ORDER is specified.
  • On the MQGET call, MQMO_MATCH_GROUP_ID is not specified.

These are the recommended ways of using these calls for messages that are not report messages. However, if the application requires more control, or the call is MQPUT1, the application must ensure that GroupId is set to an appropriate value. Message groups and segments can be processed correctly only if the group identifier is unique. For this reason, applications must not generate their own group identifiers ; instead, applications must do one of the following:

  • If MQPMO_LOGICAL_ORDER is specified, the queue manager automatically generates a unique group identifier for the first message in the group or segment of the logical message, and uses that group identifier for the remaining messages in the group or segments of the logical message, so the application does not need to take any special action. This is the recommended procedure.
  • If MQPMO_LOGICAL_ORDER is not specified, the application must request the queue manager to generate the group identifier, by setting GroupId to MQGI_NONE on the first MQPUT or MQPUT1 call for a message in the group or segment of the logical message. The group identifier returned by the queue manager on output from that call must then be used for the remaining messages in the group or segments of the logical message. If a message group contains segmented messages, the same group identifier must be used for all segments and messages in the group.

    When MQPMO_LOGICAL_ORDER is not specified, messages in groups and segments of logical messages can be put in any order (for example, in reverse order), but the group identifier must be allocated by the first MQPUT or MQPUT1 call that is issued for any of those messages.

On input to the MQPUT and MQPUT1 calls, the queue manager uses the value described in Physical order on a queue. On output from the MQPUT and MQPUT1 calls, the queue manager sets this field to the value that was sent with the message if the object opened is a single queue and not a distribution list, but leaves it unchanged if the object opened is a distribution list. In the latter case, if the application needs to know the group identifiers generated, the application must provide MQPMR records containing the GroupId field.

On input to the MQGET call, the queue manager uses the value described in Table 2. On output from the MQGET call, the queue manager sets this field to the value for the message retrieved. The following special value is defined:

    MQGI_NONE
    No group identifier specified.

    The value is binary zero for the length of the field. This is the value that is used for messages that are not in groups, not segments of logical messages, and for which segmentation is not allowed.

    For the C programming language, the constant MQGI_NONE_ARRAY is also defined; this has the same value as MQGI_NONE, but is an array of characters instead of a string.

The length of this field is given by MQ_GROUP_ID_LENGTH. The initial value of this field is MQGI_NONE. This field is ignored if Version is less than MQMD_VERSION_2.

Parent topic: Fields for MQMD