DataBlade Developers Kit User's Guide Debugging and Testing DataBlade Modules on UNIX

Debugging a DataBlade module is usually an iterative process, repeated many times until the code is completely debugged. The debugging process has the following general steps:

1. Build the shared object file with debugging support while logged on as user informix (if necessary).

To debug a DataBlade module, compile the shared object file with the -g compiler option so that debugging symbols are available to the debugger. See Compiling DataBlade Module Code for information about compiling with debugging support.

2. Install the DataBlade module shared object and SQL scripts in the $INFORMIXDIR/extend/project directory.

See Installing a DataBlade Module for more information.

3. Start your database server with the oninit command, while logged on as the informix user.

See the Administrator's Guide for Informix Dynamic Server 2000 for more information.

4. Register the DataBlade module, using BladeManager (if necessary).

See Registering a DataBlade Module for more information.

5. If you are replacing an existing shared object, shut down and restart the database server with the onmode -yuk and oninit commands.

See Replacing a Shared Object File for more information.

6. Load the DataBlade module by calling one of its routines.

See Loading the DataBlade Module for instructions.

7. Log on as user root in a new window to run the debugger.
8. Obtain the database server process ID for the root session.

See Identifying the Server Process for instructions.

9. Run the debugger and attach to the database server process.

See Running the Solaris Debugger for instructions.

10. Set any appropriate breakpoints.

See Setting Breakpoints for more information.

11. Issue SQL statements to call your DataBlade module routines from the informix session.

See the DB-Access User's Manual for more information.

12. Edit the source code (if necessary).
13. Repeat the procedure, as necessary.

The following sections describe some of these steps.

Before you can attach to the database server process with the debugger, load your DataBlade module shared object file into the database server address space. With the shared object file loaded, set breakpoints on the routine entry points and examine local storage provided by the routines.

To load the DataBlade module into the database server address space, execute one of its routines. One technique is to call the routine with an impossible condition, as follows:

SELECT routine_name(column_name) FROM table_name
WHERE 1=0; 

routine_name is the name of your routine, column_name is the name of a column in the table, and table_name is the name of the table. This statement loads your DataBlade module shared object file without executing the routine.

To debug a routine, you must identify the virtual processor in which that routine runs. By default, routines are assigned to the CPU virtual processor class. However, when you create a routine in BladeSmith, you can specify if it is poorly behaved and assign it to a user-defined virtual processor class.

To identify the virtual processor class assigned to a routine, look at the property page for the routine in BladeSmith. If the class field is blank, then the routine runs in the CPU VP. See C Programming Guidelines for more information on user-defined virtual processors.

Important: If you have more than one instance of a virtual processor in a CPU or user-defined virtual processor class, threads can migrate between virtual processors, making debugging difficult. To simplify debugging, configure your database server so that there is only one instance each of the CPU VP or user-defined VP used by the routines in your DataBlade module.

To find the process ID (PID) of the CPU or user-defined virtual processor that you want to debug, execute the onstat command, as follows:

onstat -g glo

The last section of the output of this onstat command is similar to the following example.

Typically, the PID circled in the sample output is the one you need. In this example, there are no user-defined virtual processor classes; all the DataBlade routines are marked as well behaved and run in the single instance of the CPU VP.

To debug your DataBlade module, use a debugger that can attach to the active database server process and access the symbol tables of dynamically loaded shared object files. On Solaris, the dbx utility meets these criteria, as does debugger.

Before beginning debugging, enter the following commands to disable signal handlers in the debugger:

ignore SIGUSR1
ignore SIGUSR2


Tip: You can put these instructions in the .dbxinit file. Then put the file in the $INFORMIXDIR/bin directory. However, then you must always start dbx from that directory.

To start dbx, enter the following command at the shell prompt:

dbx - PID

PID is the process ID of the CPU VP or user-defined VP.

This command starts dbx on the database server virtual process without starting a new instance of the virtual processor.

When the debugger starts, it lists the loaded shared object libraries. If your DataBlade module shared object file is not on the list, load it by calling one of its routines in the database server. See Loading the DataBlade Module for instructions.

You can set breakpoints, examine the stack, resume execution, or carry out any other normal dbx command. See the on-line dbx manual page for more information about available dbx commands.

You can set breakpoints in any routine with an entry point known to dbx.

Informix database server software is compiled with debugging support turned off, so local storage and line number information is not available for database server routines. However, after you compile the DataBlade module for debugging, you can see line number information and local storage for your functions.

When you enter a command in the client that calls one of your DataBlade module routines, the debugger stops in the routine. Then you can follow the steps of your routine. Because your DataBlade module is compiled with debugging support, you can view the local variables and stack for your routines.