Administering JMS objects

This section describes the eight types of object that the administration tool can handle. It includes details about each of their configurable properties and the verbs that can manipulate them.

Object types

Table 9 shows the eight types of administered objects. The Keyword column shows the strings that you can substitute for TYPE in the commands shown in Table 10.

Table 9. The JMS object types that are handled by the administration tool
Object Type Keyword Description
MQConnectionFactory CF The WebSphere(R) MQ implementation of the JMS ConnectionFactory interface. This represents a factory object for creating connections in the both the point-to-point and publish/subscribe domains.
MQQueueConnectionFactory QCF The WebSphere MQ implementation of the JMS QueueConnectionFactory interface. This represents a factory object for creating connections in the point-to-point domain.
MQTopicConnectionFactory TCF The WebSphere MQ implementation of the JMS TopicConnectionFactory interface. This represents a factory object for creating connections in the publish/subscribe domain.
MQQueue Q The WebSphere MQ implementation of the JMS Queue interface. This represents a destination for messages in the point-to-point domain.
MQTopic T The WebSphere MQ implementation of the JMS Topic interface. This represents a destination for messages in the publish/subscribe domain.
MQXAConnectionFactory1 XACF The WebSphere MQ implementation of the JMS XAConnectionFactory interface. This represents a factory object for creating connections in both the point-to-point and publish/subscribe domains, and where the connections use the XA versions of JMS classes.
MQXAQueueConnectionFactory1 XAQCF The WebSphere MQ implementation of the JMS XAQueueConnectionFactory interface. This represents a factory object for creating connections in the point-to-point domain that use the XA versions of JMS classes.
MQXATopicConnectionFactory1 XATCF The WebSphere MQ implementation of the JMS XATopicConnectionFactory interface. This represents a factory object for creating connections in the publish/subscribe domain that use the XA versions of JMS classes.
Notes:
  1. These classes are provided for use by vendors of application servers. They are unlikely to be directly useful to application programmers.

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. Table 10 summarizes their use. Substitute TYPE with the keyword that represents the required administered object, as listed in Table 9.

Table 10. Syntax and description of commands used to manipulate administered objects
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 (see Properties).

LDAP naming considerations

To store your objects in an LDAP environment, you must 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(TM) objects. For information to assist with this configuration, see the documentation for your LDAP server.

Properties

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

PROPERTY_NAME(property_value)

Property names are not case-sensitive, and are restricted to the set of recognized names shown in Table 11. This table also shows the valid property values for each property.

Table 11. Property names and valid values
Property Short form Valid values (defaults in bold)
BROKERCCDSUBQ1 CCDSUB
BROKERCCSUBQ CCSUB
BROKERCONQ BCON Any string
BROKERDURSUBQ1 BDSUB
BROKERPUBQ BPUB
  • SYSTEM.BROKER.DEFAULT.STREAM
  • Any string
BROKERPUBQMGR BPQM Any string
BROKERQMGR BQM Any string
BROKERSUBQ BSUB
BROKERVER BVER
  • V1 - To use a WebSphere MQ Publish/Subscribe broker, or to use a broker of WebSphere MQ Integrator, WebSphere MQ Event Broker, WebSphere Business Integration Event Broker, or WebSphere Business Integration Message Broker in compatibility mode. This is the default value if TRANSPORT is set to BIND or CLIENT.
  • V2 - To use a broker of WebSphere MQ Integrator, WebSphere MQ Event Broker, WebSphere Business Integration Event Broker, or WebSphere Business Integration Message Broker in native mode. This is the default value if TRANSPORT is set to DIRECT or DIRECTHTTP.
CCDTURL2 CCDT
  • Not set
  • A uniform resource locator (URL)
CCSID CCS Any positive integer
CHANNEL2 CHAN Any string
CLEANUP CL
  • SAFE
  • ASPROP
  • NONE
  • STRONG
