The Data Control callback interface provides functions to assist in navigating cells in the data cube.
Iterator Functions
The Iterator will visit all cells in the data cube. Using the iterator functions is the recommended method of navigating the data cube as it allows SuperSERVER to implement data cube navigation efficiently.
FirstCellT()
Move to the first cell in the data cube.
For a 3 dimensional cube, resets the location to [0][0][0].
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
FirstCellT(JobInfoT *JobInfo)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
|
|---|
| Returns | | 1 | Cells are available. |
|---|
| 0 | No cells are available. |
|---|
|
|---|
EndCellT()
Test whether the current cell is the last in the iteration of the cube.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
EndCellT(JobInfoT *JobInfo)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
|
|---|
| Returns | | 1 | No more cells are available (this is the last cell in the iteration). |
|---|
| 0 | More cells are available. |
|---|
|
|---|
NextCellT()
Moves the iterator to the next cell of the cube.
When calling NextCell for the first time after FirstCell, the iterator location will move to [0][0][1].
Once all cells in a particular dimension have been visited, that dimension's index is reset to zero and the following dimension's index will be incremented by one. For example [0][1][0].
When all cells have been visited (the last cell of the data cube is passed), this function returns 0.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
NextCellT(JobInfoT *JobInfo)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
|
|---|
| Returns | | 1 | Another cell is available. |
|---|
| 0 | No more cells are available. |
|---|
|
|---|
Cell Values
The following functions are used to access the current cell (the cell currently iterated to using the FirstCell() and NextCell() function calls).
GetCurrentCellValueT()
Retrieve the current cell value.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetCurrentCellValueT(JobInfoT *JobInfo, double *Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Value | Output | The cell value. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The value could not be retrieved. |
|---|
|
|---|
GetCurrentCellSummationOffsetT()
Retrieve the position of the current cell's summation.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetCurrentCellSummationOffsetT(JobInfoT *JobInfo, int *Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Value | Output | The offset of the current cell's summation. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The value could not be retrieved. |
|---|
|
|---|
GetCurrentCellOffsetT()
Retrieve the position of the current cell within the cube.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetCurrentCellOffsetT(JobInfoT *JobInfo, int *Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Value | Output | The current cell's unique position. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The value could not be retrieved. |
|---|
|
|---|
SetCurrentCellValueT()
Set the value of the current cell. This operation will fail if the cell is marked as concealed.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
SetCurrentCellValueT(JobInfoT *JobInfo, double Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Value | Input | The cell value to set. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The value could not be set. |
|---|
|
|---|
IsCurrentCellNullT()
Test whether the current cell is null.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
IsCurrentCellNullT(JobInfoT *JobInfo)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
|
|---|
| Returns | | 1 | The current cell is null. |
|---|
| 0 | The current cell is not null. |
|---|
|
|---|
GetValueCodesOfCurrentCellThenFreeMemT()
Retrieve the classification value codes that are related to the current cell.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetValueCodesOfCurrentCellThenFreeMemT(JobInfoT *JobInfo, int Dimension, int FieldOffset, const SourceValueInfoT** Values, int* Len)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Dimension | Input | The dimension index within the data cube. |
|---|
| FieldOffset | Input | The field index within this dimension to return the value codes for. |
|---|
| Values | Output | The returned value codes. The lifetime of the returned value may last up to the next API function call. However, if client code wants to maintain the returned value in the scope of the tabulation job then the client must make a copy of the returned value. |
|---|
| Len | Output | The size of the returned array. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
If the operation is successful, but the result set is empty, then Len will be set to zero and Values will be NULL. |
|---|
GetCurrentCellAssociatedValueT()
Retrieve the associated value from within a given association cube for the current cell.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetCurrentCellAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, double *Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| AssociationName | Input | The name of the association. |
|---|
| Value | Output | The value. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
SetCurrentCellAssociatedValueT()
Set the associated value for the given association for the current cell.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
SetCurrentCellAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, double Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| AssociationName | Input | The name of the association. |
|---|
| Value | Input | The value. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
GetCurrentCellNthAssociatedValueT()
Retrieve the nth associated value from within the given association for the current cell.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetCurrentCellNthAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, int Pos, double* Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| AssociationName | Input | The name of the association. |
|---|
| Pos | Input | The position of the association to retrieve. |
|---|
| Value | Output | The value. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
SetCurrentCellNthAssociatedValueT()
Set the nth associated value for the given association for the current cell.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
SetCurrentCellNthAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, int Pos, double Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| AssociationName | Input | The name of the association. |
|---|
| Pos | Input | The position of the association to set. |
|---|
| Value | Input | The value to set. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
Direct Cell Access
Using the iterator is the preferred method of cell access. However, the following functions allow direct access to specific cells. They are supplied for scenarios where an implementation only requires direct access to a subset of well-known cells, rather than iterating through the entire cube.
GetCellValueT()
Retrieve the value of the specified cell.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetCellValueT(JobInfoT *JobInfo, int *DimensionItems, double *Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| DimensionItems | Input | An array of dimension item indexes identifying a cell in the data cube. This should contain the same number of elements as returned by the GetDimensionCount() function call. |
|---|
| Value | Output | The value of the specified cell. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
IsCellNullT()
Determine whether the specified cell is null.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
IsCellNullT(JobInfoT *JobInfo, int* DimensionItems, int *Null)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| DimensionItems | Input | An array of dimension item indexes identifying a cell in the data cube. |
|---|
| Null | Output | Whether the value of the specified cell is null. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
SetCellValueT()
Set the value of the specified cell.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
SetCellValueT(JobInfoT *JobInfo, int* DimensionItems, double Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| DimensionItems | Input | An array of dimension item indexes identifying a cell in the data cube. |
|---|
| Value | Input | The value to set. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
GetCellAssociatedValueT()
Retrieve the associated value from within a given association cube for the current cell.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetCellAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, const int Pos, const int* DimensionItems, double *Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| AssociationName | Input | The name of the association. |
|---|
| DimensionItems | Input | An array of dimension item indexes identifying a cell in the data cube. |
|---|
| Pos | Input | The nth result of an association. |
|---|
| Value | Output | The value. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
SetCellAssociatedValueT()
Set the associated value from within a given association cube for the current cell.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
SetCellAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, const int Pos, const int* DimensionItems, double Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| AssociationName | Input | The name of the association. |
|---|
| DimensionItems | Input | An array of dimension item indexes identifying a cell in the data cube. |
|---|
| Pos | Input | The nth result of an association. |
|---|
| Value | Input | The value to set. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
Absolute to Relative Conversion
ConvertAbsoluteToRelativeItemIndexT()
Convert from an absolute index for a dimension to a field and item index. The absoluteIndex variable will be different to the itemIndex variable for concatenated fields.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
ConvertAbsoluteToRelativeItemIndexT(JobInfoT* jobInfo, const int dimension, const int absoluteIndex, int* fieldIndex, int* itemIndex)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| dimension | Input | The dimension index. |
|---|
| absoluteIndex | Input | The absolute item index. |
|---|
| fieldIndex | Output | The field index. |
|---|
| itemIndex | Output | The item index. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
ConvertRelativeToAbsoluteItemIndexT()
Convert from a field and item index to an absolute index for a dimension. The absoluteIndex variable will be different to the itemIndex variable for concatenated fields.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
ConvertRelativeToAbsoluteItemIndexT(JobInfoT* jobInfo, const int dimension, const int fieldIndex, const int itemIndex, int* absoluteIndex)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| dimension | Input | The dimension index. |
|---|
| fieldIndex | Input | The field index. |
|---|
| itemIndex | Input | The item index. |
|---|
| absoluteIndex | Output | The absolute item index. |
|---|
|
|---|
| Returns | | 1 | Success. |
|---|
| 0 | The operation failed. |
|---|
|
|---|
