Home
Extending Informix®
Beyond standard relational database objects, HCL Informix® can be extended to handle specialized data types, access methods, routines, and other objects. Informix includes many built-in extensions that are fully integrated in the database server. Informix also provides DataBlade® modules, which are packages of extended database objects for a particular purpose and that are installed separately from the database server. Alternatively, you can create your own user-defined objects for Informix.
Creating extensions
You can create user-defined data types, routines, access methods, and other database objects to suit your needs. You can use application programming interfaces to write user-defined routines and applications that access data in Informix® databases.
DataBlade® API Programmer's Guide
The Informix® DataBlade® API Programmer's Guide describes information about the DataBlade API, the C-language application programming interface (API) provided with HCL Informix.
Database access
Execute SQL statements
One basic task of a DataBlade® API module is to send SQL statements to the database server for execution.
Retrieving query data
Obtain column values
Access the columns
The mi_value() and mi_value_by_name() functions access the row structure for the current row. The current row is in the cursor that is associated with the current statement. Because a current statement is associated with a connection, you must pass a connection descriptor into mi_value() or mi_value_by_name() to identify the row to access.

Extending Informix®
Beyond standard relational database objects, HCL Informix® can be extended to handle specialized data types, access methods, routines, and other objects. Informix includes many built-in extensions that are fully integrated in the database server. Informix also provides DataBlade® modules, which are packages of extended database objects for a particular purpose and that are installed separately from the database server. Alternatively, you can create your own user-defined objects for Informix.
- Informix® extensions and DataBlade® modules
  These topics describe how to use built-in database extensions and separately installed DataBlade® modules.
- Creating extensions
  You can create user-defined data types, routines, access methods, and other database objects to suit your needs. You can use application programming interfaces to write user-defined routines and applications that access data in Informix® databases.
  - DataBlade® API Programmer's Guide
    The Informix® DataBlade® API Programmer's Guide describes information about the DataBlade API, the C-language application programming interface (API) provided with HCL Informix.
    - DataBlade® API overview
    - Data manipulation
    - Database access
      - Connection handling
        This section describes how to initialize, establish, and close connections.
      - Execute SQL statements
        One basic task of a DataBlade® API module is to send SQL statements to the database server for execution.
        Execute SQL statements
        To execute an SQL statement, a DataBlade® API module must send the SQL statement to the database server, where the statement is executed.
        Process statement results
        Retrieving query data
        Obtain row information
        A row descriptor (MI_ROW_DESC) contains information about the columns in a row.
        Obtain column information
        When you have a row descriptor for the row, you can obtain information about the columns with the row-descriptor access functions.
        Retrieve rows
        Obtain column values
        Execute the column-value loop
        Access the columns
        The mi_value() and mi_value_by_name() functions access the row structure for the current row. The current row is in the cursor that is associated with the current statement. Because a current statement is associated with a connection, you must pass a connection descriptor into mi_value() or mi_value_by_name() to identify the row to access.
        Pass in the value buffer
        To obtain the column value, you must pass in a pointer to a value buffer as an argument to mi_value() or mi_value_by_name(). The value buffer is the place that these functions put the column value that they retrieve from the current row. Both mi_value() and mi_value_by_name() represent a column value as a pointer to an MI_DATUM structure.
        Interpret column-value status
        The mi_value() and mi_value_by_name() functions return a value status, which identifies how to interpret the column value that these functions pass back.
        Obtain normal values
        The mi_value() and mi_value_by_name() functions return the MI_NORMAL_VALUE value status for a column with any data type other than a row type or collection. Therefore, these functions return MI_NORMAL_VALUE for columns that have a built-in data type, smart large object, opaque type, or distinct type.
        Obtain NULL values
        The mi_value() and mi_value_by_name() functions return the MI_NULL_VALUE value status for a column that contains the SQL NULL value. These functions return MI_NULL_VALUE for columns of any data type.
        Obtain row values
        Obtain collection values
        For a collection, the value that the mi_value() and mi_value_by_name() functions return depends on whether the control mode for the query data is text or binary representation.
        Example: The get_data() function
        Complete execution
        The DataBlade® API provides functions to complete execution of the current statement.
        Inserting data into the database
        To insert a row of data into a database, you must execute the INSERT statement.
        Save sets
        Save sets provide a mechanism for a DataBlade® API module to access several rows simultaneously.
      - Execute user-defined routines
        This section provides information about how to call a user-defined routine (UDR).
      - Exceptions and events
        This section describes exceptions and events, and explains how to handle them in DataBlade® API modules.
      - XA-compliant external data sources
    - Create user-defined routines
    - Appendix
      This section contains additional reference information.
  - DataBlade® API Function Reference
    The Informix® DataBlade® API Function Reference describes the DataBlade API functions and the subset of Informix ESQL/C functions that the DataBlade API supports.
  - DataBlade® Developers Kit
    The DataBlade® Developers Kit (DBDK) guides contain information about the tools you can use to develop and package DataBlade modules, which extend the functionality of HCL Informix® databases.
  - J/Foundation Developer's Guide
    The J/Foundation Developer's Guide describes how to write user-defined routines (UDRs) in the Java™ programming language for Informix®.
  - R-Tree Index User's Guide
    The Informix® R-Tree Index User's Guide describes the HCL Informix R-tree secondary access method and how to access and use its components.
  - User-Defined Routines and Data Types Developer's Guide
    The Informix® User-Defined Routines and Data Types Developer's Guide describes how to define new data types and enable user-defined routines (UDRs) to extend HCL Informix.
  - Virtual-Table Interface Guide
    The Informix® Virtual-Table Interface Programmer's Guide explains how to create a primary access method with the Virtual-Table Interface (VTI) so that users have a single SQL interface to HCL Informix tables and to data that does not conform to the storage scheme of HCL Informix.
  - Virtual-Index Interface Guide
    The Informix® Virtual-Index Interface Programmer's Guide explains how to create a secondary access method with the Virtual-Index Interface (VII) to extend the built-in indexing schemes of HCL Informix typically with a DataBlade® module.

Access the columns

The mi_value() and mi_value_by_name() functions access the row structure for the current row. The current row is in the cursor that is associated with the current statement. Because a current statement is associated with a connection, you must pass a connection descriptor into mi_value() or mi_value_by_name() to identify the row to access.

These functions pass back the column value as an MI_DATUM value. The format of this value depends on whether the control mode for the query data is text or binary representation. Each of the DataBlade® API statement-execution functions indicates the control mode for query data.

To obtain this column value, your DataBlade® API module must perform the following steps:

Declare a value buffer to hold the column value that mi_value() or mi_value_by_name() passes back.
Obtain the column value from the value buffer, based on the value status that mi_value() or mi_value_by_name() returns.