Previous Contents Index Next |
Sun Java System Message Queue 3.5 SP1 Administration Guide

> ## 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
> - managing connection services

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

> - Message Queue messages are routed to their receivers or subscribers by way of broker destinations. You are responsible for creating these destinations on the broker.
> - Message Queue allocates and maintains resources for durable subscribers even when clients that have durable subscriptions become inactive. You use the Message Queue Command tool to get information about durable subscriptions and to destroy durable subscriptions or purge their messages in order to save Message Queue resources.
> - Message Queue 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 a number of these same tasks by using the Administration Console, the graphical interface to the Message Queue 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 imqcmd command syntax, provides a listing of subcommands, and summarizes imqcmd options. Subsequent sections explain how you use these commands to accomplish specific tasks.

> ### Syntax of the imqcmd Command

> The general syntax of the imqcmd command is as follows:

> imqcmd subcommand argument [options]
> imqcmd -h|H
> imqcmd -v

> Note that if you specify the -v, -h, or -H options, no 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: The subcommands are described in more detail in the task-oriented sections of this chapter.

> Table 6-1 imqcmd Subcommands

> Subcommand and Argument | Description
> --- | ---
> commit txn | Commits a transaction.
> compact dst | Compacts the built-in file-based data store for one or more destinations.
> create dst | Creates a destination.
> destroy dst | Destroys a destination.
> destroy dur | Destroys a durable subscription.
> list cxn | Lists connections for a broker.
> list dst | Lists destinations on a broker.
> list dur | Lists durable subscriptions to a topic.
> list svc | Lists services on a broker.
> list txn | Lists transactions on a broker.
> metrics bkr | Displays broker metrics.
> metrics dst | Displays destination metrics.
> metrics svc | Displays service metrics.
> pause bkr | Pauses all services on a broker.
> pause dst | Pauses one or more destinations on a broker.
> pause svc | Pauses a single service on a broker.
> 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 displays information on a broker.
> query cxn | Queries and displays information on a connection.
> query dst | Queries and displays information on a destination.
> query svc | Queries and displays information on a service.
> query txn | Queries and displays information on a transaction.
> reload cls | Reloads broker cluster configuration.
> restart bkr | Restarts the current running broker instance. Cannot be used to start a new broker instance.
> resume bkr | Resumes all services on a broker.
> resume dst | Resumes one or more paused destinations on a broker.
> resume svc | Resumes one service.
> rollback txn | Rolls back a transaction.
> shutdown bkr | Shuts down the broker instance. Can be subsequently started using the imqbrokerd command, but not the restart bkr subcommand of imqcmd.
> 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. See "Managing Durable Subscriptions".
> -d destinationName | Specifies the name of the topic. Used with the list dur and destroy dur subcommands. See "Managing Durable Subscriptions".
> -f | Performs action without user confirmation.
> -h | Displays usage help. Nothing else on the command line is executed.
> -H | Displays usage help, attribute list, and examples. Nothing else on the command line is executed.
> -int interval | Specifies the interval, in seconds, at which the metrics bkr, metrics dst, and metrics svc subcommands display metrics output.
> -javahome path | Specifies an alternate Java 2 compatible runtime to use (default is to use the runtime on the system or the runtime bundled with Message Queue).
> -m metricType | Specifies the type of metric information to display. Use this option with the metrics dst, metrics svc, or metrics bkr subcommand. The value of metricType depends on whether the metrics are generated for a destination, a service, or a broker.
> -msp numSamples | Specifies the number of metric samples the metrics bkr, metrics dst, and metrics svc subcommands display in their metrics output.
> -n argumentName | Specifies the name of the subcommand argument. Depending on the subcommand, this might be the name of a service, a physical destination, a durable subscription, a connection ID, or a transaction ID.
> -o attribute=value | Specifies the value of an attribute. Depending on the subcommand argument, this might be the attribute of a broker (see "Managing a Broker"), service (see "Managing Connection Services"), or destination (see "Managing Destinations").
> -p password | Specifies your (the administrator’s) password. If you omit this value, you will be prompted for it.
> -pst pauseType | Specifies whether producers, consumers, or both are paused when pausing a destination. See "Managing Destinations".
> -rtm timeout | Specifies the initial (retry) timeout period (in seconds) of an imqcmd subcommand. The timeout is the length of time the imqcmd subcommand will wait after making a request to the broker. Each subsequent retry of the subcommand will use a timeout value that is a multiple of the initial timeout period. Default: 10
> -rtr numRetries | Specifies the number of retries attempted after an imqcmd subcommand first times out. Default: 5
> -s | Silent mode. No output will be displayed.
> -secure | Specifies a secure administration connection to the broker using the ssladmin connection service (see "Step 4. Configuring and Running SSL-based Clients").
> -svn serviceName | Specifies the service for which connections are listed. See "Getting Connection Information".
> -t destType | Specifies the type of a destination: t (topic) or q (queue). See "Managing Destinations".
> -tmp | Displays temporary destinations. See Table 6-9.
> -u userName | Specifies your (the administrator’s) name. If you omit this value, you will be prompted for it.
> -v | Displays version information. Nothing else on the command line is executed.

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

