Buffering multiple results

The am_getnext purpose function can find and store several qualified index entries in shared memory before it returns control to the database server.

To set up and fill a multiple-index entry buffer in shared memory:

Call mi_tab_setniorows() in am_open or am_beginscan to set the number of index entries that the access method can return in one scan.
Call mi_tab_niorows() at the start of am_getnext to find out how many index entries to return.
Loop through mi_tab_setnextrow() in am_getnext until the number of qualifying index entries matches the return value of mi_tab_niorows() or until no more qualifying rows remain.

The following figure shows the preceding steps.

Figure 1. Storing multiple results in a buffer

mi_integer sample_beginscan(MI_AM_SCAN_DESC *sd)
{
   mi_integer nrows = 512;
   MI_AM_TABLE_DESC *td=mi_scan_table(sd);
   mi_tab_setniorows(td, nrows);
}

mi_integer sample_getnext(MI_AM_SCAN_DESC *sd, MI_ROW **retrow,

                MI_AM_ROWID_DESC *ridDesc)
{
   mi_integer nrows, row, nextrowid, nextfragid;
   MI_ROW *nextrow=NULL; /* MI_ROW structure is not typically
used.*/

   MI_AM_TABLE_DESC *td =mi_scan_table(sd);
   nrows = mi_tab_niorows(td);

   if (nrows > 0)
   {/*Store qualified results in shared memory.buffer.*/
      for (row = 0; row &lt; nros; ++row)
      { /* Evaluate rows until we get one to return to caller. */
       find_good_row(sd, &nextrow;,&nextroid;, &fragid;
       mi_tab_setnextrow(td, nextrow, nextrowid, nextfragid);
      } /* End of loop for nrows times to fill shared memory.*/
   }/*End (nrows > 0). */
   else
   {/*Only one result per call to am_getnext. */
      find_good_row(sd, &nextrow;,&nextrowid; &nextfragid);

      mi_id_setrowid(ridDesc, nextrowid);
      mi_id_setfragid(ridDesc, nextfragid); 
   } 
   /* When reach the end of data, return MI_NO_MORE_RESULTS, else return
MI_ROWS. */
}

Typically, a secondary access method does not create rows from key data. However, if you intend to set the am_keyscan purpose flag for a secondary access method, the access method must create an MI_ROW structure that contains key values in the appropriate order and of the appropriate data type to match the query specifications for a projected row.

Important: Although a user can index UDTs, the database server issues an exception if the secondary access method creates and returns a row from index keys that contain UDTs.