Sets properties in the Rowset property group.
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.