User's Guide
   PART 3. Java in the Database
     CHAPTER 19. Debugging Java in the Database       

Using the debugger

This section describes how to accomplish tasks using the Java debugger.

  Starting the debugger

The debugger is the Jar file Debug.jar, installed into your Adaptive Server Anywhere installation directory. This jar file contains many classes. To start the debugger you invoke the sybase.vm.Debug class, which has a main method.

  To start the debugger:

1. Ensure that Debug.jar and jdbcdrv.zip are in your CLASSPATH environment variable.

2. Enter the following command at the command line:

   java sybase.vm.Debug

Connecting to a database on startup 

When you start the debugger in the simple manner described above, you need to provide entries into the text boxes in order to connect to a database. You can also supply additional command-line arguments to the debugger to connect on startup.

You can specify these connection parameters in the following ways:

• Connection string format     You can provide a -c command-line switch followed by a connection string consisting of the parameters URL, UID and PWD:

  java sybase.vm.Debug -c "uid=dba;pwd=sql"

  The UID and PWD connection parameters represent the user ID and password, respectively. The URL in this connection string may make use of the following default behavior:

  • Full URL     You can provide a full URL of the form jdbc:sybase:Tds:machine-name:port.

  • machine-name:port     You can omit the jdbc:sybase:Tds portion of the URL.

  • Default port     If you do not specify a port number, 2638 is used as the default.

  • Default machine name     If you do not specify a machine name, localhost is used as the default.

  • Default URL     You can omit the URL entirely, and the above defaults are used to construct a default URL.

• Individual parameters     You can provide the following parameters, in order:

  • url

  • user ID

  • password

  For example, the following command (entered all on one line) connects to a server on the current machine, using user ID DBA and password SQL:

  java sybase.vm.Debug jdbc:sybase:Tds:localhost:2638 DBA SQL

  Compiling classes for debugging

Java compilers such as the Sun Microsystems javac compiler can compile Java classes at different levels of optimization. You can opt to compile Java code so that information used by debuggers is retained in the compiled class files.

If you compile your source code without using switches for debugging, you can still step through code and use breakpoints. However, you cannot inspect the values of local variables.

To compile classes for debugging using the javac compiler, use the -g command-line option:

javac -g ClassName.java

  Attaching to a VM

When you connect to a database from the debugger, the Connection window shows all currently active VMs under the user ID. If there are none, the debugger goes into wait mode. Wait mode works like this:

• Each time a new VM is started, it shows up in the list.

• You may either choose to debug a VM, or wait for another one to appear.

• Once you have passed on a VM, you lose your chance to debug that VM. If you then decide to attach to the VM, you must disconnect from the database and reconnect. At this time, the VM appears as a currently active VM and you can attach.

  The Source window

The Source window serves the following purposes:

• It displays Java source code, with line numbers and breakpoint indicators (an asterisk in the left column).

• It displays execution status in the status box at the bottom of the window.

• It provides access to other debugger windows from the menu.

  The debugger windows

The debugger has the following windows:

• Breakpoints window     Displays the list of current breakpoints.

• Calls window     Displays the current call stack.

• Classes window     Displays a list of classes currently loaded in the VM. In addition, this window displays a list of methods for the currently selected class and a list of static variables for the currently selected class. In this window you can set breakpoints on entry to a method or when a static variable is written.

• Connection window     The Connection window is shown when the debugger is started. You can display it again if you wish to disconnect from the database.

• Exceptions window     You can set a particular exception on which to break, or choose to break on all exceptions.

• Inspection window     Displays current static variables, and allows you to modify them. You can also inspect the value of a Java expression, such as the following:

  • Local variables

  • Static variables

  • Expressions using the dot operator

  • Expressions using subscripts []

  • Expressions using parentheses, arithmetic, or logical operators.

  For example, the following expressions could be used:

  x[i].field
  q + 1
  i == 7
  (i + 1)*3

• Locals window     Displays current local variables, and allows you to modify them.

• Status window     Displays messages describing the execution state of the VM.

  Setting breakpoints

