Sun Java System Message Queue 4.3 Administration Guide

Command Utility

The Command utility (imqcmd) is used for managing brokers, connection services, connections, physical destinations, durable subscriptions, and transactions.

All imqcmd commands must include a subcommand (except those using the -v or -h option to display product version information or usage help, respectively). The possible subcommands are listed in Table 15–2 and described in detail in the corresponding sections below. In addition, each imqcmd subcommand supports the general options shown in General Command Utility Options.

Note –

The -u userName option (and corresponding password) is required except when using the -v or -h option. Also if a 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.

Table 15–2 Command Utility Subcommands


Broker Management
`shutdown bkr`	Shut down broker
`restart bkr`	Restart broker
`pause bkr`	Pause broker
`quiesce bkr`	Quiesce broker
`unquiesce bkr`	Unquiesce broker
`resume bkr`	Resume broker
`takeover bkr`	Initiate broker takeover
`update bkr`	Set broker properties
`reload cls`	Reload cluster configuration
`query bkr`	List broker property values
`list bkr`	List brokers in cluster
`metrics bkr`	Display broker metrics
Connection Service Management
`pause svc`	Pause connection service
`resume svc`	Resume connection service
`update svc`	Set connection service properties
`list svc`	List connection services available on broker
`query svc`	List connection service property values
`metrics svc`	Display connection service metrics
Connection Management
`list cxn`	List connections on broker
`query cxn`	Display connection information
`destroy cxn`	Destroy connection
Physical Destination Management
`create dst`	Create physical destination
`destroy dst`	Destroy physical destination
`pause dst`	Pause message delivery for physical destination
`resume dst`	Resume message delivery for physical destination
`purge dst`	Purge all messages from physical destination
`compact dst`	Compact physical destination
`update dst`	Set physical destination properties
`list dst`	List physical destinations
`query dst`	List physical destination property values
`metrics dst`	Display physical destination metrics
Durable Subscription Management
`destroy dur`	Destroy durable subscription
`purge dur`	Purge all messages for durable subscription
`list dur`	List durable subscriptions for topics
Transaction Management
`commit txn`	Commit transaction
`rollback txn`	Roll back transaction
`list txn`	List transactions being tracked by broker
`query txn`	Display transaction information
`list dur`	List durable subscriptions for topic
JMX Management
`list jmx`	List JMX service URLs of JMX connectors

General Command Utility Options

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

Table 15–3 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.
`-passfile` `path`	Location of password file See Password Files for more information.
`-D`	Set connection-related system property that affects how `imqcomd` creates a connection to the broker. Not used to set broker configuration properties. Usually overrides connection factory attributes for `imqcmd` client runtime. For example, the option in the following command changes the default value of `imqSSLIsTrusted`: `imqcmd list svc -secure -DimqSSLIsTrusted=true`
`-rtm` `timeoutInterval`	Initial timeout interval, in seconds 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]
`-h`	Display usage help^,
`-H`	Display expanded usage help, including attribute list and examples^,

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 15–4 to manage and control it.

Table 15–4 Command Utility Subcommands for Broker Management