CLEANUPINT CLINT
  • 3600000
  • Any positive integer
CLIENTID CID Any string
CLONESUPP CLS
  • DISABLED - Only one instance of a durable topic subscriber can run at a time.
  • ENABLED3 - Two or more instances of the same durable topic subscriber can run simultaneously, but each instance must run in a separate Java virtual machine (JVM).
COMPHDR HC
  • NONE
  • SYSTEM
COMPMSG MC
  • NONE
  • A list of one or more of the following values separated by blank characters:
    • RLE
    • ZLIBFAST
    • ZLIBHIGH
CONNOPT4 CNOPT
  • STANDARD - The nature of the binding between the application and the queue manager depends on the platform on which the queue manager is running and how the queue manager is configured.
  • SHARED - The application and the local queue manager agent run in separate units of execution but share some resources.
  • ISOLATED - The application and the local queue manager agent run in separate units of execution and share no resources.
  • FASTPATH - The application and the local queue manager agent run in the same unit of execution.
  • SERIALQM - The application requests exclusive use of the connection tag within the scope of the queue manager.
  • SERIALQSG - The application requests exclusive use of the connection tag within the scope of the queue sharing group to which the queue manager belongs.
  • RESTRICTQM - The application requests shared use of the connection tag, but there are restrictions on the shared use of the connection tag within the scope of the queue manager.
  • RESTRICTQSG - The application requests shared use of the connection tag, but there are restrictions on the shared use of the connection tag within the scope of the queue sharing group to which the queue manager belongs.
CONNTAG CNTAG Any string
DESCRIPTION DESC Any string
DIRECTAUTH DAUTH
  • BASIC - No authentication, username authentication, or password authentication
  • CERTIFICATE - Public key certificate authentication
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 - Calls to certain methods fail if the queue manager is in a quiescing state. If an application detects that the queue manager is quiescing, the application can complete its immediate task and close the connection, allowing the queue manager to stop.
  • NO - No method call fails because the queue manager is in a quiescing state. If you specify this value, an application cannot detect that the queue manager is quiescing. The application might continue to perform operations against the queue manager, and therefore prevent the queue manager from stopping.
HOSTNAME HOST
  • localhost
  • Any string
LOCALADDRESS LA
  • Not set
  • A string in the format [ip-addr][(low-port[,high-port])]

    Here are some examples:

    9.20.4.98
    The channel binds to address 9.20.4.98 locally
    9.20.4.98(1000)
    The channel binds to address 9.20.4.98 locally and uses port 1000
    9.20.4.98(1000,2000)
    The channel binds to address 9.20.4.98 locally and uses a port in the range 1000 to 2000
    (1000)
    The channel binds to port 1000 locally
    (1000,2000)
    The channel binds to a port in the range 1000 to 2000 locally

    You can specify a host name instead of an IP address.

    For a direct connection to a broker, this property is relevant only when multicast is used, and the value of the property must not contain a port number, or a range of port numbers. The only valid values of the property in this case are null, an IP address, or a host name.

MAXBUFFSIZE MBSZ
  • 1000
  • Any positive integer
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
MSGSELECTION MSEL
  • CLIENT - Message selection is done by the client.
  • BROKER - Message selection is done by the broker.
MULTICAST MCAST
  • DISABLED - Messages are not delivered to a message consumer using multicast transport. This is the default value for ConnectionFactory and TopicConnectionFactory objects.
  • ASCF - Messages are delivered to a message consumer according to the multicast setting for the connection factory associated with the message consumer. The multicast setting for the connection factory is noted at the time that the message consumer is created. This value is valid only for Topic objects, and is the default value for Topic objects.
  • ENABLED - If the topic is configured for multicast in the broker, messages are delivered to a message consumer using multicast transport. A reliable quality of service is used if the topic is configured for reliable multicast.
  • RELIABLE - If the topic is configured for reliable multicast in the broker, messages are delivered to the message consumer using multicast transport with a reliable quality of service. If the topic is not configured for reliable multicast, you cannot create a message consumer for the topic.
  • NOTR - If the topic is configured for multicast in the broker, messages are delivered to the message consumer using multicast transport. A reliable quality of service is not used even if the topic is configured for reliable multicast.
