IRowsetBookmark::PositionOnBookmark

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

IRowsetLocate::GetRowsAt