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_integer *rid)
tableDesc
Points to the table descriptor.
row
Points to a row structure in shared memory that contains the values for the access method to insert.
rid
Points to the row identifier of the new row.

Usage

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
  • 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.

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 about how to handle this error, see Supply error messages and a user guide.

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

Return values

MI_OK
Indicates success.
MI_ERROR
Indicates failure.