Share via

IRowsetBookmark::PositionOnBookmark

Sets the next fetch position for the rowset to be immediately before the specified bookmark.

Syntax

HRESULT PositionOnBookmark (
   HCHAPTER      hChapter,
   DBBKMARK      cbBookmark,
   const BYTE   *pBookmark);

Parameters

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

  • cbBookmark
    [in] The length in bytes of the bookmark.

  • pBookmark
    [in] A pointer to a bookmark that identifies the row to be used. The bookmark can be for a designated row or either DBBMK_FIRST or DBBMK_LAST.

Return Code

  • S_OK
    The method succeeded.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    cbBookmark was zero.

    pBookmark was a null pointer.

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

  • DB_E_BADBOOKMARK
    *pBookmark was invalid, incorrectly formed, or DBBMK_INVALID.

    Note

    Consumers should attempt to use only bookmarks that they have received from the provider. The provider is guaranteed to handle only bookmarks it gives out in a predictable manner. Attempting to use a random value as a bookmark is undefined; the provider might return DB_E_BADBOOKMARK, might return an unexpected row, or might terminate abnormally.

  • 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_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 Appendix C, "OLE DB Properties."

Comments

After using this method, the client uses IRowset::GetNextRows to fetch rows from this new position. This interface is analogous to IRowsetIndex::Seek on integrated indexes in that it merely positions the next fetch position.

If this method fails, the next fetch position is unchanged.

See Also

Reference

IRowsetLocate::GetRowsAt