ICommandProperties::GetProperties

Returns the list of properties in the Rowset property group that are currently requested for the rowset.

HRESULT GetProperties (
   const ULONG            cPropertyIDSets,
   const DBPROPIDSET   rgPropertyIDSets[],
   ULONG *                  pcPropertySets,
   DBPROPSET **         prgPropertySets);

Parameters

cPropertyIDSets

[in]
The number of DBPROPIDSET structures in rgPropertyIDSets.

If cPropertySets is zero, the provider ignores rgPropertyIDSets and returns the values of all properties in the Rowset property group for which values have been set or defaults exist. It does not return the values of properties in the Rowset property group for which values have not been set and no defaults exist, nor does it return the values of properties for which no value has been set, nor default exists, and for which a value will be set automatically because a value for another property in the Rowset property group has been set.

If cPropertyIDSets is not zero, the provider returns the values of the requested properties. If a property is not supported, the returned value of dwStatus in the returned DBPROP structure for that property is DBPROPSTATUS_NOTSUPPORTED and the value of dwOptions is undefined.

rgPropertyIDSets

[in]
An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Rowset property group. The provider returns the values of the properties specified in these structures. If cPropertyIDSets is zero, then this parameter is ignored.

For information about the properties in the Rowset property group that are defined by OLE DB, see ""Rowset Properties"" in Appendix C. For information about the DBPROPIDSET structure, see "DBPROPIDSET Structure" in Chapter 11.

pcPropertySets

[out]
A pointer to memory in which to return the number of DBPROPSET structures returned in *prgPropertySets. If cPropertyIDSets is zero, *pcPropertySets is the total number of property sets for which the provider supports at least one property in the Rowset property group. If cPropertyIDSets is greater than zero, *pcPropertySets is set to cPropertyIDSets. If an error other than DB_E_ERRORSOCCURRED occurs, *pcPropertySets is set to zero.

prgPropertySets

[out]
A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, then one structure is returned for each property set that contains at least one property belonging to the Rowset property group. If cPropertyIDSets is not zero, then one structure is returned for each property set specified in rgPropertyIDSets.

If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs. Thus, in the case where no column properties are specified in rgPropertyIDSets, corresponding elements of the input rgPropertyIDs and the returned rgProperties have the same property ID. However, if a column property is requested in rgPropertyIDSets, multiple properties may be returned, one for each column, in rgProperties. In this case, corresponding elements of rgPropertyIDs and rgProperties will not have the same property ID, and rgProperties will contain more elements than rgPropertyIDs.

The provider allocates memory for the structures and returns the address to this memory; the consumer releases this memory with IMalloc::Free when it no longer needs the structures. Before calling IMalloc::Free for *prgPropertySets, the consumer should call IMalloc::Free for the rgProperties element within each element of *prgPropertySets. If *pcPropertySets is zero on output or an error other than DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgPropertySets is a null pointer on output.

For information about the DBPROPSET and DBPROP structures, see "DBPROPSET Structure" and "DBPROP Structure" in Chapter 11.

Return Code

S_OK
The method succeeded. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK.

DB_S_ERRORSOCCURRED
No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to determine the properties for which values were not returned. GetProperties can fail to return properties for a number of reasons, including:

The property was not supported by the provider.
The property was not in the Rowset property group.
The property set was not supported by the provider. If cPropertyIDs in the DBPROPIDSET structure for the property set was zero, the provider cannot set dwStatus in the DBPROP structure because it does not know the IDs of any properties in the property set. Instead, it sets cProperties to zero in the DBPROPSET structure returned for the property set.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
cPropertyIDSets was not equal to zero and rgPropertyIDSets was a null pointer.

pcPropertySets or prgPropertySets was a null pointer.

In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer.

In an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR and cPropertyIDs was not zero, or rgPropertyIDs was not a null pointer.

cPropertyIDSets was greater than one and, in an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR.

E_OUTOFMEMORY
The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures.

DB_E_ERRORSOCCURRED
No values were returned for any properties. The provider allocates memory for *prgPropertySets and the consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory when it no longer needs the information.

Comments

GetProperties returns the current values of properties that have been set by the consumer with ICommandProperties::SetProperties. For all values not set by the consumer, GetProperties returns the initial property value.

Even though IDBProperties::GetPropertyInfo lists a property as being supported by the provider, GetProperties will not return a value for it if it does not apply to the current circumstances. For example, the provider's ability to support the property might be affected by the current transaction or the current command text.

The property values returned by ICommandProperties::GetProperties are not affected by executing the command. However, IRowsetInfo::GetProperties might return a different value for a property than does ICommandProperties::GetProperties. For example, if a consumer requests ordered bookmarks if they are possible, it calls SetProperties to set the value of DBPROP_ORDEREDBOOKMARKS to VARIANT_TRUE and specifies a dwOptions value of DBPROPOPTIONS_OPTIONAL. If the provider cannot determine at this point in the definition of the command whether this is possible, ICommandProperties::GetProperties returns a value of VARIANT_TRUE and a dwOptions of DBPROPOPTIONS_OPTIONAL for this property. If the provider determines during optimization or execution that ordered bookmarks are not possible, IRowsetInfo::GetProperties returns a value of VARIANT_FALSE and a dwOptions of zero.

If ICommand::Execute returns DB_E_ERRORSOCCURRED, the consumer can immediately call GetProperties with the DBPROPSET_PROPERTIESINERROR property set to return all the properties that were in error. For more information, see "Property Sets" in Chapter 11.