The am_insert purpose function

The database server calls am_insert for an INSERT or UPDATE statement, an ALTER FRAGMENT statement that moves a row to a different fragment, and a MERGE statement, which can perform both INSERT and DELETE or UPDATE operations on the result of an outer join of two tables.

Syntax

mi_integer am_insert(MI_AM_TABLE_DESC *tableDesc,
           MI_ROW *row,
           MI_AM_ROWID_DESC *ridDesc)

tableDesc: Points to the index descriptor.
row: Points to a row structure in shared memory that contains the values for the access method to insert.
ridDesc: Points to the row-ID descriptor, which contains the row identifier and fragment identifier for the new row that corresponds to the new index entry.

Usage

If row and ridDesc are 0, am_insert calls mi_tab_niorows() to determine the maximum number of new index entries to expect. For each entry up to the maximum number passed, the am_insert function calls mi_tab_nextrow().

Possible row identifiers include:

The sequence of this row within the fragment
An offset to an LO handle
A value that an external data manager assigns
A value that the access method assigns

For each new entry, am_insert:

Restructures and converts the data in the MI_ROW data structure as necessary to conform to the source table
Manipulates the index structure to make room for the new entry
Stores the new data in the appropriate sbspace or extspace
If the data is in an extspace, the access method stores the rowID value for use in retrieving the new record in the future.

To manipulate the index structure, am_insert executes support functions, either with a call to an access-method function or with the DataBlade® API FastPath facility. Call mi_tab_userdata() to retrieve the pointer to PER_STATEMENT user data. Call mi_routine_exec() to execute the support function.

Important: The database server does not call am_insert unless the am_readwrite purpose flag is set. If you do not set the am_rowids purpose flag, the database server ignores any row identifier that the access method provides.

Important: If the access method does not supply am_insert, but an SQL statement requires it, the database server raises an error. For more information on how to handle this error, see Supply error messages and a user guide for your functions.

For more information, see the purpose flags am_rewrite and am_rowid in Setting purpose functions, flags, and values.

Return values

MI_OK: Indicates success.
MI_ERROR: Indicates failure.