> Note | To be able to use the -secure option, you must first set up and enable the ssladmin service on the target broker instance, as described in "Setting Up an SSL-based Service Over TCP/IP".

> ### Using imqcmd Commands

> 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. For more information, see "Authenticating Users".

> When you install Message Queue, a default flat-file user repository is installed. 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 instance without doing any additional work. For example, if you are just testing Message Queue, you can run the imqcmd utility using the 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 administrative users (see Chapter 8, "Managing Security"). In particular, you need to make entries in the Message Queue user repository (see "Using a Flat-File User Repository"). You also have the option of using an LDAP directory server for your user repository (see "Using an LDAP Server for a User Repository").

> ### Example imqcmd Usage

> The following examples illustrate the use of the imqcmd command:

> - To list the properties of the broker running on localhost at port 7676:

> imqcmd query bkr -u admin -p admin

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

> - To list the properties of the broker running on localhost at port 7676, with the initial timeout for the command set to 20 seconds and the number of retries (after timeout) set to 7.

> imqcmd query bkr -u admin -p admin -rtm 20 -rtr 7

> ##

> Managing a Broker

> The Command utility includes subcommands that you can use to perform the following broker management tasks:

> - Displaying Broker Information
> - Updating Broker Properties
> - Displaying Broker Metrics
> - Controlling the Broker’s State

> To manage connection services for a broker, see "Managing Connection Services". To manage broker destinations, see "Managing Destinations"

> Table 6-3 lists the imqcmd subcommands used to manage brokers. If no host name or port is specified, the default (localhost:7676)is assumed.

> Table 6-3 imqcmd Subcommands Used to Manage a Broker

> Subcommand Syntax | Description
> --- | ---
> metrics bkr [-b hostName:port] [-m metricType] [-int interval] [-msp numSamples] | 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 Displays metrics on messages and packets flowing into and out of the broker. (default metric type) rts Displays metrics on rate of flow of messages and packets into and out of the broker (per second). cxn Displays connections, virtual memory heap, and threads. Use the -int option to specify the interval (in seconds) at which to display the metrics. The default is 5 seconds. Use the -msp option to specify the number of samples displayed in the output. The default is an unlimited number (infinite).
> pause bkr [-b hostName:port] | Pauses the default broker or a broker at the specified host and port. See "Pausing and Resuming a Broker".
> 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 | Applies only to broker clusters. Forces all the brokers in a cluster to reload the imq.cluster.brokerlist property and update cluster information. See "Adding Brokers to a Cluster" for more information.
> restart bkr [-b hostName:port] | Shuts down 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.
> resume bkr [-b hostName:port] | Resumes the default broker or a broker at the specified host and port.
> shutdown bkr [-b hostName:port] | Shuts down the default broker or a broker at the specified host and port.
> update bkr [-b hostName:port] -o attribute=value [-o attribute=value1]… | Changes the specified attributes for the default broker or a broker at the specified host and port.

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

