Usage notes

  1. The message retrieved is normally deleted from the queue. This deletion can occur as part of the MQGET call itself, or as part of a syncpoint. Message deletion does not occur if an GMBRWF or GMBRWN option is specified on the GMO parameter (see the GMOPT field described in MQGMO - Get-message options).
  2. If the GMLK option is specified with one of the browse options, the browsed message is locked so that it is visible only to this handle.

    If the GMUNLK option is specified, a previously-locked message is unlocked. No message is retrieved in this case, and the MSGDSC, BUFLEN, BUFFER and DATLEN parameters are not checked or altered.

  3. If the application issuing the MQGET call is running as an MQ client, it is possible for the message retrieved to be lost if during the processing of the MQGET call the MQ client terminates abnormally or the client connection is severed. This arises because the surrogate that is running on the queue manager's platform and which issues the MQGET call on the client's behalf cannot detect the loss of the client until the surrogate is about to return the message to the client; this is after the message has been removed from the queue. This can occur for both persistent messages and nonpersistent messages.

    The risk of losing messages in this way can be eliminated by always retrieving messages within units of work (that is, by specifying the GMSYP option on the MQGET call, and using the MQCMIT or MQBACK calls to commit or back out the unit of work when processing of the message is complete). If GMSYP is specified, and the client terminates abnormally or the connection is severed, the surrogate backs out the unit of work on the queue manager and the message is reinstated on the queue.

    In principle, the same situation can arise with applications that are running on the queue manager's platform, but in this case the window during which a message can be lost is very small. However, as with MQ clients the risk can be eliminated by retrieving the message within a unit of work.

  4. If an application puts a sequence of messages on a particular queue within a single unit of work, and then commits that unit of work successfully, the messages become available for retrieval as follows:
  5. If an application puts a sequence of messages on the same queue without using message groups, the order of those messages is preserved provided that certain conditions are satisfied. See the usage notes in the description of the MQPUT call for details. If the conditions are satisfied, the messages will be presented to the receiving application in the order in which they were sent, provided that:

    If the sending application put the messages as a message group, the messages will be presented to the receiving application in the correct order provided that the receiving application specifies the GMLOGO option on the MQGET call. For more information about message groups, see:

  6. Applications should test for the feedback code FBQUIT in the MDFB field of the MSGDSC parameter. If this value is found, the application should end. See the MDFB field described in MQMD - Message descriptor for more information.
  7. If the queue identified by HOBJ was opened with the OOSAVA option, and the completion code from the MQGET call is CCOK or CCWARN, the context associated with the queue handle HOBJ is set to the context of the message that has been retrieved (unless the GMBRWF or GMBRWN option is set, in which case the context is marked as not available). This context can be used on a subsequent MQPUT or MQPUT1 call by specifying the PMPASI or PMPASA options. This enables the context of the message received to be transferred in whole or in part to another message (for example, when the message is forwarded to another queue). For more information on message context, see the WebSphere MQ Application Programming Guide.
  8. If the GMCONV option is included in the GMO parameter, the application message data is converted to the representation requested by the receiving application, before the data is placed in the BUFFER parameter:

    When conversion of the message data is necessary, the conversion is performed either by the queue manager itself or by a user-written exit, depending on the value of the MDFMT field in the control information in the message:

    User data in the message can be converted between any supported character sets and encodings. However, be aware that if the message contains one or more MQ header structures, the message cannot be converted from or to a character set that has double-byte or multi-byte characters for any of the characters that are valid in queue names. Reason code RC2111 or RC2115 results if this is attempted, and the message is returned unconverted. Unicode character set UCS-2 is an example of such a character set.

    On return from MQGET, the following reason code indicates that the message was converted successfully:

    The following reason code indicates that the message may have been converted successfully; the application should check the MDCSI and MDENC fields in the MSGDSC parameter to find out:

    All other reason codes indicate that the message was not converted.

    Note:
    The interpretation of the reason code described above will be true for conversions performed by user-written exits only if the exit conforms to the processing guidelines.
  9. For the built-in formats listed above, the queue manager may perform default conversion of character strings in the message when the GMCONV option is specified. Default conversion allows the queue manager to use an installation-specified default character set that approximates the actual character set, when converting string data. As a result, the MQGET call can succeed with completion code CCOK, instead of completing with CCWARN and reason code RC2111 or RC2115.
    Note:
    The result of using an approximate character set to convert string data is that some characters may be converted incorrectly. This can be avoided by using in the string only characters which are common to both the actual character set and the default character set.

    Default conversion applies both to the application message data and to character fields in the MQMD and MQMDE structures:

  10. The BUFFER parameter shown in the RPG programming example is declared as a string; this restricts the maximum length of the parameter to 256 bytes. If a larger buffer is required, the parameter should be declared instead as a structure, or as a field in a physical file.

    Declaring the parameter as a structure increases the maximum length possible to 9999 bytes, while declaring the parameter as a field in a physical file increases the maximum length possible to approximately 32K bytes.