IRowsetIndex::Seek

OLE DB Programmer's Reference

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

HRESULT Seek (    HACCESSOR   hAccessor,    DBORDINAL   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, 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, 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), IRowsetIndex::Seek does not change the next fetch position.

cKeyValues

[in]
The number of bindings in hAccessor for which *pData contains valid data. IRowsetIndex::Seek 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. IRowsetIndex::Seek 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 IRowsetIndex::Seek method. The values in DBSEEKENUM have the meanings described in the following table.

Value	Description
DBSEEK_FIRSTEQ	First key with values equal to the values in *pData, in index order.
DBSEEK_LASTEQ	Last key with values equal to the values in *pData.
DBSEEK_AFTEREQ	Last key with values equal to the values in *pData or, if there are no keys equal to the values in *pData, first key with values after the values in *pData, in index order.
DBSEEK_AFTER	First key with values following the values in *pData, in index order.
DBSEEK_BEFOREEQ	First key with values equal to the values in *pData or, if there are no keys equal to the values in *pData, last key with values before the values in *pData, in index order.
DBSEEK_BEFORE	Last key with values before the values in *pData, in index order.

dwSeekOptions examples

The following table shows the expected results when given the columns and index value for the DBSEEK predicates above.

Col 1	Col 2	Col 3	With index setting of	Predicate	Result
0 1 2 3			index = col1 asc	BEFORE (2) BEFOREEQ (2)	(1) (2)
1 2 2 3	1 2 3 4		index = (col1 asc)	BEFOREEQ (2) AFTEREQ (2)	(2,2) (2,3)
1 3 3 4	4 3 3 1	0 1 2 3	index = (col1 asc, col2 desc)	BEFOREEQ (3,3) AFTEREQ (3,3)	(3,3,1) (3,3,2)

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 or was greater than the number of bindings specified in hAccessor.

pData was a null pointer.

DB_E_BADACCESSORHANDLE

hAccessor was invalid.

DB_E_BADACCESSORTYPE

The specified accessor was not a row accessor. Some providers may return DB_E_BADACCESSORHANDLE instead of this error code when command accessors are passed to the rowset.

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: Getting and Setting Data.

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.

DB_E_ROWSNOTRELEASED

The provider requires release of existing rows before new ones can be fetched. For more information, see DBPROP_CANHOLDROWS in Appendix C: OLE DB Properties.

Comments

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

The IRowsetIndex::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 IRowsetIndex::Seek transfers data from *pData, see "Setting Data" in Chapter 6: Getting and Setting Data.

See Also