Administrator's Guide

Chapter 7   Maintaining the Server

This chapter describes how to perform some typical server maintenance tasks. It has sections on the following:

Administering a SilverStream Server remotely   Top of page

You can use the SilverStream Management Console to remotely administer servers. You can administer as many servers as you want from one SMC console. If you are running a server in a cluster, you can choose additional server clusters to administer. For more information about server clusters, see Server clustering.

To choose a server:

  1. Verify that the server you want to administer is up and running.

  2. Invoke the SMC.

  3. Choose the Choose (server) icon.

  4. Type the server name and specify the port if it is not the default 80.

  5. Click OK.

  6. Use the SMC to administer the server.

Setting up mail on the server   Top of page

Handling mail received from clients is an important aspect of Web application development. SilverStream developers might write business objects that trigger when mail is received on the server. To implement this type of object the SilverStream Server must be configured to poll for e-mail in one or more mailboxes from one or more POP3 servers.

The Mail option on the SMC allows you to set up mailboxes for this purpose. For example, if a developer needs a business object to automate the maintenance of a mailing list in the database, you would first create a mail account for mailing list maintenance. Then the developer could write a business object that looks at e-mail received at that mailbox for subscribe and unsubscribe requests.

To poll for mail:

  1. Invoke the SMC.

  2. Select Configuration options.

  3. Select the Mail panel.

  4. Click New and enter data in the fields. You must provide data for all of the fields displayed on this tab.



    Check for mail every n minutes

    The time interval for the mail server to check for incoming mail messages. Enter a value or use the spinner control.

    When set to zero, the server does not check for mail.


    The e-mail ID that the server uses to receive mail. This name is like any other mail account name on your system.

    Make sure you set up a mail account specifically for the server and not for an individual user. The name is a POP3 mail account, and it should be unique to the SilverStream Server.


    The password for the mail account.


    The name of the mail server. For example,


    The port number the mail server uses to receive mail. The default port number is 110 (the default for a POP3 server).

  5. Click Update.

  6. The new settings take effect immediately.

Once enabled, the SilverStream Server acts as a POP3 client.

Managing licenses   Top of page

This section describes how to install or delete SilverStream user licenses.

About licenses   Top of page

SilverStream uses a license key to administer access to the server. License management is integrated with session management. Each user connection requires a license. The license is held for the duration of the connection.

License keys:

You receive an initial encrypted license key when you buy your product. Each product you purchase comes with a certain type of license. You use the Installation program to add this license key to your server. This information is stored in the database.

You may only need the initial user-based license key during your application development cycle. However, when it comes time to deploy your application and go live, you will probably want to call SilverStream and purchase CPU-based licenses for your application server.

If you have a user-based license, and your application is put into production, when the number of simultaneous users increase, you may see a message like this:

  "Maximum server sessions exceeded" 

You should add new licenses through the SilverStream Installation program.

When you have multiple licenses installed, SilverStream will use the least restrictive license it finds. For example, if you have installed both a single-user license and a CPU-based license, SilverStream uses the CPU-based license.

To add licenses (NT):

  1. Shut down the SilverStream Server.

  2. Run the SilverStream Installation program.

  3. From the Setup Function screen select Add a new server license.

    The License Information screen appears.

  4. Fill in the license serial number. If you receive this long encrypted number electronically, paste it into the License number field to avoid typing errors.

  5. Specify the requested information for your SilverMaster, where the license information is stored.

  6. Click Finish.

    SilverStream uses the license number and other information you enter to generate an encrypted license key.

To add licenses (UNIX):

  1. Shut down the SilverStream Server.

  2. Run the utility, which is at the root directory on the SilverStream CD.

  3. When prompted, specify where SilverStream is installed and what the license string is.

    SilverStream generates an encrypted license key.

To access or delete a license:

  1. Invoke the SMC.

  2. Select Configuration options.

  3. Select the Licenses panel.

    The license form displays information about your license.

  4. To delete a license, select it, then select Remove License.

Setting the AGCLASSPATH variable   Top of page