OPTIMISTICPUBLICATION OPTPUB
  • NO - When a publisher publishes a message, the WebSphere MQ JMS client does not return control to the publisher until it has completed all the processing associated with the call and can report the outcome to the publisher.
  • YES - When a publisher publishes a message, the WebSphere MQ JMS client returns control to the publisher immediately, before it has completed all the processing associated with the call and can report the outcome to the publisher. The WebSphere MQ JMS client reports the outcome only when the publisher commits the message.
OUTCOMENOTIFICATION NOTIFY
  • YES - When a subscriber acknowledges or commits a message, the WebSphere MQ JMS client does not return control to the subscriber until it has completed all the processing associated with the call and can report the outcome to the subscriber.
  • NO5 - When a subscriber acknowledges or commits a message, the WebSphere MQ JMS client returns control to the subscriber immediately, before it has completed all the processing associated with the call and can report the outcome to the subscriber.
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 nonpersistent.
  • HIGH - See JMS persistent messages.
POLLINGINT PINT
  • 5000
  • Any positive integer
PORT
  • 1414 - This is the default value if TRANSPORT is set to CLIENT.
  • 1506 - This is the default value if TRANSPORT is set to DIRECT or DIRECTHTTP.
  • 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.
PROCESSDURATION PROCDUR
  • UNKNOWN - A subscriber can give no guarantee about how quickly it can process any message it receives.
  • SHORT - A subscriber guarantees to process quickly any message it receives before returning control to the WebSphere MQ JMS client.
PROXYHOSTNAME PHOST
  • Not set
  • The host name of the proxy server
PROXYPORT PPORT
  • 443
  • The port number of the proxy server
PUBACKINT PAI
  • 25
  • Any positive integer
QMANAGER QMGR Any string
QUEUE QU Any string
RECEIVEISOLATION RCVISOL
  • COMMITTED - A subscriber receives only those messages on the subscriber queue that have been committed.
  • UNCOMMITTED6 - A subscriber can receive messages that have not been committed on the subscriber queue.
RECEXIT RCX
  • Not set
  • A string comprising one or more items separated by commas, where each item is one of the following:
    • The name of a class that implements the WebSphere MQ base Java interface, MQReceiveExit (for a channel receive exit written in Java)
    • A string in the format libraryName(entryPointName) (for a channel receive exit not written in Java)
RECEXITINIT RCXI
  • Not set
  • A string comprising one or more items of user data separated by commas.
RESCANINT RINT
  • 5000
  • Any positive integer
SECEXIT SCX
  • Not set
  • The name of a class that implements the WebSphere MQ base Java interface, MQSecurityExit (for a channel security exit written in Java)
  • A string in the format libraryName(entryPointName) (for a channel security exit not written in Java)
SECEXITINIT SCXI Any string
SENDEXIT SDX
  • Not set
  • A string comprising one or more items separated by commas, where each item is one of the following:
    • The name of a class that implements the WebSphere MQ base Java interface, MQSendExit (for a channel send exit written in Java)
    • A string in the format libraryName(entryPointName) (for a channel send exit not written in Java)
SENDEXITINIT SDXI
  • Not set
  • A string comprising one or more items of user data separated by commas.
SPARSESUBS SSUBS
  • NO - Subscriptions receive frequent matching messages.
  • YES - Subscriptions receive infrequent matching messages. This value requires that the subscription queue can be opened for browse.
SSLCIPHERSUITE SCPHS
SSLCRL SCRL
SSLFIPSREQUIRED SFIPS
  • NO - An SSL connection can use any CipherSuite that is not supported by the IBM Java JSSE FIPS provider (IBMJSSEFIPS).
  • YES - An SSL connection must use a CipherSuite that is supported by IBMJSSEFIPS.
