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