IMDDataset::GetCellData

Returns the cell value, formatted value, cell ordinal number, and other requested properties of a range of cells.

Syntax

HRESULT GetCellData(
   HACCESSOR   hAccessor,
   DBORDINAL   ulStartCell,
   DBORDINAL   ulEndCell,
   VOID       *pData);

Parameters

• hAccessor
  [in] The handle of the accessor to use. If hAccessor is the handle of a null accessor, IMDDataset::GetCellData does not get any data or property values.

• ulStartCell
  [in] The cell ordinal of the first cell in the range.

• ulEndCell
  [in] The cell ordinal of the last cell in the range.

• pData
  [out] A pointer to the buffer in which to return the data. The consumer allocates memory for this buffer.

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 one of DBSTATUS_S_OK, DBSTATUS_S_ISNULL, or DBSTATUS_S_TRUNCATED.

• DB_S_ERRORSOCCURRED
  An error occurred while returning data for one or more columns (cell properties) in one or more rows (cells), but data was successfully returned for at least one property of one cell. To determine the cells or properties for which data was returned, the consumer checks the status values. For a list of status values that can be returned by this method, see Possible Return and Status Values, below.

• E_FAIL
  A provider-specific error occurred.

• E_INVALIDARG
  pData was a null pointer, and the accessor was not a null accessor.

  ulStartCell or ulEndCell is invalid.

• DB_E_BADACCESSORHANDLE
  hAccessor was invalid. Providers are not required to check for this condition, because doing so might slow the method significantly.

• DB_E_BADACCESSORTYPE
  The specified accessor was not a row accessor.

• DB_E_ERRORSOCCURRED
  Errors occurred while returning data for all properties of all cells. To determine what errors occurred, the consumer checks the status values. For a list of status values that can be returned by this method, see see Possible Return and Status Values, below.

• MD_E_INVALIDCELLRANGE
  cbRowSize of the IAccessor::CreateAccessor call that created hAccessor was 0, and ulStartCell was not equal to ulEndCell.

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

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

  If this method performs deferred accessor validation and that validation occurs before any data is transferred, it can also return, for the reasons listed in the corresponding DBBINDSTATUS values in IAccessor::CreateAccessor, any of the following return codes:

  • E_NOINTERFACE

  • DB_E_BADBINDINFO

  • DB_E_BADORDINAL

  • DB_E_BADSTORAGEFLAGS

  • DB_E_UNSUPPORTEDCONVERSION

Comments

This method enables the retrieval of a dataset slice. The consumer identifies the desired slice by specifying the ulStartCell and ulEndCell parameters; ulStartCell is the upper left corner of the slice, and ulEndCell is the lower right corner of the slice. Because these parameters are used to identify the slice, not all cells between ulStartCell and ulEndCell are necessarily fetched. This is illustrated in the following diagram of a two-axis dataset. The heavily outlined cells are the slice of the dataset identified by ulStartCell and ulEndCell*.* They are fetched. The shaded cells have ordinal values less than ulEndCell and greater than ulStartCell, but they are not fetched.

Determining Cell Ordinals

To facilitate navigation among cells, OLE DB for OLAP uses an ordinal value system to uniquely identify cells within a dataset. The ordinal value is computed from the tuple ordinals of the tuples forming the cell coordinates. The tuple ordinal is the zero-based distance of the tuple from the origin of that axis.

Conceptually, cells are numbered in a dataset as if the dataset were a p-dimensional array, where p is the number of axes. Cells are addressed in row-major order. The following illustration displays the formula for calculating the ordinal number of a cell:

Available Data

Each cell is treated as a row in a rowset, and cell properties are treated as columns. The actual properties available depend on the MDX statement that generated the dataset. For a detailed discussion of cell properties, see Retrieving Cell Properties. IColumnsInfo can also be used to discover the number of columns or properties available, and the name, data type, and so on.

Special Cases

If the consumer specifies zero for ulStartCell and a nonzero value for ulEndCell, the provider fetches the cells in the slice identified by the first cell in the dataset and the specified ending cell. If the consumer specifies a nonzero value for ulStartCell and zero for ulEndCell, the provider fetches the cells in the slice identified by the specified start cell and the last cell in the dataset. Except for this latter case, it is an error to have ulStartCell greater than ulEndCell.

