mqGetBag

The mqGetBag call removes a message from the specified queue and converts the message data into a data bag.


Syntax for mqGetBag

    mqGetBag (Hconn, Hobj, MsgDesc, GetMsgOpts, HBag, CompCode, Reason)


Parameters for mqGetBag

    Hconn (MQHCONN) - input
    MQI connection handle.

    Hobj (MQHOBJ) - input
    Object handle of the queue from which the message is to be retrieved. This handle was returned by a preceding MQOPEN call issued by the application. The queue must be open for input.

    MsgDesc (MQMD) - input/output
    Message descriptor (for more information, see MQMD - Message descriptor ).

    If the Format field in the message has a value other than MQFMT_ADMIN, MQFMT_EVENT, or MQFMT_PCF, MQRC_FORMAT_NOT_SUPPORTED results.

    If, on entry to the call, the Encoding field in the application's MQMD has a value other than MQENC_NATIVE and MQGMO_CONVERT is specified, MQRC_ENCODING_NOT_SUPPORTED results. Also, if MQGMO_CONVERT is not specified, the value of the Encoding parameter must be the retrieving application's MQENC_NATIVE; if not, again MQRC_ENCODING_NOT_SUPPORTED results.

    GetMsgOpts (MQGMO) - input/output
    Get-message options (for more information, see MQGMO - Get-message options ).

    MQGMO_ACCEPT_TRUNCATED_MSG cannot be specified; MQRC_OPTIONS_ERROR results if it is. MQGMO_LOCK and MQGMO_UNLOCK are not supported in a 16-bit or 32-bit Window environment. MQGMO_SET_SIGNAL is supported in a 32-bit Window environment only.

    HBag (MQHBAG) - input/output
    Handle of a bag into which the retrieved message is placed. The MQAI performs an mqClearBag call on the bag before placing the message in the bag.

      MQHB_NONE
      Gets the retrieved message. This provides a means of deleting messages from the queue.

      If an option of MQGMO_BROWSE_* is specified, this value sets the browse cursor to the selected message; it is not deleted in this case.

    CompCode (MQLONG) - output
    Completion code.

    Reason (MQLONG) - output
    Reason code qualifying CompCode. The following reason codes indicating warning and error conditions can be returned from the mqGetBag call:

      MQRC_*
      Anything from the MQGET call or bag manipulation.

      MQRC_BAG_CONVERSION_ERROR
      Data could not be converted into a bag.

      This indicates a problem with the format of the data to be converted into a bag (for example, the message is not a valid PCF).

      If the message was retrieved destructively from the queue (that is, not browsing the queue), this reason code indicates that it has been discarded.

      MQRC_BAG_WRONG_TYPE
      Input data bag is a group bag.

      MQRC_ENCODING_NOT_SUPPORTED
      Encoding not supported; the value in the Encoding field of the MQMD must be MQENC_NATIVE.

      MQRC_FORMAT_NOT_SUPPORTED
      Format not supported; the Format name in the message is not MQFMT_ADMIN, MQFMT_EVENT, or MQFMT_PCF. If the message was retrieved destructively from the queue (that is, not browsing the queue), this reason code indicates that it has been discarded.

      MQRC_HBAG_ERROR
      Bag handle not valid.

      MQRC_INCONSISTENT_ITEM_TYPE
      Data type of second occurrence of selector differs from data type of first occurrence.

      MQRC_SELECTOR_OUT_OF_RANGE
      Selector not within valid range for call.

      MQRC_STORAGE_NOT_AVAILABLE
      Insufficient storage available.

      MQRC_SYSTEM_BAG_NOT_ALTERABLE
      System bag cannot be altered or deleted.


Usage notes for mqGetBag

  1. Only messages that have a supported format can be returned by this call. If the message has a format that is not supported, the message is discarded, and the call completes with an appropriate reason code.
  2. If the message is retrieved within a unit of work (that is, with the MQGMO_SYNCPOINT option), and the message has an unsupported format, the unit of work can be backed out, reinstating the message on the queue. This allows the message to be retrieved by using the MQGET call in place of the mqGetBag call.


C language invocation for mqGetBag

mqGetBag (hConn, hObj, &MsgDesc, &GetMsgOpts, hBag, CompCode, Reason);
Declare the parameters as follows: 
MQHCONN  hConn;         /* MQI connection handle */
MQHOBJ   hObj;          /* Object handle */
MQMD     MsgDesc;       /* Message descriptor */
MQGMO    GetMsgOpts;    /* Get-message options */
MQHBAG   hBag;          /* Bag handle */
MQLONG   CompCode;      /* Completion code */
MQLONG   Reason;        /* Reason code qualifying CompCode */


Visual Basic invocation for mqGetBag

(Supported on Windows only.) 

mqGetBag (HConn, HObj, MsgDesc, GetMsgOpts, Bag, CompCode, Reason);
Declare the parameters as follows: 
Dim HConn      As Long 'MQI connection handle'
Dim HObj       As Long 'Object handle'
Dim MsgDesc    As Long 'Message descriptor'
Dim GetMsgOpts As Long 'Get-message options'
Dim Bag        As Long 'Bag handle'
Dim CompCode   As Long 'Completion code'
Dim Reason     As Long 'Reason code qualifying CompCode'
Parent topic: MQAI calls