Command Line Syntax

Message Queue command line utilities are shell commands. The name of
the utility is a command and its subcommands or options are arguments passed
to that command. There is no need for separate commands to start or quit the
utility.

Subcommands and command-level arguments, if any, must precede all options
and their arguments; the options themselves may appear in any order. All subcommands,
command arguments, options, and option arguments are separated with spaces.
If the value of an option argument contains a space, the entire value must
be enclosed in quotation marks. (It is generally safest to enclose any attribute-value
pair in quotation marks.)

The following command, which starts the default broker, is an example
of a command line with no subcommand clause:

imqbrokerd

Here is a fuller example:

imqcmddestroy dst-t q-n myQueue-u admin-f-s

This command destroys a queue destination (destination type q)
named myQueue. Authentication is performed on the user
name admin; the command will prompt for a password. The
command will be performed without prompting for confirmation (-f option)
and in silent mode, without displaying any output (-s option).

Broker Utility

The Broker utility (imqbrokerd) starts a broker.
Command line options override values in the broker configuration files, but
only for the current broker session.

Table 13–1 shows the options
to the imqbrokerd command and the configuration properties,
if any, overridden by each option.

Table 13–1 Broker
Utility Options

Option

Properties Overridden

Description

-name instanceName

imq.instancename

Instance name of broker

Multiple broker instances running on the same host must have different
instance names.

Default value:imqbroker

-port portNumber

imq.portmapper.port

Port number for broker’s Port Mapper

Message Queue clients use this port number to connect to the broker.
Multiple broker instances running on the same host must have different Port
Mapper port numbers.

Default value:7676

-clusterbroker1 [ [ ,broker2 ] … ]

imq.cluster.brokerlist

Connect brokers into cluster [Applies only to broker clusters]

The specified brokers are merged with the list in the imq.cluster.brokerlist property. Each broker argument has one of the forms

hostName:portNumber

hostName

:portNumber

If hostName is omitted, the default value
is localhost; if portNumber is
omitted, the default value is 7676.

Clears all persistent data from the data store (including persistent
messages, durable subscriptions, and transaction information), allowing you
to start the broker instance with a clean slate. To prevent the persistent
store from being reset on subsequent restarts, restart the broker instance
without the -reset option.

To clear only persistent messages or durable subscriptions, use -resetmessages or -resetdurables instead.

Deletes the instance configuration file, log files, persistent store,
and other files and directories associated with the instance.

-password keyPassword

imq.keystore.password

Password for SSL certificate key store [This option is deprecated and will eventually be removed. Either omit
the password (so that the user will be prompted for it interactively) or use
the -passfile option to specify a file containing the password. ]

-dbuser userName

imq.persist.jdbc.user

User name for JDBC-based persistent data store

-dbpassword dbPassword

imq.persist.jdbc.password

Password for JDBC-based persistent data store

-ldappassword ldapPassword

imq.user_repository.ldap.password

Password for LDAP user repository

-passfile filePath

imq.passfile.enabledimq.passfile.dirpathimq.passfile.name

Location of password file

Sets the broker’s imq.passfile.enabled property
to true, imq.passfile.dirpath to the
path containing the password file, and imq.passfile.name to
the file name itself.

Command Utility

All imqcmd commands must include a subcommand (except
those using the -v or -h option to display
product version information or usage help). The possible subcommands are listed
here and described in detail in the corresponding sections below. In all cases,
if the subcommand accepts a broker address (-b option) and
no host name or port number is specified, the values localhost and 7676 are assumed by default.

Broker Management

The Command utility cannot be used to start a broker; use the Broker
utility (imqbrokerd) instead. Once the broker
is started, you can use the imqcmd subcommands listed in Table 13–2 to manage and control it.

Table 13–2 Command Utility
Subcommands for Broker Management

Syntax

Description

shutdown bkr [-b hostName:portNumber]

Shut down broker

restart bkr [-b hostName:portNumber]

Restart broker

Shuts down the broker and then restarts it using the same options specified
when it was originally started.

Create physical destination [Cannot be performed in a broker cluster whose master broker is temporarily
unavailable]

The destination name destName may contain
only alphanumeric characters (no spaces) and must begin with an alphabetic
character or the underscore (_) or dollar sign ($)
character. It may not begin with the characters mq.

destroy dst -t destType-n destName

Destroy physical destination

This operation cannot be applied to a system-created destination, such
as a dead message queue.

pause dst [-t destType-n destName]

[-pst pauseType]

Pause message delivery for physical destination

Pauses message delivery for the physical destination specified by the -t and -n options. If these options are not specified,
all destinations are paused.

The -pst option specifies the type of message delivery
to be paused:

CONSUMERS: Pause delivery to message consumers

PRODUCERS: Pause delivery to message producers

ALL: Pause all message delivery

Default value:ALL

resume dst [-t destType-ndestName]

Resume message delivery for physical destination

Resumes message delivery for the physical destination specified by the -t and -n options. If these options are not specified,
all destinations are resumed.

Compacts the file-based persistent data store for the physical destination
specified by the -t and -n options. If these
options are not specified, all destinations are compacted.

A destination must be paused before it can be compacted.

list dst [-t destType]

[-tmp]

List physical destinations

Lists all physical destinations of the type specified by the -t option.
If no destination type is specified, both queue and topic destinations are
listed. If the -tmp option is specified, temporary destinations
are listed as well.

query dst -t destType-n destName

List physical destination property values

metrics dst -t destType-n destName

[-m metricType]

[-int interval]

[-msp numSamples]

