MQGET - Get message

The MQGET call retrieves a message from a local queue that has been opened using the MQOPEN call.


Syntax

MQGET (Hconn, Hobj, MsgDesc, GetMsgOpts, BufferLength, Buffer, DataLength, CompCode, Reason)


Parameters

    Hconn
    Type: MQHCONN - input

    This handle represents the connection to the queue manager. The value of Hconn was returned by a previous MQCONN or MQCONNX call.

    On z/OS for CICS applications the MQCONN call can be omitted, and the following value specified for Hconn :

      MQHC_DEF_HCONN
      Default connection handle.

    Hobj
    Type: MQHOBJ - input This handle represents the queue from which a message is to be retrieved. The value of Hobj was returned by a previous MQOPEN call. The queue must have been opened with one or more of the following options (see MQOPEN - Open object for details):

    • MQOO_INPUT_SHARED
    • MQOO_INPUT_EXCLUSIVE
    • MQOO_INPUT_AS_Q_DEF
    • MQOO_BROWSE

    MsgDesc
    Type: MQMD - input/output

    This structure describes the attributes of the message required, and the attributes of the message retrieved. See MQMD - Message descriptor for details.

    If BufferLength is less than the message length, MsgDesc is filled by the queue manager, whether MQGMO_ACCEPT_TRUNCATED_MSG is specified on the GetMsgOpts parameter (see MQGMO - Options field ).

    If the application provides a version-1 MQMD, the message returned has an MQMDE prefixed to the application message data, but only if one or more of the fields in the MQMDE has a nondefault value. If all the fields in the MQMDE have default values, the MQMDE is omitted. A format name of MQFMT_MD_EXTENSION in the Format field in MQMD indicates that an MQMDE is present.

    The application does not need to provide an MQMD structure if a valid message handle is supplied in the MsgHandle field. If nothing is provided in this field, the descriptor of the message is taken from the descriptor associated with the message handles.

    If the application provides a message handle rather than an MQMD structure, and specifies MQGMO_PROPERTIES_FORCE_MQRFH2, the call fails with reason code MQRC_MD_ERROR. The call also fails, with reason code MQRC_MD_ERROR, if the application does not provide an MQMD structure and specifies MQGMO_PROPERTIES_AS_Q_DEF, and the PropertyControl queue attribute is MQPROP_FORCE_MQRFH2.

    If match options are specified and the message descriptor associated with the message handle is being used, the input fields used for matching come from the message handle.

    GetMsgOpts
    Type: MQGMO - input/output

    See MQGMO - Get-message options for details.

    BufferLength
    Type: MQLONG - input

    This is the length in bytes of the Buffer area. Specify zero for messages that have no data, or if the message is to be removed from the queue and the data discarded (we must specify MQGMO_ACCEPT_TRUNCATED_MSG in this case).

    Note: The length of the longest message that it is possible to read from the queue is given by the MaxMsgLength queue attribute; see Attributes for queues.

    Buffer
    Type: MQBYTExBufferLength - output

    This is the area to contain the message data. Align the buffer on a boundary appropriate to the nature of the data in the message. 4 byte alignment is suitable for most messages (including messages containing IBM MQ header structures), but some messages might require more stringent alignment. For example, a message containing a 64 bit binary integer might require 8-byte alignment.

    If BufferLength is less than the message length, as much of the message as possible is moved into Buffer. This happens whether MQGMO_ACCEPT_TRUNCATED_MSG is specified on the GetMsgOpts parameter (see MQGMO - Options field for more information).

    The character set and encoding of the data in Buffer are given by the CodedCharSetId and Encoding fields returned in the MsgDesc parameter. If these values are different from the values required by the receiver, the receiver must convert the application message data to the character set and encoding required. The MQGMO_CONVERT option can be used (with a user-written exit if necessary) to convert the message data; see MQGMO - Get-message options for details of this option.

    Note: All the other parameters on the MQGET call are in the character set and encoding of the local queue manager (given by the CodedCharSetId queue manager attribute and MQENC_NATIVE).

    If the call fails, the contents of the buffer might still have changed.

    In the C programming language, the parameter is declared as a pointer-to-void: the address of any type of data can be specified as the parameter.

    If the BufferLength parameter is zero, Buffer is not referred to; in this case, the parameter address passed by programs written in C or System/390 assembler can be null.

    DataLength
    Type: MQLONG - output

    This is the length in bytes of the application data in the message. If this value is greater than BufferLength, only BufferLength bytes are returned in the Buffer parameter (that is, the message is truncated). If the value is zero, the message contains no application data.

    If BufferLength is less than the message length, DataLength is still completed by the queue manager, whether MQGMO_ACCEPT_TRUNCATED_MSG is specified on the GetMsgOpts parameter (see MQGMO - Options field for more information). This allows the application to determine the size of the buffer required to accommodate the message data, and then reissue the call with a buffer of the appropriate size.

    However, if the MQGMO_CONVERT option is specified, and the converted message data is too long to fit in Buffer, the value returned for DataLength is:

    • The length of the unconverted data, for queue manager defined formats.

      In this case, if the nature of the data causes it to expand during conversion, the application must allocate a buffer bigger than the value returned by the queue manager for DataLength.

    • The value returned by the data-conversion exit, for application-defined formats.

    CompCode
    Type: MQLONG - output The completion code; it is one of the following:

      MQCC_OK
      Successful completion.

      MQCC_WARNING
      Warning (partial completion).

      MQCC_FAILED
      Call failed.

    Reason
    Type: MQLONG - output

    The reason codes listed are the ones that the queue manager can return for the Reason parameter. If the application specifies the MQGMO_CONVERT option, and a user-written exit is invoked to convert some or all the message data, the exit decides what value is returned for the Reason parameter. As a result, values other than those values documented are possible.

    If CompCode is MQCC_OK:

      MQRC_NONE
      (0, X'000') No reason to report.

    If CompCode is MQCC_WARNING:

      MQRC_CONVERTED_MSG_TOO_BIG
      (2120, X'848') Converted data too large for buffer.

      MQRC_CONVERTED_STRING_TOO_BIG
      (2190, X'88E') Converted string too large for field.

      MQRC_DBCS_ERROR
      (2150, X'866') DBCS string not valid.

      MQRC_FORMAT_ERROR
      (2110, X'83E') Message format not valid.

      MQRC_INCOMPLETE_GROUP
      (2241, X'8C1') Message group not complete.

      MQRC_INCOMPLETE_MSG
      (2242, X'8C2') Logical message not complete.

      MQRC_INCONSISTENT_CCSIDS
      (2243, X'8C3') Message segments have differing CCSIDs.

      MQRC_INCONSISTENT_ENCODINGS
      (2244, X'8C4') Message segments have differing encodings.

      MQRC_INCONSISTENT_UOW
      (2245, X'8C5') Inconsistent unit-of-work specification.

      MQRC_MSG_TOKEN_ERROR
      (2331, X'91B') Invalid use of message token.

      MQRC_NO_MSG_LOCKED
      (2209, X'8A1') No message locked.

      MQRC_NOT_CONVERTED
      (2119, X'847') Message data not converted.

      MQRC_OPTIONS_CHANGED
      (nnnn, X'xxx') Options that were required to be consistent have been changed.

      MQRC_PARTIALLY_CONVERTED
      (2272, X'8E0') Message data partially converted.

      MQRC_SIGNAL_REQUEST_ACCEPTED
      (2070, X'816') No message returned (but signal request accepted).

      MQRC_SOURCE_BUFFER_ERROR
      (2145, X'861') Source buffer parameter not valid.

      MQRC_SOURCE_CCSID_ERROR
      (2111, X'83F') Source coded character set identifier not valid.

      MQRC_SOURCE_DECIMAL_ENC_ERROR
      (2113, X'841') Packed-decimal encoding in message not recognized.

      MQRC_SOURCE_FLOAT_ENC_ERROR
      (2114, X'842') Floating-point encoding in message not recognized.

      MQRC_SOURCE_INTEGER_ENC_ERROR
      (2112, X'840') Source integer encoding not recognized.

      MQRC_SOURCE_LENGTH_ERROR
      (2143, X'85F') Source length parameter not valid.

      MQRC_TARGET_BUFFER_ERROR
      (2146, X'862') Target buffer parameter not valid.

      MQRC_TARGET_CCSID_ERROR
      (2115, X'843') Target coded character set identifier not valid.

      MQRC_TARGET_DECIMAL_ENC_ERROR
      (2117, X'845') Packed-decimal encoding specified by receiver not recognized.

      MQRC_TARGET_FLOAT_ENC_ERROR
      (2118, X'846') Floating-point encoding specified by receiver not recognized.

      MQRC_TARGET_INTEGER_ENC_ERROR
      (2116, X'844') Target integer encoding not recognized.

      MQRC_TRUNCATED_MSG_ACCEPTED
      (2079, X'81F') Truncated message returned (processing completed).

      MQRC_TRUNCATED_MSG_FAILED
      (2080, X'820') Truncated message returned (processing not completed).

    If CompCode is MQCC_FAILED:

      MQRC_ADAPTER_NOT_AVAILABLE
      (2204, X'89C') Adapter not available.

      MQRC_ADAPTER_CONV_LOAD_ERROR
      (2133, X'855') Unable to load data conversion services modules.

      MQRC_ADAPTER_SERV_LOAD_ERROR
      (2130, X'852') Unable to load adapter service module.

      MQRC_API_EXIT_ERROR
      (2374, X'946') API exit failed.

      MQRC_API_EXIT_LOAD_ERROR
      (2183, X'887') Unable to load API exit.

      MQRC_ASID_MISMATCH
      (2157, X'86D') Primary and home ASIDs differ.

      MQRC_BACKED_OUT
      (2003, X'7D3') Unit of work backed out.

      MQRC_BUFFER_ERROR
      (2004, X'7D4') Buffer parameter not valid.

      MQRC_BUFFER_LENGTH_ERROR
      (2005, X'7D5') Buffer length parameter not valid.

      MQRC_CALL_IN_PROGRESS
      (2219, X'8AB') MQI call entered before previous call complete.

      MQRC_CF_NOT_AVAILABLE
      (2345, X'929') Coupling facility not available.

      MQRC_CF_STRUC_FAILED
      (2373, X'945') Coupling-facility structure failed.

      MQRC_CF_STRUC_IN_USE
      (2346, X'92A') Coupling-facility structure in use.

      MQRC_CF_STRUC_LIST_HDR_IN_USE
      (2347, X'92B') Coupling-facility structure list-header in use.

      MQRC_CICS_WAIT_FAILED
      (2140, X'85C') Wait request rejected by CICS.

      MQRC_CONNECTION_BROKEN
      (2009, X'7D9') Connection to queue manager lost.

      MQRC_CONNECTION_NOT_AUTHORIZED
      (2217, X'8A9') Not authorized for connection.

      MQRC_CONNECTION_QUIESCING
      (2202, X'89A') Connection quiescing.

      MQRC_CONNECTION_STOPPING
      (2203, X'89B') Connection shutting down.

      MQRC_CORREL_ID_ERROR
      (2207, X'89F') Correlation-identifier error.

      MQRC_DATA_LENGTH_ERROR
      (2010, X'7DA') Data length parameter not valid.

      MQRC_DB2_NOT_AVAILABLE
      (2342, X'926') Db2 subsystem not available.

      MQRC_GET_INHIBITED
      (2016, X'7E0') Gets inhibited for the queue.

      MQRC_GLOBAL_UOW_CONFLICT
      (2351, X'92F') Global units of work conflict.

      MQRC_GMO_ERROR
      (2186, X'88A') Get-message options structure not valid.

      MQRC_HANDLE_IN_USE_FOR_UOW
      (2353, X'931') Handle in use for global unit of work.

      MQRC_HCONN_ERROR
      (2018, X'7E2') Connection handle not valid.

      MQRC_HOBJ_ERROR
      (2019, X'7E3') Object handle not valid.

      MQRC_INCONSISTENT_BROWSE
      (2259, X'8D3') Inconsistent browse specification.

      MQRC_INCONSISTENT_UOW
      (2245, X'8C5') Inconsistent unit-of-work specification.

      MQRC_INVALID_MSG_UNDER_CURSOR
      (2246, X'8C6') Message under cursor not valid for retrieval.

      MQRC_LOCAL_UOW_CONFLICT
      (2352, X'930') Global unit of work conflicts with local unit of work.

      MQRC_MATCH_OPTIONS_ERROR
      (2247, X'8C7') Match options not valid.

      MQRC_MD_ERROR
      (2026, X'7EA') Message descriptor not valid.

      MQRC_MSG_ID_ERROR
      (2206, X'89E') Message-identifier error.

      MQRC_MSG_SEQ_NUMBER_ERROR
      (2250, X'8CA') Message sequence number not valid.

      MQRC_MSG_TOKEN_ERROR
      (2331, X'91B') Use of message token not valid.

      MQRC_NO_MSG_AVAILABLE
      (2033, X'7F1') No message available.

      MQRC_NO_MSG_UNDER_CURSOR
      (2034, X'7F2') Browse cursor not positioned on message.

      MQRC_NOT_OPEN_FOR_BROWSE
      (2036, X'7F4') Queue not open for browse.

      MQRC_NOT_OPEN_FOR_INPUT
      (2037, X'7F5') Queue not open for input.

      MQRC_OBJECT_CHANGED
      (2041, X'7F9') Object definition changed since opened.

      MQRC_OBJECT_DAMAGED
      (2101, X'835') Object damaged.

      MQRC_OPTIONS_ERROR
      (2046, X'7FE') Options not valid or not consistent.

      MQRC_PAGESET_ERROR
      (2193, X'891') Error accessing page-set data set.

      MQRC_Q_DELETED
      (2052, X'804') Queue has been deleted.

      MQRC_Q_INDEX_TYPE_ERROR
      (2394, X'95A') Queue has wrong index type.

      MQRC_Q_MGR_NAME_ERROR
      (2058, X'80A') Queue manager name not valid or not known.

      MQRC_Q_MGR_NOT_AVAILABLE
      (2059, X'80B') Queue manager not available for connection.

      MQRC_Q_MGR_QUIESCING
      (2161, X'871') Queue manager quiescing.

      MQRC_Q_MGR_STOPPING
      (2162, X'872') Queue manager shutting down.

      MQRC_RESOURCE_PROBLEM
      (2102, X'836') Insufficient system resources available.

      MQRC_SECOND_MARK_NOT_ALLOWED
      (2062, X'80E') A message is already marked.

      MQRC_SIGNAL_OUTSTANDING
      (2069, X'815') Signal outstanding for this handle.

      MQRC_SIGNAL1_ERROR
      (2099, X'833') Signal field not valid.

      MQRC_STORAGE_MEDIUM_FULL
      (2192, X'890') External storage medium is full.

      MQRC_STORAGE_NOT_AVAILABLE
      (2071, X'817') Insufficient storage available.

      MQRC_SUPPRESSED_BY_EXIT
      (2109, X'83D') Call suppressed by exit program.

      MQRC_SYNCPOINT_LIMIT_REACHED
      (2024, X'7E8') No more messages can be handled within current unit of work.

      MQRC_SYNCPOINT_NOT_AVAILABLE
      (2072, X'818') sync point support not available.

      MQRC_UNEXPECTED_ERROR
      (2195, X'893') Unexpected error occurred.

      MQRC_UOW_ENLISTMENT_ERROR
      (2354, X'932') Enlistment in global unit of work failed.

      MQRC_UOW_MIX_NOT_SUPPORTED
      (2355, X'933') Mixture of unit-of-work calls not supported.

      MQRC_UOW_NOT_AVAILABLE
      (2255, X'8CF') Unit of work not available for the queue manager to use.

      MQRC_WAIT_INTERVAL_ERROR
      (2090, X'82A') Wait interval in MQGMO not valid.

      MQRC_WRONG_GMO_VERSION
      (2256, X'8D0') Wrong version of MQGMO supplied.

      MQRC_WRONG_MD_VERSION
      (2257, X'8D1') Wrong version of MQMD supplied.

    For detailed information about these codes, see Reason codes.


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 sync point.

    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. For applications issuing an MQGET call, the message retrieved can be lost if the application terminates abnormally or the connection is severed while processing the call. This issue arises because the surrogate running on the same platform as the queue manager that issues the MQGET call on behalf of the application cannot detect the loss of the application until the surrogate is about to return the message to the application, after the message has been removed from the queue. This issue 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. For more information about sync points, see Syncpoint considerations in IBM MQ applications.

    This situation can arise with IBM MQ clients as well as with applications that are running on the same platform as the queue manager.

  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 issue occurs, the application must wait a short while and then try the operation again.

  5. If an application puts a sequence of messages on the same queue without using message groups, the order of those messages is preserved if 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, if:

    • 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 might 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 if the receiving application specifies the MQGMO_LOGICAL_ORDER option on the MQGET call. For more information about message groups, see:

    If the user is getting messages in a group under sync point, they must ensure that the complete group is processed before attempting to finish the transaction.

  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 about message context, see Message context.

  8. If we 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 following format names are formats that are converted by the queue manager; these formats 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 IBM MQ.

      See 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 IBM 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 UTF-16 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 this reason code is true for conversions performed by a user-written exit only if the exit conforms to the processing guidelines described in Data conversion.

  9. When using the object-oriented interface to get messages, we can choose not to specify a buffer to hold the message data for an MQGET call. However, in versions of IBM MQ, prior to IBM WebSphere MQ Version 7.0, it was possible for MQGET to fail with reason code MQRC_CONVERTED_MSG_TO_BIG, even when a buffer was not specified. From IBM WebSphere MQ Version 7.0, when you get a message using an object-oriented application without restricting the size of the receive message buffer, the application does not fail with MQRC_CONVERTED_MSG_TOO_BIG, and receives the converted message. This is true of the following environments:

    • .NET, including fully managed applications
    • C++
    • Java ( IBM MQ classes for Java )

    Note: For all clients, if the value of sharingConversations is zero, the channel operates as it did before IBM WebSphere MQ Version 7.0, and message handling reverts to Version 6 behavior. In this situation, if the buffer is too small to receive the converted message, the unconverted message is returned, with reason code MQRC_CONVERTED_MSG_TOO_BIG. For more information about sharingConversations, see Use sharing conversations in a client application.

  10. For the built-in formats, 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 statements 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, if 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.

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

  12. Not all MQGET options are supported when read ahead is enabled. The following table indicated which options are allowed and whether they can be altered between MQGET calls.

      Permitted when read ahead is enabled and can be altered between MQGET calls Permitted when read ahead is enabled but cannot be altered between MQGET calls a MQGET options that are not permitted when read ahead is enabled b
    MQGET MD values MsgId c
    CorrelId c
    		 Encoding
    CodedCharSetId
    MQGET MQGMO options MQGMO_WAIT
    MQGMO_NO_WAIT
    MQGMO_FAIL_IF_QUIESCING
    MQGMO_BROWSE_FIRST d
    MQGMO_BROWSE_NEXT d
    MQGMO_BROWSE_MESSAGE
    _UNDER_CURSOR d

    		 MQGMO_SYNCPOINT_IF_PERSISTENT
    MQGMO_NO_SYNCPOINT
    MQGMO_ACCEPT_TRUNCATED_MSG
    MQGMO_CONVERT
    MQGMO_LOGICAL_ORDER
    MQGMO_COMPLETE_MSG
    MQGMO_ALL_MSGS_AVAILABLE
    MQGMO_ALL_SEGMENTS_AVAILABLE
    MQGMO_MARK_BROWSE_HANDLE
    MQGMO_MARK_BROWSE_CO_OP
    MQGMO_UNMARK_BROWSE_CO_OP
    MQGMO_UNMARK_BROWSE_HANDLE
    MQGMO_UNMARKED_BROWSE_MSG
    MQGMO_PROPERTIES_FORCE_MQRFH2
    MQGMO_NO_PROPERTIES
    MQGMO_PROPERTIES_IN_HANDLE
    MQGMO_PROPERTIES_COMPATIBILITY

    		 MQGMO_SET_SIGNAL
    MQGMO_SYNCPOINT
    MQGMO_MARK_SKIP
    _BACKOUT
    MQGMO_MSG_UNDER
    _CURSOR d
    MQGMO_LOCK
    MQGMO_UNLOCK
    MQGMO values   MsgHandle  
    1. If these options are altered between MQGET calls an MQRC_OPTIONS_CHANGED reason code is returned.
    2. If these options are specified on the first MQGET call then read ahead is disabled. If these options are specified on a subsequent MQGET call a reason code MQRC_OPTIONS_ERROR is returned.
    3. The client applications need to be aware that if the MsgId and CorrelId values are altered between MQGET calls messages with the previous values might have already been sent to the client and remain in the client read ahead buffer until consumed (or automatically purged).
    4. The first MQGET call determines whether messages are to be browsed or got from a queue when read ahead is enabled. If the application attempts to use a combination of browse and get an MQRC_OPTIONS_CHANGED reason code is returned.
    5. MQGMO_MSG_UNDER_CURSOR is not possible with read ahead. Messages can be browsed or got when read ahead is enabled but not a combination of both.

  13. Applications can destructively get uncommitted messages only if those messages are put in the same local unit of work as the get. Applications cannot get uncommitted messages nondestructively.
  14. Messages under a browse cursor can be retrieved in a unit of work. It is not possible to retrieve an uncommitted message in this way.


