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_integer *rowid);- scanDesc
- Points to the scan descriptor.
- row
- Points to the location where the access method creates rows from source records that satisfy the query.
- rowid
- Points to the returned row identifier.
Usage
Every access method must provide an am_getnext purpose function. This required function typically reads source data and returns query results.
If a statement includes a WHERE clause, either am_beginscan or am_getnext can
parse the qualification descriptor. For each row, an am_getnext purpose
function might:
- Read source 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
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 qualified row.
- MI_NO_MORE_RESULTS
- Indicates the end of the scan.
- 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