| Fetch the next N rows from the table.
The client allocates an array of N rows and passes it into the
fetchNextSet() call. The client must at least allocate a row and
set row_array[0] to this row. The client can optionally either leave
the rest of array entries null, or allocate rows to the slots.
If access finds an entry to be null, and wants to read a row into
it, it will allocate a row to the slot. Once fetchNextGroup() returns
"ownership" of the row passes back to the client, access will not
keep references to the allocated row. Expected usage is that
the client will specify an array of some number (say 10), and then
only allocate a single row. This way if only 1 row qualifies only
one row will have been allocated.
This routine does the equivalent of N
fetchNext() calls, filling in each of the rows in the array.
Locking is performed exactly as if the N fetchNext() calls had
been made.
It is up to Access how many rows to return. fetchNextGroup() will
return how many rows were filled in. If fetchNextGroup() returns 0
then the scan is complete, (ie. the scan is in the same state as if
fetchNext() had returned false). If the scan is not complete then
fetchNext() will return (1 <= row_count <= N).
The current position of the scan is undefined if fetchNextSet()
is used (ie. mixing fetch()/fetchNext() and fetchNextSet() calls
in a single scan does not work). This is because a fetchNextSet()
request for 5 rows from a heap where the first 2 rows qualify, but
no other rows qualify will result in the scan being positioned at
the end of the table, while if 5 rows did qualify the scan will be
positioned on the 5th row.
If the row loc array is non-null then for each row fetched into
the row array, a corresponding fetchLocation() call will be made to
fill in the rowloc_array. This array, like the row array can be
initialized with only one non-null RowLocation and access will
allocate the rest on demand.
Qualifiers, start and stop positioning of the openscan are applied
just as in a normal scan.
The columns of the row will be the standard columns returned as
part of a scan, as described by the validColumns - see openScan for
description.
Expected usage:
// allocate an array of 5 empty rows
DataValueDescriptor[][] row_array = allocate_row_array(5);
int row_cnt = 0;
scan = openScan();
while ((row_cnt = scan.fetchNextSet(row_array, null) != 0)
{
// I got "row_cnt" rows from the scan. These rows will be
// found in row_array[0] through row_array[row_cnt - 1]
}
The number of qualifying rows found and copied into the provided array of rows. If 0 then the scan is complete, otherwise the return value will be: 1 <= row_count <= row_array.length
Parameters:
row_array - The array of rows to copy rows into. row_array[].length must >= 1. The first entrymust be non-null destination rows, other entriesmay be null and will be allocated by accessif needed.
Parameters:
rowloc_array - If non-null, the array of row locations to copy into. If null, no row locations areretrieved.
exception:
StandardException - Standard exception policy. |