IRowsetBookmark::PositionOnBookmark

OLE DB Programmer's Reference

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

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