IScopedOperations::OpenRowset

OLE DB Programmer's Reference

Opens and returns a rowset containing the child rows of the current row or of a URL-named row within the scope of the current row. Due to interface and method factoring, IScopedOperations::OpenRowset is not inherited from IOpenRowset. However, it is the very same method, adapted for direct binding within the scope of the current row.

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

Parameters

pUnkOuter

[in]
If the rowset is to be aggregated, pUnkOuter is an interface pointer to the controlling IUnknown. Otherwise, it is a null pointer.

pTableID

[in]
The table ID (DBID) of the table to open. When implemented on row objects, this is an absolute or relative URL within the scope of the current row. If one of the following is true, pTableID designates the current row and the rowset will contain the child rows of this row:

pTableID is NULL.
pTableID is not NULL, pTableID->eKind is DBKIND_NAME, and pTableID->uName.pwszName is NULL.
pTableID is not null, pTableID->eKind is DBKIND_NAME, and pTableID->uName.pwszName is L"".

pIndexID

[in]
The DBID of the index to open. Not currently used in IScopedOperations. Consumers must set pIndexID to NULL. 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 in these structures must belong to the rowset property group. If the same property is specified more than once in rgPropertySets, the value used is provider-specific. If cPropertySets is zero, this argument is ignored.

For information about the rowset properties, see the rowset property group in Appendix C: OLE DB Properties. 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 IScopedOperations::OpenRowset fails, *ppRowset is set to a null pointer.

Return Code

S_OK

The method succeeded, and the rowset was opened.

DB_S_ASYNCHRONOUS

The method has initiated asynchronous creation of the rowset. The consumer can call IDBAsynchStatus to poll for status or can call 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:

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

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

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

DB_E_NOTABLE

The specified URL does not exist in the data store or does not reside within the scope of the current row.

DB_E_NOTCOLLECTION

pTableID specified a URL that does not name a collection.

pTableID was a null pointer or specified an empty string, and the current row is not a collection.

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_RESOURCEOUTOFSCOPE

pTableID named a URL that is not within the scope of the current row.

DB_SEC_E_PERMISSIONDENIED

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

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

pTableID is not NULL, and pTableID->eKind is not DBKIND_NAME.

ppRowset was a null pointer.

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

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

pIndexID was not NULL.

E_NOINTERFACE

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

E_OUTOFMEMORY

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

E_UNEXPECTED

ITransaction::Commit, ITransaction::Abort, or IScopedOperations::Delete (on this row) was called, and the object is in a zombie state.

Comments

The IScopedOperations::OpenRowset syntax was copied from IOpenRowset. However, pIndexID does not apply to rowsets, and the consumers must set it to NULL.

When invoking IScopedOperations::OpenRowset, a consumer can request asynchronous processing by setting a DBPROPVAL_ASYNCH_* bit of the DBPROP_ROWSET_ASYNCH property. When this flag is set, the provider returns immediately from the call to IScopedOperations::OpenRowset, returning either S_OK, if the operation has completed immediately, or DB_S_ASYNCHRONOUS, if the operation will continue asynchronously. Consumers can call IDBAsynchStatus::GetStatus to get the status of the operation or can register for progress notifications by passing the consumer's IDBAsynchNotify interface to the requested object's connection point. The consumer must explicitly request an asynchronous operation. Otherwise, IScopedOperations::OpenRowset does not return until the requested operation is completed. For more information on asynchronous processing in OLE DB, see Chapter 17: Asynchronous Processing.

If multiple IScopedOperations operations are invoked asynchronously on the same row object, the behavior of IDBAsynchStatus and IDBAsynchNotify is undefined.

See Also