Windows apps
Collapse the table of content
Expand the table of content
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

JetPrereadKeys Function


Last modified: March 09, 2015

Applies to: Windows | Windows Server

The JetPrereadKeys function reads key values to improve the performance of version store cleanup.

Windows 7:   PrereadKeys function is introduced in Windows 7.

JET_ERR JET_API JetPrereadKeys(
  __in JET_SESID sesid,
  __in JET_TABLEID tableid,
  __in_ecount(ckeys) const void ** rgpvKeys,
  __in_ecount(ckeys) const unsigned long * rgcbKeys,
  __in long ckeys,
  __out_opt long * pckeysPreread,
  __in JET_GRBIT grbit



The database session context to use for the API call.


The cursor to use for this call.


An array of pointers to keys. Keys can be made with JetMakeKey or retrieved with JetGetBookmark. The keys must be sorted in ascending or descending order, depending on the grbit passed. Keys can be sorted with memcmp.


An array of key lengths. rgpvKeys[n] should point to a key of length rgcbKeys[n]


The number of keys. rgpvKeys and rgcbKeys must each point to an array with at least ckeys elements.


Returns the number of keys that prereads were actually issued for. This parameter can be NULL.


This must be either JET_bitPrereadForward or JET_bitPrereadBackward. If grbit is JET_bitPrereadForward, the keys must be sorted in ascending order. If grbit is JET_bitPrereadBackward, the keys must be sorted in descending order.

Return Value

This function returns the JET_ERR datatype with one of the following return codes. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.

Various I/O errors can be returned along with these API usage errors:

Return code



Grbit was neither JET_bitPrereadForward nor JET_bitPrereadBackward.


An incorrect key size has been passed in. Keys can neither be 0 nor longer than the maximum key length for the table.


An invalid parameter has been passed in. This can be caused by a null value for a required parameter or can indicate that the key array is not sorted properly.

JetPrereadKeys traverses the internal pages of the b-tree to determine which leaf pages contain the keys specified by rgpvKeys/rgcbKeys. The list of leaf pages is sorted and then prereads are issued for the ranges of pages. The number of pages that can be preread is limited so it is possible that not all keys may be preread. In that case, the number of keys actually preread is returned in pckeysPreread.



Requires Windows 7.


Requires Windows Server 2008 R2.


Declared in Esent.h.


Use ESENT.lib.


Requires ESENT.dll.

© 2018 Microsoft