IDBSchemaRowset::GetRowset

  • Article

Returns a schema rowset.

Syntax

HRESULT GetRowset (
   IUnknown       *pUnkOuter,
   REFGUID         rguidSchema,
   ULONG           cRestrictions,
   const VARIANT   rgRestrictions[],
   REFIID          riid,
   ULONG           cPropertySets,
   DBPROPSET       rgPropertySets[],
   IUnknown      **ppRowset);

Parameters

  • pUnkOuter
    [in] A pointer to the controlling IUnknown interface if the rowset is being created as part of an aggregate. If the IDBSchemaRowset interface is not being aggregated, it is a null pointer.

  • rguidSchema
    [in] A GUID identifying the schema rowset. For more information, see the "Comments" section and IDBSchemaRowset.

  • cRestrictions
    [in] The count of restriction values.

  • rgRestrictions
    [in] An array of restriction values. These are applied in the order of the restriction columns. That is, the first restriction value applies to the first restriction column, the second restriction value applies to the second restriction column, and so on. For more information, see the "Comments" section.

  • riid
    [in] The IID of the requested rowset interface. 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 0, 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 Property Group in Appendix C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure.

  • ppRowset
    [out] A pointer to memory in which to return the requested interface pointer on the schema rowset. This rowset is read-only. If no applicable schema information exists, an empty rowset is returned.

Return Code

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

  • DB_S_ASYNCHRONOUS
    The method has initiated asynchronous creation of the rowset. The consumer can call IDBAsynchStatus to poll for status or IConnectionPointContainer to obtain the IID_IDBAsynchNotify connection point. Attempting to call any other interfaces might fail, and the full set of interfaces might not be available on the object until asynchronous initialization of the rowset has completed.

    DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED.

  • 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.

    • It was not possible to set the property.

    • The property was not in the Rowset property group.

    • The property set was not supported by the provider.

    DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. Of course, the properties-in-error are not available, but for any properties that could not be set, the provider should report that status in the property array passed to IDBSchemaRowset::GetRowset (assuming that property failures can all be determined ahead of rowset population).

  • DB_S_NOTSINGLETON
    The provider supports returning row objects on IDBSchemaRowset::GetRowset, and the consumer requested a row object but the result was not a singleton. A row object of the first row of the rowset is returned if the provider supports returning the row object. Because returning this result can be expensive, providers are not required to do so. If DB_S_ERRORSOCCURRED also applies to the execution of this method, it takes precedence over DB_S_NOTSINGLETON.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    rguidSchema was invalid.

    rguidSchema specified a schema rowset that was not supported by the provider.

    In one or more restriction values specified in rgRestrictions, the vt element of the VARIANT was the incorrect type.

    cRestrictions was greater than zero, and rgRestrictions was a null pointer.

    ppRowset was a null pointer.

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

    cPropertySets was greater than zero, and rgPropertySets was a null pointer.

  • E_NOINTERFACE
    The schema rowset did not support the interface specified in riid.

  • E_OUTOFMEMORY
    The provider was unable to allocate sufficient memory in which to create the rowset.

  • 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 satisfiable 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.

  • DB_E_NOTSUPPORTED
    In an element of rgRestrictions, the vt element of the VARIANT was not VT_EMPTY and the provider did not support the corresponding restriction. Some providers may also return E_INVALIDARG for this case, particularly if the restriction was added in a later version of the specification.

  • DB_SEC_E_PERMISSIONDENIED
    The consumer did not have sufficient permission to create the schema rowset.

  • DB_E_OBJECTOPEN
    The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set to VARIANT_FALSE.

Comments

IDBSchemaRowset::GetRowset allows the consumer to specify restrictions that limit the set of rows returned by the schema rowset but does not define the format for such restrictions. The restriction array contains single values that are compared for equality to the corresponding value in the schema rowset. Only rows that exactly match the restriction value in the corresponding column are returned in the rowset. Pattern matching is not supported.

In general, for schema rowset column types that do not have a corresponding variant type, restrictions should be specified using VT_BSTR. For DBTYPE_GUID, the format of the BSTR string is "{<guid>}".

When preparing an array of restriction values, consumers are not required to specify values for all of the restriction columns on a rowset. Any columns for which no restriction values are specified are not restricted.

There are two ways for a consumer to explicitly specify that there is no restriction value for a column. First, the consumer cannot specify a restriction value for the column. For example, if there are three restriction columns, the consumer passes only two restriction values; these apply to the first two restriction columns, and no value is specified for the third restriction column.

Second, the consumer can set the vt element of the VARIANT specified for the column to VT_EMPTY, even if the provider does not support restrictions on the column. For example, suppose there are three restriction columns, the provider supports restrictions on the first and third columns, and the consumer wants to restrict values on these two columns. The consumer passes three restriction values. The first and third values are the desired restrictions, and the second value is a VARIANT with a vt element of VT_EMPTY.

If the vt element of the VARIANT specified for a restriction column is VT_NULL, this means that the column must be NULL to satisfy the restriction. This is equivalent to the IS NULL predicate in SQL. If the vt element of the VARIANT specified for a restriction column is VT_BSTR and the bstrVal element is set to a null pointer, this means that the column must contain an empty string to satisfy the restriction.

See Also

Reference

IDBSchemaRowset::GetSchemas