SSLPEERNAME SPEER
SSLRESETCOUNT SRC
  • 0
  • Zero, or any positive integer less than or equal to 999 999 999. See SSL properties
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.
TARGCLIENTMATCHING TCM
  • YES - If an incoming message does not have an MQRFH2 header, the TARGCLIENT property of the Queue object derived from the JMSReplyTo header field of the message is set to MQ. If the message does have an MQRFH2 header, the TARGCLIENT property is set to JMS instead.
  • NO - The TARGCLIENT property of the Queue object derived from the JMSReplyTo header field of an incoming message is always set to JMS.
TEMPMODEL TM
  • SYSTEM.DEFAULT.MODEL.QUEUE
  • Any string
TEMPQPREFIX TQP Any string
TOPIC TOP Any string
TRANSPORT TRAN
  • BIND - For a bindings connection
  • CLIENT - For a client connection
  • DIRECT - For a direct connection to a broker of WebSphere MQ Event Broker, WebSphere Business Integration Event Broker, or WebSphere Business Integration Message Broker
  • DIRECTHTTP - For a direct connection using HTTP tunnelling.
USECONNPOOLING UCP
  • Yes
  • No
Notes:
  1. In certain environments, specifying the same queue name for the BROKERCCDSUBQ and BROKERDURSUBQ properties of an MQTopic object can cause a JMSException to be thrown. You are advised, therefore, to specify different queue names for these properties.
  2. The CCDTURL and CHANNEL properties of an object cannot both be set at the same time.
  3. Running two or more instances of the same durable topic subscriber simultaneously contravenes the Java Message Service Specification, Version 1.1.
  4. The binding options, STANDARD, SHARED, ISOLATED, and FASTPATH, are ignored if the application connects in client mode. The SHARED, ISOLATED, and FASTPATH options are ignored by a queue manager running on z/OS. The connection tag options, SERIALQM, SERIALQSG, RESTRICTQM, and RESTRICTQSG, are supported only by a queue manager running on z/OS. For a more detailed explanation of the connection options, see the WebSphere MQ Application Programming Reference.
  5. If you specify NO, and a message is rolled back after the WebSphere MQ JMS client has returned control to the subscriber, the subscriber still retains a copy of the message but is not informed of the rollback. In this situation, a subscriber might receive the same message more than once.
  6. The value UNCOMMITTED has an effect only if PROCESSDURATION has the value SHORT. It has no effect if PROCESSDURATION has the value UNKNOWN. If you specify UNCOMMITTED, ensure that a subscriber acknowledges or commits each message individually.

Many of the properties are relevant only to a specific subset of the object types. Table 12 shows for each property which object types are valid, and gives a brief description of each property. The 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.

