IRowsetIndex::Seek

Allows direct positioning at a key value within the current range established by the IRowsetIndex::SetRange method.

HRESULT Seek (
   HACCESSOR   hAccessor,
   ULONG         cKeyValues,
   void *            pData,
   DBSEEK         dwSeekOptions);

Parameters

hAccessor

[in]
The handle of the accessor to use. This accessor must meet the following criteria, which are illustrated with a key that consists of columns A, B, and C, where A is the most significant column and C is the least significant column:

For each key column this accessor binds, it must also bind all more significant key columns. For example, the accessor can bind column A, columns A and B, or columns A, B, and C.
Key columns must be bound in order from most significant key column to least significant key column. For example, if the accessor binds columns A and B, then the first binding must bind column A and the second binding must bind column B.
If the accessor binds any non-key columns, key columns must be bound first. For example, if the accessor binds columns A, B, and the bookmark column, then the first binding must bind column A, the second binding must bind column B, and the third binding must bind the bookmark column.
If the accessor does not meet these criteria, the method returns DB_E_BADBINDINFO or a status of DBSTATUS_E_BADACCESSOR for the offending column.
If hAccessor is the handle of a null accessor (cBindings in IAccessor::CreateAccessor was zero), then Seek does not change the next fetch position.

cKeyValues

[in]
The number of bindings in hAccessor for which *pData contains valid data. SetRange retrieves data from the first cKeyValues key columns from *pData. For example, suppose the accessor binds columns A, B, and C of the key in the previous example and cKeyValues is 2. SetRange retrieves data for columns A
and B.

pData

[in]
A pointer to a buffer containing the key values to which to seek, at offsets that correspond to the bindings in the accessor.

dwSeekOptions

[in]
A bitmask describing the options for the Seek method. The values in DBSEEKENUM have the following meanings:

Value	Description
DBSEEK_FIRSTEQ	First key with values equal to the values in *pData.
DBSEEK_LASTEQ	Last key with values equal to the values in *pData.
DBSEEK_GE	First key with values greater than or equal to the values in *pData.
DBSEEK_GT	First key with values greater than the values in *pData.
DBSEEK_LE	First key with values less than or equal to the values in *pData.
DBSEEK_LT	First key with values less than the values in *pData.

Return Code

S_OK
The method succeeded.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
dwSeekOptions was invalid.

hAccessor was the handle of a null accessor.

cKeyValues was zero.

pData was a null pointer.

DB_E_BADACCESSORHANDLE
hAccessor was invalid.

DB_E_BADACCESSORTYPE
The specified accessor was not a row accessor.

DB_E_ERRORSOCCURRED
An error occurred while transferring data for one or more key columns. To determine the columns for which values were invalid, the consumer checks the status values. For a list of status values that can be returned by this method, see "Status Values Used When Setting Data" in "Status" in Chapter 6.

DB_E_NOINDEX
The rowset uses integrated indexes and there is no current index.

DB_E_NOTFOUND
No key value matching the described characteristics could be found within the current range.

DB_E_NOTREENTRANT
The consumer called this method while it was processing a notification, and it is an error to call this method while processing the specified DBREASON value.

If this method performs deferred accessor validation and that validation takes place before any data is transferred, it can also return any of the following return codes for the reasons listed in the corresponding DBBINDSTATUS values in IAccessor::CreateAccessor:

E_NOINTERFACE
DB_E_BADBINDINFO
DB_E_BADORDINAL
DB_E_BADSTORAGEFLAGS
DB_E_UNSUPPORTEDCONVERSION

Comments

The Seek method provides the caller more control over the traversal of an index. Consider a relational query processor component implementing a merge join over inputs R1 and R2. R1, the outer input, is a rowset ordered by the joining column R1.X. R2, the inner input, is an indexed rowset on column R2.X. Suppose that R1.X has values {10, 20, 100, 110} and that R2.X has values {10, 20, ..., 30, ..., 40, ..., 50, ..., 100, ...}, then when searching R2.X, one could seek directly from 20 to 100 knowing the values of the input R1.X. In some cases, this strategy could be cost effective.

For information about how Seek transfers data from *pData, see "Setting Data" in Chapter 6.