Administrator's Guide



Chapter 12   Troubleshooting

This chapter describes some techniques and procedures that you can use for troubleshooting the SilverStream Server.

This chapter contains the following sections:

Using error logging   Top of page

SilverStream recommends that you turn on error logging at all times when running the server. Error logging is a lightweight process that prints detailed information about error messages either to the AgErrorLog table in the SilverMaster or to a file that you designate. You can activate logging using the SilverStream Management Console (SMC). For more information, see Using server logging.

When logging to the SilverMaster, you can view the log in two ways:

To create a view for error logging:

  1. Start the Designer and navigate to the SilverMaster database.

  2. Open the View wizard.

  3. Create a view of the AgErrorLog table with the following specifications:

Low-level debugging   Top of page

The Debug options in the SMC enable the printing of server debug messages to the Server Console. Options include debugging client requests, SilverStream business object execution, and database SQL statements. Activate debugging options only for application debugging purposes, as this activity can significantly inhibit server performance.

    For more information about the Server Console, see the Main Designer in the online Tools Guide.

NOTE   If you are running the server as a service in Windows NT, the output is printed to the error log instead of the Server Console.

To print debugging messages:

  1. Invoke the SMC.

  2. Select Configuration options.

  3. Select the Advanced panel.

  4. Select the Debug tab.

  5. Change the value for the type of activity that you are debugging.

    The number you enter indicates the level of detail you want displayed. The value 0 means that messages are not printed. You have the following debugging options:

    Field

    Description

    Client

    • If this parameter is set to 1, the server logs information for each client (such as http GETs, PUTs, and POSTs).

    • If set to 2 or greater, the server logs the complete request and reply message to the console window.

    This option is useful when having problems with HTTP, servlets, and other client-related issues.

    Business objects

    If this parameter is set to 1 or higher, the server logs information about the execution of each running business object.

    • If set to 1 or 2, provides minimal or maximal information about methods called in the public SilverStream API.

    • If set to 3 or 4, provides minimal or maximal information about all methods called, even methods not in the public SilverStream API. Set this parameter to 3 or 4 if requested by SilverStream Technical Support.

    • If set to 5, echoes all output to ServletOutputStreams, so you can see what is being output from the business object.

    • If set to 6, includes stack traces of various calls, so you can see where calls are being made.

    SQL

    • If this parameter is set to 1, the server logs each SQL statement executed against the database for client data.

    • If set to 2 or greater, the server logs additional information that the SilverStream Technical Support group can use to track down server problems.

    This option is useful for debugging database-related problems.

Setting JDBC/ODBC tracing   Top of page

If you experience persistent problems with a database connection, you can turn on JDBC or ODBC tracing. As a rule, you should use JDBC tracing. Use ODBC tracing only for databases accessed through ODBC.

To set JDBC tracing:

  1. If necessary create a log file for storing trace data.

  2. Shut down the server (see Shutting down the SilverStream Server).

  3. Open the httpd.props file located in SilverStream\resources.

  4. Add an http-server.Jdbc.DriverManager.LogFile entry to the props file and point it to the log file. For example, if the log file is d:\test\jdbc.log, create this line in your httpd.props file:

      http-server.Jdbc.DriverManager.LogFile=d:\\test\\jdbc.log 
  5. Restart the server.

    NOTE   Use JDBC tracing for troubleshooting only, as it will slow down the server and use considerable disk space.

To set ODBC tracing:

  1. From the Start menu, choose Settings.

  2. Open the ODBC panel to display the ODBC Data Source Administrator.

  3. Select the Tracing tab.

  4. Enable When to Trace to either One-time only or All the time.

    NOTE   If you set it to All the time your system will be slower. Also, this setting will take up disk space on your system.

Using the Watcher   Top of page

SilverStream provides the Watcher tool, which can help you understand the state of the server in cases when the server becomes unresponsive. Once activated, the Watcher logs the state of the server once a minute.

You might find the Watcher valuable when faced with problems that are hard to debug.

