DataBlade Developers Kit User's Guide Programming DataBlade Modules in Java

This section describes debugging and performing functional tests on DataBlade module routines written in Java.

This section contains the following subsections:

• Preparing Your Environment, next
• Debugging a DataBlade Module
• Performing Functional Tests

Before you can debug or test your DataBlade module, you must configure your Informix database server.

For information on the environment variables you must set to debug and test on UNIX, see Preparing Your Environment.

For information on the environment variables you must set to debug and test on Windows NT, see Preparing Your Environment.

In addition, you must complete the following tasks to use Java with the database server:

• Create an sbspace to hold the Java JAR files.
• Create the JVP properties file.
• Add or modify the Java configuration parameters in the ONCONFIG file.
• Install symbolic links to the Java VM libraries.

For instructions on how to complete these tasks, see Creating UDRs in Java.

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

1. Compile the JAR file (if necessary).
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 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 the Registering a DataBlade Module for more information.

5. If you are replacing an existing JAR file, shut down and restart the database server.

See Replacing a DataBlade Module JAR File for more information.

6. Execute a query that calls the method using an SQL query tool such as DB-Access or SQL Editor.

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

7. Examine the Java log file for errors.

See Logging and Error Handling for more information.

8. Edit the source code (if necessary).
9. Repeat the procedure, as necessary.

To install a DataBlade module for debugging, create a project directory and copy the necessary files to it. Create the project directory under $INFORMIXDIR/extend. The name of the project directory is what BladeManager uses as the DataBlade module name.

A good project naming strategy is to combine the project name and version numbers you entered in the New Project wizard in BladeSmith. For example, the Circle project, Version 1.0, can be in $INFORMIXDIR/extend/Circle.1.0. Informix DataBlade modules also include a string indicating the build platform and minor release: for example, 1.0.UC1.TC2, where UC1 is the first UNIX major release, and TC2 is the second Windows NT minor release.

To copy the necessary files to the project directory, use one of these methods:

• Use BladePack to create an installation directory for your DataBlade module and then copy that directory into the module subdirectory under $INFORMIXDIR/extend. For instructions, see Chapter 11, Using BladePack.
• Copy the project.jar file and the contents of the scripts directory into the project directory.

For installation tips and solutions to common problems, see the Informix Developers Network Web site at http://www.informix.com/idn.

You need to register your DataBlade module the first time you install it and subsequently if you change the definition of any of your DataBlade module objects in BladeSmith and generate new SQL files. You do not have to reregister your DataBlade module when you only replace its JAR file.

Important: You must have a default sbspace defined in your database server to hold your DataBlade module JAR files. If you do not, BladeManager does not register your Java DataBlade module.

See the DataBlade Module Installation and Registration Guide for more information on registering DataBlade modules.

When a DataBlade module is loaded onto an Informix database server, the database server stores it in the database server memory map. Therefore, if you overwrite a JAR file while it is loaded in the database server, you must stop and restart the database server to unload the old JAR file and load the new one.

Warning: If you do not stop and restart the database server after you replace a DataBlade module JAR file, the database server might fail when you call a DataBlade module routine.

To unload a module without restarting the Informix database server, you must drop all objects in the module, using the SQL DROP statement. After all objects in the module have been dropped and all instances of the methods have finished executing, the symbol references to the DataBlade module JAR file are invalidated, and a message is recorded in the log file.

After the module is unloaded, replace the JAR file and load it into the database.

When you generate functional tests, BladeSmith creates a set of files that include shell scripts and SQL scripts for testing opaque data type support routines, user-defined routines, and cast support functions.

For instructions on how to execute functional tests on UNIX, see Performing Functional Tests.

For instructions on how to execute functional tests on Windows NT, see Performing Functional Tests on DataBlade Modules.