Advanced usage of wscp

This file contains the following topics on using wscp and Tcl:


Using abbreviations in wscp commands

In interactive mode, the wscp interface allows abbreviations for the first word of a command only (that is, for object types). All other options must be fully specified. If an abbreviation is ambiguous, wscp returns an error that includes a list of all matches. In the following example, the word Serv is ambiguous:

wscp> Serv list
Ambiguous command name  "Serv":  Servlet ServletEngine ServletRedirector

To resolve the ambiguity, you must provide as many characters as needed to uniquely identify the desired object type--for example, ServletE.


Specifying lists in wscp commands

Some wscp options take Tcl lists as values (notably the -attribute option of create and modify operations). A Tcl list is an ordered collection of elements, where each element can be a string, a number, or another list. Lists can be delimited by either double quotation marks (" ") or braces ( { } ). The following example sets the variable x to a three-element list whose first element is the string "account", whose second element is "term", and whose third element is itself a list containing the two strings "maturity" and "date".

set x {account term {maturity date}}

In wscp, an attribute list is a list of attribute-value pairs (a Tcl list of lists). The following command modifies the PingInterval and PingTimeout attributes of an application server. The argument to the -attribute option is a list containing two elements. Both elements are themselves lists.

wscp> ApplicationServer modify /Node:dev-pc/ApplicationServer:myServer/  -attribute { \ 
{PingInterval 120} \
{PingTimeout 240}}

An attribute list containing only one attribute-value pair must also be enclosed in a list. For example, in the following command, the attribute-value pair {PingTimeout 240} must be nested within braces:

wscp> ApplicationServer  modify /Node:dev-pc/ApplicationServer:myServer/  \
-attribute {{PingTimeout 240}}
Note:

In addition to the modify operation, the show operation has an -attribute option that expects a Tcl list as its argument. If you specify only one attribute to be displayed, you can use either a string or a Tcl list. Tcl interprets both the string and the Tcl list of one element as equivalent--for example, the arguments JarFile and {JarFile} are equivalent.

As in wscp, Tcl commands consist of one or more words separated by spaces. A Tcl word that contains spaces must be enclosed in either braces ({ }) or double quotation marks (" "). The use of braces and double quotation marks is similar. Both braces and double quotation marks can be placed around a word that contains embedded spaces. However, using braces and double quotation marks differs in two respects. First, unlike double quotation marks, braces can nest. Also, no substitutions occur inside braces, as they do inside double quotation marks. All characters between braces are passed as an argument to a command or procedure, without any special processing. Substitutions can occur later if the argument is evaluated again.

Object names in wscp can contain spaces and therefore must be enclosed in either braces or double quotation marks. If object names are enclosed in braces, no evaluation takes place and everything in braces is passed to the command as an argument. If substitution must take place, for example, when the object name being passed as an argument contains a variable that must be expanded to form the name, then the object name must be enclosed in double quotation marks. The following example commands demonstrate the use of braces and double quotation marks in each case:

# Braces used because object name contains spaces
# Object name is passed to the command as an argument
# and no substitution takes place
 
wscp> ApplicationServer create {/Node:dev-pc/ApplicationServer:My Server/}
 
wscp> ApplicationServer list
{/Node:dev-pc/ApplicationServer:Default Server/} {/Node:dev-pc/ApplicationServer:Appl EJB Server/} 
{/Node:dev-pc/ApplicationServer:Model EJB Server/} {/Node:dev-pc/ApplicationServer:Model EJB Server2/} 
{/Node:dev-pc/ApplicationServer:Bean EJBServer/} {/Node:dev-pc/ApplicationServer:My Server/}
 
 
# Double quotation marks used because substitution must take place
# Assumes the NODE constant is defined as /Node:dev-pc/
 
wscp> ApplicationServer create "${NODE}ApplicationServer:Test Server/"
 
wscp> ApplicationServer list
{/Node:dev-pc/ApplicationServer:Default Server/} {/Node:dev-pc/ApplicationServer:Appl EJB Server/} 
{/Node:dev-pc/ApplicationServer:Model EJB Server/} {/Node:dev-pc/ApplicationServer:Model EJB Server2/} 
{/Node:dev-pc/ApplicationServer:Bean EJBServer/} {/Node:dev-pc/ApplicationServer:My Server/} 
{/Node:dev-pc/ApplicationServer:Test Server/}
 

Lists are a special case of quoted strings, and Tcl quoting conventions can be nonintuitive. Be particularly careful when specifying strings that contain spaces. For example, the Environment attribute of application servers is a list of strings of the form name=value. If the value contains spaces, braces are required. The following command modifies the existing value of an Environment attribute:

wscp> ApplicationServer modify /Node:dev-pc/ApplicationServer:Server1/ -attribute \
{{Environment {{VARIABLE=word1 word2}}}}

The following command creates an application server and specifies two values for the Environment attribute. Note that the PATH environment variable does not require braces because it contains no spaces.