To use the Watcher:

  1. Add the following property to the httpd.props file:

      http-server.com.sssw.srv.httpdwatcher 
  2. Set the value of the property to the pathname of a watcher configuration file. For example:

      http-server.com.sssw.srv.httpdwatcher=c:\\temp\\watchconfig.txt 

    (Remember to escape backslashes in the httpd.props file.)

What happens

If this property is set when the server is started, the server will create a watcher thread. The watcher thread just sleeps, waking up once a minute, and checking each time for the existence of the watcher configuration file supplied as the value of the httpdwatcher property. As long as the file doesn't exist, the Watcher does nothing and just goes back to sleep. Under these circumstances, the Watcher has minimal impact on Server performance. Furthermore, even if the server hangs, in most cases the Watcher will not hang.

If the watcher configuration file exists

When the Watcher discovers that the watcher configuration file exists, it reads the configuration file and uses it to control its further actions.

The watcher configuration file is an ASCII text file that should have one or two lines in it:

The flags value is a bit-coded integer, in which the bits are defined as follows:

A typical watcher configuration file looks like this:

  7 
c:\temp\watchout.txt

This tells the Watcher to dump information about threads, sessions, and database connections to the specified output file, once every minute.

When the watcher configuration file is removed, the server stops logging the output, so you can turn the logging on and off by creating and removing the watcher configuration file.

Problems starting the SilverStream Server   Top of page

This section describes some reasons why the SilverStream Server might fail to start, and how you can address the problem. For more information on troubleshooting server problems, see Using SilverMasterInit to recreate or refresh SilverMaster.

NOTE   Often server failure is related to the specific database you are using. For database-specific information, see the appropriate section of the Installation Guide.

There are two causes of server failure that are due to inadequate system resources:

Business object generating errors   Top of page

If an error message indicates that a server listener type of SilverStream business object is preventing the server from starting, use the -noserverlisteners server startup option. From a DOS prompt, enter the following:

  SilverStream\bin\SilverServer.exe -noserverlisteners 

This command starts the server and allows a SilverStream developer to access the object in the SilverStream Designer.

    For more information about startup options, and about stopping and starting the server, see Running the Server.

Database not synchronized   Top of page

If an error message indicates that a database is not synchronized properly, the server might fail to start. This error might occur if you use a tool outside of SilverStream to modify database schema. There are two server startup options you can use to address this problem. Before using these options, be sure that no other users are accessing the database at the same time.

If you see errors related to database consistency, go to the SMC and execute the Synchronize database schema option, then restart the server.

    For more information, see Synchronizing database schema.

Using SilverMonitor   Top of page

SilverMonitor is a background process running on the server that monitors the server status and attempts to restart the server if it terminates abnormally. By default, this process is activated when the server is started. SilverMonitor starts with default parameters, which you can modify. You can also run the server without SilverMonitor.

There are two ways that you can modify the parameters:

Order of precedence

The order of precedence is as follows:

Summary of parameters

The following is a summary of SilverMonitor parameters.

Start up option

Registry option (NT)

Description

Default

/X

Command in the registry to start SilverMonitor.

-retry number

/C_number

Number of restart tries. The default is 3.

-minspan number

/M_minutes

Minute span for restart tries. The default is 10.

not applicable

/D

Debug information about the SilverMonitor process.

-nomonitor

n/a

Run the server without SilverMonitor.

To modify SilverMonitor parameters in the NT Registry:

  1. From the Start menu choose Run.

  2. Type regedit to invoke the Registry Editor.

    The following screen appears.

  3. Navigate the tree as follows: HKEY_LOCAL_MACHINE > SOFTWARE > SilverStream Software Inc > SilverStream > version number.

  4. Double-click the SilverMonitor process.

  5. When the dialog appears type one or more of the options described above. Separate each option with a space. The following shows the option for starting SilverMonitor.

  6. Click OK.

What happens

