Reference | Help | Introduction | Slide Show | Class Hierarchy | InterClient
PREV | NEXT | FRAMES | NO FRAMES |  |

### Troubleshooting Common Problems

1. Testing your Local Installation
2. Testing an Applet Configuration
3. Troubleshooting the "No suitable driver" error
4. Troubleshooting "Access is denied" starting InterServer
5. Deciphering messages logged to the interserver.log file
6. The Communication Diagnostics icon in the Windows InterClient Program Group does not work
7. Getting Connection Refused on high-throughput servers
8. InstallShield crashes - Access violation in _INS0432._MP

#### Testing your Local Installation

First, verify that the installation has appended your CLASSPATH with the interclient.jar file.

Second, on Windows NT/95, select the InterServer Configuration Utility icon in the InterClient program group and start the InterServer service or application (usually, but not necessarily, on your InterBase server). On Unix the interserver service is started automatically by inetd if your `/etc/services` and `/etc/inetd.conf` are configured properly.

Finally, on Windows NT/95, select the Communication Diagnostics icon from the InterClient program group. If Java is installed on your local machine and interclient.jar is in your CLASSPATH, then a GUI will appear for making a test connection using the locally installed driver. Alternatively, and on Unix, you may invoke the Communication Diagnostics Utility from the command line using

        java interbase.interclient.utils.CommDiag

#### Testing an Applet Configuration

CommDiag may also be run as an applet on clients in which neither the JDK nor InterClient is installed. Using a Java enabled browser, browse CommDiag.html off a web server which has InterClient deployed. If you run InterClient applets such as CommDiag through a browser, then you may need to remove the interclient.jar from your local CLASSPATH to avoid a security exception. A browser's default security policy may only allow socket connections to the host which is the source of the class file which is attempting the connection. So the security manager needs to be sure that the source host of the downloaded InterClient class files is the same as the database server host. If the interclient.jar is being picked up from your local disk, rather than being downloaded along with an applet such as CommDiag, then this may be difficult for the security manager to determine.

You may also run CommDiag through the appletviewer.

On Unix:

        unset CLASSPATH
        appletviewer CommDiag.html

On Windows 95/NT:

        set CLASSPATH=
        appletviewer CommDiag.html

You may need to unset your CLASSPATH temporarily in your command session when viewing a local applet; otherwise you could receive a java.lang.IllegalAccessError. CommDiag.html contains an applet tag which references the interclient.jar archive.

Depending on your browser's security policy, untrusted applets may not be allowed to open network connections to arbitrary hosts, except for the host that provided the .class files. This is either the host where the html page came from, or the host specified in the codebase parameter in the applet tag, with codebase taking precendence. Under this security policy, untrusted applets will only operate if InterServer is installed on the same web server host that serves the interclient.jar file. If you choose to deploy InterServer on another host then you may need to digitally sign your applet together with the interclient.jar file so that the entire applet is trusted. InterServer is *not* involved in the certification process, its an issue between the browser and the downloaded jar. Browsers are all configured differently, so see the vendor-specific documentation for your browser. Some browsers (e.g. HotJava) can be configured to allow arbitrary socket connections even for untrusted applets, others (e.g. Netscape) have their own proprietary security api to allow an untrusted applet to request privileges from the browser.

Be sure to name the originating host exactly as it was specified when the applet was loaded into the browser. That is, if you load an HTML page using the URL

        http://foo.state.edu/~me/CommDiag.html

then your applet will be able to connect to its host only by using the name foo.state.edu in the jdbc URL

        jdbc:interbase://foo.state.edu//databases/employee.gdb

Using the IP address for foo.state.edu won't work, and using a "shorthand" form of the host name, like foo.state instead of foo.state.edu, won't work.

#### Troubleshooting the "No suitable driver" exception

This exception is issued by the JDBC Driver Manager and usually occurs during a call to DriverManager.getConnection(). The cause can be failing to load the appropriate JDBC driver before calling getConnection(), or specifying an invalid JDBC URL - one that isn't recognized by any loaded JDBC driver.

This error can also occur due to a bug in the JDK 1.1.x with Class.forName(). Because of a race condition in the class loader, it is sometimes possible that the class loader is prevented from executing the static section of code in the driver class. This would prevent the loaded driver class from registering itself with the driver manager. So Class.forName () may appear to succeed with no exception thrown, but the driver may not be registered with the driver manager. A work around is to obtain a connection from an explicitly constructed driver instance as follows:

    java.sql.Driver d = new interbase.interclient.Driver ();
    java.sql.Connection c = d.connect ("jdbc:interbase://server/c:/databases/atlas.gdb",
                                       "sysdba", "masterkey");

Here are some typical reasons for getting the no suitable driver error:

- The InterClient driver is not in your CLASSPATH.
  - If you're working with Sun's JDK, then make sure the correct file specifiation for interclient.jar is in your system's CLASSPATH environment variable.
  - If you're working with JBuilder, then make sure that your project property setting for Class Path has the correct file specification for interclient.jar. Choose File | Project Properties to view these properties. Also check your JBuilder.INI file and see the JBuilder Integration Notes that come with InterClient.
