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.

    Messages are not deleted if a browse option is specified on the GetMsgOpts parameter (see MQGMO - Options field). The browse options are: MQGMO_BROWSE_FIRST, MQGMO_BROWSE_NEXT, and MQGMO_BROWSE_MSG_UNDER_CURSOR.

  2. If the MQGMO_LOCK 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 MQGMO_UNLOCK option is specified, a previously-locked message is unlocked. No message is retrieved in this case, and the MsgDesc, BufferLength, Buffer, and DataLength parameters are not checked or altered.

  3. If the application issuing the MQGET call is running as an MQ client, the message retrieved can be lost if, while processing 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 that 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.

    To eliminate the risk of losing messages in this way, always retrieve messages within units of work (that is, by specifying the MQGMO_SYNCPOINT option on the MQGET call, and using the MQCMIT or MQBACK calls to commit or back out the unit of work when message processing is complete). If MQGMO_SYNCPOINT 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, you can eliminate the risk 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 MQPUT usage notes for details. If the conditions are satisfied, the messages are presented to the receiving application in the order in which they were sent, provided that:

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

  6. Applications must test for the feedback code MQFB_QUIT in the Feedback field of the MsgDesc parameter, and end if they find this value. See MQMD - Feedback field for more information.
  7. If the queue identified by Hobj was opened with the MQOO_SAVE_ALL_CONTEXT option, and the completion code from the MQGET call is MQCC_OK or MQCC_WARNING, the context associated with the queue handle Hobj is set to the context of the message that has been retrieved (unless the MQGMO_BROWSE_FIRST, MQGMO_BROWSE_NEXT, or MQGMO_BROWSE_MSG_UNDER_CURSOR option is set, in which case the context is marked as not available).

    You can use the saved context on a subsequent MQPUT or MQPUT1 call by specifying the MQPMO_PASS_IDENTITY_CONTEXT or MQPMO_PASS_ALL_CONTEXT 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 you include the MQGMO_CONVERT option in the GetMsgOpts 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 Format 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 MQRC_SOURCE_CCSID_ERROR or MQRC_TARGET_CCSID_ERROR 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 might have been converted successfully; the application must check the CodedCharSetId and Encoding fields in the MsgDesc parameter to find out:

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

    Note:
    The interpretation of the reason code described above is true for conversions performed by a user-written exit only if the exit conforms to the processing guidelines described in Appendix F. Data conversion.
  9. For the built-in formats listed above, the queue manager can perform default conversion of character strings in the message when the MQGMO_CONVERT 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 MQCC_OK, instead of completing with MQCC_WARNING and reason code MQRC_SOURCE_CCSID_ERROR or MQRC_TARGET_CCSID_ERROR.
    Note:
    The result of using an approximate character set to convert string data is that some characters might be converted incorrectly. To avoid this, use characters in the string that 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. For the Visual Basic programming language, the following points apply: