IDBProperties::SetProperties

Sets properties in the Data Source and Initialization property groups, for data source objects, or the Initialization property group, for enumerators.

HRESULT SetProperties (
   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. If the data source object or enumerator is uninitialized, the properties specified in these structures must belong to the Initialization property group. If the data source object is initialized, the properties must belong to the Data Source property group. If the enumerator is initialized, it is an error to call this method. If the same property is specified more than once in rgPropertySets, then which value is used is provider-specific. If cPropertySets is zero, this parameter is ignored.

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

Return Code

S_OK
The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK.

DB_S_ERRORSOCCURRED
One or more properties were not set. Properties not in error remain set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. SetProperties can fail to set properties for a number of reasons, including:

The property was not supported by the provider.
The data source object or enumerator was not initialized and the property was not in the Initialization property group.
The data source object was initialized and the property was not in the Data Source property group.
The property set was not supported by the provider.
The property is read-only and was not set to its default value.
It was not possible to set the property.
colid in the DBPROP structure was not DB_NULLID.
The value of dwOptions in the DBPROP structure was invalid.
The data type in vValue in the DBPROP structure was not the data type of the property or was not VT_EMPTY.
The value in vValue in the DBPROP structure was invalid.
The property's value conflicted with an existing property.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
cPropertySets was not equal to zero and rgPropertySets was a null pointer.

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

DB_E_ALREADYINITIALIZED
The method was called on the enumerator and the enumerator was already initialized.

DB_E_ERRORSOCCURRED
All property values were invalid and no properties were set. The consumer checks dwStatus in the DBPROP structures to determine why properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED, except the reason that states that it was not cheap to set the property.