AdminControl object for scripted administration

Use the AdminControl object to invoke operational commands that deal with running objects in the WebSphere Application Server. Many of the AdminControl commands have multiple signatures so that they can either invoke in a raw mode using Parameters: specified by Java Management Extensions (JMX), or 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
A convenience command that creates a string representation of a complete ObjectName value based 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.
Parameters: name -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

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

getAttribute
Returns the value of the attribute for the name you provide.
Parameters: name -- java.lang.String; attribute -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

set 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 -- ObjectName; attribute -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

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

getAttributes
Returns the attribute values for the names you provide.
Parameters using Jacl: name -- String; attributes -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

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

getAttributes_jmx
Returns the attribute values for the names you provide.
Parameters: name -- ObjectName; attributes -- java.lang.String[]
Return Type: javax.management.AttributeList

Example usage:

Using Jacl:

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

getCell
Returns the name of the connected cell.
Parameters: none
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl getCell

Example output:

Mycell

getConfigId
A convenience command from an ObjectName or ObjectName fragment that creates a configuration ID. Use this ID with the $AdminConfig command. Not all MBeans that run have configuration objects that correspond. If there are several MBeans that correspond to an ObjectName fragment, a warning issues and a configuration ID builds for the first MBean it finds.
Parameters: name -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

set serverConfigId [$AdminControl getConfigId node=SY1,type=Server,*]

getDefaultDomain
Returns the default domain name from the server.
Parameters: none
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl getDefaultDomain 

Example output:

WebSphere

getDomainName
Returns the domain name from the server.
Parameters: none
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl getDomainName

Example output:

WebSphere

getHost
Returns the name of your host.
Parameters: none
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl getHost

Example output:

myhost

getMBeanCount
Returns the number of MBeans registered in the server.
Parameters: none
Return Type: java.lang.Integer

Example usage:

Using Jacl:

$AdminControl getMBeanCount 

Example output:

114

getMBeanInfo_jmx
Returns the Java Management Extension MBeanInfo structure that corresponds to an OjbectName value. There is no string signature for this command, because the Help object displays most of the information available from getMBeanInfo.
Parameters: name -- ObjectName
Return Type: javax.management.MBeanInfo

Example usage:

Using Jacl:

set objectNameString [$AdminControl completeObjectName type=Server,*] 
set 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
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl getNode

Example output:

Myhost

getPort
Returns the name of your port.
Parameters: none
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl getPort

Example output:

8877

getPropertiesForDataSource
Deprecated, no replacement.

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

Parameters: configId -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

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

Example output:

WASX7389E: Operation not supported - getPropertiesForDataSource command 
is not supported.

getType
Returns the connection type.
Parameters: none
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl getType

Example output:

SOAP

help
Returns general help text for the AdminControl object.
Parameters: none
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl help 

Example 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 command, array of parameters and
                signature, invoke command on MBean specified
invoke          Invoke a command 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 command of the AdminControl object. The command name is not case sensitive.
Parameters: command -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

$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.
Parameters: name -- java.lang.String; operationName -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

set 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.
Parameters: name -- java.lang.String; operationName -- java.lang.String; params -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

set 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 -- java.lang.String; operationName -- java.lang.String; params -- java.lang.String; sigs -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

set 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 -- ObjectName; operationName -- java.lang.String; params -- java.lang.Object[]; signature -- java.lang.String[]
Return Type: java.lang.Object

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

isRegistered
If the ObjectName value is registered in the server, then the value is true.
Parameters: name -- java.lang.String
Return Type: Boolean

Example usage:

Using Jacl:

set 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 -- ObjectName
Return Type: Boolean

Example usage:

Using Jacl:

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

makeObjectName
A convenience command that creates an ObjectName value 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 Java Management Extensions (JMX) domain, or a string followed by a colon, then the WebSphere string appends to the name.
Parameters: name -- java.lang.String
Return Type: javax.management.ObjectName

Example usage:

Using Jacl:

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

