What Is the DataBlade API?

The DataBlade API contains the following pieces for the development of DataBlade API modules:

Informix provides the following categories of header files for use in a DataBlade API module:

The DataBlade API header files begin with the mi prefix. The DataBlade API provides the following header files for use in DataBlade API modules.

Header File	Description
mi.h	The main DataBlade API header file. It includes the DataBlade API public header files: milib.h, milo.h, miloback.h, mitrace.h, and miback.h.
milib.h	Defines function prototypes for the public entry points, and public declarations of required data structures and related macros. The *mi.h* header file automatically includes *milib.h*.
mitypes.h	Defines all DataBlade `API` simple data types, their accessor macros, and their directly related value macros. The mitypes.h header file automatically includes the ESQL/C header files: datetime.h, decimal.h, and int8.h. The *milib.h* header file automatically includes *mitypes.h*.
milo.h	Defines the data structures, values, and function prototypes for the smart-large-object interface (functions that have names starting with mi_lo_). The *mi.h* file header automatically includes *milo.h*.
mitrace.h	Defines the data structures, values, and function prototypes for the DataBlade API trace facility. The *mi.h* file header automatically includes *mitrace.h*.
miloback.h	Defines the data structures, values, and function prototypes for the Illustra large-object interface (functions that have names starting with mi_large) which are backward compatible with the Illustra applications. The *mi.h* file header automatically includes *miloback.h*.
miconv.h	Contains convention definitions. Includes on/off switches based on architecture, compiler type, and so on. Other parts of the code use these switches to define data types correctly. The *mitypes.h* header file automatically includes *miconv.h*.
miback.h	Contains definitions that provide backward compatibility with Illustra applications. The *mi.h* file header automatically includes *miback.h*.

Tip: For a complete list of header files, check the incl/public subdirectory of the INFORMIXDIR directory.

The mi.h header file provides access to all DataBlade API header files in the preceding table. Include this header file in your DataBlade API module to obtain declarations of DataBlade API functions and data types.

Informix provides the following header files to support some of the functions and data types of the Informix ESQL/C library.

Header File	Contains
datetime.h	Defines structure and macro definitions for `DATETIME` and `INTERVAL` data types.
decimal.h	Defines structure and macro definitions for `DECIMAL` and `MONEY` data types.
int8.h	Contains declarations for structure and ESQL/C library functions for the `INT8` data type.
sqlca.h	Contains structure definition that `ESQL/C` uses to store error-status codes. This structure allows you to check for the success or failure of `SQL` statements.
sqlhdr.h	Contains the function prototypes of all `ESQL/C` library functions.

Important: The mitypes.h header file automatically includes the datetime.h, decimal.h, and int8.h header files. In turn, the milib.h header file automatically includes mitypes.h, and mi.h automatically includes milib.h. Therefore, you automatically have access to the information in these ESQL/C header files when you include mi.h in your DataBlade API module.

For additional information about the use of these ESQL/C header files, see the following sections of this manual.

Header File	For More Information
datetime.h	datetime.h Header File
decimal.h	decimal.h Header File
int8.h	int8.h Header File

Informix provides a header file to support the Informix GLS library. If you use the Informix GLS library in your DataBlade API module, include its header file, ifxgls.h, in your source code. For more information on the Informix GLS library and how to use it in a DataBlade API module, see Internationalization of DataBlade API Modules.

If you define any opaque data types, you must include their header file in your DataBlade API source code. An opaque-type header file usually contains the declaration of the internal format for the opaque data type. For more information, see Creating an Opaque Data Type.

To ensure portability across dissimilar machine architectures, the DataBlade API provides a set of simple data types, which Figure 1-1 shows. These data types begin with the mi_ prefix. Most of these data types correspond to common SQL or C-language data types.

