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, and on IBM® i for applications running in compatibility mode, the MQCONN call can be omitted, and the following value specified forHconn
:- 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 theGetMsgOpts
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 (you 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 theMaxMsgLength
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 WebSphere® 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 intoBuffer
; this happens whether MQGMO_ACCEPT_TRUNCATED_MSG is specified on theGetMsgOpts
parameter (see MQGMO - Options field for more information).The character set and encoding of the data in
Buffer
are given by theCodedCharSetId
andEncoding
fields returned in theMsgDesc
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 theCodedCharSetId
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
, onlyBufferLength
bytes are returned in theBuffer
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 theGetMsgOpts
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 inBuffer
, the value returned forDataLength
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.
- The length of the unconverted data, for queue-manager 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 theReason
parameter. As a result, values other than those values documented are possible.IfCompCode
is MQCC_OK:- MQRC_NONE
- (0, X'000') No reason to report.
IfCompCode
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).
IfCompCode
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_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
- 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.
- 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
, andDataLength
parameters are not checked or altered. - 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 WebSphere MQ applications.
This situation can arise with IBM WebSphere MQ clients as well as with applications that are running on the same platform as the queue-manager.
- 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.
- 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
orCorrelId
.
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.
- Only one receiver is getting messages from the queue.
- Applications must test for the feedback code MQFB_QUIT in the
Feedback
field of theMsgDesc
parameter, and end if they find this value. See MQMD - Feedback field for more information. - 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 handleHobj
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 about message context, see Message context.
- 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 theBuffer
parameter:- The
Format
field in the control information in the message identifies the structure of the application data, and theCodedCharSetId
andEncoding
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
andEncoding
fields in theMsgDesc
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 theFormat
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 theBuffer
parameter (assuming no other errors), but the call completes with completion code MQCC_WARNING and reason code MQRC_FORMAT_ERROR.You 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 WebSphere MQ.
See Data-conversion exit 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 WebSphere 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
CodedCharSetId
andEncoding
fields in theMsgDesc
parameter to find out:- MQRC_TRUNCATED_MSG_ACCEPTED
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 exit. - The
- When using the object-oriented interface to get messages, you
can choose not to specify a buffer to hold the message data for an
MQGET call. However, in previous versions of WebSphere MQ, it was possible for MQGET
to fail with reason code MQRC_CONVERTED_MSG_TO_BIG, even when a buffer
was not specified. In WebSphere MQ Version 7, 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 ( WebSphere MQ classes for Java)
Note: For all clients, if the value ofsharingConversations
is zero, the channel operates as it did before 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 aboutsharingConversations
, see Using sharing conversations in a client application. - 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 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.
- Default conversion of the application message data occurs only
when all the following are true:
- For the Visual Basic programming language, the following points
apply:
- If the size of the
Buffer
parameter is less than the length specified by theBufferLength
parameter, the call fails with reason code MQRC_STORAGE_NOT_AVAILABLE. - The
Buffer
parameter is declared as being of typeString
. If the data to be retrieved from the queue is not of typeString
, 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 typeAny
, allowing any type of data to be retrieved. However, this means thatBuffer
cannot be checked to ensure that it is at leastBufferLength
bytes in size.
- If the size of the
- 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.
Table 1. MQGET options permitted when read ahead is enabled 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 callsa MQGET options that are not permitted when read ahead is enabledb MQGET MD values MsgIdc
CorrelIdcEncoding
CodedCharSetIdMQGET MQGMO options MQGMO_WAIT
MQGMO_NO_WAIT
MQGMO_FAIL_IF_QUIESCING
MQGMO_BROWSE_FIRSTd
MQGMO_BROWSE_NEXTd
MQGMO_BROWSE_MESSAGE
_UNDER_CURSORd
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
_CURSORd
MQGMO_LOCK
MQGMO_UNLOCK
MQGMO values MsgHandle - If these options are altered between MQGET calls an MQRC_OPTIONS_CHANGED reason code is returned.
- 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.
- 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).
- 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.
- 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.
- 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.
- 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);
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.
** 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);
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)
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
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'