CeSeekDatabaseEx (EDB)
A version of this page is also available for
4/8/2010
This function seekd to a specified record in an open database.
Syntax
CEOID CeSeekDatabaseEx(
HANDLE hDatabase,
DWORD dwSeekType,
DWORD dwValue,
WORD wNumVals,
LPDWORD lpdwIndex
);
Parameters
- hDatabase
[in] Handle to an open database. The handle must be obtained with the CeOpenDatabaseInSession (EDB) function.
dwSeekType
[in] Type of seek operation to perform. The following table shows possible values.Seek Type Description CEDB_SEEK_BEGINNING
Seeks from the beginning of the database until finding the record at the specified position. The dwValue parameter specifies the number of records to seek from the beginning.
CEDB_SEEK_CEOID
Seeks until finding an object that has the specified object identifier (OID). The dwValue parameter specifies the OID. This type of seek operation is very efficient.
CEDB_SEEK_CURRENT
Seeks backward or forward from the current position of the seek pointer for the specified number of records. The dwValue parameter specifies the number of records from the current position. The function seeks forward if dwValue is a positive value or backward if it is negative. The function is as efficient seeking backwards as forwards.
To enter negative values, cast dwValue to a signed long. This changes the effective range on the record indexes from 32 bits to 31 bits.
CEDB_SEEK_END
Seeks backward for the specified number of records from the end of the database. The dwValue parameter specifies the number of records to seek from the end.
CEDB_SEEK_PREFIX
Enables a prefix to be used when seeking data, only with string and binary large object (BLOB) data types. This type can be used only with a CEVT_LPWSTR type and must also be specified with a logical OR operation with one of the following seek types:
CEDB_SEEK_VALUEFIRSTEQUAL
CEDB_SEEK_VALUESMALLER
CEDB_SEEK_VALUEGREATER
CEDB_SEEK_VALUESMALLEROREQUAL
CEDB_SEEK_VALUEGREATEROREQUAL
Prefix matching ignores case and uses the following flags:
NORM_IGNORECASE
NORM_IGNORENONSPACE
NORM_IGNOREKANATYPE
NORM_IGNOREWIDTH
CEDB_SEEK_VALUEFIRSTEQUAL
Begins at the start of the sort and seeks forward until finding the first value that is equal to the specified value. Always seeks forward, regardless of sort order. If the seek operation fails, the seek pointer is left at the end of the database and the function returns zero. The dwValue parameter is a pointer to an array of CEPROPVAL structures and wNumVals is the number of CEPROPVAL structures in the array.
CEDB_SEEK_VALUEGREATER
Seeks forward toward the end of the sort until finding the first value that is not equal to the specified value. Always seeks forward, regardless of sort order. In ascending order, this finds the smallest value greater than the specified value. In descending order, this finds the largest value smaller than the specified value. If none of the following records has a value that meets the search criteria, the seek pointer is left at the end of the database, and the function returns zero. The dwValue parameter is a pointer to an array of CEPROPVAL structures, and wNumVals is the number of CEPROPVAL structures in the array.
CEDB_SEEK_VALUEGREATEROREQUAL
Similar to CEDB_SEEK_VALUEGREATER, but this type also matches values equal to the specified value.
CEDB_SEEK_VALUENEXTEQUAL
Starting from the current seek position, seeks exactly one position forward in the sort order, and checks whether this next record is equal in value to the specified value. If so, it returns the object identifier of this next record. Otherwise, it returns zero, and leaves the seek pointer at the end of the database. This operation can be used in conjunction with the CEDB_SEEK_VALUEFIRSTEQUAL operation to enumerate all records with an equal value. The dwValue and the wNumVals parameters are ignored.
CEDB_SEEK_VALUESMALLER
Seeks backward toward the start of the sort until finding the first value that is not equal to the specified value. Always seeks backward, regardless of sort order. In ascending order, this finds the largest value smaller than the specified value. In descending order, this finds the smallest value larger than the specified value.
If none of the previous records has a value that meets the search criteria, the seek pointer is left at the end of the database, and the function returns zero. The dwValue parameter is a pointer to an array of CEPROPVAL structures, and wNumVals is the number of CEPROPVAL structures in the array.
CEDB_SEEK_VALUESMALLEROREQUAL
Similar to CEDB_SEEK_VALUESMALLER, but this type also matches values equal to the specified value.
- dwValue
[in] Value to use for the seek operation. The meaning of this parameter depends on the value of dwSeekType.
wNumVals
[in] Number of CEPROPVAL structures supplied in dwValue. This value is ignored unless dwSeekType is set to on of the following:CEDB_SEEK_VALUESMALLER
CEDB_SEEK_VALUESMALLEROREQUAL
CEDB_SEEK_VALUEFIRSTEQUAL
CEDB_SEEK_VALUEGREATER
CEDB_SEEK_VALUEGREATEROREQUAL
- lpdwIndex
[out] Pointer to a variable that receives the index of the record that was found. This parameter can be set to NULL.
Return Value
The OID of the record on which the seek ends indicates success. Zero indicates failure. To get extended error information, call GetLastError. The following table shows possible values.
| Return Value | Description |
|---|---|
ERROR_INVALID_HANDLE |
The hDatabase parameter is set to NULL or equal to INVALID_HANDLE_VALUE. |
ERROR_INVALID_PARAMETER |
One or more or the parameters are invalid. |
ERROR_KEY_DELETED |
CEDB_SEEK_CEOID is set, and the OID specifies a deleted row. |
ERROR_NOT_ENOUGH_MEMORY |
An attempt to allocate memory failed. |
ERROR_SEEK |
The seek operation did not find the specified row. |
ERROR_SHARING_VIOLATION |
Another thread has the database locked. |
Remarks
The ERROR_INVALID_PARAMETER is returned in the situations shown in the following table.
| Parameter | Issues |
|---|---|
dwSeekType |
|
dwValue |
|
wNumVals |
This parameter is used and is greater than the number of properties in the current sort order. |
lpdwIndex |
This parameter is not set to NULL, and the database was opened without a sort order. This also occurs if a sort order exists that does not support positional access. |
This function always uses the sort order that was specified in the call to the CeOpenDatabaseInSession (EDB) function. If the CEDB_AUTOINCREMENT flag was specified, an automatic seek of one position from the current position is done with each read operation. If a seek fails, the record pointer returns to the same record as before the seek operation.
A seek is typically performed on a sorted property value. After creating and opening the database, subsequent calls to this function use the sort order that was specified in the pSort parameter of the call to the CeOpenDatabaseInSession function.
If no sort order, or one without positional access, is specified when opening the database, only the following seek options are supported:
CEDB_SEEK_CEOID
CEDB_SEEK_BEGINNING
CEDB_SEEK_CURRENT
CEDB_SEEK_END
To use negative values with CEDB_SEEK_CURRENT, dwValue can be cast to a signed long. This changes the effective range on the record indexes from 32 bits to 31 bits.
When a list of CEPROPVAL structures is required, the propid parameters must be set to the PROPID values of the sort order specified in the CeOpenDatabaseInSession function.
Using the CeWriteRecordProps (EDB) function in conjunction with this function can result in unexpected seek behavior. For more information, see the reference topic for CeWriteRecordProps.
In general, you cannot join seek options with an OR statement. The exception is CEDB_SEEK_PREFIX, which must be joined with an OR statement to another valid seek type.
Although EDB enables you to write a NULL value for a property, it is not possible to seek to NULL values.
The following are the differences between this function and the CEDB equivalent function:
- EDB introduces the new seek types shown in the following table.
| Type | Description |
|---|---|
CEDB_SEEK_PREFIX |
In EDB, a prefix can be used when performing seeks on string or BLOB data types. |
CEDB_SEEK_VALUEGREATEROREQUAL |
In CEDB, CEDB_SEEK_VALUEGREATER seeks to the first value greater than or equal to the value passed in. To achieve this behavior in EDB, CEDB_SEEK_VALUEGREATEROREQUAL must be used. For the seek type CEDB_SEEK_VALUEGREATER, EDB seeks to the first value greater than the value passed in. |
CEDB_SEEK_VALUESMALLEROREQUAL |
In CEDB, CEDB_SEEK_VALUESMALLER seeks to the first value smaller than or equal to the value passed in. To achieve this behavior in EDB, CEDB_SEEK_VALUESMALLEROREQUAL must be used. For the seek type CEDB_SEEK_VALUESMALLER, EDB seeks to the first value smaller than the value passed in. |
- EDB supports returning an index position if the seek type is CEDB_SEEK_CEOID, but only if the sort order allows positional access.
- In EDB, seeks are supported if the database is opened without a sort order. This is not possible in CEDB because CEDB selects a default sort order when the database is opened.
- EDB returns different error codes for GetLastError when a failure occurs. These error codes are more descriptive than those for CEDB. For example, when there are no more rows to be found, EDB returns ERROR_NO_MORE_ITEMS, whereas CEDB returns the generic error of ERROR_SEEK.
- When working with CEDB, passing a non-NULL value for lpdwIndex causes the call to be slower and should be avoided. In EDB, NULL and non-NULL values are equally efficient.
- In CEDB, you must pass a value for dwValue when using CEDB_SEEK_VALUENEXTEQUAL. EDB does not require a value, and if one is supplied, EDB ignores it.
Requirements
| Header | windbase.h |
| Library | coredll.lib |
| Windows Embedded CE | Windows CE 5.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
See Also
Reference
EDB Functions
CeOpenDatabaseInSession (EDB)
CeWriteRecordProps (EDB)