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.

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:

imqcmddestroy 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 15–1 shows the options
to the imqbrokerd command and the configuration properties,
if any, overridden by each option.

Table 15–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

-clusterbroker1 [ [ ,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.

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.

Command Utility

All imqcmd commands must include a subcommand (except
those using the -v or -h option to display
product version information or usage help, respectively). The possible subcommands
are listed in Table 15–2 and described
in detail in the corresponding sections below. In addition, each imqcmd subcommand
supports the general options shown in General Command Utility Options.

Note –

The -u userName option
(and corresponding password) is required except when using the -v or -h option. Also if a subcommand accepts a broker address (-b option)
and no host name or port number is specified, the values localhost and 7676 are assumed by default.

Set connection-related system property that affects how imqcomd creates
a connection to the broker. Not used to set broker configuration properties.

Usually overrides connection factory attributes for imqcmd client
runtime. For example, the option in the following command changes the default
value of imqSSLIsTrusted:

imqcmd list svc -secure -DimqSSLIsTrusted=true

-rtmtimeoutInterval

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.

-rtrnumRetries

Number of retries to attempt after a broker request times out

Default value:5.

-javahomepath

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,

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 15–4 to manage and control it.

Table 15–4 Command Utility
Subcommands for Broker Management

Syntax

Description

shutdown bkr [-bhostName:portNumber]

[-timenSeconds]

[-nofailover]

Shut
down broker

The -time option specifies the interval, in seconds,
to wait before shutting down the broker. (The broker will not block, but will
return immediately from the delayed shutdown request.) During the shutdown
interval, the broker will not accept any new jms connections; admin connections will be accepted, and existing jms connections
will continue to operate. A broker belonging to an enhanced cluster will not
attempt to take over for any other broker during the shutdown interval.

The -nofailover option indicates that no other broker
is to take over the persistent data of the one being shut down. [Applies only to broker clusters]

restart bkr [-bhostName:portNumber]

Restart
broker

Shuts down the broker and then restarts it using the same options specified
when it was originally started.

The broker will stop accepting new connections; existing connections
will continue to operate.

unquiesce bkr [-bhostName:portNumber]

Unquiesce
broker

The broker will resume accepting new connections, returning to normal
operation.

resume bkr [-bhostName:portNumber]

Resume broker

takeover bkr-nbrokerID

[-f]

Initiate broker takeover

Before taking over a broker, you should first shut it down manually
using the shutdownbkr subcommand with
the -nofailover option. If the specified broker appears to
be still running, takeoverbkr will
display a confirmation message (Do you want to take over for
this broker?). The -f option suppresses this
message and initiates the takeover unconditionally.

Note –

The takeoverbkr subcommand
is intended only for use in failed-takeover situations. You should use it
only as a last resort, and not as a general way of forcibly taking over a
running broker.

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

Destroy physical destination

This operation cannot be applied to a system-created destination, such
as a dead message queue.

pause dst [-tdestType-ndestName]

[-pstpauseType]

Pause message delivery for physical destination

Pauses message delivery for the physical destination specified by the -t and -n options. If these options are not specified,
all destinations are paused.

The -pst option specifies the type of message delivery
to be paused:

PRODUCERS: Pause delivery from message
producers

CONSUMERS: Pause delivery to message consumers

ALL: Pause all message delivery

Default value:ALL

resume dst [-tdestType-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.

purge dst -tdestType-ndestName

Purge all messages
from physical destination

compact dst [-tdestType-ndestName]

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.

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

List physical destination property
values

metrics dst -tdestType-ndestName

[-mmetricType]

[-intinterval]

[-mspnumSamples]

Display physical destination metrics

The -m option specifies the type of metrics to display:

ttl: Messages and packets flowing into
and out of the destination and residing in memory

rts: Rate of flow of messages and packets
into and out of the destination per second, along with other rate information

con: Metrics related to message consumers

dsk: Disk usage

Default value:ttl.

The -int option specifies the interval, in seconds,
at which to display metrics. Default value:5.

The -msp option specifies the number of samples to display. Default value: Unlimited (infinite).

List durable subscriptions for the specified topic. If -d option
is omitted then the command lists all durable subscriptions for all topics.

Transaction Management

Table 15–9 lists the imqcmd subcommands for managing local (non-distributed) Message Queue transactions.
Distributed transactions are managed by a distributed transaction manager
rather than imqcmd.

Table 15–9 Command Utility
Subcommands for Transaction Management

Syntax

Description

commit txn -ntransactionID

Commit transaction

rollback txn -ntransactionID

Roll back transaction

list txn

List transactions being tracked by broker

query txn -ntransactionID

Display transaction information

JMX Management

The imqcmd subcommand shown in Table 15–10 is used for administrative support of Java
applications using the Java Management Extensions (JMX)
application programming interface to configure and monitor Message Queue resources.
See Appendix D, JMX Support for further
information on the broker's JMX support.

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 data store. You can
also use it to delete Message Queue database tables that have become corrupted,
change the database, display information about the database, convert a standalone
database for use in an enhanced broker cluster, or back up and restore a highly-available
database. Table 15–13 lists the imqdbmgr subcommands.

Table 15–13 Database Manager
Subcommands

Subcommand

Description

create all

Create new database and persistent data store schema

Used on embedded database systems. The broker property imq.persist.jdbc.vendorName.createdburl must
be specified.

create tbl

Create persistent data store schema for existing database

Used on external database systems.

For brokers belonging to an enhanced broker cluster (imq.cluster.ha = true), the schema created is
for the cluster’s shared data store, in accordance with the database
vendor identified by the broker’s imq.persist.jdbc.dbVendor property.
If imq.cluster.ha = false, the schema
is for the individual broker’s standalone data store. Since the two
types of data store can coexist in the same database, they are distinguished
by appending a suffix to all table names:

CclusterID:
Shared data store

SbrokerID:
Standalone data store

delete tbl

Delete Message Queue database tables from current data store

delete oldtbl

Delete Message Queue database tables from earlier-version data store

Used after the data 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.

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 15–15 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 15–15 User Manager Subcommands

Syntax

Description

add [-iinstanceName]

-uuserName-ppassword

[-ggroup]

Add user and password to repository

The optional -g option specifies a group to which to
assign this user:

admin

user

anonymous

delete [-iinstanceName]

-uuserName

Delete user from repository

update [-iinstanceName]

-uuserName-ppassword

update [-iinstanceName]

-uuserName-aactiveStatus

update [-iinstanceName]

-uuserName-ppassword

-aactiveStatus

Set user’s password or active status (or both)

The -a option takes a boolean value specifying whether
to make the user active (true) or inactive (false).
An inactive status means that the user entry remains in the user repository,
but the user will not be authenticated, even if using the correct password.

Default value:true.

list [-iinstanceName]

[-uuserName]

Display user information

If no user name is specified, all users in the repository are listed.

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

Table 15–16 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 15–17 lists the available subcommands.

Table 15–17 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 15–18).

Default behavior: Use runtime installed
on system or bundled with Message Queue.

-jrehomepath

Location of alternative Java Runtime Environment
(JRE)

-vmargsarg1 [
[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 by
way of 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

If specified, overrides imq.hostname. This might
be necessary, for instance, if the broker’s host computer has more than
one network interface card installed.

imq.portmapper.port [Can be used with imqcmdupdatebkr 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. This might be necessary, for instance, if the broker’s
host computer has more than one network interface card installed.

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. You might need to set a different
value, for instance, to specify a static port number for connecting to the
broker through a firewall.

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

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: 10httpsjms: 10admin: 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: 512Linux: 512Windows: 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 and Delivery Properties

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

Table 16–2 Broker
Routing and Delivery Properties

Property

Type

Default Value

Description

imq.system.max_count [Can be used with imqcmdupdatebkr 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).

imq.transaction.producer.maxNumMsgs

Integer

1000

The maximum number of messages that a producer can process in a single
transaction. It is recommended that the value be less than 5000 to prevent
the exhausting of resources.

imq.transaction.consumer.maxNumMsgs

Integer

100

The maximum number of messages that a consumer can process in a single
transaction. It is recommended that the value be less than 1000 to prevent
the exhausting of resources.

The delay, in seconds. before which auto-created destinations are removed
from the system when they no longer have consumers nor contain messages, .
A smaller value means that memory reclamation takes place more often.

imq.autocreate.destination.maxNumMsgs

Integer

100000

Maximum number of unconsumed messages

A value of -1 denotes an unlimited number of
messages.

Note –

When flow control is in effect (imq.autocreate.destination.limitBehavior = FLOW_CONTROL), it is possible for the specified message limit to
be exceeded because the broker cannot react quickly enough to stop the flow
of incoming messages. In such cases, the value specified for imq.autocreate.destination.maxNumMsgs serves as merely a hint for the broker rather than a strictly
enforced limit.

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.

validateXMLSchemaEnabled

Boolean

false

XML schema validation is enabled?

If set to false or not set, then XML schema validation
is not enabled for the destination.

XMLSchemaURIList

String

null

Space separated list of XML schema document (XSD) URI strings

The URIs point to the location of one or more XSDs to use for XML schema
validation, if enabled.

Use double quotes around this value if multiple URIs are specified.

Example:

“http://foo/flap.xsd http://test.com/test.xsd”

If this property is not set or null and XML validation is enabled, XML
validation is performed using a DTD specified in the XML document.

reloadXMLSchemaOnFailure

Boolean

false

Reload XML schema on failure enabled?

If set to false or not set, then the schema is not reloaded if validation
fails.

Persistence Properties

Message Queue supports both file-based and JDBC-based
persistence modules. The broker property imq.persist.store (Table 16–4) specifies which module to
use. The following sections describe the broker configuration properties for
the two modules.

Table 16–4 Global
Broker Persistence Property

Property

Type

Default Value

Description

imq.persist.store

String

file

Module used for persistent data storage:

file: File-based persistence

jdbc: JDBC-based persistence

Must be set to jdbc for enhanced broker clusters
(imq.cluster.ha = true).

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.

imq.persist.file.transaction.memorymappedfile.enabled

Boolean

true

Use memory-mapped file to store transaction data?

Setting this property to true improves performance
at the cost of increased memory usage. Set to false for
file systems that do not support memory-mapped files.

JDBC-Based Persistence Properties

Table 16–6 lists the broker
properties related to JDBC-based persistence. The first
of these properties, imq.persist.jdbc.dbVendor, identifies
the database vendor being used for the broker’s persistent data store;
all of the remaining properties are qualified by this vendor name.

Table 16–6 Broker Properties
for JDBC-Based Persistence

Property

Type

Default Value

Description

imq.persist.jdbc.dbVendor

String

None

Name of database vendor for persistent data store:

hadb: HADB (Sun Microsystems, Inc.)

derby: Java DB (Sun Microsystems, Inc.)

oracle: Oracle (Oracle Corporation)

mysql: MySQL (Sun Microsystems, Inc.)

postgresql: postgreSQL

imq.persist.jdbc.connection.limit

Integer

5

The maximum number of connections that can be opened to the database.

imq.persist.jdbc.vendorName.driver

String

per vendor

Java class name of JDBC driver, if needed, for
connecting to database from vendor vendorName

imq.persist.jdbc.vendorName.opendburl

String

None

URL for connecting to existing database from vendor vendorName

Applicable when driver is used to connect to database.

imq.persist.jdbc.vendorName.createdburl [Optional]

String

None

URL for creating new database from vendor vendorName

Applies for embedded database, such as Java DB.

imq.persist.jdbc.vendorName.closedburl

String

None

URL for closing connection to database from vendor vendorName

Applies for some embedded databases, such as Java DB.

imq.persist.jdbc.vendorName.user

String

None

User name, if required, for connecting to database from vendor vendorName

For security reasons, the value can instead be specified using command
line options imqbrokerd -dbuser and imqdbmgr -u.

imq.persist.jdbc.vendorName.needpassword

Boolean

false

Does database from vendor vendorName 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.vendorName.password, [Should be used only in password files]

String

None

Password, if required, for connecting to database from vendor vendorName

imq.persist.jdbc.vendorName.property.propName

String

None

Vendor-specific property propName for database
from vendor vendorName

imq.persist.jdbc.vendorName.tableoption

String

None

Vendor-specific options passed to the database when creating the table
schema.

If specified, overrides imq.authentication.type for
the designated connection service.

imq.authentication.client.response.timeout

Integer

180

Interval, in seconds, to wait for client response to authentication
requests

imq.accesscontrol.enabled

Boolean

true

Use access control?

If true, the system will check the access control
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.accesscontrol.type

String

file

Specifies the access control type

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

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

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

String

None

When set to a value of dn, specifies that DN username
format is used for authentication (for example: uid=mquser,ou=People,dc=red,dc=sun,dc=com).

Also, the broker extracts the value of the imq.user.repository.lpdap.uidatr attribute from the DN username, and uses this value as the user
name in access control operations.

Set to the name of the desired entry (in the JAAS configuration
file) that references the login modules you want to use as the authentication
service. This is the name you noted in Step 3.

imq.user_repository.jaas.userPrincipalClass

String

None

This property, used by Message Queue access control, specifies the java.security.Principal implementation class in the login module(s)
that the broker uses to extract the Principal name to represent the user entity
in the Message Queue access control file. If, it is not specified, the user
name passed from the Message Queue client when a connection was requested
is used instead.

imq.user_repository.jaas.groupPrincipalClass

String

None

This property, used by Message Queue access control, specifies the java.security.Principal implementation class in the login module(s)
that the broker uses to extract the Principal name to represent the group
entity in the Message Queue access control file. If, it is not specified,
the user name passed from the Message Queue client when a connection was requested
is used instead.

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

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

Cluster Configuration Properties

imq.cluster.url [Must have the same value for all brokers in a cluster] , [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.ha

Boolean

false

Is broker part of a high-availability cluster?

imq.cluster.brokerlist, [Conventional clusters only]

String

None

List of broker addresses belonging to cluster

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

Note –

If set, this property is ignored (and a warning logged) for high-availability
clusters; all brokers configured to use the cluster’s shared persistent
store are automatically recognized as members of the cluster.

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 16–1) for the cluster connection
service. This might be necessary, for instance, if the broker’s host
computer has more than one interface card installed.

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. You might need to set a different
value, for instance, to specify a static port number for connecting to the
broker through a firewall.

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

String

None

Host name and Port Mapper port number of host on which cluster’s
master broker (if any) is running

The value has the form hostName:portNumber, where hostName is the
host name of the master broker’s host and portNumber is
its Port Mapper port number.

Example:

ctrlhost:7676

Note –

enhanced clusters cannot have a master broker. If this property
is set for a broker belonging to an enhanced cluster, the broker
will log a warning message and ignore the property.

imq.cluster.clusterid [enhanced clusters only] ,

String

None

Cluster
identifier

Must be a unique alphanumeric string of no more than n–13
characters, where n is the maximum table name length
allowed by the database. No two running clusters may have the same cluster
identifier.

This string is appended to the names of all database tables in the cluster’s
shared persistent store.

Note –

For brokers belonging to a high-availability cluster, this property
is used in database table names in place of imq.brokerid (see Table 16–1).

A value of 0 specifies that the port number should
be allocated dynamically by the Port Mapper.

imq.cluster.heartbeat.interval

Integer

2

Interval between heartbeats, in seconds

imq.cluster.heartbeat.threshold

Integer

3

Number of missed heartbeat intervals after which to invoke monitor service

imq.cluster.monitor.interval

Integer

30

Interval, in seconds, at which to update monitor time stamp

Note –

Larger values for this property will reduce the frequency of database
access and thus improve overall system performance, but at the cost of slower
detection and takeover in the event of broker failure.

imq.cluster.monitor.threshold

Integer

2

Number of missed monitor intervals after which to initiate broker takeover

JMX Properties

The broker properties listed in Table 16–12 support the use of the Java Management Extensions (JMX)
application programming interface by Java applications. The JMX API is used
to configure and monitor broker resources.

These JMX-related properties can be set in the broker's instance configuration
file (config.properties) or at broker startup with the -D option of the Broker utility (imqbrokerd). None
of these properties can be set dynamically with the Command utility (imqcmd).

In addition, some of these properties (imq.jmx.rmiregistry.start, imq.jmx.rmiregistry.use, imq.jmx.rmiregistry.port) can be set with corresponding Broker utilityimqbrokerd options described in Table 15–1.

Names of JMX connectors to be activated at broker
startup, separated by commas

imq.jmx.connector.RMIconnectorName.urlpath

String

Shown in next column

urlpath component of JMX service URL for connector connectorName

Useful in cases where an RMI registry is being used and the JMX service
URL path must be set explicitly (such as when a shared external RMI registry
is used). See The JMX Service URL.

Default:

/jndi/rmi://brokerHost:rmiPort /brokerHost/brokerPort/connectorName

imq.jmx.connector.RMIconnectorName.port

Integer

None: the port is dynamically allocated

Port number of JMX connector

Used to specify a static/known JMX connector port, typically in cases
where a JMX client is accessing the broker's MBean server through a firewall.
See JMX Connections Through a Firewall.

imq.jmx.connector.RMIconnectorName.useSSL

Boolean

false

Use Secure Socket Layer (SSL) for connector connectorName?

This property is set to true for the ssljmxrmi connector.

imq.jmx.connector.RMIconnectorName.brokerHostTrusted

Boolean

false

Trust any certificate presented by broker for connector connectorName?

Applies only when imq.jmx.connector.connectorName.useSSL is true.

If false, the JMX 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.

imq.jmx.rmiregistry.start

Boolean

false

Start RMI registry at broker startup?

If true, the broker will start an RMI registry at
the port specified by imq.jmx.rmiregistry.port and
use the regsitry to store the JMX connector stub. (The value of imq.jmx.rmiregistry.use is ignored in this
case.)

For convenience, this property can also be set at broker startup with
the -startRmiRegistry option ofimqbrokerd.

imq.jmx.rmiregistry.use

Boolean

false

Use an existing RMI registry?

Applies only if imq.jmx.rmiregistry.start is false.

If true, the broker will use an existing RMI registry
on the local host at the port specified by imq.jmx.rmiregistry.port to store the JMX connector stub. The existing
RMI registry must already be running at broker startup.

For convenience, this property can also be set at broker startup with
the -useRmiRegistry option ofimqbrokerd.

imq.jmx.rmiregistry.port

Integer

1099

Port number of RMI registry

Applies only if imq.jmx.rmiregistry.start is true or imq.jmx.rmiregistry.use is true.

This port number will be included in the URL path of the JMX service
URL.

For convenience, this property can also be set at broker startup with
the -rmiRegistryPort option of imqbrokerd.

Chapter 17 Physical Destination Property Reference

Physical Destination Properties

Table 17–1 lists the 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 16–3).

Table 17–1 Physical
Destination Properties

Property

Type

Default Value

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.

Note –

When flow control is in effect (limitBehavior = FLOW_CONTROL), it is possible for the specified message limit to
be exceeded because the broker cannot react quickly enough to stop the flow
of incoming messages. In such cases, the value specified for maxNumMsgs serves as merely a hint for the broker rather than a strictly
enforced limit.

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 [Does not apply to dead message queue]

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.

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.

This property used mostly in cases where message order is important
and you want to provide backup consumers in case the principal consumer of
a queue fails. If message order is not important, then you would simply use
multiple consumers to provide for scalability and availability.

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.

consumerFlowLimit

Integer

1000

Maximum number of messages delivered
to consumer(s) 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.

The client runtime can override this limit by specifying a lower value
on the connection factory object..

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.

validateXMLSchemaEnabled

[This property should be set when a destination is inactive: when it
has no consumers or producers and when there are no messages in the destination.
Otherwise the producer must reconnect.]

Boolean

false

XML schema validation is enabled?

When XML validation is enabled, the Message Queue client runtime will
attempt to validate an XML message against the specified XSDs (or against
the DTD, if no XSD is specified) before sending it to the broker. If the specified
schema cannot be located or the message cannot be validated, the message is
not sent, and an exception is thrown. Client applications using this feature
should use JRE 1.5 or above.

If set to false or not set, then XML schema validation
is not enabled for the destination.

XMLSchemaURIList

String

null

Space separated list of XML schema document (XSD) URI strings

The URIs point to the location of one or more XSDs to use for XML schema
validation, if enabled.

Use double quotes around this value if multiple URIs are specified.

Example:

“http://foo/flap.xsd http://test.com/test.xsd”

If this property is not set or null and XML validation is enabled, XML
validation is performed using a DTD specified in the XML document.

if an XSD is changed, as a result of changing application requirements,
all client applications producing XML messages based on the changed XSD must
reconnect to the broker.

reloadXMLSchemaOnFailure

Boolean

false

Reload XML schema on failure enabled?

If set to true and XML validation fails, then the Message Queue client
runtime will attempt to reload the XSD before attempting again to validate
a message. The client runtime will throw an exception if the validation fails
using the reloaded SXD.

If set to false or not set, then the schema is not reloaded if validation
fails.

Chapter 18 Administered Object Attribute Reference

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

Connection Handling

An existing Message Queue 3.0 address, if any; if none, the first entry
in Table 18–2

List of broker addresses

The list consists of one or more 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.

Note –

In an enhanced broker
cluster, the value of this attribute is updated dynamically as brokers enter
and leave the cluster, so that it always reflects the cluster’s current
membership.

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

1

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.

Note –

In the event of broker failure in an enhanced broker cluster,
this attribute is ignored and the Message Queue client runtime iterates through
the address list indefinitely until it succeeds in reconnecting to a takeover
broker. The effect is equivalent to an imqAddressListIterations value
of -1, overriding any other explicit or default setting
of this attribute. The only way for a client application to avoid this behavior
is to close the connection explicitly on broker failure.

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?

Note –

In the event of broker failure in an enhanced broker cluster,
this attribute is ignored and automatic reconnection is always attempted.
The effect is equivalent to an imqReconnectEnabled value
of true, overriding any other explicit or default setting
of this attribute. The only way for a client application to avoid this behavior
is to close the connection explicitly on broker failure.

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. For example, in an enhanced broker cluster, this value
will allow for connection to the failover broker.

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

false

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

Reliability and Flow Control

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

Attribute

Type

Default Value

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

1000

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

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

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 18–9 lists the attributes
that can be set for a destination administered object.

Table 18–9 Destination
Attributes

Attribute

Type

Default Value

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

Chapter 19 JMS Resource Adapter Property
Reference

This chapter describes the configuration properties of the Message Queue JMS Resource Adapter (JMS RA),
which enables you to integrate Sun JavaTM System 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 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 19–1 lists
and describes the properties with which you can configure this JavaBean.

Table 19–1 Resource
Adapter Properties

Property

Type

Default Value

Description

addressList [Exactly one of these properties must be specified]

String

mq://localhost:7676/jms

Message service address for connecting to Message Queue service

Equivalent to connectionURL (below).

connectionURL

String

mq://localhost:7676/jms

Message service address for connecting to the Message Queue service

Equivalent to addressList(above).

brokerInstanceName

String

imqbroker

Name of broker instance

brokerPort

Integer

7676

Port number for connecting to broker

brokerBindAddress

String

Null

Address to which broker binds on host machine

If null, the broker will bind to all addresses on the host machine.

userName [Required]

String

guest

Default user name for connecting to Message Queue service

password

String

guest

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

brokerEnableHA

Boolean

false

Enable high availability?

clusterID

String

None

Cluster identifier

If specified, only brokers with the same cluster identifier can be clustered
together. In the event of broker failure, client connections will fail over
only to brokers with the same cluster identifier as the original broker. If
not specified, client connections can fail over to any other broker with an
unspecified cluster identifier.

For standalone brokers (those not belonging to a cluster), this property
is ignored.

The identifier may contain only alphabetic letters (A–Z, a–z), numeric digits
(0–9), and the underscore character
(_).

brokerID

String

None

Broker identifier

For brokers using a JDBC-based persistent data store,
this string is appended to the names of all database tables to make them unique
in the case where more than one broker instance is using the same database.
For brokers using a file-based data store, this property is ignored.

In an enhanced cluster, each broker must have a unique broker
identifier.

The identifier may contain only alphabetic letters (A–Z, a–z), numeric digits
(0–9), and the underscore character
(_).

ManagedConnectionFactory JavaBean

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

List of message service addresses for connecting to Message Queue service

userName [Optional]

String

guest

User name for connecting to Message Queue service

password

String

guest

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

The value must be that of the destinationName property
for a Message Queue destination administered object.

destinationType

String

None

Type of destination specified by destination property:

javax.jms.Queue: Queue destination

javax.jms.Topic: Topic destination

messageSelector,

String

None

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

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 20 Metrics Information Reference

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

Through JMX MBeans that can be accessed programmatically by
Java applications using the JMX Administration API.

The tables in this chapter list the kinds of metrics information available
and the forms in which it can be provided. For metrics provided through the
Command utility’s imqcmd metrics subcommand, 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. All the metrics information in this chapter can be accessed
progamatically using the JMX Administration API as described in the Message Queue Developer’s Guide for JMX Clients

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

Physical Destination Metrics

Table 20–4 shows the metrics
information that the broker reports for individual destinations.

Table 20–4 Physical
Destination Metrics

Metrics Quantity

Description

Log File?

metricsdstMetric
Type

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

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

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

Chapter 21 JES Monitoring Framework
Reference

This chapter describes the monitoring information items that Message Queue exposes
through the Sun JavaTM Enterprise System Monitoring Framework
(JESMF), using the Monitoring Framework’s Common
Monitoring Model (CMM). It contains the following sections:

Number of threads beyond which no new threads are added to thread pool
for use by connection service (broker property imq.serviceName.max_threads; see Table 16–1)

NumProducers

Current number of message producers

NumConsumers

Current number of message consumers

NumMsgsIn

Cumulative number of messages received since broker started

NumMsgsOut

Cumulative number of messages sent since broker started

InBytesCount

Cumulative size in bytes of messages received since broker started

OutBytesCount

Cumulative size in bytes of messages sent since broker started

NumPktsIn

Cumulative number of packets received since broker started

NumPktsOut

Cumulative number of packets sent since broker started

PktBytesIn

Cumulative size in bytes of packets received since broker started

PktBytesOut

Cumulative size in bytes of packets sent since broker started

Destination Information

Table 21–6 shows the JESMF-accessible attributes pertaining to each destination. Each of these
attributes corresponds to a Message Queue physical destination property; see Table 17–1 for further information.

Table 21–6 JESMF-Accessible Message Queue Destination
Attributes

Attribute

Corresponding Property

Description

Type

Destination type (q = queue, t =
topic)

MaxNumMsgs

maxNumMsgs

Maximum number of unconsumed messages

MaxBytesPerMsg

maxBytesPerMsg

Maximum size, in bytes, of any single message

MaxTotalMsgBytes

maxTotalMsgBytes

Maximum total memory, in bytes, for unconsumed messages

LimitBehavior

limitBehavior

Broker behavior when memory-limit threshold reached

MaxNumProducers [Does not apply to dead message queue]

maxNumProducers

Maximum number of associated message producers

MaxNumActiveConsumers [Queue destinations only]

maxNumActiveConsumers

Maximum number of associated active message consumers in load-balanced
delivery

MaxNumBackupConsumers

maxNumBackupConsumers

Maximum number of associated backup message consumers in load-balanced
delivery

ConsumerFlowLimit

consumerFlowLimit

Maximum number of messages delivered to consumer in a single batch

LocalOnly

isLocalOnly

Local delivery only?

LocalDeliveryPreferred,

localDeliveryPreferred

Local delivery preferred?

UseDMQ

useDMQ

Send dead messages to dead message queue?

Persistent Store Information

The attributes shown in Table 21–7 pertain
to the persistent data store.

Table 21–7 JESMF-Accessible Message Queue Persistent
Store Attributes

Attribute

Description

AccessInfo

URL for accessing JDBC database

InfoFormat

Format of AccessInfo attribute (URL)

JDBCDriver

JDBC driver

UserName

User name for authentication

User Repository Information

The attributes shown in Table 21–8 pertain
to the LDAP user repository.