Share via

IOpenRowset::OpenRowset

  • Article

Opens and returns a rowset that includes all rows from a single base table or index.

Syntax

HRESULT OpenRowset(
   IUnknown    *pUnkOuter,
   DBID        *pTableID,
   DBID        *pIndexID,
   REFIID       riid,
   ULONG        cPropertySets,
   DBPROPSET    rgPropertySets[],
   IUnknown   **ppRowset);

Parameters

  • pUnkOuter
    [in] The controlling IUnknown if the rowset is to be aggregated; otherwise, a null pointer.

  • pTableID
    [in] The DBID of the table to open. For more information, see the "Comments" section.

  • pIndexID
    [in] The DBID of the index to open. For more information, see the "Comments" section.

  • riid
    [in] The IID of the interface to return in *ppRowset. 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. This must be an interface that the rowset supports, even when ppRowset is set to a null pointer and no rowset is created.

  • 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 zero, 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 Structureand DBPROP Structure.

  • ppRowset
    [in/out] A pointer to memory in which to return the interface pointer to the created rowset. If ppRowset is a null pointer, no rowset is created; properties are verified and if a required property cannot be set, DB_E_ERRORSOCCURRED is returned. If IOpenRowset::OpenRowset fails, *ppRowset is set to a null pointer.

Return Code

  • S_OK
    The method succeeded and the rowset is opened. 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 may 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 was specified to be applied to all columns but 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.

    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 IOpenRowset::OpenRowset (assuming that property failures can all be determined ahead of rowset population).

    DB_S_ERRORSOCCURRED should be returned before DB_S_NOTSINGLETON because the status values can be checked, and providers are not required to return DB_S_NOTSINGLETON.

  • DB_S_NOTSINGLETON
    The provider supports returning row objects on IOpenRowset::OpenRowset, 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. Returning this result may be expensive, so 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.

  • DB_S_STOPLIMITREACHED
    Execution has been stopped because a resource limit has been reached. The results obtained so far have been returned. This return code takes precedence over DB_S_ERRORSOCCURRED; that is, if the conditions described here and in those described in DB_S_ERRORSOCCURRED both occur, the provider returns this code. When the consumer receives this return code, it should also check for the conditions described in DB_S_ERRORSOCCURRED.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    pTableID and pIndexID were both null pointers.

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

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

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

  • 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_NOINDEX
    The specified index does not exist in the current data store or did not apply to the specified table.

    The provider does not support opening indexes through IOpenRowset.

  • DB_E_NOSTATISTIC
    The specified statistic does not exist in the current data source or did not apply to the specified table, or it does not support a histogram.

    Providers that do not support histograms do not have to return this code.

    Providers that are unable to easily detect whether a histogram is available for the specified table are allowed to return S_OK and an empty histogram rowset.

  • DB_E_NOTABLE
    The specified table does not exist in the data store.

  • DB_E_NOTFOUND
    The provider supports row objects, a row was requested via riid or DBPROP_IRow, and no rows existed in the 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.

  • DB_E_PARAMNOTOPTIONAL
    The table specified by pTableID is a procedure that requires one or more parameters.

  • DB_SEC_E_PERMISSIONDENIED
    The consumer did not have sufficient permission to open the rowset. For example, a rowset included a column for which the consumer does not have read permission.

Comments

If the table or index has no rows, the rowset is still created. The resulting rowset is fully functional and can be used, for example, to insert new rows or determine column metadata.

pTableID and pIndexID are used in the following combinations:

  • If pTableID is not a null pointer and pIndexID is a null pointer, the table identified by *pTableID is opened.

  • If pTableID is a null pointer and pIndexID is not a null pointer, *pIndexID must uniquely and fully identify an index; this index is opened. If *pIndexID does not uniquely and fully identify an index, DB_E_NOINDEX is returned.

  • If neither pTableID nor pIndexID is a null pointer, *pIndexID must identify an index for the table identified by *pTableID; this index is opened. If *pIndexID does not identify an index for the table identified by *pTableID, DB_E_NOINDEX is returned.

  • If both pTableID and pIndexID are null pointers, E_INVALIDARG is returned.

The threading model of the returned rowset is determined by the property DBPROP_ROWTHREADMODEL.

OpenRowset has security considerations that need to be reviewed before implementation. For more information, see OLE DB Security Best Practices.

Programming Considerations

This method may be used to obtain a histogram rowset for a specified table to complement additional information found in the TABLE_STATISTICS schema rowset. Provider support for histogram rowsets is indicated by the DBPROP_TABLESTATISTICS and DBPROP_OPENROWSETSUPPORT properties. A conceptual overview of this feature is provided in the Special-Purpose Rowsets section of Overview of OLE DB.

To retrieve a histogram rowset, the following parameters are set:

  • The pTableID parameter indicates the base table on which the histogram is defined.

  • The pIndexID parameter points to a DBID structure where the members are set as follows:

    • The uGUID member of the DBID structure is set to DBGUID_HISTOGRAM_ROWSET.

    • The pwszName member of the DBID structure is set to the name of the desired histogram statistic. The consumer and provider must have previously agreed to use this name. (This is the same name reported in the STATISTICS_NAME column of the TABLE_STATISTICS schema rowset.)

See Also

Reference

IDBCreateCommand::CreateCommand