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