The AdminControl object for scripted administration

Use the AdminControl object to invoke operational commands on objects that run in WebSphere Application Server - Express. Many of the AdminControl methods have multiple signatures. You can invoke these methods in a raw mode with parameters specified by Java Management Extensions (JMX), or with strings for parameters. It is recommended that you use string signatures. In addition to operational commands, the AdminControl object supports some utility methods for tracing, reconnecting with a server, and converting data types.

For additional information about the AdminControl object, see Example: Collecting arguments for the AdminControl object.

completeObjectName
Creates a string representation of a complete ObjectName value based based on a fragment. This method does not communicate with the server to find a matching ObjectName value. If it finds several MBeans that match the fragment, the method returns the first matching MBean.

Parameters: name

Example usage:

Jacl:

set serverON [$AdminControl completeObjectName node=mynode,type=Server,*]

Jython:

serverON = AdminControl.completeObjectName('node=mynode,type=Server,*')

getAttribute
Returns the value of the attribute for the name you provide.

Parameters: name, attribute

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName WebSphere:type=Server,*] 
$AdminControl getAttribute $objNameString processType

Jython:

objNameString = AdminControl.completeObjectName('WebSphere:type=Server,*') 
AdminControl.getAttribute(objNameString, 'processType')

getAttribute_jmx
Returns the value of the attribute for the name you provide.

Parameters: name, attribute

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName WebSphere:type=Server,*] 
set objName [java::new javax.management.ObjectName $objNameString]
$AdminControl getAttribute_jmx $objNameString processType

Jython:

objNameString = AdminControl.completeObjectName('WebSphere:type=Server,*') 
import  javax.management  as  mgmt 
objName =  mgmt.ObjectName(objNameString) 
AdminControl.getAttribute_jmx(objName, 'processType')

getAttributes
Returns the attribute values for the names you provide.

Parameters: name, attributes

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName WebSphere:type=Server,*] 
$AdminControl getAttributes $objName "cellName nodeName"

Jython with string attributes:

