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
- 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.
- 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.
- 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.
- 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'
- Example code for using the mqExecute call
Two code examples showing how to use mqExecute to create a local queue and to inquire about queue attributes.
Parent topic: MQAI calls