Sun Java System Message Queue 3.7 UR1 Administration Guide

Part III Reference

Chapter 13 Command Line Reference

This chapter provides reference information on the use of the Message Queue^TM command line administration utilities. It consists of the following sections:

Command Line Syntax

Message Queue command line utilities are shell commands. The name of the utility is a command and its subcommands or options are arguments passed to that command. There is no need for separate commands to start or quit the utility.

All the command line utilities share the following command syntax:

   utilityName [subcommand] [commandArgument] [ [-optionName [optionArgument]] … ]

where utilityName is one of the following:

imqbrokerd (Broker utility)
imqcmd (Command utility)
imqobjmgr (Object Manager utility)
imqdbmgr (Database Manager utility)
imqusermgr (User Manager utility)
imqsvcadmin (Service Administrator utility)
imqkeytool (Key Tool utility)

Subcommands and command-level arguments, if any, must precede all options and their arguments; the options themselves may appear in any order. All subcommands, command arguments, options, and option arguments are separated with spaces. If the value of an option argument contains a space, the entire value must be enclosed in quotation marks. (It is generally safest to enclose any attribute-value pair in quotation marks.)

The following command, which starts the default broker, is an example of a command line with no subcommand clause:

   imqbrokerd

Here is a fuller example:

   imqcmd  destroy dst  -t q  -n myQueue  -u admin  -f  -s

This command destroys a queue destination (destination type q) named myQueue. Authentication is performed on the user name admin; the command will prompt for a password. The command will be performed without prompting for confirmation (-f option) and in silent mode, without displaying any output (-s option).

Broker Utility

The Broker utility (imqbrokerd) starts a broker. Command line options override values in the broker configuration files, but only for the current broker session.

Table 13–1 shows the options to the imqbrokerd command and the configuration properties, if any, overridden by each option.

Table 13–1 Broker Utility Options


Option	Properties Overridden	Description
`-name` `instanceName`	`imq.instancename`	Instance name of broker Multiple broker instances running on the same host must have different instance names. Default value: `imqbroker`
`-port` `portNumber`	`imq.portmapper.port`	Port number for broker’s Port Mapper Message Queue clients use this port number to connect to the broker. Multiple broker instances running on the same host must have different Port Mapper port numbers. Default value: `7676`
`-cluster` `broker1` [ [ `,broker2` ] … ]	`imq.cluster.brokerlist`	Connect brokers into cluster [Applies only to broker clusters] The specified brokers are merged with the list in the `imq.cluster.brokerlist` property. Each broker argument has one of the forms `hostName:portNumber` `hostName` `:portNumber` If `hostName` is omitted, the default value is `localhost`; if `portNumber` is omitted, the default value is `7676`.
`-Dproperty=value`	Corresponding property in instance configuration file	Set configuration property See Chapter 14, Broker Properties Reference for information about broker configuration properties. Caution: Be careful to check the spelling and formatting of properties set with this option. Incorrect values will be ignored without notification or warning.
`-reset props`	None	Reset configuration properties Replaces the broker’s existing instance configuration file `config.properties` with an empty file; all properties assume their default values.
`-reset store`	None	Reset persistent data store Clears all persistent data from the data store (including persistent messages, durable subscriptions, and transaction information), allowing you to start the broker instance with a clean slate. To prevent the persistent store from being reset on subsequent restarts, restart the broker instance without the `-reset` option. To clear only persistent messages or durable subscriptions, use `-reset` `messages` or `-reset` `durables` instead.
`-reset messages`	None	Clear persistent messages from data store
`-reset durables`	None	Clear durable subscriptions from data store
`-backup` `fileName`	None	Back up configuration change record to file See Managing the Configuration Change Record for more information.
`-restore` `fileName`	None	Restore configuration change record from backup file The backup file must have been previously created using the `-backup` option. See Managing the Configuration Change Record for more information.
`-remove instance`	None	Remove broker instance [Requires user confirmation unless `-force` is also specified] Deletes the instance configuration file, log files, persistent store, and other files and directories associated with the instance.
`-password` `keyPassword`	`imq.keystore.password`	Password for SSL certificate key store [This option is deprecated and will eventually be removed. Either omit the password (so that the user will be prompted for it interactively) or use the `-passfile` option to specify a file containing the password. ]
`-dbuser` `userName`	`imq.persist.jdbc.user`	User name for JDBC-based persistent data store
`-dbpassword` `dbPassword`	`imq.persist.jdbc.password`	Password for JDBC-based persistent data store
`-ldappassword` `ldapPassword`	`imq.user_repository.ldap.password`	Password for LDAP user repository
`-passfile` `filePath`	`imq.passfile.enabledimq.passfile.dirpathimq.passfile.name`	Location of password file Sets the broker’s `imq.passfile.enabled` property to `true`, `imq.passfile.dirpath` to the path containing the password file, and `imq.passfile.name` to the file name itself. See Password Files for more information.
`-shared`	`imq.jms.threadpool_model`	Use shared thread pool model to implement `jms` connection service Execution threads will be shared among connections to increase the number of connections supported. Sets the broker’s `imq.jms.threadpool_model` property to `shared`.
`-javahome` `path`	None	Location of alternative Java runtime Default behavior: Use runtime installed on system or bundled with Message Queue.
`-vmargs` `arg1` [ [ `arg2` ] … ]	None	Pass arguments to Java virtual machine Arguments are separated with spaces. To pass more than one argument, or an argument containing a space, enclose the argument list in quotation marks. VM arguments can be passed only from the command line; there is no associated configuration property in the instance configuration file.
`-license` [ `licenseName` ]	None	License to load, if different from default for installed edition of Message Queue product: `pe`: Platform Edition with basic features `try`: Platform Edition with enterprise features (90-day trial) `unl`: Enterprise Edition If no license name is specified, all licenses installed on the system are listed.
`-upgrade-store-nobackup`	None	Automatically remove old data store on upgrade to Message Queue 3.5 or 3.5 SP`x` from an incompatible version See the Message Queue Installation Guide for more information.
`-force`	None	Perform action without user confirmation This option applies only to the `-remove` `instance` and `-upgrade-store-nobackup` options, which normally require confirmation.
`-loglevel` `level`	`imq.broker.log.level`	Logging level: `NONE` `ERROR` `WARNING` `INFO` Default value: `INFO`
`-metrics` `interval`	`imq.metrics.interval`	Logging interval for broker metrics, in seconds
`-tty`	`imq.log.console.output`	Log all messages to console Sets the broker’s `imq.log.console.output` property to `ALL`. If not specified, only error and warning messages will be logged.
`-s` \| `-silent`	`imq.log.console.output`	Silent mode (no logging to console) Sets the broker’s `imq.log.console.output` property to `NONE`.
`-version`	None	Display version information [Any other options specified on the command line are ignored. ]
`-h` \| `-help`	None	Display usage help

Command Utility

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

All imqcmd commands must include a subcommand (except those using the -v or -h option to display product version information or usage help). The possible subcommands are listed here and described in detail in the corresponding sections below. In all cases, if the subcommand accepts a broker address (-b option) and no host name or port number is specified, the values localhost and 7676 are assumed by default.

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

Broker Management

The Command utility cannot be used to start a broker; use the Broker utility (imqbrokerd) instead. Once the broker is started, you can use the imqcmd subcommands listed in Table 13–2 to manage and control it.

Table 13–2 Command Utility Subcommands for Broker Management


Syntax	Description
`shutdown bkr` [`-b` `hostName:portNumber`]	Shut down broker
`restart bkr` [`-b` `hostName:portNumber`]	Restart broker Shuts down the broker and then restarts it using the same options specified when it was originally started.
`pause bkr` [`-b` `hostName:portNumber`]	Pause broker See Pausing a Broker for more information.
`resume bkr` [`-b` `hostName:portNumber`]	Resume broker
`update bkr` [`-b` `hostName:portNumber`] `-o` `property1=value1` [ [`-o` `property2=value2`] … ]	Set broker properties See Chapter 14, Broker Properties Reference for information on broker properties.
`reload cls`	Reload cluster configuration [Applies only to broker clusters] Forces all persistent information to be brought up to date.
`query bkr` `-b` `hostName:portNumber`	List broker property values Also lists all running brokers connected to the specified broker in a cluster.
`metrics bkr` [`-b` `hostName:portNumber`] [`-m` `metricType`] [`-int` `interval`] [`-msp` `numSamples`]	Display broker metrics The `-m` option specifies the type of metrics to display: `ttl`: Messages and packets flowing into and out of the broker `rts`: Rate of flow of messages and packets into and out of the broker per second `cxn`: Connections, virtual memory heap, and threads Default value: `ttl`. The `-int` option specifies the interval, in seconds, at which to display metrics. Default value: `5`. The `-msp` option specifies the number of samples to display. Default value: Unlimited (infinite).

Connection Service Management

Table 13–3 lists the imqcmd subcommands for managing connection services.

Table 13–3 Command Utility Subcommands for Connection Service Management


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

Connection Management

Table 13–4 lists the imqcmd subcommands for managing connections.

Table 13–4 Command Utility Subcommands for Connection Service Management


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

Physical Destination Management

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

q: Queue destination

t: Topic destination

Table 13–5 Command Utility Subcommands for Physical Destination Management


Syntax	Description
`create dst` `-t` `destType` `-n` `destName` [`-o` `property1=value1`] [ [ `-o` `property2=value2`] … ]	Create physical destination [Cannot be performed in a broker cluster whose master broker is temporarily unavailable] The destination name `destName` may contain only alphanumeric characters (no spaces) and must begin with an alphabetic character or the underscore (`_`) or dollar sign (`$`) character. It may not begin with the characters `mq`.
`destroy dst` `-t` `destType` `-n` `destName`	Destroy physical destination This operation cannot be applied to a system-created destination, such as a dead message queue.
`pause dst` [`-t` `destType` `-n` `destName`] [`-pst` `pauseType`]	Pause message delivery for physical destination Pauses message delivery for the physical destination specified by the `-t` and `-n` options. If these options are not specified, all destinations are paused. The `-pst` option specifies the type of message delivery to be paused: `CONSUMERS`: Pause delivery to message consumers `PRODUCERS`: Pause delivery to message producers `ALL`: Pause all message delivery Default value: `ALL`
`resume dst` [`-t` `destType` `-ndestName`]	Resume message delivery for physical destination Resumes message delivery for the physical destination specified by the `-t` and `-n` options. If these options are not specified, all destinations are resumed.
`update dst` `-t` `destType` `-n` `destName` `-o` `property1=value1` [ [ `-o` `property2=value2`] … ]	Set physical destination properties See Chapter 15, Physical Destination Property Reference for information on physical destination properties.
`purge dst` `-t` `destType` `-n` `destName`	Purge all messages from physical destination
`compact dst` [`-t` `destType` `-n` `destName`]	Compact physical destination Compacts the file-based persistent data store for the physical destination specified by the `-t` and `-n` options. If these options are not specified, all destinations are compacted. A destination must be paused before it can be compacted.
`list dst` [`-t` `destType`] [`-tmp`]	List physical destinations Lists all physical destinations of the type specified by the `-t` option. If no destination type is specified, both queue and topic destinations are listed. If the `-tmp` option is specified, temporary destinations are listed as well.
`query dst` `-t` `destType` `-n` `destName`	List physical destination property values
`metrics dst` `-t` `destType` `-n` `destName` [`-m` `metricType`] [`-int` `interval`] [`-msp` `numSamples`]	Display physical destination metrics The `-m` option specifies the type of metrics to display: `ttl`: Messages and packets flowing into and out of the destination and residing in memory `rts`: Rate of flow of messages and packets into and out of the broker per second, along with other rate information `con`: Metrics related to message consumers `dsk`: Disk usage Default value: `ttl`. The `-int` option specifies the interval, in seconds, at which to display metrics. Default value: `5`. The `-msp` option specifies the number of samples to display. Default value: Unlimited (infinite).

