MQGET (Get message) on IBM i

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


Syntax

MQGET (HCONN, HOBJ, MSGDSC, GMO, BUFLEN, BUFFER, DATLEN, CMPCOD, REASON)


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 a GMBRWF or GMBRWN option is specified on the GMO parameter (see the GMOPT field described in MQGMO (Get-message options) on IBM i ).
  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 IBM MQ MQI client, it is possible for the message retrieved to be lost if during the processing of the MQGET call the IBM MQ MQI client terminates abnormally or the client connection is severed. This arises because the surrogate that is running on the platform of the queue manager and which issues the MQGET call on the behalf of the client 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 platform of the queue manager, but in this case the window during which a message can be lost is small. However, as with IBM MQ MQI 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 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 the usage notes in the description of the MQPUT call 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 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 are presented to the receiving application in the correct order if 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 test for the feedback code FBQUIT in the MDFB field of the MSGDSC parameter. If this value is found, the application ends. See the MDFB field described in MQMD (Message descriptor) on IBM i 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 about message context, see Message context and Control context information.
  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 must 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 following formats are converted automatically by the queue manager; these formats 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 must not begin with the letters "MQ", as such names might 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 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 RC2111 or RC2115 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:

    • RCNONE

    The following reason code indicates that the message might have been converted successfully; the application must 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 in this example is true for conversions performed by user-written exits only if the exit conforms to the processing guidelines.

  9. For the built-in formats listed previously, the queue manager might 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 might 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 statements 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, if 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 must 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 32 KB.


Parameters

The MQGET call has the following parameters:

    HCONN (10-digit signed integer) - input

    Connection handle.

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

    HOBJ (10-digit signed integer) - input

    Object handle.

    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) on IBM i for details):

    • OOINPS
    • OOINPX
    • OOINPQ
    • OOBRW

    MSGDSC (MQMD) - input/output

    Message descriptor.

    This structure describes the attributes of the message required, and the attributes of the message retrieved. See MQMD (Message descriptor) on IBM i for details.

    If BUFLEN is less than the message length, MSGDSC is still entered by the queue manager, whether GMATM is specified on the GMO parameter (see the GMOPT field described in MQGMO (Get-message options) on IBM i).

    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 of the fields in the MQMDE have default values, the MQMDE is omitted. A format name of FMMDE in the MDFMT field in MQMD indicates that an MQMDE is present.

    GMO (MQGMO) - input/output

    Options that control the action of MQGET.

    See MQGMO (Get-message options) on IBM i for details.

    BUFLEN (10-digit signed integer) - input

    Length in bytes of the BUFFER area.

    Zero can be specified for messages that have no data, or if the message is to be removed from the queue and the data discarded (GMATM must be specified 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 (1-byte bit string x BUFLEN) - output

    Area to contain the message data.

    The buffer must be aligned on a boundary appropriate to the nature of the data in the message. 4-byte alignment must be 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 BUFLEN is less than the message length, as much of the message as possible is moved into BUFFER ; this happens whether GMATM is specified on the GMO parameter (see the GMOPT field described in MQGMO (Get-message options) on IBM i for more information).

    The character set and encoding of the data in BUFFER are given by the MDCSI and MDENC fields returned in the MSGDSC 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 GMCONV option can be used with a user-written exit to perform the conversion of the message data (see MQGMO (Get-message options) on IBM i for details of this option).

    Note: All of 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 ENNAT).

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

    DATLEN (10-digit signed integer) - output

    Length of the message.

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

    If BUFLEN is less than the message length, DATLEN is still entered by the queue manager, whether GMATM is specified on the GMO parameter (see the GMOPT field described in MQGMO (Get-message options) on IBM i 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 GMCONV option is specified, and the converted message data is too long to fit in BUFFER, the value returned for DATLEN 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 DATLEN.

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

    CMPCOD (10-digit signed integer) - output

    Completion code.

    It is one of the following:

      CCOK
      Successful completion.

      CCWARN
      Warning (partial completion).

      CCFAIL
      Call failed.

    REASON (10-digit signed integer) - output

    Reason code qualifying CMPCOD.

    The following reason codes are the ones that the queue manager can return for the REASON parameter. If the application specifies the GMCONV option, and a user-written exit is invoked to convert some or all of the message data, it is the exit that decides what value is returned for the REASON parameter. As a result, values other than the values documented later in this section are possible.

    If CMPCOD is CCOK:

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

    If CMPCOD is CCWARN:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    If CMPCOD is CCFAIL:

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

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

      RC2219
      (2219, X'8AB') MQI call reentered before previous call complete.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      RC2072
      (2072, X'818') Syncpoint support not available.

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

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

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

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

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


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQGET(HCONN : HOBJ : MSGDSC : GMO :
     C                                     BUFLEN : BUFFER : DATLEN :
     C                                     CMPCOD : REASON)
The prototype definition for the call is: 
     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQGET            PR                  EXTPROC('MQGET')
     D* Connection handle
     D HCONN                         10I 0 VALUE
     D* Object handle
     D HOBJ                          10I 0 VALUE
     D* Message descriptor
     D MSGDSC                       364A
     D* Options that control the action of MQGET
     D GMO                          112A
     D* Length in bytes of the Buffer area
     D BUFLEN                        10I 0 VALUE
     D* Area to contain the message data
     D BUFFER                          *   VALUE
     D* Length of the message
     D DATLEN                        10I 0
     D* Completion code
     D CMPCOD                        10I 0
     D* Reason code qualifying CMPCOD
     D REASON                        10I 0
Parent topic: Function calls on IBM i