Gets the approximate position of a row corresponding to a specified bookmark.
HRESULT GetApproximatePosition (
HCHAPTER hChapter,
ULONG cbBookmark,
const BYTE * pBookmark,
ULONG * pulPosition,
ULONG * pcRows);
Parameters
hChapter
[in]
The chapter handle. For nonchaptered rowsets, hChapter is ignored.
cbBookmark
[in]
The length in bytes of the bookmark. If this is zero, then 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 DBPROP_BOOKMARKSKIPPED was either 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 only attempt to use bookmarks that they have received from the provider. The provider is guaranteed only to handle 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