ICommandProperties::SetProperties

  • Article

Sets properties in the Rowset property group.

Syntax

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 Rowset property group. If the same property is specified more than once in rgPropertySets, the value is used is provider-specific. If cPropertySets is zero, this parameter is ignored.

    For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure.

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

    • colid in the DBPROP structure was not DB_NULLID, and the property cannot be set on a column.

    • 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.

    • The property was not supported by the provider.

    • The property set was not supported by the provider.

    • It was not possible to set the property.

    • The property is read-only and was not set to its default value.

    • The value of dwOptions in a DBPROP structure was invalid.

    • The property was not in the Rowset property group.

  • 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. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED.

  • DB_E_OBJECTOPEN
    Properties cannot be set while there is an open rowset.

Comments

When a call to ICommandProperties::SetProperties follows a call to ICommandPrepare::Prepare, the command should remain prepared even if the provider must re-prepare the command.

Consumers should first set properties for interfaces and then set other properties that modify those interfaces. The combination of the values of an interface property and a noninterface property might result in another interface being requested. However, the value of a noninterface property, by itself, never results in another interface being requested.

Setting property values is a cumulative operation. That is, each call to ICommandProperties::SetProperties attempts to change the values of the specified properties. If a new value is illegal or conflicts with the value of another property, the value of the property is not changed and ICommandProperties::SetProperties returns DBPROPSTATUS_BADVALUE or DBPROPSTATUS_CONFLICTING in the dwStatus element of the DBPROP structure for the property. Properties are processed from the beginning of the array to the end of the array. As they are processed, properties that conflict with previously set properties, including those set previously on the same call, are marked with DBPROPSTATUS_CONFLICTING, and processing continues through the array of properties.

ICommandProperties::SetProperties cannot always determine whether a property can be set to its requested value. For example, the provider often cannot determine whether the rowset is updatable until it creates the rowset. In this case, ICommandProperties::SetProperties appears to successfully set the property value and the provider delays the determination until ICommand::Execute is called.

If the value of dwOptions for a property is DBPROPOPTIONS_OPTIONAL, the provider attempts to determine whether it can set the property to the requested value. If it can make this determination, it sets the property and returns DBPROPSTATUS_OK or does not set the property and returns DBPROPSTATUS_NOTSET. If it cannot make this determination, it can delay setting the property until the command is executed; in this case, the value of dwOptions returned for the property by ICommandProperties::GetProperties is DBPROPOPTIONS_OPTIONAL.

Consumers should not attempt to unset mandatory rowset interfaces such as DBPROP_IRowset, IAccessor, IColumnsInfo, and IRowsetInfo. These interfaces are always supported, and ICommandProperties::SetProperties returns DBPROPSTATUS_NOTSETTABLE for them.

Even if IDBProperties::GetPropertyInfo lists a property as being supported by the provider, ICommandProperties::SetProperties can return DBPROPSTATUS_NOTSUPPORTED when the consumer attempts to set the property value if the property does not apply to the current circumstances. For example, the provider's ability to support the property might be affected by the current transaction or the current command text.

If an error occurs when setting a particular property, ICommandProperties::SetProperties flags the error in dwStatus in the DBPROP structure and continues processing.

Although providers allow changing properties at any time before command execution, consumers are encouraged to set all properties prior to preparing the command to avoid forcing the provider to re-prepare the command at execution.

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

Reference

ICommandProperties::GetProperties

IDBProperties::GetPropertyInfo

IRowsetInfo::GetProperties