Components That You Provide

As the developer of a user-defined access method, you design, write, and test the following components:

• Purpose functions
• Additional UDRs that the purpose functions call
• Operator-class functions
• User messages and documentation

Purpose Functions

A purpose function is a UDR that can interpret the user-defined structure of a virtual index. You implement purpose functions in C to build, connect, populate, query, and update indexes. The interface requires a specific purpose-function syntax for each of several specific tasks.

Table 4 shows the task that each purpose function performs and the reasons that the database server invokes that purpose function. In Table 4, the list groups the purpose functions as follows:

• Data-definition
• File or smart-large-object access
• Data changes
• Scans
• Structure and data-integrity verification

  Table 4. Purpose Functions

  Generic Name	Description	Invoking Statement or Command
  am_create	Creates a new virtual index and registers it in the system catalog	CREATE INDEX ALTER FRAGMENT
  am_drop	Drops an existing virtual index and removes it from the system catalog	DROP INDEX
  am_open	Opens the file or smart large object that contains the virtual index Typically, am_open allocates memory to store handles and pointers.	CREATE INDEX DROP INDEX DROP DATABASE ALTER FRAGMENT DELETE, UPDATE, INSERT SELECT
  am_close	Closes the file or smart large object that contains the virtual index and releases any remaining memory that the access method allocated	CREATE INDEX ALTER FRAGMENT DELETE, UPDATE, INSERT SELECT
  am_insert	Inserts a new entry into a virtual index	CREATE INDEX ALTER FRAGMENT INSERT UPDATE key
  am_delete	Deletes an existing entry from a virtual index	DELETE, ALTER FRAGMENT UPDATE key
  am_update	Modifies an existing entry in a virtual index	UPDATE
  am_stats	Builds statistics information about the virtual index	UPDATE STATISTICS
  am_scancost	Calculates the cost of a scan for qualified data in a virtual index	SELECT INSERT, UPDATE, DELETE WHERE...
  am_beginscan	Initializes pointers to a virtual index, and possibly parses the query statement, prior to a scan	SELECT INSERT, UPDATE, DELETE WHERE...
  am_getnext	Scans for the next index entry that satisfies a query	SELECT INSERT, UPDATE, DELETE WHERE..., ALTER FRAGMENT
  am_rescan	Scans for the next item from a previous scan to complete a join or subquery	SELECT INSERT, UPDATE, DELETE WHERE...
  am_endscan	Releases resources that am_beginscan allocates	SELECT INSERT, UPDATE, DELETE WHERE...
  am_check	Performs a check on the physical integrity of a virtual index	oncheck utility

For more information about purpose functions, refer to the following chapters:

• Developing an Access Method, helps you decide which purpose functions to provide and explains how to register them in a database.
• Design Decisions, describes some of the functionality that you program and provides examples of program code.
• Purpose-Function Reference, specifies syntax and usage.

User-Defined Routines and Header Files

The database server calls a purpose function to initiate a specific task. Often, the purpose function calls other modules in the access-method library. For example, the scanning, insert, and update purpose functions might all call the same UDR to check for valid data type.

A complete access method provides modules that convert data formats, detect and recover from errors, commit and roll back transactions, and perform other tasks. You provide the additional UDRs and header files that complete the access method.

Operator Class

The functions that operate on index keys of a particular data type make up an operator class. The operator class has two types of functions:

• Strategy functions, which are operators that appear in SQL statements

  For example, the function equal(column, constant) or the operator expression column = constant appears in the WHERE clause of an SQL query.

• Support functions that the access method calls

  For example, the function compare(column, constant) might return a value that indicates whether each index key is less than, equal to, or greater than the specified constant.

The unique operator-class name provides a way to associate different kinds of operators with different secondary access methods.

You designate a default operator class for the access method. If a suitable operator class exists in the database server, you can assign it as the default. If not, you program and register your own strategy and support functions and then register an operator class.

For more information about operator classes, strategy functions, and support functions, refer to IBM Informix: User-Defined Routines and Data Types Developer's Guide.

User Messages and Documentation

You provide messages and a user guide that help end users apply the access method in SQL statements and interpret the results of the oncheck utility.

A user-defined access method alters some of the functionality that the database server manuals describe. The documentation that you provide details storage-area constraints, deviations from the IBM Informix implementation of SQL, configuration options, data types, error messages, backup procedures, and extended features that the IBM Informix documentation library does not describe.

For samples of user documentation that you must provide, refer to Supplying Error Messages and a User Guide.