Sun Java System Message Queue 3.7 UR1 Administration Guide

Managing Connection Services

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

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 5–1. As shown in the table, each service is associated with the service type it uses (NORMAL for application clients or ADMIN for administration clients) and with an underlying transport protocol.

Table 5–1 Message Queue Connection Services


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)

You can use imqcmd subcommands to manage connection services as a whole or to manage a particular connection service. If the target of a subcommand is a particular service, use the -n option to specify one of the names listed in the Service Name column of Table 5–1.

Listing Connection Services

To list available connection services on a broker, use the list svc subcommand.

This is the syntax of the list svc subcommand:

imqcmd list svc [-b hostName:
portNumber]

The subcommand lists all connection services on the default broker or on a broker at the specified host and port.

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

imqcmd list svc -u 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.

This is the syntax for the query svc subcommand:

imqcmd query svc -n serviceName [-b 
hostName:portNumber]

The query svc subcommand displays information about the specified service running on the default broker or on a broker at the specified host and port.

For example:

imqcmd query svc -n jms -u admin

After prompting for the password, the 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 5–2 .

Table 5–2 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.

This is the syntax of the update subcommand:

imqcmd update svc -n serviceName [-b 
hostName:portNumber] 
         -o attribute=value [-o 
attribute=value1]…

This subcommand 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 Connection Properties.

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

imqcmd update svc -n jms -o “minThreads=20” -u admin

Displaying Connection Service Metrics

To display metrics information about a single service, use the metrics subcommand.

This is the syntax of the metrics subcommand:

imqcmd metrics svc -n serviceName [-b 
hostName:portNumber] [-m metricType
]
     [-int interval] [-msp numSamples]

The subcommand 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 connection 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 connection 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).

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

After prompting for the password, the 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 Connection Service Metrics.

Pausing and Resuming a Connection Service

To pause any service other than the admin service (which cannot be paused), use the pause svc and resume svc subcommands.

This is the syntax of the pause svc subcommand:

imqcmd pause svc -n serviceName [-b 
hostName:portNumber]

The subcommand pauses the specified service running on the default broker or on a broker at the specified host and port. For example, the following command pauses the httpjms service running on the default broker.

imqcmd pause svc -n httpjms -u 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 the resume svc subcommand.

This is the syntax of the resume svc subcommand:

imqcmd resume svc -n serviceName[-b 
hostName:portNumber]

The subcommand resumes the specified service running on the default broker or on a broker at the specified host and port.