Durable Subscription Management

Table 13–6 lists the imqcmd subcommands for managing durable subscriptions.

Table 13–6 Command Utility Subcommands for Durable Subscription Management


Syntax	Description
`destroy dur` `-c` `clientID` `-n` `subscriberName`	Destroy durable subscription [Cannot be performed in a broker cluster whose master broker is temporarily unavailable]
`purge dur` `-c` `clientID` `-n` `subscriberName`	Purge all messages for durable subscription
`list dur` `-d` `topicName`	List durable subscriptions for topic

Transaction Management

Table 13–7 lists the imqcmd subcommands for managing transactions.

Table 13–7 Command Utility Subcommands for Transaction Management


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

General Command Utility Options

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

Table 13–8 General Command Utility Options


Option	Description
`-secure`	Use secure connection to broker with `ssladmin` connection service
`-u` `userName`	User name for authentication If this option is omitted, the Command utility will prompt for it interactively.
`-p` `password`	Password for authentication [This option is deprecated and will eventually be removed. Either omit the password (so that the user will be prompted for it interactively) or use the `-passfile` option to specify a file containing the password. ]
`-passfile` `path`	Location of password file See Password Files for more information.
`-rtm` `timeoutInterval`	Initial timeout interval, in seconds This is the initial length of time that the Command utility will wait for a reply from the broker before retrying a request. Each subsequent retry will use a timeout interval that is a multiple of this initial interval. Default value: `10`.
`-rtr` `numRetries`	Number of retries to attempt after a broker request times out Default value: `5`.
`-javahome` `path`	Location of alternative Java runtime Default behavior: Use runtime installed on system or bundled with Message Queue.
`-f`	Perform action without user confirmation
`-s`	Silent mode (no output displayed)
`-v`	Display version information [Any other options specified on the command line are ignored. ] ^, [User name and password not needed]
`-h`	Display usage help^,
`-H`	Display expanded usage help, including attribute list and examples^,

Object Manager Utility

The Object Manager utility (imqobjmgr) creates and manages Message Queue administered objects. Table 13–9 lists the available subcommands.

Table 13–9 Object Manager Subcommands


Subcommand	Description
`add`	Add administered object to object store
`delete`	Delete administered object from object store
`list`	List administered objects in object store
`query`	Display administered object information
`update`	Modify administered object

Table 13–10 lists the options to the imqobjmgr command.

Table 13–10 Object Manager Options


