CeSetDatabaseInfoEx (EDB)

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function sets database parameters, including the name, sort order(s), and type.

Syntax

BOOL CeSetDatabaseInfo(
  PCEGUID pGuid,
  CEOID oidDbase,
  CEDBASEINFO* pNewInfo
);

Parameters

• pGuid
  [in] CEGUID of the mounted volume in which the database identified by the oidDbase parameter resides. You can mount a volume with the CeMountDBVolEx (EDB) function

• oidDbase
  [in] OID of the database in which to set the new database information. This database must exist in the volume specified by pGuid. This OID must have been generated by the CeCreateDatabaseWithProps (EDB) function.

• pNewInfo
  [in] Pointer to a CEDBASEINFOEX (EDB) structure that contains new parameter information for the database. The ftLastModified and dwSize members of the structure are not used.

Return Value

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. The following table shows possible values.

Remarks

The ERROR_INVALID_PARAMETER can be returned in the following situations:

• The pGuid parameter is set to NULL.
• The pNewInfo parameter is set to NULL.
• The wVersion member of the CEDBASEINFOEX structure returned by pNewInfo is not equal to CEDBASEINFO_VERSION.
• The dwFlags member of the CEDBASEINFOEX structure returned by pNewInfo includes the CEDB_VALIDNAME flag, and the wszDbaseName member of the CEDBASEINFOEX structure returned by pNewInfo contains an empty string or has all spaces.
• The dwFlags member of the CEDBASEINFOEX structure returned by pNewInfo has the CEDB_VALIDSORTSPEC flag, and the wNumSortOrder member of the CEDBASEINFOEX structure returned by pNewInfo is greater than CE_MAXSORTORDER (16).
• There are sort orders specified, but one or more of the elements in the rgSortSpecs member of the CEDBASEINFOEX structure returned by pNewInfo is not valid. The following members of a SORTORDERSPECEX (EDB) structure must be valid:
  • The wVersion member must be set to SORTORDERSPECEX_VERSION.
  • The wNumProps member cannot be greater than CE_MAXSORTPROP (16).
  • The property IDs in rgPropID must all have valid CEDB data types from the CEVT_xxx enumeration.
  • The property cannot be a CEVT_STREAM data type because you cannot create sort orders on streams.

This function succeeds only if the database is not open.

When the CEDB_VALIDSORTSPEC flag is specified in the dwFlags member of the CEDBASEINFOEX structure returned by pNewInfo, consider the following issues:

• If you add new sort orders to a large database, this operation may be time-consuming.
• If you try to change a sort order to sort on non-NULL properties or unique keys, the change may fail because existing records do not satisfy those new requirements. For example, NULLs or duplicates may already exist. When this occurs, the database retains its original information. An ERROR_ACCESS_DENIED error is returned if a non-NULL requirement is not satisfied, and an ERROR_ALREADY_EXISTS error is returned if non-unique values exist. A failure of this type is potentially very slow.
• If there are sort orders in the database before calling this function and some or all of them are not specified in the rgSortSpecs member of the CEDBASEINFOEX structure returned by pNewInfo, this function cleans up the database and removes unused sort orders.

Changing sort orders can be a very expensive operation. Before doing this, consider cautioning the user that this may be a lengthy process.

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

• Compression
  EDB supports compression and, as with CEDB, the default is to create a compressed database. Unlike CEDB, however, once a database has been created in EDB, its compression status cannot be changed. In addition, compression applies to all data in the database, with the exception of properties of the type CEVT_STREAM, which is not compressed by default. To compress a stream, the property must be added by using the CEPROPSPEC (EDB) structure and specifying the DB_PROP_COMPRESSED flag. A compressed stream is inaccessible to the stream API. The CeReadRecordPropsEx (EDB) function must be used instead.
• Last modified time
  EDB does not support the caller's setting the last modified time of a table through this method. If you specify CEDB_VALIDMODTIME, this function returns FALSE, and GetLastError returns ERROR_NOT_SUPPORTED.
• User roles
  EDB does not support user roles. If you specify CEDB_SYSTEMDB, this function returns FALSE, and GetLastError returns ERROR_NOT_SUPPORTED.
• Sort orders
  If a sort order is constrained to be unique, then EDB allows a single NULL to occur, but in CEDB no NULLs are permitted. For example, if there are two properties in a sort order, EDB considers the values "A,B","A,NULL", "NULL,B" and "NULL,NULL" as unique values, whereas in CEDB any pair that contains a NULL value cannot be entered in the sort order.

Requirements

See Also

Reference

EDB Functions
CeCreateDatabaseWithProps (EDB)
CeMountDBVolEx (EDB)
CeReadRecordPropsEx (EDB)
CEDBASEINFOEX (EDB)
CEPROPSPEC (EDB)

Other Resources