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 16-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 16-2 Command Utility Subcommands
|
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 |
|
|
query bkr |
List broker property values |
list bkr |
List brokers in cluster |
metrics bkr |
Display
broker metrics |
reload cls |
Reload cluster configuration |
changemaster cls |
Change the master broker in a conventional cluster with
master broker |
|
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 |
|
list cxn |
List connections on broker |
query cxn |
Display
connection information |
destroy cxn |
Destroy connection |
|
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 |
|
destroy dur |
Destroy
durable subscription |
purge dur |
Purge all messages for durable subscription |
list dur |
List durable subscriptions for topics |
|
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 |
|
list jmx |
List JMX service URLs of JMX connectors |
|
General Command Utility Options
The additional options listed in Table 16-3 can be applied to any subcommand
of the imqcmd command.
Table 16-3 General Command Utility Options
|
|
-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 |
|
-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 1,2 |
-h |
|
-H |
Display expanded usage help, including attribute list and examples 1,2 |
|
1Any other
options specified on the command line are ignored.
2User name and password
not needed
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 16-4 to manage and control it.
Table 16-4 Command Utility Subcommands for Broker Management
|
|
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. 1 |
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] |
|
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] |
|
|
Initiate broker takeover 1Before 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]
|
|
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 |
|
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). |
reload cls |
Reload cluster configuration 1Forces all persistent information to be brought
up to date. |
changemaster cls -o imq.cluster.masterbroker=newMaster |
Change the master broker in a conventional cluster with
master broker. This command must be run on the current master broker. The value
newMaster has the form hostName:portNumber, where hostName and portNumber are is its Port
Mapper host name and port number, respectively. Literal IP addresses as host names: You can use a literal IPv4 or
IPv6 address as a host name. If you use a literal IPv6 address,
its format must conform to RFC2732, Format for Literal IPv6 Addresses in URL's. |
|
1Applies only to broker clusters
Connection Service Management
Table 16-5 lists the imqcmd subcommands for managing connection services.
Table 16-5 Command Utility Subcommands for Connection Service Management
|
|
|
Pause connection service The
admin connection service cannot be paused. |
resume svc -n serviceName
|
Resume connection service |
update svc -n serviceName
|
Set connection service properties See
Connection Properties for information on connection service properties. |
list svc [-b hostName:portNumber] |
List connection services available on broker |
|
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 16-6 lists the imqcmd subcommands for managing connections.
Table 16-6 Command Utility Subcommands for Connection Service Management
|
|
list cxn [ -svn serviceName]
|
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
|
Display connection information |
destroy cxn -n connectionID
|
|
|
Physical Destination Management
Table 16-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 16-7 Command Utility Subcommands for Physical Destination Management
|
|
create dst -t destType -n destName
|
Create physical destination 1The 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 1This
operation cannot be applied to a system-created destination, such as a dead message
queue. |
pause dst [ -t destType -n destName]
|
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
|
|
|
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). |
|
1Cannot be performed in a broker cluster whose master broker
is temporarily unavailable
Durable Subscription Management
Table 16-8 lists the imqcmd subcommands for managing durable subscriptions.
Table 16-8 Command Utility Subcommands for Durable Subscription Management
|
|
destroy dur -n subscriberName -c clientID |
Destroy durable subscription 1 |
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. |
|
1Cannot
be performed in a conventional broker cluster whose master broker is temporarily unavailable
Transaction Management
Table 16-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 16-9 Command Utility Subcommands for Transaction Management
|
|
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 16-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 16-10 Command Utility Subcommand for JMX Management
|
|
list jmx |
List
JMX service URLs of JMX connectors |
|