Administering JMS objects

Objects that can be manipulated by administration commands.

Object Type Keyword Description
MQQueueConnectionFactory
 QCF
 JMS QueueConnectionFactory. Create connections in the point-to-point domain
MQTopicConnectionFactory
 TCF
 JMS TopicConnectionFactory. Create connections in the publish/subscribe domain
MQQueue
 Q
 JMS Queue. Destination for messages in the point-to-point domain
MQTopic
 T
 JMS Topic Destination for messages in the publish/subscribe domain
MQXAQueueConnectionFactory1
 XAQCF
 JMS XAQueueConnectionFactory. Create connections in the point-to-point domain of JMS that use the XA versions of JMS classes.
MQXATopicConnectionFactory1
 XATCF
 JMS XATopicConnectionFactory. Create connections in the publish/subscribe domain of JMS that use the XA versions of JMS classes.
JMSWrapXAQueueConnectionFactory2
 WSQCF
 JMS QueueConnectionFactory. Create connections in the point-to-point domain of JMS that use the XA versions of JMS classes with WAS.
JMSWrapXATopicConnectionFactory2
 WSTCF
 JMS TopicConnectionFactory interface. Create connections in the publish/subscribe domain of JMS that use the XA versions of JMS classes with WAS.

  1. These classes are provided for use by vendors of appservers. They are unlikely to be directly useful to application programmers.

  2. Use this style of ConnectionFactory if you want your JMS sessions to participate in global transactions that are coordinated by WebSphere Application Server.

 

Verbs used with JMS objects

You can use the verbs ALTER, DEFINE, DISPLAY, DELETE, COPY, and MOVE to manipulate administered objects in the directory namespace.

Command syntax Description
ALTER TYPE(name) [ property ]*
 Attempts to update the given administered object's properties with the ones supplied. Fails if there is a security violation, if the specified object cannot be found, or if the new properties supplied are not valid.
DEFINE TYPE(name) [ property ]*
 Attempts to create an administered object of type TYPE with the supplied properties, and store it under the name name in the current context.
Fails if there is a security violation, if the supplied name is not valid or already exists, or if the properties supplied are not valid.
DISPLAY TYPE(name)
 Displays the properties of the administered object of type TYPE, bound under the name name in the current context.
Fails if the object does not exist, or if there is a security violation.
DELETE TYPE(name)
 Attempts to remove the administered object of type TYPE, having the name name, from the current context.
Fails if the object does not exist, or if there is a security violation.
COPY TYPE(nameA)
TYPE(nameB)

 Makes a copy of the administered object of type TYPE, having the name nameA, naming the copy nameB. This all occurs within the scope of the current context.
Fails if the object to be copied does not exist, if an object of name nameB already exists, or if there is a security violation.
MOVE TYPE(nameA) TYPE(nameB)
 Moves (renames) the administered object of type TYPE, having the name nameA, to nameB. This all occurs within the scope of the current context.
Fails if the object to be moved does not exist, if an object of name nameB already exists, or if there is a security violation.

 

Creating objects

Objects are created and stored in a JNDI namespace using the following command syntax: 

DEFINE TYPE(name) [ property ]*

That is, the DEFINE verb, followed by a TYPE(name) administered object reference, followed by zero or more properties.

 

LDAP naming considerations

To store your objects in an LDAP environment, give them names that comply with certain conventions. One of these is that object and subcontext names must include a prefix, such as cn= (common name), or ou= (organizational unit).

The administration tool simplifies the use of LDAP service providers by allowing you to refer to object and context names without a prefix. If you do not supply a prefix, the tool automatically adds a default prefix to the name you supply. For LDAP this is cn=.

You can change the default prefix by setting the NAME_PREFIX property in the JMSAdmin configuration file, as described in Using an unlisted InitialContextFactory.

This is shown in the following example. 

InitCtx> DEFINE Q(testQueue)
 
InitCtx> DISPLAY CTX
 
    Contents of InitCtx
 
      a  cn=testQueue              com.ibm.mq.jms.MQQueue
 
     1 Object(s)
       0 Context(s)
       1 Binding(s), 1 Administered

