Setting Property Values

To set property values, a consumer performs the following actions:

  1. Determines the properties for which to set values. To set the value of a property to a different value, the property must be updatable. However, consumers can set the value of a read-only property to its current value. For information about how to determine if a property is writable, see "Getting Information about Properties" in this chapter.

  2. Determines the property sets that contain the identified properties.

  3. Allocates an array of DBPROPSET structures, one for each identified property set.

  4. Allocates an array of DBPROP structures for each property set. The number of elements in each array is the number of properties, identified in step 1, that belong to that property set.

  5. Places the property's value and a flag showing whether it is required or optional in the DBPROP structure for each property. If the provider cannot set the value of a required property, it will fail to create the object to which the property applies and the method will return DB_E_ERRORSOCCURRED. If the provider cannot easily set the value of an optional property, it will create the object to which the property applies and the method will return DB_S_ERRORSOCCURRED.

    If the property belongs to the Rowset property group and applies to a single column, the consumer sets the colid element of the DBPROP structure to the ID of the column.

  6. For each property set, places the property set GUID in the DBPROPSET structure. It then places the count of elements in and the pointer to the corresponding DBPROP array in the DBPROPSET structure.

  7. Calls a method that sets properties and passes it the count and array of DBPROPSET structures. The provider returns the status of each property in the dwStatus element of the DBPROP structure for that property; that is, whether the property was set and, if not, why it was not set.

For example, assume that the consumer wants to set values for five properties, where properties 1, 2, and 3 are in property set A and properties 4 and 5 are in property set B. The consumer uses the following structures.

An example of setting property values

The following table lists the methods that consumers use to set property values.

Methods used by consumer to set property values

Property group Methods used to set property values
Column ITableDefinition::CreateTable
Data Source IDBProperties::SetProperties
Data Source Creation IDBDataSourceAdmin::CreateDataSource
Data Source Information IDBProperties::SetProperties
Initialization IDBProperties::SetProperties
Index IIndexDefinition::CreateIndex
Rowset IColumnsRowset::GetColumnsRowset,
ICommandProperties::SetProperties,
IDBSchemaRowset::GetRowset,
IOpenRowset::OpenRowset,
ISourcesRowset::GetSourcesRowset,
ITableDefinition::CreateTable
Session ISessionProperties::SetProperties
Table ITableDefinition::CreateTable

Read-only properties can always be set to their default values or to VT_EMPTY. Setting read-only properties to any other values will cause an error.