Display physical destination metrics

The -m option specifies the type of metrics to display:

ttl: Messages and packets flowing into
and out of the destination and residing in memory

rts: Rate of flow of messages and packets
into and out of the broker per second, along with other rate information

con: Metrics related to message consumers

dsk: Disk usage

Default value:ttl.

The -int option specifies the interval, in seconds,
at which to display metrics. Default value:5.

The -msp option specifies the number of samples to display. Default value: Unlimited (infinite).

General Command Utility Options

The additional options listed in Table 13–8 can
be applied to any subcommand of the imqcmd command.

Table 13–8 General Command
Utility Options

Option

Description

-secure

Use secure connection to broker with ssladmin connection
service

-u userName

User name for authentication

If this option is omitted, the Command utility will prompt for it interactively.

-p password

Password for authentication [This option is deprecated and will eventually be removed. Either omit
the password (so that the user will be prompted for it interactively) or use
the -passfile option to specify a file containing the password. ]

This is the initial length of time that the Command utility will wait
for a reply from the broker before retrying a request. Each subsequent retry
will use a timeout interval that is a multiple of this initial interval.

Default value:10.

-rtr numRetries

Number of retries to attempt after a broker request times out

Default value:5.

-javahome path

Location of alternative Java runtime

Default behavior: Use runtime installed
on system or bundled with Message Queue.

-f

Perform action without user confirmation

-s

Silent mode (no output displayed)

-v

Display version information [Any other options specified on the command line are ignored. ] , [User name and password not needed]

Default behavior: Use runtime installed
on system or bundled with Message Queue.

-f

Perform action without user confirmation

-s

Silent mode (no output displayed)

-v

Display version information [Any other options specified on the command line are ignored. ]

-h

Display usage help

-H

Display expanded usage help, including attribute list and examples

Database Manager Utility

The Database Manager utility (imqdbmgr) sets up
the database schema for a JDBC-based persistent data store.
You can also use it to delete Message Queue database tables that have become
corrupted or to change the data store. Table 13–11 lists the available subcommands.

Table 13–11 Database Manager
Subcommands

Subcommand

Description

create all

Create new database and persistent store schema

Used on embedded database systems. The broker property imq.persist.jdbc.createdburl must be specified.

Caution: Be careful to check the
spelling and formatting of properties set with this option. Incorrect values
will be ignored without notification or warning.

-u name

User name for authentication

-p password

Password for authentication [This option is deprecated and will eventually be removed. Either omit
the password (so that the user will be prompted for it interactively) or use
the -passfile option to specify a file containing the password. ]

Display version information [Any other options specified on the command line are ignored. ]

-h

Display usage help

User Manager Utility

The User Manager utility (imqusermgr) is used for
populating or editing a flat-file user repository. The utility must be run
on the same host where the broker is installed; if a broker-specific user
repository does not yet exist, you must first start up the corresponding broker
instance in order to create it. You will also need the appropriate permissions
to write to the repository: on the Solaris or Linux platforms, this means you must be either
the root user or the user who originally created the broker instance.

Table 13–13 lists the subcommands available with the imqusermgr command.
In all cases, the -i option specifies the instance name of
the broker to whose user repository the command applies; if not specified,
the default name imqbroker is assumed.

Table 13–13 User Manager Subcommands

Syntax

Description

add [-i instanceName]

-u userName-p password

[-g group]

Add user and password to repository

The optional -g option specifies a group to which to
assign this user:

admin

user

anonymous

delete [-i instanceName]

-u userName

Delete user from repository

update [-i instanceName]

-u userName-p password

[-a activeState]

update [-i instanceName]

-u userName-a activeState

[-p password]

Set user’s password or active state (or both)

The -a option takes a boolean value specifying whether
to make the user active (true) or inactive (false). Default value:true.

list [-i instanceName]

[-u userName]

Display user information

If no user name is specified, all users in the repository are listed.

In addition, the options listed in Table 13–14 can be applied to any subcommand of the imqusermgr command.

Table 13–14 General User Manager
Options

Option

Description

-f

Perform action without user confirmation

-s

Silent mode (no output displayed)

-v

Display version information [Any other options specified on the command line are ignored. ]

-h

Display usage help

Service Administrator Utility

The Service Administrator utility (imqsvcadmin)
installs a broker as a Windows service. Table 13–15 lists the available subcommands.

Table 13–15 Service Administrator
Subcommands

Subcommand

Description

install

Install service

remove

Remove service

query

Display startup options

Startup options can include whether the service is started manually
or automatically, its location, the location of the Java runtime, and the
values of arguments passed to the broker on startup (see Table 13–16).

Default behavior: Use runtime installed
on system or bundled with Message Queue.

-jrehome path

Location of alternative Java Runtime Environment (JRE)

-vmargs arg1 [ [arg2] … ]

Additional arguments to pass to Java Virtual Machine (JVM)
running broker service [These arguments can also be specified in the Start Parameters field
under the General tab in the service’s Properties window (reached via
the Services tool in the Windows Administrative Tools control panel). ]

Example:

imqsvcadmin install -vmargs "-Xms16m
-Xmx128m"

-args arg1 [ [arg2]
… ]

Additional command line arguments to pass to broker service

Example:

imqsvcadmin install -args "-passfile d:\\imqpassfile"

See Broker Utility for information
about broker command line arguments.

-h

Display usage help [Any other options specified on the command line are ignored. ]

Any information you specify using the -javahome, -vmargs, and -args options is stored in the Windows registry
under the keys JREHome, JVMArgs, and ServiceArgs in the path