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 are called once for each cross tabulation job request:

Function	Called...
PrepareJob	When a cross tabulation job is received but before SuperSERVER performs the cross tabulation.
PerformJob	After cross tabulation has been performed by SuperSERVER. This function should carry out any work that involves modifying tabulation results.
CleanupJob	After all tabulation work is complete. Any memory allocated in `PrepareJob` or `PerformJob` should be de-allocated in `CleanupJob`.

Return codes

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

If a module returns a 0 value from 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.

Job Information

The first parameter passed to all functions is the JobInfoT struct.

CPP

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

This struct holds several pieces of information:

Parameter	Description
m_JobNumber	Unique identifier for the job.
m_Callbacks	`Struct` of function pointers to callback functions to manipulate the cross tabulation data. For more information see Module Callback API.
m_PublicData	Void pointer that may be used by a module to store any intermediate data it requires.
m_PrivateData	Private information used by SuperSERVER to manage jobs and modules. Not to be used by client code.

The JobInfoT parameter must be passed back to all callback functions called by the module.