> ### Displaying Broker Information

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

> imqcmd query bkr -u admin -p admin

> This command produces output like the following:

> Version 3.5 SP1
> Instance Name imqbroker
> Primary Port 7676
> Current Number of Messages in System 0
> Current Total Message Bytes in System 0
> Max Number of Messages in System unlimited (-1)
> Max Total Message Bytes in System unlimited (-1)
> Max Message Size 70m
> Auto Create Queues true
> Auto Create Topics true
> Auto Created Queue Max Number of Active Consumers 1
> Auto Created Queue Max Number of Backup Consumers 0
> Cluster Broker List (active)
> Cluster Broker List (configured)
> Cluster Master Broker
> Cluster URL
> Log Level INFO
> Log Rollover Interval (seconds) 604800
> Log Rollover Size (bytes) unlimited (-1)

> ### Updating Broker Properties

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

> Table 6-4 Broker Properties Updated by imqcmd

> Property | Reference
> --- | ---
> imq.autocreate.queue | Table 2-10
> imq.autocreate.topic | Table 2-10
> imq.autocreate.queue.maxNumActiveConsumers | Table 2-10
> imq.autocreate.queue.maxNumBackupConsumers | Table 2-10
> imq.cluster.url | Table 5-3.
> imq.log.level | Table 2-9
> imq.log.file.rolloversecs | Table 2-9
> imq.log.file.rolloverbytes | Table 2-9
> imq.system.max_count | Table 2-4
> imq.system.max_size | Table 2-4
> imq.message.max_size | Table 2-4
> imq.portmapper.port | Table 2-3

> For example, the following command turns off the auto-creation of queue destinations:

> imqcmd update bkr -o “imq.autocreate.queue=false”
> -u admin -p admin

> ### 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 and Resuming a Broker

> - Pausing the broker. Pausing a broker suspends the broker’s connection service threads, which causes the broker to stop listening on the connection ports. As a result, the broker will no longer be able to accept new connections, receive messages, dispatch messages.

> However, pausing a broker does not suspend the admin connection service, letting you perform 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.

> Pausing a broker also does not suspend the cluster connection service. However message delivery within a cluster depend on the delivery functions performed by the different brokers in the cluster.

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

> imqcmd pause bkr -b myhost:1588 -u admin -p admin

> (You can also pause individual connection services—see "Pausing and Resuming a Connection Service"—as well as individual destinations—see "Pausing and Resuming Destinations")

> - 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 -u admin -p admin

> #### Shutting Down and Restarting a Broker

> - 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 -u admin -p admin

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

> imqcmd restart bkr -u admin -p admin

> ### Displaying Broker Metrics

> To display metrics information about a broker, use the metrics bkr subcommand. For example, to get the rate of message flow into and out of the broker at ten second intervals:

> imqcmd metrics bkr -m rts -int 10 -u admin -p admin

> This command produces output like the following:

> --------------------------------------------------------
> Msgs/sec Msg Bytes/sec Pkts/sec Pkt Bytes/sec
> In Out In Out In Out In Out
> --------------------------------------------------------
> 0 0 27 56 0 0 38 66
> 10 0 7365 56 10 10 7457 1132
> 0 0 27 56 0 0 38 73
> 0 10 27 7402 10 20 1400 8459
> 0 0 27 56 0 0 38 73

> For a more detailed description of the use of imqcmd to report broker metrics, see "Monitoring Tools".

> ##

> Managing Connection Services

> The Command utility includes subcommands that allow you to perform the following connection service management tasks:

> - Listing Connection Services
> - Displaying Connection Service Information
> - Updating Connection Service Properties
> - Displaying Connection Service Metrics
> - Pausing and Resuming a Connection Service

> For an overview of Message Queue connection services, see "Connection Services".

