Share via

CeWriteRecordProps (EDB)

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function either inserts a new record or updates the properties of an existing record.

Syntax

CEOID CeWriteRecordProps(
  HANDLE hDatabase,
  CEOID oidRecord,
  WORD cPropID,
  CEPROPVAL* prgPropVal
);

Parameters

  • hDatabase
    [in] Handle to the database in which to insert or update the record. The database is opened with the CeOpenDatabaseInSession (EDB) function.
  • oidRecord
    [in] Object identifier (OID) of the record to which the specified properties are written. If this parameter is set to zero, a new record is created and filled with the specified properties.
  • cPropID
    [in] Number of properties in the array specified by the prgPropVal ** parameter. This parameter cannot be set to zero.
  • prgPropVal
    [in] Pointer to an array of CEPROPVAL structures that specifies the property values to be written to the specified record.

Return Value

The OID of the record to which the properties were written indicates success. Zero indicates failure. To get extended error information, call GetLastError. The following table shows possible values.

Return Value Description

ERROR_ACCESS_DENIED

Indicates one of the following:

  • A property was added with DB_PROP_NOTNULL set and NULL is set as the value for that property, or you tried to delete that property.
  • The database has sort orders that have the CEDB_SORT_NONNULL flag, and one of the corresponding properties in the updated or inserted record is set to NULL or was deleted.

ERROR_ALREADY_EXISTS

The database has sort orders that have the CEDB_SORT_UNIQUE flag, and the record being updated or inserted generates a key that is a duplicate of another key in the sort order.

ERROR_BAD_LENGTH

The data that is to be written exceeds the maximum record size.

ERROR_DISK_FULL

The flush was called when the disk was full. This function caches all data until a flush operation occurs explicitly or implicitly.

ERROR_INSUFFICIENT_BUFFER

An odd number of bytes were written when using CEVT_LPWSTR.

ERROR_INVALID_HANDLE

The hDatabase parameter is set to NULL or equal to INVALID_HANDLE_VALUE.

ERROR_INVALID_PARAMETER

Indicates one of the following invalid parameters:

  • A CEVT_FILETIME value in the CEPROPVAL structure is set to zero.
  • The oidRecord parameter is set to NULL or invalid.
  • The cPropID parameter is set to zero, or prgPropVal is set to NULL.
  • A property ID specified in the prgPropVal array does not exist in the current database property set. You must specify the properties when creating a database or use the CeAddDatabaseProps (EDB) function after a database is created. The one exception is if the database is empty, that is, contains no data, although it may have properties. In this case, this function adds those properties.

ERROR_NOT_FOUND

Indicates one of the following:

  • The record specified by oidRecord does not exist.
  • The database for which the handle was obtained has been unmounted.

ERROR_SHARING_VIOLATION

Indicates a lock conflict.

Remarks

Write operations are cached until a flush operation occurs. The flush occurs either after the flush interval has elapsed or when you call the CeFlushDBVol (EDB) function.

This function leaves the seek pointer on the record that is written to. However, the position of that record in the sort order may change if its sort properties are included in those properties that are modified. Therefore, using this function in conjunction with the CeSeekDatabaseEx (EDB) function may result in unexpected seek behavior.

To delete a property value, that is, to set the value to NULL, set the CEDB_PROPDELETE flag for the appropriate property value. This allows multiple deletes and changes in a single call, which is much more efficient than multiple calls.

No memory is freed by the caller. Pointers in the CEPROPVAL structures can be anywhere in the caller's address space. They can be marshaled, as in the array returned by the CeReadRecordPropsEx (EDB) function, or they can be independently allocated.

When writing strings with CEVT_LPWSTR, write an even number of bytes. Otherwise, GetLastError returns ERROR_INSUFFICIENT_BUFFER.

The following are the differences between this function and the CEDB equivalent function:

  • To write properties, you must first have added the property ID to the database with the CeAddDatabaseProps (EDB) function. The one exception to this is if the database is empty of data, although it may have properties. In this case, the record is written, and the properties passed in with prgPropVal are added as properties to the database. If properties are added to the database, the relevant errors added with CeAddDatabaseProps are propagated.
  • If CEDB_SORT_UNIQUE is used, an insertion that does not specify all the properties can still succeed, with NULL being inserted for the properties that were not specified. To determine uniqueness, NULL is treated as though it were a value. Only one NULL value is permitted. In CEDB, a unique constraint requires that all properties be written.

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

Reference

EDB Functions
CeOpenDatabaseInSession (EDB)
CeAddDatabaseProps (EDB)
CeFlushDBVol (EDB)