IRowsetIndex::Seek
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.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.