MQGMO - Get-message options

The MQGMO structure allows the application to control how messages are removed from queues. The structure is an input/output parameter on the MQGET call.

Version

The current version of MQGMO is MQGMO_VERSION_4. Certain fields are available only in certain versions of MQGMO. If you need to port applications between several environments, you must ensure that the version of MQGMO is consistent across all environments. Fields that exist only in particular versions of the structure are identified as such in MQGMO - Get-message options and in the field descriptions.

The header, COPY, and INCLUDE files provided for the supported programming languages contain the most recent version of MQGMO that is supported by the environment, but with the initial value of the Version field set to MQGMO_VERSION_1. To use fields that are not present in the version-1 structure, set the Version 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 MQENC_NATIVE. However, if the application is running as an MQ MQI client, the structure must be in the character set and encoding of the client.

Fields

Note: In the following table, the fields are grouped by usage rather than alphabetically. The child topics follow the same sequence.
Table 1. Fields in MQGMO for MQGMO
Field name and description Name of constant Initial value (if any) of constant
StrucId (structure identifier) MQGMO_STRUC_ID 'GMO¬'
Version (structure version number) MQGMO_VERSION_1 1
MQGMO - Options field (options that control the action of MQGET) MQGMO_NO_WAIT 0
WaitInterval (wait interval) None 0
Signal1 (signal) None Null pointer on z/OS® ; 0 otherwise
Signal2 (signal identifier) None 0
ResolvedQName (resolved name of destination queue) None Null string or blanks
Note: The remaining fields are ignored if Version is less than MQGMO_VERSION_2.
MatchOptions (options controlling selection criteria used for MQGET) MQMO_MATCH_MSG_ID + MQMO_MATCH_CORREL_ID 3
GroupStatus (flag indicating whether message retrieved is in a group) MQGS_NOT_IN_GROUP '¬'
SegmentStatus (flag indicating whether message retrieved is a segment of a logical message) MQSS_NOT_A_SEGMENT '¬'
Segmentation (flag indicating whether further segmentation is allowed for the message retrieved) MQSEG_INHIBITED '¬'
Reserved1 (reserved) None '¬'
Note: The remaining fields are ignored if Version is less than MQGMO_VERSION_3.
MsgToken (message token) MQMTOK_NONE Nulls
ReturnedLength (length in bytes of message data returned) MQRL_UNDEFINED -1
Note: The remaining fields are ignored if Version is less than MQGMO_VERSION_4.
Reserved2 (reserved) None '¬'
MsgHandle (handle to a message that is to be populated with the properties of the message being retrieved from the queue) MQHM_NONE 0
Notes:
  1. The symbol ¬ represents a single blank character.
  2. The value Null string or blanks denotes the null string in C, and blank characters in other programming languages.
  3. In the C programming language, the macro variable MQGMO_DEFAULT contains the values that are listed in the table. It can be used in the following way to provide initial values for the fields in the structure: 
    
MQGMO MyGMO = {MQGMO_DEFAULT};

Language declarations

C declaration for MQGMO


typedef struct tagMQGMO MQGMO;
struct tagMQGMO {
  MQCHAR4   StrucId;         /* Structure identifier */
  MQLONG    Version;         /* Structure version number */
  MQLONG    Options;         /* Options that control the action of */
                                MQGET */
  MQLONG    WaitInterval;    /* Wait interval */
  MQLONG    Signal1;         /* Signal */
  MQLONG    Signal2;         /* Signal identifier */
  MQCHAR48  ResolvedQName;   /* Resolved name of destination queue */
  /* Ver:1 */
  MQLONG    MatchOptions;    /* Options controlling selection */
                                criteria used for MQGET */
  MQCHAR    GroupStatus;     /* Flag indicating whether message */
                                retrieved is in a group */
  MQCHAR    SegmentStatus;   /* Flag indicating whether message */
                                retrieved is a segment of a logical */
                                message */
  MQCHAR    Segmentation;    /* Flag indicating whether further */
                                segmentation is allowed for the */
                                message retrieved */
  MQCHAR    Reserved1;       /* Reserved */
  /* Ver:2 */
  MQBYTE16  MsgToken;        /* Message token */
  MQLONG    ReturnedLength;  /* Length of message data returned */
                                (bytes) */
  /* Ver:3 */
  MQLONG    Reserved2;       /* Reserved */
  MQHMSG    MsgHandle;       /* Message handle */
  /* Ver:4 */
};
Note: On z/OS, the Signal1 field is declared as PMQLONG.

COBOL declaration for MQGMO