SilverMonitor writes to the NT EventLog when it restarts the server. It also writes to a SilverMonitor.log file in the directory where it is run (usually SilverStream\bin). This log file gets an entry every time the monitor starts.

When you restart the SilverMonitor the log file is emptied and restarted.

Using the SilverMasterInit program   Top of page

SilverStream relies on the SilverMaster database for overall system management. SilverMasterInit is a command-line program that performs several types of processes on the SilverMaster database. It can:

    See Command-line options next for a complete list of SilverMasterInit processes.

This section contains the following information:

Command-line options   Top of page

The following table describes how and when to run each of the SilverMasterInit command-line options. To see a list of options, type the following at the command prompt:

  SilverStream\bin\SilverMasterInit -?  

You need to specify Full mode or Refresh mode for all SilverMasterInit options except those noted in the following table. The syntax examples also show which options require you to enter the database user account name and password on the command line.

Specify parameter(s) as SilverMasterInit startup options on the command line.

SilverMasterInit startup option

Description

Use

-?

Displays usage for SilverMasterInit

Use to check option usage.

+cp:a path

Appends specified path to the class path.

This option makes additional Java classes available to SilverStream applications by appending the specified path to the class path.

NOTE   It is recommended that you use use the AGCLASSPATH environment variable to extend Java classes.

Example:

SilverMasterInit [-f or -r] +cp:a path -U dbusername -P dbpassword

+cp:p path

Prepends specified path to the class path.

Don't use this debugging option without first contacting technical support. Instead, use AGCLASSPATH to make additional Java classes available to SilverStream applications. For more information, see Setting the AGCLASSPATH variable.

-a

Causes the SilverStream Server to require users to authenticate themselves.

Set this parameter if you accidentally restrict read access to your SilverMaster database, which includes the login resource. This option also provides a quick way to set authentication without running the SMC. For more information, see Using server authentication to access the login resource.

You don't need to specify Refresh or Full mode when running the -a option.

Example:

SilverMasterInit -a -U dbusername -P dbpassword

-b

Displays boot environment settings.

Run to see the initial SilverMaster environment properties used by Full mode or Refresh mode.

Example:

SilverMasterInit [-f or -r] -b -U dbusername -P dbpassword

-c

Checks that BLOBs are inserted into the database correctly.

Run to verify that these objects are properly stored.

Example:

SilverMasterInit [-f or -r] -c -U dbusername -P dbpassword

-D database

Deletes all Ag tables from the specified SilverMaster database.

Deletes all existing SilverStream tables (including users, groups, and licensing data) from the specified SilverMaster database. Use to remove a SilverStream database from the server.

Unlike Full mode, this option deletes SilverStream data but does not replace it with initial properties.

Example:

SilverMasterInit -U dbusername -P dbpassword -D Agdb

-e error log file

Writes errors to the specified file, which is created as necessary.

If no errors are found, a log file is not created.

If you don't specify a path, the error log file is stored in the directory from which you ran SilverMasterInit. The default file name is sminit.log.

Example:

SilverMasterInit [-f or -r]
-U
dbusername -P dbpassword -e c:\silverstream\bin\logs\sminit.log

-f

Runs in Full mode to create a new SilverMaster database.

Creates new SilverMaster system data and resources.

This option deletes existing users, groups, and licensing data.

Example:

SilverMasterInit -f -U dbusername -P dbpassword

-L jdbc log file

Writes JDBC debugging information to the specified log file.

If you do not specify a log file name, this option is ignored.

If you don't specify a path, the JDBC log file is stored in the SilverStream\bin directory.

Example:

SilverMasterInit [-f or -r] -L c:\SilverStream\logs\jdbclogfile.log

-l locksmith account

Specifies a user or group account to grant Locksmith privileges to.

Use this option if you accidentally delete all accounts that have Locksmith privileges. See Regaining access to SilverMaster for more information.

You don't need to specify Refresh or Full mode when running the -l option.

Example:

SilverMasterInit -l -U dbusername -P dbpassword

