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.
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 Purpose
functions, 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 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 before 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 |