MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 14: Properties

Setting Property Values

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

The following table lists methods consumers can call to set 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 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.