Setting Property Values

OLE DB Programmer's Reference

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," later in this chapter.
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

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

1998-2001 Microsoft Corporation. All rights reserved.