Skip to end of metadata
Go to start of metadata

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
FirstCellT(JobInfoT *JobInfo)
Arguments
JobInfoInputInformation about the current job.
Returns
1Cells are available.
0No cells are available.

EndCellT()

Test whether the current cell is the last in the iteration of the cube.

Available To
PrepareJob
PerformJob
CleanUpJob
EndCellT(JobInfoT *JobInfo)
Arguments
JobInfoInputInformation about the current job.
Returns
1No more cells are available (this is the last cell in the iteration).
0More 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
NextCellT(JobInfoT *JobInfo)
Arguments
JobInfoInputInformation about the current job.
Returns
1Another cell is available.
0No 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
GetCurrentCellValueT(JobInfoT *JobInfo, double *Value)
Arguments
JobInfoInputInformation about the current job.
ValueOutputThe cell value.
Returns
1Success.
0The value could not be retrieved.

GetCurrentCellSummationOffsetT()

Retrieve the position of the current cell's summation.

Available To
PrepareJob
PerformJob
CleanUpJob
GetCurrentCellSummationOffsetT(JobInfoT *JobInfo, int *Value)
Arguments
JobInfoInputInformation about the current job.
ValueOutputThe offset of the current cell's summation.
Returns
1Success.
0The value could not be retrieved.

GetCurrentCellOffsetT()

Retrieve the position of the current cell within the cube.

Available To
PrepareJob
PerformJob
CleanUpJob
GetCurrentCellOffsetT(JobInfoT *JobInfo, int *Value)
Arguments
JobInfoInputInformation about the current job.
ValueOutputThe current cell's unique position.
Returns
1Success.
0The 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
SetCurrentCellValueT(JobInfoT *JobInfo, double Value)
Arguments
JobInfoInputInformation about the current job.
ValueInputThe cell value to set.
Returns
1Success.
0The value could not be set.

IsCurrentCellNullT()

Test whether the current cell is null.

Available To
PrepareJob
PerformJob
CleanUpJob
IsCurrentCellNullT(JobInfoT *JobInfo)
Arguments
JobInfoInputInformation about the current job.
Returns
1The current cell is null.
0The current cell is not null.

GetValueCodesOfCurrentCellThenFreeMemT()

Retrieve the classification value codes that are related to the current cell.

Available To
PrepareJob
PerformJob
CleanUpJob
GetValueCodesOfCurrentCellThenFreeMemT(JobInfoT *JobInfo, int Dimension, int FieldOffset, const SourceValueInfoT** Values, int* Len)
Arguments
JobInfoInputInformation about the current job.
DimensionInputThe dimension index within the data cube.
FieldOffsetInputThe field index within this dimension to return the value codes for.
ValuesOutput

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.

LenOutputThe size of the returned array.
Returns
1Success.
0The 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
GetCurrentCellAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, double *Value)
Arguments
JobInfoInputInformation about the current job.
AssociationNameInputThe name of the association.
ValueOutputThe value.
Returns
1Success.
0The operation failed.

SetCurrentCellAssociatedValueT()

Set the associated value for the given association for the current cell.

Available To
PrepareJob
PerformJob
CleanUpJob
SetCurrentCellAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, double Value)
Arguments
JobInfoInputInformation about the current job.
AssociationNameInputThe name of the association.
ValueInputThe value.
Returns
1Success.
0The operation failed.

GetCurrentCellNthAssociatedValueT()

Retrieve the nth associated value from within the given association for the current cell.

Available To
PrepareJob
PerformJob
CleanUpJob
GetCurrentCellNthAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, int Pos, double* Value)
Arguments
JobInfoInputInformation about the current job.
AssociationNameInputThe name of the association.
PosInputThe position of the association to retrieve.
ValueOutputThe value.
Returns
1Success.
0The operation failed.

SetCurrentCellNthAssociatedValueT()

Set the nth associated value for the given association for the current cell.

Available To
PrepareJob
PerformJob
CleanUpJob
SetCurrentCellNthAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, int Pos, double Value)
Arguments
JobInfoInputInformation about the current job.
AssociationNameInputThe name of the association.
PosInputThe position of the association to set.
ValueInputThe value to set.
Returns
1Success.
0The 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
GetCellValueT(JobInfoT *JobInfo, int *DimensionItems, double *Value)
Arguments
JobInfoInputInformation about the current job.
DimensionItemsInput

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.

ValueOutputThe value of the specified cell.
Returns
1Success.
0The operation failed.

IsCellNullT()

Determine whether the specified cell is null.

Available To
PrepareJob
PerformJob
CleanUpJob
IsCellNullT(JobInfoT *JobInfo, int* DimensionItems, int *Null) 
Arguments
JobInfoInputInformation about the current job.
DimensionItemsInput

An array of dimension item indexes identifying a cell in the data cube.

NullOutputWhether the value of the specified cell is null.
Returns
1Success.
0The operation failed.

SetCellValueT()

Set the value of the specified cell.

Available To
PrepareJob
PerformJob
CleanUpJob
SetCellValueT(JobInfoT *JobInfo, int* DimensionItems, double Value)
Arguments
JobInfoInputInformation about the current job.
DimensionItemsInput

An array of dimension item indexes identifying a cell in the data cube.

ValueInputThe value to set.
Returns
1Success.
0The operation failed.

GetCellAssociatedValueT()

Retrieve the associated value from within a given association cube for the current cell.

Available To
PrepareJob
PerformJob
CleanUpJob
GetCellAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, const int Pos, const int* DimensionItems, double *Value)
Arguments
JobInfoInputInformation about the current job.
AssociationNameInputThe name of the association.
DimensionItemsInput

An array of dimension item indexes identifying a cell in the data cube.

PosInputThe nth result of an association.
ValueOutputThe value.
Returns
1Success.
0The operation failed.

SetCellAssociatedValueT()

Set the associated value from within a given association cube for the current cell.

Available To
PrepareJob
PerformJob
CleanUpJob
SetCellAssociatedValueT(JobInfoT *JobInfo, const char* AssociationName, const int Pos, const int* DimensionItems, double Value)
Arguments
JobInfoInputInformation about the current job.
AssociationNameInputThe name of the association.
DimensionItemsInput

An array of dimension item indexes identifying a cell in the data cube.

PosInputThe nth result of an association.
ValueInputThe value to set.
Returns
1Success.
0The 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
ConvertAbsoluteToRelativeItemIndexT(JobInfoT* jobInfo, const int dimension, const int absoluteIndex, int* fieldIndex, int* itemIndex)
Arguments
JobInfoInputInformation about the current job.
dimensionInputThe dimension index.
absoluteIndexInput

The absolute item index.

fieldIndexOutputThe field index.
itemIndexOutputThe item index.
Returns
1Success.
0The 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
ConvertRelativeToAbsoluteItemIndexT(JobInfoT* jobInfo, const int dimension, const int fieldIndex, const int itemIndex, int* absoluteIndex)
Arguments
JobInfoInputInformation about the current job.
dimensionInputThe dimension index.
fieldIndexInputThe field index.
itemIndexInputThe item index.
absoluteIndexOutput

The absolute item index.

Returns
1Success.
0The operation failed.
  • No labels