IRowsetLocate::Compare

Compares two bookmarks.

HRESULT Compare (
   HCHAPTER         hChapter,
   ULONG            cbBookmark1,
   const BYTE *         pBookmark1,
   ULONG            cbBookmark2,
   const BYTE *         pBookmark2,
   DBCOMPARE *   pComparison);

Parameters

hChapter

[in]
The chapter handle. For nonchaptered rowsets, hChapter is ignored.

cbBookmark1

[in]
The length in bytes of the first bookmark.

pBookmark1

[in]
A pointer to the first bookmark. This can be a pointer to DBBMK_FIRST or DBBMK_LAST.

cbBookmark2

[in]
The length in bytes of the second bookmark.

pBookmark2

[in]
A pointer to the second bookmark. This can be a pointer to DBBMK_FIRST or DBBMK_LAST.

pComparison

[out]
A pointer to memory in which to return a flag that specifies the result of the comparison. The returned flag will be one of the following values.

Value	Description
DBCOMPARE_LT	The first bookmark is before the second.
DBCOMPARE_EQ	The two bookmarks are equal.
DBCOMPARE_GT	The first bookmark is after the second.
DBCOMPARE_NE	The bookmarks are not equal and not ordered.
DBCOMPARE_NOTCOMPARABLE	The two bookmarks cannot be compared.

Return Code

S_OK
The method succeeded.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
cbBookmark1 or cbBookmark2 was zero.

pBookmark1, pBookmark2, or pComparison was a null pointer.

E_UNEXPECTED
ITransaction::Commit or ITransaction::Abort was called and the object is in a zombie state.

DB_E_BADBOOKMARK
*pBookmark1 or *pBookmark2 was invalid, incorrectly formed, or DBBMK_INVALID.

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.

If bookmarks are ordered, they can be compared to determine the relative position of their associated rows in the rowset. The DBPROP_ORDEREDBOOKMARKS property indicates whether bookmarks are ordered. If bookmarks are not ordered, then the returned comparison value will be DBCOMPARE_EQ or DBCOMPARE_NE. If bookmarks are ordered, then the returned comparison value will be DBCOMPARE_LT, DBCOMPARE_EQ, or DBCOMPARE_GT. The command that creates the rowset does not have to have an ordered text command, such as an SQL statement containing an ORDER BY clause, to have ordered bookmarks.

Compare can compare any valid bookmarks. The consumer is not required to have permission to read the corresponding rows, nor are the rows even required to exist — for example, they might have been deleted.

If the DBPROP_LITERALBOOKMARKS property is VARIANT_TRUE, then consumers can directly compare values.

Specifying the bookmark DBBMK_FIRST or DBBMK_LAST returns DBCOMPARE_EQ when compared with itself and DBCOMPARE_NE when compared with any other bookmark.