**   MQGMO structure
  10 MQGMO.
**    Structure identifier
   15 MQGMO-STRUCID        PIC X(4).
**    Structure version number
   15 MQGMO-VERSION        PIC S9(9) BINARY.
**    Options that control the action of MQGET
   15 MQGMO-OPTIONS        PIC S9(9) BINARY.
**    Wait interval
   15 MQGMO-WAITINTERVAL   PIC S9(9) BINARY.
**    Signal
   15 MQGMO-SIGNAL1        PIC S9(9) BINARY.
**    Signal identifier
   15 MQGMO-SIGNAL2        PIC S9(9) BINARY.
**    Resolved name of destination queue
   15 MQGMO-RESOLVEDQNAME  PIC X(48).
**    Options controlling selection criteria used for MQGET
   15 MQGMO-MATCHOPTIONS   PIC S9(9) BINARY.
**    Flag indicating whether message retrieved is in a group
   15 MQGMO-GROUPSTATUS    PIC X.
**    Flag indicating whether message retrieved is a segment of a
**    logical message
   15 MQGMO-SEGMENTSTATUS  PIC X.
**    Flag indicating whether further segmentation is allowed for the
**    message retrieved
   15 MQGMO-SEGMENTATION   PIC X.
**    Reserved
   15 MQGMO-RESERVED1      PIC X.
**    Message token
   15 MQGMO-MSGTOKEN       PIC X(16).
**    Length of message data returned (bytes)
   15 MQGMO-RETURNEDLENGTH PIC S9(9) BINARY.
**    Reserved
   15 MQGMO-RESERVED2      PIC S9(9) BINARY.
**    Message handle
   15 MQGMO-MSGHANDLE      PIC S9(18) BINARY.
Note: On z/OS, the Signal1 field is declared as POINTER.

PL/I declaration for MQGMO


dcl
 1 MQGMO based,
  3 StrucId        char(4),       /* Structure identifier */
  3 Version        fixed bin(31), /* Structure version number */
  3 Options        fixed bin(31), /* Options that control the action of
                                     MQGET */
  3 WaitInterval   fixed bin(31), /* Wait interval */
  3 Signal1        fixed bin(31), /* Signal */
  3 Signal2        fixed bin(31), /* Signal identifier */
  3 ResolvedQName  char(48),      /* Resolved name of destination
                                     queue */
  3 MatchOptions   fixed bin(31), /* Options controlling selection
                                     criteria used for MQGET */
  3 GroupStatus    char(1),       /* Flag indicating whether message
                                     retrieved is in a group */
  3 SegmentStatus  char(1),       /* Flag indicating whether message
                                     retrieved is a segment of a logical
                                     message */
  3 Segmentation   char(1),       /* Flag indicating whether further
                                     segmentation is allowed for the
                                     message retrieved */
  3 Reserved1      char(1),       /* Reserved */
  3 MsgToken       char(16),      /* Message token */
  3 ReturnedLength fixed bin(31); /* Length of message data returned
                                     (bytes) */
  3 Reserved2      fixed bin(31); /* Reserved */
  3 MsgHandle      fixed bin(63); /* Message handle */
Note: On z/OS, the Signal1 field is declared as pointer.

High Level Assembler declaration for MQGMO


MQGMO                 DSECT
MQGMO_STRUCID         DS   CL4   Structure identifier
MQGMO_VERSION         DS   F     Structure version number
MQGMO_OPTIONS         DS   F     Options that control the action of
*                                MQGET
MQGMO_WAITINTERVAL    DS   F     Wait interval
MQGMO_SIGNAL1         DS   F     Signal
MQGMO_SIGNAL2         DS   F     Signal identifier
MQGMO_RESOLVEDQNAME   DS   CL48  Resolved name of destination queue
MQGMO_MATCHOPTIONS    DS   F     Options controlling selection criteria
*                                used for MQGET
MQGMO_GROUPSTATUS     DS   CL1   Flag indicating whether message
*                                retrieved is in a group
MQGMO_SEGMENTSTATUS   DS   CL1   Flag indicating whether message
*                                retrieved is a segment of a logical
*                                message
MQGMO_SEGMENTATION    DS   CL1   Flag indicating whether further
*                                segmentation is allowed for the message
*                                retrieved
MQGMO_RESERVED1       DS   CL1   Reserved
MQGMO_MSGTOKEN        DS   XL16  Message token
MQGMO_RETURNEDLENGTH  DS   F     Length of message data returned (bytes)
MQGMO_RESERVED2       DS   F     Reserved
MQGMO_MSGHANDLE       DS   D     Message handle
MQGMO_LENGTH          EQU  *-MQGMO
                      ORG  MQGMO