queryNames
Returns a string that lists all ObjectNames based on the name template.
Parameters: name -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

$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 -- javax.management.ObjectName;query -- javax.management.QueryExp
Return Type: java.util.Set

Example usage:

Using Jacl:

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

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
Return Type: none

Example usage:

Using Jacl:

$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 -- java.lang.String; attributeName -- java.lang.String; attributeValue -- java.lang.String
Return Type: none

Example usage:

Using Jacl:

set 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 -- ObjectName; attribute -- javax.management.Attribute
Return Type: none

Example usage:

Using Jacl:

set objectNameString [$AdminControl completeObjectName 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 

setAttributes
Sets the attribute values for the names you provide and returns a list of successfully set names.
Parameters using Jacl: name -- String; attributes -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

set 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 -- ObjectName; attributes -- javax.management.AttributeList
Return Type: javax.management.AttributeList

Example usage:

Using Jacl:

set objectNameString [$AdminControl completeObjectName 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

startServer
Starts the specified application server 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 NodeAgent. It returns a message to indicate if the server starts successfully.
Parameters: server name -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl startServer server1

startServer
Starts the specified application server 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 NodeAgent. It returns a message to indicate if the server starts successfully.
Parameters: server name -- java.lang.String, wait time -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl startServer server1 100

startServer
Starts the specified application server 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 NodeAgent or Deployment Manager process. It returns a message to indicate if the server starts successfully.
Parameters: server name -- java.lang.String, node name -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl startServer server1 myNode

startServer
Starts the specified application server 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 NodeAgent or Deployment Manager process. It returns a message to indicate if the server starts successfully.
Parameters: server name -- java.lang.String, node name -- java.lang.String, wait time -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl startServer server1 myNode 100

stopServer
Stops the specified application server. It returns a message to indicate if the server stops successfully.
Parameters: server name -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl stopServer server1

stopServer
Stops the specified application server. 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.
Parameters: server name -- java.lang.String, immediate flag -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl stopServer server1 immediate

stopServer
Stops the specified application server. It returns a message to indicate if the server stops successfully.
Parameters: server name -- java.lang.String, node name -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl stopServer server1 myNode

stopServer
Stops the specified application server. 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.
Parameters: server name -- java.lang.String, node name -- java.lang.String, immediate flag -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl stopServer server1 myNode immediate

stopServer
Stops a server in the specified node. If the flag is set to terminate, a stopImmediate (CANCEL) followed by a terminate (FORCE) will be performed on the server that you specify. This command returns a message to indicate if the server stops successfully. The node name is a required argument. This syntax is only valid if the server that you want to stop is a managed process.
Parameters: server name, node name, terminate flag
Return Type: java.lang.String

Example usage:

Using Jacl:

$AdminControl stopServer server1 myNode terminate

testConnection
A convenience command 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 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. The return value is a message containing the message indicating a successful connection or a connection with warning. If the connection fails, an exception is thrown from the server indicating the error.
Parameters: configId -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

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

Example output:

WASX7217I: Connection to provided datasource was successful.

TestConnection
Deprecated.

This command can give false results and does not work when connected to a NodeAgent. As of V5.0.2, the preferred way to test a Datasource connection is with the testConnection command passing in the DataSource configId as the only parameter.

Parameters: configId -- java.lang.String; props -- java.lang.String
Return Type: java.lang.String

Example usage:

Using Jacl:

set ds [lindex [$AdminConfig list DataSource] 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 that you specify.
Parameters: traceSpec -- java.lang.String
Return Type: none

Example usage:

Using Jacl:

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


Related concepts
Jacl
Related reference
Example: Collecting arguments for the AdminControl object
AdminApp object for scripted administration
Help object for scripted administration
AdminConfig object for scripted administration



Searchable topic ID:   rxml_admincontrol
Last updated: Jun 21, 2007 9:56:50 PM CDT    WebSphere Application Server for z/OS, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/rxml_admincontrol.html

Library | Support | Terms of Use | Feedback