objNameString = AdminControl.completeObjectname('WebSphere:type=Server,*)
AdminControl.getAttributes(objNameString, '[cellName nodeName]')

Jython with object attributes:

objNameString = AdminControl.completeObjectname('WebSphere:type=Server,*)
AdminControl.getAttributes(objNameString, ['cellName', 'nodeName'])

getAttributes_jmx
Returns the attribute values for the names you provide.

Parameters: name, attributes

Example usage:

Jacl:

set objectNameString [$AdminControl completeObjectName WebSphere:type=Server,*]
set objName [java:;new javax.management.ObjectName $objectNamestring]
set attrs [java::new {String[]} 2 {cellName nodeName}] 
$AdminControl getAttributes_jmx $objName $attrs

Jython:

objectNameString = AdminControl.completeObjectName('type=Server,*')
objName = AdminControl.makeObjectName(objectNameString)
attrs = ['cellName', 'nodeName']
AdminControl.getAttributes_jmx(objName, attrs)

getCell
Returns the name of the connected cell.

Parameters: none

Example usage:

Jacl:
```
$AdminControl getCell
```
Jython:
```
AdminControl.getCell()
```

Example output:

Mycell

getConfigId
Creates a configuration ID from an ObjectName or ObjectName fragment. Use this ID with the $AdminConfig method. Not all Mbeans that run have configuration objects that correspond. If there are several Mbeans that correspond to an ObjectName fragment, the command returns a warning message and creates a configuration ID for the first Mbean that it finds.

Parameters: name

Example usage:

Jacl:

set threadpoolCID [$AdminControl getConfigId node=mynode,type=ThreadPool,*]

Jython:

threadpoolCID = AdminControl.getConfigId('node=mynode,type=ThreadPool,*')

getDefaultDomain
Returns the default domain name from the server.

Parameters: none

Example usage:

Jacl:
```
$AdminControl getDefaultDomain
```
Jython:
```
AdminControl.getDefaultDomain()
```

Example output:

WebSphere

getDomainName
Returns the domain name from the server.

Parameters: none

Example usage:

Jacl:
```
$AdminControl getDomainName
```
Jython:
```
AdminControl.getDomainName()
```

Example output:

WebSphere

getHost
Returns the name of your host.

Parameters: none

Example usage:

Jacl:
```
$AdminControl getHost
```
Jython:
```
AdminControl.getHost()
```

Example output:

myhost

getMBeanCount
Returns the number of Mbeans registered in the server.

Parameters: none

Example usage:

Jacl:
```
$AdminControl getMBeanCount
```
Jython:
```
AdminControl.getMBeanCount()
```

Example output:

getMBeanInfo_jmx
Returns the JMX MBeanInfo structure that corresponds to an OjbectName value. There is no string signature for this method, because the Help object displays most of the information available from getMBeanInfo.

Parameters: name

Example usage:

Jacl:

set objName [java::new javax.management.ObjectName [$AdminControl 
  completeObjectName type=Server,*]] 
$AdminControl getMBeanInfo_jmx $objName

Jython:

objectNameString = AdminControl.completeObjectName('type=Server,*') 
objName = AdminControl.makeObjectName(objectNameString)
AdminControl.getMBeanInfo_jmx(objName)

Example output:

javax.management.modelmbean.ModelMBeanInfoSupport@10dd5f35

getNode
Returns the name of the connected node.

Parameters: none

Example usage:

Jacl:
```
$AdminControl getNode
```
Jython:
```
AdminControl.getNode()
```

Example output:

myhost

getPort
Returns the name of your port.

Parameters: none

Example usage:

Jacl:
```
$AdminControl getPort
```
Jython:
```
AdminControl.getPort()
```

Example output:

getType
Returns the connection type.

Parameters: none

Example usage:

Jacl:
```
$AdminControl getType
```
Jython:
```
AdminControl.getType()
```

Example output:

SOAP

help
Returns general help text for the AdminControl object.

Parameters: none

Usage:

Jacl:
```
$AdminControl help
```
Jython:
```
AdminControl.help()
```

Output:

WASX7027I: The AdminControl object enables the manipulation
of MBeans running in a WebSphere server process.  The number and type
of MBeans available to the scripting client depends on the server to
which the client is connected.  If the client is connected to a
Deployment Manager, then all the MBeans running in the Deployment
Manager are visible, as are all the MBeans running in the Node Agents
connected to this Deployment Manager, and all the MBeans running in
the application servers on those nodes.

The following commands are supported by AdminControl; more detailed
information about each of these commands is available by using the
"help" command of AdminControl and supplying the name of the command
as an argument.

Note that many of these commands support two different sets of
signatures: one that accepts and returns strings, and one low-level
set that works with JMX objects like ObjectName and AttributeList.
In most situations, the string signatures are likely to be more useful,
but JMX-object signature versions are supplied as well.  Each of these
JMX-object signature commands has "_jmx" appended to the command name.
Hence there is an "invoke" command, as well as a "invoke_jmx" command.

completeObjectName
                Return a String version of an object name given a
                template name
getAttribute_jmx
                Given ObjectName and name of attribute, returns value of
                attribute
getAttribute    Given String version of ObjectName and name of attribute,
                returns value of attribute
getAttributes_jmx
                Given ObjectName and array of attribute names, returns
                AttributeList
getAttributes   Given String version of ObjectName and attribute names,
                returns String of name value pairs

getCell         returns the cell name of the connected server
getConfigId     Given String version of ObjectName, return a config id for
                the corresponding configuration object, if any.
getDefaultDomain
                returns "WebSphere"
getDomainName   returns "WebSphere"

getHost         returns String representation of connected host
getMBeanCount   returns number of registered beans
getMBeanInfo_jmx
                Given ObjectName, returns MBeanInfo structure for MBean

getNode         returns the node name of the connected server
getPort         returns String representation of port in use
getType         returns String representation of connection type in use
help            Show help information
invoke_jmx      Given ObjectName, name of method, array of parameters and
                signature, invoke method on MBean specified
invoke          Invoke a method on the specified MBean
isRegistered_jmx
                true if supplied ObjectName is registered
isRegistered    true if supplied String version of ObjectName is registered
makeObjectName  Return an ObjectName built with the given string
queryNames_jmx  Given ObjectName and QueryExp, retrieves set of ObjectNames
                that match.
queryNames      Given String version of ObjectName, retrieves String of
                ObjectNames that match.
reconnect       reconnects with server
setAttribute_jmx
                Given ObjectName and Attribute object, set attribute for MBean
                specified
setAttribute    Given String version of ObjectName, attribute name and
                attribute value, set attribute for MBean specified
setAttributes_jmx
                Given ObjectName and AttributeList object, set attributes for
                the MBean specified
startServer     Given the name of a server, start that server.
stopServer      Given the name of a server, stop that server.
testConnection  Test the connection to a DataSource object
trace           Set the wsadmin trace specification

help
Returns help text for the specific method of the AdminControl object. The method name is not case sensitive.

Parameters: method

Example usage:

Jacl:
```
$AdminControl help getAttribute
```
Jython:
```
AdminControl.help('getAttribute')
```

Example output:

WASX7043I: Method: getAttribute; Arguments: object name, attribute Description: 
Returns value of "attribute" for the MBean described by "object name."

invoke
Invokes the object operation without parameters. Returns the result of the invocation.

Parameters: name, operationName

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName WebSphere:type=Server,*]
$AdminControl invoke $objNameString stop

Jython:

objNameString = AdminControl.completeObjectName('WebSphere:type=Server,*') 
AdminControl.invoke(objNameString, 'stop')

invoke
Invokes the object operation based on the parameter list that you supply. The signature generates automatically. The types of parameters are supplied by examining the MBeanInfo that the MBean supplies. Returns the string result of the invocation.

Parameters: name, operationName

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName WebSphere:type=Server,*] 
$AdminControl invoke $objNameString appendTraceString com.ibm.*=all=enabled

