Cell Operations

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.