Sets the next fetch position for the rowset to be immediately before the specified bookmark.
HRESULT PositionOnBookmark ( HCHAPTER hChapter, DBBKMARK cbBookmark, const BYTE *pBookmark);
[in] The chapter handle. For nonchaptered rowsets, the caller must set hChapter to DB_NULL_HCHAPTER.
[in] The length in bytes of the bookmark.
[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.
The method succeeded.
A provider-specific error occurred.
cbBookmark was zero.
pBookmark was a null pointer.
*pBookmark was invalid, incorrectly formed, or DBBMK_INVALID.
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.
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.
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.
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."
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.