CeWriteRecordProps

  • Article

This function writes a set of properties to a single record, creating the record if necessary.

A RAPI version of this function exists called CeWriteRecordProps (RAPI).

CEOID CeWriteRecordProps(
  HANDLE hDbase, 
  CEOID oidRecord, 
  WORD cPropID, 
  CEPROPVAL* rgPropVal
);

Parameters

  • hDbase
    [in] Handle to an open database. The database must have been opened by a previous call to the CeOpenDatabase function.
  • oidRecord
    [in] Object identifier of the record to which the specified properties are to be written. If this parameter is zero, a new record is created and filled in with the specified properties.
  • cPropID
    [in] Number of properties in the array specified by the rgPropVal parameter. The cPropID parameter must not be zero.
  • rgPropVal
    [in] Pointer to an array of CEPROPVAL structures that specify the property values to be written to the specified record.

Return Values

The object identifier 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 return values for GetLastError.

Value Description
ERROR_DISK_FULL Indicates that theres was not enough space in the object store to write the properties.
ERROR_INVALID_PARAMETER Indicates that a parameter was invalid.

Remarks

The CeWriteRecordProps function writes all the requested properties into the specified record. CeWriteRecordProps 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 modified. Therefore, using CeWriteRecordProps in conjunction with CeSeekDatabaseEx may result in unexpected seek behavior.

To delete a property, set the CEDB_PROPDELETE flag in 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 CeReadRecordProps, or they can be independently allocated.

For Windows CE versions 2.10 and later, on a mounted database volume, all write operations are cached. The database subsystem periodically requests a cache flush after a series of operations. If memory is low, the cache is flushed to permanent storage. Unlike a file system that can choose to flush only part of the cache, on a database, all blocks are flushed.

If this API is called by a replication synchronization client thread, the sync flags will determine its behavior. If the client has set the REPL_SYNC_ALLOWOVERWRITE flag, the call will proceed normally. If the REPL_SYNC_ALLOWOVERWRITE flag is not set, the call may fail with ERROR_ACCESS_DENIED, to block the synchronization client from overwriting changes it has not yet read. See the ReplOpenSync and ReplChangeSyncSettings APIs for more details.

Requirements

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

See Also

CeOpenDatabaseEx2 | CeReadRecordPropsEx | CEPROPVAL | ReplOpenSync | ReplChangeSyncSettings

 Last updated on Friday, April 09, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.