Command syntax and usage

This file contains basic and detailed syntax for the wscp interface, and describes how to use the wscp online help facility. The topics include:


Basic syntax

The syntax for the wscp command is as follows:

wscp [ -h  ]  [ -c command ] [ -f  Tcl_file_name] 
[ -p  properties_file_name] [ -x  extension_class] [ [ -- ] options ]

The command options and arguments are as follows:

If no command-line options or files are specified, an interactive shell (Tcl interpreter) is invoked, which is terminated by the exit command. Command-line options not supported by wscp, or specified after the double hyphen (- -) on the command line, are used to set the Tcl argc or argv variables. These variables can be interpreted by Tcl extensions or other commands.

The wscp shell evaluates Tcl commands in the order specified on the command line, so any extensions must be loaded prior to invoking commands dependent on those extensions. The following extensions are supported:

After a command or script is executed, control is returned to the shell.

The wscp commands can be run as individual wscp invocations from the operating system prompt (command-line mode), as scripts, or interactively in a wscp session (interactive mode).


Invoking and terminating wscp

To invoke wscp, use the following procedure. See the wscp.bat or wscp.sh file included with the product.

  1. Set up the CLASSPATH environment variable, including the appropriate JAR files.

  2. Run Java, invoking the following:

  3. Optionally, set properties to enable tracing.

When wscp is invoked without specifying the -p option, the property file homeDirectory/.wscprc is loaded if it exists, where homeDirectory is the value of the Java property user.home. The .wscprc file can be used to automatically load settings for various properties, amending or replacing system properties already defined. For example, you can modify the values of the wscp.hostName and wscp.hostPort properties to connect to a remote node. See Connecting to local and remote nodes for details.

Note that the value of the Java user.home property can differ depending on the JDK version level. On Windows NT, the JDK 1.2.2 used by WebSphere sets the user.home property based on the value of the USERPROFILE environment variable.

The following example .wscprc file specifies values for various properties.

#
# primaryNode is used with qualifyHomeNames (default=hostName property)
#
# wscp.primaryNode=pc-dev1
#
# hostName is used for com.ibm.CORBA.BootstrapHost
#
wscp.hostName=pc-dev1
#
# hostPort is used for com.ibm.CORBA.BootstrapPort (default=900)
#
# wscp.hostPort=900
#
# wscp.remotePasswordFile (default : uses random number for password)
# wscp.remoteConnectionTimeout (default = 300 seconds)
# wscp.remoteConnectionsAllowed (default = false)
# wscp.remoteHostListAccept (default = null, colon-separated string)
# wscp.remoteHostListReject (default = null, colon-separated string)
#
wscp.remotePasswordFile=C:/TEMP/password
wscp.remoteConnectionTimeout=300
wscp.remoteConnectionsAllowed=true
wscp.remoteHostListAccept=abc.def.com:abc.com
wscp.remoteHostListReject=dhcp-198-7.abc.def.com
#
# set traceString to enable tracing
#
# wscp.traceString=com.ibm.ejs.sm.client.ui.desc.*=all=enabled
# wscp.traceString=com.ibm.ejs.sm.ejscp.*=all=enabled
##
# Typically, these need to be set if only ContextExtension is loaded
# (otherwise, EjscpExtension sets them as noted above)
#
# com.ibm.CORBA.BootstrapHost=pc-dev1
# com.ibm.CORBA.BootstrapPort=900
# java.naming.factory.initial=com.ibm.ejs.ns.jndi.CNInitialContextFactory

The exit command terminates an wscp interactive session.


Authenticating to the administrative server

If security is enabled for your administrative server, you must prepare the wscp client so that it can authenticate to the server. To do this, perform the following steps:


Connecting to local and remote nodes

When you invoke wscp, you are automatically connected to the administrative server running on the local machine. (The host name is defined in the default .wscprc property file.) To connect to a remote node (that is, to specify the host name of a remote administrative server), set the property wscp.hostName to the name that a domain name system (DNS) server can resolve. For example, the following property specifies that the administrative server running on myHost is to be used:

wscp.hostName=myHost 

This property can be set on the Java command line or in the default .wscprc file. You can also use the -p option of the wscp command to specify a different property file to use. See Invoking and terminating wscp for information on the .wscprc property file.


Using command-line mode

To execute an individual wscp command in command-line mode, use the -c option followed by the command. The following examples execute a wscp command on the local node. On Windows NT systems, enclose the command in double quotes. On UNIX systems, enclose the command in single quotes.

