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.
You must configure the administration tool with values for the following three parameters:
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.
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.)
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.
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.
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:
|
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. |
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. |
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.
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.
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.
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. |