-O table space

Creates all Ag tables in the specified Oracle table space for SilverMaster.

Use this option when creating a SilverMaster database to use with Oracle. More space (than the default) must be allocated for SilverMaster table objects because of the way an Oracle database stores data.

Example:

SilverMasterInit [-f or -r] -U dbusername -P dbpassword
-O tablespacename

-P dbpassword

Specifies the database password used by SilverStream Server to access SilverMaster.

The password and associated user account is stored encrypted in the SilverStream Registry. The specified account name and password will be used at server startup to access the SilverMaster database.

An account and password are created and stored in the Registry during installation.

Example:

SilverMasterInit [-f or -r] -U dbusername -P dbpassword

-p properties file

Reads startup properties from the specified file.

Defaults to SilverStream\Resources\httpd.props.

Use to specify SilverMaster startup properties file name and location other than the default.

After you set the property file option with SilverMasterInit you need to start the SilverStream Server from the command line with the -p option to use the new property file.

Example:

SilverMasterInit [-f or -r] -p c:\SilverStream\ resources\httpd.newprops -U dbusername -P dbpassword

-r

Runs in Refresh mode to update SilverMaster resources.

This process skips some of the database installation steps used by Full mode. Use this option to refresh SilverMaster system data and resources when you don't want to delete existing users, groups, and licensing data.

Example:

SilverMasterInit -r -U dbusername -P dbpassword

-U dbusername

Specifies the database user account used by SilverStream Server to access SilverMaster.

The user account and associated password are stored encrypted in the SilverStream Registry. The specified account name and password will be used at server startup to access the SilverMaster database.

Example:

SilverMasterInit [-f or -r] -U dbusername -P dbpassword

-v

Generates verbose output as SilverMasterInit runs.

If the process fails, run this option to identify where the failure occurred.

Example:

SilverMasterInit [-f or -r] -v -U dbusername -P dbpassword

-x

Displays SilverMaster initialization properties and then exits without starting SilverMasterInit.

Run to view local server startup properties. This option does not change or refresh properties. Use this debugging option to check for misdirected initialization settings.

Example:

SilverMasterInit -x

Using SilverMasterInit to recreate or refresh SilverMaster   Top of page

The SilverMaster database, which is created during installation, can also be recreated or updated using SilverMasterInit. The SilverMaster database keeps track of all of the application databases used by the SilverStream Server and also holds the SilverStream system tables, including those containing group, user, and licensing information. There is one SilverMaster catalog for each SilverStream Server or SilverStream cluster.

    For more information about the SilverMaster database, see The SilverMaster database catalog.

If your SilverMaster database is damaged, you can run SilverMasterInit. If you cannot start the SilverStream Server, try one of the following procedures if nothing else has worked:

Refreshing the SilverMaster database with SilverMasterInit

You can run SilverMasterInit in Refresh mode to upgrade or access SilverMaster properties. The refresh process skips some of the database installation steps used by Full mode. Run SilverMasterInit in Refresh mode to refresh SilverMaster system data and resources without deleting existing users, groups, and licensing data.

NOTE   As part of the SilverStream Server installation process, SilverMasterInit upgrades resources. You typically upgrade the SilverStream Server by running the Installation program.

To run SilverMasterInit in Refresh mode:

  1. Shut down the SilverStream Server and Designer.

  2. From SilverStream\bin directory, enter

      SilverMasterInit -r options 

    The following message appears:

      Creating Resources will take a few minutes, please wait. 
  3. Restart the SilverStream Server once SilverMasterInit completes without errors.

Creating a new SilverMaster database with SilverMasterInit

SilverMasterInit can often fix problems caused by someone removing or renaming a file or table that SilverMaster relies on. If you cannot start the SilverStream Server or connect to the SilverMaster database, you may need to run SilverMasterInit.

While SilverMasterInit can reset corrupted SilverMaster properties, this program cannot repair a corrupted Registry key, configuration files, sample databases, or files associated with databases. To address these types of problems, run the Installation program.

