mqExecute

The mqExecute call sends an administration command message and waits for the reply (if expected).


Syntax for mqExecute

    mqExecute (Hconn, Command, OptionsBag, AdminBag, ResponseBag, AdminQ, ResponseQ, CompCode, Reason)


Parameters for mqExecute

    Hconn (MQHCONN) - input
    MQI Connection handle.

    This is returned by a preceding MQCONN call issued by the application.

    Command (MQLONG) - input
    The command to be executed.

    This should be one of the MQCMD_* values. If it is a value that is not recognized by the MQAI servicing the mqExecute call, the value is still accepted. However, if mqAddInquiry was used to insert values in the bag, the Command parameter must be an INQUIRE command recognized by the MQAI; MQRC_INQUIRY_COMMAND_ERROR results if it is not.

    OptionsBag (MQHBAG) - input
    Handle of a bag containing options that affect the operation of the call. This must be the handle returned by a preceding mqCreateBag call or the following special value:

      MQHB_NONE
      No options bag; all options assume their default values.

      Only the options listed in this topic can be present in the options bag (MQRC_OPTIONS_ERROR results if other data items are present).

      The appropriate default value is used for each option that is not present in the bag. The following option can be specified:

      MQIACF_WAIT_INTERVAL
      This data item specifies the maximum time in milliseconds that the MQAI should wait for each reply message. The time interval must be zero or greater, or the special value MQWI_UNLIMITED; the default is thirty seconds. The mqExecute call completes either when all of the reply messages are received or when the specified wait interval expires without the expected reply message having been received. Note: The time interval is an approximate quantity.

      If the MQIACF_WAIT_INTERVAL data item has the wrong data type, or there is more than one occurrence of that selector in the options bag, or the value of the data item is not valid, MQRC_WAIT_INTERVAL_ERROR results.

    AdminBag (MQHBAG) - input
    Handle of the bag containing details of the administration command to be issued.

    All user items placed in the bag are inserted into the administration message that is sent. It is the application's responsibility to ensure that only valid parameters for the command are placed in the bag.

    If the value of the MQIASY_TYPE data item in the command bag is not MQCFT_COMMAND, MQRC_COMMAND_TYPE_ERROR results. If the bag contains nested system bags, MQRC_NESTED_BAG_NOT_SUPPORTED results.

    ResponseBag (MQHBAG) - input
    Handle of the bag where reply messages are placed.

    The MQAI performs an mqClearBag call on the bag before placing reply messages in the bag. To retrieve the reply messages, the selector, MQIACF_CONVERT_RESPONSE, can be specified.

    Each reply message is placed into a separate system bag, with a handle that is then placed in the response bag. Use the mqInquireBag call with selector MQHA_BAG_HANDLE to determine the handles of the system bags within the reply bag, and those bags can then be inquired to determine their contents.

    If some but not all of the expected reply messages are received, MQCC_WARNING with MQRC_NO_MSG_AVAILABLE results. If none of the expected reply messages is received, MQCC_FAILED with MQRC_NO_MSG_AVAILABLE results.

    Group bags cannot be used as response bags.

    AdminQ (MQHOBJ) - input
    Object handle of the queue on which the administration message is to be placed.

    This handle was returned by a preceding MQOPEN call issued by the application. The queue must be open for output.

    The following special value can be specified:

      MQHO_NONE
      This indicates that the administration message should be placed on the SYSTEM.ADMIN.COMMAND.QUEUE belonging to the currently connected queue manager. If MQHO_NONE is specified, the application need not use MQOPEN to open the queue.

    ResponseQ
    Object handle of the queue on which reply messages are placed.

    This handle was returned by a preceding MQOPEN call issued by the application. The queue must be open for input and for inquiry.

    The following special value can be specified:

      MQHO_NONE
      This indicates that the reply messages should be placed on a dynamic queue created automatically by the MQAI. The queue is created by opening SYSTEM.DEFAULT.MODEL.QUEUE, that must therefore have suitable characteristics. The queue created exists for the duration of the call only, and is deleted by the MQAI on exit from the mqExecute call.

    CompCode
    Completion code.

    Reason
    Reason code qualifying CompCode. The following reason codes indicating error conditions can be returned from the mqExecute call:

      MQRC_*
      Anything from the MQINQ, MQPUT, MQGET, or MQOPEN calls.

      MQRC_BAG_WRONG_TYPE
      Input data bag is a group bag.

      MQRC_CMD_SERVER_NOT_AVAILABLE
      The command server that processes administration commands is not available.

      MQRC_COMMAND_TYPE_ERROR
      The value of the MQIASY_TYPE data item in the request bag is not MQCFT_COMMAND.

      MQRC_HBAG_ERROR
      Bag handle not valid.

      MQRC_INQUIRY_COMMAND_ERROR
      mqAddInteger call used with a command code that is not a recognized INQUIRE command.

      MQRC_NESTED_BAG_NOT_SUPPORTED
      Input data bag contains one or more nested system bags.

      MQRC_NO_MSG_AVAILABLE
      Some reply messages received, but not all. Reply bag contains system-generated bags for messages that were received.

      MQRC_NO_MSG_AVAILABLE
      No reply messages received during the specified wait interval.

      MQRC_OPTIONS_ERROR
      Options bag contains unsupported data items, or a supported option has a value which is not valid.

      MQRC_PARAMETER_MISSING
      Administration message requires a parameter which is not present in the bag. This reason code occurs for bags created with the MQCBO_ADMIN_BAG or MQCBO_REORDER_AS_REQUIRED options only.

      MQRC_SELECTOR_NOT_UNIQUE
      Two or more instances of a selector exist within the bag for a mandatory parameter that permits one instance only.

      MQRC_SELECTOR_WRONG_TYPE
      mqAddString or mqSetString was used to add the MQIACF_INQUIRY selector to the bag.

      MQRC_STORAGE_NOT_AVAILABLE
      Insufficient storage available.

      MQRCCF_COMMAND_FAILED
      Command failed; details of failure are contained in system-generated bags within the reply bag.


