Facilities Guide

Chapter 3   SilverCmd Reference

This chapter describes the SilverCmd utilities, in alphabetical order. It discusses the purpose, syntax, and arguments for each utility. It also describes how to run SilverCmd and presents the associated security and authentication issues. It includes the following sections:

• About SilverCmd

• AddDatabase

• Build

• BuildJspJar

• BuildWAR

• ClearDefaultURL

• ComGen

• ConvertEJB

• CreatePackage

• Delete

• DeployCAR

• DeployEAR

• DeployEJB

• DeployJSP

• DeployWAR

• ExportSource

• ImportClass

• ImportMedia

• ImportPage

• ImportSource

• JSPCompiler

• ModifyTableList

• Prefs

• Publish

• PublishFromFile

• PublishToFile

• QuickDeployEJB

• QuickDeployWAR

• RebuildJAR

• RemoveDatabase

• ServerState

• SetDefaultURL

• SetSecurity

• SetUserGroupInfo

• SourceControl

• ValidateEAR

• ValidateEJB

About SilverCmd

SilverStream's command line tool, SilverCmd, provides a way to perform SilverStream operations without accessing the SilverStream Designer. You can use SilverCmd to automate many of the tasks associated with managing the components of a SilverStream application, or to incorporate application objects built outside the SilverStream Designer.

Separate ports   The SilverStream server lets you define separate runtime, design, and administration ports for different types of users and operations. In most cases you will need to specify the design port when running SilverCmd. As noted in the description of each SilverCmd later in this chapter, you will need to specify the administration port for any command that will add/delete databases or change security properties. Specifying an inappropriate port will result in a security error code.

    For more information about using separate ports, see the chapter on running the server in the Administrator's Guide.

The following table summarizes the commands available through SilverCmd along with the server permissions required to execute them.

Command	Description	Required permission
AddDatabase	Registers (or adds) a database with the specified server.	Modify server settings
Build	Compiles the specified SilverStream application components.	Read/Write
BuildJspJar	Deprecated. Creates and deploys a JSP Jar from a local directory.	Write
BuildWAR	Creates and deploys a J2EE-compatible Web application archive from a local directory.	Write (when deploying to the server)
ClearDefaultURL	Clears a database or server default URL	Modify (on application database or SilverMaster database for server default)
ComGen	Generates COM-access classes from a COM Typelib.	None
ConvertEJB	Deprecated. Converts an EJB1.0-compatible JAR file to an EJB1.1-compatible JAR file	None
CreatePackage	Creates Java packages in the Objects directory.	Write
Delete	Deletes the specified application components from the server.	Write
DeployCAR	Deploys a J2EE-compatible client application archive to a SilverStream server	Write
DeployEAR	Deploys a J2EE-compatible Enterprise Application Archive (EAR) to a SilverStream server.	Write
DeployEJB	Deploys an EJB 1.1 JAR to a SilverStream server.	Write
DeployJSP	Deprecated. Uploads a JSP JAR file to the specified server and deploys it on that server.	Write
DeployWAR	Deploys a J2EE-compatible Web Application Archive (WAR) to a SilverStream server.	Write
ExportSource	Copies the Java source file for a business object or a package to the specified location on disk.	Read
ImportClass	Imports .class files to the server as business objects.	Write
ImportMedia	Imports a media object, such as an image or sound, to the server.	Write
ImportPage	Imports a static HTML page to the SilverStream server, optionally associating a set of URLs with the page.	Write
ImportSource	Copies a Java source file to the Objects directory of the SilverStream server.	Write
JSPCompiler	Deprecated. Translates a JSP page to a Java servlet.	None
ModifyTableList	Defines the set of database tables available to the SilverStream server for a specific database.	Modify server settings
Prefs	Updates various compiler settings for the SilverStream Designer.	None
Publish	Publishes items from one database or server to another.	Read (for the source database) Write (for the destination database)
PublishFromFile	Copies items from a location on disk to the specified server and database. Only items copied to disk using PublishToFile can be uploaded.	Write
PublishToFile	Copies Java source files for any SilverStream application component (for example, forms, views, and media) and its design metadata (if desired) from a server to a specified location on disk. Use in conjunction with PublishFromFile when you want to copy the application components, as a complete unit, from one SilverStream server to another.	Read
QuickDeployEJB	Compiles and deploys the EJB components that have changed since the last full deployment.	Read/Write
QuickDeployWAR	Compiles and deploys the JSP classes that have changed since the last full deployment.	Write
RebuildJAR	Rebuilds SilverStream-generated JAR files	Read/Write
RemoveDatabase	Removes a database from the server's list of accessible databases.	Modify server settings
ServerState	Tests whether the server is running or shuts down the server.	Modify server settings when action value is set to shutdown Read Server Settings when action value is set to isrunning
SetDefaultURL	Sets a database or server's default URL	Modify (on application database or SilverMaster database for server default)
SetSecurity	Sets read, write, protect, select, and execute security on the specified application objects.	Set Permissions
SetUserGroupInfo	Creates, deletes, and sets properties for SilverStream users and groups.	Modify Server Settings
SourceControl	Performs source control tasks.	Read/Write
ValidateEAR	Validates the deployment descriptor within an enterprise application archive.	None
ValidateEJB	Validates the deployment descriptor within a specified EJB JAR file.	None

Running SilverCmd

SilverCmd is located in the SilverStreamInstallDir\bin directory. If you will be using SilverCmd frequently, consider adding SilverStreamInstallDir\bin to your system path for convenience.

Authentication   If your SilverStream server is running in a restricted production environment (as opposed to a unrestricted design environment) you will need to authenticate yourself using the -U and -P options to run commands that access the server.

Executing SilverCmd from the command prompt   To run SilverCmd from the command prompt, use this syntax:

  SilverCmd command arguments

SilverCmd arguments   The following table describes the arguments you can specify with SilverCmd.

Argument	Description
-? or -h	Provides general usage information for SilverCmd For usage on an individual command, specify the command followed by the -? argument: SilverCmd command -? Usage messages that include brackets [ ] indicate that the element within the bracket is optional
-i	Ignore errors and proceed When SilverCmd encounters an error, it stops execution, generates detailed error messages explaining the failure, and displays the messages in the command prompt window If you specify -i, SilverCmd ignores the errors and continues execution
-U and -P	Specifies a user name and password combination for SilverStream authentication If the SilverStream server is running in a restricted production environment, you will need to authenticate yourself to run commands that access the server SilverStream uses all of the standard SilverStream security mechanisms as though the user were executing the command from the SilverStream design environment or the management console If you run SilverCmd in execute mode, you can specify a different -U and -P per command     For more information about supplying these values for each supported security realm, see the chapter on setting up security in the Administrator's Guide.

Running SilverCmd in execute mode   You can run one or more SilverCmds from a file. This is called execute mode. To run in execute mode, use this syntax:

  SilverCmd Execute command-file

The valid arguments are:

Argument

Description

command-file

A text file of commands structured so that each command is on its own line and contains the appropriate arguments. NOTE   Do not specify the SilverCmd keyword on each line in the command-file. Specify SilverCmd only at the command line when running in execute mode. There are no restrictions on the set of commands you can perform from the same file. For example, you can create a file that uploads two classes, rebuilds a JAR file, publishes a database, and sets security. The SilverStream installation program automatically creates a file association for files with a .scd extension for SilverCmd command files; however, you can use any extension that you want. The commands execute in the order in which they appear in the file. Running from a batch file is almost exactly like repeatedly calling SilverCmd, except that when you run SilverCmd in execute mode, you can avoid any performance penalty associated with starting SilverCmd repeatedly. To ignore errors from particular commands and proceed with the commands that follow, specify -i after the file name: SilverCmd Execute command-file -i Certain commands also allow you to specify -i. When used this way, -i means to continue on error within the set of operations that this command does: SetSecurity localhost mydb -f myfile.xml -i You can specify -U and -P at the command line and once for each command within the file. If you do not specify the -U and -P for each command, then the one specified at the command line is used. Values specified at the command line override input file settings.

Logging messages to a file   By default, SilverCmd logs informational messages, warnings, and errors to the command window. You can write the messages to a file using the standard redirect symbol (>). For example:

  SilverCmd Execute command-file -i > SilverCmd.log
  SilverCmd RebuildJAR localhost MyApp myJar > SilverCmd.log

Using input files

Some commands require an input file (specified using the -f option); for other commands it is optional and provided as a convenience. For example, the AddDatabase command requires that you supply the database name, the database type, the user name, the password, and the JDBC driver in an input file. The Delete command does not require an input file. You can delete a single item at the command line, or you can specify a list of items to delete within an input file.