wscp> ApplicationServer create /Node:dev-pc/ApplicationServer:Server2/ -attribute \
{{Environment {PATH=/myPath {OTHERVARIABLE=word1 word2}}}}
 
 

The following commands display the Environment attributes of both servers in the above example:

wscp> ApplicationServer show /Node:dev-pc/ApplicationServer:Server1/ -attribute Environment
{Environment {{VARIABLE=word1 word2}}}
wscp> ApplicationServer show /Node:dev-pc/ApplicationServer:Server2/ -attribute Environment
{Environment {PATH=/myPath {OTHERVARIABLE=word1 word2}}}

Note that when you modify an attribute, you are replacing the existing value with a new value. If you want to add to or replace part of an existing value (for example, change a path name), you must use a custom procedure. See Modifying an Environment attribute (modEnv procedure) for an example procedure named modEnv. The procedure can be used to modify the Environment attribute of one or more servers in a domain. It modifies one element of the list and retains the values of the other elements.

Other attributes that take a list of strings as their arguments are the CommandLineArgs and SystemProperties attributes of application server objects, the URIPaths attribute of Servlet objects, the transportAttributes attribute of servlet engine objects, and the Classpath attribute of Web application objects.


Example use of wscp and Tcl

The wscp interface consists of wscp operations and built-in Tcl commands. Tcl provides a portable method of controlling and extending wscp administrative operations. You can use native Tcl commands for creating and executing new commands (the proc and eval commands), conditionalizing and controlling the flow of execution (if statements and loops), and handling errors and exceptions (the catch command).

The Tcl foreach looping command iterates over all elements in a list. In the following example, the foreach command is used to iterate over all instances of ApplicationServer objects in a domain and then stop each server object. The square brackets ([ ]) invoke command substitution--the result of the ApplicationServer list operation (a list of server names) is used as the list argument to the foreach command. In turn, each ApplicationServer server name is substituted for the variable $ejbserver.

wscp> foreach ejbserver [ApplicationServer  list] \
 {puts "stopping $ejbserver..."; ApplicationServer stop $ejbserver}

As part of many server administration tasks, you often need to monitor the values of one or more server attributes. To do so, you can create and run a procedure that displays the attributes of interest. The following is an example procedure called showServerStatus, which displays the current state for each application server in a domain. As written, the showServerStatus procedure displays the Name and CurrentState attributes of all application servers. You can modify the procedure to display additional or different attributes.

proc showServerStatus {} {
	puts "\nStatus of servers in the domain:\n"
          foreach ejbserver [ApplicationServer list] {
          set serverInfo($ejbserver) [ApplicationServer show $ejbserver -attribute \
          {Name CurrentState}]
          puts $serverInfo($ejbserver)
	
	}
}

The following example demonstrates output of the showServerStatus procedure:

wscp> showServerStatus
Status of servers in the domain:
{Name {Default Server}} {CurrentState {Initialization Failed}}
{Name {Appl EJB Server}} {CurrentState Running}
{Name {Model EJB Server}} {CurrentState Stopped}
{Name {Model EJB Server2}} {CurrentState Stopped}
{Name {Bean EJB Server}} {CurrentState Running}
{Name {My Server}} {CurrentState Stopped}
{Name {Test Server}} {CurrentState Stopped}

The following procedure displays the attributes of a specified object instance, formatting them so that the attributes are displayed one per line, without enclosing braces.

proc display {type name} {
 
	set attrs [$type show $name]
	foreach attr $attrs {
		puts $attr
	}
}

The following example demonstrates output from the display procedure. The procedure is used display the attributes of the DataSource object named testDataSource:

wscp> display DataSource /DataSource:testDataSource/
FullName /DataSourceHome:testDataSource/
Name testDataSource
ConnTimeout 300
DatabaseName WAS
IdleTimeout 1800
JDBCDriver /JDBCDriver:DB2Driver/
MaxPoolSize 30
MinPoolSize 3
OrphanTimeout 1800

Using wscp and operating system commands

All UNIX and Windows NT commands can be issued from within a wscp session. In interactive mode, Tcl executes operating system commands with an explicit exec command. The exec command creates one or more subprocesses and waits until they complete before returning. If you wish to disable this behavior and instead have Tcl search your UNIX or Windows NT PATH environment variable for command names before checking whether they are abbreviations, enter the following command in interactive mode:

wscp> unset auto_noexec

To check the definition of the variable and to reset it to true, enter the following in interactive mode:

wscp> set auto_noexec 
wscp> set auto_noexec true

The Tcl info globals command returns the names of all global variables currently defined.


Obtaining status and error information

Successful wscp commands return a result, typically either a list of information or an empty string. When run interactively, the Tcl result is displayed by the wscp shell. Failed wscp commands raise a TclException, which, unless there is a catch clause, stops the execution of the enclosing procedure.

When an exception is caught by wscp, the stack trace is appended to the Tcl variable errorInfo. You can view the stack trace by issuing either of the following commands:

