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, then 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 11.

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 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 may not be available on the object until asynchronous initialization of the rowset has completed.

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:

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.

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 prgPropertySets 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 except the reason that states that it was not possible to set the property.

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 rowset being created does not support aggregation.

pUnkOuter was non-null and riid was not IID_Unknown.

DB_E_NOINDEX
The specified index does not exist in the current data source 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 current data source.

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.

Consumers must supply fully qualified names as pTableID on providers that support catalog or schema names. For more information, see "Fully Qualified Names," Chapter 4.

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

See Also

IDBCreateCommand::CreateCommand