CeSetDatabaseInfo (EDB) (Windows CE 5.0)
This function is used to set various database parameters, including the name, sort orders, and type.
This function does not work with CEDB databases. For more information about CEDB, see CEDB Reference.
BOOL CeSetDatabaseInfo(CEOIDoidDbase,CEDBASEINFO*pNewInfo);
Parameters
- oidDbase
[in] The OID of the database in which to set the new database information. This database must exist in the volume specified by the pGuid parameter. This OID must have been generated by the CeCreateDatabaseWithProps (EDB) function. - pNewInfo
[in] A 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 Values
TRUE indicates success. FALSE 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 that one or more parameters are invalid. See "Remarks" later in this topic for more information. |
| ERROR_NOT_FOUND | Indicates that the volume specified by pGuid does not exist, or that the database specified by oidDbase does not exist in the volume specified by pGuid. |
| ERROR_SHARING_VIOLATION | Indicates that the database being modified is currently open. |
| ERROR_NOT_SUPPORTED | Indicates that pNewInfo->dwFlags contains one of these two flags:
|
| ERROR_ACCESS_DENIED | A non-NULL requirement was not satisfied. |
| ERROR_ALREADY_EXISTS | Indicates that a uniqueness violation has occurred. For example, an attempt was made to add a unique sort order when the values are not unique. |
Remarks
The ERROR_INVALID_PARAMETER may be returned in the following situations:
- pGuid is NULL.
- pNewInfo is NULL.
- *pNewInfo->*wVersion is not equal to CEDBASEINFO_VERSION.
- *pNewInfo->*dwFlags includes the CEDB_VALIDNAME flag, and *pNewInfo->*wszDbaseName contains an empty string or has all spaces.
- *pNewInfo->*dwFlags has the CEDB_VALIDSORTSPEC flag, and *pNewInfo->*wNumSortOrder is greater than CE_MAXSORTORDER (16).
- There are sort orders specified, and any of the elements in pNewInfo->rgSortSpecsare not valid. The following members of a SORTORDERSPECEX (EDB) structure must be valid:
- wVersion must be set to SORTORDERSPECEX_VERSION.
- wNumProps cannot be greater than CE_MAXSORTPROP (16).
- The property IDs in the 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 *pNewInfo->*dwFlags, there are a few issues to consider.
- If you add new sort orders to a database, and there are many records in the database, this operation may be time-consuming.
- If you try to change a sort order to a 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 was not satisfied and an ERROR_ALREADY_EXISTS error is returned if non-unique values exist. A failure of this type is potentially very slow and should be avoided.
- If there were sort orders present in the database before calling this function, and some or all of those sort orders are not specified in *pNewInfo->*rgSortSpecs, this function will clean up the database and remove those unused sort orders.
Changing the sort orders of a database can be a very expensive operation. Before doing this, consider cautioning the user that this may be a lengthy process.
The following list highlights 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 CEVT_STREAM property the property must be added by using the CEPROPSPEC (EDB) structure and specifying the DB_PROP_COMPRESSED flag. A compressed stream is inaccessible via the stream API; the CeReadRecordPropsEx (EDB) function must be used instead.
Last modified time
EDB doesn't allow the caller to set the last modified time of a table through this method. If you specify CEDB_VALIDMODTIME, then this function returns FALSE and GetLastError returns ERROR_NOT_SUPPORTED.
User roles
EDB does not support the concept of user roles. If you specify CEDB_SYSTEMDB then 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, while in CEDB any pair that contains a NULL value could not be entered in the sort order.
Requirements
OS Versions: Windows CE 5.0 and later.
Header: Windbase.h.
Link Library: Coredll.lib.
See Also
CeCreateDatabaseWithProps (EDB) | CeMountDbVolEx (EDB) | CeReadRecordPropsEx (EDB) | CEDBASEINFOEX (EDB) | CEPROPSPEC (EDB) | EDB Schema Support
Send Feedback on this topic to the authors