Use the command server

The command server is an IBM MQ component that works with the command processor component. We can send formatted messages to the command server which interprets the messages, runs the administration requests, and sends responses back to your administration application.

The command server reads request messages from the system-command input queue, verifies them, and passes the valid ones as commands to the command processor. The command processor processes the commands and puts any replies as reply messages on to the reply-to queue that you specify. The first reply message contains the user message CSQN205I. See Interpreting the reply messages from the command server for more information. The command server also processes channel initiator and queue sharing group commands, wherever they are issued from.

Identifying the queue manager that processes your commands

The queue manager that processes the commands you issue from an administration program is the queue manager that owns the system-command input queue that the message is put onto.

Starting the command server

Normally, the command server is started automatically when the queue manager is started. It becomes available as soon as the message CSQ9022I 'START QMGR' NORMAL COMPLETION is returned from the START QMGR command. The command server is stopped when all the connected tasks have been disconnected during the system termination phase.

We can control the command server yourself using the START CMDSERV and STOP CMDSERV commands. To prevent the command server starting automatically when IBM MQ is restarted, we can add a STOP CMDSERV command to your CSQINP1 or CSQINP2 initialization data sets. However, this is not recommended as it prevents any channel initiator or queue sharing group commands being processed.

The STOP CMDSERV command stops the command server as soon as it has finished processing the current message, or immediately if no messages are being processed.

If the command server has been stopped by a STOP CMDSERV command in the program, no other commands from the program can be processed. To restart the command server, you must issue a START CMDSERV command from the z/OS® console.

If you stop and restart the command server while the queue manager is running, all the messages that are on the system-command input queue when the command server stops are processed when the command server is restarted. However, if you stop and restart the queue manager after the command server is stopped, only the persistent messages on the system-command input queue are processed when the command server is restarted. All nonpersistent messages on the system-command input queue are lost.

Sending commands to the command server

For each command, you build a message containing the command, then put it onto the system-command input queue.

Building a message that includes IBM MQ commands

We can incorporate IBM MQ commands in an application program by building request messages that include the required commands. For each such command you:

1. Create a buffer containing a character string representing the command.
2. Issue an MQPUT call specifying the buffer name in the buffer parameter of the call.

The simplest way to do this in C is to define a buffer using 'char'. For example:

char message_buffer[ ] = "ALTER QLOCAL(SALES) PUT(ENABLED)";

When you build a command, use a null-terminated character string. Do not specify a command prefix string (CPF) at the start of a command defined in this way. This means that we do not have to alter your command scripts if you want to run them on another queue manager. However, you must take into account that a CPF is included in any response messages that are put onto the reply-to queue.

The command server folds all lowercase characters to uppercase unless they are inside quotation marks.

Commands can be any length up to a maximum 32 762 characters.

Putting messages on the system-command input queue

Use the MQPUT call to put request messages containing commands on the system-command input queue. In this call you specify the name of the reply-to queue that we have already opened.

To use the MQPUT call:

1. Set these MQPUT parameters:

   Hconn

   The connection handle returned by the MQCONN or MQCONNX call.

   Hobj

   The object handle returned by the MQOPEN call for the system-command input queue.

   BufferLength

   The length of the formatted command.

   Buffer

   The name of the buffer containing the command.

2. Set these MQMD fields:

   MsgType

   MQMT_REQUEST

   Format

   MQFMT_STRING or MQFMT_NONE

   If you are not using the same code page as the queue manager, set CodedCharSetId as appropriate and set MQFMT_STRING, so that the command server can convert the message. Do not set MQFMT_ADMIN, as that causes your command to be interpreted as PCF.

   ReplyToQ

   Name of your reply-to queue.

   ReplyToQMgr

   If you want replies sent to your local queue manager, leave this field blank. If you want your IBM MQ commands to be sent to a remote queue manager, put its name here. You must also have the correct queues and links set up, as described in Distributed queuing and clusters.

3. Set any other MQMD fields, as required. You should normally use nonpersistent messages for commands.
4. Set any PutMsgOpts options, as required.

   If you specify MQPMO_SYNCPOINT (the default), you must follow the MQPUT call with a syncpoint call.

Use MQPUT1 and the system-command input queue

If you want to put just one message on the system-command input queue, we can use the MQPUT1 call. This call combines the functions of an MQOPEN, followed by an MQPUT of one message, followed by an MQCLOSE, all in one call. If we use this call, modify the parameters accordingly. See Putting one message on a queue using the MQPUT1 call for details.