C invocation

MQGET (Hconn, Hobj, &MsgDesc, &GetMsgOpts, BufferLength, Buffer,
      &DataLength, &CompCode, &Reason);
Declare the parameters as follows: 
MQHCONN  Hconn;         /* Connection handle */
MQHOBJ   Hobj;          /* Object handle */
MQMD     MsgDesc;       /* Message descriptor */
MQGMO    GetMsgOpts;    /* Options that control the action of MQGET */
MQLONG   BufferLength;  /* Length in bytes of the Buffer area */
MQBYTE   Buffer[n];     /* Area to contain the message data */
MQLONG   DataLength;    /* Length of the message */
MQLONG   CompCode;      /* Completion code */
MQLONG   Reason;        /* Reason code qualifying CompCode */


COBOL invocation

CALL 'MQGET' USING HCONN, HOBJ, MSGDESC, GETMSGOPTS, BUFFERLENGTH,
BUFFER, DATALENGTH, COMPCODE, REASON.
Declare the parameters as follows: 
**   Connection handle
 01  HCONN         PIC S9(9) BINARY.
**   Object handle
 01  HOBJ          PIC S9(9) BINARY.
**   Message descriptor
 01  MSGDESC.
     COPY CMQMDV.
**   Options that control the action of MQGET
 01  GETMSGOPTS.
     COPY CMQGMOV.
