JetRetrieveKey Function

Applies to: Windows | Windows Server

JetRetrieveKey Function

The JetRetrieveKey function retrieves the key for the index entry at the current position of a cursor. Such keys are constructed by calls to JetMakeKey. The retrieved key can then be used to efficiently return that cursor to the same index entry by a call to JetSeek.

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit
    );

Parameters

sesid

The session to use for this call.

tableid

The cursor to use for this call.

pvData

The output buffer that will receive the key.

cbMax

The maximum size in bytes of the output buffer.

pcbActual

Receives the actual size in bytes of the key.

If this parameter is NULL then the actual size of the key will not be returned.

If the output buffer is too small, then the actual size of the key will still be returned. That means that this number will be larger than the size of the output buffer.

grbit

A group of bits that contain the options to be used for this call, which include zero or more of the following.

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.

On success, the key for the index entry at the current position of a cursor will be returned in the output buffer. If JET_wrnBufferTruncated is returned then the output buffer will contain as much of the key as will fit in the space provided and the actual size of the key will be accurate. No change to the database state will occur.

On failure, the state of the output buffer and the actual size of the key will be undefined. No change to the database state will occur.

Remarks

Keys should generally be treated as opaque chunks of data. No attempt should be made to exploit the internal structure of this data. However, the following properties can be known about all ESENT keys:

• Keys may be compared against each other using memcmp function to establish their relative ordering in the originating index over the table of the source index entries.

• It is meaningless to compare keys of index entries from different indexes against each other.

• A key is always less than or equal to JET_cbKeyMost (255) bytes in length prior to Windows Vista. On Windows Vista and later releases, keys can be larger. The maximum size of a key is equal to the current value of JET_paramKeyMost.

In addition to the above properties of ESENT keys in general, it is important to note that a search key is different from the key for an index entry. Specifically, a search key may be longer than an ordinary key. This extra length occurs when a wildcard option is used while constructing the search key. See JetMakeKey for more information.

There is an important bug in this API that is present in all releases. If the search key is requested using the use of JET_bitRetrieveCopy and the output buffer is too small to receive the entire key then JET_wrnBufferTruncated will NOT be returned. JET_errSuccess will be returned instead. It is important to verify that the actual size of the key as returned using pcbActual is less than or equal to the size of the output buffer. If the actual size is larger than the size of the output buffer, then the caller of JetRetrieveKey should react as if JET_wrnBufferTruncated were returned instead.

Requirements

See Also

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetSeek
JetSetIndexRange