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.
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.
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:
|
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.
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. |
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).
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.
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.
Property | Short form | Valid values (defaults in bold) |
---|---|---|
BROKERCCDSUBQ1 | CCDSUB |
|
BROKERCCSUBQ | CCSUB |
|
BROKERCONQ | BCON | Any string |
BROKERDURSUBQ1 | BDSUB |
|
BROKERPUBQ | BPUB |
|
BROKERPUBQMGR | BPQM | Any string |
BROKERQMGR | BQM | Any string |
BROKERSUBQ | BSUB |
|
BROKERVER | BVER |
|
CCDTURL2 | CCDT |
|
CCSID | CCS | Any positive integer |
CHANNEL2 | CHAN | Any string |
CLEANUP | CL |
|
CLEANUPINT | CLINT |
|
CLIENTID | CID | Any string |
CLONESUPP | CLS |
|
COMPHDR | HC |
|
COMPMSG | MC |
|
CONNOPT4 | CNOPT |
|
CONNTAG | CNTAG | Any string |
DESCRIPTION | DESC | Any string |
DIRECTAUTH | DAUTH |
|
ENCODING | ENC | See The ENCODING property |
EXPIRY | EXP |
|
FAILIFQUIESCE | FIQ |
|
HOSTNAME | HOST |
|
LOCALADDRESS | LA |
|
MAXBUFFSIZE | MBSZ |
|
MSGBATCHSZ | MBS |
|
MSGRETENTION | MRET |
|
MSGSELECTION | MSEL |
|
MULTICAST | MCAST |
|
OPTIMISTICPUBLICATION | OPTPUB |
|
OUTCOMENOTIFICATION | NOTIFY |
|
PERSISTENCE | PER |
|
POLLINGINT | PINT |
|
PORT |
|
|
PRIORITY | PRI |
|
PROCESSDURATION | PROCDUR |
|
PROXYHOSTNAME | PHOST |
|
PROXYPORT | PPORT |
|
PUBACKINT | PAI |
|
QMANAGER | QMGR | Any string |
QUEUE | QU | Any string |
RECEIVEISOLATION | RCVISOL |
|
RECEXIT | RCX |
|
RECEXITINIT | RCXI |
|
RESCANINT | RINT |
|
SECEXIT | SCX |
|
SECEXITINIT | SCXI | Any string |
SENDEXIT | SDX |
|
SENDEXITINIT | SDXI |
|
SPARSESUBS | SSUBS |
|
SSLCIPHERSUITE | SCPHS |
|
SSLCRL | SCRL |
|
SSLFIPSREQUIRED | SFIPS |
|
SSLPEERNAME | SPEER |
|
SSLRESETCOUNT | SRC |
|
STATREFRESHINT | SRI |
|
SUBSTORE | SS |
|
SYNCPOINTALLGETS | SPAG |
|
TARGCLIENT | TC |
|
TARGCLIENTMATCHING | TCM |
|
TEMPMODEL | TM |
|
TEMPQPREFIX | TQP | Any string |
TOPIC | TOP | Any string |
TRANSPORT | TRAN |
|
USECONNPOOLING | UCP |
|
Notes:
|
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.
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:
|
|||||
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:
|
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
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.
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.
For example, specifying RECEXITINIT(myString) without specifying RECEXIT(some.exit.classname) causes an error.
The valid values that the ENCODING property can take are constructed from three sub-properties:
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)
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.
The following are examples of the error conditions that might arise when creating an object:
InitCtx/cn=Trash> DEFINE QCF(testQCF) SSLCIPHERSUITE(RC4_MD5_US) WARNING: Converting CipherSpec RC4_MD5_US to CipherSuite SSL_RSA_WITH_RC4_128_MD5
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
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
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
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
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
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.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
jms77h3 |