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