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

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 is not being aggregated, it is a null pointer.

iAxis

[in]
The numeric identifier of an axis. OLE DB for OLAP defines the following manifest constants for commonly used axes: MDAXIS_COLUMNS, MDAXIS_ROWS, MDAXIS_PAGES, MDAXIS_SECTIONS, and MDAXIS_ CHAPTERS. These constants 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, the 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 were not set. The method can fail to set properties for a number of reasons, including the following:

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

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 was not zero and rgProperties was a null pointer.

E_NOINTERFACE

The axis rowset did not support the interface specified in riid.

MD_E_INVALIDAXIS

iAxis was not 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 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 stating that it was not cheap to set the property.

DB_E_NOAGGREGATION

pUnkOuter was not a null pointer, and the axis rowset does not 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 by using IMDDataset::GetCellData.

Additional columns may be present for a dimension if the following conditions apply:

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

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

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