Jython:

objNameString = AdminControl.completeObjectName('WebSphere:type=Server,*') 
AdminControl.invoke(objNameString, 'appendTraceString', 'com.ibm.*=all=enabled')

invoke
Invokes the object operation by conforming the parameter list to the signature. Returns the result of the invocation.

Parameters: name, operationName, params, sigs

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName WebSphere:type=Server,*] 
$AdminControl invoke $objNameString appendTraceString com.ibm.*=all=enabled
  java.lang.String

Jython:

objNameString = AdminControl.completeObjectName('WebSphere:type=Server,*') 
AdminControl.invoke(objNameString, 'appendTraceString', 'com.ibm.*=all=enabled',
  'java.lang.String')

invoke_jmx
Invokes the object operation by conforming the parameter list to the signature. Returns the result of the invocation.

Parameters: name, operationName, params, sigs

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName WebSphere:type=TraceService,*] 
set objName [java::new javax.management.ObjectName $objNameString] 
set parms [java::new {java.lang.Object[]} 1 com.ibm.ejs.sm.*=all=disabled] 
set signature [java::new {java.lang.String[]} 1 java.lang.String] 
$AdminControl invoke_jmx $objName appendTraceString $parms $signature

Jython:

objNameString = AdminControl.completeObjectName('WebSphere:type=TraceService,*') 
import  javax.management  as  mgmt 
objName =  mgmt.ObjectName(objNameString) 
parms = ['com.ibm.ejs.sm.*=all=disabled'] 
signature = ['java.lang.String'] 
AdminControl.invoke_jmx(objName, 'appendTraceString', parms, signature)

isAlive

Parameters: none

Example usage:

Jacl:
```
$AdminControl isAlive
```
Jython:
```
AdminControl.isAlive()
```

isInstanceof
If the ObjectName value is a member of the class you provide, then the value is true.

Parameters: name, class name

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName WebSphere:type=Server,*]
$AdminControl isInstanceOf $objNameString java.lang.Object

Jython:

objNameString = AdminControl.completeObjectName('WebSphere:type=Server,*')
AdminControl.isInstanceOf(objNameString, 'java.lang.Object')

isInstanceof_jmx
If the ObjectName value is a member of the class you provide, then the value is true.

Parameters: name, class name

Example usage:

Jacl:

set objName [java::new javax.management.ObjectName
[$AdminControl completeObjectName WebSphere:type=Server,*]]
$AdminControl isInstanceOf_jmx $objName java.lang.Object

Jython:

import javax.management as mgmt
objName = mgmt.ObjectName(AdminControl.completeObjectName('WebSphere:type=Server,*'))
AdminControl.isInstanceOf_jmx(objName, 'java.lang.Object')

isRegistered
If the ObjectName value is registered in the server, then the value is true.

Parameters: name

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName WebSphere:type=Server,*] 
$AdminControl isRegistered $objNameString

Jython:

objNameString = AdminControl.completeObjectName('WebSphere:type=Server,*') 
AdminControl.isRegistered(objNameString)

isRegistered_jmx
If the ObjectName value is registered in the server, then the value is true.

Parameters: name

Example usage:

Jacl:

set objName [java::new javax.management.ObjectName WebSphere:type=Server,*] 
$AdminControl isRegistered_jmx $objName

Jython:

objectNameString = AdminControl.completeObjectName('type=Server,*')
objName = AdminControl.makeObjectName(objectNameString)
AdminControl.isRegistered_jmx(objName)

makeObjectName
Creates an ObjectName value based on the strings that you specify. This method does not communicate with the server, and may generate an ObjectName value that does not exist. If the string you supply contains an extra set of quotation marks ("), they are removed. If the string does not begin with a Java Management eXtensions (JMX) domain, or a string followed by a colon, then the WebSphere string prepends to the name.

Parameters: name

Example usage:

Jacl:

set objName [$AdminControl makeObjectName WebSphere:type=Server,node=mynode,*]

Jython:

objectNameString = AdminControl.completeObjectName('type=Server,node=mynode,*')
objName = AdminControl.makeObjectName(objectNameString)

queryNames
Returns a string that lists all ObjectNames based on the name template.

Parameters: name

Example usage:

Jacl:

$AdminControl queryNames WebSphere:type=Server,*

Jython:

AdminControl.queryNames('WebSphere:type=Server,*')

Example output:

WebSphere:cell=BaseApplicationServerCell,name=server1,mbeanIdentifier=server1,
  type=Server,node=mynode,process=server1

queryNames_jmx
Returns a set of ObjectName objects, based on the ObjectName and QueryExp that you provide.

Parameters: name, query

Example usage:

Jacl:

set objName [java::new javax.management.ObjectName WebSphere:type=Server,*]
set null [java::null]
$AdminControl queryNames_jmx $objName $null

Jython:

objectNameString = AdminControl.completeObjectName('type=Server,*')
objName = AdminControl.makeObjectName(objectNameString)
AdminControl.queryNames_jmx(objName, None)

Example output:

[WebSphere:cell=BaseApplicationServerCell,name=server1,mbeanIdentifier=server1,
  type=Server,node=mynode,process=server1]

reconnect
Reconnects to the server, and clears information out of the local cache.

Parameters: none

Example usage:

Jacl:
```
$AdminControl reconnect
```
Jython:
```
AdminControl.reconnect()
```

Example output:

WASX7074I: Reconnect of SOAP connector to host myhost completed.

setAttribute
Sets the attribute value for the name you provide.

Parameters: name, attributeName, attributeValue

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName 
  WebSphere:type=TraceService,*] 
$AdminControl setAttribute $objNameString traceSpecification 
  com.ibm.*=all=disabled

Jython:

objNameString = AdminControl.completeObjectName('WebSphere:type=TraceService,*') 
AdminControl.setAttribute(objNameString, 'traceSpecification',
  'com.ibm.*=all=disabled')

setAttribute_jmx
Sets the attribute value for the name you provide.

Parameters: name, attribute

Example usage:

Jacl:

set objectNameString [$AdminControl completeObjectName 
  WebSphere:type=TraceService,*] 
set objName [java:;new javax.management.ObjectName $objectNamestring]
set attr [java::new javax.management.Attribute 
  traceSpecification com.ibm.*=all=disabled] 
$AdminControl setAttribute_jmx $objName $attr

Jython:

objectNameString = AdminControl.completeObjectName('WebSphere:type=TraceService,*')
import javax.management as mgmt
objName = AdminControl.makeObjectName(objectNameString)
attr = mgmt.Attribute('traceSpecification', 'com.ibm.*=all=disabled')
AdminControl.setAttribute_jmx(objName, attr)

setAttributes
Sets the attribute values for the names you provide and returns a list of successfully set names.

Parameters: name, attributes

Example usage:

Jacl:

set objNameString [$AdminControl completeObjectName 
  WebSphere:type=TracesService,*] 
$AdminControl setAttributes $objNameString {{traceSpecification 
  com.ibm.ws.*=all=enabled}}

Jython with string attributes:

objNameString = AdminControl.completeObjectName('WebSphere:type=TracesService,*') 
AdminControl.setAttributes(objNameString, '[[traceSpecification "com.ibm.ws.*=all=enabled"]]')

Jython with object attributes:

objNameString = AdminControl.completeObjectName('WebSphere:type=TracesService,*') 
AdminControl.setAttributes(objNameString, [['traceSpecification', 'com.ibm.ws.*=all=enabled']])

setAttributes_jmx
Sets the attribute values for the names you provide and returns a list of successfully set names.

Parameters: name, attributes

Example usage:

Jacl:

set objectNameString [$AdminControl completeObjectName 
  WebSphere:type=TraceService,*] 