Note that, although the object name supplied (testQueue) does not have a prefix, the tool automatically adds one to ensure compliance with the LDAP naming convention. Likewise, submitting the command DISPLAY Q(testQueue) also causes this prefix to be added.

You might need to configure your LDAP server to store Java objects. Information to assist with this configuration is provided in Appendix C, LDAP schema definition for storing Java objects.

 

Properties

A property consists of a name-value pair in the format: 

PROPERTY_NAME(property_value)

For example: 

# ./JMSAdmin"
InitCtx> def tcf(CacheInvalidationTopic) brokerver(v1)

Property Short form Valid values (defaults in bold)
BROKERCCDSUBQ
 CCDSUB

  • SYSTEM.JMS.D.CC.SUBSCRIBER.QUEUE
  • Any string

BROKERCCSUBQ
 CCSUB

  • SYSTEM.JMS.ND.CC.SUBSCRIBER.QUEUE
  • Any string

BROKERCONQ
 BCON
 Any string
BROKERDURSUBQ
 BDSUB

  • SYSTEM.JMS.D.SUBSCRIBER.QUEUE
  • Any string

BROKERPUBQ
 BPUB


BROKERQMGR
 BQM
 Any string
BROKERSUBQ
 BSUB

  • SYSTEM.JMS.ND.SUBSCRIBER.QUEUE
  • Any string

BROKERVER
 BVER

  • V1 - To use the WebSphere MQ broker. Also to use the WebSphere MQ Integrator V2 or WebSphere MQ Event Broker brokers in compatibility mode.
  • V2 - To use the WebSphere MQ Integrator V2 or WebSphere MQ Event Broker brokers in native mode

CCSID
 CCS
 Any positive integer
CHANNEL
 CHAN
 Any string
CLEANUP
 CL

  • SAFE
  • ASPROP
  • NONE
  • STRONG

CLEANUPINT
 CLINT

  • 60000
  • Any positive integer

CLIENTID
 CID
 Any string
DESCRIPTION
 DESC
 Any string
ENCODING
 ENC
 See The ENCODING property
EXPIRY
 EXP

  • APP - Expiry may be defined by the JMS application.
  • UNLIM - No expiry occurs.
  • Any positive integer representing expiry in milliseconds.

FAILIFQUIESCE
 FIQ
  • Yes - Applications return from a method call if the queue manager has entered a controlled shutdown.
  • No - Applications continue to carry out operations against a quiescing queue manager, preventing that queue manager's shutdown.

HOSTNAME
 HOST

  • localhost
  • Any string

MSGBATCHSZ
 MBS

  • 10
  • Any positive integer

MSGRETENTION
 MRET
  • Yes - Unwanted messages remain on the input queue
  • No - Unwanted messages are dealt with according to their disposition options

PERSISTENCE
 PER

  • APP - Persistence is defined by the JMS application.
  • QDEF - Persistence takes the value of the queue default.
  • PERS - Messages are persistent.
  • NON - Messages are non-persistent.

POLLINGINT
 PINT

  • 5000
  • Any positive integer

PORT

  • 1414 (for TRANSPORT set to BIND or CLIENT); 1506 (for TRANSPORT set to DIRECT)
  • Any positive integer

PRIORITY
 PRI

  • APP - Priority is defined by the JMS application.
  • QDEF - Priority takes the value of the queue default.
  • Any integer in the range 0-9.

PUBACKINT
 PAI

  • 25
  • Any positive integer

QMANAGER
 QMGR
 Any string
QUEUE
 QU
 Any string
RECEXIT
 RCX
 Any string
RECEXITINIT
 RCXI
 Any string
SECEXIT
 SCX
 Any string
SECEXITINIT
 SCXI
 Any string
SENDEXIT
 SDX
 Any string
SENDXITINIT
 SDXI
 Any string
SSLCIPHERSUITE
 SCPHS


SSLCRL
 SCRL


SSLPEERNAME
 SPEER


STATREFRESHINT
 SRI

  • 60000
  • Any positive integer

SUBSTORE
 SS

  • MIGRATE
  • QUEUE
  • BROKER

SYNCPOINTALLGETS
 SPAG

  • No
  • Yes

