CeSeekDatabaseEx (EDB) (Windows Embedded CE 6.0)

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

• 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.

Remarks

The ERROR_INVALID_PARAMETER is returned in the situations shown in the following table.

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.

• 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

See Also

Reference

EDB Functions
CeOpenDatabaseInSession (EDB)
CeWriteRecordProps (EDB)

Concepts

EDB Schema Support
Comparing EDB with Other Databases