Table 12. The valid combinations of property and object type
Property CF1 QCF TCF Q T XACF1 XAQCF XATCF Description
BROKERCCDSUBQ Y The name of the queue from which durable subscription messages are retrieved for a ConnectionConsumer
BROKERCCSUBQ Y Y Y Y The name of the queue from which non-durable subscription messages are retrieved for a ConnectionConsumer
BROKERCONQ Y Y Y Y Broker's control queue name
BROKERDURSUBQ Y The name of the queue from which durable subscription messages are retrieved
BROKERPUBQ Y Y Y Y Y The name of the queue where published messages are sent (the stream queue)
BROKERPUBQMGR Y The name of the queue manager that owns the queue where messages published on the topic are sent
BROKERQMGR Y Y Y Y The name of the queue manager on which the broker is running
BROKERSUBQ Y Y Y Y The name of the queue from which non-durable subscription messages are retrieved
BROKERVER Y2 Y2 Y Y Y The version of the broker being used
CCDTURL3 Y Y Y A uniform resource locator (URL) that identifies the name and location of the file containing the client channel definition table and specifies how the file can be accessed
CCSID Y Y Y Y Y The coded-character-set-ID to be used on connections
CHANNEL3 Y Y Y The name of the client connection channel being used
CLEANUP Y Y Y Y Cleanup Level for BROKER or MIGRATE Subscription Stores
CLEANUPINT Y Y Y Y The interval between background executions of the publish/subscribe cleanup utility
CLIENTID Y2 Y Y2 Y Y Y A string identifier for the client
CLONESUPP Y Y Y Y Whether two or more instances of the same durable topic subscriber can run simultaneously
COMPHDR Y Y Y A list of the techniques that can be used for compressing header data on a connection
COMPMSG Y Y Y A list of the techniques that can be used for compressing message data on a connection
CONNOPT Y Y Y Y Y Y Options that control how the application connects to the queue manager
CONNTAG4 Y Y Y Y Y Y A tag that the queue manager associates with the resources updated by the application within a unit of work while the application is connected to the queue manager
DESCRIPTION Y2 Y Y2 Y Y Y Y Y A description of the stored object
DIRECTAUTH Y Y To enable SSL authentication for a direct connection5
ENCODING Y Y The encoding scheme used for this destination
EXPIRY Y Y The period after which messages at a destination expire
FAILIFQUIESCE Y Y Y Y Y Y Y Y Whether calls to certain methods fail if the queue manager is in a quiescing state
HOSTNAME Y2 Y Y2 The host name or IP address of the system on which the queue manager resides or, for a direct connection to a broker, the system on which the broker resides
LOCALADDRESS Y Y Y For a connection to a queue manager, this property specifies either or both of the following:
  • The local network interface to be used
  • The local port, or range of local ports, to be used
