jConnect for JDBC Programmer's Reference

Chapter 3 Troubleshooting

Chapter 3

Troubleshooting

This chapter describes solutions and workarounds for problems you might encounter when using jConnect.

Debugging with jConnect

jConnect includes a Debug class that contains a set of debugging functions. The Debug methods include a variety of assert, trace, and timer functions that let you define the scope of the debugging process and the output destination for the debugging results.

The jConnect installation also includes a complete set of debug-enabled classes. These classes are located in the devclasses subdirectory under your jConnect installation directory. For debugging purposes, you must redirect your CLASSPATH environment variable to reference the debug mode runtime classes (devclasses/jconn2d.jar), rather than the standard jConnect classes directory. You can also do this by explicitly providing a -classpath argument to the java command when you run a Java program.

Obtaining an instance of the Debug class

To use the jConnect debugging feature, your application must import the Debug interface and obtain an instance of the Debug class by calling the getDebug( ) method on the SybDriver class.

import com.sybase.jdbcx.Debug 
 import.com.sybase.jdbcx.SybDebug 
 //
 ... 
 SybDriver sybDriver = (SybDriver)
 Class.forName("com.sybase.jdbc2.jdbc.SybDriver").newInstance();

Debug sybdebug = sybDriver.getDebug();
 ...

Turning on debugging in your application

To use the debug( ) method on the Debug object to turn on debugging within your application, add this call:

sybdebug.debug(true, [classes], [printstream]);

The classes parameter is a string that lists the specific classes you want to debug, separated by colons. For example:

sybdebug.debug(true,"MyClass")

and

sybdebug.debug(true,"MyClass:YourClass")

"STATIC" in the class string turns on debugging for all static methods in jConnect in addition to the designated classes. For example:

sybdebug.debug(true,"STATIC:MyClass")

You can specify "ALL" to turn on debugging for all classes. For example:

sybdebug.debug(true,"ALL");

The printstream parameter is optional. If you do not specify a printstream, the debug output goes to the output file you specified with DriverManager.setLogStream( ).

Turning off debugging in your application

To turn off debugging, add this call:

sybdebug.debug(false);

Setting the CLASSPATH for debugging

Before you run your debug-enabled application, redefine the CLASSPATH environment variable to reference the /devclasses subdirectory under your jConnect installation directory.

For UNIX, replace $JDBC_HOME/classes/jconn2.jar with $JDBC_HOME/devclasses/jconn2d.jar.
For Windows, replace %JDBC_HOME%\classes\jconn2.jar with %JDBC_HOME%\devclasses\jconn2d.jar.

Using the Debug methods

To customize the debugging process, you can add calls to other Debug methods.

In these methods, the first (object) parameter is usually this to specify the calling object. If any of these methods are static, use null for the object parameter.

println( )
Use this method to define the message to print in the output log if debugging is enabled and the object is included in the list of classes to debug. The debug output goes to the file you specified with sybdebug.debug( ).
The syntax is:
```
sybdebug.println(object,message string);
```
For example:
```
sybdebug.println(this,"Query: "+ query);
```
produces a message similar to this in the output log:
```
myApp(thread[x,y,z]): Query: select * from authors
```
assert( )
Use this method to assert a condition and throw a runtime exception when the condition is not met. You can also define the message to print in the output log if the condition is not met. The syntax is:
```
sybdebug.assert(object,boolean condition,message
   string);
```
For example:
```
sybdebug.assert(this,amount<=buf.length,amount+"
   too big!");
```
produces a message similar to this in the output log if "amount" exceeds the value of buf.length:
```
java.lang.RuntimeException:myApp(thread[x,y,z]):
Assertion failed: 513 too big!
at jdbc.sybase.utils.sybdebug.assert(
sybdebug.java:338)
at myApp.myCall(myApp.java:xxx)
at .... more stack: 
```
startTimer( ) stopTimer( )
Use these methods to start and stop a timer that measures the milliseconds that elapse during an event. The method keeps one timer per object, and one for all static methods. The syntax to start the timer is:
```
sybdebug.startTimer(object);
```
The syntax to stop the timer is:
```
sybdebug.stopTimer(object,message string);
```
For example:
```
sybdebug.startTimer(this);
stmt.executeQuery(query);
sybdebug.stopTimer(this,"executeQuery");
```
produces a message similar to this in the output log:
```
myApp(thread[x,y,z]):executeQuery elapsed time =
  25ms
```

Capturing TDS communication

Tabular Data Stream (TDS) is Sybase's proprietary protocol for handling communication between a client application and Adaptive Server. jConnect includes a PROTOCOL_CAPTURE connection property that allows you to capture raw TDS packets to a file.

If you are having problems with an application that you cannot resolve within either the application or the server, you can use PROTOCOL_CAPTURE to capture the communication between the client and the server in a file. You can then send the file, which contains binary data and is not directly interpretable, to Sybase Technical Support for analysis.

You can also use the Ribo utility to capture, translate, and display the protocol stream flowing between the client and the server. For details on how to obtain and use Ribo, visit the jConnect utilities Web page at .

PROTOCOL_CAPTURE connection property

Use the PROTOCOL_CAPTURE connection property to specify a file for receiving the TDS packets exchanged between an application and an Adaptive Server. PROTOCOL_CAPTURE takes effect immediately so that TDS packets exchanged during connection establishment are written to the specified file. All packets continue to be written to the file until Capture.pause( ) is executed or the session is closed.

