Informix DataBlade API Programmer's Manual Developing a User-Defined Routine

This section provides the following design considerations for the development of a C UDR:

• Development tools
• Uses of a UDR
• Portability

The creation of a C UDR involves the production of source code, header files, SQL statements, and many other files. This manual describes how to generate the code for C UDRs yourself, using the DataBlade API and the basic tools available with an operating system.

However, Informix provides a package of development tools, called the DataBlade Developers Kit (DBDK), that helps you build and manage the C UDRs of a DataBlade module project. A DataBlade module is a package of software that extends the functionality of the database server. It can include the following objects:

• New or extended data types
• UDRs
• Error messages
• Functional tests
• Interfaces to other DataBlade modules
• Packaging and installation scripts

The DBDK runs on Windows platforms. The following table summarizes the development tools of the DBDK.

These development tools include on-line help to describe their use. Informix also provides the DataBlade Developers Kit User's Guide to describe these tools.

BladeSmith can develop source code and a makefile that can be compiled on a UNIX platform.

Consider using the development tools of the DBDK to generate the initial code for your C UDRs. You can then use the information in this manual to enhance and change this code to handle the unique needs of your C UDR or DataBlade module.

The following table summarizes the tasks that a C UDR can perform. It also describes where you can find additional information in this manual for each of these UDR uses.

To ensure portability of your C UDR, include the following items in the design and implementation of your C UDR:

• Use the DataBlade API data types for data types whose size might vary across computer architectures.
• Use the DataBlade API functions to transfer data between client and server computers.

The DataBlade API provides platform-independent data types, such as mi_smallint (2-byte integer), mi_integer (4-byte integer), and mi_double_precision (floating-point values). For a complete list of DataBlade API data types, see Figure 1-1 on page 1-11. The mitypes.h header file defines these data types.

Tip: The mi.h header file automatically includes the milib.h header, which in turn includes the mitypes.h header file. Therefore, you do not need to explicitly include mitypes.h to use the DataBlade API data types.

To ensure maximum portability of your code, use these platform-independent data types instead of their C-language equivalents.

The DataBlade API provides special functions to handle the following data conversions that a C UDR might need to perform:

• Data conversion between the text and binary representations of the data

The control mode of a query determines whether the query results are in text or binary representation. The DataBlade API provides functions that convert between these two representations. Conversion between these two representations might also be useful in the input and output support functions of an opaque type. For a list of these functions, see Converting Opaque-Type Data Between Text and Binary Representations.

• Data transfer between a client application and the database server

When opaque-type data is transferred between a client application and the database server, the database server calls the send and receive support functions. For these UDRs, you can handle potential differences in computer architecture that might affect the byte ordering or size with special DataBlade API functions. For more information, see Converting Opaque-Type Data With Machine-Specific Data Types.