IMDRangeRowset::
GetRangeRowset

Returns the range rowset for the desired set of cells in the dataset.

HRESULT GetRangeRowset(
   IUnknown*         pUnkOuter,
   ULONG               ulStartCell,
   ULONG               ulEndCell,
   REFIID            riid,
   ULONG               cPropertySets,
   DBPROPSET         rgPropertySets,
   IUnknown**         ppRowset);

Parameters

pUnkOuter[in]

A pointer to the controlling IUnknown if the range rowset is being created as part of an aggregate.

ulStartCell[in]

The cell ordinal of the first cell in the range.

ulEndCell[in]

The cell ordinal of the last cell in the range.

riid[in]

The IID of the requested rowset interface.

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 the value to be used is provider-specific.

ppRowset[out]

A pointer to memory in which to return the requested interface pointer on the range rowset.

Return Code

S_OK
The method succeeded. The status of all columns (cell properties) for all rows (cells) bound by the accessor is set to DBSTATUS_S_OK, DBSTATUS_S_ISNULL, or DBSTATUS_S_TRUNCATED.

DB_S_ERRORSOCCURRED
The rowset was opened but one or more properties — for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_SETIFCHEAP — 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 property was not supported by the provider.
  
  
• The property was not in the ROWSET property group.
  
  
• The property set was not supported by the provider.
  
  
• It was not cheap to set the property.
  
  
• colid in the DBPROP structure was invalid.
  
  
• The value of dwOptions in the DBPROP structure was invalid.
  
  
• The data type in vValue in the DBPROP structure was not the property 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.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
ulStartCell or ulEndCell is invalid.

ppRowset was a null pointer.

cPropertySets was greater than 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 range rowset did not support the interface specified in riid.

DB_E_ERRORSOCCURRED
No rowset was returned because one or more properties — for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED — were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. None of the properties are remembered. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED except for the reason that states that it was not cheap to set the property.

MD_E_INVALIDCELLRANGE
ulStartCell was greater than ulEndCell and ulEndCell was not zero.

ulStartCell, ulEndCell, or both specified a cell ordinal that was not in the dataset.

Comments

This method allows the retrieval of a range rowset based on a slice of the dataset. The consumer identifies the desired slice by specifying the ulStartCell and ulEndCell parameters. The ulStartCell parameter is the upper left corner of the slice and ulEndCell is the lower right corner of the slice. The slice of the dataset identified by these parameters is the same as that described for IMDDataset::GetCellData.

The range rowset contains one row for each cell in the slice. The first column of the this rowset is always CELL_ORDINAL. Subsequent columns are those that are selected in the creation of the dataset. If the provider supports cell updatability, then one or more columns of the range rowset can be updated. Typically, this includes the VALUE column.

For more information, see “Updating Cell Data” in Chapter 2.