C:\> wscp -c "ApplicationServer list"
% wscp.sh -c 'Application Server list'

The -c option can be repeated multiple times on the command line.


Using interactive mode

To invoke an interactive wscp session, type wscp and press Return. The following prompt signals that you have entered interactive mode:

wscp>

At the interactive prompt, enter a wscp command; wscp executes the command, displays the result, and is ready to accept another command. Use the exit command to terminate a wscp interactive session.

In an interactive wscp session, you can break the line of a wscp command after a left brace ( { ) or after typing a backslash ( \ ). The wscp session displays a question mark (?) prompt, and you can continue typing the command.


Running scripts

To execute a wscp script from the command-line, specify the -f option and the name of the executable file that contains the script. For example, the following command executes the script in the modEnv.tcl file.

C:\> wscp -f  modEnv.tcl

To execute a script from within an interactive wscp session, use the Tcl source command to source the script. The following command runs the script in the file myScript.tcl:

wscp> source myScript.tcl

Detailed syntax

The detailed syntax for the wscp command argument is as follows:

object_type operation [object_name]
 [ -option  [value] | -attribute  attribute_list] 

A command argument can be issued immediately following the -c option of the wscp command, or at the wscp interactive prompt, as shown in the following examples.

C:\> wscp -c  "ApplicationServer list"
wscp> ApplicationServer list

When using the -c option, enclose the command in double quotes (Windows NT systems) or in single quotes (UNIX systems).

Note:All object type names, object instance names, and attributes are case-sensitive.

The arguments are as follows:


Specifying object names

In the console, simple names such as myAppServer or dataSource1 are used to specify object names. However, in the repository, object names are stored as fully qualified names. Fully qualified names are required when using wscp. Fully qualified names reflect an object's containment hierarchy. Containment determines how resources are related to one another. For example, an application server contains a servlet engine and one or more enterprise bean containers. A servlet engine contains one or more Web applications, each of which contains one or more servlets.

Containment represents a hierarchical naming structure. This structure prevents name clashes between objects that have the same name but belong to different containment hierarchies. A resource's position in the containment structure is used to generate the resource's full, unique name within the repository. Examples of containment hierarchies are Node/ApplicationServer/EJBContainer/EnterpriseBean and VirtualHost/WebResource.

Containment is also used for efficient operations: starting a contained resource starts the resources above it in the hierarchy. Containment is also used to impose restrictions on relationships: an application server can contain only one servlet engine.

Fully qualified names have the form /Node:nodeName/objectType:objectInstance/. . . /. For example, if the enterprise bean named bean1 runs in the container named container1, and container1 runs in the application server named ejbserver1, which resides on the machine myPc, the repository name of the enterprise bean reflects this hierarchy. The name of the bean, /Node:myPc/ApplicationServer:ejbserver1/EJBContainer:container1/EnterpriseBean:bean1/, is a fully qualified name.

Some objects, for example DataSource objects, do not belong to a containment hierarchy. These objects are known as root types. An example of a fully qualified name for the DataSource object named myDs is /DataSource:myDs/.

Note:You must use fully qualified names in wscp commands and scripts. Because of the syntax of fully qualified names, an object name cannot contain a colon. Fully qualified names can contain spaces; if spaces are used, the name must be enclosed in braces or quotes so that Tcl parses the name as a single argument.

To reduce typing and for readability of scripts, use variables to store a full or partial name of an object. For example, the following commands set variables for the name of a node, server, container, and bean. These variables can then be used in building other object names:

set node  "/Node:my-Pc/"
set serv "${node}ApplicationServer:myServer/"
set cont "${serv}EJBContainer:myContainer/"
set bean "${cont}EnterpriseBean:myBean/"

The braces are required so that the remaining part of the object name is not considered part of the variable name.

Elsewhere, the variable names can be used as shown in the following example:

wscp> ApplicationServer create $serv

The containment operation lists the containment hierarchy for a specified object type. This operation is useful for determining the required elements in a fully qualified name. The syntax is as follows:

object_type containment

The following example command displays the containment hierarchy for the Servlet object type:

wscp> Servlet containment
Node ApplicationServer ServletEngine WebApplication  Servlet

Using the wscp help facility

You can access wscp online help in varying levels of detail. Either of the following commands displays a summary of syntax for the help facility.

C:\> wscp -c Help
wscp> Help

The following topics contain examples of how to obtain help:

Help on object types

To obtain help on an object type, use the following syntax:

object_type help  [operation [ -verbose ] ]

When no arguments are specified, this command displays a brief description of all valid operations for the object type. Depending on the argument specified, you can access help on the following:

For example, the following command requests help on the ApplicationServer object. The command displays the names and descriptions of all valid operations for that object type.

wscp> ApplicationServer help
The following actions are available for ApplicationServer
attributes	    Display the attributes of the object
containment	    Display the containment hierarchy for the object
create		    Create the specified object
defaults     Display or set attribute defaults
help		    Display this help message
list		    Display all the instances of this type
modify		    Modify the attributes of the specified object
operations	    List all the actions available on the object type
remove		    Remove the specified object
show		    Display the attributes of specified object
start		    Start the specified object
stop		    Stop the specified object

The following command displays help for the list operation of ApplicationServer object types:

wscp> ApplicationServer help list
ApplicationServer list [-constraint <attribute list>] [-recursive]

The following command displays verbose help for the list operation:

wscp> ApplicationServer help list -verbose
ApplicationServer list
The following options are available for list
[-constraint <attribute list>]	Display only objects
 which satisfy the constraints
[-recursive]			Display subtype objects

The following command displays the valid options for the addClone operation of Model objects:

wscp> Model help addClone
Model addClone <name> -cloneName <string>

The following command displays verbose help for the addClone operation:

wscp> Model help addClone -verbose
Model addClone <name>
The following options are available for addClone
-cloneName <string>		Fully qualified name of the object which must be made 
a clone of the model

Help on operations

To obtain help on an object type's operations, use the following syntax:

object_type operations 

This command displays a list of all valid operations for the given object type. The following examples display a list of all valid operations for the Servlet, Model, and EnterpriseApplication object types:

wscp> Servlet operations
attributes containment create defaults help list modify operations remove show 
start stop
wscp> Model operations
addClone attributes clone containment create help list listClones modify operations 
remove removeClone show showAttrs start stop
wscp> EnterpriseApplication operations
addRelation attributes containment create defaults help list 
listRelations modify operations remove removeRelation show start stop

Help on attributes

To obtain help on an object type's attributes, use the following syntax:

object_type attributes [ -cloneOnly ]   [ -modelOnly ]  [ -optional ]
[ -readOnly ]  [ -readWrite ]  [ -repository ]  [ -required ]  
[ -runtime ]   [ -server ]  [ -startup ] 

When no options are specified, this command displays a list of all valid attributes for the given object type. Various options allow you to display a subset of attributes. The options are as follows:

The following commands display all valid attributes of the Model, Servlet, and EnterpriseBean object types:

wscp> Model attributes
FullName Name Attributes CloneInterfaceClass ConfigNo IfStarted StartTime
wscp> Servlet attributes
FullName Name CurrentState DesiredState StartTime Code CodeActive
DebugMode Description DescriptionActive Enabled EnabledActive 
InitParams InitParamsActive LoadAtStartup LoadAtStartupActive 
URIPaths URIPathsActive UserServlet UserServletActive
wscp> EnterpriseBean attributes
FullName Name CurrentState DesiredState StartTime CreateDbTable
CreateDbTableActive DataSource DataSourceActive DbExclusiveAccess
DbExclusiveAccessActive DbPassword DbPasswordActive DbUserId 
DbUserIdActive DeploymentDescriptor DeploymentDescriptorActive 
FindForUpdate FindForUpdateActive Home JarFile JarFileActive 
MaxPoolSize MaxPoolSizeActive MinPoolSize MinPoolSizeActive 
PrimaryKeyCheck PrimaryKeyCheckActive

The following command displays only required attributes of the DataSource and EnterpriseBean object types:

wscp> DataSource attributes -required
Name DatabaseName JDBCDriver
wscp> EnterpriseBean attributes -required
Name DeploymentDescriptor JarFile

The following command displays only those attributes of ApplicationServer objects that apply to models and clones of that type:

wscp> ApplicationServer attributes -modelOnly
SelectionPolicy
wscp> ApplicationServer attributes -cloneOnly
FullName Name ServerId ServerInstance

See Printing an object's attributes for a custom Tcl procedure that provides a shortcut method of displaying various combinations of attributes for one or more objects.



Copyright IBM Corporation 1999, 2000. All Rights Reserved