Usage notes for mqExecute

  1. If no AdminQ is specified, the MQAI checks to see if the command server is active before sending the administration command message. However, if the command server is not active, the MQAI does not start it. If we are sending many administration command messages, we are recommended to open the SYSTEM.ADMIN.COMMAND.QUEUE yourself and pass the handle of the administration queue on each administration request.
  2. Specify the MQHO_NONE value in the ResponseQ parameter simplifies the use of the mqExecute call, but if mqExecute is issued repeatedly by the application (for example, from within a loop), the response queue will be created and deleted repeatedly. In this situation, it is better for the application itself to open the response queue before any mqExecute call, and close it after all mqExecute calls have been issued.
  3. If the administration command results in a message being sent with a message type of MQMT_REQUEST, the call waits for the time given by the MQIACF_WAIT_INTERVAL data item in the options bag.
  4. If an error occurs during the processing of the call, the response bag might contain some data from the reply message, but the data will typically be incomplete.


C language invocation for mqExecute

mqExecute (Hconn, Command, OptionsBag, AdminBag, ResponseBag,
AdminQ, ResponseQ, CompCode, Reason);
Declare the parameters as follows: 
MQHCONN  Hconn;         /* MQI connection handle */
MQLONG   Command;       /* Command to be executed */
MQHBAG   OptionsBag;    /* Handle of a bag containing options */
MQHBAG   AdminBag;      /* Handle of administration bag containing
                        /* details of administration command */
MQHBAG   ResponseBag;   /* Handle of bag for response messages */
MQHOBJ   AdminQ         /* Handle of administration queue for
                           administration messages */
MQHOBJ   ResponseQ;     /* Handle of response queue for response
                           messages */
MQLONG   pCompCode;     /* Completion code */
MQLONG   pReason;       /* Reason code qualifying CompCode */


Visual Basic invocation for mqExecute

(Supported on Windows only.) 

mqExecute (Hconn, Command, OptionsBag, AdminBag, ResponseBag,
AdminQ, ResponseQ, CompCode, Reason);
Declare the parameters as follows: 
Dim HConn       As Long 'MQI connection handle'
Dim Command     As Long 'Command to be executed'
Dim OptionsBag  As Long 'Handle of a bag containing options'
Dim AdminBag    As Long 'Handle of command bag containing details of
                         administration command'
Dim ResponseBag As Long 'Handle of bag for reply messages'
Dim AdminQ      As Long 'Handle of command queue for
                         administration messages'
Dim ResponseQ   As Long 'Handle of response queue for reply messages'
Dim CompCode    As Long 'Completion code'
Dim Reason      As Long 'Reason code qualifying CompCode'

Parent topic: MQAI calls