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.
Tip: To discuss
the function call for a given task, this publication uses a column
name from the sysams system catalog table as the generic purpose-function
name. For example, this publication 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.
The following table shows the task that each purpose function performs
and the reasons that the database server invokes that purpose function.
In Table 1, the list
groups the purpose functions as follows:
- Data-definition
- File or smart-large-object access
- Data changes
- Scans
- Structure and data-integrity verification
| 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 INDEX 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 row into a virtual index | CREATE INDEX ALTER FRAGMENT INSERT UPDATE key |
| am_delete | Deletes an existing row from a virtual index | DELETE ALTER FRAGMENT UPDATE key |
| am_update | Modifies an existing row 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 before a scan | SELECT INSERT, UPDATE, DELETE WHERE... ALTER FRAGMENT |
| 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 |