To avoid deleting all your database tables, try running SilverMasterInit in Refresh mode (before running it in Full mode) to see if that resolves the server problem.

If you run SilverMasterInit in Full mode to regenerate new SilverMaster properties, you will have to rerun the license install, recreate any SilverStream users and groups, and manually add your SilverStream application databases. Running SilverMasterInit will not alter your application databases unless you have stored application objects in SilverMaster (this is not common practice and is not recommended).

To run SilverMasterInit in Full mode:

  1. Shut down the SilverStream Server and Designer.

  2. From SilverStream\bin directory, enter

      SilverMasterInit -f options 

    The following message appears:

      Creating Resources will take a few minutes, please wait. 
  3. Record any errors from this command.

  4. Once SilverMasterInit completes without errors, rerun your license install using the Installation program.

    NOTE   You must re-license the server because running SilverMasterInit in Full mode deletes the table data that stores license information.

        For information on adding licenses, see Managing licenses.

  5. Start the SilverStream Server.

  6. Start the Designer and re-add your application databases.

  7. Recreate any users and groups.

Regaining access to SilverMaster   Top of page

You can use SilverMasterInit to regain access to locked resources. The SilverMaster database is where SilverStream stores all system resources and links to other databases. By default, any user with the SilverStream Locksmith privilege has "read" access permission to the SilverMaster. If all users are accidently denied access to the SilverMaster database, no one will be able to access the SilverStream Server, either through the Designer or through the SMC.

See the following sections if you suspect that read access to SilverMaster has been restricted:

Using the Locksmith option to access locked resources

By default, the administrator and any other user with Locksmith privileges can get and set data access permissions for any resource in any database, read all SilverMaster resources, and grant Locksmith privileges to users and groups. The only user that can grant the Locksmith privilege is someone who is already a locksmith. If all accounts with the Locksmith privilege get deleted, use the SilverMasterInit locksmith option to grant this privilege to a user to regain access to resources.

NOTE   By default, after a new installation or after you run SilverMasterInit in Full mode, an administrator account is automatically created that has Locksmith privileges.

Once a user with the Locksmith privilege can access SilverMaster, that person can unlock resources and reset access privileges.

    For more information, see Using the Locksmith privilege.

To reset locksmith privileges:

  1. Shut down the SilverStream Server and Designer.

  2. From SilverStream\bin directory, enter

      SilverMasterInit -l -U dbusername -P dbpassword 

    The locksmith can now use the SMC to unlock resources.

Using server authentication to access the login resource

You can set server authentication from the SMC or the SilverMasterInit command line. Set server authentication if you accidently restrict read access to your SilverMaster database. If users cannot access SilverMaster, run the SilverMasterInit server authentication option to allow users to authenticate themselves when they initially connect to the server. When a user logs into the SilverStream Server from the Designer or SMC, a request for the login resource is issued. Users cannot access the login dialog box if their access to SilverMaster is restricted because they have no read access to the database. This is because the SilverMaster has the login resource.

You do not need to specify Full or Refresh mode when you run the server authentication option. When you restart the server after setting server authentication, your first attempt to access the server will bring up the credentials dialog and you can log in.

To set server authentication:

  1. Shut down the SilverStream Server and Designer.

  2. From SilverStream\bin directory, enter

      SilverMasterInit -a -U dbusername -P dbpassword 
  3. Restart the SilverStream Server

    Users will now be prompted to log in.

Handling a stack overflow   Top of page

In some obscure situations it is possible to exceed the limits of the stack, in which case the Java Virtual Machine (JVM) throws a java.lang.StackOverflowError.

About stacks

On a Windows system in the Java environment there are at least two program stacks (possibly more, depending on the JVM implementation), any one of which can overflow and cause a StackOverflowError to be thrown:

Each thread created in the JVM has its own hardware and Java stacks.

What to do if you get a stack overflow

