IRowsetLocate::Hash

OLE DB Programmer's Reference

Returns hash values for the specified bookmarks.

HRESULT Hash (    HCHAPTER       hChapter,    DBBKMARK       cBookmarks,    const DBBKMARK rgcbBookmarks[],    const BYTE    *rgpBookmarks[],    DBHASHVALUE    rgHashedValues[],    DBROWSTATUS    rgBookmarkStatus[]);

Parameters

hChapter: [in]
The chapter handle. hChapter is ignored. For maximum interoperability, consumers should set hChapter to DB_NULL_HCHAPTER.
cBookmarks: The number of bookmarks to hash. If cBookmarks is zero, IRowsetLocate::Hash does not do anything.
rgcbBookmarks: [in]
An array containing the length in bytes for each bookmark.
rgpBookmarks: [in]
An array of pointers to bookmarks. The bookmarks cannot be standard bookmarks (DBBMK_FIRST, DBBMK_LAST, DBBMK_INVALID). If rgpBookmarks contains a duplicate bookmark, a hash value is returned once for each occurrence of the bookmark.
Caution The consumer must ensure that all bookmarks in rgpBookmarks are valid. The provider is not required to validate bookmarks before hashing them. Therefore, hash values might be returned for invalid bookmarks.
rgHashedValues: [out]
An array of cBookmarks hash values corresponding to the elements of rgpBookmarks. The consumer allocates, but is not required to initialize, memory for this array and passes the address of this memory to the provider. The provider returns the hash values in the array.
rgBookmarkStatus: [out]
An array with cBookmarks elements in which to return values indicating the status of each bookmark specified in rgpBookmarks. If no errors occur while hashing a bookmark, the corresponding element of rgBookmarkStatus is set to DBROWSTATUS_S_OK. If an error occurs while hashing a bookmark, the corresponding element is set as specified in DB_S_ERRORSOCCURRED. The consumer allocates memory for this array but is not required to initialize it. If rgBookmarkStatus is a null pointer, no bookmark statuses are returned.

Return Code

S_OK

The method succeeded. All bookmarks were successfully hashed. The following value can be returned in rgRowStatus:

The bookmark was successfully hashed. The corresponding element of rgRowStatus contains DBROWSTATUS_S_OK.

DB_S_ERRORSOCCURRED

An error occurred while hashing a bookmark, but at least one bookmark was successfully hashed. Successes can occur for the reason listed under S_OK. The following errors can occur:

An element of rgpBookmarks pointed to an invalid or incorrectly formed bookmark. The corresponding element of rgBookmarkStatus contains DBROWSTATUS_E_INVALID. Providers are not required to check for this condition, because doing so might slow the method significantly.
An element of rgcbBookmarks was zero. The corresponding element of rgBookmarkStatus contains DBROWSTATUS_E_INVALID.
An element of rgpBookmarks was a null pointer. The corresponding element of rgBookmarkStatus contains DBROWSTATUS_E_INVALID.
An element of rgpBookmarks pointed to a standard bookmark (DBBMK_FIRST, DBBMK_LAST, DBBMK_INVALID). The corresponding element of rgBookmarkStatus contains DBROWSTATUS_E_INVALID.
The consumer encountered a recoverable, provider-specific error, such as an RPC failure when transmitting the change to a remote server. The corresponding element of rgRowStatus contains DBROWSTATUS_E_FAIL.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

cBookmarks was not zero, and rgcbBookmarks or rgpBookmarks was a null pointer.

rgHashedValues was a null pointer.

E_UNEXPECTED

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

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_ERRORSOCCURRED

Errors occurred while hashing all of the bookmarks. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED.

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 two bookmarks point to the same underlying row, the same hash value is returned for both bookmarks. That is, if IRowsetLocate::Compare returns DBCOMPARE_EQ for two bookmarks, IRowsetLocate::Hash must return the same value for these two bookmarks.

If IRowsetLocate::Hash encounters an error while attempting to hash a bookmark, such as a bad bookmark, it notes the error in the error array, continues processing, and returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED. Although the rows are hashed in undefined order, the ordering of the error array must match the order of the bookmark array so that the consumer can perform a side-by-side scan of each array to determine which rows were not hashed.

IRowsetLocate::Hash can hash any valid bookmarks. The consumer is not required to have permission to read the corresponding row, nor is the row even required to exist—for example, it might have been deleted.

Standard bookmarks cannot be hashed.

See Also