> Table 6-5 lists the imqcmd subcommands used to manage connection services. If no host name or port is specified, the default (localhost:7676)is assumed.

> Table 6-5 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] [-msp numSamples] | Displays 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 Displays metrics on messages and packets flowing into and out of the broker by way of the specified service. (default metric type) rts Displays metrics on rate of flow of messages and packets into and out of the broker (per second) by way of the specified service. cxn Displays connections, virtual memory heap, and threads. Use the -int option to specify the interval (in seconds) at which to display the metrics. The default is 5 seconds. Use the -msp option to specify the number of samples displayed in the output. The default is an unlimited number (infinite).
> 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.
> 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.
> 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 attribute=value [-o attribute=value1]… | 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-7.

> A broker supports connections from both application clients and administration clients. The connection services currently available from a Message Queue broker are shown in Table 6-6. 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 (application clients) or ADMIN (administration clients)—and an underlying transport layer.

> Table 6-6 Connection Services Supported by a Broker

> Service Name | Service Type | Protocol Type
> --- | --- | ---
> jms | NORMAL | tcp
> ssljms (Enterprise Edition) | NORMAL | tls (SSL-based security)
> httpjms (Enterprise Edition) | NORMAL | http
> httpsjms (Enterprise Edition) | NORMAL | https (SSL-based security)
> admin | ADMIN | tcp
> ssladmin (Enterprise Edition) | 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] -u admin -p admin

> 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 -u admin -p admin

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

> imqcmd list svc -u admin -p admin

> The command will output information like the following:

> ------------------------------------------------
> Service Name Port Number Service State
> ------------------------------------------------
> admin 41844 (dynamic) RUNNING
> httpjms - UNKNOWN
> httpsjms - UNKNOWN
> jms 41843 (dynamic) RUNNING
> ssladmin dynamic UNKNOWN
> ssljms dynamic UNKNOWN

> ### Displaying Connection Service Information

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

> imqcmd query svc -n jms -u admin -p admin

> This command produces output like the following:

> Service Name jms
> Service State RUNNING
> Port Number 60920 (dynamic)
> Current Number of Allocated Threads 0
> Current Number of Connections 0
> Min Number of Threads 10
> Max Number of Threads 1000

> ### Updating Connection Service Properties

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

> Table 6-7 Connection Service Properties Updated by imqcmd

> Property | Description
> --- | ---
> port | The port assigned to the service to be updated (does not apply to httpjms or httpsjms). A value of 0 means the port is dynamically allocated by the Port Mapper.
> 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”

> ### Displaying Connection Service Metrics

> To display metrics information about a single service, use the metrics subcommand. For example, to get cumulative totals for messages and packets handled by the jms connection service:

> imqcmd metrics svc -n jms -m ttl -u admin -p admin

> This command produces output like the following:

> -------------------------------------------------
> Msgs Msg Bytes Pkts Pkt Bytes
> In Out In Out In Out In Out
> -------------------------------------------------
> 164 100 120704 73600 282 383 135967 102127
> 657 100 483552 73600 775 876 498815 149948

> For a more detailed description of the use of imqcmd to report connection service metrics, see "Monitoring Tools".

> ### Pausing and Resuming a Connection 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 -u admin -p admin

> Pausing a service has the following effects:

> - The broker stops accepting new client connections on the paused service. If a Message Queue client attempts to open a new connection, it will get an exception.
> - All the existing connections on the paused service are kept alive, but the broker suspends all message processing on such connections until the service is resumed. (For example, if a client attempts to send a message, the send() method will block until the service is resumed.)
> - The message delivery state of any messages already received by the broker is maintained. (For example, transactions are not disrupted and message delivery will resume when the service is resumed.)

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

> imqcmd resume svc -n serviceName -u admin -p admin

> ##

> Getting Connection Information

> The Command utility includes subcommands that allow you to list and get information about connections.

> Table 6-8 lists the imqcmd subcommands that apply to connections. If no host name or port is specified, they are assumed to be localhost, 7676.

