Writing Purpose Functions

Home | Previous Page | Next Page Developing an Access Method >

Writing Purpose Functions

The VII specifies the parameters and return values for a limited set of UDRs, called purpose functions, that correspond to one or more SQL statements. For most SQL statements, the database server attempts to invoke a sequence of task-specific purpose functions to process the statement. You choose the tasks and SQL statements that the access method supports and then write the appropriate purpose functions for those tasks. For more information about the specific purpose functions that the database server executes for specific statements, refer to Purpose-Function Flow.

Table 7 shows purpose-function prototypes for access-method tasks and one or more corresponding SQL statements. Table 7 includes the purpose function prototype that the database server calls to process the oncheck utility.

Table 7. Statements and Their Purpose Functions
Invoking Statement or Command	Purpose-Function Prototype
All If you do not supply am_open and am_close, open and close the data source in am_getnext.	am_open(MI_AM_TABLE_DESC ) am_close(MI_AM_TABLE_DESC )
CREATE INDEX	am_create(MI_AM_TABLE_DESC ) am_insert(MI_AM_TABLE_DESC , MI_ROW , MI_AM_ROWID_DESC )
DROP INDEX	am_drop(MI_AM_TABLE_DESC *)
INSERT	am_insert(MI_AM_TABLE_DESC , MI_ROW , MI_AM_ROWID_DESC *)
DELETE	`am_delete(MI_AM_TABLE_DESC , MI_ROW , MI_AM_ROWID_DESC *)`
SELECT INSERT, UPDATE, DELETE WHERE...	am_scancost(MI_AM_TABLE_DESC , MI_AM_QUAL_DESC ) am_beginscan(MI_AM_SCAN_DESC ) am_getnext(MI_AM_SCAN_DESC , MI_ROW *, MI_AM_ROWID_DESC ) am_endscan(MI_AM_SCAN_DESC *)
SELECT with join	am_rescan(MI_AM_SCAN_DESC *)
UPDATE	am_update(MI_AM_TABLE_DESC , MI_ROW , MI_AM_ROWID_DESC , MI_ROW ,MI_AM_ROWID_DESC *
UPDATE STATISTICS	am_stats(MI_AM_TABLE_DESC ,MI_AM_ISTATS_DESC )
oncheck utility	am_check(MI_AM_TABLE_DESC *, mi_integer)

Important:

Do not use the purpose label (am_open, am_create, am_getnext) as the actual name of a user-defined purpose function. Avoid names such as vii_open, vii_create, vii_*. Assign unique names, such as image_open, docfile_open, and getnext_record. To prevent potential name-space collision, follow the instructions for registering and using an object prefix in the IBM Informix: DataBlade Developer's Kit User's Guide.

When the database server calls a purpose function, it passes the appropriate parameters for the current database server activity. Most parameters reference the opaque descriptor data structures. The database server creates and passes descriptors to describe the state of the index and the current SQL statement or oncheck command. For an overview of descriptors, refer to Descriptors, and for detailed information, refer to Descriptors.

As you write the purpose functions, adhere to the syntax provided for each in Purpose-Function Syntax.

At a minimum, you must supply one purpose function, the am_getnext purpose function, to scan data. To determine which other purpose functions to provide, decide if the access method should support the following tasks:

Opening and initializing files or smart large objects, as well as closing them again at the end of processing
Creating new indexes
Inserting, updating, or deleting data
Running the oncheck utility
Optimizing queries

Warning:

The database server issues an error if a user or application tries to execute an SQL statement and the access method does not include a purpose function to support that statement.

The following sections name the functions that the database server calls for the specific purposes in the previous list. The access-method library might contain a separate function for each of several purpose-function prototypes or supply only an am_getnext purpose function as the entry point for all the essential access-method processing. For a detailed description of each purpose function, refer to Purpose-Function Reference.