Components That You Provide

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

Purpose Functions

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

To discuss the function call for a given task, this manual uses a column name from the sysams system catalog table as the generic purpose-function name. For example, this manual refers to the UDR that builds a new table as am_create. The am_create column in sysams contains the registered UDR name that the database server calls to perform the work of am_create.

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:

Table 4. Purpose Functions
Generic Name	Description	Invoking Statement or Command
am_create	Creates a new virtual table and registers it in the system catalog	CREATE TABLE ALTER FRAGMENT
am_drop	Drops an existing virtual table and removes it from the system catalog	DROP TABLE
am_open	Opens the file or smart large object that contains the virtual table Typically, am_open allocates memory to store handles and pointers.	CREATE TABLE DROP TABLE DROP DATABASE ALTER FRAGMENT DELETE, UPDATE, INSERT SELECT
am_close	Closes the file or smart large object that contains the virtual table and releases any remaining memory that the access method allocated	CREATE TABLE ALTER FRAGMENT DELETE, UPDATE, INSERT SELECT
am_insert	Inserts a new row into a virtual table	ALTER FRAGMENT INSERT
am_delete	Deletes an existing row from a virtual table	DELETE, ALTER FRAGMENT
am_update	Modifies an existing row in a virtual table	UPDATE
am_stats	Builds statistics information about the virtual table	UPDATE STATISTICS
am_scancost	Calculates the cost of a scan for qualified data in a virtual table	SELECT INSERT, UPDATE, DELETE WHERE...
am_beginscan	Initializes pointers to a virtual table and possibly parses the query statement prior to a scan	SELECT INSERT, UPDATE, DELETE WHERE...
am_getnext	Scans for the next row 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_getbyid	Uses a specific physical address to fetch a row	SELECT using an index INSERT, UPDATE, DELETE
am_check	Performs a check on the physical integrity of a virtual table	oncheck utility

Table 4. Purpose Functions

Generic Name

Description

Invoking Statement or Command

am_create

Creates a new virtual table and registers it in the system catalog

CREATE TABLE
ALTER FRAGMENT

am_drop

Drops an existing virtual table and removes it from the system catalog

DROP TABLE

am_open

Opens the file or smart large object that contains the virtual table Typically, am_open allocates memory to store handles and pointers.

CREATE TABLE
DROP TABLE
DROP DATABASE
ALTER FRAGMENT
DELETE, UPDATE, INSERT
SELECT

am_close

Closes the file or smart large object that contains the virtual table and releases any remaining memory that the access method allocated

CREATE TABLE
ALTER FRAGMENT
DELETE, UPDATE, INSERT
SELECT

am_insert

Inserts a new row into a virtual table

ALTER FRAGMENT
INSERT

am_delete

Deletes an existing row from a virtual table

DELETE, ALTER FRAGMENT

am_update

Modifies an existing row in a virtual table

UPDATE

am_stats

Builds statistics information about the virtual table

UPDATE STATISTICS

am_scancost

Calculates the cost of a scan for qualified data in a virtual table

SELECT
INSERT, UPDATE, DELETE WHERE...

am_beginscan

Initializes pointers to a virtual table and possibly parses the query statement prior to a scan

SELECT
INSERT, UPDATE, DELETE WHERE...

am_getnext

Scans for the next row 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_getbyid

Uses a specific physical address to fetch a row

SELECT using an index
INSERT, UPDATE, DELETE

am_check

Performs a check on the physical integrity of a virtual table

oncheck utility

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.

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.