The am_getbyid purpose function
The database server calls am_getbyid instead of am_getnext to pass the row identifier instead of a scan descriptor. For example, the database server might obtain the row identifier from an index on the virtual table.
Syntax
mi_integer am_getbyid(MI_AM_TABLE_DESC *tableDesc,
MI_ROW **retrow, mi_integer rowID) - tableDesc
- Points to the table descriptor.
- retrow
- Points to the location where the function is to place a row structure that contains the fetched data.
- rowID
- Is the row identifier or physical address of the row to fetch.
Usage
The am_getbyid purpose function does not scan a table to find a qualifying row.
Possible
row identifiers that rowID might point to 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
As with am_getnext, am_getbyid first
fetches the specified row and then passes the retrow pointer
to mi_row_create() to build the composite MI_ROW
value from fetched data.
Important: The database server
does not call am_getbyid unless you set the am_rowids purpose
flag.
For more information, see the purpose flag am_rowids in Settings purpose functions, flags, and values.
Return values
- MI_OK
- Indicates success.
- MI_ERROR
- Indicates failure.
Related topics
See
the description of:
- DataBlade API function mi_row_create() in the HCL Informix® DataBlade API Programmer's Guide