> Table 6-8 imqcmd Subcommands Used to Manage Connection Services

> Subcommand Syntax | Description
> --- | ---
> list cxn [-svn serviceName] [-b hostName:port] | Lists all connections of the specified service name on the default broker or on a broker at the specified host and port. If the service name is not specified, all connections are listed.
> query cxn -n connectionID [-b hostName:port] | Displays information about the specified connection on the default broker or on a broker at the specified host and port.

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

> imqcmd query cxn -n 421085509902214374 -u admin -p admin

> This command produces output like the following:

> Connection ID 421085509902214374
> User guest
> Service jms
> Producers 0
> Consumers 1
> Host 111.22.333.444
> Port 60953
> Client ID
> Client Platform

> ##

> Managing Destinations

> All Message Queue messages are routed to their consumer clients by way of queue and topic destinations created on a particular broker.

> The Command utility includes subcommands that allow you to perform the following destination management tasks:

> - Creating Destinations
> - Listing Destinations
> - Displaying Destination Information
> - Updating Destination Attributes
> - Displaying Destination Metrics
> - Pausing and Resuming Destinations
> - Purging Destinations
> - Destroying Destinations
> - Compacting Destinations

> 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 broker (localhost:7676).

> Table 6-9 imqcmd Subcommands Used to Manage Destinations

> Subcommand Syntax | Description
> --- | ---
> compact dst [-t destType -n destName] | Compacts the built-in file-based data store for the destination of the specified type and name. If no destination type and name are specified, then all destinations are compacted. Destinations must be paused before they can be compacted.
> create dst -t destType -n destName [-o attribute=value] [-o attribute=value1]… | 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 characters “_” and “$”. They cannot begin with the character string “mq.”
> destroy dst -t destType -n destName | Destroys the destination of the specified type and name.
> list dst [-t destType] [-tmp] | Lists all destinations of the specified type, with option of listing temporary destinations as well (see "Temporary Destinations"). The type argument can have two values: destType = q (queue) destType = t (topic) If the type is not specified, all destinations of all types are listed.
> metrics dst -t destType -n destName [-m metricType] [-int interval] [-msp numSamples] | Displays metrics information for the destination of the specified type and name. Use the -m option to specify the type of metric to display: ttl Displays metrics on messages and packets flowing into and out of the destination and residing in memory. (default metric type)) rts Displays metrics on rate of flow of messages and packets into and out of the destination (per second) and other rate information. con Displays consumer-related metrics. dsk Displays disk usage metrics. Use the -int option to specify the interval (in seconds) at which to display the metrics. The default is 5 seconds. Use the -msp option to specify the number of samples displayed in the output. The default is an unlimited number (infinite).
> pause dst [-t destType -n destName] [-pst pauseType] | Pauses the delivery of messages to consumers (-pst CONSUMERS), or from producers (-pst PRODUCERS), or both (-pst ALL), for the destination of the specified type and name. If no destination type and name are specified, then all destinations are paused. The default is ALL.
> purge dst -t destType -n destName | Purges messages at the destination of the specified type and name.
> query dst -t destType -n destName | Lists information about the destination of the specified type and name.
> resume dst [-t destType -n destName] | Resumes the delivery of messages for the paused destination of the specified type and name. If no destination type and name are specified, then all destinations are resumed.
> update dst -t destType -n destName -o attribute=value [-o attribute=value1]… | 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 the following:

> - The destination type: topic or queue
> - The destination name: must contain only alphanumeric characters (no spaces) and can begin with an alphabetic character or the characters “_” and “$”. The name cannot begin with the character string “mq.”
> - Any non-default values for the destination’s attributes

> Many of the destination attributes are used to manage broker memory resources and message flow. For example, you can specify the maximum number of producers allowed for a destination or the maximum number (or size) of messages allowed in a destination. These limits are similar to those that can be set on a broker-wide basis using broker configuration properties (see "Managing Memory Resources and Message Flow"). You can also specify how the broker responds when these limits are reached.

