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.

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

  To find out how to create a row, refer to Converting to and from Row Format.

The am_getnext purpose function can loop to fill a shared-memory buffer with multiple rows. For more information about buffering, see Buffering Multiple Results.

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. For more information on memory duration, refer to Storing Data in Shared Memory.

MI_ROWS indicates the return of a qualified row.

MI_NO_MORE_RESULTS indicates the end of the scan.

MI_ERROR indicates failure.

See the descriptions of:

• Purpose functions am_getnext, am_endscan, and am_rescan
• Accessor functions mi_eval_am_qual(), mi_tab_niorows(), and mi_tab_setnextrow() in Descriptor Function Reference
• DataBlade API function mi_row_create() in the IBM Informix: DataBlade API Programmer's Guide
• Executing Qualification Functions
• Optimizing Queries