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.

If a statement includes a WHERE clause, either am_beginscan or am_getnext can parse the qualification descriptor. For each index entry, an am_getnext purpose function might:
  • 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

See the description of:
  • DataBlade® API function mi_row_create() in the Informix® DataBlade API Programmer's Guide