Share via

CeSeekDatabaseEx (EDB) (Windows Embedded CE 6.0)

  • Article

1/6/2010

This function seekd to a specified record in an open database.

This function does not work with CEDB databases. For more information about CEDB, see CEDB Reference.

Syntax

CEOID CeSeekDatabaseEx(
  HANDLE hDatabase,
  DWORD dwSeekType,
  DWORD dwValue,
  WORD wNumVals,
  LPDWORD lpdwIndex
);

Parameters

  • 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
  • It is not set to a valid seek type value.
  • It is set to CEDB_SEEK_VALUENEXTEQUAL and is specified without a previous call to this function using CEDB_SEEK_VALUEFIRSTEQUAL. These seek types must be matched and used together.
  • If the property includes CEDB_SEEK_PREFIX, dwSeekType must also be specified with one of the following:
    • CEDB_SEEK_VALUEFIRSTEQUAL
    • CEDB_SEEK_VALUESMALLER
    • CEDB_SEEK_VALUEGREATER
    • CEDB_SEEK_VALUESMALLEROREQUAL
    • CEDB_SEEK_VALUEGREATEROREQUAL
  • The database was opened without a specified sort order, and dwSeekType is a value other than the following:
    • CEDB_SEEK_CEOID
    • CEDB_SEEK_BEGINNING
    • CEDB_SEEK_CURRENT
    • CEDB_SEEK_END
    All other seek types require the use of a sort order.

dwValue
  • It is NULL and the specified seek type requires a value for this parameter.
  • If dwValue specifies an array of CEPROPVAL structures, the following conditions are checked:
    • The order of the property IDs in the array must match the order of the properties in the current sort order of the database.
    • The CEVT_xxx type stored in a property ID must be a valid CEDB data type and must match the data type of the corresponding property in the current sort order.

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

See Also

Reference

EDB Functions
CeOpenDatabaseInSession (EDB)
CeWriteRecordProps (EDB)

Concepts

EDB Schema Support
Comparing EDB with Other Databases