Provided Components

Home | Previous Page | Next Page Access Methods > Access-Method Components >

Provided Components

The following application program interface support is provided for the development of user-defined access methods:

Virtual-Index Interface
DataBlade API
Access-method specific SQL extensions
Additional IBM Informix API libraries, as needed

Virtual-Index Interface

The Virtual-Index Interface (VII) consists of the following items:

Purpose functions
Descriptors
Accessor functions

Purpose Functions

The database server calls user-defined purpose functions to pass SQL statement specifications and state information to the access method. The following special traits distinguish purpose functions from other user-defined routines (UDRs):

A purpose function conforms to a predefined syntax.
The purpose-function syntax describes the parameters and valid return values, but the access method developer chooses a unique function name.
The database server calls a purpose function as the entry point into the access method for a specific access-method task.
Each SQL statement results in specific purpose-function calls.
The sysams system catalog table contains the unique function name for each purpose function.
The database server substitutes calls to purpose functions for calls to built-in access-method modules.

For example, when the database server encounters a CREATE INDEX statement, it invokes an access-method function with the following required parameter and return value types:

mi_integer am_create(MI_AM_TABLE_DESC *)

To determine which UDR provides the entry point for index creation in this example, the database server looks for the function identifier in the am_create column of the sysams system catalog. The database server then calls that UDR and passes, by reference, an MI_AM_TABLE_DESC structure that contains data-definition information.

The access-method developer provides the program code inside the purpose function to create the new index structure. When the purpose function exits, the access-method returns a prespecified value to indicate success or failure.

For information about the access-method developer's contribution to purpose functions, refer to Components That You Provide. For the syntax and usage of each purpose function, refer to Purpose-Function Reference.

Descriptors

Descriptors are predefined opaque data types that the database server creates to exchange information with a Datablade module or an access method. The VII provides several descriptors in addition to those that the DataBlade API provides. An access-method descriptor contains the specifications from an SQL statement or oncheck request as well as relevant information from the system catalog.

The database server passes descriptors by reference as arguments to purpose functions. The following list highlights only a few access-method descriptors to illustrate the type of information that the database server passes to an access method. For detailed information about all the VII descriptors, refer to the Descriptors.

Descriptor Name and Structure	Database Server Entries in the Descriptor
table descriptor MI_AM_TABLE_DESC	The database server puts CREATE INDEX specifications in the table descriptor, including the following items: Identification by index name, owner, storage space, and current fragment Structural details, such as the number of fragments in the whole index, column names, and data types Optional user-supplied parameters Constraints such as read/write mode and unique keys
scan descriptor MI_AM_SCAN_DESC	The database server puts SELECT statement specifications in the scan descriptor, including the following items: Index-key columns Lock type and isolation level Pointers to the table descriptor and the qualification descriptor
qualification descriptor MI_AM_QUAL_DESC	In the qualification descriptor, the database server describes the functions and Boolean operators that a WHERE clause specifies. A qualification function tests the value in a column against a constant or value that an application supplies. The following examples test the value in the price column against the constant value 80. WHERE lessthan(price,80) WHERE price < 80 The qualification descriptor for a function identifies the following items: Function name Arguments that the WHERE clause passes to the function Negation (NOT) operator, if any A complex qualification combines the results of two previous qualifications with an AND or OR operation, as the following example shows: WHERE price < 80 AND cost > 60 A complex qualification descriptor contains each Boolean AND or OR operator from the WHERE clause. For examples, refer to Interpreting the Qualification Descriptor.

Descriptor Name and Structure

Database Server Entries in the Descriptor

table descriptor
MI_AM_TABLE_DESC

The database server puts CREATE INDEX specifications in the table descriptor, including the following items:

Identification by index name, owner, storage space, and current fragment
Structural details, such as the number of fragments in the whole index, column names, and data types
Optional user-supplied parameters
Constraints such as read/write mode and unique keys

scan descriptor
MI_AM_SCAN_DESC

The database server puts SELECT statement specifications in the scan descriptor, including the following items:

Index-key columns
Lock type and isolation level
Pointers to the table descriptor and the qualification descriptor

qualification descriptor
MI_AM_QUAL_DESC

In the qualification descriptor, the database server describes the functions and Boolean operators that a WHERE clause specifies. A qualification function tests the value in a column against a constant or value that an application supplies. The following examples test the value in the price column against the constant value 80.

