Performing local administration tasks using MQSC commands

 

You can use MQSC commands to manage queue manager objects, including

  1. Queue managers
  2. clusters
  3. channels
  4. queues
  5. namelists
  6. process definitions
  7. authentication information objects

This page deals with queue managers, queues, and process definitions.

One issues MQSC commands to a queue manager using the runmqsc command. 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.

You can run the runmqsc command in three ways, depending on the flags set on the command:

  • Verify a command without running it
  • Run a command on a local queue manager
  • Run a command on a remote queue manager

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.

 

WebSphere MQ object names

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.

 

Case-sensitivity in MQSC commands

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.

The runmqsc command invocation, in common with all Using WebSphere MQ control commands, is case sensitive in some WebSphere MQ environments.

 

Standard input and output

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.

 

Using MQSC commands interactively

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 chicago.queue.manager, use the command: 

runmqsc chicago.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:

  • A minus sign (-) indicates that the command is to be continued from the start of the following line.

  • A plus sign (+) indicates that the command is to be continued from the first nonblank character 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.)

 

Feedback from MQSC commands

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.

 

Ending interactive input of MQSC commands

To stop working with MQSC commands, enter the END command.

Alternatively, you can use the EOF character for your operating system.

 

Running MQSC commands from text files

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. 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.

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 command files

MQSC commands are written in human-readable form, that is, in ASCII text. 

 .
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.

 

MQSC command reports

The runmqsc command returns a report, which is sent to stdout. The report contains:

  • A header identifying MQSC commands as the source of the report:

    Starting WebSphere MQ Commands.

  • An optional numbered listing of the MQSC commands issued. By default, the text of the input is echoed to the output. Within this output, each command is prefixed by a sequence number. Use the -e flag on the runmqsc command to suppress the output.

  • A syntax error message for any commands found to be in error.

  • An operator message indicating the outcome of running each command. For example, the operator message for the successful completion of a DEFINE QLOCAL command is:

    AMQ8006: WebSphere MQ queue created.

  • Other messages resulting from general errors when running the script file.

  • A brief statistical summary of the report indicating the number of commands read, the number of commands with syntax errors, and the number of commands that could not be processed.

The queue manager attempts to process only those commands that have no syntax errors. 

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.
       :

 

Running the supplied MQSC command files

These MQSC command files are supplied with WebSphere MQ:

amqscos0.tst
Definitions of objects used by sample programs.

amqscic0.tst
Definitions of queues for CICS transactions.

These files are located in: /opt/mqm/samp

The command that runs them is:

runmqsc <amqscos0.tst>test.out

 

Using runmqsc to verify commands

To verify MQSC commands on a local queue manager without actually running them, set the -v flag:

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:

  • Running a large number of commands from a command file.
  • Using an MQSC command file many times over.

You cannot use this method to verify MQSC commands remotely. For example, if you attempt this command...

runmqsc -w 30 -v chicago.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.

 

Running MQSC commands from scripts

If you have very long commands, or are using a particular sequence of commands repeatedly, consider redirecting stdin from a script. To do this, first create a script containing the MQSC commands using your usual text editor. When you use the runmqsc command, use the redirection operators. The following example:

  1. Creates a test queue manager, TESTQM
  2. Creates a matching CLNTCONN and listener set to use TCP/IP port 1600
  3. Creates a test queue, TESTQ
  4. Puts a message on the queue, using the amqsputc sample program

Here is an example script: 

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

 

Resolving problems with MQSC commands

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:

  • Use the < operator to redirect input from a file. If you omit this operator, the queue manager interprets the file name as a queue manager name, and issues the following error message:

    AMQ8118: WebSphere MQ queue manager does not exist.

  • If you redirect output to a file, use the > redirection operator. By default, the file is put in the current working directory at the time runmqsc is invoked. Specify a fully-qualified file name to send your output to a specific file and directory.

  • Check that you have created the queue manager that is going to run the commands. On UNIX systems, look in the WebSphere MQ configuration file, mqs.ini.

  • The queue manager must be running. If it is not, start it. You get an error message if you try to start a queue manager that is already running.

  • Specify a queue manager name on the runmqsc command if you have not defined a default queue manager, or you get this error:

    AMQ8146: WebSphere MQ queue manager not available.

  • You cannot specify an MQSC command as a parameter of the runmqsc command. For example, this is not valid:

    runmqsc DEFINE QLOCAL(FRED)

  • You cannot enter MQSC commands before you issue the runmqsc command.

  • You cannot run control commands from runmqsc. For example, you cannot issue the strmqm command to start a queue manager while you are running MQSC commands interactively. If you do this, you receive error messages similar to the following: 
    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

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.