Module Life Cycle - Data Control API

A Data Control module is a DLL or Shared Object that provides the custom implementation.

Each module must implement the interface defined in the externaldcmodule.h header file (if you have installed SuperSERVER to the default location, this is located in C:\ProgramData\STR\SuperSERVER SA\etc\include\externaldcmodule.h).

Functions

The following functions are called once for each loaded DLL for the lifetime of a SuperSERVER instance:

Function	Called...
Init	After SuperSERVER loads the DLL. Any initialisation required should be performed in this function.
Destroy	Just before SuperSERVER unloads the DLL. Any memory or resources allocated by the DLL should be disposed of in this function. Resources used in an individual "job" should be released by `CleanUpJob`. Only resources required for the entire lifetime the DLL is loaded should have their clean up deferred until the `Destroy` function is called.

The following functions can be called once for each cross tabulation job request:

Function	Called...
PreJob	Immediately prior to cross tabulation. This function can be used to: Check if the query is valid or not (and cancel the job if it is not valid). Modify the query by appending temporary summations, in order to perform necessary calculations in the `PerformJob` method. Add required options (such as FREQ) for use by the `PerformJob` method.
PrepareJob	After successful cross tabulation has been performed by SuperSERVER, but before `PerformJob`. This function can be used to do any initialisation and error checking.
PerformJob	After `PerformJob`. This function should carry out any work that involves modifying tabulation results.
CleanUpJob	After all tabulation work is complete, or when `PreJob` has been called but the job is cancelled. Any memory allocated in `PreJob`, `PrepareJob` or `PerformJob` should be de-allocated in `CleanUpJob`.

Return codes

A module may indicate a failure by returning zero from any of the functions described above.

If a module returns a 0 value from PreJob, PrepareJob or PerformJob the cross tabulation process will stop and no results will be returned to the end user.

If a non-zero value is returned, the cross tabulation process will continue as normal.

Memory Management

When using the Data Control API all resources allocated (malloc, fopen, ...) by a module must be cleaned up by that module.

Resources allocated for each job should be cleaned up in CleanUpJob() at the latest.

If resources are allocated and stored statically in the module they should be cleaned up in Destroy().

All pointers returned from SuperSERVER via callback functions will be cleaned up by SuperSERVER and must not be freed or deleted by any modules.

Thread Safety

The Data Control API does not support multiple threads in module code.

SuperSERVER is a multi-threaded application. Client programmers must take care when implementing modules to ensure that code that they write is thread safe.

In particular, ensure the use of 'static' storage within a module's implementation, and access to external systems, is protected against the impact of operating in a multi-threaded environment.

Job Information

The first parameter passed to PreJob is the PreJobInfoT struct:

CPP

typedef struct
    {
        int                          m_JobNumber;
        struct PreJobCallbacks*      m_Callbacks;
        struct SJobImpl*             m_PrivateData;
        void*                        m_PublicData;
} PreJobInfoT;

The first parameter passed to PrepareJob, PerformJob and CleanUpJob is the JobInfoT struct:

CPP

typedef struct
    {
        int                          m_JobNumber;
        struct SCallbacks*           m_Callbacks;
        void*                        m_PublicData;
        struct SJobImpl*             m_PrivateData;
} JobInfoT;

Parameter	Description
m_JobNumber	Unique identifier for the job.
m_Callbacks	`Struct` of function pointers to callback functions. For `PreJob` this can be used to manipulate the tabulation query. For the other methods this can be used to manipulate the cross tabulation data. For details of the available callback functions, see Module Callback API.
m_PublicData	Void pointer that may be used by a module to store any intermediate data it requires. It is client module's responsibility to clean up `m_PublicData` when `CleanUpJob` is called on a module. The data created in `PreJob` is available in `PrepareJob`, `PerformJob` and `CleanUpJob`.
m_PrivateData	Private information used by SuperSERVER to manage jobs and modules. Not to be used by client code.