wscp> puts $errorInfo
wscp> set errorInfo

The Tcl variable errorCode is set when wscp commands are executed. A nonzero value represents an error returned by the command. Interactive users (and script writers) must check this variable to determine whether a command succeeded or failed. The errorCode variable is set to an integer (0 indicates success). The static statusToString method of com.ibm.ejs.sm.ejscp.WscpStatus can be used to translate an errorCode value. For example, the following Tcl procedure takes an errorCode value and translates it:

# Converts a WscpStatus to its corresponding string translation
#
proc statusToString {{status -1}} {
    global errorCode
    if {$status == -1 && $errorCode != "NONE"} {set status $errorCode}
    java::call com.ibm.ejs.sm.ejscp.WscpStatus statusToString $status
}

Note that this Tcl procedure can be used to convert any error code; if an error code argument is not provided, the procedure will convert the current value of the global errorCode variable.

The sample Tcl script init.tcl contains the statusToString procedure and other useful procedures for debugging. See Initialization and general-purpose procedures.


Tracing the administrative server, application servers, and the wscp client

Use either of the following methods to enable tracing for a wscp client:

The following example lines set trace properties. The first line enables all tracing for all of the wscp classes; the second line enables tracing for only the wscp.commands classes.

wscp.traceString=com.ibm.ejs.sm.ejscp.*=all=enabled
wscp.traceString=com.ibm.ejs.sm.ejscp.commands.*=all=enabled

You can also use the DrAdmin extension to enable and set tracing for the administrative server and for application (enterprise bean) servers.

If you are not using the DrAdmin extension, you must use the console to enable tracing for an application server. You can, however, use wscp to set trace for these servers by modifying the TraceSpec attribute of the server object.

See Server trace properties for additional information on tracing.


Use of qualified home names in the administrative server

The following property is used by the administrative server to set up the Java Naming and Directory Interface (JNDI) name space. It specifies whether enterprise bean homes are looked up in the initial context or in a specified subcontext. If this property is set to true, bean homes are looked up in the specified subcontext.

com.ibm.ejs.sm.adminServer.qualifyHomeName

Both the administrative server and wscp, by default, have this property set to true. If the administrative server is running with qualified home names, wscp must also run with qualified home names. The following property controls the use of qualified home names in wscp:

wscp.qualifyHomeName
Note:This property is not related to the fully qualified names used for object instances.

You can disable the use of qualified home names in an administrative server by setting the com.ibm.ejs.sm.adminServer.qualifyHomeName property to false in the admin.config file. This file is located in the directory where Advanced Application Server was installed (typically, on Windows NT systems, installation_drive\Websphere\Appserver\bin). If this property is set to false, the corresponding property in wscp must also be set to false.


Additional extensions to wscp

In addition to the EjscpExtension class, WebSphere Advanced Application Server includes the ContextExtension class for JNDI context manipulation and the DrAdminExtension class for tracing. This file describes the syntax and usage of the DrAdmin extension.

The DrAdmin extension can be used to trace an administrative server or any application server in a domain. The DrAdmin local operation traces the wscp client itself. The DrAdmin remote operation traces the administrative server or an application server (the server can be local, running on the same machine as wscp, or it can be running on a remote machine). The syntax for both commands is as follows:

DrAdmin local  [-setTrace <string>] [-setRingBufferSize <string>]
 [-dumpRingBuffer <string>] [-dumpState <string>]
DrAdmin remote  <server port> [-serverHost <string> [-setTrace <string>] 
 [-setRingBufferSize <string>] [-dumpRingBuffer <string>] [-dumpState <string>] 
 [-stopServer] [-stopNode] [-dumpThreads]

The arguments and options are as follows:

In the following example, the DrAdmin extension is used to trace the administrative server running on port 1078. By default, the trace ring buffer is written to the system default directory. The second example specifies a file name where the trace is to be written. (For Windows NT path names, you can use forward slashes. If backslashes are used, they must be prefaced with the backslash (\ ) character so that the backslashes are treated as ordinary characters.) The third example sets a trace specification that enables tracing for all container classes.

wscp> DrAdmin remote 1078
Server trace ring buffer dumped into file JmonDump52701921622
wscp> DrAdmin remote 1078 -dumpRingBuffer e:\\wscp\\dradmin.dump
Server trace ring buffer dumped into file e:\wscp\dradmin.dump
wscp> DrAdmin remote 1078 -setTrace com.ibm.ejs.container.*=all=enabled
Server trace set to com.ibm.ejs.container.*=all=enabled
Server trace ring buffer dumped into file e:\wscp\dradmin.dump

Where to find more information about Tcl

The following are some useful Tcl commands for writing wscp scripts. For additional information on Tcl, refer to Tcl and the TK Toolkit by John K. Ousterhout (Addison Wesley), or to the Tcl developer Web site at http://dev.scripts.com.



Copyright IBM Corporation 1999, 2000. All Rights Reserved