The following example shows the use of PROTOCOL_CAPTURE to send TDS data to the file tds_data:

...
 props.put("PROTOCOL_CAPTURE", "tds_data")Connection conn = DriverManager.getConnection(url, props);

where url is the connection URL and props is a Properties object for specifying connection properties.

pause( ) and resume( ) methods in the Capture class

The Capture class is contained in the com.sybase.jdbcx package. It contains two public methods:

public void pause( )
public void resume( )

Capture.pause( ) stops the capture of raw TDS packets into a file; Capture.resume( ) restarts the capture.

The TDS capture file for an entire session can become very large. If you want to limit the size of the capture file, and you know where in an application you want to capture TDS data, you can do the following:

Immediately after you have established a connection, get the Capture object for the connection and use the pause( ) method to stop capturing TDS data:
```
Capture cap = ((SybConnection)conn).getCapture();
 cap.pause();
```
Place cap.resume( ) just before the point where you want to start capturing TDS data.
Place cap.pause( ) just after the point where you want to stop capturing data.

Unsuccessful connection errors

This section addresses problems that may arise when you are trying to establish a connection or start a gateway.

Gateway connection refused

Gateway connection refused:

HTTP/1.0 502 Bad Gateway|Restart Connection

This error message indicates that something is wrong with the hostname or port# used to connect to your Adaptive Server. Check the [query] entry in $SYBASE/interfaces (UNIX) or in %SYBASE%\ini\sql.ini (Windows).

If the problem persists after you have verified the hostname and port#, you can learn more by starting the HTTP server using the "verbose" system property.

For Windows, go to a DOS prompt and enter:

httpd -Dverbose=1 > filename

For UNIX, enter:

sh httpd.sh -Dverbose=1 > filename &

where filename is the debug messages output file.

Your Web server probably does not support the connect method. Applets can connect only to the host from which they were downloaded.

The HTTP gateway and your Web server must run on the same host. In this scenario, your applet can connect to the same machine/host through the port controlled by the HTTP gateway, which routes the request to the appropriate database.

To see how this is accomplished, review the source of Isql.java and gateway.html in the sample2 subdirectory under the jConnect installation directory. Search for "proxy."

Unable to connect to a 4.9.2 SQL Server

jConnect uses TDS 5.0 (Sybase transfer protocol). SQL Server 4.9.x uses TDS 4.6, which is not compatible with TDS 5.0.

SQL Server 10.0.2 or later is required for use with jConnect.

Memory usage in jConnect applications

The following situations and their solutions may be helpful if you notice increased memory use in jConnect applications.

In jConnect applications, you should explicitly close all Statement objects and subclasses (for example, PreparedStatement, CallableStatement) after their last use to prevent statements from accumulating in memory. Closing the ResultSet is not sufficient.
For example:
```
ResultSet rs = _conn.prepareCall(_query).execute();
```
```
...
rs.close();
```
will cause problems. Instead use:
```
PreparedStatement ps = _conn.prepareCall(_query);
ResultSet rs = ps.execute();
```
```
...
ps.close();
rs.close();
```
jConnect uses the Tabular Data Stream (TDS)--Sybase's proprietary protocol--to communicate with Sybase database servers. As of jConnect 5.5, TDS does not support scrollable cursors. To support scrollable cursors, jConnect caches the row data on demand, on the client, on each call to ResultSet.next( ). However, when the end of the result set is reached, the entire result set is stored in the client's memory. Because this may cause a performance strain, Sybase recommends that you use TYPE_SCROLL_INSENSITIVE result sets only when the result set is reasonably small.

Stored procedure errors

This section addresses problems that may arise when you are trying to use jConnect and stored procedures.

RPC returns fewer output parameters than registered

SQLState: JZ0SG - An RPC did not return as many output parameters as the application had registered for it.

This error occurs if you call CallableStatement.registerOutParam( ) for more parameters than you have declared as "OUTPUT" parameters in the stored procedure. Make sure that you have declared all of the appropriate parameters as "OUTPUT." Look at the line of code that reads:

 create procedure yourproc (@p1 int OUTPUT, ...

If you receive this error while using Adaptive Server Anywhere (previously known as SQL Anywhere), upgrade to Adaptive Server Anywhere version 5.5.04 or later.

Fetch/state errors when output params returned

If a query does not return row data, then it should use the CallableStatement.executeUpdate( ) or execute( ) methods rather than the executeQuery( ) method.

As required by the JDBC standards, jConnect throws a SQL exception if an executeQuery( ) has no result sets.

Stored procedure executed in unchained transaction mode

Sybase Error 7713 - Stored Procedure can only be executed in unchained transaction mode.

JDBC attempts to put the connection in autocommit(true) mode. The application can change the connection to chained mode using Connection.setAutoCommit(false) or by using a "set chained on" language command. This error occurs if the stored procedure was not created in a compatible mode.

To fix the problem, use:

sp_procxmode procedure_name,"anymode"

Custom socket implementation error

You may receive an exception similar to the following while trying to set up an SSL socket when calling sun.security.ssl.SSLSocketImpl.setEnabledCipherSuites:

java.lang.IllegalArgumentException:
 SSL_SH_anon_EXPORT_WITH_RC4_40_MDS

Verify that the SSL libraries are in the system library path.

Restrictions on and interpretations of JDBC standards


	Expand Search