ISourcesRowset::GetSourcesRowset

  • Article

Returns a rowset of the data source objects and enumerators visible from the current enumerator.

Syntax

HRESULT GetSourcesRowset(
   IUnknown     *pUnkOuter,
   REFIID        riid,
   ULONG         cPropertySets,
   DBPROPSET     rgPropertySets[],
   IUnknown    **ppSourcesRowset);

Parameters

  • pUnkOuter
    [in] A pointer to the controlling IUnknown interface if the sources rowset is being created as part of an aggregate. If the rowset is not part of an aggregate, this must be set to a null pointer.

  • riid
    [in] The IID of the interface on which to return a pointer. This interface is conceptually added to the list of required interfaces on the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting rowset.

  • cPropertySets
    [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets.

  • rgPropertySets
    [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must belong to the Rowset property group. If the same property is specified more than once in rgPropertySets, it is provider-specific which value is used. If cPropertySets is 0, this argument 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 DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure.

  • ppSourcesRowset
    [in] A pointer to memory in which to return the requested interface pointer on the rowset. If an error occurs, the returned pointer is null.

Return Code

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

  • DB_S_ERRORSOCCURRED
    The rowset was opened, but one or more properties ? for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for a number of reasons, including the following:

    • colid in the DBPROP structure was invalid.

    • The data type in vValue in the DBPROP structure was not the data type of the property or was not VT_EMPTY.

    • The value in vValue in the DBPROP structure was invalid.

    • The property's value conflicted with an existing property.

    • A property that was specified to be applied to all columns could not be applied to one or more columns.

    • The property was not supported by the provider.

    • The property set was not supported by the provider.

    • It was not possible to set the property.

    • The property was not in the Rowset property group.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    ppSourcesRowset was a null pointer.

    cPropertySets was not 0, and rgPropertySets was a null pointer.

    In an element of rgPropertySets, cProperties was not 0 and rgProperties was a null pointer.

  • E_NOINTERFACE
    The rowset did not support the interface specified in riid, or riid is IID_NULL.

  • E_OUTOFMEMORY
    The provider did not have enough memory to create the rowset object.

  • E_UNEXPECTED
    The enumerator object was in an uninitialized state.

  • DB_E_ABORTLIMITREACHED
    The method failed because a resource limit has been reached. For example, a query used to implement the method timed out. No rowset is returned.

  • DB_E_ERRORSOCCURRED
    No rowset was returned because one or more properties ? for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. None of the properties are remembered. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED.

  • DB_E_NOAGGREGATION
    pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support aggregation of the rowset object being created.

    pUnkOuter was not a null pointer, and riid was not IID_IUnknown.

  • DB_E_NOTFOUND
    The provider supports the return of singleton row objects on a method that typically returns a rowset, a row was requested via riid or DBPROP_IRow, and no rows existed in the rowset.

Comments

ISourcesRowset::GetSourcesRowset returns the following rowset. The rowset is read-only. The columns are returned in the order shown in the following table.

Column name

Type indicator

Description

SOURCES_NAME

DBTYPE_WSTR

The name of the data store or enumerator.

SOURCES_PARSENAME

DBTYPE_WSTR

String to pass to IParseDisplayName to obtain a moniker for the data source object or enumerator.

SOURCES_DESCRIPTION

DBTYPE_WSTR

The description of the data source object or enumerator.

SOURCES_TYPE

DBTYPE_UI2

Specifies whether the row describes a data source object or an enumerator:

  • DBSOURCETYPE_BINDER ? Indicating a provider binder that supports direct URL binder

  • DBSOURCETYPE_DATASOURCE_MDP ? Indicating a multidimensional (OLAP) provider

  • DBSOURCETYPE_DATASOURCE_TDP ? Indicating a tabular data provider

  • DBSOURCETYPE_ENUMERATOR ? Indicating an enumerator

If a single piece of code is capable of being used both as a data source object and as an enumerator, it is listed in the rowset twice, once in each role.

SOURCES_ISPARENT

DBTYPE_BOOL

If the row describes an enumerator, SOURCES_ISPARENT is VARIANT_TRUE if the enumerator is the parent enumerator ? that is, the enumerator whose enumeration contains the enumerator on which ISourcesRowset::GetSourcesRowset was just called. This allows the consumer to go backward through the enumeration. Whether an enumerator is able to enumerate its parent is provider-specific. Otherwise, SOURCES_ISPARENT is VARIANT_FALSE.

If the row describes a data source object, SOURCES_ISPARENT is ignored by the consumer.

See Also

Reference

IDBProperties::GetPropertyInfo