For a direct connection to a broker, this property is relevant only when multicast is used, and specifies the local network interface to be used.
MAXBUFFSIZE Y Y The maximum number of received messages that can be stored in an internal message buffer while waiting to be processed by the client application. This property applies only when TRANSPORT has the value DIRECT.
MSGBATCHSZ Y Y 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 Y Y Whether or not the connection consumer keeps unwanted messages on the input queue
MSGSELECTION Y Y Y Y Determines whether message selection is done by the JMS client or by the broker. If TRANSPORT has the value DIRECT, message selection is always done by the broker and the value of MSGSELECTION is ignored. Message selection by the broker is not supported when BROKERVER has the value V1.
MULTICAST Y Y Y To enable multicast transport on a direct connection and, if enabled, to specify the precise way in which multicast transport is used to deliver messages from the broker to a message consumer. The property has no effect on how a message producer sends messages to the broker.5
OPTIMISTICPUBLICATION Y Y Whether the WebSphere MQ JMS client returns control immediately to a publisher that has just published a message, or whether it returns control only after it has completed all the processing associated with the call and can report the outcome to the publisher
OUTCOMENOTIFICATION Y Y Whether the WebSphere MQ JMS client returns control immediately to a subscriber that has just acknowledged or committed a message, or whether it returns control only after it has completed all the processing associated with the call and can report the outcome to the subscriber
PERSISTENCE Y Y The persistence of messages sent to a destination
POLLINGINT Y Y Y Y Y Y If each message listener within a session has no suitable message on its queue, this is the maximum interval, in milliseconds, that elapses before each message listener tries again to get a message from its queue. If it frequently happens that no suitable message is available for any of the message listeners in a session, consider increasing the value of this property. This property is relevant only if TRANSPORT has the value BIND or CLIENT.
PORT Y2 Y Y2 The port on which the queue manager or broker listens
PRIORITY Y Y The priority for messages sent to a destination
PROCESSDURATION Y Y Whether a subscriber guarantees to process quickly any message it receives before returning control to the WebSphere MQ JMS client
PROXYHOSTNAME Y Y The host name of the proxy server for a direct connection5
PROXYPORT Y Y The port number of the proxy server for a direct connection5
PUBACKINT Y Y Y Y The number of messages published by a publisher before the WebSphere MQ JMS client requests an acknowledgement from the broker. If you lower the value of this property, the client requests acknowledgements more often, and therefore the performance of the publisher decreases. If you raise the value, the client takes a longer time to throw an exception if the broker fails. This property is relevant only if TRANSPORT has the value BIND or CLIENT.
QMANAGER Y Y Y Y Y Y Y The name of the queue manager to connect to. But, if your application uses a client channel definition table to connect to a queue manager, see Using a client channel definition table.
QUEUE Y The underlying name of the queue representing this destination
RECEIVEISOLATION Y Y Whether a subscriber might receive messages that have not been committed on the subscriber queue
RECEXIT Y Y Y Identifies a channel receive exit, or a sequence of receive exits to be run in succession
RECEXITINIT Y Y Y The user data that is passed to channel receive exits when they are called
RESCANINT Y Y Y Y When a message consumer in the point-to-point domain uses a message selector to select which messages it wants to receive, the WebSphere MQ JMS client searches the WebSphere MQ queue for suitable messages in the sequence determined by the MsgDeliverySequence attribute of the queue. When the client finds a suitable message and delivers it to the consumer, the client resumes the search for the next suitable message from its current position in the queue. The client continues to search the queue in this way until it reaches the end of the queue, or until the interval of time in milliseconds, as determined by the value of this property, has expired. In each case, the client returns to the beginning of the queue to continue its search, and a new time interval commences.
SECEXIT Y Y Y Identifies a channel security exit
SECEXITINIT Y Y Y The user data that is passed to a channel security exit when it is called
SENDEXIT Y Y Y Identifies a channel send exit, or a sequence of send exits to be run in succession
SENDEXITINIT Y Y Y The user data that is passed to channel send exits when they are called
SPARSESUBS Y Y Y Y Controls the message retrieval policy of a TopicSubscriber object
SSLCIPHERSUITE Y Y Y The CipherSuite to use for an SSL connection
SSLCRL Y Y Y CRL servers to check for SSL certificate revocation
SSLFIPSREQUIRED Y Y Y Whether an SSL connection must use a CipherSuite that is supported by the IBM Java JSSE FIPS provider (IBMJSSEFIPS)
SSLPEERNAME Y Y Y For SSL, a distinguished name skeleton that must match that provided by the queue manager
SSLRESETCOUNT Y Y Y For SSL, the total number bytes sent and received by a connection before the secret key that is used for encryption is renegotiated.
STATREFRESHINT Y Y Y Y The interval, in milliseconds, between refreshes of the long running transaction that detects when a subscriber loses its connection to the queue manager. This property is relevant only if SUBSTORE has the value QUEUE. For more information about setting this property, see Subscription stores.
SUBSTORE Y Y Y Y Where WebSphere MQ JMS should store persistent data relating to active subscriptions
SYNCPOINTALLGETS Y Y Y Y Y Y Whether all gets should be performed under syncpoint
TARGCLIENT6 Y Y Whether the WebSphere MQ RFH2 format is used to exchange information with target applications
TARGCLIENTMATCHING Y Y Y Y Whether a reply message, sent to the queue identified by the JMSReplyTo header field of an incoming message, has an MQRFH2 header only if the incoming message has an MQRFH2 header
TEMPMODEL Y Y Y Y The name of the model queue from which JMS temporary queues are created
TEMPQPREFIX Y Y Y Y The prefix that is used to form the name of a WebSphere MQ dynamic queue. The rules for forming the prefix are the same as those for forming the contents of the DynamicQName field in a WebSphere MQ object descriptor, structure MQOD, but the last non blank character must be an asterisk. If no value is specified for the property, the value used is CSQ.* on z/OS and AMQ.* on the other platforms.
TOPIC Y The underlying name of the topic representing this destination
TRANSPORT Y2 Y Y2 Y Y Y Whether a connection uses bindings or client mode to connect to a queue manager, or whether it is a direct connection to a broker
USECONNPOOLING Y Y Y Y Y Y Whether to use connection pooling
Notes:
  1. This object type applies to JMS 1.1 only.
  2. Only the BROKERVER, CLIENTID, DESCRIPTION, HOSTNAME, LOCALADDRESS, PORT, and TRANSPORT properties are supported for a TopicConnectionFactory object, or a JMS 1.1 domain independent ConnectionFactory object, when connecting directly to a broker.
  3. The CCDTURL and CHANNEL properties of an object cannot both be set at the same time.
  4. The CONNTAG property is supported only by a queue manager running on z/OS.
  5. See Appendix C. Connecting to other products.
  6. 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).

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
For a connection to a queue manager, the following properties are relevant only if TRANSPORT has the value CLIENT: Using the administration tool, you cannot set values for these properties if TRANSPORT has the value BIND.