Input file format   Regardless of whether the command requires the input file or allows its use as a convenience, the input file must be in XML format. Each input file must include a DOCTYPE statement. You do not need to be an XML expert to create input files. SilverStream supplies sample XML files for each of the commands. You can copy and paste the required DOCTYPE statement from the appropriate sample into your own XML input file.

The DTD for each input file is located in the SilverStreamInstallDir\Resources\DTDCatalog directory.

The XML sample for each input file is located in the SilverStreamInstallDir\samples\SilverCmd directory.

The examples and DTDs include are self-documenting. See them for the most up-to-date input file requirements.

Some values can be specified at both the command line and within an input file. Values specified at the command line override input file settings.

The following table lists the DTD and sample input files for each SilverCmd command.

Command	DTD	Sample input file
AddDatabase	add_database.dtd	add_database_sample.xml
Build	itemlist.dtd	build_sample.xml
BuildWAR	deploy_war.dtd	none
ClearDefaultURL	none	none
ComGen	none	none
ConvertEJB	none	none
CreatePackage	none	none
Delete	itemlist.dtd	none
DeployCAR	deploy_car.dtd	deploy_car_sample.xml
DeployEAR	deploy_ear.dtd	deploy_ear_sample.xml
DeployEJB	deploy_ejb.dtd	deploy_ejb_sample.xml
DeployJSP	deploy_jsp.dtd	deploy_jsp_sample.xml
DeployWAR	deploy_war.dtd	deploy_war_sample.xml
ExportSource	export_source.dtd	export_source_sample.xml
ImportClass	import.dtd	import_sample.xml
ImportMedia	none	none
ImportPage	none	none
ImportSource	import.dtd	import_sample.xml
JSPCompiler	jsp_1_0.dtd	none
ModifyTableList	modify_table_list.dtd	modify_table_list_sample.xml
Prefs	prefs.dtd	prefs_sample.xml
Publish	itemlist.dtd	publish_sample.xml
PublishFromFile	filelist.dtd	publish_from_file_sample.xml
PublishToFile	itemlist.dtd	publish_to_file_sample.xml
QuickDeployEJB	deploy_ejb.dtd	deploy_ejb_sample.xml
QuickDeployWAR	deploy_war.dtd	deploy_war_sample.xml
RebuildJAR	none	none
RemoveDatabase	none	none
ServerState	none	none
SetDefaultURL	none	none
SetSecurity	set_security.dtd	set_security_sample.xml
SetUserGroupInfo	set_user_group_info.dtd	set_user_group_info_sample.xml
SourceControl	itemlist.dtd	source_control_sample.xml
ValidateEAR	none	none
ValidateEJB	none	none

AddDatabase

Registers a SQL database with the specified SilverStream server.

NOTE   If you have configured separate ports, you will need to specify the administration port when running AddDatabase.

