DataBlade Developers Kit User's Guide Getting Started with DataBlade Module Development

This section suggests how to prepare for developing DataBlade modules. This overview is intended to act as a map for information resources.

To prepare for DataBlade module development, complete these general processes:

1. If necessary, familiarize yourself with Informix software and documentation (see Becoming Familiar with Informix Software and Documentation, next).
2. Design your DataBlade module (see Designing Your DataBlade Module).

After you finish your preparations, you can develop your DataBlade module and then have it certified (see Developing Your DataBlade Module).

Familiarizing yourself with Informix software and documentation is critical for first-time DataBlade developers. However, it is important for experienced DataBlade developers too because Informix software and documentation are enhanced in each release.

1. Read DataBlade Module Development Overview.

This manual briefly describes the database objects you can include in your DataBlade module and other options you have when you create a DataBlade module.

2. Join the DataBlade Partners Program, if appropriate.

See The DataBlade Partners Program for more information.

3. Install the necessary Informix software.

See Installing Informix Software for more information.

4. Learn to use Informix software: at the very least, your database server, the Setnet32 utility (client connectivity), and the DB-Access or SQL Editor utilities (SQL querying).
5. Complete the DataBlade Developers Kit Tutorial.

See DataBlade Developers Kit Tutorial for more information.

6. Create your own practice DataBlade module.

See Creating a Practice DataBlade Module for more information.

Some of these steps are described in the following sections.

If you are developing a DataBlade module as a commercial product, join the DataBlade Partners Program. The DataBlade Partners Program helps third-party DataBlade developers create and market new DataBlade modules. The program offers tools, training, and joint marketing opportunities. If you join the program, you can have your DataBlade module certified by Informix. Certification verifies that your DataBlade module programming and business practices comply with Informix quality standards.

Important: If you plan to have your DataBlade module certified by Informix, you must be a member of the DataBlade Partners Program.

For information on enrollment requirements and benefits, send email to datablades@informix.com.

Install and become familiar with the following Informix software products:

• Your database server
• Informix Client Software Developer's Kit
• DataBlade Developers Kit

In addition, if you plan to develop a DataBlade module in Java, you should become familiar with Informix J/Foundation and the Java Development Kit (JDK). For information on the correct version and the source of the JDK, see the release notes for your database server.

Install the latest version of the Informix software for your development environment. Although the DataBlade Developers Kit is only available on Windows NT, it can generate DataBlade modules for UNIX as well as Windows NT.

For information on currently available Informix software releases, see the Informix Developer Network Web site at http://www.informix.com/idn.

The DataBlade Developers Kit Tutorial offers several exercises, each focusing on a single aspect of DataBlade module development.

To access the exercises, start the tutorial from the DataBlade Developers Kit InfoShelf home page. You can launch the InfoShelf from the BladeSmith Help menu or start it independently by choosing Start Programs Informix DBDK InfoShelf.

To familiarize yourself with the entire development process, create a simple practice DataBlade module containing an easily implemented object, such as a user-defined routine that takes built-in data types as arguments. Be sure to write the code, test it, and debug it. Completing a simple DataBlade module helps you create a realistic estimate of the length of your development cycle.

DataBlade modules can contain complex operations. A good design is critical to your success.

1. Read about DataBlade module SQL design concepts.

For DataBlade module SQL design issues, see Chapter 2, Designing DataBlade Modules.

For general information about the options you have when you extend the server, see Extending Informix Dynamic Server 2000.

2. Write a functional specification.

See Writing a Functional Specification for more information.

3. Read Informix coding guidelines.

See Programming Resources for more information.

4. Write a design specification.

See Writing a Design Specification for more information.

5. Create an iterative development strategy.

See Creating an Iterative Development Plan for more information.

6. Contact the Informix DataBlade Development Partners Program Registry for a name, prefix, and error codes for your production DataBlade module. Skip this step if you are not creating a production DataBlade module.

See Contacting the Informix Registry for more information.

Some of these steps are described in the following sections.