DataBlade API Data Type	Standard C or ESQL/C Data Type	SQL Data Type
Character Data Types
mi_char	C: char	`CHAR, VARCHAR,` `GLS: NCHAR`, `NVARCHAR`
mi_char1	C: char	`CHAR(1)`
mi_unsigned_char1	C: unsigned char	None
mi_wchar (deprecated)	C: unsigned 2-byte integer	None
mi_string	C: char *	`CHAR, VARCHAR,` `GLS: NCHAR`, `NVARCHAR`
mi_lvarchar	ESQL/C: lvarchar (though lvarchar is null-terminated and mi_lvarchar is not)	`LVARCHAR` Within C UDRs: for `CHAR, NCHAR, TEXT, VARCHAR, and NVARCHAR arguments and return value`
Numeric Data Types: Integer
mi_sint1	C: signed 1-byte integer	None
mi_int1	C: unsigned 1-byte integer, char	None
mi_smallint	C: signed 2-byte integer (short integer on many systems)	`SMALLINT`
mi_unsigned_smallint	C: unsigned 2-byte integer	None
mi_integer	C: signed 4-byte integer (long integer on many systems)	`INTEGER`, `SERIAL`
mi_unsigned_integer	C: unsigned 4-byte integer	None
mi_int8	C: signed 8-byte integer; ESQL/C: int8, ifx_int8_t	`INT8`, `SERIAL8`
mi_unsigned_int8	C: unsigned 8-byte integer; ESQL/C: int8, ifx_int8_t	None
Numeric Data Types: Fixed-Point
mi_decimal, mi_numeric	ESQL/C: decimal, dec_t	`DECIMAL`(p,s) (fixed-point)
mi_money	ESQL/C: decimal, dec_t	`MONEY`
Numeric Data Types: Floating-Point
mi_decimal	ESQL/C: decimal, dec_t	`DECIMAL`(p) (floating-point)
mi_real	C: float	`SMALLFLOAT`, `REAL`
mi_double_precision	C: double	`FLOAT`, `DOUBLE PRECISION`
Date and Time Data Types
mi_date	C: 4-byte integer ESQL/C: date	`DATE`
mi_datetime	ESQL/C: datetime, dtime_t	`DATETIME`
mi_interval	ESQL/C: interval, intrvl_t	`INTERVAL`
Varying-Length Data Types
mi_lvarchar	C: void * ESQL/C: lvarchar (though lvarchar is null-terminated and mi_lvarchar is not)	`LVARCHAR`, Opaque types Within C UDRs: for `CHAR, NCHAR, TEXT, VARCHAR,` and `NVARCHAR` arguments and return value
mi_sendrecv	C: void *	`SENDRECV`, opaque-type support functions: send, receive
mi_impexp	C: void *	`IMPEXP`, opaque-type support functions: import, export
mi_impexpbin	C: void *	`IMPEXPBIN`, opaque-type support functions: importbin, exportbin
mi_bitvarying	C: void *	None
Complex Types
`MI_COLLECTION`	C: void *	SET, LIST, MULTISET
`MI_ROW`	C: void *	`ROW` (unnamed row type), Named row type
Other Data Types
mi_boolean	C: char ESQL/C: boolean	`BOOLEAN`
mi_pointer	C: void *	`POINTER`

Important: To make your DataBlade API module portable, Informix recommends that you use the DataBlade API platform-independent data types (such as mi_integer, mi_smallint, mi_real, mi_boolean, and mi_double_precision) instead of their C-language counterparts. These data types handle the different sizes of numeric values across machine architectures.

Figure 1-1 on page 1-11 lists the correspondences between DataBlade API data types and SQL data types. However, when you pass some of these data types to and from C user-defined routines, you must pass them as pointers rather than as actual values. For more information, see Passing Mechanism for MI_DATUM Values.

Figure 1-2 shows where you can find the description of how to use these DataBlade API data types to the corresponding SQL data types.

Data Type	For More Information
`BLOB`	Chapter 6, Using Smart Large Objects
`BOOLEAN`	Boolean Data
`BYTE`	Simple Large Objects
`CHAR`	Text and String Support
`CLOB`	Chapter 6, Using Smart Large Objects
DATE	Chapter 4, Using Date and Time Data Types
`DATETIME`	Chapter 4, Using Date and Time Data Types
`DECIMAL`	Chapter 3, Using Numeric Data Types
Distinct	Chapter 14, Extending Data Types
FLOAT	Chapter 3, Using Numeric Data Types
`INT8`	Chapter 3, Using Numeric Data Types
INTEGER	Chapter 3, Using Numeric Data Types
`INTERVAL`	Chapter 4, Using Date and Time Data Types
`LIST`	Chapter 5, Using Complex Data Types
`LVARCHAR`	Varying-Length Data Structures
`MONEY`	Chapter 3, Using Numeric Data Types
`MULTISET`	Chapter 5, Using Complex Data Types
`NCHAR`	Text and String Support
`NVARCHAR`	Text and String Support
Opaque	Chapter 14, Extending Data Types
POINTER	POINTER Data Type
ROW	Chapter 5, Using Complex Data Types
SERIAL	Chapter 3, Using Numeric Data Types
`SERIAL8`	Chapter 3, Using Numeric Data Types
`SET`	Chapter 5, Using Complex Data Types
SMALLFLOAT	Chapter 3, Using Numeric Data Types
SMALLINT	Chapter 3, Using Numeric Data Types
`TEXT`	Simple Large Objects
`VARCHAR`	Text and String Support