TARGCLIENT
 TC

  • JMS - The target of the message is a JMS application.
  • MQ - The target of the message is a non-JMS WebSphere MQ application.

TEMPMODEL
 TM
 Any string
TOPIC
 TOP
 Any string
TRANSPORT
 TRAN

  • BIND - Connections use WebSphere MQ bindings.
  • CLIENT - For a client connection
  • DIRECT - For direct connection to WebSphere MQ Event Broker broker

USECONNPOOLING
 UCP

  • Yes
  • No

Many of the properties are relevant only to a specific subset of the object types. Object types are identified using keywords; refer to Table 9 for an explanation of these.

Numbers refer to notes at the end of the table. See also Property dependencies. Appendix A, Mapping between administration tool properties and programmable properties shows the relationship between properties set by the tool and programmable properties.

Property QCF TCF Q T XAQCF
 XATCF
 Description
BROKERCCDSUBQ





Y



The name of the queue from which durable subscription messages are retrieved for a ConnectionConsumer
BROKERCCSUBQ
Y



Y The name of the queue from which non-durable subscription messages are retrieved for a ConnectionConsumer
BROKERCONQ
Y



Y Broker's control queue name
BROKERDURSUBQ


Y



The name of the queue from which durable subscription messages are retrieved
BROKERPUBQ
Y



Y The name of the broker input queue (stream queue)
BROKERQMGR
Y



Y The queue manager on which the broker is running
BROKERSUBQ
Y



Y The name of the queue from which non-durable subscription messages are retrieved
BROKERVER
Y
Y

Y The version of the broker being used
CCSID
 Y Y Y Y



The coded-character-set-ID to be used on connections
CHANNEL
 Y Y





The name of the client connection channel being used
CLEANUP
Y



Y Cleanup Level for BROKER or MIGRATE Subscription Stores
CLEANUPINT
Y



Y The interval between background executions of the publish/subscribe cleanup utility
CLIENTID
 Y Y

Y Y A string identifier for the client
DESCRIPTION
 Y Y Y Y Y Y A description of the stored object
ENCODING

Y Y



The encoding scheme used for this destination
EXPIRY

Y Y



The period after which messages at a destination expire
HOSTNAME Y Y>





The name of the host on which the queue manager or WebSphere MQ Event Broker broker resides. A dotted-decimal TCP/IP address can also be used.
MSGBATCHSZ
 Y Y

Y Y The maximum number of messages to be taken from a queue in one packet when using asynchronous message delivery
MSGRETENTION
 Y


Y

Whether or not the connection consumer keeps unwanted messages on the input queue
PERSISTENCE

Y Y



The persistence of messages sent to a destination
PRIORITY

Y Y



The priority for messages sent to a destination
POLLINGINT
 Y Y

Y Y The interval, in milliseconds, between scans of all receivers during asynchronous message delivery
PORT Y Y





The port on which the queue manager or broker listens
PUBACKINT
Y



Y The interval, in number of messages, between publish requests that require acknowledgement from the broker
QMANAGER
 Y Y Y
Y Y The name of the queue manager to connect to
QUEUE

Y




The underlying name of the queue representing this destination
RECEXIT
 Y Y





The fully-qualified class name of the receive exit being used
RECEXITINIT
 Y Y





The receive exit initialization string
SECEXIT
 Y Y





The fully-qualified class name of the security exit being used
SECEXITINIT
 Y Y





The security exit initialization string
SENDEXIT
 Y Y





The fully-qualified class name of the send exit being used
SENDEXITINIT
 Y Y





The send exit initialization string
SSLCIPHERSUITE
 Y Y





The cipher suite to use for SSL connection
SSLCRL
 Y Y





CRL servers to check for SSL certificate revocation
SSLPEERNAME
 Y Y





For SSL, a distinguished name skeleton that must match that provided by the queue manager
STATREFRESHINT
Y



Y The interval, in milliseconds, between transactions to refresh publish/subscribe status
SUBSTORE
Y



Y Where WebSphere MQ JMS should store persistent data relating to active subscriptions
SYNCPOINTALLGETS
 Y Y

Y Y Whether all gets should be performed under syncpoint
TARGCLIENT

Y Y