SilverStream supports an environment variable called AGCLASSPATH, which allows developers to extend Java classes. You can use this AGCLASSPATH, for example, when you want to include third-party elements such as database drivers with your application. Use this variable instead of the +cp Java class path option described in Starting the SilverStream Server. SilverStream overrides the CLASSPATH variable.

NOTE   When deploying business objects using created Java classes, SilverStream developers should create JAR files using the SilverStream Designer, rather than by setting AGCLASSPATH. For more information, see the Programmer's Guide.

In UNIX, set the environment variable AGCLASSPATH following the appropriate procedure for the shell you are using. For NT, use the following procedure.


  1. From the NT start menu, choose Settings>Control Panel.

  2. Choose the System icon, then select the Environment tab.

    The following screen appears.

  3. Type AGCLASSPATH in the Variable field, then type a path in the Value field.

  4. Click Set.

    The screen above shows AGCLASSPATH with a value of c:\myclasses.

Maintaining Enterprise JavaBeans   Top of page

You can use the SMC to maintain the Enterprise JavaBeans (EJBs) that have been deployed on a server.

    For more information about EJBs, see the part on developing EJBs in the Programmer's Guide.

To manage the EJBs:

  1. Invoke the SMC.

  2. Select Configuration options.

  3. Select the EJB panel.

  4. Expand the database you want to manage.

    The panel lists the EJB JARs that have been deployed in the selected database. It also lists the beans in the JARs.

  5. Select an EJB JAR and perform one of the following actions.



    Enable EJB JAR

    Enable a disabled EJB JAR. If a JAR is enabled, the beans in the JAR are available.

    Disable EJB JAR

    Disable an enabled EJB JAR. If a JAR is disabled, none of the beans in the JAR are available.

    Disabling a JAR stops any running EJBs in the JAR. A disabled JAR remains disabled until it is explicitly enabled.

    Shut Down EJB JAR

    Shut down the JAR and all its beans for the current server session. When a JAR is shut down, none of the beans in the JAR are available.

    When the server is restarted, enabled JARs that had been shut down in the previous server session are again available.

    Restart EJB JAR

    Shut down, then restart the EJB JAR.

Setting Fulcrum full text properties   Top of page

You can use the SMC to set some administrative properties used by the Fulcrum SearchServer full text search engine.

    For more information about Fulcrum SearchServer and how to enable full text search in SilverStream applications, see the full text search chapter in the online Tools Guide.

To set Fulcrum full text properties:

  1. Invoke the SMC.

  2. Select Configuration options.

  3. Select the Advanced panel.

  4. Select the Full Text tab.

  5. Specify values as described below.



    Indexer interval

    Specifies how often Fulcrum SearchServer checks and performs incremental indexing for rows whose full-text-search columns have been modified.

    The default is 20 minutes.

    NOTE   Indexing is forced before a query against a modified table is processed.

    Maximum result row count

    Maximum number of hits Fulcrum will return for a full text search query.

    The default is 1000. Set this value to 0 if you don't want any limit to the number of hits returned.

    Enable partial indexing at startup

    If this property is selected, SilverStream will not reindex tables marked for full text search at server startup time.

        For more information, see Indexing full-text-search tables below.

  6. Click Update.

Indexing full-text-search tables

If the Enable partial indexing at startup property is not selected, at startup time the SilverStream Server deletes all previous full-text indexing from all tables that have full index search enabled, then reindexes all the tables from scratch. After the initial indexing the tables are marked for incremental indexing only when updates are made to them within SilverStream.

Full reindexing of tables consumes resources unnecessarily if the tables are never updated outside of SilverStream.

You can select the Enable partial indexing at startup property (which is selected by default) to turn off full reindexing when the server starts. This means that at server startup, previous indexes will be maintained, tables will be marked for incremental indexing, and incremental indexing for SilverStream-modified tables will continue.

If Enable partial indexing at startup is not selected, full text search tables will be indexed from scratch each time the server starts.

NOTE   If you set this property but still have some tables that are updated outside of SilverStream, you can specify full indexing for these tables: Open the SilverStream Business Object Designer and create a business object that will fire when the server is started. Add the following line of code for each table that you want to be reindexed:

  com.ssw.srv.agents.AgFullText.index("db", "table"); 

