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.

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 rowindex entry, an am_getnext purpose function can:

• Read source index data into user data
• Execute strategy 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.

• 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 Bypassing Table Scans describes.

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 rowsindex entries. For more information about buffering, see Buffering Multiple Results and the example of an am_getnext loop in 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 row-ID descriptor for 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_scan_quals(), mi_tab_niorows(), and mi_tab_setnextrow() in Descriptor Function Reference
• The am_keyscan purpose flag in Purpose Options
• DataBlade API function mi_row_create() in the IBM Informix: DataBlade API Programmer's Guide
• Executing Qualification Functions and Using FastPath
• Optimizing Queries