IMDDataset::GetAxisRowset

Returns the specified axis rowset.

HRESULT GetAxisRowset(
   IUnknown*   pUnkOuter,
   ULONG         iAxis,
   REFIID      riid,
   ULONG         cPropertySets,
   DBPROPSET   rgPropertySets[],
   IUnknown**   ppRowset);

Parameters

pUnkOuter[in]

A pointer to the controlling IUnknown if the axis rowset is being created as part of an aggregate. If IMDDataset isn’t being aggregated, it is a null pointer.

iAxis[in]

The numeric identifier of an axis.

OLE DB for OLAP defines manifest constants for commonly used axes: MDAXIS_COLUMNS, MDAXIS_ROWS, MDAXIS_PAGES, MDAXIS_SECTIONS, and MDAXIS_ CHAPTERS. They denote (respectively) the columns, rows, pages, sections, and chapters axes. For the purposes of this function, the set of slicer dimensions is treated as a special axis and is identified by the constant MDAXIS_SLICERS.

riid[in]

The IID of the requested rowset interface.

cPropertySets[in]

The number of DBPROPSET structures in rgPropertySets. If this is 0, 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, which value to be used is provider-specific.

ppRowset[out]

A pointer to memory in which to return the requested interface pointer on the axis rowset. The returned rowset is read-only.

Return Code

S_OK
The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK.

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 weren’t set. The method can fail to set properties for a number of reasons, including:

• The property wasn’t supported by the provider.
  
  
• The property wasn’t in the rowset property group.
  
  
• The property set wasn’t supported by the provider.
  
  
• It wasn’t cheap to set the property.
  
  
• The colid value 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 wasn’t the data type of the property or wasn’t 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 couldn’t be applied to one or more columns.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
ppRowset was a null pointer.

cPropertySets was greater than 0 and rgPropertySets was a null pointer.

In an element of rgPropertySets, cProperties wasn’t zero and rgProperties was a null pointer.

E_NOINTERFACE
The axis rowset didn’t support the interface specified in riid.

MD_E_INVALIDAXIS
iAxis wasn’t a valid axis for this Dataset.

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 weren’t 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 wasn’t cheap to set the property.

DB_E_NOAGGREGATION
pUnkOuter wasn’t a null pointer and the axis rowset doesn’t support aggregation.

Comments

An axis rowset contains the name, display caption, level name, depth, and number of children for each tuple component or member along the axis. The axis rowset also contains a column that has the ordinal for each axis coordinate. This ordinal can be used when calculating the cell ordinal for fetching the cell data with.IMDDataset::GetCellData.

Additional columns may be present for a dimension if:

• The provider returns provider-specific columns.
  
  
• The consumer has requested to see member properties using the DIMENSION PROPERTIES clause in the SELECT statement.

rgcColumns in the MDAXISINFO structure points to an array containing the number of columns in the axis rowset for each constituent dimension.

The axis for which the rowset is requested is identified by its numeric identifier.

For a complete description of the columns in an axis rowset and their data types, see “Axis Rowsets” in Chapter 3.

The set of slicer dimensions is treated as a special axis and is identified by the axis identifier MDAXIS_SLICERS. Calling this method with iAxis set to MDAXIS_SLICERS returns information about the slicer dimensions in the form of an axis rowset. For more information, see “Finding Slicer Information” in Chapter 3.

If an error occurs, *ppRowset is set to NULL.