It is possible to alter the size of each of the stacks if it is determined that the default stack size is too small. However, the most common cause of stack overflow errors is a programming error where a method is called recursively a number of times. If this is the case, increasing the size of the stack will not fix the stack overflow problem. Before attempting to increase the stack size, verify that the code does not contain any errors of this nature. Assuming the stack overflow is not caused by an infinite recursion error it should be possible to fix the stack overflow by increasing the stack size. To determine which stack overflowed is largely a matter of trial and error.

The size of the hardware stack is determined by the operating system using a value stored in the header of the executable. The SilverStream executables (SilverServer.exe, SilverDesigner.exe, and SilverJRunner.exe) all specify a default stack size of 256K.

Changing the stack size

In order to change the stack size you must modify the executable header using Microsoft's EDITBIN utility. For example, to change the default stack size for SilverServer.exe to 512K, use the following command line:

  EDITBIN /STACK:0x80000 SilverServer.exe 

Of course, you should make a backup before modifying any executable.

If increasing the size of the hardware stack doesn't work, it is possible that the Java stack is the problem. In the JDK 1.1. documentation, there were two command-line options affecting the stack size:

The defaults were 128K and 400K respectively. Although these options are no longer documented in JDK 1.2 (Java 2), they appear to have been carried forward as non-standard (-X) switches. To set these options for a SilverStream executable use +X instead of -X (the SilverStream executables interpret + options as options to be passed to the JVM).

    For more information about SilverStream startup options, see Using startup options.

For example, to set both the native and Java stacks for the SilverStream Server to a maximum of 512K, use the following command line:

  SilverServer +Xss512k +Xoss512k 

Note that increasing any of the default stack size values will increase the amount of virtual memory allocated per thread. Virtual memory is a finite resource, albeit a large one (in a 32-bit operating system such as Windows NT, processes can address up to 2G of virtual memory). Increasing the per-thread virtual memory requirement will reduce the number of threads that can be created. It is important to realize that this could reduce the number of simultaneously connected users that the server is able to support (since the server uses one thread per connected client).

Miscellaneous issues   Top of page

This section describes some issues that you might need to address.

Browser issues   Top of page

This section contains browser issues that you might encounter.

Form on a page only works once

There is a bug in Internet Explorer Version 3.0x that may cause a form on a particular HTML page to work only once per session. When you visit the page again, the form will not appear correctly.

To work around this bug:

  1. Select View>Options from the menu.

  2. Select the Advanced tab.

  3. Select the Settings button and make sure that Check for newer versions of stored pages is set to Every visit to the page.

Internet Explorer 5 error reporting

By default, Internet Explorer 5 returns its own HTML error page for common HTTP error messages. You need to turn off this processing to get the SilverStream error page.

To turn off Internet Explorer 5's default error reporting:

  1. Launch Internet Explorer 5.

  2. Select Tools>Internet Options.

  3. Select the Advanced tab.

  4. Deselect Show friendly http error messages.

  5. Click OK.

Server appears to be hung   Top of page

If the SilverStream Server seems to be hung or in a loop, you can generate a listing of each thread with a stack trace. The procedure does not stop the server.

In Windows NT

In the window where you started the server, press Ctrl+Break. SilverStream lists each thread with a stack trace.

In Solaris

Determine the process that SilverStream is running under:

  ps -all | grep Silver 

Issue the following command:

  kill -3 SilverServer_process_ID 

SilverStream lists each thread with a stack trace in the window where the server was started from.

Socket exceptions   Top of page

You might receive a Socket Exception message in your NT application log. Typically, this is not a problem: It usually indicates that a client has unilaterally closed a socket. Browsers such as Internet Explorer frequently do this when the connection has been idle for a while, and it will show up as a Socket Exception in the server's console when running with debugging.

Typically you can ignore such warnings; they simply reflect a normal situation.

Calling Technical Support   Top of page

If you call SilverStream Technical Support for assistance, you should have certain information ready.

    For more information, see the section on contacting Technical Support in the first chapter of the Installation Guide.






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