**   Length in bytes of the BUFFER area
 01  BUFFERLENGTH  PIC S9(9) BINARY.
**   Area to contain the message data
 01  BUFFER        PIC X(n).
**   Length of the message
 01  DATALENGTH    PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE      PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON        PIC S9(9) BINARY.


PL/I invocation

call MQGET (Hconn, Hobj, MsgDesc, GetMsgOpts, BufferLength, Buffer,
           DataLength, CompCode, Reason);
Declare the parameters as follows: 
dcl Hconn         fixed bin(31);  /* Connection handle */
dcl Hobj          fixed bin(31);  /* Object handle */
dcl MsgDesc       like MQMD;      /* Message descriptor */
dcl GetMsgOpts    like MQGMO;     /* Options that control the action of
                                     MQGET */
dcl BufferLength  fixed bin(31);  /* Length in bytes of the Buffer
                                     area */
dcl Buffer        char(n);        /* Area to contain the message data */
dcl DataLength    fixed bin(31);  /* Length of the message */
dcl CompCode      fixed bin(31);  /* Completion code */
dcl Reason        fixed bin(31);  /* Reason code qualifying CompCode */


High Level Assembler invocation

         CALL MQGET,(HCONN,HOBJ,MSGDESC,GETMSGOPTS,BUFFERLENGTH,       
               BUFFER,DATALENGTH,COMPCODE,REASON)