- The InterClient driver has not been loaded.
  - Check your spelling and capitalization of the InterClient driver name.
    Make sure you specify interbase.interclient.Driver with the capital D.
    For example,

               Class.forName ("interbase.interclient.Driver");

- The InterClient driver does not recognize the database URL syntax.
  - Check the subprotocol in the URL.
    URLs for InterClient must start with jdbc:interbase:
    For example,

             DriverManager.getConnection ("jdbc:interbase://server/c:/databases/atlas.gdb", ...);

- The InterClient driver has not been registered.
  - The class loader bug in JDK 1.1.x was encountered. See notes above.

Finally, try using the Communication Diagnostics program that comes with InterClient and see if you can connect that way.

#### Troubleshooting "Access is denied" when trying to start the InterServer service

Only one customer has reported this problem, and its cause is currently unknown. If you encounter this problem, please send email to interclient@interbase.com.

#### Deciphering messages logged to the interserver.log file

In general, interserver errors are relayed back to InterClient and surfaced via an SQLException. However, if the socket is unexpectedly disconnected, or some other error occurs on the socket, then relay of the error message back to the client over the same socket may be impossible. So the purpose of the interserver.log file is for the logging of messages that cannot be relayed back to InterClient.

Messages logged to the interserver.log file are usually innocuous and caused by client application neglect to close the socket gracefully using the Connection.close() or ServerManager.close() methods. InterServer spends its idle time waiting for requests from InterClient. If InterClient terminates abruptly without using Connection.close() then InterServer will detect an error on the socket, and log a message to the interserver.log file. This is of no real concern to the user, as the connection is closed, just not in a graceful manner.

However, socket failures could be caused for more insidious reasons, such as someone cutting the network wire with a pair of scissors. In such case, a message to interserver.log is logged since there is no way to relay an exception back to InterClient.

Here are the message codes which may be logged to the interserver.log file. The integer code simply indicates the exact location in the InterServer source where the message originated.

JDBC/Net [100-199] | Unable to read bytes from socket
JDBC/Net [200-299] | Unable to write bytes to socket

#### The Communication Diagnostics icon in the Windows InterClient Program Group does not work

If a version of the JDK 1.1 was not in your system PATH when InterClient was installed, the CommDiag program group icon will not have the correct properties. On NT, use the Control Panel to edit the user Environment variable PATH to include the JDK 1.1 bin directory on your system. Also, edit the ClassPath Environment variable and include interclient.jar if it is not already present in the path. Next, right click on the InterClient program group in the Windows start menu and select "open". This will bring up the InterClient program group icons in a separate window. Select the Communications Diagnostics icon, right click, and select "properties". Now insert "java " in front of the class name "interbase.interclient.utils.CommDiag" in the target location field property.

Alternatively, the Communications Diagnostics utility may also be run from the command-line using

    java interbase.interclient.utils.CommDiag

#### Getting Connection Refused on high-throughput servers

If you send many connection requests to InterServer within a certain timeframe, you may experience hanging processes or "Connection refused" error messages. This happens because the number of requests per minutes exceeds the maximum defined by inetd, thereby causing inetd to mistakenly tag interserver as a broken service. Broken services are kept out of operation for usually ten minutes before they are allowed to receive new connections.

The inetd super-daemon has a default maximum of 40 invocations per minute on many operating systems, including Solaris and Linux. These values usually can be adjusted by the system administrator.

For Solaris, modify the startup scripts that launch inetd so that inetd uses the -r parameter. Refer to the Solaris documentation for details.

For Linux, modify the interserver entry in /etc/inetd.conf, changing 'nowait' to 'nowait.100' or higher. After the changes are made, send a hangup signal, SIGHUP, to the inetd process so that it rereads the inetd.conf file.

#### InstallShield crashes - Access violation in _INS0432._MP

If you have JBuilder installed and an access violation occurs at the end of the installation for InterClient, this may be because the IDEClassPath setting within the JBuilder.INI file exceeds 1024 bytes. The workaround to this problem is to edit the JBuilder.INI file manually by following these steps:

1. Run regedit.exe and delete the following key:

       HKEY_LOCAL_MACHINE\SOFTWARE\InterBase Corp\InterClient

2. Shut down JBuilder if it is running. Open the JBuilder.ini file with a text editor. You can find this file in the JBuilder bin directory. Make a backup copy of this file. Search for a line that begins with 'IDEClassPath' and change this word to 'OLDIDEClassPath'. Insert a line above this one that reads 'IDEClassPath=x'. Save the file.
3. Rerun the InterClient installation program. There should be no error this time.
4. After the installation is complete. Re-open the JBuilder.ini file with a text editor. You may notice that the IDEClassPath value has a reference to the InterClient jar file. It may look like this:

       IDEClassPath=c:\Program Files\InterBase Corp\InterClient\interclient.jar;x

   The actual path depends on where you installed InterClient. Delete the trailing `x` in the IDEClassPath and merge this value with the OLDIDEClassPath. The final outcome is the original IDEClassPath setting with the InterClient jar file and an semi-colon added to it. Save the JBuilder.INI file.

Reference | Help | Introduction | Slide Show | Class Hierarchy | InterClient
PREV | NEXT | FRAMES | NO FRAMES |  |

Send comments or suggestions to interclient@interbase.com