Syntax	Description
`shutdown bkr` [`-b` `hostName:portNumber`] [`-time` `nSeconds`] [`-nofailover`]	Shut down broker The `-time` option specifies the interval, in seconds, to wait before shutting down the broker. (The broker will not block, but will return immediately from the delayed shutdown request.) During the shutdown interval, the broker will not accept any new `jms` connections; `admin` connections will be accepted, and existing `jms` connections will continue to operate. A broker belonging to an enhanced cluster will not attempt to take over for any other broker during the shutdown interval. The `-nofailover` option indicates that no other broker is to take over the persistent data of the one being shut down. [Applies only to broker clusters]
`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.
`pause bkr` [`-b` `hostName:portNumber`]	Pause broker See Pausing and Resuming a Broker for more information.
`quiesce bkr` [`-b` `hostName:portNumber`]	Quiesce broker The broker will stop accepting new connections; existing connections will continue to operate.
`unquiesce bkr` [`-b` `hostName:portNumber`]	Unquiesce broker The broker will resume accepting new connections, returning to normal operation.
`resume bkr` [`-b` `hostName:portNumber`]	Resume broker
`takeover bkr` `-n` `brokerID` [`-f`]	Initiate broker takeover Before taking over a broker, you should first shut it down manually using the `shutdown` `bkr` subcommand with the `-nofailover` option. If the specified broker appears to be still running, `takeover` `bkr` will display a confirmation message (`Do you want to take over for this broker?`). The `-f` option suppresses this message and initiates the takeover unconditionally. Note – The `takeover` `bkr` subcommand is intended only for use in failed-takeover situations. You should use it only as a last resort, and not as a general way of forcibly taking over a running broker.
`update bkr` [`-b` `hostName:portNumber`] `-o` `property1=value1` [ [`-o` `property2=value2`] … ]	Set broker properties See Chapter 16, Broker Properties Reference for information on broker properties.
`reload cls`	Reload cluster configuration Forces all persistent information to be brought up to date.
`query bkr` `-b` `hostName:portNumber`	List broker property values For brokers belonging to a cluster, also lists cluster properties such as broker list, master broker (for conventional clusters), and cluster identifier (for enhanced clusters).
`list bkr`	List brokers in cluster
`metrics bkr` [`-b` `hostName:portNumber`] [`-m` `metricType`] [`-int` `interval`] [`-msp` `numSamples`]	Display broker metrics The `-m` option specifies the type of metrics to display: `ttl`: Messages and packets flowing into and out of the broker `rts`: Rate of flow of messages and packets into and out of the broker per second `cxn`: Connections, virtual memory heap, and threads 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).

Connection Service Management

Table 15–5 lists the imqcmd subcommands for managing connection services.

Table 15–5 Command Utility Subcommands for Connection Service Management


Syntax	Description
`pause svc` `-n` `serviceName` [`-b` `hostName:portNumber`]	Pause connection service The `admin` connection service cannot be paused.
`resume svc` `-n` `serviceName` [`-b` `hostName:portNumber`]	Resume connection service
`update svc` `-n` `serviceName` [`-b` `hostName:portNumber`] `-o` `property1=value1` [ [`-o` `property2=value2`] … ]	Set connection service properties See Connection Properties for information on connection service properties.
`list svc` [`-b` `hostName:portNumber`]	List connection services available on broker
`query svc` `-n` `serviceName` [`-b` `hostName:portNumber`]	List connection service property values
`metrics svc` `-n` `serviceName` [`-b` `hostName:portNumber`] [`-m` `metricType`] [`-int` `interval`] [`-msp` `numSamples`]	Display connection service metrics The `-m` option specifies the type of metrics to display: `ttl`: Messages and packets flowing into and out of the broker by way of the specified connection service `rts`: Rate of flow of messages and packets into and out of the broker per second by way of the specified connection service `cxn`: Connections, virtual memory heap, and threads 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).

Connection Management

Table 15–6 lists the imqcmd subcommands for managing connections.

Table 15–6 Command Utility Subcommands for Connection Service Management


Syntax	Description
`list cxn` [`-svn` `serviceName`] [`-b` `hostName:portNumber`]	List connections on broker Lists all connections on the broker to the specified connection service. If no connection service is specified, all connections are listed.
`query cxn` `-n` `connectionID` [`-b` `hostName:portNumber`]	Display connection information
`destroy cxn` `-n` `connectionID` [`-b` `hostName:portNumber`]	Destroy connection

Physical Destination Management

Table 15–7 lists the imqcmd subcommands for managing physical destinations. In all cases, the -t (destination type) option can take either of two values:

q: Queue destination

t: Topic destination

Table 15–7 Command Utility Subcommands for Physical Destination Management


Syntax	Description
`create dst` `-t` `destType` `-n` `destName` [ [`-o` `property=value`] … ]	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` `-tdestType` `-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: `PRODUCERS`: Pause delivery from message producers `CONSUMERS`: Pause delivery to message consumers `ALL`: Pause all message delivery Default value: `ALL`
`resume dst` [`-t` `destType` `-n` `destName`]	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.
`purge dst` `-t` `destType` `-n` `destName`	Purge all messages from physical destination
`compact dst` [`-t` `destType` `-n` `destName`]	Compact physical destination 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.
`update dst` `-t` `destType` `-n` `destName` `-o` `property1=value1` [ [ `-o` `property2=value2`] … ]	Set physical destination properties See Chapter 17, Physical Destination Property Reference for information on physical destination properties.
`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 destination 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).

Durable Subscription Management

Table 15–8 lists the imqcmd subcommands for managing durable subscriptions.

Table 15–8 Command Utility Subcommands for Durable Subscription Management


Syntax	Description
`destroy dur` `-n` `subscriberName` `-c` `clientID`	Destroy durable subscription [Cannot be performed in a conventional broker cluster whose master broker is temporarily unavailable]
`purge dur` `-n` `subscriberName` `-c` `clientID`	Purge all messages for durable subscription
`list dur` `-[d` `topicName`]	List durable subscriptions for the specified topic. If `-d` option is omitted then the command lists all durable subscriptions for all topics.

Transaction Management

Table 15–9 lists the imqcmd subcommands for managing local (non-distributed) Message Queue transactions. Distributed transactions are managed by a distributed transaction manager rather than imqcmd.

Table 15–9 Command Utility Subcommands for Transaction Management


Syntax	Description
`commit txn` `-n` `transactionID`	Commit transaction
`rollback txn` `-n` `transactionID`	Roll back transaction
`list txn`	List transactions being tracked by broker
`query txn` `-n` `transactionID`	Display transaction information

JMX Management

The imqcmd subcommand shown in Table 15–10 is used for administrative support of Java applications using the Java Management Extensions (JMX) application programming interface to configure and monitor Message Queue resources. See Appendix D, JMX Support for further information on the broker's JMX support.

Table 15–10 Command Utility Subcommand for JMX Management


Syntax	Description
`list jmx`	List JMX service URLs of JMX connectors