MQGETAny call" /> Usage notes
Home

 

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, we 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:

    • If the queue is a nonshared queue (that is, a local queue), all messages within the unit of work become available at the same time.

    • If the queue is a shared queue, messages within the unit of work become available in the order in which they were put, but not all at the same time. When the system is heavily laden, it is possible for the first message in the unit of work to be retrieved successfully, but for the MQGET call for the second or subsequent message in the unit of work to fail with MQRC_NO_MSG_AVAILABLE. If this occurs, the application must wait a short while and then retry the operation.

  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:

    • Only one receiver is getting messages from the queue.

      If there are two or more applications getting messages from the queue, they must agree with the sender the mechanism to be used to identify messages that belong to a sequence. For example, the sender could set all the CorrelId fields in the messages in a sequence to a value that was unique to that sequence of messages.

    • The receiver does not deliberately change the order of retrieval, for example by specifying a particular MsgId or CorrelId.

    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).

    We 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:

    • The Format field in the control information in the message identifies the structure of the application data, and the CodedCharSetId and Encoding fields in the control information in the message specify its character-set identifier and encoding.

    • The application issuing the MQGET call specifies in the CodedCharSetId and Encoding fields in the MsgDesc parameter the character-set identifier and encoding to which to convert the application message data.

    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:

    • The format names listed below are formats that are converted by the queue manager; these are called "built-in" formats:

      • MQFMT_ADMIN

      • MQFMT_CICS (z/OS only)

      • MQFMT_COMMAND_1

      • MQFMT_COMMAND_2

      • MQFMT_DEAD_LETTER_HEADER

      • MQFMT_DIST_HEADER

      • MQFMT_EVENT version 1

      • MQFMT_EVENT version 2 (z/OS only)

      • MQFMT_IMS

      • MQFMT_IMS_VAR_STRING

      • MQFMT_MD_EXTENSION

      • MQFMT_PCF

      • MQFMT_REF_MSG_HEADER

      • MQFMT_RF_HEADER

      • MQFMT_RF_HEADER_2

      • MQFMT_STRING

      • MQFMT_TRIGGER

      • MQFMT_WORK_INFO_HEADER (z/OS only)

      • MQFMT_XMIT_Q_HEADER

    • The format name MQFMT_NONE is a special value that indicates that the nature of the data in the message is undefined. As a consequence, the queue manager does not attempt conversion when the message is retrieved from the queue.
      Note:
      If MQGMO_CONVERT is specified on the MQGET call for a message that has a format name of MQFMT_NONE, and the character set or encoding of the message differs from that specified in the MsgDesc parameter, the message is returned in the Buffer parameter (assuming no other errors), but the call completes with completion code MQCC_WARNING and reason code MQRC_FORMAT_ERROR.

      We can use MQFMT_NONE either when the nature of the message data means that it does not require conversion, or when the sending and receiving applications have agreed between themselves the form in which to send the message data.

    • All other format names pass the message to a user-written exit for conversion. The exit has the same name as the format, apart from environment-specific additions. User-specified format names must not begin with the letters MQ.

      See Appendix F. Data conversion for details of the data-conversion exit.

    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:

    • MQRC_NONE

    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:

    • MQRC_TRUNCATED_MSG_ACCEPTED

    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:

    • Default conversion of the application message data occurs only when all the following are true:

      • The application specifies MQGMO_CONVERT.

      • The message contains data that must be converted either from or to a character set that is not supported.

      • Default conversion was enabled when the queue manager was installed or restarted.

    • Default conversion of the character fields in the MQMD and MQMDE structures occurs as necessary, provided that default conversion is enabled for the queue manager. The conversion is performed even if the MQGMO_CONVERT option is not specified by the application on the MQGET call.

  10. For the Visual Basic programming language, the following points apply:

    • If the size of the Buffer parameter is less than the length specified by the BufferLength parameter, the call fails with reason code MQRC_STORAGE_NOT_AVAILABLE.

    • The Buffer parameter is declared as being of type String. If the data to be retrieved from the queue is not of type String, use the MQGETAny call in place of MQGET.

      The MQGETAny call has the same parameters as the MQGET call, except that the Buffer parameter is declared as being of type Any, allowing any type of data to be retrieved. However, this means that Buffer cannot be checked to ensure that it is at least BufferLength bytes in size.




 

Home