DataBlade API Data Structures

Many DataBlade API functions provide information for DataBlade API modules in special data structures. These data types begin with the MI_ prefix. Figure 1-3 lists these data structures, their purpose, and the location in this manual where the data structure is described in more detail.

DataBlade API Data Structure	Purpose	Related Topics
MI_COLL_DESC	Collection descriptor, which describes the structure of a collection	Using a Collection Descriptor
MI_COLLECTION	Collection structure, which contains the elements of a collection	Using a Collection Structure
`MI_CONNECTION`	Connection descriptor, which contains the execution context for a connection	Establishing the Connection
`MI_CONNECTION_INFO`	Connection-information descriptor, which contains connection parameters for an open connection	Using Connection Parameters
`MI_DATABASE_INFO`	Database-information descriptor, which contains database parameters for an open connection	Using Database Parameters
MI_DATUM	Datum, which provides a transport mechanism for data types	MI_DATUM Data Type
`MI_ERROR_DESC`	Error descriptor, which describes an exception	Obtaining Event Information
`MI_EVENT_TYPE`	Classifies an event	What Is An Event?
MI_FPARAM	Function-parameter structure, which holds information about a user-defined routine that the routine can access during its execution	Accessing the Routine State with MI_FPARAM
MI_FUNC_DESC	Function descriptor, which describes a user-defined routine that is to be invoked with the Fastpath interface	Obtaining a Function Descriptor
`MI_LO_FD`	LO file descriptor, which describes an open smart large object	Obtaining an LO File Descriptor and the mi_large_object_open() function
`MI_LO_HANDLE`	LO handle, which identifies the location of a smart large object in its sbspace	Obtaining an LO Handle and the mi_large_object_create()function
MI_LO_SPEC	LO-specification structure, which contains storage characteristics for a smart large object	Obtaining the LO-Specification Structure and the mi_large_object_info() function
`MI_LO_STAT`	LO-status structure, which contains status information for a smart large object	Obtaining the Status of a Smart Large Object and the mi_large_object_stat() function
`MI_MULTIREP_DATA`	Holds multirepresentational data	Creating Multirepresentational Data
`MI_PARAMETER_INFO`	Parameter-information descriptor, which specified whether callbacks are enabled or disabled and whether pointers are checked in client `LIBMI` applications	Using Session Parameters
`MI_ROW`	Row (or row structure), which contains either the column values of a table row or field values of a row type	Retrieving Rows Using a Row Structure
`MI_ROW_DESC`	Row descriptor, which describes the structure of a row	Obtaining Row Information Using a Row Descriptor
`MI_SAVE_SET`	Save-set descriptor, which describes a save set	Creating a Save Set
MI_STATEMENT	Statement descriptor, which describes a prepared SQL statement	Executing Prepared SQL Statements
`MI_TRANSITION_DESC`	Error descriptor, which describes an exception	Obtaining Event Information
MI_TYPEID	Type identifier, which uniquely identifies a data type within a database	Type Identifiers
MI_TYPE_DESC	Type descriptor, which provides information about a data type	Type Descriptors

The DataBlade API also provides simple data types for use with SQL values. For a list of these data types, see Figure 1-1 on page 1-11.

The DataBlade API provides constructor and destructor functions for most of these public DataBlade API data structures. These functions handle memory allocation of these data structures, as follows:

The DataBlade API provides support for the following types of functions in a DataBlade API module.

Type of Function	Purpose
DataBlade API functions	Provide access to the database server
Informix ESQL/C functions	Provide operations on certain data types
Informix GLS functions	Provide the ability to internationalize your DataBlade API module

The DataBlade API functions begin with the mi_ prefix. The milib.h header file declares most of these DataBlade API functions. The mi.h header file automatically includes milib.h. You must include mi.h in any DataBlade API module that uses a DataBlade API function.

The functions of the DataBlade API function library can be divided into the following categories.