Monitoring server activity   Top of page

The SMC provides several options that allow you to easily monitor server activity. These options are described in the following sections:

Displaying charts of server activity   Top of page

You can display real-time charts of various server statistics.

To display a chart of server activity:

  1. Select the server or cluster you are administering.

  2. Select Monitor options.

  3. Select the Charts panel.

    An empty chart displays.

  4. Click Add Plot.

    The Add Plot dialog displays, allowing you to choose which statistics you want to chart. The statistics are divided into categories.

  5. Select a statistic you want to chart and click Add. Statistics marked with are counts; statistics marked with record changes.

    The statistic is added to the table below the chart. The current value of the statistic is shown, as is the color of the plot line that will be generated.

  6. Select additional statistics if you want, clicking Add after each one.

  7. When you have selected all the statistics you are interested in, click Close.

What happens

SilverStream plots all the statistics you have specified and displays the exact values in the table below the chart. By default the values are updated every five seconds.

Changing the scale and refresh rate

You can change the scale of the Y-axis by specifying a new value in the Scale field (the default is 100). You can also change how often SilverStream updates the values by changing the value in the Refresh interval field (the default is every five seconds).

Removing a plot

To remove a plot:

Editing a plot

It may be that you are plotting different statistics with very different scales but want them to appear clearly in the chart. To do this, you can change the multiplier for particular plots to equalize the values and make the chart easier to read.

To edit a plot:

  1. Double-click the plot in the table.

    The Change Plot Detail dialog displays.

  2. Change the multiplier used to plot the value.

  3. Click OK.

Saving a statistics set

Once you have charted a set of statistics that you are interested in, you can save the specification of the statistics set in a file so that you can easily view the set of statistics later.

NOTE   The file stores the list of statistics that are plotted. It does not store the statistics' values.

To save a statistics set:

  1. Display the statistics you want to save as a set.

  2. Click Save.

    The Save dialog displays.

  3. Specify the file you want to save the statistics set in. If you don't provide an extension, SilverStream gives the file the extension META.

  4. Click Save.

    The specifications for the chart are saved in a file. You can view the statistics set later by clicking Load, as described next.

Loading a statistics set

To view a statistics set you saved previously:

  1. Click Load.

    The Open dialog displays.

  2. Select the file that defines the statistics set you want to view and click Open.

    The chart is updated to show the statistics set that had been saved in the file.

Displaying logs   Top of page

