Share via

CeSeekDatabaseEx

  • Article

This function seeks the specified record in an open database.

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

Parameters

  • hDatabase
    [in] Handle to the open database in which to seek the record.

  • dwSeekType
    [in] Type of seek operation to perform. The following table shows possible values for dwSeekType.

    Value Description
    CEDB_SEEK_CEOID Seeks until finding an object that has the specified object identifier. The dwValue parameter specifies the object identifier. This type of seek operation is very efficient.
    CEDB_SEEK_VALUESMALLER Starting from the current position, seeks backward toward the start of the sort. Always seeks backward, regardless of sort order. In ascending order, this finds the largest value smaller than or equal to the specified value; in descending order, this finds the smallest value larger than or equal to 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. wNumVals is the number of CEPROPVAL structures in the array.
    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. 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 sorted order and checks if the next record is equal in value to the specified value. If so, returns the object identifier of this next record; otherwise, returns zero and leaves the seek pointer at the end of the database. You can use this operation in conjunction with the CEDB_SEEK_VALUEFIRSTEQUAL operation to enumerate all records with an equal value. The dwValue parameter is a pointer to an array of CEPROPVAL structures. wNumVals is the number of CEPROPVAL structures in the array.
    CEDB_SEEK_VALUEGREATER Starting from the current position, seeks backward toward the start of the sort. Always seeks forward, regardless of sort order. In ascending order, this finds the smallest value greater than or equal to the specified value; in descending order, this finds the largest value smaller than or equal to 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. wNumVals is the number of CEPROPVAL structures in the array.
    CEDB_SEEK_BEGINNING Seeks until finding the record at the specified position from the beginning of the database. The dwValue parameter 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. The dwValue parameter specifies the number of records to seek from the current position. The function seeks forward if dwValue is a positive value or backward if it is negative.
    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.

  • dwValue
    [in] Value to use for the seek operation. The meaning of this parameter depends on the value of dwSeekType. It may be a CEOID, a DWORD counter, or a pointer to an array of CEPROPVAL structures.

  • wNumVals
    [in] Number of CEPROPVAL structures supplied in the dwValue parameter.

    This value is ignored unless dwSeekType is CEDB_SEEK_VALUESMALLER, CEDB_SEEK_VALUEGREATER, or CEDB_SEEK_VALUEFIRSTEQUAL

  • lpdwIndex
    [out] Pointer to a variable that receives the index from the start of the database to the beginning of the record that was found. This parameter can be NULL. Passing a non-NULL value for lpdwIndex will cause the call to be slower and should be avoided whenever possible.

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. GetLastError may return ERROR_INVALID_PARAMETER if a parameter is invalid.

Remarks

The CeSeekDatabaseEx function always uses the current sort order as specified in the call to the CeOpenDatabaseEx2 function. If the CEDB_AUTOINCREMENT flag was specified, an automatic seek of one from the current position is done with each read operation that occurs on the database. If a seek fails, the record pointer points to the same record as before the seek operation.

Note that a seek can only be performed on a sorted property value. After creating a database (using CeCreateDatabaseEx2) and opening the database (using CeOpenDatabaseEx2), subsequent calls to CeSeekDatabaseEx assume the sort order that was specified in the propid parameter of the call to CeOpenDatabaseEx.

To enter negative values for the CEDB_SEEK_CURRENT case, cast 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 CeOpenDatabaseEx2 call.

Using CeWriteRecordProps in conjunction with CeSeekDatabaseEx may result in unexpected seek behavior. See description of CeWriteRecordProps for more details.

Requirements

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

See Also

CeCreateDatabaseEx2 | CeOpenDatabaseEx2 | CEPROPVAL | CeWriteRecordProps

 Last updated on Friday, April 09, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.