Share via

Setting Property Values

  • Article

To set property values, a consumer must perform the following actions:

  1. Determine the properties for which to set values. To set the value of a property to a different value, the property must be settable. However, consumers can set the value of a read-only property to its default value. For information about how to determine if a property is settable, see Getting Information About Properties.

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

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

  4. Allocate 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. Store the property's value in that property's DBPROP structure, along with a flag showing whether it is required or optional.

    If the provider cannot satisfy a required property, it fails to create the object to which the property applies and the object-creation method returns DB_E_ERRORSOCCURRED. If the provider cannot set the value of an optional property, it creates the object to which the property applies and the method returns 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. Otherwise, the consumer sets the value of colid to DB_NULLID.

    Note

    In cases where the colid element in the DBPROP structure for specified properties is ignored, the consumer must nevertheless set the value of colid to DB_NULLID. Not to do so is a programming error.

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

  7. Call a method that sets properties and pass 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 structures shown in the following illustration.

An example of setting property values

setting property information

Note

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.

The following table lists methods consumers can call 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, IDBDataSourceAdmin::CreateDataSource

Index

IIndexDefinition::CreateIndex

Rowset

IColumnsRowset::GetColumnsRowset, ICommandProperties::SetProperties, IDBSchemaRowset::GetRowset, IOpenRowset::OpenRowset, ISourcesRowset::GetSourcesRowset, ITableDefinition::CreateTable

Session

ISessionProperties::SetProperties

Table

ITableDefinition::CreateTable, IAlterTable::AlterTable

The return code generated by a property-setting method indicates how far the method has succeeded. Whether a success (S_) or an error (E_) return code is generated depends on factors such as whether the properties that failed to be set were required and on whether the method is SetProperties or a method that performs other actions in addition to setting properties. These factors are summarized in the following table.

Note

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.

Success or failure case

Return code: SetProperties

Return code: other methods

All properties are optional, and all are set successfully.

S_OK

S_OK

All properties are optional, and one or more (but not all) fail to be set.

DB_S_ERRORSOCCURRED

DB_S_ERRORSOCCURRED

All properties are optional, and all fail to be set.

DB_E_ERRORSOCCURRED

DB_S_ERRORSOCCURRED

All properties are required, and all are set successfully.

S_OK

S_OK

All properties are required, and one or more (but not all) fail to be set.

DB_S_ERRORSOCCURRED

DB_E_ERRORSOCCURRED

All properties are required, and all fail to be set.

DB_E_ERRORSOCCURRED

DB_E_ERRORSOCCURRED

Not all properties are required, and all are set successfully.

S_OK

S_OK

Not all properties are required, all required properties are set successfully, and one or more optional properties fail to be set.

DB_S_ERRORSOCCURRED

DB_S_ERRORSOCCURRED

Not all properties are required, and one or more (but not all) required properties fail to be set.

DB_S_ERRORSOCCURRED

DB_E_ERRORSOCCURRED

Not all properties are required, and all fail to be set.

DB_E_ERRORSOCCURRED

DB_E_ERRORSOCCURRED