- 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. Message deletion does not occur if an GMBRWF or GMBRWN option
is specified on the GMO parameter (see the GMOPT field described in MQGMO - Get-message options).
- If the GMLK 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 GMUNLK
option is specified, a previously-locked message is unlocked. No message is
retrieved in this case, and the MSGDSC, BUFLEN, BUFFER and DATLEN parameters
are not checked or altered.
- If the application issuing the MQGET call is running
as an MQ client, it is possible for the message retrieved to be lost if during
the processing of 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 which 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.
The risk of losing messages in this way can be eliminated by
always retrieving messages within units of work (that is, by specifying the
GMSYP option on the MQGET call, and using the MQCMIT or MQBACK calls to commit or back out the
unit of work when processing of the message is complete). If GMSYP 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 the risk can be eliminated 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 RC2033. If this occurs, the application should
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 the usage notes in the
description of the MQPUT call for details. If the conditions
are satisfied, the messages will be 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 of the MDCID 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 MDMID or MDCID.
If the sending application put the messages as a message group, the
messages will be presented to the receiving application in the correct order
provided that the receiving application specifies the GMLOGO option on the MQGET call. For more information about message groups, see:
- MDMFL field in MQMD
- PMLOGO option in MQPMO
- GMLOGO option in MQGMO
- Applications should test for the feedback code FBQUIT in the MDFB field of the MSGDSC parameter. If this
value is found, the application should end. See the MDFB field
described in MQMD - Message descriptor for more information.
- If the queue identified by HOBJ was opened with the
OOSAVA option, and the completion code from the MQGET call
is CCOK or CCWARN, the context associated with the queue handle HOBJ is set to the context of the message that has been retrieved
(unless the GMBRWF or GMBRWN option is set, in which case the context is marked
as not available). This context can be used on a subsequent MQPUT or MQPUT1 call by specifying the PMPASI or
PMPASA 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 the GMCONV option is included in the GMO 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 MDFMT field in the control information in the
message identifies the structure of the application data, and the MDCSI and MDENC fields in the control information
in the message specify its character-set identifier and encoding.
- The application issuing the MQGET call specifies
in the MDCSI and MDENC fields in the MSGDSC parameter the character-set identifier and encoding to which
the application message data should be converted.
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 MDFMT field in the control
information in the message:
- The format names listed below are formats that are converted automatically
by the queue manager; these are called "built-in" formats:
FMADMN |
FMMDE |
FMCICS |
FMPCF |
FMCMD1 |
FMRMH |
FMCMD2 |
FMRFH |
FMDLH |
FMRFH2 |
FMDH |
FMSTR |
FMEVNT |
FMTM |
FMIMS |
FMXQH |
FMIMVS |
|
- The format name FMNONE 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 GMCONV is specified on the MQGET call for
a message that has a format name of FMNONE, and the character set or encoding
of the message differs from that specified in the MSGDSC parameter,
the message is still returned in the BUFFER parameter
(assuming no other errors), but the call completes with completion code CCWARN
and reason code RC2110.
FMNONE can be used 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 the message data should be sent.
- All other format names cause the message to be passed 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 should not begin
with the letters "MQ", as such names may conflict with
format
names supported in the future.
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 RC2111 or RC2115
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 may have been converted successfully; the application should check the MDCSI and MDENC fields in the MSGDSC parameter to find out:
All other reason codes indicate that the message was not converted.
Note:
The interpretation of the reason code described above
will be true for conversions performed by user-written exits only if the exit conforms to the processing guidelines.
- For the built-in formats listed above, the queue manager may perform default conversion of character strings in the message
when the GMCONV 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 CCOK, instead of completing
with CCWARN and reason code RC2111 or RC2115.
Note:
The result of
using an approximate character set to convert string data is that some characters
may be converted incorrectly. This can be avoided by using in the string only
characters which 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 of the following are true:
- The application specifies GMCONV.
- The message contains data that must be converted either from or to a character
set which 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 GMCONV option is not specified
by the application on the MQGET call.
- The BUFFER parameter shown in the RPG programming
example is declared as a string; this restricts the maximum length of the
parameter to 256 bytes. If a larger buffer is required, the parameter should
be declared instead as a structure, or as a field in a physical file.
Declaring the parameter as a structure increases the maximum length possible
to 9999 bytes, while declaring the parameter as a field in a physical file
increases the maximum length possible to approximately 32K bytes.