If TRANSPORT has the value CLIENT, the default value of the BROKERVER property is V1 and the default value of the PORT property is 1414. If you set the value of BROKERVER or PORT explicitly, a later change to the value of TRANSPORT does not override your choices.

Properties for a direct connection to a broker
Only the following properties are relevant if TRANSPORT has the value DIRECT or DIRECTHTTP:

If TRANSPORT has the value DIRECT or DIRECTHTTP, the default value of the BROKERVER property is V2, and the default value of the PORT property is 1506. If you set the value of BROKERVER or PORT explicitly, 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:

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

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

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

In this string:

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 Secure Sockets Layer (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 D. SSL CipherSpecs and CipherSuites for a list of CipherSpecs recognized by WebSphere MQ and JMSAdmin.

If you require a connection to use a CipherSuite that is supported by the IBM Java JSSE FIPS provider (IBMJSSEFIPS), set the SSLFIPSREQUIRED property of the connection factory to YES. The default value of this property is NO, which means that a connection can use any CipherSuite that is not supported by IBMJSSEFIPS. The property is ignored if SSLCIPHERSUITE is not set.

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

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

The SSLRESETCOUNT property represents the total number of bytes sent and received by a connection before the secret key that is used for encryption is renegotiated. The number of bytes sent is the number before encryption, and the number of bytes received is the number after decryption. The number of bytes also includes control information sent and received by the WebSphere MQ JMS client.

For example, to configure a ConnectionFactory object that can be used to create a connection over an SSL enabled MQI channel whose secret key is renegotiated after 4 MB of data have flowed, issue the following command to JMSAdmin:

ALTER CF(my.cf) SSLRESETCOUNT(4194304)

If the value of SSLRESETCOUNT is zero, which is the default value, the secret key is never renegotiated. The SSLRESETCOUNT property is ignored if SSLCIPHERSUITE is not set.

If you are using an HP or Sun Java 2 Software Development Kit (SDK) or Java Runtime Environment (JRE), do not set SSLRESETCOUNT to a value other than zero. If you do set SSLRESETCOUNT to a value other than zero, a connection fails when it attempts to renegotiate the secret key.

For more information about the secret key that is used for encryption on an SSL enabled channel, see WebSphere MQ Security.

Sample error conditions

The following are examples of the error conditions that might arise when 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

The following are examples of error conditions that might arise on Windows when looking up JNDI administered objects from a JMS client.

  1. If you are using the WebSphere JNDI provider, com.ibm.websphere.naming.WsnInitialContextFactory, you must use a forward slash (/) to access administered objects defined in sub-contexts; for example, jms/MyQueueName. If you use a backslash (\), an InvalidNameException is thrown.
  2. If you are using the Sun JNDI provider, com.sun.jndi.fscontext.RefFSContextFactory, you must use a backslash (\) to access administered objects defined in sub-contexts; for example, ctx1\\fred. If you use a forward slash (/), a NameNotFoundException is thrown.