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 Informix® DataBlade API Programmer's Guide