Whether the WebSphere MQ RFH2 format is used to exchange information with target applications
TEMPMODEL
 Y


Y

The name of the model queue from which temporary queues are created
TOPIC


Y



The underlying name of the topic representing this destination
TRANSPORT Y Y

Y
 Y Whether connections use the WebSphere MQ bindings, a client connection, or WebSphere MQ Event Broker.
USECONNPOOLING
 Y Y

Y Y Whether to use connection pooling

Notes:

  1. For WSTCF, WSQCF, XATCF, and XAQCF objects, only the BIND transport type is allowed.

  2. The TARGCLIENT property indicates whether the WebSphere MQ RFH2 format is used to exchange information with target applications.

    The MQJMS_CLIENT_JMS_COMPLIANT constant indicates that the RFH2 format is used to send information. Applications that use WebSphere MQ JMS understand the RFH2 format. Set the MQJMS_CLIENT_JMS_COMPLIANT constant when you exchange information with a target WebSphere MQ JMS application.

    The MQJMS_CLIENT_NONJMS_MQ constant indicates that the RFH2 format is not used to send information. Typically, this value is used for an existing WebSphere MQ application (that is, one that does not handle RFH2).

  3. HOSTNAME, PORT, and TRANSPORT are also used to identify if you are connecting to WebSphere MQ Event Broker and the broker's IP hostname and listening port.

  4. Only the BROKERVER, CLIENTID, DESCRIPTION, HOSTNAME, PORT, and TRANSPORT properties are supported for a TopicConnectionFactory used with a direct connection across TCP/IP to WebSphere MQ Event Broker.

 

Property dependencies

Some properties have dependencies on each other. This might mean that it is meaningless to supply a property unless another property is set to a particular value. The specific property groups where this can occur are

  • Client properties

  • Properties for connecting to WebSphere MQ Event Broker

  • Exit initialization strings

Client properties
Some properties are only relevant to a connection with the TRANSPORT property set to the value CLIENT. If this property is not explicitly set on a connection factory to one of the values CLIENT or DIRECT, the transport used on connections provided by the factory is WebSphere MQ Bindings. Consequently, none of the client properties on this connection factory can be configured. These are:

  • HOST
  • PORT
  • CHANNEL
  • CCSID
  • RECEXIT
  • RECEXITINIT
  • SECEXIT
  • SECEXITINIT
  • SENDEXIT
  • SENDEXITINIT
  • SSLCIPHERSUITE
  • SSLCRL
  • SSLPEERNAME

It is an error to set any of these properties without setting the TRANSPORT property to CLIENT (or, for some, DIRECT; see Properties for connecting to WebSphere MQ Event Broker).

Properties for connecting to WebSphere MQ Event Broker

The only properties used with a direct connection to WebSphere MQ Event Broker are BROKERVER, CLIENTID, DESCRIPTION, HOSTNAME, PORT, and TRANSPORT.

The default values for PORT and BROKERVER are set by the definition of TRANSPORT:

  1. Defining a connection factory with TRANSPORT as CLIENT sets:

    • BROKERVER to V1

    • PORT to 1414

  2. Defining a connection factory with TRANSPORT as DIRECT sets:

    • BROKERVER to V2

    • PORT to 1506

If you explicitly set the value of PORT or BROKERVER, a later change to the value of TRANSPORT does not override your choices.

Exit initialization strings
Do not set any of the exit initialization strings without supplying the corresponding exit name. The exit initialization properties are:

  • RECEXITINIT

  • SECEXITINIT

  • SENDEXITINIT

For example, specifying RECEXITINIT(myString) without specifying RECEXIT(some.exit.classname) causes an error.

 

The ENCODING property

The valid values that the ENCODING property can take are constructed from three sub-properties:

integer encoding
Either normal or reversed

decimal encoding
Either normal or reversed

floating-point encoding
IEEE normal, IEEE reversed, or z/OS.

The ENCODING is expressed as a three-character string with the following syntax: 

{N|R}{N|R}{N|R|3}

In this string:

  • N denotes normal

  • R denotes reversed

  • 3 denotes z/OS

  • The first character represents integer encoding

  • The second character represents decimal encoding

  • The third character represents floating-point encoding

