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


 

DBPROP Structure

Consumers and providers use DBPROP structures to pass property values. An array of DBPROP structures, one for each property in the property set, is passed in a DBPROPSET structure. Each DBPROPSET structure represents one property set.

The DBPROP structure is defined as follows:

typedef struct tagDBPROP {
   DBPROPID        dwPropertyID;
   DBPROPOPTIONS   dwOptions;
   DBPROPSTATUS    dwStatus;
   DBID            colid;
   VARIANT         vValue;
} DBPROP;

The elements of this structure are described in the following table.

Element Description
dwPropertyID The ID of the property.
dwOptions The options for this property. For example, when setting a property, the consumer can specify that the property is optional; therefore, the provider should continue even if it cannot satisfy the property. Alternatively, the consumer can specify that a property is required; therefore, the provider should fail if it cannot satisfy the property.
dwStatus The status returned by the provider to indicate success or failure in setting or getting the property value. This value is ignored on input and need not be set by the consumer.

For properties the provider does not support, the provider returns DBPROPSTATUS_NOTSUPPORTED in this element and the values of dwOptions, colid, and vValue are undefined.
colid An optional ID for a column to which the property applies. To specify that a particular property applies to all columns, the consumer sets colid to DB_NULLID.

This is ignored unless the property can be applied to a column—that is, unless the DBPROPFLAGS_COLUMNOK flag is returned for the property in the dwFlags element of the DBPROPINFO structure.

Note   The consumer is required to set colid to a valid DBID value or to DB_NULLID, even if the actual value of colid is ignored by the provider. Not setting colid to a valid value or to DB_NULLID is a programming error.
vValue The value of the property.

When getting property values, if the consumer requests the value of a property that has not been set and has no default, VT_EMPTY is returned.

When setting property values, specifying VT_EMPTY returns the property to its default value.

Note   The consumer is required to set vValue to a valid VARIANT value or to VT_EMPTY, even if the actual value of vValue is ignored by the provider. Not setting vValue to a valid value or to VT_EMPTY is a programming error.