Chapter 6   Broker and Application Management


This chapter explains how to perform tasks related to managing the broker and the services it provides. Some of these tasks are independent of any particular client application. These include:

• controlling the broker's state: you can pause, resume, shutdown, and restart the broker.

• querying and updating broker properties

• querying and updating connection services

• allocating and managing resources

• managing connection services

Other broker tasks are performed on behalf of specific applications; these include managing physical destinations, durable subscriptions, and transactions:

• MQ messages are routed to their receivers or subscribers by way of broker destinations. You are responsible for creating these destinations on the broker.

• MQ allocates and maintains resources for durable subscribers even when clients that have durable subscriptions become inactive. You use the MQ Command tool to get information about durable subscriptions and to destroy durable subscriptions or purge their messages in order to save MQ resources.

• MQ transactions and distributed transactions are tracked by a broker. You might need to manually commit or roll back transactions if a failure takes place.

This chapter explains how you use the Command utility (imqcmd) to perform all these tasks. You can accomplish many of these same tasks by using the Administration Console, the graphical interface to the MQ message server. For more information, see Chapter 4, "Administration Console Tutorial."

Command Utility

---

The Command utility allows you to manage the broker and the services it provides. This section describes the basic syntax of imqcmd commands, provides a listing of subcommands, and summarizes imqcmd options. Subsequent sections explain how you use these commands to accomplish specific tasks.

Syntax of Commands

The general syntax of imqcmd commands is as follows:

imqcmd [subcommand argument ] options

or

imqcmd subcommand argument [options ]

Note that if you specify the -v, -h, or -H options, no other subcommands specified on the command line are executed. For example, if you enter the following command, version information is displayed but the restart subcommand is not executed.

imqcmd restart bkr -v

imqcmd Subcommands

The Command utility (imqcmd) includes the subcommands listed in Table 6-1:

Table 6-1    imqcmd Subcommands and Arguments 

Subcommand	Description
create dst	Creates a destination.
commit txn	Commits a transaction.
destroy dst	Destroys a destination.
destroy dur	Destroys a durable subscription.
list dst	Lists destinations on the broker.
list dur	Lists durable subscriptions on the topic.
list svc	Lists services on the broker.
list txn	Lists transactions on the broker.
metrics bkr	Displays broker metrics.
metrics svc	Displays service metrics.
pause bkr	Pauses all services on the broker.
pause svc	Pauses one service.
purge dst	Purges all messages on a destination without destroying the destination.
purge dur	Purges all messages on a durable subscription without destroying the durable subscription.
query bkr	Queries and display information on a broker.
query dst	Queries and display information on a destination.
query svc	Queries and display information on a service.
query txn	Queries and display information on a transaction.
reload cls	Reloads broker cluster configuration.
restart bkr	Restarts broker.
resume bkr	Resumes all services on the broker.
resume svc	Resumes one service.
rollback txn	Rolls back a transaction.
shutdown bkr	Shuts down broker.
update bkr	Updates attributes of a broker.
update dst	Updates attributes of a destination.
update svc	Updates attributes of a service.

Summary of imqcmd Options

Table 6-2 lists the options to the imqcmd command. For a discussion of their use, see the following task-based sections.

Table 6-2    imqcmd Options 