Declare the parameters as follows: 
HCONN         DS       F      Connection handle
HOBJ          DS       F      Object handle
MSGDESC       CMQMDA ,      Message descriptor
GETMSGOPTS    CMQGMOA,      Options that control the action of MQGET
BUFFERLENGTH  DS       F      Length in bytes of the BUFFER area
BUFFER        DS       CL(n)  Area to contain the message data
DATALENGTH    DS       F      Length of the message
COMPCODE      DS       F      Completion code
REASON        DS       F      Reason code qualifying COMPCODE


Visual Basic invocation

MQGET Hconn, Hobj, MsgDesc, GetMsgOpts, BufferLength, Buffer,
DataLength, CompCode, Reason
Declare the parameters as follows: 
Dim Hconn        As Long   'Connection handle'
Dim Hobj         As Long   'Object handle'
Dim MsgDesc      As MQMD   'Message descriptor'
Dim GetMsgOpts   As MQGMO  'Options that control the action of MQGET'
Dim BufferLength As Long   'Length in bytes of the Buffer area'
Dim Buffer       As String 'Area to contain the message data'
Dim DataLength   As Long   'Length of the message'
Dim CompCode     As Long   'Completion code'
Dim Reason       As Long   'Reason code qualifying CompCode'
Parent topic: Function calls