Sending administration commands to the qm command server using the mqExecute call

When a data bag has been created and populated, an administrative command message can be sent to the command server of a queue manager using the mqExecute call. This handles the exchange with the command server and returns responses in a bag.

After we have created and populated your data bag, we can send an administration command message to the command server of a queue manager. The easiest way to do this is by using the mqExecute call. The mqExecute call sends an administration command message as a nonpersistent message and waits for any responses. Responses are returned in a response bag. These might contain information about attributes relating to several IBM MQ objects or a series of PCF error response messages, for example. Therefore, the response bag could contain a return code only or it could contain nested bags.

Response messages are placed into system bags that are created by the system. For example, for inquiries about the names of objects, a system bag is created to hold those object names and the bag is inserted into the user bag. Handles to these bags are then inserted into the response bag and the nested bag can be accessed by the selector MQHA_BAG_HANDLE. The system bag stays in storage, if it is not deleted, until the response bag is deleted.

The concept of nesting is shown in Figure 1.
Figure 1. Nesting

As input to the mqExecute call, you must supply:

  • An MQI connection handle.
  • The command to be executed. This should be one of the MQCMD_* values. Note: If this value is not recognized by the MQAI, the value is still accepted. However, if the mqAddInquiry call was used to insert values into the bag, this parameter must be an INQUIRE command recognized by the MQAI. That is, the parameter should be of the form MQCMD_INQUIRE_*.
  • Optionally, a handle of the bag containing options that control the processing of the call. This is also where we can specify the maximum time in milliseconds that the MQAI should wait for each reply message.
  • A handle of the administration bag that contains details of the administration command to be issued.
  • A handle of the response bag that receives the reply messages.
The following handles are optional:

  • An object handle of the queue where the administration command is to be placed.

    If no object handle is specified, the administration command is placed on the SYSTEM.ADMIN.COMMAND.QUEUE belonging to the currently connected queue manager. This is the default.

  • An object handle of the queue where reply messages are to be placed.

    We can choose to place the reply messages on a dynamic queue that is created automatically by the MQAI. The queue created exists for the duration of the call only, and is deleted by the MQAI on exit from the mqExecute call.

For examples uses of the mqExecute call, see Example code