Share via

IRowsetLocate::GetRowsByBookmark

  • Article

Fetches the rows that match the specified bookmarks.

Syntax

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

Parameters

  • hChapter
    [in] The chapter handle. For nonchaptered rowsets or to designate the root rowset, the caller must set hChapter to DB_NULL_HCHAPTER.

  • 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.

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 provider called a method from IRowsetNotify in the consumer that had not yet returned, and the provider does not support reentrancy in this method.

  • 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

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

hChapter restricts which rows can be returned. If a bookmark identifies a row not in the chapter, the provider should return a status of DBROWSTATUS_E_INVALID for that row.

If the provider encounters a problem fetching a row?for example, data stored in a text file contains a letter in a numeric column?IRowsetLocate::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 IRowsetLocate::GetRowsByBookmark encounters an error while attempting to fetch a row, such as a bad bookmark or a deleted 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 that the consumer can perform a side-by-side scan of each array to determine which rows were not fetched.

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

See Also

Reference

IRowset::GetData

IRowset::GetNextRows

IRowsetLocate::GetRowsAt

IRowsetScroll::GetRowsAtRatio