This section introduces you to MQSC commands and tells you how to use them for some common tasks. If you use WebSphere MQ for Windows, you can also perform the operations described in this section using the WebSphere MQ Explorer. See Chapter 7, "Administration using the WebSphere MQ Explorer" for more information.
You can use MQSC commands to manage queue manager objects, including the queue manager itself, clusters, channels, queues, namelists, process definitions, and authentication information (authinfo) objects. This section deals with queue managers, queues, and process definitions; for information about administering channel objects, see WebSphere MQ Intercommunication. For information about MQSC commands for managing the authinfo object, see WebSphere MQ Script (MQSC) Command Reference.
You issue MQSC commands to a queue manager using the runmqsc command. (For details of this command, see runmqsc (run MQSC commands).) You can do this interactively, issuing commands from a keyboard, or you can redirect the standard input device (stdin) to run a sequence of commands from an ASCII text file. In both cases, the format of the commands is the same. (For information about running the commands from a text file, see Running MQSC commands from text files.)
You can run the runmqsc command in three ways, depending on the flags set on the command:
You can also run the command followed by a question mark to display the syntax.
Object attributes specified in MQSC commands are shown in this book in uppercase (for example, RQMNAME), although they are not case sensitive. MQSC command attribute names are limited to eight characters. MQSC commands are available on other platforms, including OS/400 and z/OS.
MQSC commands are summarized in Appendix E, Comparing command sets.The WebSphere MQ Script (MQSC) Command Reference contains a description of each MQSC command and its syntax.
In examples, we use some long names for objects. This is to help you identify the type of object you are dealing with.
When you issue MQSC commands, you need specify only the local name of the queue. In our examples, we use queue names such as:
ORANGE.LOCAL.QUEUE
The LOCAL.QUEUE part of the name is simply to illustrate that this queue is a local queue. It is not required for the names of local queues in general.
We also use the name saturn.queue.manager as a queue manager name. The queue.manager part of the name is simply to illustrate that this object is a queue manager. It is not required for the names of queue managers in general.
MQSC commands, including their attributes, can be written in uppercase or lowercase. Object names in MQSC commands are folded to uppercase (that is, QUEUE and queue are not differentiated), unless the names are enclosed within single quotation marks. If quotation marks are not used, the object is processed with a name in uppercase. See the WebSphere MQ Script (MQSC) Command Reference for more information.
The runmqsc command invocation, in common with all WebSphere MQ control commands, is case sensitive in some WebSphere MQ environments. See Using control commands for more information.
The standard input device, also referred to as stdin, is the device from which input to the system is taken. Typically this is the keyboard, but you can specify that input is to come from a serial port or a disk file, for example. The standard output device, also referred to as stdout, is the device to which output from the system is sent. Typically this is a display, but you can redirect output to a serial port or a file.
On operating-system commands and WebSphere MQ control commands, the < operator redirects input. If this operator is followed by a file name, input is taken from the file. Similarly, the > operator redirects output; if this operator is followed by a file name, output is directed to that file.
To use MQSC commands interactively, open a command window or shell and enter:
runmqsc
In this command, a queue manager name has not been specified, so the MQSC commands are processed by the default queue manager. If you want to use a different queue manager, specify the queue manager name on the runmqsc command. For example, to run MQSC commands on queue manager jupiter.queue.manager, use the command:
runmqsc jupiter.queue.manager
After this, all the MQSC commands you type in are processed by this queue manager, assuming that it is on the same node and is already running.
Now you can type in any MQSC commands, as required. For example, try this one:
DEFINE QLOCAL (ORANGE.LOCAL.QUEUE)
For commands that have too many parameters to fit on one line, use continuation characters to indicate that a command is continued on the following line:
Command input terminates with the final character of a nonblank line that is not a continuation character. You can also terminate command input explicitly by entering a semicolon (;). (This is especially useful if you accidentally enter a continuation character at the end of the final line of command input.)
When you issue MQSC commands, the queue manager returns operator messages that confirm your actions or tell you about the errors you have made. For example:
AMQ8006: WebSphere MQ queue created.
This message confirms that a queue has been created.
AMQ8405: Syntax error detected at or near end of command segment below:-
AMQ8426: Valid MQSC commands are:
ALTER
CLEAR
DEFINE
DELETE
DISPLAY
END
PING
RESET
REFRESH
RESOLVE
RESUME
START
STOP
SUSPEND
4 : end
This message indicates that you have made a syntax error.
These messages are sent to the standard output device. If you have not entered the command correctly, refer to the WebSphere MQ Script (MQSC) Command Reference for the correct syntax.
To stop working with MQSC commands, enter the END command.
Alternatively, you can use the EOF character for your operating system.
Running MQSC commands interactively is suitable for quick tests, but if you have very long commands, or are using a particular sequence of commands repeatedly, consider redirecting stdin from a text file. (See Standard input and output for information about stdin and stdout.) To do this, first create a text file containing the MQSC commands using your usual text editor. When you use the runmqsc command, use the redirection operators. For example, the following command runs a sequence of commands contained in the text file myprog.in:
runmqsc < myprog.in
Similarly, you can also redirect the output to a file. A file containing the MQSC commands for input is called an MQSC command file. The output file containing replies from the queue manager is called the output file.
To redirect both stdin and stdout on the runmqsc command, use this form of the command:
runmqsc < myprog.in > myprog.out
This command invokes the MQSC commands contained in the MQSC command file myprog.in. Because we have not specified a queue manager name, the MQSC commands run against the default queue manager. The output is sent to the text file myprog.out. Figure 2 shows an extract from the MQSC command file myprog.in and Figure 3 shows the corresponding extract of the output in myprog.out.
To redirect stdin and stdout on the runmqsc command, for a queue manager (saturn.queue.manager) that is not the default, use this form of the command:
runmqsc saturn.queue.manager < myprog.in > myprog.out
MQSC commands are written in human-readable form, that is, in ASCII text. Figure 2 is an extract from an MQSC command file showing an MQSC command (DEFINE QLOCAL) with its attributes. The WebSphere MQ Script (MQSC) Command Reference contains a description of each MQSC command and its syntax.
Figure 2. Extract from an MQSC command file
.
.
.
DEFINE QLOCAL(ORANGE.LOCAL.QUEUE) REPLACE +
DESCR(' ') +
PUT(ENABLED) +
DEFPRTY(0) +
DEFPSIST(NO) +
GET(ENABLED) +
MAXDEPTH(5000) +
MAXMSGL(1024) +
DEFSOPT(SHARED) +
NOHARDENBO +
USAGE(NORMAL) +
NOTRIGGER;
.
.
.
|
For portability among WebSphere MQ environments, we recommend that you limit the line length in MQSC command files to 72 characters. The plus sign indicates that the command is continued on the next line.
The runmqsc command returns a report, which is sent to stdout. The report contains:
Starting WebSphere MQ Commands.
AMQ8006: WebSphere MQ queue created.
| Note: | The queue manager attempts to process only those commands that have no syntax errors. |
Figure 3. Extract from an MQSC command report file
Starting WebSphere MQ Commands.
.
.
12: DEFINE QLOCAL('ORANGE.LOCAL.QUEUE') REPLACE +
: DESCR(' ') +
: PUT(ENABLED) +
: DEFPRTY(0) +
: DEFPSIST(NO) +
: GET(ENABLED) +
: MAXDEPTH(5000) +
: MAXMSGL(1024) +
: DEFSOPT(SHARED) +
: NOHARDENBO +
: USAGE(NORMAL) +
: NOTRIGGER;
AMQ8006: WebSphere MQ queue created.
:
.
.
|
These MQSC command files are supplied with WebSphere MQ:
In WebSphere MQ for Windows, these files are located in the directory c:\Program Files\IBM\WebSphere MQ\tools\mqsc\samples.
On UNIX systems these files are located in the directory opt/mqm/samp (usr/mqm/samp on AIX).
The command that runs them is:
runmqsc <amqscos0.tst>test.out
You can use the runmqsc command to verify MQSC commands on a local queue manager without actually running them. To do this, set the -v flag in the runmqsc command, for example:
runmqsc -v < myprog.in > myprog.out
When you invoke runmqsc against an MQSC command file, the queue manager verifies each command and returns a report without actually running the MQSC commands. This allows you to check the syntax of the commands in your command file. This is particularly important if you are:
The returned report is similar to that shown in Figure 3.
You cannot use this method to verify MQSC commands remotely. For example, if you attempt this command:
runmqsc -w 30 -v jupiter.queue.manager < myprog.in > myprog.out
the -w flag, which you use to indicate that the queue manager is remote, is ignored, and the command is run locally in verification mode. 30 is the number of seconds that WebSphere MQ waits for replies from the remote queue manager.
If you have very long commands, or are using a particular sequence of commands repeatedly, consider redirecting stdin from a batch file. To do this, first create a batch file containing the MQSC commands using your usual text editor. When you use the runmqsc command, use the redirection operators. The following example:
Figure 4. Example script for running MQSC commands from a batch file
export MYTEMPQM=TESTQM
export MYPORT=1600
export MQCHLLIB=/var/mqm/qmgrs/$MQTEMPQM/@ipcc
crtmqm $MYTEMPQM
strmqm $MYTEMPQM
runmqlsr -m $MYTEMPQM -t TCP -p $MYPORT &
runmqsc $MYTEMPQM << EOF
DEFINE CHANNEL(NTLM) CHLTYPE(SVRCONN) TRPTYPE(TCP) SCYEXIT('amqrspin(SCY_NTLM)')
DEFINE CHANNEL(NTLM) CHLTYPE(CLNTCONN) QMNAME('$MYTEMPQM') CONNAME('127.0.0.1($MYPORT)')
ALTER CHANNEL(NTLM) CHLTYPE(CLNTCONN) SCYEXIT('amqrspin(SCY_NTLM)')
DEFINE QLOCAL(TESTQ)
EOF
amqsputc TESTQ $MYTEMPQM << EOF
hello world
EOF
endmqm -i $MYTEMPQM
|
If you cannot get MQSC commands to run, use the following information to see if any of these common problems apply to you. It is not always obvious what the problem is when you read the error generated.
When you use the runmqsc command, remember the following:
AMQ8118: WebSphere MQ queue manager does not exist.
To do this on Windows systems, use the WebSphere MQ Explorer to display a list of queue managers. On UNIX systems, look in the WebSphere MQ configuration file, mqs.ini. This file contains the names of the queue managers and the name of the default queue manager, if you have one.
AMQ8146: WebSphere MQ queue manager not available.
runmqsc DEFINE QLOCAL(FRED)
runmqsc
.
.
Starting WebSphere MQ Commands.
1 : strmqm saturn.queue.manager
AMQ8405: Syntax error detected at or near end of cmd segment below:-s
AMQ8426: Valid MQSC commands are:
ALTER
CLEAR
DEFINE
DELETE
DISPLAY
END
PING
REFRESH
RESET
RESOLVE
RESUME
START
STOP
SUSPEND
2 : end