MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Interfaces

IOpenRowset::OpenRowset

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

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 Structure" and "DBPROP Structure" in Chapter 14, “Properties.”

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 descrbed 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_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_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_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_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 table.

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.

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

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.

See Also

IDBCreateCommand::CreateCommand