IRowsetLocate::GetRowsByBookmark

Fetches the rows that match the specified bookmarks.

HRESULT GetRowsByBookmark (
   HCHAPTER         hChapter,
   ULONG            cRows,
   const ULONG      rgcbBookmarks[],
   const BYTE *         rgpBookmarks[],
   HROW                rghRows[],
   DBROWSTATUS   rgRowStatus[]);

Parameters

hChapter

[in]
The chapter handle. For nonchaptered rowsets, hChapter is ignored.

cRows

[in]
The number of rows to fetch.

If cRows is zero, no rows are fetched; the fetch direction and the next fetch position are unchanged, and the provider performs no processing, returning immediately from the method invocation.

If the provider does not discover any other errors, the method returns S_OK; whether the provider checks for any other errors is provider-specific.

rgcbBookmarks

[in]
An array containing the length in bytes of each bookmark.

rgpBookmarks

[in]
An array containing a pointer to the bookmark of each row sought. These cannot be pointers to a standard bookmark (DBBMK_FIRST, DBBMK_LAST, DBBMK_INVALID). If rgpBookmarks contains a duplicate bookmark, the corresponding row is fetched and the reference count incremented once for each occurrence of the bookmark.

rghRows

[out]
An array with cRows elements in which to return the handles of the fetched rows. The consumer allocates this array but is not required to initialize the elements of it. In each element of this array, if the row was fetched, the provider returns the handle of the row identified by the bookmark in the corresponding element of rgpBookmarks. If the row was not fetched, the provider returns DB_NULL_HROW.

rgRowStatus

[out]
An array with cRows elements in which to return values indicating the status of each row specified in rgpBookmarks. If no errors or warnings occur while fetching a row, the corresponding element of rgRowStatus is set to DBROWSTATUS_S_OK. If an error occurs while fetching a row, the corresponding element is set as specified in DB_S_ERRORSOCCURRED. The consumer allocates memory for this array but is not required to initialize it. If rgRowStatus is a null pointer, no row statuses are returned. For information about the DBROWSTATUS enumerated type, see "Arrays of Errors" in Chapter 13.

Return Code

S_OK
The method succeeded. All rows were successfully fetched. The following value can be returned in rgRowStatus:

The row was successfully fetched. The corresponding element of rgRowStatus contains DBROWSTATUS_S_OK.

DB_S_ERRORSOCCURRED
An error occurred while fetching a row, but at least one row was successfully fetched. Successes can occur for the reasons listed under S_OK. The following errors can occur:

An element of rgpBookmarks pointed to an invalid or incorrectly formed bookmark. The corresponding element of rgRowStatus contains DBROWSTATUS_E_INVALID.
An element of rgpBookmarks pointed to a bookmark that did not match any rows in the rowset. This includes the case when the row corresponding to the bookmark has been deleted. The corresponding element of rgRowStatus contains DBROWSTATUS_E_INVALID.
An element of rgcbBookmarks was zero. The corresponding element of rgRowStatus contains DBROWSTATUS_E_INVALID.
An element of rgpBookmarks was a null pointer. The corresponding element of rgRowStatus contains DBROWSTATUS_E_INVALID.
An element of rgpBookmarks pointed to a standard bookmark (DBBMK_FIRST, DBBMK_LAST, DBBMK_INVALID). The corresponding element of rgRowStatus contains DBROWSTATUS_E_INVALID.
The row corresponding to the bookmark was not fetched because fetching it would have exceeded the total number of active rows supported by the rowset. The corresponding element of rgRowStatus contains DBROWSTATUS_E_LIMITREACHED.
The row corresponding to the bookmark was not fetched for the following reason. Fetching rows required further execution of the command, such as when the rowset uses a server-side cursor. Execution has been stopped because a resource limit has been reached. Execution cannot be resumed. The corresponding element of rgRowStatus contains DBROWSTATUS_E_LIMITREACHED.
The rowset ran out of memory and was unable to fetch the row. The corresponding element of rgRowStatus contains DBROWSTATUS_E_OUTOFMEMORY.
The consumer did not have sufficient permission to fetch a row. The corresponding element of rgRowStatus contains DBROWSTATUS_E_PERMISSIONDENIED.
The consumer encountered a recoverable, provider-specific error, such as an RPC failure when transmitting the change to a remote server. The corresponding element of rgRowStatus contains DBROWSTATUS_E_FAIL.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
rghRows was a null pointer.

rgcbBookmarks or rgpBookmarks was a null pointer.

E_OUTOFMEMORY
The provider was unable to allocate sufficient memory in which to return the row handles.

E_UNEXPECTED
ITransaction::Commit or ITransaction::Abort was called and the object is in a zombie state.

DB_E_BADCHAPTER
The rowset was chaptered and hChapter was invalid.

The rowset was single-chaptered and the specified chapter was not the currently open chapter. The consumer must use the currently open chapter or release the currently open chapter before specifying a new chapter.

DB_E_ERRORSOCCURRED
Errors occurred while fetching all of the rows. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED.

DB_E_NOTREENTRANT
The consumer called this method while it was processing a notification, and it is an error to call this method while processing the specified DBREASON value.

DB_E_ROWSNOTRELEASED
The provider requires release of existing rows before new ones can be fetched. For more information, see DBPROP_CANHOLDROWS in "Rowset Properties" in Appendix C.

Comments

GetRowsByBookmark increments the reference count of each row for which it returns a handle by 1. Thus, if a handle is returned for a row that has already been fetched, the reference count of that row will be greater than 1. ReleaseRows must be called once for each time the handle to a row has been returned.

If the provider encounters a problem fetching a row — for example, data stored in a text file contains a letter in a numeric column — GetRowsByBookmark fetches the row normally, returns the row handle, and returns S_OK. However, when the consumer calls IRowset::GetData for the row, the provider returns DBSTATUS_E_CANTCONVERTVALUE as the status for the offending column.

If GetRowsByBookmark encounters an error while attempting to fetch a row, such as a bad bookmark or adeleted row, it notes the error in the rgRowStatus array, continues processing, and returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED. Although the rows are fetched in undefined order, the ordering of the error array must match the order of the bookmark array, so the consumer can perform a side-by-side scan of each array to determine which rows were not fetched.

For information about what GetRowsByBookmark does when it fetches a row that it already has in its internal buffers, see "Uniqueness of Rows in the Rowset" in Chapter 4. For information about whether GetRowsByBookmark can detect changes made to rows in the rowset, see "Visibility of Changes" in Chapter 5.