CeSeekDatabaseEx (EDB) (Windows CE 5.0)

  • Article

Send Feedback

This function is used to seek to a specific record in an open database.

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

CEOID CeSeekDatabaseEx(HANDLEhDatabase,DWORDdwSeekType,DWORDdwValue,WORDwNumVals,LPDWORDlpdwIndex);

Parameters

  • hDatabase
    [in] A handle to an open database. The handle must be obtained by calling the CeOpenDatabaseInSession (EDB) function.

  • dwSeekType
    [in] The type of seek operation to perform.

    The following values are supported for this parameter.

    Seek Type Description
    CEDB_SEEK_CEOID Seeks until finding an object that has the specified OID. dwValue specifies the object identifier. This type of seek operation is very efficient.
    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 0. dwValue 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.
    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 0. dwValue is a pointer to an array of CEPROPVAL structures and wNumVals is the number of CEPROPVAL structures in the array.
    CEDB_SEEK_VALUENEXTEQUAL Starting from the current seek position, seeks exactly one position forward in the sort order and checks if 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 0 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. dwValue and wNumVals are ignored.
    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 0. dwValue 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_BEGINNING Seeks from the beginning of the database until finding the record at the specified position. dwValue specifies the number of records to seek from the beginning.
    CEDB_SEEK_CURRENT Seeks backward or forward from the current position of the seek pointer for the specified number of records. dwValue 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.

    Note: To enter negative values, cast dwValue to a signed long. This changes the effective range on the record indexes to 31 bits from 32 bits.
    CEDB_SEEK_END Seeks backward for the specified number of records from the end of the database. dwValue specifies the number of records to seek from the end.
    CEDB_SEEK_PREFIX Allows a prefix to be used when seeking data; it is only used with string and BLOB data types. For example, the prefix "AAA" would match "AAAA" and "AAABC" but not "AA" or "AAB". This type can only be used with a CEVT_LPWSTR type and must also be specified (ORed) 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

  • dwValue
    [in] The value to use for the seek operation. The meaning of this parameter depends on the value of dwSeekType.

  • wNumVals
    [in] The number of CEPROPVAL structures supplied in the dwValue parameter. This value is ignored unless dwSeekType is set to CEDB_SEEK_VALUESMALLER, CEDB_SEEK_VALUESMALLEROREQUAL, CEDB_SEEK_VALUEFIRSTEQUAL, CEDB_SEEK_VALUEGREATER, or CEDB_SEEK_VALUEGREATEROREQUAL.

  • lpdwIndex
    [out] A pointer to a variable that receives the index of the record that was found. This parameter can be NULL.

Return Values

The object identifier of the record on which the seek ends indicates success. Zero indicates failure. To get extended error information, call GetLastError. The following table lists possible values returned by GetLastError:

Return Value Description
ERROR_INVALID_PARAMETER Indicates one or more problems. See "Remarks" later in this topic for more information.
ERROR_INVALID_HANDLE Indicates that hDatabase is NULL or equal to INVALID_HANDLE_VALUE.
ERROR_KEY_DELETED Indicates that CEDB_SEEK_CEOID is used and the OID specifies a deleted row.
ERROR_NOT_ENOUGH_MEMORY Indicates that an attempt to allocate memory failed.
ERROR_SEEK Indicates that the seek operation did not find the specified row.
ERROR_SHARING_VIOLATION Indicates a lock conflict.

Remarks

The ERROR_INVALID_PARAMETER may be returned in the following situations:

  • Problems with 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 then 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.

  • Problems with 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 is used and is greater than the number of properties in the current sort order.

  • lpdwIndex is not NULL and the database was opened without a sort order. Also occurs if a sort order exists that does not support positional access.

This function always uses the current 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 will 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, then 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 to 31 bits from 32 bits.

When a list of CEPROPVAL structures is required to seek, 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 may result in unexpected seek behavior. For more information, see the description of the CeWriteRecordProps (EDB) function.

In general, you cannot join SEEK options with an OR statement. The exception to this is CEDB_SEEK_PREFIX, which must be joined with an OR statement to another valid seek type.

Although EDB allows you to write a NULL value for a property, it is not possible to seek to NULL values.

The following list highlights the differences between this function and the CEDB equivalent function:

  • EDB introduces three new seek types:

    • CEDB_SEEK_VALUESMALLEROREQUAL

      In CEDB, CEDB_SEEK_VALUESMALLER actually 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.

    • CEDB_SEEK_VALUEGREATEROREQUAL

      In CEDB, CEDB_SEEK_VALUEGREATER actually 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_PREFIX

      In EDB, a prefix can be used when performing seeks on string or BLOB data types. For example, the prefix "AAA" would match "AAAA" and "AAABC" but not "AA" or "AAB".

  • 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 what CEDB returns. 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

OS Versions: Windows CE 5.0 and later.
Header: Windbase.h.
Link Library: Coredll.lib.

See Also

CeOpenDatabaseInSession (EDB) | CeWriteRecordProps (EDB) | EDB Schema Support | Comparing EDB with Other Databases

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.