When you set a breakpoint in the debugger, the VM stops execution at that breakpoint. Once execution is stopped, you can inspect and modify the values of variables and other expressions in order to better understand the state of the program. You can then trace through execution step by step to identify problems.

Setting breakpoints in the proper places is a key to efficiently pinpointing the problem execution steps.

The Java debugger allows you to set breakpoints not only on a line of code, but on many other conditions. This section describes how to set breakpoints using different conditions.

  Breaking on a line number

When you break on a particular line of code, execution stops whenever that line of code is executed.

  To set a breakpoint on a particular line:

1. In the Source window, select the line and press F9.

   Alternatively, you can double-click a line.

When a breakpoint is set on a line number, the breakpoint is shown in the Source window by an asterisk in the left hand column. If the Breakpoints window is open, the method and line number is displayed in the list of breakpoints.

You can toggle the breakpoint on and off by repeatedly double-clicking or pressing F9.

  Breaking on a class method

When you break on a method, the break point is set on the first line of code in the method that contains an executable statement.

  To set a breakpoint on a class method:

1. From the Source window, choose Break-> New. The Break At window is displayed.

2. Enter the name of a method in which you wish execution to stop. For example

   JDBCExamples.Query

   stops execution whenever the JDBCExamples.Query method is entered.

When a breakpoint is set on a method, the breakpoint is shown in the Source window by an asterisk in the left hand column of the line where the breakpoint actually occurs. If the Breakpoints window is open, the method is displayed in the list of breakpoints.

  Using counts with breakpoints

If you set a breakpoint on a line that is in a loop, or in a method that is frequently invoked, you may find that the line is executed many times before the condition you are really interested in takes place. The debugger allows you to associate a count with a breakpoint, so that execution stops only when the line is executed a set number of times.

  To associate a count with a breakpoint:

1. From the Source window, select Break->Display. The Breakpoints window is displayed.

2. In the Breakpoints window, click a breakpoint to select it.

3. Select Break->Count. A window is displayed with a field for entering a number of iterations. Enter an integer value. The execution will stop when the line has been executed the specified number of times.

Example 

This example assumes you have run the tutorial described in A debugging tutorial.

The JDBCExamples.Query method used in the tutorial has a loop in it:

while( result.next() ) {
   int price = result.getInt(2);
   if( price > max_price ) {
     max_price = price ;
   }

The lines inside this loop are executed ten times. You can set a breakpoint on the if statement and associate a count of two with it. Then execute the query to stop at the breakpoint.

Count is decremented 

The count is decremented each time the line of code is executed. A side effect of this is that once the breakpoint is reached, the count is set to zero.

  Using conditions with breakpoints

The debugger allows you to associate a condition with a breakpoint, so that execution stops only when the line is executed and the condition is met.

  To associate a condition with a breakpoint:

1. From the Source window, select Break->Display. The Breakpoints window is displayed.

2. In the Breakpoints window, click a breakpoint to select it.

3. Select Break->Condition. A window is displayed with a field for entering an expression. The execution will stop when the condition is true.

   The expressions used here are the same as those that can be used in the Inspection window, and include the following:

   • Local variables

   • Static variables

   • Expressions using the dot operator

   • Expressions using subscripts []

   • Expressions using parentheses, arithmetic, or logical operators.

Example 

This example assumes you have run the tutorial described in A debugging tutorial.

The JDBCExamples.Query method used in the tutorial has a loop in it:

while( result.next() ) {
   int price = result.getInt(2);
   if( price > max_price ) {
     max_price = price ;
   }

The lines inside this loop are executed ten times. You can set a breakpoint on the if statement and associate the following condition with it:

price > 10

Then execute the query to stop at the breakpoint whenever the price is greater than $10.

  Breaking when execution is not interrupted

With a single exception, breakpoints can only be set when program execution is interrupted. If you clear all breakpoints, and run the program you are debugging to completion, you can no longer set a breakpoint on a line or at the start of a method. Also, if a program is running in a loop, execution is continuing and is not interrupted.

To debug your program under either of these conditions, select Run->Stop from the Source window. This stops execution at the next line of Java code that is executed. You can then set breakpoints at other points in the code.