MQGMO_AREA            DS   CL(MQGMO_LENGTH)

High Level Assembler declaration for MQGMO


Type MQGMO
  StrucId        As String*4  'Structure identifier'
  Version        As Long      'Structure version number'
  Options        As Long      'Options that control the action of MQGET'
  WaitInterval   As Long      'Wait interval'
  Signal1        As Long      'Signal'
  Signal2        As Long      'Signal identifier'
  ResolvedQName  As String*48 'Resolved name of destination queue'
  MatchOptions   As Long      'Options controlling selection criteria'
                              'used for MQGET'
  GroupStatus    As String*1  'Flag indicating whether message'
                              'retrieved is in a group'
  SegmentStatus  As String*1  'Flag indicating whether message'
                              'retrieved is a segment of a logical'
                              'message'
  Segmentation   As String*1  'Flag indicating whether further'
                              'segmentation is allowed for the message'
                              'retrieved'
  Reserved1      As String*1  'Reserved'
  MsgToken       As MQBYTE16  'Message token'
  ReturnedLength As Long      'Length of message data returned (bytes)'
End Type

PROPCTL channel options for MQGMO

Use the PROPCTL channel attribute to control which message properties are included in a message that is sent from an IBM® MQ 9.1 queue manager to a partner queue manager from an earlier version of IBM MQ.

Table 2. Channel message property attribute settings
PROPCTL Description
ALL

Use this option if applications connected to the partner queue manager from an earlier version are able to process any properties placed in a message by an IBM MQ 9.1 application.

All properties are sent to the partner queue manager, in addition to any name-value pairs placed in the MQRFH2.

You must consider two application design issues:
  1. An application connected to the partner queue manager must be able to process messages containing MQRFH2 headers generated on an IBM MQ 9.1 queue manager.
  2. The application connected to the partner queue manager must process new message properties that are flagged with MQPD_SUPPORT_REQUIRED correctly.

With the ALL channel option set, JMS applications can interoperate between IBM MQ 9.1 and an earlier version using the channel. New IBM MQ 9.1 applications using message properties can interoperate with applications from an earlier version, depending on how the earlier version application handles MQRFH2 headers.

COMPAT

Use this option to send message properties to applications connected to an earlier version partner queue manager in some cases, but not all. Message properties are only sent if two conditions are met:

  1. No property must be marked as requiring message property processing.
  2. At least one of the message properties must be in a reserved folder; see Note.

With the COMPAT channel option set, JMS applications can interoperate between IBM MQ 9.1 and an earlier version using the channel.

The channel is not available to every application using message properties, only to those applications that use the reserved folders. The rules concerning whether the message or the property is sent are:

  1. If the message has properties, but none of the properties are associated with a reserved folder, then no message properties are sent.
  2. If any message property has been created in a reserved property folder, all message properties associated with the message are sent. However:
    1. If any of the message properties are marked as support being required, MQPD_SUPPORT_REQUIRED or MQPD_SUPPORT_REQUIRED_IF_LOCAL, the whole message is rejected. It is returned, discarded, or sent to the dead letter queue according to the value of its report options.
    2. If no message properties are marked as support being required, an individual property might not be sent. If any of the message property descriptor fields are set to non-default values the individual property is not sent. The message is still sent. An example of a non-default property descriptor field value is MQPD_USER_CONTEXT.
Note: The reserved folders names start with mcd., jms., usr., or mqext.. These folders are created for applications that use the JMS interface. In IBM MQ 9.1 any name-value pairs that are placed in these folders are treated as message properties.

Message properties are sent in an MQRFH2 header, in addition to any name-value pairs placed in an MQRFH2 header. Any name-value pairs placed in an MQRFH2 header are sent as long as the message is not rejected.

NONE

Use this option to prevent any message properties being sent to applications connected to an earlier version partner queue manager. An MQRFH2 that contains name-value pairs and message properties is still sent, but only with the name-value pairs.

With the NONE channel option set, a JMS message is sent as a JMSTextMessage or a JMSBytesMessage without any JMS message properties. If it is possible for an earlier version application to ignore all properties set in an IBM MQ 9.1 application, it can interoperate with it.

PROPCTL queue options for MQGMO

Use the PROPCTL queue attribute to control how message properties are returned to an application that calls MQGET without setting any MQGMO message property options.

Table 3. Queue message property attribute settings
PROPCTL Description
ALL