set objName [java:;new javax.management.ObjectName $objectNamestring] 
set attr [java::new javax.management.Attribute traceSpecification 
  com.ibm.ws.*=all=enabled] 
set alist [java::new javax.management.AttributeList] 
$alist add $attr 
$AdminControl setAttributes_jmx $objName $alist

Jython:

objectNameString = AdminControl.completeObjectName('WebSphere:type=TraceService,*')
import  javax.management  as  mgmt 
objName = AdminControl.makeObjectName(objectNameString) 
attr = mgmt.Attribute('traceSpecification', 'com.ibm.ws.*=all=enabled') 
alist = mgmt.AttributeList() 
alist.add(attr)
AdminControl.setAttributes_jmx(objName, alist)

startServer
Starts the specified application server. This command uses the default wait time. You can only use this command if the scripting client is connected to a NodeAgent. It returns a message to indicate if the server starts successfully.

Parameters: server name

Example usage:

Jacl:
```
$AdminControl startServer server1
```
Jython:
```
AdminControl.startServer('server1')
```

startServer
Starts the specified application server. The start process waits the number of seconds specified by the wait time for the server to start. You can only use this command if the scripting client is connected to a NodeAgent. It returns a message to indicate if the server starts successfully.

Parameters: server name, wait time

Example usage:

Jacl:
```
$AdminControl startServer server1 100
```

Jython:

AdminControl.startServer('server1', 100)

startServer
Starts the specified application server. This command uses the default wait time. You can use this command when the scripting client is either connected to a NodeAgent or Deployment Manager process. It returns a message to indicate if the server starts successfully.

Parameters: server name, node name

Example usage:

Jacl:

$AdminControl startServer server1 myNode

Jython:

AdminControl.startServer('server1', 'myNode')

startServer
Starts the specified application server. The start process waits the number of seconds specified by the wait time for the server to start. You can use this command when the scripting client is either connected to a NodeAgent or Deployment Manager process. It returns a message to indicate if the server starts successfully.

Parameters: server name, node name, wait time

Example usage:

Jacl:

$AdminControl startServer server1 myNode 100

Jython:

AdminControl.startServer('server1', 'myNode', 100)

stopServer
Stops the specified application server. The command returns a message to indicate if the server stops successfully.

Parameters: server name

Example usage:

Jacl:
```
$AdminControl stopServer server1
```
Jython:
```
AdminControl.stopServer('server1')
```

stopServer
Stops the specified application server. If you set the flag to immediate, the server stops immediately. The command returns a message to indicate if the server stops successfully.

Parameters: server name, immediate flag

Example usage:

Jacl:

$AdminControl stopServer server1 immediate

Jython:

AdminControl.stopServer('server1', 'immediate')

stopServer
Stops the specified application server. The command returns a message to indicate if the server stops successfully.

Parameters: server name, node name

Example usage:

Jacl:
```
$AdminControl stopServer server1 myNode
```

Jython:

AdminControl.stopServer('server1', 'my Node')

stopServer
Stops the specified application server. If you set the flag to immediate, the server stops immediately. The command returns a message to indicate if the server stops successfully.

Parameters: server name, node name, immediate flag

Example usage:

Jacl:

$AdminControl stopServer server1 myNode immediate

Jython:

AdminControl.stopServer('server1', 'my Node', 'immediate')

testConnection
Communicates with the DataSourceCfgHelper Mbean to test a DataSource connection. This command works with DataSource resided in the configuration repository. If the DataSource to be tested is in the temporary workspace that holds the update to the repository, you must save the update to the configuration repository before you run this command. Use this method with the configuration ID that corresponds to the DataSource and the WAS40DataSource object types. The return value is a message that indicates a successful connection or a connection with warning. If the connection fails, an exception is thrown from the server.

Parameters: configId

Example usage:

Jacl:

set ds [lindex [$AdminConfig list DataSource] 0]
$AdminControl testConnection $ds

Jython:

# get line separator 
import java.lang.System as sys
lineSeparator = sys.getProperty('line.separator')
ds = AdminConfig.list('DataSource').split(lineSeparator)[0]
AdminControl.testConnection(ds)

Example output:

WASX7217I: Connection to provided datasource was successful.

trace
Sets the trace specification for the scripting process to the value that you specify.

Parameters: traceSpec

Example usage:

Jacl:

$AdminControl trace com.ibm.ws.scripting.*=all=enabled

Jython:

AdminControl.trace('com.ibm.ws.scripting.*=all=enabled')