Returns hash values for the specified bookmarks.
HRESULT Hash (
HCHAPTER hChapter,
ULONG cBookmarks,
const ULONG rgcbBookmarks[],
const BYTE * rgpBookmarks[],
DWORD rgHashedValues[],
DBROWSTATUS rgBookmarkStatus[]);
Parameters
hChapter
[in]
The chapter handle. For nonchaptered rowsets, hChapter is ignored.
cBookmarks
The number of bookmarks to hash. If cBookmarks is zero, 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. Thus, 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. For information about the DBROWSTATUS enumerated type, see "Arrays of Errors" in Chapter 13.
Return Code
S_OK
The method succeeded. All bookmarks were successfully hashed. The following value can be returned in rgRowStatus:
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:
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 Compare returns DBCOMPARE_EQ for two bookmarks, Hash must return the same value for these two bookmarks.
If 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 the consumer can perform a side-by-side scan of each array to determine which rows were not hashed.
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