Use the ALL option so that different applications reading a message from the same queue can process the message in different ways.

  • An application, migrated unchanged from an earlier version, can continue to read the MQRFH2 directly. Properties are directly accessible in the MQRFH2 header.

    You must modify the application to handle any new properties, and new property attributes. It is possible that the application might be affected by changes in the layout and number of MQRFH2 headers. Some folder attributes might be removed, or that IBM MQ reports an error in the layout of the MQRFH2 header that it ignored in an earlier version.

  • A new or changed application can use the message property MQI to query message properties, and read name-value pairs in MQRFH2 header directly.
All the properties in the message are returned to the application.
  • If the application calls MQCRTMH to create a message handle, it must query the message properties using MQINQMP. Name-value pairs that are not message properties remain in the MQRFH2, which is stripped of any message properties.
  • If the application does not create a message handle, all the message properties and name-value pairs remain in the MQRFH2.

ALL only has this effect if the receiving application has not set a MQGMO_PROPERTIES option, or has set it to MQGMO_PROPERTIES_AS_Q_DEF.

COMPAT (default)

COMPAT is the default option. If GMO_PROPERTIES_* is not set, as in an unmodified application from an earlier version, COMPAT is assumed. By defaulting to the COMPAT option, an earlier version application that did not explicitly create an MQRFH2, works without change on IBM MQ 9.1.

Use this option if you have written an earlier version application MQI application to read JMS messages.

  • The JMS properties, which are stored in an MQRFH2 header, are returned to the application in an MQRFH2 header in folders with names starting with mcd., jms., usr., or mqext.
  • If the message has JMS folders, and if an IBM MQ 9.1 application adds new property folders to the message, these properties are also returned in the MQRFH2. Consequently, you must modify the application to handle any new properties, and new property attributes. It is possible that an unmodified application might be affected by changes in the layout and number of MQRFH2 headers. It might find some folder attributes are removed, or that IBM MQ finds errors in the layout of the MQRFH2 header that it ignored in an earlier version.
    Note: In this scenario, the behavior of the application is the same whether it is connected to an earlier version or IBM MQ 9.1 queue manager. If the channel PROPCTL attribute is set to COMPAT or ALL any new message properties are sent in the message to the earlier version partner queue manager.
  • If the message is not a JMS message, but contains other properties, those properties are not returned to the application in an MQRFH2 header. 1
  • The option also enables earlier version applications that explicitly create an MQRFH2 to work correctly, in many cases. For example, An MQI program that creates an MQRFH2 containing JMS message properties continues to work correctly. If a message is created without JMS message properties, but with some other MQRFH2 folders, the folders are returned to the application. Only if the folders are message property folders are those specific folders are removed from the MQRFH2. Message property folders are identified by having the new folder attribute content='properties', or are folders with names listed in Defined property folder name or Ungrouped property folder name.
  • If the application calls MQCRTMH to create a message handle, it must query the message properties using MQINQMP. Message properties are removed from the MQRFH2 headers. Name-value pairs that are not message properties remain in the MQRFH2.
  • If the application calls MQCRTMH to create a message handle, it can query all message properties, regardless of whether the message has JMS folders.
  • If the application does not create a message handle, all the message properties and name-value pairs remain in the MQRFH2.

If a message contains new user property folders, you can infer that the message was created by a new or changed IBM MQ 9.1 application. If the receiving application is to process these new properties directly in an MQRFH2, you must modify the application to use the ALL option. With the default COMPAT option set, an unmodified application continues to process the rest of the MQRFH2, without the IBM MQ 9.1 properties.

The intent of the PROPCTL interface is to support old applications reading MQRFH2 folders, and new and changed applications using the message property interface. Aim for new applications to use the message property interface for all user message properties, and to avoid reading and writing MQRFH2 headers directly.

COMPAT only has this effect if the receiving application has not set a MQGMO_PROPERTIES option, or has set it to MQGMO_PROPERTIES_AS_Q_DEF.

FORCE

The FORCE option places all messages properties into MQRFH2 headers. All message properties and name-value pairs in the MQRFH2 headers remain in the message. Message properties are not removed from the MQRFH2, and made available through a message handle. The effect of choosing the FORCE option is to enable a newly migrated application to read message properties from MQRFH2 headers.

Suppose you have modified an application to process IBM MQ 9.1 message properties, but have also retained its ability to work directly with MQRFH2 headers, as before. You can decide when to switch the application over to using message properties by initially setting the PROPCTL queue attribute to FORCE. Set the PROPCTL queue attribute to another value when you are ready to start using message properties. If the new function in the application does not behave as you expected, set the PROPCTL option back to FORCE.

