Commands for the AdminControl object

 

+

Search Tips   |   Advanced Search

 

Use the AdminControl object to invoke operational commands that deal with running objects in the WAS.

Many of the AdminControl commands have multiple signatures so that they can either invoke in a raw mode using parameters that are specified by Java Management Extensions (JMX), or by using strings for parameters. In addition to operational commands, the AdminControl object supports some utility commands for tracing, reconnecting with a server, and converting data types.

 

completeObjectName

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

Example usage:

Use Jacl:

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

Use Jython:

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

 

getAttribute

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

Example usage:

Use Jacl: 

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

Use Jython: 

objNameString = Admin
Control.completeObject
Name('WebSphere:type=
Server,*') 
AdminControl.getAttribute (objNameString, 
'processType')

 

getAttribute_jmx

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

Example usage:

Use Jacl: 

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

Use Jython: 

objNameString = 
AdminControl.complete
ObjectName('WebSphere: type=Server,*')  import  javax. management  as  mgmt  objName =  mgmt.Object
Name(objNameString) 
AdminControl.getAttribute
_jmx(objName, 
'processType')

 

getAttributes

Returns the attribute values for the names that you provide.

Example usage:

Use Jacl: 

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

Use Jython with string attributes: 

objNameString = Admin
Control.completeObject name('WebSphere:type
=Server,*)
AdminControl.getAttributes (objNameString, 
'[cellName nodeName]')

Use Jython with object attributes: 

objNameString = Admin
Control.completeObject name('WebSphere:type
=Server,*)
AdminControl.get
Attributes(objNameString, 
['cellName', 'nodeName'])

 

getAttributes_jmx

Returns the attribute values for the names that you provide.

Example usage:

Use Jacl: 

set objectNameString 
[$AdminControl complete
ObjectName WebSphere: type=Server,*] set objName [$AdminControl  makeObjectName 
$objectNameString] set attrs [java::new 
{String[]} 2 {cellName  nodeName}] 
$AdminControl getAttributes
_jmx $objName $attrs

Use Jython: 

objectNameString = 
AdminControl.complete
ObjectName('type=Server,*') objName = AdminControl. makeObjectName (objectNameString) attrs = ['cellName', 
'nodeName']
AdminControl.getAttributes
_jmx(objName, attrs)

 

getCell

Returns the name of the connected cell.

Example usage:

Use Jacl: 

$AdminControl getCell

Using Jython: 

AdminControl.getCell()
Example output: 

Mycell

 

getConfigId

Creates a configuration ID from an ObjectName or an ObjectName fragment. Use this ID with the $AdminConfig command. Not all MBeans that run have configuration objects that correspond. If several MBeans correspond to an ObjectName fragment, a warning is created and a configuration ID builds for the first MBean it finds.

Example usage:

Use Jacl: 

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

Use Jython: 

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

 

getDefault Domain

Returns the default domain name from the server.

Example usage:

Use Jacl: 

$AdminControl getDefaultDomain

Using Jython: 

AdminControl.getDefaultDomain()
Example output: 

WebSphere

 

getDomain Name

Returns the domain name from the server.

Example usage:

Use Jacl: 

$AdminControl getDomainName

Using Jython: 

AdminControl.getDomainName()
Example output: 

WebSphere

 

getHost

Returns the name of your host.

Example usage:

Use Jacl: 

$AdminControl getHost

Using Jython: 

AdminControl.getHost()
Example output: 

myhost

 

getMBean Count

Returns the number of MBeans that are registered in the server.

Example usage:

Use Jacl: 

$AdminControl getMBeanCount

Using Jython: 

AdminControl.getMBeanCount()
Example output: 

114

 

getMBeanInfo_jmx

Returns the Java Management Extension MBeanInfo structure that corresponds to an ObjectName value. No string signature exists for this command, because the Help object displays most of the information available from the getMBeanInfo command.

Example usage:

Use Jacl: 

set objectNameString 
[$AdminControl complete
ObjectName type=Server,*]  set objName [$AdminControl  makeObjectName 
$objectNameString]
$AdminControl getMBeanInfo
_jmx $objName

Use Jython: 

objectNameString = 
AdminControl.complete
ObjectName('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.

Example usage:

Use Jacl: 

$AdminControl getNode

Using Jython: 

AdminControl.getNode()
Example output: 

Myhost

 

getObjectInstance

Returns the object instance that matches the input object name.

Example usage:

Using Jacl: 

set server [$AdminControl  completeObjectName type=Server,*] set serverOI [$AdminControl  getObjectInstance $server]
Use the following example to manipulate the return value of the getObjectInstance command: 

puts [$serverOI getClassName]

Use Jython: 

server = AdminControl.completeObjectName(
'type=Server,*') serverOI = AdminControl.getObjectInstance( server)
Use the following example to manipulate the return value of the getObjectInstance command: 

print serverOI.getClassName()
Example output: 

javax.management.modelmbean.RequiredModelMBean

 

getPort

Returns the name of your port.

Example usage:

Use Jacl: 

$AdminControl getPort

Using Jython: 

AdminControl.getPort()
Example output: 

8877

 

getProperties ForData Source

Deprecated, no replacement.

This command incorrectly assumes the availability of a configuration service when running in connected mode.

Example usage:

Use Jacl: 

set ds [lindex 
[$AdminConfig list 
DataSource] 0] 
$AdminControl getProper tiesForDataSource $ds

Use Jython: 

ds = AdminConfig.list ('DataSource')

# get line separator  import  java.lang.
System  as  sys lineSeparator = sys. getProperty('line. separator')
 dsArray = ds.split (lineSeparator)
AdminControl.getProper tiesForDataSource (dsArray[0])
Example output: 

WASX7389E: Operation  not supported - get
PropertiesForDataSource  command is not supported.

 

getType

Returns the connection type.

Example usage:

Use Jacl: 

$AdminControl getType

Using Jython: 

AdminControl.getType()
Example output: 

SOAP

 

help

Returns general help text for the AdminControl object.

Example usage:

Use Jacl: 

$AdminControl help

Using Jython: 

AdminControl.help()
Example output: 

WASX7027I: The AdminControl  object enables the  manipulation of MBeans that  run in a WebSphere 
Application Server process.
The number and type of MBeans  that are available to the  scripting client depend  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 that are connected to this  deployment manager, and  all the MBeans that run in  the appservers  on those nodes.

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

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, so an "invoke"  command, as well as a 
"invoke_jmx" command  are supported.



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

 

help

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

Example usage:

Use Jacl: 

$AdminControl help getAttribute

Using Jython: 

AdminControl.help('getAttribute')
Example output: 

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

 

invoke

Invokes the object operation without any parameter. Returns the result of the invocation.

Example usage:

Use Jacl:

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

Use Jython:

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

 

invoke

Invokes the object operation using 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. The string that is returned is controlled by the Mbean method that you invoked. If the Mbean method is synchronous, then control is returned back to the wsadmin tool only when the operation is complete. If the Mbean method is asynchronous, control is returned back to the wsadmin tool immediately even though the invoked task might not be complete.

Example usage:

Use Jacl: 

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

Use Jython: 

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

 

invoke

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

Example usage:

Use Jacl: 

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

Use Jython: 

objNameString = AdminControl. completeObjectName('WebSphere: type=Server,*') 
AdminControl.invoke (objNameString, 'appendTrace
String', '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.

Example usage: 

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

Use 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)

 

isRegistered

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

Example usage:

Use Jacl: 

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

Use 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.

Example usage:

Use Jacl: 

set objectNameString [$AdminControl  completeObjectName type=Server,*] set objName [$AdminControl  makeObjectName $objNameString]
$AdminControl isRegistered_jmx 
$objName

Use Jython: 

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

 

makeObject Name

A convenience command that creates an ObjectName value that is based on the strings input. This command does not communicate with the server, so the ObjectName value that results might not exist. If the string you supply contains an extra set of double quotes, they are removed. If the string does not begin with a JMX domain, or a string followed by a colon, then the WAS string appends to the name.

Example usage:

Use Jacl: 

set objectNameString 
[$AdminControl complete
ObjectName type=Server, node=mynode,*] set objName [$AdminControl  makeObjectName $objNameString]

Use Jython: 

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

 

queryMBeans

Returns a list of object instances that match the object name that you provide.

Example usage:

Using Jacl: 

set apps [$AdminControl queryMBeans  type=Application,*]
Use the following example to manipulate the return value of the queryMBeans command: 

set appArray [$apps toArray] set app1 [java::cast javax.management.
ObjectInstance [$appArray get 0]] puts [[$app1 getObjectName] toString]

Use Jython: 

apps = AdminControl.queryMBeans(
'type=Application,*')
Use the following example to manipulate the return value of the queryMBeans command: 

appArray = apps.toArray() app1 = appArray[0] print app1.getObjectName().toString()
Example output: 

WebSphere:name=PlantsByWebSphere,process= server1,platform=dynamicproxy,node=Goodog,
J2EEName=PlantsByWebSphere,Server=server1, version=6.1.0.0,type=Application, mbeanIdentifier=cells/GooddogNode02Cell/ applications/PlantsByWebSphere.ear/ deployments/PlantsByWebSphere/deployment.
xml#ApplicationDeployment_1126623343902, cell=GooddogNode02Cell

 

queryMBeans

Returns a list of object instances that match the object name and query that you provide.

Example usage:

Using Jacl: 

set apps [$AdminControl queryMBeans  type=Application,* [java::null]]
Use the following example to manipulate the return value of the queryMBeans command: 

set appArray [$apps toArray] set app1 [java::cast  javax.management.ObjectInstance 
[$appArray get 0]] puts [[$app1 getObjectName] toString]

Use Jython: 

apps = AdminControl.queryMBeans(
'type=Application,*',None)
Use the following example to manipulate the return value of the queryMBeans command: 

appArray = apps.toArray() app1 = appArray[0] print app1.getObjectName().toString()
Example output: 

WebSphere:name=PlantsByWebSphere,process= server1,platform=dynamicproxy,node=Goodog,
J2EEName=PlantsByWebSphere,Server=server1, version=6.1.0.0,type=Application, mbeanIdentifier=cells/GooddogNode02Cell/ applications/PlantsByWebSphere.ear/ deployments/PlantsByWebSphere/deployment.
xml#ApplicationDeployment_1126623343902, cell=GooddogNode02Cell

 

queryNames

Returns a string that lists all the ObjectName objects based on the name template.

Example usage:

Use Jacl:

$AdminControl queryNames WebSphere:type=Server,*

Use Jython:

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

Example output:

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

 

queryNames _jmx

Returns a set of ObjectName objects that are based on the ObjectName object and the QueryExp query that you provide.

Example usage:

Use Jacl:

set objectNameString [$AdminControl complete ObjectName type=Server,*]
set objName [$AdminControl makeObjectName $objNameString]
set null [java::null]
$AdminControl queryNames_jmx $objName $null

Use Jython: 

objectNameString = 
AdminControl.completeObject
Name('type=Server,*') objName = AdminControl.make
ObjectName(objectNameString)
AdminControl.queryNames_ jmx(objName, None)
Example output: 

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

 

reconnect

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

Example usage:

Use Jacl: 

$AdminControl reconnect

Using Jython: 

AdminControl.reconnect()
Example output: 

WASX7074I: Reconnect of 
SOAP connector to host  myhost completed.

 

setAttribute

Sets the attribute value for the name that you provide.

Example usage:

Use Jacl: 

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

Use Jython: 

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

 

setAttribute _jmx

Sets the attribute value for the name that you provide.

Example usage:

Use Jacl: 

set objectNameString 
[$AdminControl complete
ObjectName WebSphere: type=TraceService,*]  set objName [$AdminControl  makeObjectName 
$objectNameString] set attr [java::new javax. management.Attribute  traceSpecification com.ibm.
*=all=disabled] 
$AdminControl setAttribute_ jmx $objName $attr

Use 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 that you provide and returns a list of successfully set names.

Example usage:

Use Jacl: 

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

Use Jython with string attributes: 

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

Use Jython with object attributes: 

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

 

setAttributes _jmx

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

Example usage:

Use Jacl: 

set objectNameString 
[$AdminControl completeObject
Name WebSphere:type=
TraceService,*]  set objName [$AdminControl  makeObjectName 
$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

Use Jython: 

objectNameString = 
AdminControl.completeObject
Name('WebSphere:type=
TraceService,*') import  javax.management   as  mgmt  objName = AdminControl. makeObjectName(object
NameString)  attr = mgmt.Attribute ('traceSpecification', 
'com.ibm.ws.*=all=enabled')  alist = mgmt.AttributeList()  alist.add(attr)
AdminControl.setAttributes_ jmx(objName, alist)

 

startServer

Starts the specified appserver by locating it in the configuration. This command uses the default wait time. You can only use this command if the scripting client is connected to a node agent. This command returns a message to indicate if the server starts successfully.

Example usage:

Using Jacl: 

$AdminControl startServer server1

Using Jython: 

AdminControl.startServer ('server1')

 

startServer

Starts the specified appserver by locating it in the configuration. 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 node agent. This command returns a message to indicate if the server starts successfully.

Example usage:

Using Jacl: 

$AdminControl startServer  server1 100

Use Jython: 

AdminControl.startServer ('server1', 100)

 

startServer

Starts the specified appserver by locating it in the configuration. This command uses the default wait time. You can use this command when the scripting client is either connected to a node agent or to a deployment manager process. It returns a message to indicate if the server starts successfully.

Example usage:

Using Jacl:

$AdminControl startServer server1 myNode

Use Jython:

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

 

startServer

Starts the specified appserver by locating it in the configuration. 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 node agent or to a deployment manager process. This command returns a message to indicate if the server starts successfully.

Example usage:

Using Jacl:

$AdminControl startServer server1 myNode 100

Use Jython:

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

 

stopServer

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

Example usage:

Use Jacl: 

$AdminControl stopServer  server1

Use Jython: 

AdminControl.stopServer ('server1')

 

stopServer

Stops the specified appserver. If you set the flag to immediate, the server stops immediately. Otherwise, a normal stop occurs. This command returns a message to indicate if the server stops successfully.

Example usage:

Use Jacl: 

$AdminControl stopServer  server1 immediate

Use Jython: 

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

 

stopServer

Stops the specified appserver. This command returns a message to indicate if the server stops successfully.

Example usage:

Use Jacl: 

$AdminControl stopServer  server1 myNode

Use Jython: 

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

 

stopServer

Stops the specified appserver. If you set the flag to immediate, the server stops immediately. Otherwise, a normal stop occurs. This command returns a message to indicate if the server stops successfully.

Example usage:

Use Jacl: 

$AdminControl stopServer  server1 myNode immediate

Use Jython: 

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

 

test Connection

A convenience command communicates with the DataSource CfgHelper MBean to test a DataSource connection. This command works with the DataSource that resides in the configuration repository. If the DataSource to be tested is in the temporary workspace that holds the update to the repository, you have to save the update to the configuration repository before running this command. Use this command with the configuration ID that corresponds to the DataSource and the WAS40DataSource object types.

Example usage:

Use Jacl: 

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

Use 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.

The return value is a message that contains the message indicating a successful connection or a connection with warning. If the connection fails, an exception is created from the server indicating the error.

 

 

 

test Connection

Deprecated.

This command can give false results and does not work when connected to a node agent.

As of V5.0.2, the preferred way to test a data source connection is with the test Connection command that passes in the DataSource configId parameter as the only parameter.

Example usage:

Use Jacl: 

set ds [lindex [$AdminConfig list 
DataSource] 0] 
$AdminControl testConnection $ds 
{{prop1 val1}}

Use 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, 
'[[prop1 val1]]')
Example output:

WASX7390E: Operation not supported - testConnection command with config id and properties arguments is not supported. Use testConnection command with config id argument only.

 

trace

Sets the trace specification for the scripting process to the value specified.

Example usage:

Use Jacl:

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

Use Jython:

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



 

Related tasks


Use the AdminControl object for scripted administration

 

Reference topic