Command server

Using the command server

The command server is a WebSphere MQ component that works with the command processor component. Thecommand 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 theuser message CSQN205I. See Interpreting the replies 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
• Starting the command server
• Sending commands to the command server
• Putting messages on the system-command input queue

                                                                                       

Using the command server

The command server is a WebSphere MQ component that works with the command processor component. 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 replies for more information.

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.
You can control the command server yourself using the START CMDSERV and STOP CMDSERV commands. To prevent the command server starting automatically when WebSphere MQ is restarted, you can add a STOP CMDSERV command to your CSQINP1 or CSQINP2 initialization data sets.
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 WebSphere MQ commands

You can incorporate WebSphere 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 you 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 single quotes.
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 you 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

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 WebSphere 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 the WebSphere MQ Intercommunication manual.

3.    Set any other MQMD fields, as required. If you are not using the same code page as the queue manager, set CodedCharSetId as appropriate, and set Format to MQFMT_STRING, so that the command server can convert the message. 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.

Using MQPUT1 and the system-command input queue

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