Properties

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.

Available To	PreJob

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.

Available To	PreJob

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

1	Success.
0	Failed.

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.

Available To	PreJob

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.

Available To	PreJob

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.

Available To	PreJob

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.

Available To	PreJob

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.

Available To	PreJob

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

1	Success.
0	Failed.

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

1	Success.
0	Failed.

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

1	Success.
0	Failed.

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

1	Success.
0	Failed.

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

1	Success.
0	Failed.

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

1	Success.
0	Failed.

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

1	Success.
0	Failed.

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

1	Success.
0	Failed.

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

1	Success.
0	Failed.

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'.