OLE DB Programmer's Reference

IDBDataSourceAdmin::ModifyDataSource

Modifies the current data store.

HRESULT ModifyDataSource (
   ULONG       cPropertySets,
   DBPROPSET   rgPropertySets[]);

Parameters

cPropertySets
[in]
The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets and the method does not do anything.
rgPropertySets
[in/out]
An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must belong to the Data Source Creation or Initialization property groups; Initialization properties must be supported by the provider for use in data store creation. If the same property is specified more than once in rgPropertySets, the value used is provider-specific. If a provider cannot support a property, the property is ignored. If cPropertySets is zero, this argument is ignored.

For information about the properties in the Data Source Creation and Initialization property groups that are defined by OLE DB, see "Data Source Creation Property Group" and "Initialization Property Group" in Appendix C. For information about the DBPROPSET and DBPROP structures, see "DBPROPSET Structure" and "DBPROP Structure" in Chapter 14: Properties.

Return Code

S_OK
The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK.
DB_S_ERRORSOCCURRED
The data store was modified, but one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_OPTIONAL—were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for a number of reasons, including the following:
  • The property was not in the Data Source Creation or Initialization property group.
  • The property was in the Initialization property group but was not supported for use in data store creation.
  • The property set was not supported by the provider.
  • It was not possible to set the property.
E_FAIL
A provider-specific error occurred.
E_INVALIDARG
cPropertySets was not zero, and rgPropertySets was a null pointer.

In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer.

E_UNEXPECTED
The data source object was in an uninitialized state.
DB_E_ERRORSOCCURRED
The data store was not modified because one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED—were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties for a number of reasons, including the following:
  • The property was not in the Data Source Creation or Initialization property group.
  • The property was in the Initialization property group but was not supported for use in data store creation.
  • The property set was not supported by the provider.
  • The value of dwOptions in a DBPROP structure was invalid.
DB_E_NOTSUPPORTED
The provider does not support this method.
DB_SEC_E_PERMISSIONDENIED
The consumer did not have permission to modify the current data store.

Comments

IDBDataSourceAdmin::ModifyDataSource modifies the current data store. Any open OLE DB objects on this data source object, such as sessions, commands, rowsets, rows, and views, must be released before calling this method. Consumers cannot modify a data store if they have not successfully connected to the provider by initializing the data source object.

See Also

IDBDataSourceAdmin::CreateDataSource | IDBDataSourceAdmin::DestroyDataSource