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

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

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, their names must 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 may 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)

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

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 dependencies

Some properties have dependencies on each other. This may 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

If you attempt 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) , there will be an error.

Properties for connecting to WebSphere MQ Event Broker

The only properties used with a direct connection to WebSphere MQ Event Broker are listed in note (ADNL1D) associated with Table 12.

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 will not override your choices.

Exit initialization strings

You must not set any of the exit initialization strings unless the corresponding exit name has been supplied. 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 more complex than the rest of the properties. The encoding property is constructed from three sub-properties:

integer encoding

this is either normal or reversed

decimal encoding

this is either normal or reversed

floating-point encoding

this is 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

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

  ldap://hostname:[port]

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

Sample error conditions

This section provides examples of the error conditions that may arise during the creation of 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