CeWriteRecordProps (EDB) (Windows CE 5.0)

  • Artikel

Send Feedback

This function is used to either insert a new record or update the properties of an existing record.

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

CEOID CeWriteRecordProps(HANDLEhDatabase,CEOIDoidRecord,WORDcPropID,CEPROPVAL*prgPropVal);

Parameters

  • hDatabase
    [in] A handle to the database in which to insert or update the record. The database is opened by using the CeOpenDatabaseinSession (EDB) function.
  • oidRecord
    [in] The object identifier of the record to which the specified properties are written. If this parameter is 0, a new record is created and filled with the specified properties.
  • cPropID
    [in] The number of properties in the array specified by the prgPropVal parameter. This parameter cannot be 0.
  • prgPropVal
    [in] A pointer to an array of CEPROPVAL structures that specifies 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 lists possible values returned by GetLastError:

Return Value Description
ERROR_INVALID_PARAMETER Indicates one of the following:
  • oidRecord is NULL or invalid.
  • cPropID is 0, or prgPropVal is 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 (contains no data, although it may have properties) — in this case this function will add those properties.
ERROR_INVALID_HANDLE Indicates that hDatabase is NULL or equal to INVALID_HANDLE_VALUE.
ERROR_BAD_LENGTH Indicates that the data that is to be written exceeds the maximum record size.
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_ACCESS_DENIED Indicates one of the following:
  • A property was added with DB_PROP_NOTNULL set and NULL is given as the value for that property, or you try 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 NULL or is deleted.
ERROR_ALREADY_EXISTS Indicates that 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_SHARING_VIOLATION Indicates a lock conflict.
ERROR_INSUFFICIENT_BUFFER Indicates that an odd number of bytes were written when using CEVT_LPWSTR. See "Remarks" later in this topic for more information.

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's 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 CeReadRecordPropsEx (EDB), or they can be independently allocated.

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

The following list highlights the differences between this function and the CEDB equivalent function:

  • To write properties, you must first have added the property ID to the database by using 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 via prgPropVal are added as properties to the database. If properties are added to the database, then the relevant errors from the CeAddDatabaseProps function are propagated.
  • If CEDB_SORT_UNIQUE is used, then an insert that does not specify all the properties may still succeed, with NULL being inserted for the properties that were not specified. For the purpose of determining uniqueness, NULL is treated as though it were a value; one NULL value is permitted. In CEDB, a unique constraint requires that all properties are written.

Requirements

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

See Also

CeOpenDatabaseinSession (EDB) | CeAddDatabaseProps (EDB) | CeFlushDBVol (EDB)

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.