A functional specification describes the scope and functionality of your DataBlade module, without documenting implementation details. It also documents other issues for development, such as phases of functionality, compatibility, performance, and platform. A good functional specification shows how your DataBlade module solves the problem you designed it to solve.

For a sample functional specification, see the Informix Developer Network Web site at http://www.informix.com/idn.

For specific language options and guidelines, see Chapter 3, Programming Guidelines.

The following table lists the programming language options you have when writing DataBlade module code and refers you to sources of information about them.

For further tips on coding DataBlade modules, see the Informix Developer Network Web page at http://www.informix.com/idn.

A design specification describes the overall functionality of your DataBlade module and documents the specific routines available to the user, the supporting database tables used to implement the routines, error messages, and the environment used to build the DataBlade module. A design specification also documents implementation details that the DataBlade module customer does not need to know, such as internal support routines.

If you plan to have your DataBlade module certified by Informix, you must provide a detailed design specification.

For a sample design specification, see the Informix Developer Network Web page at http://www.informix.com/idn.

Keep the following guidelines in mind when you create an iterative development plan:

• Plan the order in which to create objects.

Some objects can depend on others; you must create new data types before you create the routines that operate on them. Create simple data types and routines before complex ones. Create objects in the smallest independently testable groups. For example, you can test opaque data type support routines without any other objects.

• Add unit and functional test data for opaque data type support routines, user-defined routines, and cast support routines as you create them.

Unit tests are SQL files you use to test boundary conditions while debugging your DataBlade module on Windows NT. After you generate unit tests for all your routines with BladeSmith, you add test data to them. If you later regenerate unit tests, the changes you made are merged into the new unit test files.

Functional tests are scripts you execute to validate your DataBlade module on UNIX after you finish debugging it. You can also run functional tests on Windows NT if you use a UNIX emulator, such as MKS Toolkit. Before you generate functional tests in BladeSmith, you must enter functional test data for all your routines. You can add custom scripts, but if you alter existing scripts and then regenerate them, changes you made are overwritten. See Adding Functional Test Data for more information.

• Include tracing when you generate code.

If you enable tracing when you generate code in BladeSmith, BladeSmith includes enter and exit tracing for every routine. You can also add more tracing. See Generating Files for information on how to generate code with tracing and Tracing and Error Handling for information on the generated tracing.

• Add custom error messages.

Anticipate how your customers will use your DataBlade module and create error messages that sensibly report problems to your users. See Defining Errors for information on how to define error messages and Tracing and Error Handling for information on how to add custom error handling to your DataBlade code.

Tip: Although you can use BladeSmith to define all of the objects in a DataBlade project before you edit and test the code, you might find it helpful to develop a modular plan to define and test objects one by one before you test the project as a whole.

The Informix DataBlade Developers Program maintains a registry of object prefixes and error code ranges for all DataBlade modules. The registry ensures that object names and error codes are unique so that any combination of DataBlade modules can coexist in a database.

Before you begin to create a production DataBlade module, send an email message to registry@informix.com to register the following information with the Informix DataBlade Developers Program registry:

• A name for your DataBlade module. This is also the BladeSmith project name and the name of the installation directory for your DataBlade module; therefore, this name must follow standard directory naming conventions for both UNIX and Windows NT.
• One or more DataBlade module object prefixes. An object prefix is a three-character code with the following format:
• The first and second characters are letters.
• The third character is a letter or digit.

See New Object Prefix for more information about when to use an object prefix.

• A range of error message codes. Error message codes, which must conform to the SQL standard for SQLSTATE, have the following format:
• The first character is the letter U.
• The second and third characters are unique alphabetical characters assigned to the DataBlade module.
• The fourth and fifth characters are alphanumeric.

Using this format, a DataBlade module can have up to 1,296 error codes. If you anticipate no more than 36 error codes, you can use the three-character object name prefix in the second, third, and fourth positions, and the digits 0 through 9 and letters A through Z in the fifth position.

See Defining Errors for more information about defining error messages.