MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 14: Properties
Consumers use DBPROPOPTIONS values to specify whether a property value is required or optional. The values of DBPROPOPTIONS are mutually exclusive. DBPROPOPTIONS is used in the DBPROP structure.
Providers should return the same DBPROPOPTIONS value for GetProperties that the consumer specified in SetProperties. In particular, providers must not return failure because a property, set as DBPROPOPTIONS_OPTIONAL, could not be satisfied; and providers must not return success without satisfying all properties set as DBPROPOPTIONS_REQUIRED. Properties that have not been set by the consumer are usually returned as DBPROPOPTIONS_OPTIONAL.
The values of DBPROPOPTIONS have the following meanings.
| Value | Description |
| DBPROPOPTIONS_REQUIRED | The specified property value is required.
If the provider does not support the specified property, it sets the dwStatus element of the DBPROP structure to DBPROPSTATUS_NOTSUPPORTED and returns DB_E_ERRORSOCCURRED. Whatever action the method was to take, such as initializing a data source object or creating a rowset, fails. If the provider supports the specified property, all methods except ICommandProperties::SetProperties or IDBProperties::SetProperties can determine whether the provider supports setting the property to the requested value. For these methods, if the provider does not support setting the property to the requested value, it sets dwStatus to DBPROPSTATUS_NOTSUPPORTED and returns DB_E_ERRORSOCCURRED. Whatever action the method was to take, such as initializing a data source or creating a rowset, fails. For ICommandProperties::SetProperties or IDBProperties::SetProperties, if the provider supports the specified property and SetProperties determines that the provider does not support setting the property to the requested value, it sets dwStatus to DBPROPSTATUS_NOTSUPPORTED and returns DB_S_ERRORSOCCURRED if one or more properties passed to SetProperties were successfully set, or DB_E_ERRORSOCCURRED if none of the properties could be set. If the provider supports the specified property but SetProperties cannot determine whether the provider supports the requested value, it sets dwStatus to DBPROPSTATUS_OK. When ICommand::Execute or IDBInitialize::Initialize is called, the provider determines whether it can support the requested value. If the provider cannot support the requested value, ICommand::Execute or IDBInitialize::Initialize returns DB_E_ERRORSOCCURRED. |
| DBPROPOPTIONS_OPTIONAL | The specified property value is optional. If the provider does not support the specified property, it sets the dwStatus element of the DBPROP structure to DBPROPSTATUS_NOTSUPPORTED and returns DB_S_ERRORSOCCURRED. Whatever action the method was to take, such as initializing a data source object or creating a rowset, succeeds.
If the provider supports the specified property, all methods except ICommandProperties::SetProperties or IDBProperties::SetProperties can determine whether the provider supports setting the property to the requested value. For these methods, if the provider cannot support the specified value, it sets dwStatus to DBPROPSTATUS_NOTSET and returns DB_S_ERRORSOCCURRED. Whatever action the method was to take, such as initializing a data source object or creating a rowset, succeeds. For ICommandProperties::SetProperties or IDBProperties::SetProperties, if the provider supports the specified property and SetProperties cannot determine whether the provider supports setting the property to the requested value, it sets dwStatus to DBPROPSTATUS_OK. ICommandProperties::GetProperties or IDBProperties::GetProperties returns the specified value in vValue and DBPROPOPTIONS_OPTIONAL in dwOptions. When ICommand::Execute or IDataInitialize::Initialize is called, the provider determines whether it can support the specified value. If the provider does not support setting the property to the requested value, ICommand::Execute or IDataInitialize::Initialize returns DB_S_ERRORSOCCURRED but successfully executes the command or initializes the data source object. |