The am_getnext purpose function
The am_getnext purpose function identifies rows that meet query criteria.
Syntax
mi_integer am_getnext(MI_AM_SCAN_DESC *scanDesc,
MI_ROW **row,
MI_AM_ROWID_DESC *ridDesc)- scanDesc
- Points to the scan descriptor.
- row
- Points to the location where an access method can create a row
structure that contains the index keys.
Most secondary access methods fill the row location with NULL values and do not create rows. Create a row only if the access method supports the am_keyscan purpose flag.
- ridDesc
- Points to the returned row-ID descriptor.
Usage
Every access method must provide an am_getnext purpose function. This required function typically reads source data and returns query results.
- Read source index data into user data
- Execute functions in the qualification descriptor
- Save the results in the qualification descriptor
- Call mi_eval_am_qual() to complete a complex qualification expression
- Build a row from the fetched data that matches the projection specifications in the query
- Call mi_id_setrowid() and mi_id_setfragid() to give the location of the table row to the database server
Typically, the database server uses the information that the access method sets in the row-id descriptor to access a row from the indexed table. The access method can build a row from the key values if you set the am_keyscan purpose flag to indicate that the access method returns keys to the query, as Bypass table scans describes.
The am_getnext purpose function can loop to fill a shared-memory buffer with multiple rows.
The database server calls the am_getnext purpose function until that function returns MI_NO_MORE_RESULTS. Then the database server calls the am_endscan purpose function, if any, that the access method supplies.
If the access method does not provide an am_rescan purpose function, am_getnext stores interim data for subsequent scans in memory that persists between executions of the access method.
Return values
- MI_ROWS
- Indicates the return of a row-ID descriptor for a qualified row.
- MI_NO_MORE_RESULTS
- Indicates the end of the scan.
- MI_ERROR
- Indicates failure.
Related topics
- DataBlade API function mi_row_create() in the HCL Informix® DataBlade API Programmer's Guide