FORCE only has this effect if the receiving application has not set a MQGMO_PROPERTIES option, or has set it to MQGMO_PROPERTIES_AS_Q_DEF.

NONE
Use the NONE option so that an existing application can process a message, ignoring all message properties, and a new or changed application can query message properties.
  • If the application calls MQCRTMH to create a message handle, it must query the message properties using MQINQMP. Name-value pairs that are not message properties remain in the MQRFH2, which is stripped of any message properties.
  • If the application does not create a message handle, all the message properties are removed from the MQRFH2. Name-value pairs in the MQRFH2 headers remain in the message.

NONE only has this effect if the receiving application has not set a MQGMO_PROPERTIES option, or has set it to MQGMO_PROPERTIES_AS_Q_DEF.

V6COMPAT

Use this option to receive an MQRFH2 in the same format as it was sent. If the sending application, or the queue manager, creates additional message properties, these are returned in the message handle.

This option has to be set on both the sending and receiving queues, and any intervening transmission queues. It overrides any other PROPCTL options set on queue definitions in the queue name resolution path.

Use the V6COMPAT option only in exceptional circumstances. For example, if you are migrating applications from an earlier version to IBM MQ 9.1, the option is valuable because it preserves the behavior of the earlier version. The option is likely to have an impact on message throughput. It is also more difficult to administer; you need to ensure the option is set on the sender, receiver, and intervening transmission queues.

V6COMPAT only has this effect if the receiving application has not set a MQGMO_PROPERTIES option, or has set it to MQGMO_PROPERTIES_AS_Q_DEF.

For more information about message properties and name-value pairs, see NameValueData ( MQCHARn).

Message property options for MQGMO

Use the MQGMO message property options to control how message properties are returned to an application.

Table 4. MQGMO message property option settings
MQGMO Option Description
MQGMO_PROPERTIES_AS_Q_DEF

IBM MQ applications that read from the same queue, and do not set GMO_PROPERTIES_*, receive the message properties differently. IBM MQ applications that do not create a message handle, are controlled by the queue PROPCTL attribute. An IBM MQ application can choose to receive message properties in the MQRFH2, or create a message handle and query the message properties. If the application creates a message handle, properties are removed from the MQRFH2.

  • A new or changed IBM MQ application that does not set GMO_PROPERTIES_* or sets it to MQGMO_PROPERTIES_AS_Q_DEF can choose to query message properties. It must set MQCRTMH to create a message handle and query message properties using the MQINQMP MQI call.
  • If a new or changed application does not create a message handle, it must read any message properties it receives directly from the MQRFH2 headers.
  • If the queue attribute PROPCTL is set to FORCE, no properties are returned in the message handle. All properties are returned in MQRFH2 headers.
  • If the queue attribute PROPCTL is set to NONE, or COMPAT, an IBM MQ application that creates a message handle, receives all message properties.
MQGMO_PROPERTIES_IN_HANDLE

Force an application to use message properties. Use this option to detect if a modified application fails to create message handle. The application might be trying to read message properties directly from an MQRFH2, rather than call MQINQMP.

MQGMO_NO_PROPERTIES
  • All properties are removed. . Queue manager generated properties, such as JMS properties, are removed.

  • Properties are removed even if a message handle is created. Name-value pairs in other MQRFH2 folders are available in the message data.

MQGMO_PROPERTIES_FORCE_MQRFH2

Properties are returned in the MQRFH2 headers, even if a message handle is created.

  • MQINQMP returns no message properties, even if a message handle is created. MQRC_PROPERTY_NOT_AVAILABLE is returned if a property is inquired upon.
MQGMO_PROPERTIES_COMPATIBILITY

If the message is from a JMS client, the JMS properties are returned in the MQRFH2 headers. New or modified IBM MQ applications, that create a message handle, behave differently.

  • All properties in any message property folders are returned if the message contains a mcd., jms., usr., or mqext folder.
  • If the message contains property folders, but not a mcd., jms., usr., or mqext folder, no message properties are returned in an MQRFH2.
  • If a new or modified IBM MQ application creates a message handle, query message properties using the MQINQMP MQI call. All message properties are removed from the MQRFH2.
  • If a new or modified IBM MQ application creates a message handle, all properties in the message can be queried. Even if the message does not contain a mcd., jms., usr., or mqext folder, all message properties are queriable.
1 The existence of specific property folders created by the IBM MQ classes for JMS indicates a JMS message. The property folders are mcd., jms., usr., or mqext.