Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
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 dwValueparameter 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 dwValueparameter 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 dwValueparameter specifies the number of records from the current position. The function seeks forward if dwValueis a positive value or backward if it is negative. The function is as efficient seeking backwards as forwards.

To enter negative values, cast dwValueto 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 dwValueparameter 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 dwValueparameter is a pointer to an array of CEPROPVALstructures and wNumValsis the number of CEPROPVALstructures 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 dwValueparameter is a pointer to an array of CEPROPVALstructures, and wNumValsis the number of CEPROPVALstructures 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 dwValueand the wNumValsparameters 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 dwValueparameter is a pointer to an array of CEPROPVALstructures, and wNumValsis the number of CEPROPVALstructures 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 CEPROPVALstructures supplied in dwValue. This value is ignored unless dwSeekTypeis 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 hDatabaseparameter 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, dwSeekTypemust 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 dwSeekTypeis 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 dwValuespecifies an array of CEPROPVALstructures, 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 pSortparameter of the call to the CeOpenDatabaseInSessionfunction.

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, dwValuecan 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 CEPROPVALstructures is required, the propidparameters must be set to the PROPID values of the sort order specified in the CeOpenDatabaseInSessionfunction.

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 GetLastErrorwhen 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 lpdwIndexcauses 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 dwValuewhen 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