IRowsetInfo::GetProperties

OLE DB Programmer's Reference

Returns the current settings of all properties supported by 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 exist, including properties for which values were not set but for which defaults exist, and also including properties for which values were set automatically because values were set for other properties.

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, 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 14: Properties.

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, 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, 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. Therefore, 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. The consumer must also call VariantClear for the vValue property of each DBPROP structure in order to prevent a memory leak in cases where the variant contains a reference type (such as a BSTR.) If *pcPropertySets is zero on output or if 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 14: Properties.

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. IRowsetInfo::GetProperties can fail to return properties for a number of reasons, including the following:

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.

E_OUTOFMEMORY

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

E_UNEXPECTED

ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

DB_E_ERRORSOCCURRED

Values were not 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

This method makes no logical change to the state of the object.

Even though IDBProperties::GetPropertyInfo lists a property as being supported by the provider, IRowsetInfo::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.

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 ICommandProperties::SetProperties to set the value of DBPROP_ORDEREDBOOKMARKS to VARIANT_TRUE and specifies a dwOptions value of DBPROPOPTIONS_OPTIONAL. If the provider cannot determine 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 execution that ordered bookmarks are not possible, IRowsetInfo::GetProperties returns a value of VARIANT_FALSE and a dwOptions of zero.

See Also