This is the documentation for SuperSTAR 9.8

SuperSTAR 9.9 is now available.
View this page in the SuperSTAR 9.9 documentation or visit the SuperSTAR 9.9 documentation home.

Skip to end of metadata
Go to start of metadata

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:

FunctionCalled...
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:

FunctionCalled...
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:

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:

typedef struct
    {
        int                          m_JobNumber;
        struct SCallbacks*           m_Callbacks;
        void*                        m_PublicData;
        struct SJobImpl*             m_PrivateData;
} JobInfoT;
ParameterDescription
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.

  • No labels