If you have enabled server logging and are using the built-in SilverStream logging class to log to the database, you can display the log(s) in realtime in the SMC. (If you are logging to a file or using a custom class to do the logging, you can't display the log in the SMC.)

    For more information about server logging, see Using server logging.

To display a log:

  1. Select the server or cluster you are administering.

  2. Select Monitor options.

  3. Select the Logs panel.

  4. Select the tab corresponding to the logging you have enabled and which you want to view.

    The log displays.

What you can do

You can:

Displaying views of server statistics   Top of page

You can display in the SMC tabular views of server statistics related to individual sessions and threads, as well as a summary of server activity.

To access server statistics in a view:

  1. Select the server or cluster you are administering.

  2. Select Monitor options.

  3. Select the Statistics tab.

  4. Select the tab for the category you want.

    Statistics are updated dynamically.

What you can do

You can:

About the statistics

The following sections describe the statistics that are displayed.

Session statistics

This tab displays statistics for each current client session.

Session statistic



Displays the session ID returned by a call to the AgiSession internal system table.

User name

Displays the user name of the person or entity logged on to this session. If unknown, displays Anonymous.


The state of the connection.

Logged in

Displays true if the user has logged in, for example, from the browser's login or the Silverstream Designer menu item. Otherwise, displays false.


Displays the host of the client source, if known.

Idle time

Displays the time elapsed (in seconds) since the last client connection on this session ended.

Protocol version

Displays the SilverStream protocol used for the session.

Viewing statistics in a browser

You can also display these statistics in a browser: Point your browser at http://server/SilverStream/Sessions.

Thread statistics

This tab displays statistics for each server thread.

Following is a description of each of the fields.

Thread statistic



Non-client threads are used for various internal tasks, such as cleaning up server data structures, indexing full-text tables, and so on. Client threads handle incoming requests. There should be at least as many client threads as there are MAXCLIENTCONNS listed in the SMC Connections panel (see Client connection parameters).

ResultBuffer threads are prefetch buffer threads as defined in the SMC (see Setting performance parameters). They are dynamically added as needed, but should not exceed the number defined in the SMC.


A brief description of the current state of the thread.

Start date

The start date for the thread. In many cases this date is the same as when the server was started. However for dynamically allocated threads (such as prefetch buffers) this value will be different.

Busy time

The elapsed time (in seconds) since the thread has been actively working, as opposed to waiting. This value reflects how busy the server is in general.


An internal session ID for this thread. Refer to the Sessions tab to determine user/host information.

Summary statistics

This tab provides access to different types of category summaries. The following describes the items for each tab selection.

Viewing statistics in a browser

You can also display most of these summary statistics in a browser: Point your browser at http://server:port/SilverStream/Statistics. The page updates itself automatically every five seconds.

Integrating with existing Web servers   Top of page

SilverStream provides a mechanism that allows you to redirect requests for selected pages served by your Web server to a SilverStream Server. This mechanism is implemented by SilverJunction, an NSAPI/ISAPI module that can be installed on Microsoft Internet Information Server or Netscape Enterprise/Fast Track Web servers.

    For information on installing SilverJunction, see the Installation Guide.

Using SilverJunction   Top of page

Through the use of HTTP redirect mechanisms, SilverJunction allows for one-time redirects from standard Web servers. SilverStream uses two HTTP redirect calls: 302 for 1.0 implementations and 307 for 1.1 implementations. These implementations are executed at the browser level and are hidden from the user.

The example in this section describes a typical implementation of the SilverJunction plug-in. ABCDE Company has an IIS server that is accessible by clients at the host The company catalog resides at The catalog has been redesigned and improved using SilverStream, and now runs on a SilverStream Server at the following URL: 

ABCDE's Web master does not want to break any existing links that may point to the old location of the catalog so the Web master installs a SilverJunction filter (plug-in) for IIS on the original Web server. Then the Web master writes a configuration file specifying that all requests that come to the Web server at and whose relative URL portion looks like "/catalog/*" should be redirected to*.

Given this setup, an HTTP 1.1 browser pointed to: 

receives a temporary redirect (HTTP code 307) to: 

If the SilverStream Server is running as part of a cluster, the Dispatcher will redirect the request to an appropriate SilverStream Server.

Once the user has been redirected to the SilverStream Server, subsequent calls will go directly to the SilverStream Server and not to the original Web server. The SilverJunction mechanism may mask the URL on the first redirect but since the user has been fully redirected to the SilverStream Server, the URL may not be masked on subsequent requests.

The following shows how SilverJunction works using a standalone SilverStream Server. The initial client request directed at the IIS server is redirected back to the client to be resent directly to the SilverStream Server.

The following shows how SilverJunction works in a clustered server environment. In this case the client request is redirected twice. The first redirect goes to the Dispatcher, which then redirects the request to an appropriate server. For more information, see Administering a Cluster.

To configure SilverStream as a plug-in:

  1. Open the metadata file called SilverJunction.jdl, located in SilverStream/Resources.

    By default, the configuration file SilverJunction.jdl is found in the Silverstream/resources directory. The IIS version of SilverJunction will always look for it in this location.

    For an NSAPI (NetScape) version, the location of the configuration file is determined by initialization parameters specified in the obj.conf file. This is done by inserting the following lines:

      Init fn=init_redirect 

    For more information, see the Netscape Server documentation.

    The following is an example of a setup in SilverJunction.jdl.

          /Host ''
          /Port 8002
          /From '/S2/'
          /To '/'
          /From '/demo1'
          /To '/silverstream1/db2/user3'
  2. Edit the values as described below:

    You must enter a TARGET_SERVER. Both /Host and /Port properties must be defined.


Given the settings in the preceding file a request for /demo1/main.htm is redirected to: 

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