If the consumer specifies a ulStartCell or ulEndCell value that falls outside the dataset, the method fails.

Possible Return and Status Values

As the provider returns cell data, it sets the status field of each bound property value buffer. Using this value, the consumer can determine which property values were successfully fetched.

Note

Consumers are strongly encouraged to bind to status values. If the status is other than DBSTATUS_S_OK, the provider is not obligated to touch the value part of the consumer's buffer.

The method produces return values as follows:

• Success. Return code is S_OK. No errors occurred while getting data for any properties. There may have been warnings (for example, data truncation warnings) when fetching property values for certain cells.

• Partial success. Return code is DB_S_ERRORSOCCURRED. There were errors while retrieving cell properties for one or more cells. At least one property value was successfully retrieved for at least one cell.

• Failure. Return code is DB_E_ERRORSOCCURRED. No property was successfully retrieved.

The following table lists all possible status values.

Status value	Success, warning, or error	Data returned	Description
DBSTATUS_S_OK	Success	Y	A non-NULL value was returned by the provider.
DBSTATUS_S_ISNULL	Success	Y	A NULL value was returned by the provider.
MDSTATUS_S_CELLEMPTY	Success	Y	The cell was empty. This occurs when there is no data in the cube at the coordinates of the cell. Using the NON EMPTY clause of the MDX statement guarantees that there are no empty cells.
DBSTATUS_S_TRUNCATED	Warning	Y	Variable-length data or nonsignificant digits of numeric data were truncated.
DBSTATUS_E_BADACCESSOR	Error	N	Accessor validation was deferred and was performed while the method returned data. The binding was invalid for this column or parameter.
DBSTATUS_E_CANTCONVERTVALUE	Error	N	The data value could not be converted for reasons other than sign mismatch or data overflow. For example, the data in the data store was corrupted but the row was still retrievable.
DBSTATUS_E_CANTCREATE	Error	N	One of the following conditions: The provider could not allocate memory in which to return data. The type indicator for the column was DBTYPE_IUNKNOWN, and a storage object was already open on the column. The type indicator for the column was DBTYPE_IUNKNOWN, the provider supports only one open storage object at a time (DBPROP_MULTIPLESTORAGEOBJECTS was VARIANT_FALSE), and a storage object was already open on the rowset.
DBSTATUS_E_DATAOVERFLOW	Error	N	Conversion failed because the data value overflowed the type specified for the value part in the consumer's buffer.
DBSTATUS_E_SIGNMISMATCH	Error	N	Conversion failed because the data value was signed and the type specified for the value part in the consumer's buffer was unsigned.
DBSTATUS_E_UNAVAILABLE	Error	N	Value could not be determined by the provider. For example, the row was just created, the default for the column was not available, and the consumer had not yet set a new value.

Errors During Cell Fetch

When fetching a range of cells, there can be errors in fetching a given column or property of a given row or cell. Examples of such errors include truncation and arithmetic overflow. This does not necessarily invalidate all the data fetched. Errors are localized to individual columns and are indicated in the STATUS part of the consumer's buffer for each column. This is a 2-byte field that contains manifest constants denoting different error and status indicators. The status indicators and their meanings are listed in Status Values Used When Getting Data.

Using cbRowSize of IAccessor::CreateAccessor

Because this method fetches properties for more than one cell, the provider should know how long each row is. In this context, a "row" means the area allocated in the consumer's buffer to hold all properties pertaining to one cell. This information should be given in the cbRowSize parameter of IAccessor::CreateAccessor. If the value of this parameter is zero, the consumer wants to fetch only one row of data (one cell). In this case, it is an error to specify a ulStartCell different from the ulEndCell.

The consumer's buffer for holding cell data must be laid out so that each row is directly adjacent to the next row. Within a row, the columns must be laid out at the offsets specified by the DBBINDING structure. Sufficient space must be allocated to fetch the requested number of cells. Consumers are advised to pad cbRowSize appropriately for machine alignment (Intel, 4-byte).