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

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

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

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 RC2033. If this occurs, the application should 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 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

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

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

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

   • RCNONE

   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:

   • RC2079

   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.

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

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