IRowsetScroll::GetApproximatePosition

OLE DB Programmer's Reference

Gets the approximate position of a row corresponding to a specified bookmark.

HRESULT GetApproximatePosition (    HCHAPTER       hChapter,    DBBKMARK       cbBookmark,    const BYTE    *pBookmark,    DBCOUNTITEM   *pulPosition,    DBCOUNTITEM   *pcRows);

Parameters

hChapter: [in]
The chapter handle designating the rows on which to position. For nonchaptered rowsets, the caller must set hChapter to DB_NULL_HCHAPTER. For chaptered rowsets, DB_NULL_HCHAPTER designates the entire rowset.
cbBookmark: [in]
The length in bytes of the bookmark. If this is zero, pBookmark is ignored, *pcRows is set to the count of rows, and no position is returned in *pulPosition.
pBookmark: [in]
A pointer to a bookmark that identifies the row of which to find the position. This can be a pointer to DBBMK_FIRST or DBBMK_LAST. The consumer is not required to have permission to read the row.
pulPosition: [out]
A pointer to memory in which to return the position of the row identified by the bookmark. The returned number is one-based; that is, the first row in the rowset is 1 and the last row is equal to *pcRows. If *pcRows is zero, the provider sets *pulPosition to zero also, regardless of the bookmark that was passed. If pulPosition is a null pointer, no position is returned. In case of error, *pulPosition is not changed.
pcRows: [out]
A pointer to memory in which to return the total number of rows. This number is zero if there are no rows. If pcRows is a null pointer, no count of rows is returned. In case of error, *pcRows is not changed.

Return Code

S_OK: The method succeeded.
E_FAIL: A provider-specific error occurred.
E_INVALIDARG: cbBookmark was not zero, and 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.
*pBookmark did not match any of the rows in the rowset. This includes the case when the row corresponding to the bookmark was deleted and either DBPROP_BOOKMARKSKIPPED was VARIANT_FALSE or the provider is a 1.x provider that does not support getting the approximate position of a deleted row.
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 may return DB_E_BADBOOKMARK, may return an unexpected row, or may 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.

Comments

This method makes no logical change to the state of the object.

There is no guarantee that the row position will be accurate. The provider is expected to choose the fastest possible estimation technique that is not completely in error. *pcRows must be greater than or equal to *pulPosition. The ratio is intended to be useful for scrolling and similar noncritical uses.

See Also