Syntax

  SilverCmd AddDatabase server[:port] -f file [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target server and the administration port
-f file	Specifies the input file containing the database and connection information If -s is also specified, the XML file must contain a System Tables node describing the connection information for the database containing the system tables
options	Specifies any operating criteria for the command

The valid options are:

Option	Definition
-s	Indicates that you want to store SilverStream's system tables in a different database than the one you are adding If you want to store the system tables in a different database, the input file must include a System Tables node that specifies the database name and connection information for the different database
-U and -P	User name and password for SilverStream authentication
?	Displays the usage message

AddDatabase Input file   The AddDatabase command expects the input file to use the add_database.DTD located in the SilverStream/DTDs directory. It includes nodes for the following:

Entry	Description
Database name	Specifies the fully qualified database name
Username & Password	Specifies the user account used by the SilverStream server when accessing this database The account must have read/write permissions for the database
Platform	Specifies the vendor name for the database, for example, Oracle, DB2, or Sybase System 11.     For more information, see Valid Database Connection Types.
Driver set	Specifies the driver type for the database Each database type has a default connection type. If you do not specify a value, SilverStream assumes this type. If you are using a value that is not in the list of database type/connection type values you must specify Other JDBC Driver plus: The fully qualified package name for the JDBC driver The JDBC URL that tells the driver where to connect to the specified database The URL attributes (which include properties like cache size) This syntax is driver-dependent.

The following nodes are optional.

Entry	Description
Table list	Specifies a subset of the tables that should be made available to the SilverStream server You can modify this value later using the ModifyTableList command or the SilverStream Designer The table list can include: A list of table names (which must exactly match the names in the database) A list of table name patterns NOTE   When you specify a pattern, you can use the % symbol to match any number of characters, and the underscore (_) character to specify that you want to match any one character. A combination of names and patterns
System tables	Stores SilverStream's system tables in a different database than the one you are adding This section must include the following information about the database where you want to store the system tables: the database, the user name, the password, the database platform, and the driver set or the LDS key This entry is required when you specify the -s argument at the command line; otherwise it is ignored

Valid Database Connection Types   To connect to a database, the SilverStream server needs the combination of:

• Platform name. Identifies the vendor and version of the database. For example, Oracle 7 or Microsoft SQL Server 7.

• Driver set. Identifies the database driver. It must include the package name so the server can locate it.

or

• LDS key. The logical data source key. You can use this in place of the platform name and driver set.

SilverStream has already defined strings that resolve to these values. See add_database_sample.xml in the SilverStreamInstallDir\samples\SilverCmd directory for the complete listing of valid values.

Build

Compiles the items in an entire database, a directory within the database, or a named item within a directory. You can only build the items located in the Forms, Pages, Views, and Objects directories.

During a build, SilverStream:

• Copies the specified item (or set of items) from the server to the following directory on the local disk: SilverStream/compilecache/server/database/source

• Compiles the objects (using the Java compiler specified in the Designer's preferences file). Generates warning messages for items that cannot be compiled

• Saves (or uploads) the successfully compiled items (.CLASS files) back to the server

Syntax

  SilverCmd Build server[:port] database [item] [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target SilverStream database
item	Specifies the name of a single item to build. It must include the SilverStream directory. For example: SilverCmd Build localhost MyApp Forms/frmAccountType
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	Specifies user name and password for SilverStream authentication
-c	Removes any .CLASS files from the compile cache directory on the local machine before executing the current command For example, if you are building the Forms directory of your Examples database, SilverCmd removes the .CLASS files from the directory: SilverStreamInstallDir\host\database\classes\com\sssw\gen\forms
-f file	Specifies an input file that contains the list of items to build The input file format is based on the ItemList DTD The file name must include a string array of item names. The file can have any extension and can reside in any directory that is accessible to SilverCmd. For example, you can specify SilverCmd Build localhost MyApp -f c:\build_sample.xml
-i	Continues on error

BuildJspJar

Deprecated. For JSP1.1 pages, use the DeployWAR command.

Deploys JavaServer Pages (JSPs) 1.0 authored outside SilverStream to a SilverStream server. This command combines the capabilities of the JSPCompiler and DeployJSP SilverCmd utilities into a single command.

BuildJspJar performs these tasks:

• Compiles the JSP(s) to .java files.

• Compiles the .java files to .class files.

• Builds the JAR file for deployment.

• Builds the XML deployment descriptor file.

• Deploys the JSP(s) to the SilverStream server.

Syntax

  SilverCmd BuildJspJar server[:port] database rootDir -u
  baseURLList [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target SilverStream database
rootDir	Specifies the root directory for the Web site that will be deployed to SilverStream. You do not need to list the files you want to deploy individually because the BuildJspJar command uses the root directory for the site to determine which files will be deployed.
-u baseURLList	One or more base URLs for the JAR. If you specify multiple JAR files, the JARs must be separated by semicolons (;). Each URL you specify provides the root context for the JAR file. The complete URL required to access a JSP page in a JAR must specify the package name and JSP page as well. For example, suppose you deploy a JAR to the myDatabase database on your local machine and the JAR contains a page called test.jsp in the mypackage package. In this case, if you specify jsptests/jspurl as the URL for the JAR, the full URL required to access the page is: http://localhost/myDatabase/jsptests/jspurl/mypackag e/test.jsp
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	Specifies a user name for SilverStream authentication
-U and -P	Specifies a password for SilverStream authentication
-n	Optional name for the created JAR. If you do not specify this option, the name for the JAR file defaults to temp.jar.
-j	Optional list of JAR dependencies. If the JSP JAR references objects in other JAR files, specify the names of these JAR files using the -j option. If you specify multiple JAR files, the JARs must be separated by semicolons (;).

BuildWAR

Constructs a Web Archive (WAR) file using the contents of a specified directory on the local file system (including files and subdirectories). It also constructs the web.xml deployment descriptor and by default adds an entry for each JSPin the directory. You can optionally provide a more detailed web.xml that may include information about any servlets or tag libraries in the WAR. When you provide a web.xml, you must also include the information about the JSPs.

You can use the -n option to specify the location where BuildWAR should create the WAR file. When you do not specify -n, the WAR is created in the Temp directory. It is named agwarXXXX.war.

You can use the -d option to deploy the WAR to a SilverStream server after the WAR is constructed. When you do specify -d, the server and database arguments are required along with the - u option and one or more URLs. If you do not specify the -u option, then you must supply them in a deployment plan file using the -f option.

    For more information about the WAR deployment plan requirements, see Deploying Web Archives (WARs).

Syntax

  SilverCmd BuildWar server[:port] database rootDir [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port This value is optional unless -d is specified
database	Specifies the name of the target database
rootDir	Specifies the directory of files to be placed in the JAR

The valid options are:

Option	Description
-?	Displays the usage message
-U and -P	Specifies the user name and password for SilverStream authentication
-u baseURLList	One or more base URLs for the WAR They should be specified in a semicolon separated list, for example, url1;url2
-d	Specifies that once the WAR is created, it should be deployed on the target SilverStream server and database Server and database arguments are required when -d is specified
-n	Specifies the name for the WAR that is created If not specified, a WAR is created in the TEMP directory and is named AgwXXXX.war, where XXXX is any four digits.
-x	Specifies that the web.xml file already exists in web-inf directory and should not be overwritten
-o	Specifies that an existing WAR of the same name on the server should be overwritten with the current WAR
-e	Specifies the name of the error log file
-f	Specifies the name of the SilverStream deployment plan file

ClearDefaultURL

Clears the default URL for a database or server.

Syntax

  SilverCmd ClearDefaultURL server[:port] [database] [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the target SilverStream database
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	Specifies user name and password for SilverStream authentication

ComGen

Generates COM-access classes from a COM Typelib.

Syntax

  SilverCmd ComGen typelib_path [options]

The valid arguments are:

Argument	Description
typelib_path	The type library for the COM component. The type library can be a separate .TLB file or a resource that is linked into the .DLL or .EXE.
options	Specifies operating criteria for the command

The valid options are:

Option	Description
-l	Lists all registered type libraries on your system. This option does not generate any code.
-d dir	Output directory The output directory is the root directory under which the package directory tree is created.
-p pkg	Output package The Java package name for the generated classes

ConvertEJB

Deprecated.

Converts EJB 1.0 serialized deployment descriptors to EJB 1.1 XML deployment descriptors.

Syntax

  SilverCmd ConvertEJB OldEjbJarPath [NewEjbJarPath] [options]

The valid arguments are:

Arguments	Description
OldEjbJarPath	Specifies the path for the existing EJB 1.0 JAR file
NewEjbJarPath	Specifies the path for newly created EJB 1.1 JAR file
options	Specifies operating criteria for the command

The valid options are:

Option	Description
-?	Displays the usage message
-v	Prints verbose output to the command window

CreatePackage

Creates a Java package of the specified name in the Objects directory of the target database.

Syntax

  SilverCmd CreatePackage server:[port] database package [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target database
package	Specifies the name of the package to create
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	Specifies a user name and password for SilverStream authentication

This example creates the package com.myco.foo in the mydb database on the localhost server:

  SilverCmd CreatePackage localhost mydb com.myco.foo

Delete

Deletes the named component(s) from the specified database and server.

Syntax

  SilverCmd Delete server[:port] database [item] [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target database
item	Specifies the name of the item to delete. To delete a form, page, or view, specify: dir/itemname where dir is Forms, Pages, or Views To delete a business object, specify: Objects/packagename/itemname To delete a media item, specify: Media/dir/itemname where dir is Jars, Images, Sounds or General To delete multiple items, use the -f file.
options	Specifies operating criteria for the command

The valid options are:

Option	Description
-?	Displays the usage message.
-f file	Specifies an input file that contains the list of items to delete The input file format is based on the ItemList DTD The file name must include a string array of item names. The file can have any extension and can reside in any directory accessible to SilverCmd.
-U and -P	Specifies the user name and password for SilverStream authentication
-r	Recursively delete children of packages

DeployCAR

Deploys a J2EE-compatible application client archive file authored outside SilverStream to the specified SilverStream server.

The archive file must comply with the J2EE specification and must contain a manifest file that includes a Main-Class entry.

The deployed object is given the same name as the archive unless you specify the -d option.

Syntax

  SilverCmd DeployCAR server[:port] database jarfile 
     -f [deployment plan] [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target SilverStream database
jarfile	Specifies the name (and path) of the client application archive to deploy

Options   The valid options are:

Option	Description
-?	Displays the usage message
-d	Specifies an alternate name for the deployed object. Use this option when you want to use the same client archive for multiple deployments
-f	Specifies the name (and path) of the deployment plan A deployment plan is only necessary when your application references EJBs or external resources.
-o	Overwrites an existing deployed object of the same name
-U and -P	User name and password for authentication by the server

DeployEAR

Deploys an Enterprise Archive file (EAR) authored outside SilverStream to a SilverStream server.

DeployEAR performs these tasks:

1. Opens the EAR file and extracts all of the files to a local temporary directory.

2. Performs the appropriate SilverCmd DeployXXX corresponding to each archive type.

3. Passes the -o flag (if specified) to each of the DeployXXX commands

   • You might want to specify -o if you are redeploying an existing EAR

   • You might not want to specify -o if you are deploying an EAR name which has not previously been deployed. This ensures that you will get an error if there's one there already that you might not want to overwrite.

Syntax

  SilverCmd DeployEAR server[:port] database [EARFile] 
     -f deploymentPlan [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target SilverStream database
EARFile	Specifies the name and location (on disk) of the EAR file to deploy. This value can also be specified in the deployment plan. When specified in both places, the deploymentPlan value takes precedence.
-f deploymentPlan	Specifies the name and location (on disk) of the XML-based deployment plan.     For more information on the structure of this file, see Deployment Plan DTDs.

Options   The valid options are:

Option	Description
-?	Displays the usage message
-i	Ignores errors when compiling JSP pages and deploys whatever builds successfully.
-l	Specifies the name for the deployed EAR object on the SilverStream server. By default, the enterprise archive name is used.
-o	If a deployedObject or remoteJar object already exists on the server, this flag forces that object to be overwritten.
-t	Used for debugging JSP pages using non-Latin-1 character sets: If specified, the JSP compiler outputs into the compile cache an additional .java file with the extension -local (for example, along with date_jsp_xxxxxxxxxxx.java, you will also find date_jsp_xxxxxxxxxxx-local.java). The version of the file with -local is in the machine's local character set, instead of UTF-8. By default, you will find these files in SilverStreamInstallDir/compilecache/server/database/temp/sources/archive/com/sssw/gen/jsps.
-U and -P	User name and password for authentication by the server

DeployEJB

Deploys an EJB JAR on the named SilverStream server.

The EJBs can be authored using SilverStream tools so the source files and deployment plan reside on the SilverStream server, or the EJBs can be authored using external tools so the sources and deployment plan reside outside of the SilverStream server.

DeployEJB performs these tasks:

• Creates implementation classes for the home and remote interfaces, and generates wrapper classes that handle security and transactions.

• Generates a deployed object which contains the implementation classes used by the SilverStream server. This object remains on the server.

• Generates stub classes and puts them into a remote JAR that is used by the bean's clients. A copy of this remains on the server.

  NOTE   For external Java clients, you must manually copy this remote JAR to each client that needs to access this deployed EJB, or you can specify the -R option to automatically copy the remote JAR to a single client machine.

• Enables the deployedObject for client access when allowed by the deployment plan.

Syntax

  SilverCmd DeployEJB server[:port] database [ejbJar] [-d ejbDeployedObject] [-r ejbRemoteJar] -f file [-R remoteJarPath] [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target database
ejbJar	Specifies the name of the EJB JAR to deploy If not specified at the command line, the EJB JAR must be specified in the deployment plan. Values specified at the command line override input file settings. The JAR should contain the Enterprise JavaBean classes, the home and remote interfaces for each EJB in the JAR, a deployment descriptor and any supporting components (utility classes, images, and so forth)
-f file	Specifies the name of the deployment plan. This file must be on disk (not in the database). See the deploy_ejb.DTD in the SilverStreamInstallDir\Resources\DTDCatalog directory and the deploy_ejb_sample.XML file in the SilverStreamInstallDir\samples\SilverCmd directory for information about how this file should be structured You can also create this file using SilverStream's Deployment Plan Designer.
options	Specifies operating criteria for the command

The valid options are:

Option	Description
-?	Displays the usage message
-U and -P	User name and password for server authentication
-o	If an ejbDeployedObject or ejbRemoteJar argument is given and the object exists on the server, this flag forces the object to be overwritten
-d ejbDeployedObject	Specifies the name for the deployed object created by the command. You can specify the name in the deployment plan or at the command line. Values specified at the command line override input file settings. If the name is not specified, SilverCmd generates a default name by appending Deployed to the current name (for example, xxxDeployed) If a JAR of this name already exists on the server, you must specify the -o parameter to overwrite it
-r ejbRemoteJar	Specifies the name to use for the remote JAR created by this command. You can specify this name in the deployment plan or at the command line. Values specified at the command line override input file settings. If the name is not specified, SilverCmd generates a default name by appending Remote to the current name (for example, xxxRemote.JAR) If a JAR of this name already exists on the server, you must specify the -o parameter to overwrite it The remote JAR file is enerated only if the input file specifies that the JAR should be enabled.
-R remoteJarPath	Creates a copy of the generated ejbRemoteJAR on the local drive in the directory path given The JAR will have the same name as the remote JAR generated on the server
-v verboseLevel	The level of messages to output. Values for verboseLevel are 0 for no messages (default) to 5 for the most messages.

DeployJSP

Deprecated. For JSP1.1 pages, use the DeployWAR command.

Uploads a JSP 1.0 JAR file to the specified server and deploys it on that server.

Syntax

  SilverCmd DeployJSP server[:port] database jspJarFile -f file [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target database
jspJarFile	Specifies the name of the JSP JAR to deploy The JAR should contain the compiled JSP classes and any supporting components (utility classes, images, and so forth)
-f file	Specifies the input XML file that specifies URLs and dependency JAR files See the deploy_jsp.DTD in the SilverStreamInstallDir\Resources\DTDCatalog directory and the deploy_jsp_sample.XML file in the SilverStreamInstallDir\samples\SilverCmd directory for information about how this file should be structured
options	Specifies operating criteria for the command

The valid options are:

Option	Description
-?	Displays the usage message
-o	If the JAR exists on the server, this flag forces the JAR to be overwritten

DeployWAR

Deploys a J2EE-compatible Web archive (WAR) to a SilverStream server.

DeployWAR performs these tasks:

• Compiles all JSP pages in the WAR into Java source files and then compiles these Java sources

• Adds the compiled Java class files to the WAR file

• Uploads the WAR file to the SilverStream server

The deployed WAR can also contain standard servlet classes and other supporting Java source files that were compiled separately, as well as HTML documents, images, and any other files required by the application.

Syntax

  SilverCmd DeployWAR server[:port] database [WARFile] 
      -f deploymentPlan [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target database
WARFile	Specifies the name of the WAR file to deploy. This value can be specified at either the command line or in the deployment plan. Values specified at the command line override input file settings.
-f deploymentPlan	An XML-based file that specifies the SilverStream-specific deployment information.

Options   The valid options are:

Option	Description
-?	Displays the usage message
-i	Ignores errors when compiling JSP pages and deploys whatever builds successfully.
-o	If a deployedObject or remoteJar object already exists on the server, this flag forces these objects to be overwritten.
-t	Used for debugging JSP pages using non-Latin-1 character sets: If specified, the JSP compiler outputs into the compile cache an additional .java file with the extension -local (for example, along with date_jsp_xxxxxxxxxxx.java, you will also find date_jsp_xxxxxxxxxxx-local.java). The version of the file with -local is in the machine's local character set, instead of UTF-8. By default, you will find these files in SilverStreamInstallDir/compilecache/server/database/temp/sources/archive/com/sssw/gen/jsps.
-U and -P	User name and password for authentication by the server.

ExportSource

Copies the .JAVA source file of a single business object from a SilverStream application database to the specified location on disk as a text file.

Syntax

  SilverCmd ExportSource server[:port] database [classname] [javafile] [is-file] [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the source SilverStream server and the design-time port
database	Specifies the name of the source database
classname	Specifies the name of the class to export
javafile	Specifies the name of the local file If you do not specify a fully qualified file name, ExportSource creates the file in the current working directory
is-file	Specifies a file that will be populated by ExportSource The resulting file is in XML format and includes the metadata required to recreate the object on a SilverStream server using the ImportSource command For example, if the object is a triggered business object, it includes the metadata about the trigger and the object's lifetime If it does not exist, SilverCmd creates it If you do not specify this file for a triggered business object, you must manually create the import options file when you want to reimport the object It is not necessary to specify this option for nontriggered business objects, because they do not have any associated metadata
options	Specifies operating criteria for the command

The valid options are:

Options	Description
-?	Displays the usage message
-f file	Specifies the file name of an input file This input file can contain the item or directory to export as well as the export source and options files
-U and -P	User name and password for SilverStream authentication
-o	Specifies that ExportSource should overwrite the javafile if it already exists on disk

ImportClass

Copies Java .CLASS files to the Objects directory of the specified database.

You can use ImportClass to copy any kind of Java class including utility classes and SilverStream's triggered objects. You cannot use this command to import the class files for any other type of SilverStream object (such as forms, views, or pages).

To import some types of triggered business object, you must provide additional information about the object's trigger. For example: a mail triggered business object requires data about the mail account to which it responds, a servlet requires the URL specification, and so on. Values for mail and table listeners can be specified at the command line; all others must be specified within the input file. Server, cluster, and invoked business objects do not require additional information. Values specified at the command line (specifically, the -t, -m, and -p options) override settings in the input file.

Syntax

  SilverCmd ImportClass server[:port] database classfile [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name and optionally the design-time port number of the target SilverStream server
database	Specifies the name of the target SilverStream database
classfile	Specifies the name of the class file to import
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-f file	Specifies the file name of the input file that contains the metadata information about the object you are importing Used only if the object is a triggered business object     For more information, see import.dtd in the SilverStreamInstallDir\Resources\DTDCatalog directory and import_sample.xml in the SilverStreamInstallDir\samples\SilverCmd directory
-m account	Specifies the mail account if loading an AgiMailListener object Overrides input file specifications
-o	Specifies that ImportClass should overwrite the class file if it already exists on the server
-p	Makes the triggered business object a server-lifetime object; that is, it is instantiated once, not for each event (objects are event-lifetime by default) Overrides input file specifications
-t table	Specifies a database table name if loading an AgiTableListener object Overrides input file specifications
-U and -P	Specifies the user name and password for SilverStream authentication

ImportMedia

Imports objects to the appropriate Media subdirectory on the SilverStream server. The objects can include images, standard JARs, EJB JARs, and sounds.

NOTE   You cannot modify imported JARs using the SilverStream Jar Designer. You must make any modifications to the JAR file before importing it into SilverStream.

Importing JAR files that reference files in other JARs   You might have to import a JAR file that contains references to classes in other JAR files. The JAR that you want to import must contain a Class-path entry that lists the JARs containing the referenced classes. When this is true, you:

1. Import the JARs containing the referenced files (the referenced JARs).

2. Import the primary JAR.

3. Add the primary JAR to any forms, pages, business objects, or deployment plans that use the components in the primary JAR (added via the File>Jar files menu item.

If the JAR you are importing does not include a manifest file with a Class-path entry listing the referenced JARs, do the following before trying to import the JAR:

1. Extract the manifest of the primary JAR (making sure that the path on extract matches the manifest's path within the JAR).

2. Add the Class-path attribute to the manifest of the primary JAR.

       For more information on the Class-path attribute, see the chapter on the JAR Designer in the Tools Guide of the server's Classic Development Help.

3. Update the primary JAR with the new manifest file.

4. Follow the steps for importing JARs that already contain the Class-path entry outlined above.

Syntax

  SilverCmd ImportMedia server[:port] database fileOrDir...[options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target SilverStream database into which you want to import the media files
fileOrDir...	Specifies the name of the file to import or the directory whose files are to be imported You can supply multiple files or directories at the command line
options	Specifies operating criteria for the command

The valid options are:

Option	Description
-?	Displays the usage message
-U and -P	User name and password for authentication
-i	Continue on error
-j	Import all specified files or the contents of all directories as JAR files regardless of their extension
-o	If the media object exists on the server, this flag forces it to be overwritten
-r	For specified directories, recurse into the subdirectories

ImportPage

Imports a static HTML page to a SilverStream database. You can optionally associate the HTML page with one or more URLs.

Syntax

  SilverCmd ImportPage server[:port] database htmlfile [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target SilverStream database
htmlfile	Specifies the name of the HTML file to import
options	Specifies operating criteria for the command

The valid options are:

Option	Description
-e URLElements	Specifies a semicolon-separated list of database-relative URLs to associate with the HTML file
-o	Specifies that ImportPage should overwrite an existing HTML file of the same name if necessary

ImportSource

Imports .Java files to the business objects directory of the specified database and server.

You can use ImportSource to copy source code for utility, EJB, and SilverStream's triggered objects. You cannot use this command to import the source for any other type of SilverStream object (such as forms, views, or pages).

To import some types of triggered business objects, you must provide additional information about the object's trigger. For example, a mail triggered business object requires data about the mail account to which it should respond; a servlet requires the URL specification, and so on. Values for mail and table listeners can be specified either at the command line or in the input file; all others must be specified within the input file. Server, cluster, and invoked business objects do not require additional information. Values specified at the command line (specifically the -t, -m, and -p options) override settings in input file. You can also set or modify these values once the object is imported.

Syntax

  SilverCmd ImportSource server[:port] database javafile [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target SilverStream database
javafile	Specifies the location and name of the Java file to import
options	Specifies operating criteria for the command

The valid options are:

Option	Description
-?	Displays the usage message
-f file	Specifies the file name of the input file that contains the metadata information about the object you are importing Used only if the object is a triggered business object     For more information, see import.dtd in the SilverStreamInstallDir\Resources\DTDCatalog directory and import_sample.xml in the SilverStreamInstallDir\samples\SilverCmd directory.
-k	Specifies that ImportSource should not overwrite existing metadata if the class already exists on the server
-m account	Specifies the mail account if loading an AgiMailListener object Overrides input file specifications
-o	Specifies that ImportSource should overwrite the source file if it already exists on the server
-p	Makes the triggered business object a server-lifetime object; that is, it is instantiated once, not for each event (objects are event-lifetime by default) Overrides input file specifications
-t table	Specifies a database table name if loading an AgiTableListener object Overrides input file specifications
-U and -P	Specifies the user name and password for SilverStream authentication

JSPCompiler

Deprecated. For JSP1.1 pages, use the DeployWAR command.

Translates a JSP 1.0 page to a Java servlet.

Syntax

  SilverCmd JSPCompiler jspfile | xmldoc jspfiles... [options]

The valid arguments are:

Argument	Description
jspfile	The name of the JSP file you want to process
xmldoc	The name of the XML document you want to process
jspfiles...	The name(s) of additional JSP files to process (in a space-separated list)
options	Specifies operating criteria for the command

The valid options are:

Option	Description
-?	Displays the usage message
-d dir	Generates debugging output
-p pkg	Specifies a fully qualified package name
-r root	Specifies the application root location. This option is used only when compiling a page that contains a JSP include directive with a relative URL that starts with a slash (/)
-v	Validates the XML document

ModifyTableList

Defines the set of tables available to SilverStream for a specified database. The ModifyTableList command requires an input file to specify the table names.

NOTE   If you have configured separate ports, you will need to specify the administration port when running ModifyTableList.

Syntax

  SilverCmd ModifyTableList server[:port] database -f file [options]

The valid arguments are:

Argument	Definition
server[:port]	Specifies the name of the target SilverStream server and the administration port
database	Specifies the name of the database whose table list you want to modify
-f file	Specifies a file containing the names of the database tables See the modify_table_list_sample.xml file in the SilverStreamInstallDir\samples\SilverCmd directory for an example.
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	User name and password for SilverStream authentication

Specifying tables in the input file   Your input file specifies the tables you want to include or make accessible to SilverStream. The input file can include either a list of individual table names to include, a list of table name patterns, or a combination.

When you specify a pattern, you can use the % symbol to match any number of characters and the underscore (_) character to specify that you want to match any one character.

Prefs

Updates the following compiler settings in the Designer preferences file:

• Compiler name and directory

• Compiler flags

• Compile cache directory

• SilverStream debug flags

The preferences file contains additional information that is not settable from the Prefs command line. Any compiler values not specified via the command line or in the input file are left unchanged in the preferences file. To change any other settings, such as, the default browser, you must use the Edit>Preferences menu option in the Main Designer.

    For more information on changing these setttings, see the chapter on the Main Designer in the Tools Guide in the server's Classic Development Help.

NOTE   You should stop the Designer before executing the Prefs command. If the Designer is running, the changes will not take effect.

Syntax

  SilverCmd Prefs [options]

The valid options are:

Option	Description
-?	Displays the usage message
-a flags	Sets the compiler-specific flags. It must be a quoted string. If compiler flags start with a dash (-), eliminate the space between the -a and the flags. For example: SilverCmd Prefs -c sj "-a-nodeprecated -noinline"
-c name	Sets the compiler type. The value can only be one of the following: SunJavacInProc javac sj jikes
-d dir	Sets the compiler's directory
-f file	Specifies an input file that contains the new compiler preferences Values specified at the command line override input file settings See the prefs_sample.xml file in the SilverStreamInstallDir\samples\SilverCmd directory for an example that shows how to create one of these files
-g true/false	Turns debugging information on or off Debug is off by default
-l	Lists existing preferences to the console
-s file	Saves existing preferences to the specified file
-t dir	Sets the compile-cache directory

Setting Debug Flags   The DebugFlags option is not a directive to the compiler, but to SilverStream. It specifies whether or not AgfForm.debugPrint() should print. An existing preferences file might list the value as 0 or 1, but when you set this flag, you should always set it to a Boolean value (true or false). You cannot change the debug flags option at the command line; you must set it via the XML file specified using the -f option.

Publish

Publishes items from one database or server to another.

Syntax

  SilverCmd Publish sourceserver[:port] sourcedatabase
  targetserver[:port] targetdatabase -f file [options]

The valid arguments are:

Argument	Definition
sourceserver[:port]	Specifies the name of the source SilverStream server and the design-time port
sourcedatabase	Specifies the name of the source database
targetserver[:port]	Specifies the name of the target SilverStream server and the design-time port
targetdatabase	Specifies the name of the target database
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	User name and password for source SilverStream server for authentication
-V and -Q	User name and password for destination SilverStream server for authentication; if not specified, values given for -U and -P are used
-a	Publishes the contents of the database
-f file	Specifies the name of a file that specifies the publish list You can only specify -f when -a is not specified
-c	Forces an overwrite of read-only items in the destination database This setting is ignored when the destination database is not part of source control
-s	Specifies that Publish should strip design information from the items published

PublishFromFile

Publishes SilverStream components from the specified directory on disk to the appropriate directory on the specified SilverStream server and database. You can only publish items that were downloaded using PublishToFile (not exported) from a SilverStream server because they must be in the expected file format. SilverCmd places the objects in the appropriate server directory. For example, forms are uploaded to the forms directory, pages to the page directory, and so on.

    For more information, see PublishToFile.

If you are publishing items without their .CLASS files, you must build the objects after uploading them.

Syntax

  SilverCmd PublishFromFile server[:port] database [fileorDir] [options]

The valid arguments are:

Argument	Definition
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target database
fileorDir	Specifies the source file or directory to publish
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	User name and password for SilverStream authentication
-f file	Specifies an input file that contains the list of items to upload The file should be in the format specified by the FileList.DTD in the SilverStream/DTDs directory
-s	Specifies that SilverStream should copy items from the specified directory recursively

PublishToFile

Downloads the components of an application database from the server to a specified location on disk, or to the current working directory if no directory is specified.

The PublishToFile operation maintains the server's directory structure for the items it downloads. For example, if you specify that the items be downloaded to the C:\test directory, SilverCmd downloads forms to the c:\test\Forms, pages to the c:\test\Pages, business objects to the c:\test\Objects, and so on.

You might use PublishToFile in conjunction with PublishFromFile when you want to transfer application components indirectly between servers. Suppose, for example, that you have created an application that you want to install (not Publish) on another server. You would use PublishToFile to obtain all of the application's files including all of the necessary components (such as Java code, metadata information, and associated data such as HTML for pages, and so on). You might then create a script that runs the SilverCmd PublishFromFile command to put them on the target server.

Syntax

  SilverCmd PublishToFile server[:port] database [item] [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target database
item	The name of a single item to publish Specifications include: For forms, views, or pages, use: dir/itemname For business objects, use: Objects/packagename/itemname For items in the Media directory: Media/dir/itemname where dir can be Jars, Images, Sounds, or General
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	User name and password for SilverStream authentication
-c	Specifies that the download should exclude the CLASS files
-d dir	Specifies the output directory. SilverCmd creates the directory if it does not exist.
-f	Specifies an input file that contains a list of items to download.
-s	Specifies that SilverStream should strip the design metadata and the Java source code
-x	Specifies that the download should be in XML format instead of binary (binary is the default Binary format is more compact and faster to read and write than XML format. If you were building an installer (by downloading the objects and then using Upload at install time to install them), you might want to use binary format.

QuickDeployEJB

Compiles and deploys the EJB components that have changed since the last full deployment.

As with DeployEJB, the EJBs can be authored using SilverStream tools or can be authored using external tools. The source files can already reside on the SilverStream server or can reside on disk.

QuickDeployEJB performs these tasks:

1. Searches the EJB JAR for those classes that have been modified since the last full deployment and determines if they are a home or remote interface of any bean in the EJB JAR.

2. If there are modified class files:

   • Disables the EJB deployed object

   • If the modified classes are not the home or remote interfaces for any of the EJB components, QuickDeployEJB adds the updated classes to the EJB deployed object

   • If the modified classes are the home or remote interfaces for any of the EJB components, QuickDeployEJB runs RMIC on the modified classes and adds the classes to the deployed object and the generated stubs to the remote JAR

   • Re-enables the deployed object.

This command is particularly useful during the development phase when you are making small iterative changes to your EJBs. If your changes include deleting or renaming existing classes, you must do a full deployment using DeployEJB or the Deployment Plan Designer.

If you change the deployment plan, you cannot use QuickDeployEJB until you have completed a full deploy using the Deployment Plan Designer or SilverCmd DeployEJB.

Syntax

  SilverCmd QuickDeployEJB server[:port] database deploymentPlan [-j ejbJar] [-d ejbDeployedName] [-r ejbRemoteJar] [-R remoteJarPath] [-s (JSDFile|rootDirectory)] [-U user] [-P password] [-?]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target SilverStream database containing the EJB deployed object and remote JAR to be updated
deploymentPlan	Specifies the name of the XML-based file containing the EJB deployment information. This file must reside in file system, not the specified database.

Options   The valid options are:

Option	Description
-?	Displays the usage message
-j ejbJar	Specifies the name of the JAR containing the EJBs to deploy. If this argument is not specified on the command line, it must be specified in the deployment plan file. Values specified at the command line override input file settings. This file can reside on the file system or the database. QuickDeployEJB first checks to see if a file of the given name exists locally, then it checks the specified server and database for the JAR.
-d ejbDeployedName	Specifies the name for the deployed object created by the command. If this argument is not specified at the command line, it must be specified in the deployment plan using the <deployedObject> tag. Values specified at the command line override input file settings.
-r ejbRemoteJar	Specifies the name for the remote JAR created by the command. If this argument is not specified at the command line, it must be specified in the deployment plan file. Values specified at the command line override input file settings.
-R remoteJarPath	Creates a copy in the of the generated remote JAR in the directory path given. It will have the same name as the remote JAR generated on the server.
-s JSDFile or -s rootDirectory	Specifies the JAR Source Descriptor file or the root directory containing the source files listed in the EJB JAR file. The JAR Source Descriptor file maps the files on the local file system to their location in the EJB JAR file. The rootDirectory is a local root directory that represents the root of the sources in the EJB JAR file. When -s is not specified, it is assumed that the EJB JAR and its sources are on the server.     For more information, see the Understanding JAR Source Descriptor files.
-U and -P	User name and password for server authentication

Understanding JAR Source Descriptor files

JAR Source Descriptor (JSD) files are used to map the location of a file on disk to a resource in an EJB archive or a WAR. The SilverCmd QuickDeployXXX commands use this file.

JSD file format   The JSD file format is a two column list where:

• The first column specifies the path of a file on disk.

• The second column specifies the name of the resource in the archive.

For example:

  RootDir=directoryPath
  
  localFilePath     resourcePath
  localFilePath     resourcePath
  localFilePath     resourcePath
  ...

• The RootDir=directoryPath directive is optional. It can appear only once at the top of the JSD file.

• The directoryPath argument is the root directory to use if the localFilePath arguments are relative instead of absolute.

  If the names are relative, then they are interpreted to be relative to this directory. If no RootDir argument is specified then relative file names are assumed to be relative to the current directory.

• You should specify the localFilePath using the / path separator.

  NOTE   You can use the local system's syntax; however, SilverStream recommends against this to ensure portability.

• You must specify the resourcePath as it is in the archive. It must always us the / file separator.

• To specify a comment line, use the # character. All characters up to the end of the line are ignored.

• You can specify an optional recursion marker (**) followed by a wildcard pattern to match file names.

  • The pattern can contain * to match any number of any characters.

  • When wildcards are used in the localFilePath, the resourcePath is treated as a directory and the resource is given the same base name as was matched in the local file system. For example if you had the following directory structure:

    com
         myco
           package1
              foo.java
              foo.class
              image1.gif
           package2
              foo2.java
              foo2.class
  

  You might have the following line in your JSD file:

    /com/myco/package1/*.*        com/myco/package1
  

  In this case, the archive would end up with:

    com/myco/package1/foo.java
    com/myco/package1/foo.class
    com/myco/package1/image1.gif
  

  To match all directories under a root, use the recursion marker ** as in:

    /com/myco/**/*.class  com/myco
  

  In this case the archive would contain:

    com/myco/package1/foo.class
    com/myco/package2/foo2.class
  

  The pattern can be a logical expression containing & for logical AND, | for logical OR, ! or logical NOT and parentheses for grouping. Matches are not case sensitive. For example, to include all classes or images in package1 you could specify:

    /com/myco/package1/*.class|*.gif
  

  Another way might be:

    /com/myco/package1/!*.java
  

  which would match everything that was not a Java source file.

Example files   Here is an example of a JSD file for a WAR:

  # test.war's Jar Source Descriptor file
  # Root directory for relative names in left hand column
  RootDir=/j2ee/wars/testwar
  # Local file Jar resource
  # ---------- ------------
  META-INF/MANIFEST.MF /META-INF/MANIFEST.MF
  WARTest1/**/*                     /WARTest1
  WEB-INF/web.xml                  /WEB-INF/web.xml
  WEB-INF/classes/**/*.class      /WEB-INF/classes
  WEB-INF/lib/*.jar|*.zip        /WEB-INF/lib

QuickDeployWAR

Compiles theJSP's implementation class and deploys the classes that have changed since the last full deployment. This command is particularly useful when you are making small iterative changes to your code.

QuickDeployWAR performs these steps:

1. Searches the source files for the application to find JSPs that have been modified

2. Compiles the modified JSPs into servlet Java source files

3. Compiles the servlet Java source files into class files

4. Deploys JARs that contain the changes made and prepends them to the classpath used by the server

When you run the QuickDeployWAR utility, you need to specify the location of all source files for your Web application so that QuickDeployWAR can check for changes. You do this using the -s option and by specifying one of the following:

• A root directory on the local file system that represents the root of the sources in the WAR file

• The name of a JAR Source Descriptor (JSD) file that maps the files on the local file system to their location in the WAR file

    For more information on writing JSD files, see Understanding JAR Source Descriptor files.

Syntax

  SilverCmd QuickDeployWAR server[:port] database [WARFile] -f deploymentPlan -s JSDFile|rootDirectory [options]

The valid arguments are:

Argument	Description
server[:port]	The name of the server where the original WAR file was deployed.
database	The name of the database where the original WAR file was deployed.
-f deploymentPlan	The name of the XML-based file containing the JSP's deployment information.
-s JDSFile or -s rootDirectory	The Jar Source Descriptor file that maps the files on the local file system to their location in the WAR file. A local root directory that represents the root of the sources in the WAR file. This is a required argument.     For more information, see the Understanding JAR Source Descriptor files.

Options   The valid options are:

Option	Description
-?	Displays the usage message
-U and -P	User name and password for server authentication
-i	Ignore JSP compile errors and deploy whatever compiles successfully.

RebuildJAR

Rebuilds SilverStream-generated JAR files.

You might use RebuildJAR when certain components of your application that are part of a JAR have changed or when you want to insert new packages or business objects into your JAR. For example, you might have changed a GIF or added a new package as a subpackage. The RebuildJAR operation discards the old items and inserts the new ones. You might think of RebuildJAR as "edit existing JAR and save changes".

You cannot use RebuildJar to add or remove objects from the JAR. RebuildJAR takes the most recent versions of the objects that exist in the current JAR. This means that for specific items, such as Forms/form1 or Views/view1, the newer versions of these items (if any) replace the existing ones. For directories, such as Forms, Views and so on, only the items that were in those directories at the time of the JAR's creation will be reinserted. This is not so for packages, whose contents are dynamically regenerated each time you rebuild. For example, if the user adds any new classes to a package, they will get inserted into the JAR, older versions of existing classes substituted for newer ones, and any deletions reflected in warning messages.

Restrictions   You cannot rebuild JAR files created outside the SilverStream IDE.

Syntax

  SilverCmd RebuildJAR server[:port] database jarfile [options]

The valid arguments are:

Argument	Definition
server[:port]	Specifies the name of the source SilverStream server and the design-time port
database	Specifies the name of the source database
jarfile	Specifies the name of the JAR file to rebuild
options	Specifies operating criteria for the command

RebuildJar supports the following options:

Options	Description
-?	Displays the usage message
-U and -P	User name and password for SilverStream authentication

RemoveDatabase

Removes the database from the server's list of accessible databases.

NOTE   If you have configured separate ports, you will need to specify the administration port when running RemoveDatabase.

Syntax

SilverCmd RemoveDatabase server[:port] database [options]

The valid arguments are:

Argument	Definition
server[:port]	Specifies the name of the source SilverStream server and the administration port
database	Specifies the name of the source database
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Print the usage message
-U and -P	User name and password for SilverStream authentication

ServerState

Manages the server's state. Use it to shut down a server or test whether the server is currently running. For example, you can use this from an installation script.

NOTE   ServerState can be run on any (runtime, design-time, or administration) port with the isrunning action, if you have configured separate ports. If you run ServerState with the shutdown action, you must specify the administration port.

Syntax

  SilverCmd ServerState server[:port] action [options]

The valid arguments are:

Argument	Definition
server[:port]	Specifies the name of the source SilverStream server and the port. The required port depends on which of the following two actions you specify.
action	Specifies one of the following: isrunning - Returns a message when the server is (or is not) running. You can run ServerState with the isrunning action on any (runtime, design-time, or administration). This action must be run as part of a batch file or script. shutdown - Gracefully shuts down the SilverStream server. You must enter the administration port, when running this action; otherwise a security error code is returned.
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	User name and password for SilverStream authentication
-d	Deactivate the target server
-r	Restart the target server

SetDefaultURL

Sets the default URL for a server or database.

    For more information about default URLs, see the chapter on the Main Designer in the Tools Guide of the server's Classic Development Help.

Syntax

  SilverCmd SetDefaultURL server[:port] [database] [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the target SilverStream server and the design-time port
database	Specifies the target SilverStream database; include only if setting a database-default URL (see the examples below)
options	Specifies operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	Specifies user name and password for SilverStream authentication
-e URL	Specifies a server-relative URL (database/URL) or a database-relative URL (URL) Here is a server-relative URL: /MyDatabase/SilverStream/Pages/pgHome.html Here is a database-relative URL: /SilverStream/Pages/pgHome.html

Examples

Setting server-default URLs   When setting a server-default URL, do not specify a database name as an argument, and specify an URL using a server-relative URL.

For example, the following command sets a server-default URL for the server myServer:

  SilverCmd SetDefaultURL myServer 
  -e /MyDatabase/SilverStream/Pages/pgHome.html

Setting database-default URLs   When setting a database-default URL, specify the database name as an argument, and use a database-relative URL.

For example, the following command sets a database-default URL for the database myDatabase on the server myServer:

  SilverCmd SetDefaultURL myServer myDatabase 
  -e /SilverStream/Pages/pgHome.html

SetSecurity

Sets Read, Write, Protect, Select, and Execute security permissions on the SilverStream server, a database, a directory, or one or more objects. Certain permission types are applicable only for certain types of items. For example, the Select permission is only applicable to tables.

You can also set permissions on the Security directory of a server. The Read permission on this resource rules who can have access to user and group information such as lists of users and groups and user/group properties. The Protect permission rules who can set the permissions on the Security directory.

NOTE   If you have configured separate ports, you will need to specify the administration port when running SetSecurity.

Syntax

  SilverCmd SetSecurity server[:port] [database] -f file [options]

The valid arguments are:

Argument	Definition
server[:port]	Specifies the name of the SilverStream server and the administration port
[database]	Specifies the name of the database Do not specify this value when setting server permissions
-f file	Specifies the fully qualified name for an input file whose contents specify the security permissions information
options	Specifies the operating criteria for the command

The valid options are:

Option	Definition
-?	Displays the usage message
-U and -P	Specifies user name and password for SilverStream authentication
-i	Continue on error

SetUserGroupInfo

Creates and deletes SilverStream users and groups, adds users to groups, sets properties for both.

NOTE   If you have configured separate ports, you will need to specify the administration port when running SetUserGroupInfo to change settings.

Syntax

  SilverCmd SetUserGroupInfo server[:port] 
       [action action-parameters] [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the SilverStream server and the administration port
[action]	Specifies the action to perform--for example, CreateUser or DeleteUser
[action-parameters]	Specifies any special operating criteria for the action
options	Specifies operating criteria for the command

The SetUserGroupInfo options are:

Option	Description
-?	Displays the usage message
-f file	Specifies the name of a file containing data for the SetUserGroupInfo command
-i	Continues on error This is valid in batch mode only
-U and -P	User name and password for SilverStream authentication

The SetUserGroupInfo actions are:

Action	Description
AddUserToGroup	Adds a user to a SilverStream security group
CreateGroup	Creates a SilverStream security group
CreateUser	Creates a SilverStream user or certificate
DeleteGroup	Deletes a SilverStream group from the server
DeleteUser	Deletes a SilverStream user from the server
DeleteUserFromGroup	Deletes a SilverStream user from the specified SilverStream group
SetGroupProperties	Specifies properties for an existing SilverStream group
SetUserProperties	Specifies properties for an existing SilverStream user

The AddUserToGroup Action

Adds an existing user from a known security realm (for example, NT) to an existing SilverStream security group.

Syntax

  SilverCmd SetUserGroupInfo server[:port] AddUserToGroup "username"
  "groupname" [options] 

The action-parameters are:

Action-parameter	Description
user name	Specifies the name of the user to add. The name must be in a valid login format     For more information about supplying these values for the security realms, see the chapter on setting up security in the Administrator's Guide.
groupname	Specifies the name of the SilverStream group to which you want to add the user If the name includes spaces, it must be quoted

Examples

This example shows how to adds the NT user admin to the SilverStream group Admins.

  SilverCmd SetUserGroupInfo localhost AddUserToGroup
  ntDomain1\admin Admins

This example shows how to add the NT user admin to the SilverStream group "Our NT Administrators".

  SilverCmd SetUserGroupInfo localhost AddUserToGroup
  ntDomain1\admin "Our NT Administrators"

The CreateGroup Action

Creates a SilverStream security group for the specified server.

Syntax

  SilverCmd SetUserGroupInfo server[:port] CreateGroup -g
  "groupname" [-d "description"]

The valid arguments are:

Argument	Description
-g groupname	Specifies the name of the group This value is required
-d description	Specifies a description for the group. This value is optional. If the description includes spaces, it must be enclosed in quotes.

Examples

The following examples show how to create three different SilverStream groups: one called Developers, one called Our Administrators, and one called Finance.

  SilverCmd SetUserGroupInfo localhost CreateGroup -g "Developers" -
  d "Research and Development Group"
  
  SilverCmd SetUserGroupInfo localhost CreateGroup -g "Our
  Administrators" -d "Our Admins" -l 
  
  SilverCmd SetUserGroupInfo http://myserver CreateGroup -g
  "Finance"

The CreateUser Action

Creates a SilverStream user by specifying a user name/password or a certificate user.

Syntax

  SilverCmd SetUserGroupInfo server[:port] CreateUser -u "username"
  [-p "password"] [-n "full name"] [-d "description"]

or

  SilverCmd SetUserGroupInfo server[:port] CreateUser 
     -c client-certificate-file

The valid arguments are:

Argument	Description
-c client-certificate-file	Specifies the client certificate file
-d description	Specifies a description for the user. If the description includes spaces, it must be enclosed in quotes. This value is optional.
-n name	Specifies the user's full name. If the name includes spaces, it must be enclosed in quotes. This value is optional.
-p password	Specifies the user's SilverStream password. This value is optional. Note that this value is different than the -U and -P (uppercase) parameters used for authenticating the user running SilverCmd.
-u username	Specifies the name by which the new user will be known to SilverStream. This value is required except when specifying a client certificate file. Note that this value is different than the -U and -P (uppercase) parameters used for authenticating the user running SilverCmd.

Examples

This example shows how to create a new user.

  SilverCmd SetUserGroupInfo http://myserver CreateUser -u "user1" -
  p "password" -n "John Brown" -d "Applications Developer"
  
  SilverCmd SetUserGroupInfo localhost CreateUser -u "user1" -n
  "John Brown"
  
  SilverCmd SetUserGroupInfo localhost CreateUser -u "user1"

This example shows how to create a certificate user, given a client certificate file.

  SilverCmd SetUserGroupInfo localhost CreateUser -c
  c:\certs\ClientCert1.cer

The DeleteGroup Action

Deletes a SilverStream group.

Syntax

  SilverCmd SetUserGroupInfo server[:port] DeleteGroup "groupname"

The valid arguments are:

Argument	Description
groupname	Specifies the name of the group to delete

For example,

  SilverCmd SetUserGroupInfo localhost DeleteGroup "TestGroup"

The DeleteUser Action

Deletes a SilverStream user.

Syntax

  SilverCmd SetUserGroupInfo server[:port] DeleteUser "username"

The valid arguments are:

Argument	Description
username	Specifies the name of the user to delete

For example:

  SilverCmd SetUserGroupInfo http://myserver DeleteUser "testUser1"

To delete a certificate user:

  SilverCmd SetUserGroupInfo localhost DeleteUser "CERT\\Jack Brown, DigitalID Class 1 - Microsoft Full Service, VeriSign, Inc. (28f52c889e8d6d8cf21d932d9b71z705)"

You must specify the complete distinguished name of the certificate user.

The constant CERT\\ must be prepended to the distinguished name in order to disambiguate it. CERT means Certificate Security Realm.

The \\ signifies a security authority that is not present in this case.

With NT, for example, the name would look something like this:

  NT\domainname\user1

With Certificate Security Realm, no authorities are specified.

You can specify the default security realm (via the SMC or by setting the AgiAdmServer.PROP_DEFAULT_SECURITY_REALM property on the server object). If you set the default to "Certificate Security Realm" (for example, by setting the property value to "CERT"), then there would be no need for the "CERT\\" part because it would be assumed by default.

The DeleteUserFromGroup Action

Deletes a user from a SilverStream group.

Syntax

  SilverCmd SetUserGroupInfo server[:port] DeleteUserFromGroup "username" "groupname"

The valid arguments are:

Argument	Description
username	Specifies the name of the user to delete from the group
groupname	Specifies the name of the SilverStream group from which to delete the user

For example:

  SilverCmd SetUserGroupInfo localhost DeleteUserFromGroup
  ntDomain1\admin Admins

Using SetGroupProperties

Sets properties for a SilverStream group. Any properties that are not specified retain their original values.

Syntax

  SilverCmd SetUserGroupInfo server[:port] SetGroupProperties
     -g "groupname" [-d "description" -l "is locksmith"]

The valid arguments are:

Argument	Description
-g groupname	Specifies the name of the group
-d description	Provides a description of the group
-l islocksmith	Specifies the locksmith value which may be true or false You may set is locksmith on any type of group, not just SilverStream groups You can only grant locksmith privileges if you have them--for example, if you are a locksmith The value true means grant the privilege and false means revoke the privilege

Examples

  SilverCmd SetUserGroupInfo myserver SetGroupProperties -g
  testGroup -d "This is a test group"
  
  SilverCmd SetUserGroupInfo myserver SetGroupProperties -g "Our
  Administrators" -l false

The SetUserProperties Action

Modifies properties for a SilverStream or certificate user. Values not specified are not modified.

Syntax

  SilverCmd SetUserGroupInfo server[:port] SetUserProperties -u
  "username" -p "password" -n "full name" [-d "description"] [-l "is
  locksmith"]

or

  SilverCmd SetUserGroupInfo server[:port] SetUserProperties -c
  "certificate-file" [-l "is locksmith"]

The valid arguments are:

Argument	Description
-c certificate-file	Specifies the certificate file for updating the certificate users This is a required value for certificate files and is not configurable
-d description	Provides a description of the user
-l is-locksmith	Specifies the locksmith privilege value You can give locksmith privileges to any type of user, not just SilverUser or CertificateUser You can only grant locksmith privileges if you have them--for example, if you are a locksmith The value true means grant the privilege and false means revoke the privilege
-n name	Specifies a full name for the user
-p password	Specifies a new password for the user
-u username	Specifies the user name for the user whose properties you want to change. This value is required and is not configurable

For example:

  SilverCmd SetUserGroupInfo localhost SetUserProperties -u "jsmith"
       -p "new password" -l false
  SilverCmd SetUserGroupInfo localhost SetUserProperties -u "jsmith"
       -n "Jonathan H. Smith"
  SilverCmd SetUserGroupInfo localhost SetUserProperties -u "jsmith"
       -d "Principal Engineer" -p "new pwd"

SourceControl

Performs source control tasks.

Before you can run the SourceControl command, you must have one of the SilverStream supported source control software packages installed and your SilverStream application database set up to use it. You cannot set up a database for source control using the SourceControl command line tool. For setup information, see the chapter on source control in the Tools Guide of the server's Classic Development Help.

Syntax

  SilverCmd SourceControl server[:port] database action [item] [options]

The valid arguments are:

Argument	Description
server[:port]	Specifies the name of the target SilverStream server and the design-time port
database	Specifies the name of the target database that contains your SilverStream application components This database must already be configured to use a source control system
item	Specifies the name of the SilverStream application object on which you want to perform the source control operation The name must be specified using the SilverStream server's directory structure-- for example: Forms/formname or Media/Jars/jarname. To work with multiple items, you must specify them in an input file which you specify using the -f file argument
action	Specifies the source control action to execute Valid values are Get, Checkin, Checkout, and Undocheckout These values are not case-sensitive
options	Specifies operating criteria for the action If you supply an option that is not valid for the current action, SilverCmd executes the action and ignores any invalid options See the table below for more information on the valid options

You can customize the source control operation (Get, Checkin, and so on) using the options described in the following table.

Option	Description
-?	Displays the SourceControl usage message
-U username and -P password	User name and password for SilverStream authentication
-c comment	Specifies the comment to use for Checkin operations. The text must be in quotes. For example: SilverCmd SourceControl Checkin -c "This is a comment" localhost MyApp Forms/myForm This option is only valid for Checkin operations
-d date	Gets an object checked in on a specific date Valid formats are: -d 4/4/98 -d 4/4/1998 -d 1998-4-4 -d "4/4/98 3:33 pm" -d "4/4/98 15:33" -d "1998-4-4 15:33:33" You can use period (.) or hyphen (-) in place of slash (/) anywhere in the date portion. The month/day order is determined by the current locale. Two-digit years are handled appropriately (98 means 1998, 02 means 2002). This option is only valid with Get operations.
-f file	The name of the input file that specifies the items on which to perform the source control operation. This is useful when you want to perform an operation on multiple files.
-l label	Gets an object that has the specified label. The label must be in quotes. For example: SilverCmd SourceControl Get -l "Version 3.0 Beta" localhost Examples3 Forms/myForm
-p password	Specifies the source control password. This must match the password exactly as configured in your source control system. The user name cannot be specified on the command linel; it must be set in the Source Control Settings dialog. If your source control access was set up to save your password, then you do not need to supply one. You can check the Source Control settings from the Designer by choosing Source>Source Control Settings SilverCmd generates an error message if the -p option is required but not specified.
-v version	Gets an object by its source control version.
-o	Confirms an action that will overwrite an existing file; for example, an Undocheckout of any file, or a Get of a checked-out file. SilverCmd fails if the specified operation will overwrite an existing file and the -y option is not specified.

The following example illustrates how to check in a form called frmCasting:

  SilverCmd SourceControl Checkin -c "updated code in FormActivate
  event"localhost MyApp Forms/frmCasting

ValidateEAR

Validates the deployment descriptor within the specified EAR file. It reports any deployment descriptor problems, missing application assembly components, and class-related problems. The problems are written to the command window by default.

Use this command when you want to verify that the descriptor is correct before attempting to deploy the enterprise archive on the SilverStream Server with DeployEAR.

Syntax

  SilverCmd ValidateEAR earfile [options]

The valid arguments are:

Argument	Description
EARFile	Specifies the name of the EAR file to validate.

The valid options are:

Option	Description
-?	Displays the usage message

ValidateEJB

Validates the deployment descriptor within the specified EJB JAR file. It reports any deployment descriptor problems, missing application assembly components, and class-related problems. The problems are written to the command window by default.

You might want to use this command if you are building your own EJB JAR and its descriptor outside the SilverStream IDE and want to verify that the descriptor is correct before importing the JAR to the SilverStream server.

Syntax

  SilverCmd ValidateEJB ejbJarFile [options]

The valid arguments are:

Argument	Description
ejbJarFile	The EJB JAR file whose beans are to be validated

The valid options are:

Option	Description
-?	Displays the ValidateEJB usage message
-c max	Maximum number of catastrophic errors allowed per bean The default is 1
-t max	Maximum number of fatal errors allowed per bean The default is 5
-n max	Maximum number of non-fatal errors allowed per bean The default is 10
-w max	Maximum number of warnings allowed per bean The default is 15

If -c, -t, -n, or -w is not specified, the default maximum for the given type of error is used.

If a numeric value is specified for the switch, SilverStream allows up to that many errors of the given type per bean and stops validating the bean when the limit is reached. If the string value of all is specified for the switch, the SilverStream will register all errors of the given type.

Facilities Guide

Copyright © 2001, SilverStream Software, Inc. All rights reserved.