This provides a set of twelve possible values for the ENCODING property.

There is an additional value, the string NATIVE, which sets appropriate encoding values for the Java platform.

The following examples show valid combinations for ENCODING: 

     ENCODING(NNR)
	     ENCODING(NATIVE)
	     ENCODING(RR3)

 

SSL properties

When you specify TRANSPORT(CLIENT), you can enable SSL encrypted communication using the SSLCIPHERSUITE property. Set this property to a valid CipherSuite provided by your JSSE provider; it must match the CipherSpec named on the SVRCONN channel named by the CHANNEL property.

However, CipherSpecs (as specified on the SVRCONN channel) and CipherSuites (as specified on ConnectionFactory objects) use different naming schemes to represent the same SSL encryption algorithms. If a recognized CipherSpec name is specified on the SSLCIPHERSUITE property, JMSAdmin issues a warning and maps the CipherSpec to its equivalent CipherSuite. See Appendix H, SSL CipherSuites supported by WebSphere MQ for a list of CipherSpecs recognized by WebSphere MQ and JMSAdmin.

The SSLPEERNAME matches the format of the SSLPEER parameter, which can be set on channel definitions. It is a list of attribute name and value pairs separated by commas or semicolons. For example: 

  SSLPEERNAME(CN=QMGR.*, OU=IBM, OU=WEBSPHERE)

The set of names and values makes up a distinguished name. For more details about distinguished names and their use with WebSphere MQ, see the WebSphere MQ Security book.

The example given checks the identifying certificate presented by the server at connect-time. For the connection to succeed, the certificate must have a Common Name beginning QMGR., and must have at least two Organizational Unit names, the first of which is IBM and the second WEBSPHERE. Checking is case-insensitive.

If SSLPEERNAME is not set, no such checking is performed. SSLPEERNAME is ignored if SSLCIPHERSUITE is not specified.

The SSLCRL property specifies zero or more CRL (Certificate Revocation List) servers. Use of this property requires a JVM at Java 2 v1.4. This is a space-delimited list of entries of the form: 

  ldap://hostname:[ port ]

optionally followed by a single /. If port is omitted, the default LDAP port of 389 is assumed. At connect-time, the SSL certificate presented by the server is checked against the specified CRL servers. See the WebSphere MQ Security book for more about CRL security.

If SSLCRL is not set, no such checking is performed. SSLCRL is ignored if SSLCIPHERSUITE is not specified.

 

Sample error conditions

This section provides examples of the error conditions that might arise while creating an object.

CipherSpec mapped to CipherSuite
InitCtx/cn=Trash> DEFINE QCF(testQCF) SSLCIPHERSUITE(RC4_MD5_US)
	  WARNING: Converting CipherSpec RC4_MD5_US to 
	  CipherSuite SSL_RSA_WITH_RC4_128_MD5

Invalid property for object
InitCtx/cn=Trash> DEFINE QCF(testQCF) PRIORITY(4)
	  Unable to create a valid object, please check the parameters supplied
	  Invalid property  for a QCF: PRI

Invalid type for property value
InitCtx/cn=Trash> DEFINE QCF(testQCF) CCSID(english)
	  Unable to create a valid object, please check the parameters supplied
	  Invalid value for CCS property: English

Property clash - client/bindings
InitCtx/cn=Trash> DEFINE QCF(testQCF) HOSTNAME(polaris.hursley.ibm.com)
	  Unable to create a valid object, please check the parameters supplied
	  Invalid property in this context: Client-bindings attribute clash

Property clash - Exit initialization
InitCtx/cn=Trash> DEFINE QCF(testQCF) SECEXITINIT(initStr)
	  Unable to create a valid object, please check the parameters supplied
	  Invalid property in this context: ExitInit string supplied
	  without Exit string

Property value outside valid range
InitCtx/cn=Trash> DEFINE Q(testQ) PRIORITY(12)
	  Unable to create a valid object, please check the parameters supplied
	  Invalid value for PRI property: 12

Unknown property
InitCtx/cn=Trash> DEFINE QCF(testQCF) PIZZA(ham and mushroom)
  Unable to create a valid object, please check the parameters supplied
  Unknown property: PIZZA

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.