Users can set the module configuration properties by modifying the method catalogue in SuperADMIN.
Your Data Control module can use the following functions to read these configuration properties.
It is also possible for your module to dynamically add or remove some properties. Some properties added by PreJob can modify the tabulation request, instead of adding them to the SuperADMIN catalogue. Properties added or removed by the post tabulation function do not affect the underlying entries in the catalogue and are only present for the duration of the tabulation request. You can use these facilities to allow a simple form of 'inter module' communication when multiple modules are configured for a particular tabulation request.
Pre Job Property Query and Manipulation
The following functions are available to PreJob. They allow your code to query or add property values before the cross tabulation is executed.
HasQueryPropertyKeyT()
Query the existence of a particular property key.
CPP
HasQueryPropertyKeyT(PreJobInfoT* JobInfo, const char* Key)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Key | Input | The property key to query. |
|---|
|
|---|
| Returns | | 1 | The key exists. |
|---|
| 0 | The key does not exist. |
|---|
|
|---|
GetQueryPropertyValuesT()
Query the property values of a particular property key. The property values (such as string, integer, or boolean) are all converted to string values. It is up to the client code to understand the value type correctly and convert it to the appropriate type.
CPP
GetQueryPropertyValuesT(PreJobInfoT* JobInfo, const char* Key, const char*** Values, int* Len)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Key | Input | The property key to query. |
|---|
| Values | Output | A list of strings containing the values of this property key. |
|---|
| Len | Output | The length of the values. |
|---|
|
|---|
| Returns | |
|---|
AddQueryPropertyValueT()
Add a boolean property value.
When adding a boolean property via AddQueryPropertyValueT() it is always set to true. It is not possible to disable the property by setting it to false.
CPP
AddQueryPropertyValueT(PreJobInfoT* JobInfo, const char* Key)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Key | Input | The property key to add the value to. The following keys are supported: - FREQ
- CELL_ERRORS
- COLLECTRKEY
- GrandTotalRequire
- RKEY
|
|---|
|
|---|
| Returns | | 1 | The property has been added. |
|---|
| 0 | The property has not been added (for example because it already exists). |
|---|
|
|---|
AddQueryIntegerPropertyValueT()
Add an integer property value.
CPP
AddQueryIntegerPropertyValueT(PreJobInfoT* JobInfo, const char* Key, unsigned int Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Key | Input | The property key to add the value to. TOPN is the only key that is currently supported.
|
|---|
| Value | Input | The value of the integer property. |
|---|
|
|---|
| Returns | | 1 | The property has been added. |
|---|
| 0 | The property has not been added (for example because it already exists). |
|---|
|
|---|
AddQueryLongIntegerPropertyValueT()
Add a long integer property value. This function allows you to set a value of the BigN key for use during perturbation.
CPP
AddQueryLongIntegerPropertyValueT(PreJobInfoT* JobInfo, const char* Key, unsigned int64 Value)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Key | Input | The property key to add the value to. BigN is the only key that is currently supported.
|
|---|
| Value | Input | The value of the long integer property. |
|---|
|
|---|
| Returns | | 1 | The property has been added. |
|---|
| 0 | The property has not been added (for example because it already exists). |
|---|
|
|---|
HasModuleConfigurationPropertyKeyT()
Query the existence of a specific property key for the current plugin.
CPP
HasModuleConfigurationPropertyKeyT(PreJobInfoT* JobInfo, const char* Key)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Key | Input | The property key. |
|---|
|
|---|
| Returns | | 1 | The key exists. |
|---|
| 0 | The key does not exist. |
|---|
|
|---|
GetModuleConfigurationPropertyValuesT()
Query the property values of a particular property key for the current plugin. The property values (such as string, integer, or boolean) are all converted to string values. It is up to the client code to understand the value type correctly and convert it to the appropriate type.
CPP
GetModuleConfigurationPropertyValuesT(PreJobInfoT* JobInfo, const char* Key, const char*** Values, int* Len)
| Arguments | | JobInfo | Input | Information about the current job. |
|---|
| Key | Input | The property key. |
|---|
| Values | Output | A list of strings containing the values of this property key. |
|---|
| Len | Output | The length of the values. |
|---|
|
|---|
| Returns | |
|---|
Post Job Property Query and Manipulation
The following functions allow your code to query and manipulate properties after the cross tabulation has been performed.
SetResultPropertyValueT()
Dynamically add a value to a configuration property.
Configuration properties can have multiple values associated with them.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
SetResultPropertyValueT(JobInfoT *JobInfo, const char *Key, const char* Value)
| Arguments | | JobInfo | Information about the current job. |
|---|
| Key | The property to set. |
|---|
| Value | The value to set for this property. |
|---|
|
|---|
| Returns | |
|---|
GetResultPropertyValuesT()
Get the value(s) of a configuration property.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetResultPropertyValuesT(JobInfoT *JobInfo, const char* Key, const char*** Values, int* Len)
| Arguments | | JobInfo | Information about the current job. |
|---|
| Key | The configuration property. |
|---|
| Values | The set of values of this property. |
|---|
| Len | The size of the value set. |
|---|
|
|---|
| Returns | |
|---|
GetFieldPropertiesT()
Get the value(s) for a given key for a given field.
For example, a summation field of income has had the average operation applied to it.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetFieldPropertiesT(JobInfoT *JobInfo, int Dimension, int FieldOffset, const char* Key, const char*** Values, int* Len)
| Arguments | | JobInfo | Information about the current job. |
|---|
| Dimension | The dimension index within the data cube. |
|---|
| FieldOffset | The field index within the dimension. |
|---|
| Key | The configuration property. |
|---|
| Values | The set of values for this field. |
|---|
| Len | The size of the value set. |
|---|
|
|---|
| Returns | |
|---|
SetFieldPropertyT()
Dynamically add a value to a configuration property for this field.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
SetFieldPropertyT(JobInfoT *JobInfo, int Dimension, int FieldOffset, const char* Key, const char* Value)
| Arguments | | JobInfo | Information about the current job. |
|---|
| Dimension | The dimension index within the data cube. |
|---|
| FieldOffset | The field index within the dimension. |
|---|
| Key | The configuration property. |
|---|
| Value | The value to set for this property. |
|---|
|
|---|
| Returns | |
|---|
GetDefaultSummationPropertiesT()
Get the property values for the default summation field.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
GetDefaultSummationPropertiesT(JobInfoT *JobInfo, const char* Key, const char*** Values, int* Len)
| Arguments | | JobInfo | Information about the current job. |
|---|
| Key | The configuration property. |
|---|
| Values | The set of values for the default summation field. |
|---|
| Len | The size of the value set. |
|---|
|
|---|
| Returns | |
|---|
SetDefaultSummationPropertyT()
Set a property value for the given key for the default summation field.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
SetDefaultSummationPropertyT(JobInfoT *JobInfo, const char* Key, const char* Value)
| Arguments | | JobInfo | Information about the current job. |
|---|
| Key | The configuration property. |
|---|
| Value | The value to set for this property. |
|---|
|
|---|
| Returns | |
|---|
RemoveResultPropertyValueT()
Remove the nominated value from the key. A key can have multiple values, but this function only removes the specified one.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
RemoveResultPropertyValueT(JobInfoT *JobInfo, const char *Key, const char* Value)
| Arguments | | JobInfo | Information about the current job. |
|---|
| Key | The configuration property. |
|---|
| Value | The value to remove. |
|---|
|
|---|
| Returns | |
|---|
RemoveResultPropertyT()
Remove all values and the associated key from the property list.
| Available To | PrepareJob | PerformJob | CleanUpJob |
|---|
CPP
RemoveResultPropertyT(JobInfoT *JobInfo, const char *Key)
| Arguments | | JobInfo | Information about the current job. |
|---|
| Key | The configuration property to remove. |
|---|
|
|---|
| Returns | |
|---|
Standard Properties
The following standard properties are defined for use by SuperSERVER:
Property | Type | Description |
|---|
FREQ | boolean (true/false) | The module requires SuperSERVER to produce an associated data cube containing contribution count information for each cell. Data is retrieved using the GetCurrentCellAssociatedValue() callback passing the association name as 'FREQ'.
The FREQ property (hence the FREQ cube) is affected by null handling. The FREQ cube contains the number of contributors. If there is a null field value that is contributing to a specific cell in the cube, then it may, or may not (depending on null configuration) be counted (by default, null values are not counted). This will mean a different number of contributors hence different values in the FREQ cube.
|
TOPN | integer (1+) | The module requires SuperSERVER to produce an associated data cube containing the values for the top n contributors for each cell. Data is accessed by client programmers using the GetCurrentCellNthAssociatedValue() callback. |
CONCEALMENT | | This is a special, well known, association name. Client programmers programmatically create this associated data cube by calling the AddAssociation() callback function and then set the associated cell value to 1 to indicate a cell should be hidden by using the SetCurrentCellAssociatedValue() callback passing the association name as "CONCEALMENT". |
ConfidentialityModule | boolean (true/false) | Indicates to SuperSERVER that this module applies confidentiality rules. SuperSERVER may block record view requests based on the setting of this property and the values of the 'CONCEALMENT' associated data cube. |
GrandTotalRequire | | Indicates to SuperSERVER that grand totals for all fields in the tabulation request be computed and present in the data cube prior to execution of an external module. During module execution, grand totals can be identified using the GetDimensionFieldItemType() callback function. Grand Totals added to the cube by SuperSERVER in this fashion will be removed from tabulation data prior to returning results to the User Interface client application. |
CELL_ERRORS | boolean (true/false) | The module requires SuperSERVER to produce an associated data cube containing a count of errors (or Nulls) for each cell. Data is retrieved using the GetCurrentCellNthAssociatedValue() callback passing the association name as 'CELL_ERRORS'. |
