Chapter 3 Troubleshooting

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 for jConnect 4.x and devclasses/jconn2d.jar for jConnect 5.x), 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.

For jConnect 4.x:

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

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

For jConnect 5.x:

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 jConnect 4.x:

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

For jConnect 5.x:

For UNIX, replace $JDBC_HOME/classes/jconn2.jar with $JDBC_HOME/devclasses/jconn2.jar.
For Windows, replace %JDBC_HOME%\classe\jconn2.jar with %JDBC_HOME%\devclasses\jconn2.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
```