Option	Description
`-l` `lookupName`	JNDI lookup name of administered object
`-j` `attribute=value`	Attributes of JNDI object store (see Object Stores)
`-t` `objectType`	Type of administered object: `q`: Queue destination `t`: Topic destination `cf`: Connection factory `qf`: Queue connection factory `tf`: Topic connection factory `xcf`: Connection factory for distributed transactions `xqf`: Queue connection factory for distributed transactions `xtf`: Topic connection factory for distributed transactions `e`: SOAP endpoint (see Message Queue Developer's Guide for Java Clients)
`-o` `attribute=value`	Attributes of administered object (see Administered Object Attributes and Chapter 16, Administered Object Attribute Reference)
`-r` `readOnlyState`	Is administered object read-only? If `true`, client cannot modify object’s attributes. Default value: `false`.
`-i` `fileName`	Name of command file containing all or part of subcommand clause
`-pre`	Preview results without performing command This option is useful for checking the values of default attributes.
`-javahome` `path`	Location of alternative Java runtime Default behavior: Use runtime installed on system or bundled with Message Queue.
`-f`	Perform action without user confirmation
`-s`	Silent mode (no output displayed)
`-v`	Display version information [Any other options specified on the command line are ignored. ]
`-h`	Display usage help
`-H`	Display expanded usage help, including attribute list and examples

Database Manager Utility

The Database Manager utility (imqdbmgr) sets up the database schema for a JDBC-based persistent data store. You can also use it to delete Message Queue database tables that have become corrupted or to change the data store. Table 13–11 lists the available subcommands.

Table 13–11 Database Manager Subcommands


Subcommand	Description
`create all`	Create new database and persistent store schema Used on embedded database systems. The broker property `imq.persist.jdbc.createdburl` must be specified.
`create tbl`	Create persistent store schema for existing database Used on external database systems.
`delete tbl`	Delete Message Queue database tables from current persistent store
`delete oldtbl`	Delete Message Queue database tables from earlier-version persistent store Used after the persistent store has been automatically migrated to the current version of Message Queue.
`recreate tbl`	Re-create persistent store schema Deletes all existing Message Queue database tables from the current persistent store and then re-creates the schema.
`reset lck`	Reset persistent store lock Resets the lock so that the persistent store database can be used by other processes.

Table 13–12 lists the options to the imqdbmgr command.

Table 13–12 Database Manager Options


Option	Description
`-b` `instanceName`	Instance name of broker
`-Dproperty=` `value`	Set broker configuration property See Persistence Properties for information about persistence-related broker configuration properties. Caution: Be careful to check the spelling and formatting of properties set with this option. Incorrect values will be ignored without notification or warning.
`-u` `name`	User name for authentication
`-p` `password`	Password for authentication [This option is deprecated and will eventually be removed. Either omit the password (so that the user will be prompted for it interactively) or use the `-passfile` option to specify a file containing the password. ]
`-passfile` `path`	Location of password file See Password Files for more information.
`-v`	Display version information [Any other options specified on the command line are ignored. ]
`-h`	Display usage help

User Manager Utility

The User Manager utility (imqusermgr) is used for populating or editing a flat-file user repository. The utility must be run on the same host where the broker is installed; if a broker-specific user repository does not yet exist, you must first start up the corresponding broker instance in order to create it. You will also need the appropriate permissions to write to the repository: on the Solaris or Linux platforms, this means you must be either the root user or the user who originally created the broker instance.

Table 13–13 lists the subcommands available with the imqusermgr command. In all cases, the -i option specifies the instance name of the broker to whose user repository the command applies; if not specified, the default name imqbroker is assumed.

Table 13–13 User Manager Subcommands


Syntax	Description
`add` [`-i` `instanceName`] `-u` `userName` `-p` `password` [`-g` `group`]	Add user and password to repository The optional `-g` option specifies a group to which to assign this user: `admin` `user` `anonymous`
`delete` [`-i` `instanceName`] `-u` `userName`	Delete user from repository
`update` [`-i` `instanceName`] `-u` `userName` `-p` `password` [`-a` `activeState`] `update` [`-i` `instanceName`] `-u` `userName` `-a` `activeState` [`-p` `password`]	Set user’s password or active state (or both) The `-a` option takes a boolean value specifying whether to make the user active (`true`) or inactive (`false`). Default value: `true`.
`list` [`-i` `instanceName`] [`-u` `userName`]	Display user information If no user name is specified, all users in the repository are listed.

In addition, the options listed in Table 13–14 can be applied to any subcommand of the imqusermgr command.

Table 13–14 General User Manager Options


Option	Description
`-f`	Perform action without user confirmation
`-s`	Silent mode (no output displayed)
`-v`	Display version information [Any other options specified on the command line are ignored. ]
`-h`	Display usage help

Service Administrator Utility

The Service Administrator utility (imqsvcadmin) installs a broker as a Windows service. Table 13–15 lists the available subcommands.

Table 13–15 Service Administrator Subcommands


Subcommand	Description
`install`	Install service
`remove`	Remove service
`query`	Display startup options Startup options can include whether the service is started manually or automatically, its location, the location of the Java runtime, and the values of arguments passed to the broker on startup (see Table 13–16).

Table 13–16 lists the options to the imqsvcadmin command.

Table 13–16 Service Administrator Options


Option	Description
`-javahome` `path`	Location of alternative Java runtime Default behavior: Use runtime installed on system or bundled with Message Queue.
`-jrehome` `path`	Location of alternative Java Runtime Environment (JRE)
`-vmargs` `arg1` [ [`arg2`] … ]	Additional arguments to pass to Java Virtual Machine (JVM) running broker service [These arguments can also be specified in the Start Parameters field under the General tab in the service’s Properties window (reached via the Services tool in the Windows Administrative Tools control panel). ] Example: `imqsvcadmin install -vmargs "-Xms16m -Xmx128m"`
`-args` `arg1` [ [`arg2`] … ]	Additional command line arguments to pass to broker service Example: `imqsvcadmin install -args "-passfile` `d:\\imqpassfile"` See Broker Utility for information about broker command line arguments.
`-h`	Display usage help [Any other options specified on the command line are ignored. ]

Any information you specify using the -javahome, -vmargs, and -args options is stored in the Windows registry under the keys JREHome, JVMArgs, and ServiceArgs in the path

   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\iMQ_Broker\Parameters

Key Tool Utility

The Key Tool utility (imqkeytool) generates a self-signed certificate for the broker, which can be used for the ssljms, ssladmin, or cluster connection service. The syntax is

   imqkeytool -broker

On UNIX systems, you may need to run the utility from the superuser (root) account.

Chapter 14 Broker Properties Reference

This chapter provides reference information about configuration properties for a message broker. It consists of the following sections:

Connection Properties

Table 14–1 lists the broker properties related to connection services.

Table 14–1 Broker Connection Properties


Property	Type	Default	Description
`imq.service.activelist`	String	`jms,admin`	List of connection services to be activated at broker startup, separated by commas
`imq.hostname`	String	All available IP addresses	Default host name or IP address for all connection services
`imq.portmapper.hostname`	String	None	Host name or IP address of Port Mapper If specified, overrides `imq.hostname`.
`imq.portmapper.port` [Can be used with `imqcmd` `update` `bkr` command]	Integer	`7676`	Port number of Port Mapper Note – If multiple broker instances are running on the same host, each must be assigned a unique Port Mapper port.
`imq.serviceName.protocolType.hostname` [`jms`, `ssljms`, `admin`, and `ssladmin` services only; see Appendix C, HTTP/HTTPS Support for information on configuring the `httpjms` and `httpsjms` services]	String	None	Host name or IP address for connection service If specified, overrides `imq.hostname` for the designated connection service.
`imq.serviceName.protocolType.port`	Integer	`0`	Port number for connection service A value of `0` specifies that the port number should be allocated dynamically by the Port Mapper.
`imq.portmapper.backlog`	Integer	`50`	Maximum number of pending Port Mapper requests in operating system backlog
`imq.serviceName.threadpool_model` [`jms` and `admin` services only]	String	`dedicated`	Threading model for thread pool management: `dedicated`: Two dedicated threads per connection, one for incoming and one for outgoing messages `shared`: Connections processed by shared thread when sending or receiving messages
			The dedicated model limits the number of connections that can be supported, but provides higher performance; the shared model increases the number of possible connections, but at the cost of lower performance because of the additional overhead needed for thread management.
`imq.serviceName.min_threads`	Integer	`jms`: `10ssljms`: `10httpjms`: `10` `httpsjms`: `10` `admin`: `4ssladmin`: `4`	Minimum number of threads maintained in connection service’s thread pool When the number of available threads exceeds this threshold, threads will be shut down as they become free until the minimum is reached. The default value varies by connection service, as shown.
`imq.serviceName.max_threads`	Integer	`jms`: `1000ssljms`: `500httpjms`: `500httpsjms` : `500admin`: `10ssladmin`: `10`	Number of threads beyond which no new threads are added to the thread pool for use by the named connection service Must be greater than `0` and greater than the value of `imq.serviceName.min_threads`. The default value varies by connection service, as shown.
`imq.shared.connectionMonitor_limit` [Shared threading model only]	Integer	Solaris: `512`Linux: `512`Windows: `64`	Maximum number of connections monitored by a distributor thread The system allocates enough distributor threads to monitor all connections. The smaller the value of this property, the faster threads can be assigned to active connections. A value of `-1` denotes an unlimited number of connections per thread. The default value varies by operating-system platform, as shown.
`imq.ping.interval`	Integer	`120`	Interval, in seconds, at which to test connection between client and broker A value of `0` or `-1` disables periodic testing of the connection.

Routing Properties

Table 14–2 lists the broker properties related to routing services. Properties that configure the automatic creation of destinations are listed in Table 14–3.

Table 14–2 Broker Routing Properties


Property	Type	Default	Description
`imq.system.max_count` [Can be used with `imqcmd` `update` `bkr` command]	Integer	`-1`	Maximum number of messages held by broker A value of `-1` denotes an unlimited message count.
`imq.system.max_size`	String	`-1`	Maximum total size of messages held by broker The value may be expressed in bytes, kilobytes, or megabytes, using the following suffixes: `b`: Bytes `k`: Kilobytes (1024 bytes) `m`: Megabytes (1024 × 1024 = 1,048,576 bytes)
			An unsuffixed value is expressed in bytes; a value of `-1` denotes an unlimited message capacity.
			Examples: `1600`: 1600 bytes `1600b`: 1600 bytes `16k`: 16 kilobytes (= 16,384 bytes) `16m`: 16 megabytes (= 16,777,216 bytes) `-1`: No limit
`imq.message.max_size`	String	`70m`	Maximum size of a single message body The syntax is the same as for `imq.system.max_size` (see above).
`imq.message.expiration.interval`	Integer	`60`	Interval, in seconds, at which expired messages are reclaimed
`imq.resourceState.threshold`	Integer	`green`: `0yellow`: `80orange`: `90red`: `98`	Percent utilization at which memory resource state is triggered (where `resourceState` is `green`, `yellow`, `orange`, or `red`)
`imq.resourceState.count`	Integer	`green`: `5000yellow`: `500orange`: `50red`: `0`	Maximum number of incoming messages allowed in a batch before checking whether memory resource state threshold has been reached (where `resourceState` is `green`, `yellow`, `orange` , or `red`) This limit throttles back message producers as system memory becomes increasingly scarce.
`imq.destination.DMQ.truncateBody`	Boolean	`false`	Remove message body before storing in dead message queue? If `true`, only the message header and property data will be saved.
`imq.transaction.autorollback`	Boolean	`false`	Automatically roll back distributed transactions left in prepared state at broker startup? If `false`, transactions must be manually committed or rolled back using the Command utility (`imqcmd`).

Table 14–3 Broker Properties for Auto-Created Destinations


Property	Type	Default	Description
`imq.autocreate.queue` [Can be used with `imqcmd` `update` `bkr` command] ^, [Queue destinations only]	Boolean	`true`	Allow auto-creation of queue destinations?
`imq.autocreate.topic` [Topic destinations only]	Boolean	`true`	Allow auto-creation of topic destinations?
`imq.autocreate.destination.maxNumMsgs`	Integer	`100000`	Maximum number of unconsumed messages A value of `-1` denotes an unlimited number of messages.
`imq.autocreate.destination.maxBytesPerMsg`	String	`10k`	Maximum size, in bytes, of any single message The value may be expressed in bytes, kilobytes, or megabytes, using the following suffixes: `b`: Bytes `k`: Kilobytes (1024 bytes) `m`: Megabytes (1024 × 1024 = 1,048,576 bytes)
			An unsuffixed value is expressed in bytes; a value of `-1` denotes an unlimited message size.
			Examples: `1600`: 1600 bytes `1600b`: 1600 bytes `16k`: 16 kilobytes (= 16,384 bytes) `16m`: 16 megabytes (= 16,777,216 bytes) `-1`: No limit
`imq.autocreate.destination.maxTotalMsgBytes`	String	`10m`	Maximum total memory, in bytes, for unconsumed messages The syntax is the same as for `imq.autocreate.destination.maxBytesPerMsg` (see above).
`imq.autocreate.destination.limitBehavior`	String	`REJECT_NEWEST`	Broker behavior when memory-limit threshold reached: `FLOW_CONTROL`: Slow down producers `REMOVE_OLDEST`: Throw out oldest messages `REMOVE_LOW_PRIORITY`: Throw out lowest-priority messages according to age; no notification to producing client `REJECT_NEWEST`: Reject newest messages; notify producing client with an exception only if message is persistent
			If the value is `REMOVE_OLDEST` or `REMOVE_LOW_PRIORITY` and the `imq.autocreate.destination.useDMQ` property is `true`, excess messages are moved to the dead message queue.
`imq.autocreate.destination.maxNumProducers`	Integer	`100`	Maximum number of message producers for destination When this limit is reached, no new producers can be created. A value of `-1` denotes an unlimited number of producers.
`imq.autocreate.queue.maxNumActiveConsumers`	Integer	`1`	Maximum number of active message consumers in load-balanced delivery from queue destination A value of `-1` denotes an unlimited number of consumers.
`imq.autocreate.queue.maxNumBackupConsumers`	Integer	`0`	Maximum number of backup message consumers in load-balanced delivery from queue destination A value of `-1` denotes an unlimited number of consumers.
`imq.autocreate.queue.consumerFlowLimit`	Integer	`1000`	Maximum number of messages delivered to queue 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 begins. A destination consumer can override this limit by specifying a lower value on a connection. A value of `-1` denotes an unlimited number of messages.
`imq.autocreate.topic.consumerFlowLimit`	Integer	`1000`	Maximum number of messages delivered to topic consumer in a single batch A value of `-1` denotes an unlimited number of consumers.
`imq.autocreate.destination.isLocalOnly`	Boolean	`false`	Local delivery only? This property applies only to destinations in broker clusters, and cannot be changed once the destination has been created. If `true`, the destination is not replicated on other brokers and is limited to delivering messages only to local consumers (those connected to the broker on which the destination is created).
`imq.autocreate.queue.localDeliveryPreferred`	Boolean	`false`	Local delivery preferred? This property applies only to load-balanced queue delivery in broker clusters. If `true`, messages will be delivered to remote consumers only if there are no consumers on the local broker; the destination must not be restricted to local-only delivery (`imq.autocreate.destination.isLocalOnly` must be `false`).
`imq.autocreate.destination.useDMQ`	Boolean	`true`	Send dead messages to dead message queue? If `false`, dead messages will simply be discarded.

Persistence Properties

Message Queue^TM supports both file-based and JDBC-based models for persistent data storage. The broker property imq.persist.store (Table 14–4) specifies which model to use. The following sections describe the broker configuration properties for the two models.

Table 14–4 Global Broker Persistence Property


Property	Type	Default	Description
`imq.persist.store`	String	`file`	Model for persistent data storage: `file`: File-based persistence `jdbc`: JDBC-based persistence

File-Based Persistence

Table 14–5 lists the broker properties related to file-based persistence.

Table 14–5 Broker Properties for File-Based Persistence


Property	Type	Default	Description
`imq.persist.file.message.max_record_size`	String	`1m`	Maximum-size message to add to message storage file Any message exceeding this size will be stored in a separate file of its own. The value may be expressed in bytes, kilobytes, or megabytes, using the following suffixes: `b`: Bytes `k`: Kilobytes (1024 bytes) `m`: Megabytes (1024 × 1024 = 1,048,576 bytes) An unsuffixed value is expressed in bytes. Examples: `1600`: 1600 bytes `1600b`: 1600 bytes `16k`: 16 kilobytes (= 16,384 bytes) `16m`: 16 megabytes (= 16,777,216 bytes)
`imq.persist.file.destination.message.filepool.limit`	Integer	`100`	Maximum number of free files available for reuse in destination file pool Free files in excess of this limit will be deleted. The broker will create and delete additional files in excess of the limit as needed. The higher the limit, the faster the broker can process persistent data.
`imq.persist.file.message.filepool.cleanratio`	Integer	`0`	Percentage of files in free file pools to be maintained in a clean (empty) state The higher this value, the less disk space is required for the file pool, but the more overhead is needed to clean files during operation.
`imq.persist.file.message.cleanup`	Boolean	`false`	Clean up files in free file pools on shutdown? Setting this property to `true` saves disk space for the file store, but slows broker shutdown.
`imq.persist.file.sync.enabled`	Boolean	`false`	Synchronize in-memory state with physical storage device? Setting this property to `true` eliminates data loss due to system crashes, but at a cost in performance. Note – If running Sun Cluster and the Sun Cluster Data Service for Message Queue, set this property to `true` for brokers on all cluster nodes.

JDBC-Based Persistence

Table 14–6 lists the broker properties related to JDBC-based persistence. Examples shown are for the PointBase^® family of database products from DataMirror Mobile Solutions, Inc.

Table 14–6 Broker Properties for JDBC-Based Persistence


Property	Example	Description
`imq.persist.jdbc.brokerid`	Not required for PointBase embedded version	(Optional) Broker instance identifier Must be an alphanumeric string of no more than`n` - 12 characters, where `n` is the maximum table name length allowed by the database. This identifier is appended to database table names to make them unique in the case where more than one broker instance is using the same database as a persistent data store. It is usually unnecessary for an embedded database, which stores data for only one broker instance.
`imq.persist.jdbc.driver`	`com.pointbase.jdbc.jdbcUniversalDriver`	Java class name of JDBC driver for connecting to database
`imq.persist.jdbc.opendburl`	`jdbc:pointbase:embedded:dbName;` `database.home=` `.../instances/instanceName/dbstore`	URL for opening connection to existing database
`imq.persist.jdbc.createdburl`	`jdbc:pointbase:embedded:dbName;` `new,database.home=` `.../instances/instanceName/dbstore`	(Optional) URL for creating new database Needed only if the database will be created using the Message Queue Database Manager utility (`imqdbmgr`).
`imq.persist.jdbc.closedburl`	Not required for PointBase	(Optional) URL for closing database connection
`imq.persist.jdbc.user`		(Optional) User name for opening database connection, if required For security reasons, the value can instead be specified using command line options `imqbrokerd -dbuser` and `imqdbmgr -u`.
`imq.persist.jdbc.needpassword`		(Optional) Does database require a password for broker access? If `true`, the `imqbrokerd` and `imqdbmgr` commands will prompt for a password, unless you use the `-passfile` option to specify a password file containing it.
`imq.persist.jdbc.password` [Should be used only in password files]		(Optional) Password for opening database connection
`imq.persist.jdbc.table.IMQSV35`	`CREATE TABLE ${name}` `(STOREVERSION INTEGER NOT NULL,` `BROKERID VARCHAR(100))`	SQL command to create version table
`imq.persist.jdbc.table.IMQCCREC35`	`CREATE TABLE ${name}` `(RECORDTIME BIGINT NOT NULL,` `RECORD BLOB(10k))`	SQL command to create configuration change record table
`imq.persist.jdbc.table.IMQDEST35`	`CREATE TABLE ${name}` `(DID VARCHAR(100) NOT NULL,` `DEST BLOB(10k),` `primaryKey(DID))`	SQL command to create destination table
`imq.persist.jdbc.table.IMQINT35`	`CREATE TABLE ${name}` `(CUID BIGINT NOT NULL,` `INTEREST BLOB(10k),` `primaryKey(CUID))`	SQL command to create interest table
`imq.persist.jdbc.table.IMQMSG35`	`CREATE TABLE ${name}` `(MID VARCHAR(100) NOT NULL,` `DID VARCHAR(100),` `MSGSIZE BIGINT,` `MSG BLOB(1m),` `primaryKey(MID))`	SQL command to create message table The default maximum length for the `MSG` column is 1 megabyte (`1m`). If you expect to have messages larger than this, set the length accordingly. If the tables have already been created, you must re-create them to change the maximum message length.
`imq.persist.jdbc.table.IMQPROPS35`	`CREATE TABLE ${name}` `(PROPNAME VARCHAR(100) NOT NULL,` `PROPVALUE BLOB(10k),` `primaryKey(PROPNAME))`	SQL command to create property table
`imq.persist.jdbc.table.IMQILIST35`	`CREATE TABLE ${name}` `(MID VARCHAR(100) NOT NULL,` `CUID BIGINT,` `DID VARCHAR(100),` `STATE INTEGER,` `primaryKey(MID, CUID))`	SQL command to create interest state table
`imq.persist.jdbc.table.IMQTXN35`	`CREATE TABLE ${name}` `(TUID BIGINT NOT NULL,` `STATE INTEGER,` `TSTATEOBJ BLOB(10K),` `primaryKey(TUID))`	SQL command to create transaction table
`imq.persist.jdbc.table.IMQTACK35`	`CREATE TABLE ${name}` `(TUID BIGINT NOT NULL,` `TXNACK BLOB(10k))`	SQL command to create transaction acknowledgment table

Security Properties

Table 14–7 lists the broker properties related to security services.

Table 14–7 Broker Security Properties


Property	Type	Default	Description
`imq.accesscontrol.enabled`	Boolean	`true`	Use access control? If `true`, the system will check the access control properties file to verify that an authenticated user is authorized to use a connection service or to perform specific operations with respect to specific destinations.
`imq.serviceName.accesscontrol.enabled`	Boolean	None	Use access control for connection service? If specified, overrides `imq.accesscontrol.enabled` for the designated connection service. If `true`, the system will check the access control properties file to verify that an authenticated user is authorized to use the designated connection service or to perform specific operations with respect to specific destinations.
`imq.accesscontrol.file.filename`	String	`accesscontrol.properties`	Name of access control properties file The file name specifies a path relative to the access control directory (see Appendix A, Platform-Specific Locations of Message Queue^TM Data).
`imq.serviceName.accesscontrol.file.filename`	String	None	Name of access control properties file for connection service If specified, overrides `imq.accesscontrol.file.filename` for the designated connection service. The file name specifies a path relative to the access control directory (see Appendix A, Platform-Specific Locations of Message Queue^TM Data).
`imq.authentication.type`	String	`digest`	Password encoding method: `basic`: Base-64 `digest`: MD5
`imq.serviceName.authentication.type`	String	None	Password encoding method for connection service: `basic`: Base-64 `digest`: MD5 If specified, overrides `imq.authentication.type` for the designated connection service.
`imq.authentication.basic.user_repository`	String	`file`	Type of user repository for base-64 authentication: `file`: File-based `ldap`: LDAP
`imq.authentication.client.response.timeout`	Integer	`180`	Interval, in seconds, to wait for client response to authentication requests
`imq.passfile.enabled`	Boolean	`false`	Obtain passwords from password file?
`imq.passfile.dirpath`	String	See Appendix A, Platform-Specific Locations of Message Queue^TM Data	Path to directory containing password file
`imq.passfile.name`	String	`passfile`	Name of password file
`imq.imqcmd.password`	String	None	Password for administrative user The Command utility (`imqcmd`) uses this password to authenticate the user before executing a command.
`imq.user_repository.ldap.server`	String	None	Host name and port number for LDAP server The value is of the form `hostName:port` where `hostName` is the fully qualified DNS name of the host running the LDAP server and `port` is the port number used by the server.
			To specify a list of failover servers, use the following syntax: `host1:port1` `ldap://host2:` `port2` `ldap://host3` `:port3` …
			Entries in the list are separated by spaces. Note that each failover server address is prefixed with `ldap://`. Use this format even if you use SSL and have set the property `imq.user_repository.ldap.ssl.enabled` to `true`. You need not specify `ldaps` in the address.
`imq.user_repository.ldap.principal`	String	None	Distinguished name for binding to LDAP user repository Not needed if the LDAP server allows anonymous searches.
`imq.user_repository.ldap.password` [Should be used only in password files]	String	None	Password for binding to LDAP user repository Not needed if the LDAP server allows anonymous searches.
`imq.user_repository.ldap.propertyName`	To come	To come	To come
`imq.user_repository.ldap.base`	String	None	Directory base for LDAP user entries
`imq.user_repository.ldap.uidattr`	String	None	Provider-specific attribute identifier for LDAP user name
`imq.user_repository.ldap.usrfilter`	String	None	(Optional) JNDI filter for LDAP user searches
`imq.user_repository.ldap.grpsearch`	Boolean	`false`	Enable LDAP group searches? Note – Message Queue does not support nested groups.
`imq.user_repository.ldap.grpbase`	String	None	Directory base for LDAP group entries
`imq.user_repository.ldap.gidattr`	String	None	Provider-specific attribute identifier for LDAP group name
`imq.user_repository.ldap.memattr`	String	None	Provider-specific attribute identifier for user names in LDAP group
`imq.user_repository.ldap.grpfilter`	String	None	(Optional) JNDI filter for LDAP group searches
`imq.user_repository.ldap.timeout`	Integer	`280`	Time limit for LDAP searches, in seconds
`imq.user_repository.ldap.ssl.enabled`	Boolean	`false`	Use SSL when communicating with LDAP server?
`imq.keystore.file.dirpath`	String	See Appendix A, Platform-Specific Locations of Message Queue^TM Data	Path to directory containing key store file
`imq.keystore.file.name`	String	`keystore`	Name of key store file
`imq.keystore.password`	String	None	Password for key store file
`imq.audit.enabled` [Message Queue Enterprise Edition only]	Boolean	`false`	Start audit logging to broker log file?

Monitoring Properties

Table 14–8 lists the broker properties related to monitoring services.

Table 14–8 Broker Monitoring Properties


Property	Type	Default	Description
`imq.log.level` [Can be used with `imqcmd` `update` `bkr` command]	String	`INFO`	Logging level Specifies the categories of logging information that can be written to an output channel. Possible values, from high to low: `ERROR` `WARNING` `INFO` Each level includes those above it (for example, `WARNING` includes `ERROR`).
`imq.destination.logDeadMsgs`	Boolean	`false`	Log information about dead messages? If `true`, the following events will be logged: A destination is full, having reached its maximum size or message count. The broker discards a message for a reason other than an administrative command or delivery acknowledgment. The broker moves a message to the dead message queue.
`imq.log.console.stream`	String	`ERR`	Destination for console output: `OUT`: `stdout` `ERR`: `stderr`
`imq.log.console.output`	String	`ERROR\|WARNING`	Categories of logging information to write to console: `NONE` `ERROR` `WARNING` `INFO` `ALL` The `ERROR`, `WARNING`, and `INFO` categories do not include those above them, so each must be specified explicitly if desired. Any combination of categories can be specified, separated by vertical bars (`\|`).
`imq.log.file.dirpath`	String	See Appendix A, Platform-Specific Locations of Message Queue^TM Data	Path to directory containing log file
`imq.log.file.filename`	String	`log.txt`	Name of log file
`imq.log.file.output`	String	`ALL`	Categories of logging information to write to log file: `NONE` `ERROR` `WARNING` `INFO` `ALL` The `ERROR`, `WARNING`, and `INFO` categories do not include those above them, so each must be specified explicitly if desired. Any combination of categories can be specified, separated by vertical bars (`\|`).
`imq.log.file.rolloverbytes`	Integer	`-1`	File length, in bytes, at which output rolls over to a new log file A value of `-1` denotes an unlimited number of bytes (no rollover based on file length).
`imq.log.file.rolloversecs`	Integer	`604800` (one week)	Age of file, in seconds, at which output rolls over to a new log file A value of `-1` denotes an unlimited number of seconds (no rollover based on file age).
`imq.log.syslog.output` [Solaris platform only]	String	`ERROR`	Categories of logging information to write to `syslogd(1M)`: `NONE` `ERROR` `WARNING` `INFO` `ALL` The `ERROR`, `WARNING`, and `INFO` categories do not include those above them, so each must be specified explicitly if desired. Any combination of categories can be specified, separated by vertical bars (`\|`).
`imq.log.syslog.facility`	String	`LOG_DAEMON`	`syslog` facility for logging messages Possible values mirror those listed on the `syslog(3C)` man page. Appropriate values for use with Message Queue include: `LOG_USER` `LOG_DAEMON` `LOG_LOCAL0` `LOG_LOCAL1` `LOG_LOCAL2` `LOG_LOCAL3` `LOG_LOCAL4` `LOG_LOCAL5` `LOG_LOCAL6` `LOG_LOCAL7`
`imq.log.syslog.identity`	String	`imqbrokerd_${imq.instanceName}`	Identity string to be prefixed to all messages logged to `syslog`
`imq.log.syslog.logpid`	Boolean	`true`	Log broker process ID with message?
`imq.log.syslog.logconsole`	Boolean	`false`	Write messages to system console if they cannot be sent to `syslog`?
`imq.log.timezone`	String	Local time zone	Time zone for log time stamps Possible values are the same as those used by the method `java.util.TimeZone.getTimeZone`. Examples: `GMT` `GMT-8:00` `America/LosAngeles` `Europe/Rome` `Asia/Tokyo`
`imq.metrics.enabled`	Boolean	`true`	Enable writing of metrics information to Logger? Does not affect the production of metrics messages (controlled by `imq.metrics.topic.enabled`).
`imq.metrics.interval`	Integer	`-1`	Time interval, in seconds, at which to write metrics information to Logger Does not affect the time interval for production of metrics messages (controlled by `imq.metrics.topic.interval`). A value of `-1` denotes an indefinite interval (never write metrics information to Logger).
`imq.metrics.topic.enabled`	Boolean	`true`	Enable production of metrics messages to metric topic destinations? If `false`, an attempt to subscribe to a metric topic destination will throw a client-side exception.
`imq.metrics.topic.interval`	Integer	`60`	Time interval, in seconds, at which to produce metrics messages to metric topic destinations
`imq.metrics.topic.persist`	Boolean	`false`	Are metrics messages sent to metric topic destinations persistent?
`imq.metrics.topic.timetolive`	Integer	`300`	Lifetime, in seconds, of metrics messages sent to metric topic destinations

Cluster Configuration Properties

Table 14–9 lists the configuration properties related to broker clusters.

Table 14–9 Broker Properties for Cluster Configuration


Property	Type	Default	Description
`imq.cluster.brokerlist` [Must have the same value for all brokers in a cluster]	String	None	List of broker addresses The list consists of one or more addresses, separated by commas. Each address specifies the host name and Port Mapper port number of a broker in the cluster, in the form `hostName:portNumber`. Example: `host1:3000,host2:8000,ctrlhost`
`imq.cluster.hostname` [Can be specified independently for each broker in a cluster]	String	None	Host name or IP address for `cluster` connection service If specified, overrides `imq.hostname` (see Table 14–1) for the `cluster` connection service.
`imq.cluster.port`	Integer	`0`	Port number for `cluster` connection service A value of `0` specifies that the port number should be allocated dynamically by the Port Mapper.
`imq.cluster.transport`	String	`tcp`	Network transport protocol for `cluster` connection service For secure, encrypted message delivery between brokers, set this property to `ssl`.
`imq.cluster.url`^, [Can be used with `imqcmd update bkr` command]	String	None	URL of `cluster` configuration file, if any Examples: `http://webserver/imq/cluster.properties` (for a file on a Web server) `file:/net/mfsserver/imq/cluster.properties` (for a file on a shared drive)
`imq.cluster.masterbroker`	String	None	Host name and port number of cluster’s master broker, if any The value has the form `hostName:portNumber`, where `hostName` is the host name of the master broker and `portNumber` is its Port Mapper port number. Example: `ctrlhost:7676`

Alphabetical List of Broker Properties

Alphabetical List of Broker Properties is an alphabetical list of broker configuration properties, with cross-references to the relevant tables in this chapter.

Table 14–10 Alphabetical List of Broker Properties


Property	Table
`imq.accesscontrol.enabled`	Table 14–7
`imq.accesscontrol.file.filename`	Table 14–7
`imq.audit.enabled`	Table 14–7
`imq.authentication.basic.user_repository`	Table 14–7
`imq.authentication.client.response.timeout`	Table 14–7
`imq.authentication.type`	Table 14–7
`imq.autocreate.destination.isLocalOnly`	Table 14–3
`imq.autocreate.destination.limitBehavior`	Table 14–3
`imq.autocreate.destination.maxBytesPerMsg`	Table 14–3
`imq.autocreate.destination.maxNumMsgs`	Table 14–3
`imq.autocreate.destination.maxNumProducers`	Table 14–3
`imq.autocreate.destination.maxTotalMsgBytes`	Table 14–3
`imq.autocreate.destination.useDMQ`	Table 14–3
`imq.autocreate.queue`	Table 14–3
`imq.autocreate.queue.consumerFlowLimit`	Table 14–3
`imq.autocreate.queue.localDeliveryPreferred`	Table 14–3
`imq.autocreate.queue.maxNumActiveConsumers`	Table 14–3
`imq.autocreate.queue.maxNumBackupConsumers`	Table 14–3
`imq.autocreate.topic`	Table 14–3
`imq.autocreate.topic.consumerFlowLimit`	Table 14–3
`imq.cluster.brokerlist`	Table 14–9
`imq.cluster.hostname`	Table 14–9
`imq.cluster.masterbroker`	Table 14–9
`imq.cluster.port`	Table 14–9
`imq.cluster.transport`	Table 14–9
`imq.cluster.url`	Table 14–9
`imq.destination.DMQ.truncateBody`	Table 14–2
`imq.destination.logDeadMsgs`	Table 14–8
`imq.hostname`	Table 14–1
`imq.imqcmd.password`	Table 14–7
`imq.keystore.file.dirpath`	Table 14–7
`imq.keystore.file.name`	Table 14–7
`imq.keystore.password`	Table 14–7
`imq.keystore.propertyName`	Table 14–7
`imq.log.console.output`	Table 14–8
`imq.log.console.stream`	Table 14–8
`imq.log.file.dirpath`	Table 14–8
`imq.log.file.filename`	Table 14–8
`imq.log.file.output`	Table 14–8
`imq.log.file.rolloverbytes`	Table 14–8
`imq.log.file.rolloversecs`	Table 14–8
`imq.log.level`	Table 14–8
`imq.log.syslog.facility`	Table 14–8
`imq.log.syslog.identity`	Table 14–8
`imq.log.syslog.logconsole`	Table 14–8
`imq.log.syslog.logpid`	Table 14–8
`imq.log.syslog.output`	Table 14–8
`imq.log.timezone`	Table 14–8
`imq.message.expiration.interval`	Table 14–2
`imq.message.max_size`	Table 14–2
`imq.metrics.enabled`	Table 14–8
`imq.metrics.interval`	Table 14–8
`imq.metrics.topic.enabled`	Table 14–8
`imq.metrics.topic.interval`	Table 14–8
`imq.metrics.topic.persist`	Table 14–8
`imq.metrics.topic.timetolive`	Table 14–8
`imq.passfile.dirpath`	Table 14–7
`imq.passfile.enabled`	Table 14–7
`imq.passfile.name`	Table 14–7
`imq.persist.file.destination.message.filepool.limit`	Table 14–5
`imq.persist.file.message.cleanup`	Table 14–5
`imq.persist.file.message.filepool.cleanratio`	Table 14–5
`imq.persist.file.message.max_record_size`	Table 14–5
`imq.persist.file.sync.enabled`	Table 14–5
`imq.persist.jdbc.brokerid`	Table 14–6
`imq.persist.jdbc.closedburl`	Table 14–6
`imq.persist.jdbc.createdburl`	Table 14–6
`imq.persist.jdbc.driver`	Table 14–6
`imq.persist.jdbc.needpassword`	Table 14–6
`imq.persist.jdbc.opendburl`	Table 14–6
`imq.persist.jdbc.password`	Table 14–6
`imq.persist.jdbc.table.IMQCCREC35`	Table 14–6
`imq.persist.jdbc.table.IMQDEST35`	Table 14–6
`imq.persist.jdbc.table.IMQILIST35`	Table 14–6
`imq.persist.jdbc.table.IMQINT35`	Table 14–6
`imq.persist.jdbc.table.IMQMSG35`	Table 14–6
`imq.persist.jdbc.table.IMQPROPS35`	Table 14–6
`imq.persist.jdbc.table.IMQSV35`	Table 14–6
`imq.persist.jdbc.table.IMQTACK35`	Table 14–6
`imq.persist.jdbc.table.IMQTXN35`	Table 14–6
`imq.persist.jdbc.user`	Table 14–6
`imq.persist.store`	Table 14–4
`imq.ping.interval`	Table 14–1
`imq.portmapper.backlog`	Table 14–1
`imq.portmapper.hostname`	Table 14–1
`imq.portmapper.port`	Table 14–1
`imq.resourceState.count`	Table 14–2
`imq.resourceState.threshold`	Table 14–2
`imq.service.activelist`	Table 14–1
`imq.serviceName.accesscontrol.enabled`	Table 14–7
`imq.serviceName.accesscontrol.file.filename`	Table 14–7
`imq.serviceName.authentication.type`	Table 14–7
`imq.serviceName.max_threads`	Table 14–1
`imq.serviceName.min_threads`	Table 14–1
`imq.serviceName.protocolType.hostname`	Table 14–1
`imq.serviceName.protocolType.port`	Table 14–1
`imq.serviceName.threadpool_model`	Table 14–1
`imq.shared.connectionMonitor_limit`	Table 14–1
`imq.system.max_count`	Table 14–2
`imq.system.max_size`	Table 14–2
`imq.transaction.autorollback`	Table 14–2
`imq.user_repository.ldap.base`	Table 14–7
`imq.user_repository.ldap.gidattr`	Table 14–7
`imq.user_repository.ldap.grpbase`	Table 14–7
`imq.user_repository.ldap.grpfilter`	Table 14–7
`imq.user_repository.ldap.grpsearch`	Table 14–7
`imq.user_repository.ldap.memattr`	Table 14–7
`imq.user_repository.ldap.password`	Table 14–7
`imq.user_repository.ldap.principal`	Table 14–7
`imq.user_repository.ldap.propertyName`	Table 14–7
`imq.user_repository.ldap.server`	Table 14–7
`imq.user_repository.ldap.ssl.enabled`	Table 14–7
`imq.user_repository.ldap.timeout`	Table 14–7
`imq.user_repository.ldap.uidattr`	Table 14–7
`imq.user_repository.ldap.usrfilter`	Table 14–7

Chapter 15 Physical Destination Property Reference

This chapter provides reference information about configuration properties for physical destinations. These properties can be set when creating or updating a physical destination. For auto-created destinations, you set default values in the broker’s instance configuration file (see Table 14–3).

Physical Destination Properties

Table 15–1 Physical Destination Properties


Property	Type	Default	Description
`maxNumMsgs` [In a cluster environment, applies to each individual instance of a destination rather than collectively to all instances in the cluster]	Integer	`-1`	Maximum number of unconsumed messages A value of `-1` denotes an unlimited number of messages. For the dead message queue, the default value is `1000`.
`maxBytesPerMsg`	String	`-1`	Maximum size, in bytes, of any single message Rejection of a persistent message is reported to the producing client with an exception; no notification is sent for nonpersistent messages.
			The value may be expressed in bytes, kilobytes, or megabytes, using the following suffixes: `b`: Bytes `k`: Kilobytes (1024 bytes) `m`: Megabytes (1024 × 1024 = 1,048,576 bytes)
			An unsuffixed value is expressed in bytes; a value of `-1` denotes an unlimited message size.
			Examples: `1600`: 1600 bytes `1600b`: 1600 bytes `16k`: 16 kilobytes (= 16,384 bytes) `16m`: 16 megabytes (= 16,777,216 bytes) `-1`: No limit
`maxTotalMsgBytes`	String	`-1`	Maximum total memory, in bytes, for unconsumed messages The syntax is the same as for `maxBytesPerMsg` (see above). For the dead message queue, the default value is `10m`.
`limitBehavior`	String	`REJECT_NEWEST`	Broker behavior when memory-limit threshold reached: `FLOW_CONTROL`: Slow down producers `REMOVE_OLDEST`: Throw out oldest messages `REMOVE_LOW_PRIORITY`: Throw out lowest-priority messages according to age; no notification to producing client `REJECT_NEWEST`: Reject newest messages; notify producing client with an exception only if message is persistent
			If the value is `REMOVE_OLDEST` or `REMOVE_LOW_PRIORITY` and the `useDMQ` property is `true`, excess messages are moved to the dead message queue. For the dead message queue itself, the default limit behavior is `REMOVE_OLDEST` and cannot be set to `FLOW_CONTROL`.
`maxNumProducers` [Cannot be set for dead message queue]	Integer	`-1`	Maximum number of message producers for destination When this limit is reached, no new producers can be created. A value of `-1` denotes an unlimited number of producers.
`maxNumActiveConsumers` [Queue destinations only.]	Integer	`1`	Maximum number of active message consumers in load-balanced delivery from queue destination A value of `-1` denotes an unlimited number of consumers. In Sun Java System Message Queue^TM Platform Edition, the value is limited to `2`.
`maxNumBackupConsumers`	Integer	`0`	Maximum number of backup message consumers in load-balanced delivery from queue destination A value of `-1` denotes an unlimited number of consumers. In Sun Java System Message Queue Platform Edition, the value is limited to `1`.
`consumerFlowLimit`	Integer	`1000`	Maximum number of messages delivered to 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 begins. A destination consumer can override this limit by specifying a lower value on a connection. A value of `-1` denotes an unlimited number of messages.
`isLocalOnly`	Boolean	`false`	Local delivery only? This property applies only to destinations in broker clusters, and cannot be changed once the destination has been created. If `true`, the destination is not replicated on other brokers and is limited to delivering messages only to local consumers (those connected to the broker on which the destination is created).
`localDeliveryPreferred` ^,	Boolean	`false`	Local delivery preferred? This property applies only to load-balanced queue delivery in broker clusters. If `true`, messages will be delivered to remote consumers only if there are no consumers on the local broker; the destination must not be restricted to local-only delivery (`isLocalOnly` must be `false`).
`useDMQ`	Boolean	`true`	Send dead messages to dead message queue? If `false`, dead messages will simply be discarded.

Chapter 16 Administered Object Attribute Reference

This chapter provides reference information about the attributes of administered objects. It consists of the following sections:

Connection Factory Attributes

The attributes of a connection factory object are grouped into categories described in the following sections below:

Connection Handling

Table 16–1 lists the connection factory attributes for connection handling.

Table 16–1 Connection Factory Attributes for Connection Handling


Attribute	Type	Default	Description
`imqAddressList`	String	An existing Message Queue^TM 3.0 address, if any; if none, the first entry in Table 16–2	List of broker addresses The list consists of one or more broker addresses, separated by commas. Each address specifies (or implies) the host name, port number, and connection service for a broker instance to which the client can connect. Address syntax varies depending on the connection service and port assignment method; see below for details.
`imqAddressListBehavior`	String	`PRIORITY`	Order in which to attempt connection to broker addresses: `PRIORITY`: Order specified in address list `RANDOM`: Random order Note – If many clients share the same connection factory, specify random connection order to prevent them from all attempting to connect to the same address.
`imqAddressListIterations`	Integer	`5`	Number of times to iterate through address list attempting to establish or reestablish a connection A value of `-1` denotes an unlimited number of iterations.
`imqPingInterval`	Integer	`30`	Interval, in seconds, at which to test connection between client and broker A value of `0` or `-1` disables periodic testing of the connection.
`imqReconnectEnabled`	Boolean	`false`	Attempt to reestablish a lost connection?
`imqReconnectAttempts`	Integer	`0`	Number of times to attempt connection (or reconnection) to each address in address list before moving on to next A value of `-1` denotes an unlimited number of connection attempts: attempt repeatedly to connect to first address until successful.
`imqReconnectInterval`	Long integer	`3000`	Interval, in milliseconds, between reconnection attempts This value applies both for successive attempts on a given address and for successive addresses in the list. Note – Too small a value may give the broker insufficient recovery time; too large a value may cause unacceptable connection delays.
`imqSSLIsHostTrusted`	Boolean	`true`	Trust any certificate presented by broker? If `false`, the Message Queue client runtime will validate all certificates presented to it. Validation will fail if the signer of the certificate is not in the client's trust store. If `true`, validation of certificates is skipped. This can be useful, for instance, during software testing when a self-signed certificate is used. NOTE: To use signed certificates from a certification authority, set this attribute to `false`.

The value of the imqAddressList attribute is a comma-separated string specifying one or more broker addresses to which to connect. The general syntax for each address is as follows:

   
scheme://address

where scheme identifies one of the addressing schemes shown in the first column of Table 16–2 and address denotes the broker address itself. The exact syntax for specifying the address depends on the addressing scheme, as shown in the last column of the table.

Table 16–2 Message Broker Addressing Schemes


Scheme	Service	Syntax	Description
`mq`	`jms` or `ssljms`	[`hostName`][`:portNumber`][`/serviceName`]	Assign port dynamically for `jms` or `ssljms` connection service The address list entry specifies the host name and port number for the Message Queue Port Mapper. The Port Mapper itself dynamically assigns a port to be used for the connection. Default values: `hostName` = `localhost` `portNumber` = `7676` `serviceName` = `jms` For the `ssljms` connection service, all variables must be specified explicitly.
`mqtcp`	`jms`	`hostName:portNumber/jms`	Connect to specified port using `jms` connection service Bypasses the Port Mapper and makes a TCP connection directly to the specified host name and port number.
`mqssl`	`ssljms`	`hostName:portNumber/ssljms`	Connect to specified port using `ssljms` connection service Bypasses the Port Mapper and makes a secure SSL connection directly to the specified host name and port number.
`http`	`httpjms`	`http://hostName:portNumber/contextRoot/tunnel` If multiple broker instances use the same tunnel servlet, the following syntax connects to a specific broker instance rather than a randomly selected one: `http://hostName:portNumber/contextRoot/tunnel?` `ServerName=hostName:instanceName`	Connect to specified port using `httpjms` connection service Makes an HTTP connection to a Message Queue tunnel servlet at the specified URL. The broker must be configured to access the HTTP tunnel servlet.
`https`	`httpsjms`	`https://hostName:portNumber/contextRoot/tunnel` If multiple broker instances use the same tunnel servlet, the following syntax connects to a specific broker instance rather than a randomly selected one: `https://hostName:portNumber/contextRoot/tunnel?` `ServerName=hostName:instanceName`	Connect to specified port using `httpsjms` connection service Makes a secure HTTPS connection to a Message Queue tunnel servlet at the specified URL. The broker must be configured to access the HTTPS tunnel servlet.

Table 16–3 Message Broker Address Examples


Service	Broker Host	Port	Example Address
Not specified	Not specified	Not specified	No address (`mq://localHost:7676/jms`)
Not specified	Specified host	Not specified	`myBkrHost` (`mq://myBkrHost:7676/jms`)
Not specified	Not specified	Specified Port Mapper port	`1012` (`mq://localHost:1012/jms`)
`ssljms`	Local host	Standard Port Mapper port	`mq://localHost:7676/ssljms`
`ssljms`	Specified host	Standard Port Mapper port	`mq://myBkrHost:7676/ssljms`
`ssljms`	Specified host	Specified Port Mapper port	`mq://myBkrHost:1012/ssljms`
`jms`	Local host	Specified service port	`mqtcp://localhost:1032/jms`
`ssljms`	Specified host	Specified service port	`mqssl://myBkrHost:1034/ssljms`
`httpjms`	Not applicable	Not applicable	`http://websrvr1:8085/imq/tunnel`
`httpsjms`	Not applicable	Not applicable	`https://websrvr2:8090/imq/tunnel`

Client Identification

Table 16–4 lists the connection factory attributes for client identification.

Table 16–4 Connection Factory Attributes for Client Identification


Attribute	Type	Default	Description
`imqDefaultUsername`	String	`guest`	Default user name for authenticating with broker
`imqDefaultPassword`	String	`guest`	Default password for authenticating with broker
`imqConfiguredClientID`	String	`null`	Administratively configured client identifier
`imqDisableSetClientID`	Boolean	`false`	Prevent client from changing client identifier using `setClientID` method?

Reliability and Flow Control

Table 16–5 lists the connection factory attributes for reliability and flow control.

Table 16–5 Connection Factory Attributes for Reliability and Flow Control


Attribute	Type	Default	Description
`imqAckTimeout`	String	`0`	Maximum time, in milliseconds, to wait for broker acknowledgment before throwing an exception A value of `0` denotes no timeout (wait indefinitely). Note – In some situations, too low a value can cause premature timeout: for example, initial authentication of a user against an LDAP user repository using a secure (SSL) connection can take more than 30 seconds.
`imqConnectionFlowCount`	Integer	`100`	Number of payload messages in a metered batch Delivery of payload messages to the client is temporarily suspended after this number of messages, allowing any accumulated control messages to be delivered. Payload message delivery is resumed on notification by the client runtime, and continues until the count is again reached. A value of `0` disables metering of message delivery and may cause Message Queue control messages to be blocked by heavy payload message traffic.
`imqConnectionFlowLimitEnabled`	Boolean	`false`	Limit message flow at connection level?
`imqConnectionFlowLimit`	Integer	`1000`	Maximum number of messages per connection to deliver and buffer for consumption Message delivery on a connection stops when the number of unconsumed payload messages pending (subject to flow metering governed by `imqConnectionFlowCount`) exceeds this limit. Delivery resumes only when the number of pending messages falls below the limit. This prevents the client from being overwhelmed with pending messages that might cause it to run out of memory. This attribute is ignored if `imqConnectionFlowLimitEnabled` is `false`.
`imqConsumerFlowLimit`	Integer	`100`	Maximum number of messages per consumer to deliver and buffer for consumption Message delivery to a given consumer stops when the number of unconsumed payload messages pending for that consumer exceeds this limit. Delivery resumes only when the number of pending messages for the consumer falls below the percentage specified by `imqConsumerFlowThreshold`. This can be used to improve load balancing among multiple consumers and prevent any single consumer from starving others on the same connection. This limit can be overridden by a lower value set for a queue’s own `consumerFlowLimit` attribute (see Chapter 15, Physical Destination Property Reference). Note also that message delivery to all consumers on a connection is subject to the overall limit specified by `imqConnectionFlowLimit`.
`imqConsumerFlowThreshold`	Integer	`50`	Number of messages per consumer buffered in the client runtime, as a percentage of `imqConsumerFlowLimit`, below which to resume message delivery

Queue Browser and Server Sessions

Table 16–6 lists the connection factory attributes for queue browsing and server sessions.

Table 16–6 Connection Factory Attributes for Queue Browser and Server Sessions


Attribute	Type	Default	Description
`imqQueueBrowserMaxMessagesPerRetrieve`	Integer	`1000`	Maximum number of messages to retrieve at one time when browsing contents of a queue destination Note – This attribute does not affect the total number of messages browsed, only the way they are chunked for delivery to the client runtime (fewer but larger chunks or more but smaller ones). The client application will always receive all messages in the queue. Changing the attribute's value may affect performance, but will not affect the total amount of data retrieved.
`imqQueueBrowserRetrieveTimeout`	Long integer	`60000`	Maximum time, in milliseconds, to wait to retrieve messages, when browsing contents of a queue destination, before throwing an exception
`imqLoadMaxToServerSession`	Boolean	`true`	Load up to maximum number of messages into a server session? If `false`, the client will load only a single message at a time. This attribute applies only to JMS application server facilities.

Standard Message Properties

The connection factory attributes listed in Table 16–7 control whether the Message Queue client runtime sets certain standard message properties defined in the Java Message Service Specification.

Table 16–7 Connection Factory Attributes for Standard Message Properties


Property	Type	Default	Description
`imqSetJMSXUserID`	Boolean	`false`	Set `JMSXUserID` property (identity of user sending message) for produced messages?
`imqSetJMSXAppID`	Boolean	`false`	Set `JMSXAppID` property (identity of application sending message) for produced messages?
`imqSetJMSXProducerTXID`	Boolean	`false`	Set `JMSXProducerTXID` property (transaction identifier of transaction within which message was produced) for produced messages?
`imqSetJMSXConsumerTXID`	Boolean	`false`	Set `JMSXConsumerTXID` property (transaction identifier of transaction within which message was consumed) for consumed messages?
`imqSetJMSXRcvTimestamp`	Boolean	`false`	Set `JMSXRcvTimestamp` property (time message delivered to consumer) for consumed messages?

Message Header Overrides

Table 16–8 lists the connection factory attributes for overriding JMS message header fields.

Table 16–8 Connection Factory Attributes for Message Header Overrides


Attribute	Type	Default	Description
`imqOverrideJMSDeliveryMode`	Boolean	`false`	Allow client-set delivery mode to be overridden?
`imqJMSDeliveryMode`	Integer	`2`	Overriding value of delivery mode: `1` Nonpersistent `2` Persistent
`imqOverrideJMSExpiration`	Boolean	`false`	Allow client-set expiration time to be overridden?
`imqJMSExpiration`	Long integer	`0`	Overriding value of expiration time, in milliseconds A value of `0` denotes an unlimited expiration time (message never expires).
`imqOverrideJMSPriority`	Boolean	`false`	Allow client-set priority level to be overridden?
`imqJMSPriority`	Integer	`4` (normal)	Overriding value of priority level (`0` to `9`)
`imqOverrideJMSHeadersToTemporaryDestinations`	Boolean	`false`	Apply overrides to temporary destinations?

Destination Attributes

Table 16–9 lists the attributes that can be set for a destination administered object.

Table 16–9 Destination Attributes


Attribute	Type	Default	Description
`imqDestinationName`	String	`Untitled_Destination_Object`	Name of physical destination The destination name may contain only alphanumeric characters (no spaces) and must begin with an alphabetic character or the underscore (`_`) or dollar sign (`$`) character. It may not begin with the characters `mq`.
`imqDestinationDescription`	String	None	Descriptive string for destination

SOAP Endpoint Attributes

Table 16–10 lists the attributes used to configure endpoint URLs for applications that use the Simple Object Access Protocol (SOAP); see the Message Queue Developer's Guide for Java Clients for more information.

Table 16–10 SOAP Endpoint Attributes


Attribute	Type	Default	Description
`imqSOAPEndpointList`	String	None	List of one of more URLs representing SOAP endpoints to which to send messages, separated by spaces Each URL should be associated with a servlet that can receive and process SOAP messages. Example: `http://www.serv1/ http://www.serv2/` If the list specifies more than one URL, messages are broadcast to all of them.
`imqEndpointName`	String	`Untitled_Endpoint_Object`	Name of SOAP endpoint
`imqEndpointDescription`	String	None	Descriptive string for SOAP endpoint Example: `My endpoints for broadcast`

Chapter 17 JMS Resource Adapter Property Reference

This chapter describes the configuration properties of the Message Queue^TM JMS Resource Adapter (JMS RA), which enables you to integrate Sun Java System^TM Message Queue with any J2EE 1.4 application server by means of the standard J2EE connector architecture (JCA). When plugged into an application server, the Resource Adapter allows applications deployed in that application server to use Message Queue to send and receive JMS messages.

The Message Queue JMS Resource Adapter exposes its configuration properties through three JavaBean components:

The ResourceAdapter JavaBean (ResourceAdapter JavaBean) affects the behavior of the Resource Adapter as a whole.
The ManagedConnectionFactory JavaBean (ManagedConnectionFactory JavaBean) affects connections created by the Resource Adapter for use by message-driven beans (MDBs).
The ActivationSpec JavaBean (ActivationSpec JavaBean) affects message endpoints that represent MDBs in their interactions with the messaging system.

To set property values for these entities, you use the tools provided by your application server for configuration and deployment of the Resource Adapter and for deployment of MDBs.

This chapter lists and describes the configuration properties of the Message Queue JMS Resource Adapter. It contains the following sections:

ResourceAdapter JavaBean

The ResourceAdapter configuration configures the default JMS Resource Adapter behavior. Table 17–1 lists and describes the properties with which you can configure this JavaBean.

Table 17–1 Resource Adapter Properties


Property	Type	Default	Description
`addressList`	String	`mq://localhost:7676/jms`	(Required) Message service address for connecting to Message Queue service Equivalent to `connectionURL` (below); you must set one or the other.
`connectionURL`	String	`mq://localhost:7676/jms`	Message service address for connecting to the Message Queue service Equivalent to `addressList`(above); you must set one or the other.
`userName`	String	`guest`	(Required) Default user name for connecting to Message Queue service
`password`	String	`guest`	(Required) Default password for connecting to Message Queue service
`addressListBehavior`	String	`PRIORITY`	Order in which to attempt connection to Message Queue service: `PRIORITY`: Order specified in address list `RANDOM`: Random order Note – Reconnection attempts after a connection failure start with the broker whose connection failed and proceed sequentially through the address list, regardless of the value set for this property.
`addressListIterations`	Integer	`1`	Number of times to iterate through address list attempting to establish or reestablish a connection
`reconnectEnabled`	Boolean	`false`	Attempt to reestablish a lost connection?
`reconnectAttempts`	Integer	`6`	Number of times to attempt reconnection to each address in address list before moving on to next
`reconnectInterval`	Long integer	`30000`	Interval, in milliseconds, between reconnection attempts

ManagedConnectionFactory JavaBean

A managed connection factory defines the connections that the Resource Adapter provides to a message-driven bean. Table 17–2 shows the properties of the ManagedConnectionFactory JavaBean; if set, these properties override the corresponding properties of the ResourceAdapter JavaBean.

Table 17–2 Managed Connection Factory Properties


Property	Type	Default	Description
`addressList`	String	Inherited from `ResourceAdapter` JavaBean (see Table 17–1)	List of message service addresses for connecting to Message Queue service
`userName`	String	`guest`	(Optional) User name for connecting to Message Queue service
`password`	String	`guest`	(Optional) Password for connecting to Message Queue service
`clientID`	String	None	Client identifier for connections to Message Queue service
`addressListBehavior`	String	`PRIORITY`	Order in which to attempt connection to Message Queue service: `PRIORITY`: Order specified in address list `RANDOM`: Random order Note – Reconnection attempts after a connection failure start with the broker whose connection failed and proceed sequentially through the address list, regardless of the value set for this property.
`addressListIterations`	Integer	`1`	Number of times to iterate through address list attempting to establish or reestablish a connection
`reconnectEnabled`	Boolean	`false`	Attempt to reestablish a lost connection?
`reconnectAttempts`	Integer	`6`	Number of times to attempt reconnection to each address in address list before moving on to next
`reconnectInterval`	Long integer	`30000`	Interval, in milliseconds, between reconnection attempts

ActivationSpec JavaBean

Table 17–3 shows the configurable properties of the ActivationSpec JavaBean. These properties are used by the application server when instructing the Resource Adapter to activate a message endpoint and associate it with a message-driven bean.

Table 17–3 Activation Specification Properties


Property	Type	Default	Description
`addressList` [Property specific to Message Queue JMS Resource Adapter]	String	Inherited from `ResourceAdapter` JavaBean	(Optional) Message service address for connecting to Message Queue service
`destination` [Standard Enterprise JavaBean (EJB) and J2EE Connector Architecture (CA) property]	String	None	(Required) Name of destination from which to consume messages The value must be that of the `destinationName` property for a Message Queue destination administered object.
`destinationType`	String	None	(Required) Type of destination specified by `destination` property: `javax.jms.Queue`: Queue destination `javax.jms.Topic`: Topic destination
`messageSelector`	String	None	(Optional) Message selector for filtering messages delivered to consumer
`subscriptionName`	String	None	Name for durable subscriptions This property must be set if `subscriptionDurability` is set to `Durable`.
`subscriptionDurability`	String	`NonDurable`	Durability of consumer for topic destination: `Durable`: Durable consumer `NonDurable`: Nondurable consumer This property is valid only if `destinationType` is set to `javax.jms.Topic`, and is optional for nondurable subscriptions and required for durable ones. If set to `Durable`, the `clientID` and `subscriptionName` properties must also be set.
`clientId`	String	None	Client ID for connections to Message Queue service This property must be set if `subscriptionDurability` is set to `Durable`.
`acknowledgeMode`	String	`Auto-acknowledge`	(Optional) Acknowledgment mode: `Auto-acknowledge`: Auto-acknowledge mode `Dups-ok-acknowledge`: Dups-OK-acknowledge mode
`customAcknowledgeMode`	String	None	Acknowledgment mode for MDB message consumption Valid values are `No_acknowledge` or null. You can use no-acknowledge mode only for a nontransacted, nondurable topic subscription; if you use this setting with a transacted subscription or a durable subscription, subscription activation will fail.
`endpointExceptionRedeliveryAttempts`	Integer	`6`	Number of times to redeliver a message when MDB throws an exception during message delivery
`sendUndeliverableMsgsToDMQ`	Boolean	`true`	Place message in dead message queue when MDB throws a runtime exception and number of redelivery attempts exceeds the value of `endpointExceptionRedeliveryAttempts`? If `false`, the Message Queue broker will attempt redelivery of the message to any valid consumer, including the same MDB.

Chapter 18 Metrics Reference

This chapter describes the metric information that a Message Queue^TM message broker can provide for monitoring, tuning, and diagnostic purposes. This information can be made available in a variety of ways:

In a log file (see Sending Metrics Data to Log Files)
Via the Command utility’s metrics bkr command (see Broker Management)
In metrics messages sent to a metrics topic destination (see Writing an Application to Monitor Brokers)

The tables in this chapter list the kinds of metric information available and the forms in which it can be provided. For metrics provided through the Command utility’s metrics bkr command, the tables list the metric type with which they can be requested; for those provided in metrics messages, the tables list the metrics topic destination to which they are delivered. The chapter consists of the following sections:

JVM Metrics

Table 18–1 shows the metric information that the broker reports for the broker process JVM (Java Virtual Machine) heap.

Table 18–1 JVM Metrics


Metric Quantity	Description	Log File?	`metrics` `bkr`MetricType	Metrics Topic
JVM heap: total memory	Current total memory, in bytes	Yes	`cxn`	`mq.metrics.jvm`
JVM heap: free memory	Amount of memory currently available for use, in bytes	Yes	`cxn`	`mq.metrics.jvm`
JVM heap: max memory	Maximum allowable heap size, in bytes	Yes	None	`mq.metrics.jvm`

Brokerwide Metrics

Table 18–2 shows the brokerwide metric information that the broker reports.

Table 18–2 Brokerwide Metrics


Metric Quantity	Description	Log File?	`metrics` `bkr`MetricType	Metrics Topic
Connections
Num connections	Total current number of connections for all connection services	Yes	`cxn`	`mq.metrics.broker`
Num threads	Total current number of threads for all connection services	Yes	`cxn`	None
Min threads	Total minimum number of threads for all connection services	Yes	`cxn`	None
Max threads	Total maximum number of threads for all connection services	Yes	`cxn`	None
Stored Messages
Num messages	Current number of payload messages stored in memory and persistent store	No	None [Use `query` `bkr` command instead]	`mq.metrics.broker`
Total message bytes	Total size in bytes of payload messages currently stored in memory and persistent store	No	None	`mq.metrics.broker`
Message Flow
Num messages in	Cumulative number of payload messages received since broker started	Yes	`ttl`	`mq.metrics.broker`
Num messages out	Cumulative number of payload messages sent since broker started	Yes	`ttl`	`mq.metrics.broker`
Rate messages in	Current rate of flow of payload messages into broker	Yes	`rts`	None
Rate messages out	Current rate of flow of payload messages out of broker	Yes	`rts`	None
Message bytes in	Cumulative size in bytes of payload messages received since broker started	Yes	`ttl`	`mq.metrics.broker`
Message bytes out	Cumulative size in bytes of payload messages sent since broker started	Yes	`ttl`	`mq.metrics.broker`
Rate message bytes in	Current rate of flow of payload message bytes into broker	Yes	`rts`	None
Rate message bytes out	Current rate of flow of payload message bytes out of broker	Yes	`rts`	None
Num packets in	Cumulative number of payload and control packets received since broker started	Yes	`ttl`	`mq.metrics.broker`
Num packets out	Cumulative number of payload and control packets sent since broker started	Yes	`ttl`	`mq.metrics.broker`
Rate packets in	Current rate of flow of payload and control packets into broker	Yes	`rts`	None
Rate packets out	Current rate of flow of payload and control packets out of broker	Yes	`rts`	None
Packet bytes in	Cumulative size in bytes of payload and control packets received since broker started	Yes	`ttl`	`mq.metrics.broker`
Packet bytes out	Cumulative size in bytes of payload and control packets sent since broker started	Yes	`ttl`	`mq.metrics.broker`
Rate packet bytes in	Current rate of flow of payload and control packet bytes into broker	Yes	`rts`	None
Rate packet bytes out	Current rate of flow of payload and control packet bytes out of broker	Yes	`rts`	None
Destinations
Num destinations	Current number of physical destinations	No	None	`mq.metrics.broker`

Connection Service Metrics

Table 18–3 shows the metric information that the broker reports for individual connection services.

Table 18–3 Connection Service Metrics


Metric Quantity	Description	Log File?	`metrics` `svc`MetricType	Metrics Topic
Connections
Num connections	Current number of connections	No	`cxn` [Also available with `query` `svc` command]	None
Num threads	Current number of threads	No	`cxn`	None
Min threads	Minimum number of threads assigned to service	No	`cxn`	None
Max threads	Maximum number of threads assigned to service	No	`cxn`	None
Message Flow
Num messages in	Cumulative number of payload messages received through connection service since broker started	No	`ttl`	None
Num messages out	Cumulative number of payload messages sent through connection service since broker started	No	`ttl`	None
Rate messages in	Current rate of flow of payload messages into broker through connection service	No	`rts`	None
Rate messages out	Current rate of flow of payload messages out of broker through connection service	No	`rts`	None
Message bytes in	Cumulative size in bytes of payload messages received through connection service since broker started	No	`ttl`	None
Message bytes out	Cumulative size in bytes of payload messages sent through connection service since broker started	No	`ttl`	None
Rate message bytes in	Current rate of flow of payload message bytes into broker through connection service	No	`rts`	None
Rate message bytes out	Current rate of flow of payload message bytes out of broker through connection service	No	`rts`	None
Num packets in	Cumulative number of payload and control packets received through connection service since broker started	No	`ttl`	None
Num packets out	Cumulative number of payload and control packets sent through connection service since broker started	No	`ttl`	None
Rate packets in	Current rate of flow of payload and control packets into broker through connection service	No	`rts`	None
Rate packets out	Current rate of flow of payload and control packets out of broker through connection service	No	`rts`	None
Packet bytes in	Cumulative size in bytes of payload and control packets received through connection service since broker started	No	`ttl`	None
Packet bytes out	Cumulative size in bytes of payload and control packets sent through connection service since broker started	No	`ttl`	None
Rate packet bytes in	Current rate of flow of payload and control packet bytes into broker through connection service	No	`rts`	None
Rate packet bytes out	Current rate of flow of payload and control packet bytes out of broker through connection service	No	`rts`	None

Destination Metrics

Table 18–4 shows the metric information that the broker reports for individual destinations.

Table 18–4 Destination Metrics


Metric Quantity	Description	Log File?	`metrics` `dst`MetricType	Metrics Topic
Message Consumers
Num consumers	Current number of associated message consumers For queue destinations, this attribute includes both active and backup consumers. For topic destinations, it includes both nondurable and (active and inactive) durable subscribers and is equivalent to “Num active consumers.”	No	`con`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Peak num consumers	Peak number of associated message consumers since broker started For queue destinations, this attribute includes both active and backup consumers. For topic destinations, it includes both nondurable and (active and inactive) durable subscribers and is equivalent to “Peak num active consumers.”	No	`con`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Avg num consumers	Average number of associated message consumers since broker started For queue destinations, this attribute includes both active and backup consumers. For topic destinations, it includes both nondurable and (active and inactive) durable subscribers and is equivalent to “Avg num active consumers.”	No	`con`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Num active consumers	Current number of associated active message consumers For topic destinations, this attribute includes both nondurable and (active and inactive) durable subscribers and is equivalent to “Num consumers.”	No	`con`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Peak num active consumers	Peak number of associated active message consumers since broker started For topic destinations, this attribute includes both nondurable and (active and inactive) durable subscribers and is equivalent to “Peak num consumers.”	No	`con`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Avg num active consumers	Average number of associated active message consumers since broker started For topic destinations, this attribute includes both nondurable and (active and inactive) durable subscribers and is equivalent to “Avg num consumers.”	No	`con`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Num backup consumers [Queue destinations only]	Current number of associated backup message consumers	No	`con`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Peak num backup consumers	Peak number of associated backup message consumers since broker started	No	`con`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Avg num backup consumers	Average number of associated backup message consumers since broker started	No	`con`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Stored Messages
Num messages	Current number of messages stored in memory and persistent store	No	`conttlrts` [Also available with `query` `dst` command]	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Peak num messages	Peak number of messages stored in memory and persistent store since broker started	No	`conttlrts`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Avg num messages	Average number of messages stored in memory and persistent store since broker started	No	`conttlrts`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Total message bytes	Current total size in bytes of messages stored in memory and persistent store	No	`ttlrts`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Peak total message bytes	Peak total size in bytes of messages stored in memory and persistent store since broker started	No	`ttlrts`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Avg total message bytes	Average total size in bytes of messages stored in memory and persistent store since broker started	No	`ttlrts`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Message Flow
Num messages in	Cumulative number of messages received since broker started	No	`ttl`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Num messages out	Cumulative number of messages sent since broker started	No	`ttl`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Msg bytes in	Cumulative size in bytes of messages received since broker started	No	`ttl`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Msg bytes out	Cumulative size in bytes of messages sent since broker started	No	`ttl`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Peak message bytes	Size in bytes of largest single message received since broker started	No	`ttlrts`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Rate num messages in	Current rate of flow of messages received	No	`rts`	None
Rate num messages out	Current rate of flow of messages sent	No	`rts`	None
Rate msg bytes in	Current rate of flow of message bytes received	No	`rts`	None
Rate msg bytes out	Current rate of flow of message bytes sent	No	`rts`	None
Disk Utilization
Disk reserved [File-based persistence only]	Amount of disk space, in bytes, reserved for destination	No	`dsk`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Disk used	Amount of disk space, in bytes, currently in use by destination	No	`dsk`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`
Disk utilization ratio	Ratio of disk space in use to disk space reserved for destination	No	`dsk`	`mq.metrics.destination.queue.queueNamemq.metrics.destination.topic.topicName`