> There are also destination attributes that apply only to queue destinations. These are used to specify the number of active and backup consumers used in load-balanced delivery of messages to multiple consumers (see "Queue Destinations").

> Table 6-10 describes the attributes that apply for each type of destination. You can set the attribute values when you create or update a destination. For auto-created destinations you set default property values in the broker’s instance configuration file (see "Configuration Files").

> Table 6-10 Destination Attributes

> Destination Type | Attribute | Default Value | Description
> --- | --- | --- | ---
> Queue & Topic | maxNumMsgs1 | -1 (unlimited) | Specifies maximum number of unconsumed messages allowed in the destination.
> Queue & Topic | maxTotalMsgBytes1 | -1 (unlimited) | Specifies the maximum total amount of memory (in bytes) allowed for unconsumed messages in the destination.
> Queue & Topic | limitBehavior | REJECT_ NEWEST | Specifies how the broker responds when a memory-limit threshold is reached. Values are: FLOW_CONTROL — slows down producers REMOVE_OLDEST — throws out oldest messages REMOVE_LOW_PRIORITY — throws out lowest priority messages according to age of the messages (producing client receives no notification of message deletion) REJECT_NEWEST — rejects the newest messages (producing client gets exception for rejection of persistent messages, but no notification for rejection of non-persistent messages)
> Queue & Topic | maxBytesPerMsg | -1 (unlimited) | Specifies maximum size (in bytes) of any single message allowed in the destination (producing client gets exception for rejection of persistent messages, but no notification for rejection of non-persistent messages.
> Queue & Topic | maxNumProducers1 | -1 (unlimited) | Specifies maximum number of producers allowed for the destination. When this limit is reached, no new producers can be created.
> Queue only | maxNumActiveConsumers | 1 | Specifies the maximum number of consumers that can be active in load-balanced delivery from a queue destination. A value of -1 means an unlimited number. (Platform Edition limits this value to 2.)
> Queue only | maxNumBackupConsumers | 0 | Specifies the maximum number of backup consumers that can take the place of active consumers, if any fail during load-balanced delivery from a queue destination. A value of -1 means an unlimited number.
> Queue & Topic | consumerFlowLimit | Topics: 1000 Queues: 1000 | Specifies the maximum number of messages that will be delivered to a consumer in a single batch. In load-balanced queue delivery, this is the initial number of queued messages routed to active consumers before load-balancing commences (see "Queue Delivery to Multiple Consumers"). This limit can be overridden by a lower value specified for the destination’s consumers on their respective connections (see information on Connection Factory attributes in the Message Queue Java Client Developer’s Guide). A value of -1 means an unlimited number.
> Queue only | localDeliveryPreferred | false | Applies only to load-balanced queue delivery in broker clusters. Specifies that messages be delivered to remote consumers only if there are no consumers on the local broker. Requires that the destination not be restricted to local-only delivery (isLocalOnly = false).
> Queue & Topic | isLocalOnly | false | Applies only to broker clusters. Specifies that a destination is not replicated on other brokers, and is therefore limited to delivering messages only to local consumers (consumers connected to the broker on which the destination is created). This attribute cannot be updated once the destination has been created.
> 1. In a cluster environment, this property applies to each instance of the destination in the cluster, rather than collectively to all instances in the cluster.

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

> imqcmd create dst -n myQueue -t q -o “maxNumActiveConsumers=5”

> Note that a destination name must contain only alphanumeric characters (no spaces) and can begin with an alphabetic character or the characters “_” and “$”. It cannot begin with the character string “mq,” which is reserved for metrics topic destinations (see Table 2-8.

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

> imqcmd create dst -n myTopic -t t -o “maxBytesPerMsg=5000”

> ### Listing Destinations

> You can get information about a destination’s current attribute values, about the number of producers or consumers associated with a destination, and about messaging metrics, such as the number and size of messages in the destination.

> To find a destination about which you want to get information, you can first list all destinations on a particular broker using the list dst subcommand. For example, to get a list of all destinations on the broker running on myHost at port 4545, enter the following command:

> imqcmd list dst -b myHost:4545

> The list dst subcommand can optionally specify the type of destination to list or optionally include temporary destinations (using the -tmp option). Temporary destinations are created by clients, normally for the purpose of receiving replies to messages sent to other clients (see "Temporary Destinations").

> ### Displaying Destination Information

> To get information about a destination’s current attribute values, use the query dst subcommand, such as in the following command:

> imqcmd query dst -t q -n XQueue -u admin -p admin

> This command produces output like the following:

> ------------------------------------
> Destination Name Destination Type
> ------------------------------------
> XQueue Queue
> On the broker specified by:
> -------------------------
> Host Primary Port
> -------------------------
> localhost 7676
> Destination Name XQueue
> Destination Type Queue
> Destination State RUNNING
> Created Administratively true
> Current Number of Messages 0
> Current Total Message Bytes 0
> Current Number of Producers 0
> Current Number of Active Consumers 0
> Current Number of Backup Consumers 0
> Max Number of Messages unlimited (-1)
> Max Total Message Bytes unlimited (-1)
> Max Bytes per Message unlimited (-1)
> Max Number of Producers 100
> Max Number of Active Consumers 1
> Max Number of Backup Consumers 0
> Limit Behavior REJECT_NEWEST
> Consumer Flow Limit 100
> Is Local Destination false
> Local Delivery is Preferred false

> The output also shows the number of producers and consumers associated with the destination. For queue destinations, this would include both active and backup consumers.

> You can use the update dst subcommand to change the values of one or more attributes (see "Updating Destination Attributes").

> ### Updating Destination Attributes

> 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” -u admin -p admin

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

> ### Displaying Destination Metrics

> To get message metrics information about a destination, use the metrics dst subcommand, such as in the following command:

> imqcmd metrics dst -t q -n XQueue -m ttl -u admin -p admin

> This command produces output like the following:

> -----------------------------------------------------------------------------
> Msgs Msg Bytes Msg Count Total Msg Bytes (k) Largest
> In Out In Out Current Peak Avg Current Peak Avg Msg (k)
> -----------------------------------------------------------------------------
> 200 200 147200 147200 0 200 0 0 143 71 0
> 300 200 220800 147200 100 200 10 71 143 64 0
> 300 300 220800 220800 0 200 0 0 143 59 0

> For a more detailed description of the use of imqcmd to report destination metrics, see "Monitoring Tools".

> ### Pausing and Resuming Destinations

> You can pause a destination to control the delivery of messages from producers to the destination, or from the destination to consumers, or both. In particular, you can pause the flow of messages into a destination to help prevent destinations from being overwhelmed with messages when production of messages is much faster than consumption.

> To pause the delivery of messages to or from a destination, use the pause dst subcommand, as in the following command:

> imqcmd pause dst -n myQueue -t q -pst PRODUCERS -u admin -p admin

> imqcmd pause dst -n myTopic -t t -pst CONSUMERS -u admin -p admin

> In the case where you have paused a destination and want to resume delivery, enter the following command:

> imqcmd resume dst -n myQueue -t q

> In a multi-broker cluster, instances of the destination reside on each broker in the cluster. You must pause each of these destinations individually.

> ### 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, use the purge dst subcommand, as in the following commands:

> imqcmd purge dst -n myQueue -t q -u admin -p admin

> imqcmd purge dst -n myTopic -t t -u admin -p admin

> 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 messges option to purge stale messages; for example:

> imqbrokerd -reset messages -u admin -p admin

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

> In a multi-broker cluster, instances of the destination reside on each broker in the cluster. You must purge each of these destinations individually.

> ### Destroying Destinations

> To destroy a destination, use the destroy dst subcommand, as in the following command:

> imqcmd destroy dst -t q -n myQueue -u admin -p admin

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

> ### Compacting Destinations

> If you are using the built-in file-based data store (as opposed to a plugged-in JDBC-compliant data store) as the persistent store for messages, you can monitor disk utilization and compact the disk when necessary.

> The file-based message store is structured so that messages are stored in directories according to the destinations in which they are being held. In each destination’s directory, most messages are stored in one file consisting of variable-sized records, the variable-sized record file. (To alleviate fragmentation, messages whose size exceeds a configurable threshold will be stored in their own individual files.) As messages of varying sizes are persisted and then removed from the variable-sized record file, holes may develop in the file where free records are not being re-used.

> To manage unused free records, the Command utility includes subcommands for monitoring disk utilization per destination and for reclaiming free disk space when utilization drops.

> #### Monitoring a Destination’s Disk Utilization

> To monitor a destination’s disk utilization, use the following imqcmd subcommand:

> imqcmd metrics dst -t q -n myQueue -m dsk -u admin -p admin

> This command produces output like the following:

> --------------------------------------
> Reserved Used Utilization Ratio
> --------------------------------------
> 806400 804096 99
> 1793024 1793024 100
> 2544640 2518272 98

> The columns in the subcommand output have the following meaning:

> Table 6-11 Destination disk Utilization Metrics

> Metric | Description
> --- | ---
> Reserved | Disk space in bytes used by all records, including records that hold active messages and free records waiting to be reused
> Used | Disk space in bytes used by records that hold active messages
> Utilization Ratio | Quotient of used disk space divided by reserved disk space. The higher the ratio, the more the disk space is being used to hold active messages.

> #### Reclaiming Unused Destination Disk Space

> The disk utilization pattern depends on the characteristics of the messaging application that uses a particular destination. Depending on the relative flow of messages into and out of a destination, and the relative size of messages, the reserved disk space might grow over time.

> If the message producing rate is greater than the message consuming rate, then free records should generally be reused and the utilization ratio should be on the high side. However, if the message producing rate is similar to or smaller than the message consuming rate, you can expect that the utilization ratio will be low.

> In general, you want the reserved disk space to stabilize and the utilization to remain high. As a rule of thumb, if the system reaches a steady state in which the amount of reserved disk space stays pretty much constant and the utilization rate is high (above 75%), there is no need to reclaim the unused disk space. If the system reaches a steady state and the utilization rate is low (below 50%), you can compact the disk to reclaim the disk space occupied by free records.

> If the reserved disk space continues to increase over time, you should reconfigure the destination’s memory management by setting destination memory limit properties and limit behaviors (see Table 6-10).

> ##### To Reclaim Unused Destination Disk Space

> 1. Pause the destination.

> imqcmd pause dst -t q -n myQueue -u admin -p admin

> 2. Compact the disk.

> imqcmd compact dst -t q -n myQueue -u admin -p admin

> 3. Resume the destination.

> imqcmd resume dst -t q -n myQueue -u admin -p admin

> If destination type and name are not specified, then these operations are performed for all destinations.

> ##

> 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-12 imqcmd Subcommands Used to Manage Durable Subscriptions

> Subcommand | Description
> --- | ---
> list dur -d destName | Lists all durable subscriptions for the specified destination.
> destroy dur -n subscrName -c client_id | Destroys the specified durable subscription with the specified Client Identifier (see "Client Identifiers").
> purge dur -n subscrName -c client_id | Purges all messages for the specified durable subscription with 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 dur 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:

> Name Client ID Number of Durable Sub
> Messages State
> ----------------------------------------------------------------
> myDurable myClientID 1 INACTIVE

> You can use the information returned from the list dur subcommand 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 Message Queue transactions or distributed transactions managed by an XA resource manager (see "Local Transactions"). Each transaction has a Message Queue 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. Message Queue maintains the association of an Message Queue 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-13 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-13 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:

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

> 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 output like the following:

> 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

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

> Previous Contents Index Next

> Copyright 2003 Sun Microsystems, Inc. All rights reserved.