ISessionProperties::SetProperties

OLE DB Programmer's Reference

Sets properties in the Session property group.

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. The properties specified in these structures must belong to the Session property group. 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 Session property group that are defined by OLE DB, see "Session Properties" 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. ISessionProperties::SetProperties can fail to set properties for a number of reasons, including the following:

• The property was not supported by the provider.
• The property was not in the Session 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_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.

Comments

Generally, consumers should not set the same property twice, because if they do, the value of the property is provider-specific, meaning it is unknown to the consumer. The status for the successfully set value should be DBPROPSTATUS_OK, but it is provider-specific what the status value is for the other property values.

See Also

IDBProperties::GetPropertyInfo | ISessionProperties::GetProperties

1998-2001 Microsoft Corporation. All rights reserved.