IRowsetLocate::Compare

OLE DB Programmer's Reference

Compares two bookmarks.

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

Parameters

hChapter

[in]
The chapter handle. For nonchaptered rowsets or to designate the root rowset, the caller must set hChapter to DB_NULL_HCHAPTER.

When comparing literal bookmarks and hChapter is DB_NULL_HCHAPTER, IRowsetLocate::Compare must return the same ordering as an arithmetic comparison. If hChapter is not DB_NULL_HCHAPTER, IRowsetLocate::Compare must reflect the ordering within that chapter. Also, the row designated by the special bookmarks DBBMK_FIRST or DBBMK_LAST depends on the chapter.

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 values in the following table.

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. When to return DBCOMPARE_NOTCOMPARABLE: When calling IRowsetLocate::Compare, the consumer passed a bookmark for a row that does not belong to the chapter designated by hChapter. This bookmark could have been handed out on the base rowset or on another chapter for this rowset. The provider supports key value bookmarks, and one of the bookmarks passed to IRowsetLocate::Compare is now disassociated from the row due to a prior update of a key value.

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 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.

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, the returned comparison value will be DBCOMPARE_EQ or DBCOMPARE_NE. If bookmarks are ordered, 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.

IRowsetLocate::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, 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.

See Also