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 TABLE statement, it calls 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 table 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 table structure. When the purpose function exits, the access-method returns a pre-specified value to indicate success or failure.