Category of DataBlade API Function		For More Information
Data handling
	Obtaining type information	Type Identifiers Type Descriptors
	Transferring data types between machines (Server)	Converting Opaque-Type Data With Machine-Specific Data Types
	Converting data types	DataBlade API Functions for Date Conversion DataBlade API Functions for Date and Time Conversion DataBlade API Functions for Decimal Conversion DataBlade API Functions for String Conversion
	Handling collections: sets, multisets, and lists	Collections
	Converting between code sets (Server)
	Handling collections	Collections
	Managing varying-length structure	Varying-Length Data Structures
	Obtaining `SERIAL` values	Processing Insert Results
	Accessing multirepresentational data types	Creating Multirepresentational Data
	Handling `NULL` values	The SQL NULL Value
Session, thread, and transaction management
	Obtaining connection information	Using Connection Parameters Using Database Parameters Using Session Parameters
	Establishing a connection	Establishing the Connection
	Initializing the DataBlade API	Initializing the DataBlade API
	Managing Informix threads (Server)	Yielding the CPU Managing Stack Usage
	Obtaining transaction and server-processing state changes	Using a Transition Descriptor
Processing SQL statements
	Sending SQL statements	Executing Basic SQL Statements Executing Prepared SQL Statements
	Obtaining statement information	Returning a Statement Descriptor Obtaining Input-Parameter Information
	Obtaining result information	Processing Statement Results
	Retrieving rows and row data (also row types and row-type data)	Obtaining Row Information Retrieving Rows
	Retrieving columns	Obtaining Column Information Obtaining Column Values
	Using save sets	Using Save Sets
Executing a user-defined-routine
	Accessing the `MI_FPARAM` structure	Accessing the Routine State with MI_FPARAM
	Allocating an `MI_FPARAM` structure	Using a User-Allocated MI_FPARAM Structure
	Using the Fastpath interface	Calling UDRs with the Fastpath Interface
	Accessing a function descriptor	Obtaining Information from a Function Descriptor
Managing memory		Managing Memory
Handling exceptions
	Raising a database exception	Raising an Exception
	Accessing an error descriptor	Using an Error Descriptor, Handling Multiple Exceptions
	Using callback functions	Invoking a Callback
Smart-large-object interface
	Creating a smart large object	Smart-Large-Object Creation
	Performing I/O on a smart large object	Smart-Large-Object I/O
	Moving smart large objects to and from operating-system files	Smart Large Objects to and from Operating-System Files
	Manipulating `LO` handles	Manipulation of LO Handles
	Handling `LO`-specification structures	Smart-Large-Object Storage Characteristics
	Handling smart-large-object status	Smart-Large-Object Status
	Illustra large-object interface (for backward compatibility)	Using the Illustra Large-Object Interface
Smart-large-object interface (continued)
	Using the operating-system file interface Tracing (Server) Managing databases (Client) Miscellaneous	Accessing Operating-System Files Using Tracing None None

If an error occurs while one of the DataBlade API function executes, the function usually indicates the error with one of the following return values.

Way to Indicate an Error	For More Information
Functions that return a pointer return the `NULL`-valued pointer	The NULL-Valued Pointer
Functions that return an mi_integer (or other integer) value return the `MI_ERROR` status code	Handling Errors From DataBlade API Functions
Functions that raise an exception	Handling Errors From DataBlade API Functions

In a DataBlade API module, you can use some of the functions in the Informix ESQL/C library functions to perform conversions and operations on different data types. The ESQL/C functions do not begin with the mi_ prefix. Various header files declare these functions. For more information, see ESQL/C Header Files.

The functions of the ESQL/C function library that are valid in a DataBlade API module can be divided into the following categories.

Category of DataBlade API Function	For More Information
Byte handling	Manipulating Byte Data
Character processing	ESQL/C Functions for String Conversion Operations on Character Values
`DECIMAL`-type and `MONEY`-type processing	ESQL/C Functions for Decimal Conversion Performing Operations on Decimal Data
`DATE`-type processing	ESQL/C Functions for Date Conversion Performing Operations on Date Data
`DATETIME`-type processing and `INTERVAL`-type processing	ESQL/C Functions for Date, Time, and Interval Conversion Performing Operations on Date and Time Values
`INT8`-byte processing	Converting INT8 Values Performing Operations on 8-Byte Values
Processing for other C-language data types	Formatting Numeric Strings

The Informix GLS library is an application-programming interface (API) that lets developers of DataBlade API modules create internationalized applications. The macros and functions of Informix GLS provide access to the GLS locales, which contain culture-specific information.

The Informix GLS library contains functions that provide the following capabilities:

The mi.h header file does not automatically include the Informix GLS library. For more information on the Informix GLS library and how to use it in a DataBlade API module, see Internationalization of DataBlade API Modules.

Informix DataBlade API Programmer's Manual
Using the DataBlade API