CeWriteRecordProps (EDB) (Windows Embedded CE 6.0)

1/6/2010

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

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

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

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

See Also

Reference

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