The JMS administration tool

The administration tool provides a simple way for administrators to define and edit the properties of WebSphere MQ Everyplace JMS administered objects. This tool is based on the administration tool shipped with JMS for WebSphere MQ, differing only in the properties that can be applied to JMS administered objects.

Configuration

You must configure the administration tool with values for the following three parameters:

INITIAL_CONTEXT_FACTORY
This indicates the service provider that the tool uses. There are currently two supported values for this property:

PROVIDER_URL
This indicates the URL of the session's initial context, the root of all JNDI operations carried out by the tool. Two forms of this property are currently supported:

SECURITY_AUTHENTICATION
This indicates whether JNDI passes over security credentials to your service provider. This parameter is used only when an LDAP service provider is used. This property can currently take one of three values:

If a valid value is not supplied, the property defaults to none. If the parameter is set to either simple or CRAM-MD5, security credentials are passed through JNDI to the underlying service provider. These security credentials are in the form of a user distinguished name (User DN) and password. If security credentials are required, then the user will be prompted for these when the tool initializes.

Note:
The text typed is echoed to the screen, and this includes the password. Therefore, take care that passwords are not disclosed to unauthorized users.

These parameters are set in a plaintext configuration file consisting of a set of key-value pairs, separated by an "=". This is shown in the following example:

#Set the service provider
INITIAL_CONTEXT_FACTORY=com.sun.jndi.ldap.LdapCtxFactory
#Set the initial context
PROVIDER_URL=ldap://polaris/o=ibm_us,c=us
#Set the authentication type
SECURITY_AUTHENTICATION=none

(A "#" in the first column of the line indicates a comment, or a line that is not used.)

Starting the JMS admin tool

To start the tool in interactive mode, enter the command:

java com.ibm.mqe.jms.admin.MQeJMSAdmin [-cfg config_filename]

where the -cfg option specifies the name of an alternative configuration file. If no configuration file is specified, then the tool looks for a file named MQeJMSAdmin.config in the current directory.

After authentication, if necessary, the tool displays a command prompt:

InitCtx>

indicating that the tool is using the initial context defined in the PROVIDER_URL configuration parameter.

To start the tool in batch mode, enter the command:

java com.ibm.mqe.jms.admin.MQeJMSAdmin < script.scp

where script.scp is a script file that contains administration commands. The last command in this file must be an END command.

Administration commands

When the command prompt is displayed, the tool is ready to accept commands. Administration commands are generally of the following form:

verb [param ]*

where verb is one of the administration verbs listed in Table xxx. All valid commands consist of at least one (and only one) verb, which appears at the beginning of the command in either its standard or short form.

The parameters a verb may take depend on the verb. For example, the END verb cannot take any parameters, but the DEFINE verb may take anything between 1 and 20 parameters. Details of the verbs that take at least one parameter are discussed later in this section.

Table 24. Administration verbs

Verb Short form Description
ALTER ALT Change at least one of the properties of a given administered object
DEFINE DEF Create and store an administered object, or create a new subcontext
DISPLAY DIS Display the properties of one or more stored administered objects, or the contents of the current context
DELETE DEL Remove one or more administered objects from the namespace, or remove an empty subcontext
CHANGE CHG Alter the current context, allowing the user to traverse the directory namespace anywhere below the initial context (pending security clearance)
COPY CP Make a copy of a stored administered object, storing it under an alternative name
MOVE MV Alter the name under which an administered object is stored
END
Close the administration tool

Verb names are not case-sensitive.

Usually, to terminate commands, you press the carriage return key. However, you can override this by typing the "+" symbol directly before the carriage return. This enables you to enter multi-line commands, as shown in the following example:

DEFINE Q(BookingsInputQueue)+
QMGR(ExampleQM)+
QUEUE(QUEUE.BOOKINGS)

Lines beginning with one of the characters *, #, or / are treated as comments.

Manipulating subcontexts

You can use the verbs CHANGE , DEFINE , DISPLAY and DELETE to manipulate directory namespace subcontexts. Their use is described in Table xxx.

Table 25. Syntax and description of commands used to manipulate subcontexts

Command syntax Description
DEFINE CTX(ctxName) Attempts to create a new child subcontext of the current context, having the name ctxName. Fails if there is a security violation, if the subcontext already exists, or if the name supplied is invalid.
DISPLAY CTX Displays the contents of the current context. Administered objects are annotated with a 'a', subcontexts with '[D]'. The Java type of each object is also displayed.
DELETE CTX(ctxName) Attempts to delete the current context's child context having the name ctxName. Fails if the context is not found, is non-empty, or if there is a security violation.
CHANGE CTX(ctxName) Alters the current context, so that it now refers to the child context having the name ctxName. One of two special values of ctxName may be supplied:

=UP
which moves to the current context's parent

=INIT
which moves directly to the initial context
Fails if the specified context does not exist, or if there is a security violation.

Administering JMS objects

Two object types can currently be manipulated by the administration tool. These are listed in table xxx.

Table 26. JMS administered objects

Object type Keyword Description
MQeJNDIQueueConnectionFactory QCF The WebSphere MQ Everyplace implementation of the JMS QueueConnectionFactory interface. This represents a factory object for creating connections in the JMS Point-to-Point messaging domain.
MQeJMSJNDIQueue Q The WebSphere MQ Everyplace implementation of the JMS Queue interface. This represents a message Destination in the JMS Point-to-Point messaging domain.

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

Table 27. 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 invalid.
DEFINE TYPE(name) [property]* Attempts to create an administered object of type TYPE with the supplied properties, and tries to store it under the name name in the current context. Fails if there is a security violation, if the supplied name is invalid or already exists, or if the properties supplied are invalid.
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, 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 (currently cn=) to the name you supply.

This is shown in the following example.

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

Note that although the object name supplied 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 later in this Chapter.

Properties

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

PROPERTY_NAME(property_value)

Names are not case sensitive, but are restricted to a set of recognized names shown in table xxx.

Table 28. Property names and valid values

Property Short form Valid values
CLIENTIDCID
Any String
DESCRIPTION DESC Any String
DUPSOKCOUNT DOC Any positive integer
INIFILE INI Any String
QUEUE QU Any String
QMANAGER QMGR Any String
LOGGERURL URL Any String

Most of these properties only apply to specific object types. These are listed below, along with a short description.

Table 29.

Property QCF Q Description
CLIENTID Y
A string identifier for the client
DESCRIPTION Y Y A description of the stored object
DUPSOKCOUNT Y
The number of messages to receive before acknowledgment in a DUPS_OK_ACKNOWLEDGE Session.
INIFILE Y
An initialization (.ini) file for a WebSphere MQ Everyplace Queue Manager
QUEUE
Y The name of an WebSphere MQ Everyplace queue
QMANAGER
Y The name of an WebSphere MQ Everyplace queue manager
LOGGERURL Y
A URL to be passed to the JMS transaction logger, of the format file://<path>, defining where the transaction log should be located.



© IBM Corporation 2002. All Rights Reserved