Option	Description
-b hostName:port	Specifies the name of the broker's host and its port number. The default value is localhost:7676. To specify port only: -b :7878 To specify name only: -b somehost
-c "clientID"	Specifies the ID of the durable subscriber to a topic. For more information, see "Managing Durable Subscriptions".
-d topicName	Specifies the name of the topic. Used with the list dur and destroy dur subcommands. See "Managing Durable Subscriptions".
-f	Perform action without user confirmation.
-h	Displays usage help.
-H	Displays usage help, attribute list, and examples.
-int interval	Specifies the interval, in seconds, at which imqcmd displays broker metrics. (Used with the metrics subcommand.)
-javahome	Specifies an alternate Java 2 compatible runtime to use (default is to use the runtime bundled with the product).
-m metricType	Specifies the type of metric information to display. Type can be one of the following ttl    Total of messages in and out of the broker (default). rts    Provides the same information as ttl, but specifies the            number of messages per second. cxn    Connections, virtual memory heap, threads Use this option with the metrics bkr or metrics svc subcommand. The following command displays cxn-type metrics for the default broker every five seconds. imqcmd metrics bkr -m cxn -int 5
-n targetName	Specifies the name of the target. Depending on the subcommand, this might be the name of a physical destination, a service, a transaction ID, or a durable subscription. For information about its use with destination management, see "Managing Destinations".
-o attribute=value	Specifies the value of an attribute. Depending on the subcommand argument, this might be the attribute of a broker (see "Querying and Updating Broker Properties"), service (see "Managing Connection Services"), or destination (see "Managing Destinations").
-secure	Specifies a secure administration connection to the broker using the ssladmin connection service (see "Step 4. Configuring and Running SSL-based Clients,", "Command Utility (imqcmd)").
-p password	Specifies your (the administrator's) password. If you omit this value, you will be prompted for it.
-s	Silent mode. No output will be displayed.
-t destinationType	Specifies the type of a destination: t (topic) or q (queue).
-tmp	Displays temporary destinations.
-u name	Specifies your (the administrator's) name. If you omit this value, you will be prompted for it.
-v	Displays version information.

You must specify the options for host name and port number (-b), user name (-u) password (-p), and secure connection (-secure) each time you issue a imqcmd subcommand. If you don't specify the host name and port number, it uses the default values. If you don't specify user name and password information, you will be prompted for them. If you don't specify -secure, then the connection will not be secure.

Prerequisites to Using imqcmd

In order to use imqcmd commands to manage the broker, you must do the following:

• Start the broker using the imqbrokerd command.

  See "Starting a Broker". You can use the Command utility only to administer brokers that are already running; you cannot use it to start a broker.

• Specify the target broker using the -b option unless the broker is running on the local host, on port 7676.

• Specify the proper administrator user name and password. If you do not do this, you will be prompted for it. Either way, be aware that every operation you perform using imqcmd will be authenticated against a user repository.

  When you install MQ, a default flat-file user repository is installed. The file is named IMQ_HOME/etc/passwd (/etc/imq/passwd on Solaris). The repository is shipped with two entries: one for an admin user and one for a guest user. These entries allow you to connect to the broker without doing any additional work. For example, if you are just testing MQ, you can run the utility using your default user name and password (admin/admin).

  If you are setting up a production system, you will need to do some additional work to authenticate and authorize users. You also have the option of using an existing LDAP directory server for your user repository. For more information, see "Authenticating Users".

Examples

The following command lists the properties of the broker running on localhost at port 7676:

imqcmd query bkr -u admin -p admin

The following command lists the properties of the broker running on myserver at port 1564; the user's name is alladin, the user's password is abracadabra.

imqcmd query bkr -b myserver:1564 -u alladin -p abracadabra

Assuming that the user name alladin was assigned to the admin group, you will be connected as an admin client to the specified broker.

Controlling the Broker's State

---

After you start the broker, you can use the following imqcmd subcommands to control the state of the broker.

• Pausing the broker

  Pausing the broker suspends the broker service threads which causes the broker to stop listening on the ports. You can then perform any administration tasks needed to regulate the flow of messages to the broker. For example, if a particular destination is bombarded with messages, you can pause the broker and take any of the following actions that might help you fix the problem: trace the source of the messages, limit the size of the destination, or destroy the destination.

  The following command pauses the broker running on myhost at port 1588.

  imqcmd pause bkr -b myhost:1588

• Resuming the broker

  Resuming the broker reactivates the broker's service threads and the broker resumes listening on the ports. The following command resumes the broker running on localhost at port 7676.

  imqcmd resume bkr

• Shutting down the broker

  Shutting down the broker terminates the broker process. This is a graceful termination: the broker stops accepting new connections and messages, it completes delivery of existing messages, and it terminates the broker process. The following command shuts down the broker running on ctrlsrv at port 1572

  imqcmd shutdown bkr -b ctrlsrv:1572

• Restarting the broker

  Shuts down and restarts the broker. The following command restarts the broker running on localhost at port 7676:

  imqcmd restart bkr

Table 6-3 summarizes the imqcmd subcommands used to control the broker. Remember that you must specify the broker host name and port number unless you are targeting the broker running on localhost at port 7676.

Table 6-3    imqcmd Subcommands Used to Control the Broker 

Subcommand	Description
pause bkr [-b hostName:port]	Pause the default broker or a broker at the specified host and port.
resume bkr [-b hostName:port]	Resume the default broker or a broker at the specified host and port.
shutdown bkr [-b hostName:port]	Shutdown the default broker or a broker at the specified host and port.
restart bkr [-b hostName:port]	Shutdown and restart the default broker or a broker at the specified host and port. Note that this command restarts the broker using the options specified when the broker was first started. If you want different options to be in effect, you must shutdown the broker and then start it again, specifying the options you want.

Querying and Updating Broker Properties

---

The Command utility includes subcommands that you can use to get information about the broker and to update broker properties. Table 6-4 lists these subcommands.

Table 6-4    imqcmd Subcommands Used to Get Information and to Update Broker

Subcommand Syntax	Description
query bkr -b hostName:port	Lists the current settings of properties of the default broker or a broker at the specified host and port. Also shows the list of running brokers (in a multi-broker cluster) that are connected to the specified broker.
reload cls	Forces all the brokers in a cluster to reload the imq.cluster.brokerlist property and update cluster information. See "Adding Brokers to Clusters" for more information.
update bkr [-b hostName:port] -o attr=val	Changes the specified attributes for the default broker or a broker at the specified host and port.
metrics bkr [-b hostName:port] [-m metricType] [-int interval]	Displays broker metrics for the default broker or a broker at the specified host and port. Use the -m option to specify the type of metric to display: ttl    Total of messages in and out of the             broker (default). rts    Provides the same information as ttl,             but specifies the number of messages             per second. cxn    Connections, virtual memory heap,             threads Use the -int option to specify the interval (in seconds) at which to display the metrics. The default is 5 seconds

Remember that you must specify the broker host name and port number when using any of the subcommands listed in Table 6-4 unless you are targeting the broker running on localhost at port 7676

Querying a Broker

To query and display information about a single broker, use the query subcommand. For example,

imqcmd query bkr

This produces output like the following:

%imqcmd query bkr Querying the broker specified by: ------------------------- Host         Primary Port ------------------------- localhost    7676 Auto Create Queues                     true Auto Create Topics                     true Auto Created Queue Delivery Policy     Round Robin Cluster Broker List (active)           myhost/192.18.116.221:7676 Cluster Broker List (configured)        Cluster Master Broker                   Cluster URL                             Current Number of Messages in System   0 Current Size of Messages in System     0 Instance Name                          imqbroker Log Level                              INFO Log Rollover Interval (seconds)        604800 Log Rollover Size (bytes)              0 (unlimited) Max Message Size                       70m Max Number of Messages in System       0 (unlimited) Max Size of Messages in System         0 (unlimited) Primary Port                           7676 Version                                3.0 Successfully queried the broker.

Updating a Broker

You can use the update subcommand to update any of the broker properties listed in Table 6-5. Note that updates to the broker are automatically written to the broker's instance configuration file.

Table 6-5    Broker Properties 

Properties	Description
imq.autocreate.queue	Specifies whether a broker is allowed to auto-create a queue destination. True by default.
imq.autocreate.topic	Specifies whether a broker is allowed to auto-create a topic destination. True by default.
imq.queue.deliverypolicy	Specifies the default delivery policy of auto-created queues. Values are: s (single), r (round-robin), or f (failover). Default is s.
imq.cluster.url	Specifies the location of the cluster configuration file. For more information, see"Cluster Configuration Properties".
imq.log.level	Specifies the log level as one of the following: NONE, ERROR, WARNING, INFO. Default is INFO.
imq.log.file.rolloversecs	The age (in seconds) before the log file is rolled over. A value of 0 means no rollover based on the age of the file. Default is 604800 (7 days).
imq.log.file.rolloverbytes	Specifies the maximum size of the log file before it is rolled over. A value of 0 means no rollover based on file size. Default is 0.
imq.message.max_size	Specifies the maximum size of a message in bytes. Default is 70m.
imq.system.max_count	Specifies the maximum number of messages in memory and disk. A value of 0 means no limit. Default is 0.
imq.system.max_size	Specifies the maximum total size of messages in memory and disk. A value of 0 means no limit. Default is 0.
imq.portmapper.port	Specifies the number of the port mapper port. Default is 7676.

For example, the following command changes the default delivery policy for queues from single to round-robin.

imqcmd update bkr -o "imq.queue.deliverypolicy=r"

Managing Connection Services

---

The Command utility includes a number of subcommands that allows you to do the following

• list available connection services

• display information about a particular service

• update the attributes of a service

• pause and resume services

For an overview of MQ connection services, see "Connection Services".

Table 6-6 lists the imqcmd subcommands that control connection services. If no host name or port is specified, they are assumed to be localhost, 7676.

Table 6-6    imqcmd Subcommands Used to Manage Connection Services 

Subcommand Syntax	Description
list svc [-b hostName:port]	Lists all connection services on the default broker or on a broker at the specified host and port.
metrics svc -n serviceName [-b hostName:port] [-m metricType] [-int interval]	List metrics for the specified service on the default broker or on a broker at the specified host and port. Use the -m option to specify the type of metric to display: ttl    Total of messages in and out of the broker             (default). rts    Provides the same information as ttl, but             specifies the number of messages per             second. cxn    Connections, virtual memory heap, threads Use the -int option to specify the interval (in seconds) at which to display the metrics. The default is 5 seconds.
query svc -n serviceName [-b hostName:port]	Displays information about the specified service running on the default broker or on a broker at the specified host and port.
pause svc -n serviceName [-b hostName:port]	Pauses the specified service running on the default broker or on a broker at the specified host and port. You cannot pause the admin service.
resume svc -n serviceName [-b hostName:port]	Resumes the specified service running on the default broker or on a broker at the specified host and port.
update svc -n serviceName [-b hostName:port] -o attr=val	Updates the specified attribute of the specified service running on the default broker or on a broker at the specified host and port. For a description of service attributes, see Table 6-8.

A broker supports communication with both application clients and administration clients. The connection services currently available from an MQ broker are shown in Table 6-7. The values in the Service Name column are the values you use to specify a service name for the -n option. (As shown in the table, each service is specified by the service type it uses—NORMAL (JMS) or ADMIN—and an underlying transport layer.)

Table 6-7    Connection Services Supported by a Broker 

Service Name	Service Type	Protocol Type
jms	NORMAL (JMS message delivery)	tcp
ssljms	NORMAL (JMS message delivery)	tls (SSL-based security)
httpjms	NORMAL (JMS message delivery)	http
httpsjms	NORMAL (JMS message delivery)	https (SSL-based security)
admin	ADMIN	tcp
ssladmin	ADMIN	tls (SSL-based security)

Listing Connection Services

To list available connection services on a broker, use a command like the following:

imqcmd list svc [-b hostName:portNumber]

For example, the following command lists the services available for the broker running on the host MyServer on port 6565.

imqcmd list svc -b MyServer:6565

The following command lists all services on the broker running on localhost at port 7676:

imqcmd list svc

The command will output information like the following:

Listing all the services on the broker specified by: Host                 Primary Port localhost            7676 Service Name     Port Number       Service State admin            33984 (dynamic)   RUNNING httpjms                            UNKNOWN httpsjms         -                 UNKNOWN jms              33983 (dynamic)   RUNNING ssladmin         dynamic           UNKNOWN ssljms           dynamic           UNKNOWN Successfully listed services.

Querying and Updating Service Properties

To query and display information about a single service, use the query subcommand. For example,

imqcmd query svc -n jms

This produces output like the following:

Querying the service where: Service Name jms On the broker specified by: Host                         Primary Port localhost                    7676 Current Number of Allocated Threads    120 Current Number of Connections          20 Max Number of Threads                  1000 Min Number of Threads                  50 Port Number                            42019 (dynamic) Service Name                           jms Service State                          RUNNING Successfully queried the service.

You can use the update subcommand to change the value of one or more of the service attributes listed in Table 6-8.

Table 6-8    Connection Service Attributes

Attribute	Description
port	The port assigned to the service to be updated (does not apply to httpjms or httpsjms).
minThreads	The minimum number of threads assigned to the service.
maxThreads	The maximum number of threads assigned to the service.

The following command changes the minimum number of threads assigned to the jms service to 20.

imqcmd update svc -n jms -o "minThreads=20"

Pausing and Resuming a Service

To pause any service other than the admin service (which cannot be paused), use a command like the following:

imqcmd pause svc -n serviceName

To resume a service, use a command like the following:

imqcmd resume svc -n serviceName

Managing Destinations

---

All MQ messages are routed to their consumer clients by way of destinations, queues and topics, created on a particular broker. You are responsible for managing these destinations on the broker. This involves using the Command utility to create and destroy destinations, to list destinations, to display information about destinations, and to purge messages. For an introduction to destinations, see "Physical Destinations".

Table 6-9 provides a summary of the imqcmd destination subcommands. Remember to specify the host name and port of the broker if this is not the default (localhost:7676) broker.

Table 6-9    imqcmd Subcommands Used to Manage Destinations 

Subcommand	Description
list dst [-tmp]	Lists all destinations, with option of listing temporary destinations as well (see "Temporary Destinations").
create dst -t type -n name [-o att=val] [-o att=val1]...]	Creates a destination of the specified type, with the specified name, and the specified attributes. Destination names must contain only alphanumeric characters (no spaces) and can begin with an alphabetic character or the character "_"
destroy dst -t type -n name	Destroys the destination of the specified type and name.
purge dst -t type -n name	Purge messages at the destination with the specified type and name.
query dst -t type -n name	Lists information about the destination of the specified type and name.
update dst -t type -n name -o att=val[[-o att=val1]...]	Updates the value of the specified attributes at the specified destination. The attribute name may be any of the attributes described in Table 6-10.

Creating Destinations

When creating a destination, you must specify its type (topic or queue) and, if needed, specify values for the destination's attributes. Default values for these attributes are set in the broker's configuration file (see "Configuration Files".)

Destroying a destination purges all messages at that destination and removes it from the broker; the operation is not reversible.

Table 6-10 describes the attributes that can be set for each type of destination when you create the destination.

Table 6-10    Destination Attributes 

Destination Type	Attribute	Default Value	Description
Queue	queueDeliveryPolicy	Single	Describes the algorithm used to route messages. Values are f = Failover r = Round robin s = Single
Queue	maxTotalMsgBytes	0 (unlimited)	Maximum total size in bytes of messages allowed in the queue.
Queue	maxNumMsgs	0 (unlimited)	Maximum number of messages allowed in the queue
Queue	maxBytesPerMsg	0 (unlimited)	Maximum size of any single message allowed in the queue.
Topic	maxBytesPerMsg	0 (unlimited)	Maximum size of any single message posted to the topic.

• To create a queue destination, enter a command like the following:

  imqcmd create dst -n myQueue -t q -o "queueDeliveryPolicy=f"

  Note that a destination name must be a valid Java identifier.

• To create a topic destination, enter a command like the following:

  imqcmd create dst -n myTopic -t t -o "maxBytesPerMsg=5000"

Getting Information About Destinations

To get information about the current value of a destination's attributes, use a command like the following:

imqcmd query dst -t q -n XQueue

You can then use the update imqcmd subcommand to change the values of one or more attributes.

To list all destinations on a particular broker, say the broker running on myHost at port 4545, use a command like the following:

imqcmd list dst -b myHost:4545

The list command can optionally include temporary destinations (using the -tmp option). These are destinations created by client applications that need a destination at which to receive replies to messages sent to other clients (see "Temporary Destinations"). You cannot destroy these destinations; they can only be destroyed by API calls made by the client application when there are no more active message consumers.

Updating Destinations

You can change the attributes of a destination by using the update dst subcommand and the -o option to specify the attribute to update. You can use the -o option more than once if you want to update more than one attribute. For example, the following command changes the maxBytesPerMsg attribute to 1000 and the MaxNumMsgs to 2000:

imqcmd update dst -t q -n myQueue -o "maxBytesPerMsg=1000"
-o maxNumMsgs=2000

See Table 6-10 for a list of the attributes that you can update.

You cannot use the update dst subcommand to update the type of a destination or to update the queue delivery policy for a queue.

Purging Destinations

You can purge all messages currently queued at a destination. Purging a destination means that all messages queued at the physical destination are deleted. You might want to purge messages when the messages accumulated at a destination are taking up too much of the system's resources. This might happen when a queue does not have any registered consumer clients and is receiving many messages. It might also happen if inactive durable subscribers to a topic do not become active. In both cases, messages are held unnecessarily.

To purge messages at a destination, enter commands like the following:

imqcmd purge dst -n myQueue -t q

imqcmd purge dst -n myTopic -t t

In the case where you have shut down the broker and do not want old messages to be delivered when you restart it, use the reset subcommand of the imqbrokerd command to purge stale messages; for example:

imqbrokerd -reset messages

This saves you the trouble of purging destinations after restarting the broker.

Destroying Destinations

To destroy a destination, enter a command like the following:

imqcmd destroy dst -t q -n myQueue

Managing Durable Subscriptions

---

You might need to use imqcmd subcommands to manage a broker's durable subscriptions. A durable subscription is a subscription to a topic that is registered by a client as durable; it has a unique identity and it requires the broker to retain messages for that subscription even when its consumer becomes inactive. Normally, the broker may only delete a message held for a durable subscriber when the message expires.

Table 6-12 provides a summary of the imqcmd durable subscription subcommands. Remember to specify the host name and port of the broker if this is not the default (localhost:7676) broker.

Table 6-11    imqcmd Subcommands Used to Manage Durable Subscriptions

Subcommand	Description
list dur -d destination	Lists all durable subscriptions for the specified destination.
destroy dur -n name -c client_id	Destroys the specified durable subscription for the specified Client Identifier (see "Client Identifiers").
purge dur -n name -c client_id	Purges all messages for the specified Client Identifier (see "Client Identifiers").

For example, the following command lists all durable subscriptions to the topic SPQuotes

imqcmd list dur -d SPQuotes

For each durable subscription to a topic, the list subcommand returns the name of the durable subscription, the client ID of the user, the number of messages queued to this topic, and the state of the durable subscription (active/inactive). For example:

Listing all the durable subscriptions on the topic myTopic on the broker specified by: ------------------------- Host         Primary Port ------------------------- localhost    7676 Name        Client ID       Number of   Durable Sub                             Messages      State ---------------------------------------------------------------- myDurable   myClientID       1           INACTIVE Successfully listed durable subscriptions.

You can use the information returned from the list command to identify a durable subscription you might want to destroy or for which you want to purge messages. Use the name of the subscription and the client ID to identify the subscription. For example:

imqcmd destroy dur -n myDurable -c myClientID

Managing Transactions

---

All transactions initiated by client applications are tracked by the broker. These can be simple MQ transactions or distributed transactions managed by an XA resource manager (see "Local Transactions"). All transaction have an MQ transaction ID—a 64 bit number that uniquely identifies a transaction on the broker. Distributed transactions also have a distributed transaction ID (XID) assigned by the distributed transaction manager—up to 128 bytes long. MQ maintains the association of an MQ transaction ID with an XID.

For distributed transactions, in cases of failure, it is possible that transactions could be left in a PREPARED state without ever being committed. Hence, as an administrator you might need to monitor and then roll back or commit transactions left in a prepared state.

Table 6-12 provides a summary of the imqcmd transactions subcommands. Remember to specify the host name and port of the broker if this is not the default (localhost:7676) broker.

Table 6-12    imqcmd Subcommands Used to Manage Transactions

Subcommand	Description
list txn	Lists all transactions, being tracked by the broker.
query txn -n transaction_id	Lists information about the specified transaction.
commit txn -n transaction_id	Commits the specified transaction.
rollback txn -n transaction_id	Rolls back the specified transaction.

For example, the following command lists all transactions in a broker.

imqcmd list txn

For each transaction, the list subcommand returns the transaction ID, state, user name, number of messages or acknowledgements, and creation time. For example:

Listing all the transactions on the broker specified by: ------------------------- Host         Primary Port ------------------------- localhost    7676 --------------------------------------------------------------- Transaction ID  State    User name   # Msgs/   Creation time                                      # Acks --------------------------------------------------------------- 64248349708800  PREPARED guest      4/0      1/30/02 10:08:31 AM 64248371287808  PREPARED guest      0/4      1/30/02 10:09:55 AM Successfully listed transactions.

The command shows all transactions in the broker, both local and distributed. You can only commit or roll back transactions in the PREPARED state. You should only do so if you know that the transaction has been left in this state by a failure and is not in the process of being committed by the distributed transaction manager.

For example, if the broker's auto-rollback property is set to false (see Table 2-4), then you have to manually commit or roll back transactions found in a PREPARED state at broker startup.

The list subcommand also shows the number of messages that were produced in the transaction and the number of messages that were acknowledged in the transaction (#Msgs/#Acks). These messages will not be delivered and the acknowledgements will not be processed until the transaction is committed.

The query subcommand lets you see the same information plus a number of additional values: the Client ID, connection identification, and distributed transaction ID (XID). For example,

imqcmd query txn -n 64248349708800

produces the following output:

Querying the transaction where: ------------------------- Transaction ID ------------------------- 64248349708800 On the broker specified by: ------------------------- Host         Primary Port ------------------------- localhost    7676 Client ID Connection                 guest@192.18.116.219:62209->jms:62195 Creation time              1/30/02 10:08:31 AM Number of acknowledgements 0 Number of messages         4 State                      PREPARED Transaction ID             64248349708800 User name                  guest XID 6469706F6C7369646577696E6465723130313234313431313030373230 Successfully queried the transaction.

The commit and rollback subcommands can be used to commit or roll back a distributed transaction. As mentioned previously, only a transaction in the PREPARED state can be committed or rolled back. For example:

imqcmd commit txn -n 64248349708800

It is also possible to configure the broker to automatically roll back transactions in the PREPARED state at broker startup. See the imq.transaction.autorollback property in Table 2-4 for more information.