MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Interfaces

IDBProperties::SetProperties

Sets properties in the Data Source and Initialization property groups, for data source objects, or in 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 except return S_OK.

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, the value 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 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

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. IDBProperties::SetProperties can fail to set properties for a number of reasons, including the following:

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.

Comments

For OLE DB 2.5 providers that support direct URL binding, IDBProperties::SetProperties is implemented on binder objects via IDBBinderProperties:IDBProperties. The behavior of IDBProperties::SetProperties on a binder object depends on the type of binder object.

When called on the root binder object, IDBProperties::SetProperties can be used to set properties from any property group. This includes provider-specific properties, which are propagated to provider binder objects at bind time.

When called on provider binder objects, IDBProperties::SetProperties behaves as follows:

If cPropertySets is zero, the provider ignores rgPropertySets and the method does not do anything.
If cPropertySets is not zero, the provider sets the requested properties. If a property is not supported, the returned value of dwStatus in the returned DBPROPINFO structure for that property is DBPROPFLAGS_NOTSUPPORTED and the values of the pwszDescription, vtType, and vValues elements are undefined. If the same property is specified more than once in rgPropertySets, the value used is provider-specific.