WHERE lessthan(price,80)
WHERE price < 80

The qualification descriptor for a function identifies the following items:

Function name
Arguments that the WHERE clause passes to the function
Negation (NOT) operator, if any

A complex qualification combines the results of two previous qualifications with an AND or OR operation, as the following example shows:

WHERE price < 80 AND cost > 60

A complex qualification descriptor contains each Boolean AND or OR operator from the WHERE clause.

For examples, refer to Interpreting the Qualification Descriptor.

Descriptors reserve areas where the access method stores information. An access method can also allocate user-data memory of a specified duration and store a pointer to the user-data in a descriptor, as the following list shows.

Descriptor Name and Structure	Access Method Entries in the Descriptor
table descriptor MI_AM_TABLE_DESC	To share state information among multiple purpose functions, the access method can allocate user-data memory with a PER_STATEMENT duration and store a pointer to the user data in the table descriptor. PER_STATEMENT memory lasts for the duration of an SQL statement, for as long as the accessed index is open. For example, an access method might execute DataBlade API functions that open smart large objects or files and store the values, or handles, that the functions return in PER_STATEMENT memory.
scan descriptor MI_AM_SCAN_DESC	To maintain state information during a scan, an access method can allocate user-data memory with a PER_COMMAND duration and store a pointer to the user data in the scan descriptor. For example, as it scans an index, the access method can maintain a pointer in PER_COMMAND memory to the address of the current index entry.
qualification descriptor MI_AM_QUAL_DESC	As it processes each qualification against a single index entry, the access method can set the following items in the qualification descriptor: A host-variable value for a function with an OUT argument The MI_VALUE_TRUE or MI_VALUE_FALSE to indicate the result that each function or Boolean operator returns An indicator that forces the database server to reoptimize between scans for a join or subquery

To allocate memory for a specific duration, the access method specifies a duration keyword. For example, the following command allocates PER_STATEMENT memory:

my_data = (my_data_t *) mi_dalloc(sizeof(my_data_t), 
   PER_STATEMENT)

Accessor Functions

Unlike purpose functions, the VII supplies the full code for each accessor function. Accessor functions obtain and set specific information in descriptors. For example, the access method can perform the following actions:

Call the mi_tab_name() accessor function to obtain the name of the index from the table descriptor.
Store state information, such as a file handle or LO handle, in shared memory, and then call the mi_tab_setuserdata() to place the pointer to the handle in the table descriptor so that subsequent purpose functions can retrieve the handle.

For the syntax and usage of each accessor function, refer to Accessor Functions.

DataBlade API

The DataBlade application programming interface includes functions and opaque data structures that enable an application to implement C-language UDRs. The access method uses functions from the DataBlade API that allocate shared memory, execute user-defined routines, handle exceptions, construct rows, and report whether a transaction commits or rolls back.

The remainder of this manual contains information about the specific DataBlade API functions that an access method calls. For more information about the DataBlade API, refer to the IBM Informix: DataBlade API Programmer's Guide.

SQL Extensions

The IBM Informix extension to ANSI SQL-92 entry-level standard SQL includes statements and keywords that specifically refer to user-defined access methods.

Registering the Access Method in a Database

The CREATE SECONDARY ACCESS_METHOD statement registers a user-defined access method. When you register an access method, the database server puts information in the system catalog that identifies the purpose functions and other properties of the access method.

ALTER ACCESS_METHOD changes the registration information in the system catalog, and DROP ACCESS_METHOD removes the access-method entries from the system catalog.

For more information about the SQL statements that register, alter, or drop the access method, refer to SQL Statements for Access Methods.

Specifying an Access Method for a Virtual Index

The user needs a way to specify a virtual index in an SQL statement.

To create a virtual index with the CREATE INDEX statement, a user specifies the USING keyword followed by the access-method name and, optionally, with additional access-method-specific keywords.

With the IN clause, the user can place the virtual index in an extspace or sbspace.

For more information about the SQL extensions specific to virtual indexes, refer to Supporting Data Definition Statements and Supporting Data Retrieval, Manipulation, and Return.

API Libraries

For information about the complete set of APIs for Dynamic Server, refer to the IBM Informix: Getting Started Guide.