This file contains basic and detailed syntax for the wscp interface, and describes how to use the wscp online help facility. The topics include:
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).
To invoke wscp, use the following procedure. See the wscp.bat or wscp.sh file included with the product.
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.
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:
com.ibm.CORBA.loginSource=properties com.ibm.CORBA.loginUserid=<your_user_id> com.ibm.CORBA.principalName=<NT_domain>/<user_id> com.ibm.CORBA.loginPassword=<your_password>The value "properties" is the only option for the com.ibm.CORBA.loginSource property. The value "login" (prompting for a user ID) is not supported for wscp.
com.ibm.CORBA.SSLKeyRing=<key ring to use> com.ibm.CORBA.SSLKeyRingPassword=<your choice of password> com.ibm.CORBA.securityEnabled=trueA "dummy" key ring is provided as a WebSphere Application Server installation option. To use the dummy key ring (if you installed it), include the following line:
com.ibm.CORBA.SSLKeyRing=com.ibm.websphere.DummyKeyringThe dummy keyring is not intended for use in a production environment.
com.ibm.CORBA.ConfigURL=<URL of properties file>An example URL is file:///C:/WebSphere/AppServer/properties/sas.wscp.props. Alternatively, you can add the following option to the Java command line (preceding the application class name):
-Dcom.ibm.CORBA.ConfigURL=<URL of properties file>
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.
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.
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.
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
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:
{FullName /DataSource:ds1/} {Name ds1} {ConnTimeout 300} {DatabaseName WAS} {IdleTimeout 1800} {JDBCDriver /JDBCDriver:DB2Driver/} {MaxPoolSize 30} {MinPoolSize 1} {OrphanTimeout 1800}See Specifying lists in wscp commands for details.
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
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:
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
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
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.