OpenSCADAWiki: Home Page En/Doc/API/part19
 

19. API of modules of modular subsystems

Modules in the OpenSCADA system are implemented as shared libraries. As it was previously mentioned, one such library can contain many modules of OpenSCADA subsystems, actually acting as a container.

The first step in connecting the shared (SO — shared object) libraries is the connection of the initialization functions. These functions should be defined as usual "C" functions to avoid distortion of function names. Usually this is done as follows:
//================== CUT =========================
extern "C"
{
#ifdef MOD_INCL
    //Need for define only at case builtin to OpenSCADA core support by the module
    TModule::SAt bd_DBF_module( int n_mod )
#else
    TModule::SAt module( int n_mod )
#endif
    {
    //Allowed into the shared object the modules descriptors forming
    }

#ifdef MOD_INCL
    //Need for define only at case builtin to OpenSCADA core support by the module
    TModule *bd_Tmpl_attach( const TModule::SAt &AtMod, const string &source )
#else
    TModule *attach( const TModule::SAt &AtMod, const string &source )
#endif
    {
    //Selected module connect
    }
}
//================== CUT =========================


Functions for the working with shared library:
TModule::SAt module( int n_mod );
The function is provided to sequentially poll the information about modules which are contained in the SO library. n_mod parameter indicates the serial number of the requested module and must be looked over, starting from zero. In the case of absence of the module with the given identifier the function must return the structure with the module name of zero length, that is the end of the scanning process.

TModule *attach( const TModule::SAt &AtMod, const string &source );
Connection to the specified module.

Actually all functions and data of the system are summarized in the API-systems described in this document. However, to simplify and accelerate the process of writing the modules the main function, redefined in modules, are listed in Table 22.

Table 22. The main functions used when creating the modules
Common API
Objects API (TCntrNode):
  • virtual void load_( ); — Object loading from storage.
  • virtual void save_( ); — Object saving into storage.
Common modules API (TModule):
Attributes:
  • string mId; — Module's ID.
  • string mName; — Module's name.
  • string mDescr; — Module's description.
  • string mType; — Module's type.
  • string mVers; — Module's version.
  • string mAutor; — Module's author.
  • string mLicense; — Module's license.
  • string mSource; — Module's source/origin.
Methods:
  • virtual void modStart( ); — Module's start.
  • virtual void modStop( ); — Module's stop.
  • virtual void modInfo( vector<string> &list ); — The list of available elements of information about the module. There are the following information elements:
    Module — module's ID;
    Name — localized module's name;
    Type — module's type;
    Source — module's source (container);
    Version — module's version;
    Author — module's author;
    Description — module's description;
    License — module's license.
  • virtual string modInfo( const string &name ); — Request of the specified information element.
  • virtual void perSYSCall( unsigned int cnt ); — Ρall from system thread, with period 10 seconds and seconds counter cnt.
  • void postEnable( int flag ); — Connecting the module to the dynamic tree of objects.
  • void modFuncReg( ExpFunc *func ); — Registration of the exported function.
API of the modules of the "DB" subsystem.
DB type (child from TTypeBD):
  • virtual TBD *openBD( const string &id ); — Open/create DB.
DB (child from TBD):
  • virtual void enable( ); — DB enable.
  • virtual void disable( ); — DB disable.
  • virtual void allowList( vector<string> &list ) const; — Tables' list in the DB.
  • virtual void sqlReq( const string &req, vector< vector<string> > *tbl = NULL, char intoTrans = EVAL_BOOL ); — Sending the SQL-request req to the DB and receiving the result in tabular form tbl. If set intoTrans to true then will open transaction for the request, else if set to false then transaction will close.
  • virtual void transCloseCheck( ); — The function call periodic for opened transaction check to close for old transaction or overloaded.
  • virtual TTable *openTable( const string &table, bool create ); — Open/create the table.
Table (child from TTable):
  • virtual void fieldStruct( TConfig &cfg ); — Getting the table's structure.
  • virtual bool fieldSeek( int row, TConfig &cfg ); — Sequential scan of the table fields.
  • virtual void fieldGet( TConfig &cfg ); — Getting the specified field.
  • virtual void fieldSet( TConfig &cfg ); — Setting the specified field.
  • virtual void fieldDel( TConfig &cfg ); — Deleting the specified field.
API of the modules of subsystem "Transports".
Transport's type (child from TTypeTransport):
  • virtual TTransportIn *In( const string &name, const string &db ); — Create/open new "incoming" transport.
  • virtual TTransportOut *Out( const string &name, const string &db ); — Create/open new "outgoing" transport.
Incoming transport (child from TTransportIn):
  • virtual string getStatus( ); — Interface status.
  • virtual void setAddr( const string &addr ); — The transport address set. It would be redefined for processing and checking for specific to the module transport's address format.
  • virtual void start(); — Transport's start.
  • virtual void stop(); — Transport's stop.
Outgoing transport (child from TTransportOut):
  • virtual string getStatus( ); — Interface status.
  • virtual void setAddr( const string &addr ); — The transport address set. It would be redefined for processing and checking for specific to the module transport's address format.
  • virtual void start( ); — Transport's start.
  • virtual void stop( ); — Transport's stop.
  • virtual int messIO( const char *obuf, int len_ob, char *ibuf = NULL, int len_ib = 0, int time = 0 ); — Sending data via the transport. Timeout time of the connection is indicated in milliseconds.
API of the modules of subsystem "Protocols".
Protocol (child from TProtocol):
  • virtual void itemListIn( vector<string> &ls, const string &curIt = "" ); — The input protocol subelements list, at case the protocol allow. Used for select in object of input transport configuration.
  • virtual void outMess( XMLNode &io, TTransportOut &tro ); — Data transfer in the XML tree in to the remote system by means of transport tro and the current outgoing protocol.
  • virtual TProtocolIn *in_open( const string &name ) — Open/create the incoming protocol.
Incoming protocol (child from TProtocolIn):
  • virtual bool mess( const string &request, string &answer, const string &sender ); — Transfer of unstructured message to the protocol.
API of the modules of "Data acquisition" subsystem.
Controller's type (child from TTypeDAQ):
  • virtual void compileFuncLangs( vector<string> &ls ); — The list of user programming languages that are supported by the module.
  • virtual void compileFuncSynthHighl( const string &lang, XMLNode &shgl ); — Syntax highlight rules shgl request for user programming language lang.
  • virtual string compileFunc( const string &lang, TFunction &fnc_cfg, const string &prog_text ); — Compilation of the user procedure and creation of the object of function's execution for the specified language of user programming.
  • virtual bool redntAllow( ); — The sign of support of the redundancy mechanisms by the module. Should by simply redefined and return true.
  • virtual TController *ContrAttach( const string &name, const string &daq_db ); — Opening/connection of the controller.
Controller (child from TController):
  • virtual string getStatus( ); — Call for specific controller status get.
  • virtual void enable_( ); — Controller enable.
  • virtual void disable_( ); — Controller disable.
  • virtual void start_( ); — Controller's start.
  • virtual void stop_( ); — Controller's stop.
  • virtual void redntDataUpdate( bool firstArchiveSync = false ); — An operation of the data receiving from the redundant station execution. It is called automatically by the service task of the redundancy scheme and before starting to synchronize the archives with the parameter firstArchiveSync set.
  • virtual TParamContr *ParamAttach( const string &name, int type ); — Creation/opening of the new parameter.
Controller's parameter (child from TParamContr->TValue):
  • virtual void enable( ); — Enable parameter.
  • virtual void disable( ); — Disable parameter.
  • virtual void setType( const string &tpId ); — Is called to change the parameter type tpId and can be processed in the object module for self data change.
  • virtual TVal* vlNew( ); — Call at new attribute creation. Would be redefined for specific behavior into self, inherited from TVal, class at accessing to attribute.
  • virtual void vlSet( TVal &val, const TVariant &pvl ); — Call for attribute into direct write mode TVal::DirWrite (synchronous mode or writing to internal object's buffer) at a value set, for direct writing to physical controller or object's buffer.
  • virtual void vlGet( TVal &val ); — Call for attribute into direct read mode TVal::DirRead (synchronous mode or reading from internal object's buffer) at a value get, for direct reading from physical controller or object's buffer.
  • virtual void vlArchMake( TVal &val ); — Call at a value archive creation with attribute val as the source for quality properties initialization to archive's buffer according with specific of data source and its acquisition.
API of the modules of the "Archives" subsystem.
Archiver's type (child from TTypeArchivator):
  • virtual TMArchivator *AMess(const string &id, const string &db ); — Creation of the messages' archive.
  • virtual TVArchivator *AVal(const string &id, const string &db ); — Creation of the messages' archiver.
Messages' archiver (child from TMArchivator):
  • virtual void start( ); — Archiver's start.
  • virtual void stop( ); — Archiver's stop.
  • virtual time_t begin( ); — The beginning of the data in the archive.
  • virtual time_t end( ); — The end of the data in the archive.
  • virtual void put( vector<TMess::SRec> &mess ); — Put the message to the archiver.
  • virtual void get( time_t b_tm, time_t e_tm, vector<TMess::SRec> &mess, const string &category = "", char level = 0, time_t upTo = 0 ); — Get the message from the archiver.
Values' archiver (child from TVArchivator):
  • virtual void setValPeriod( double per ); — Set the periodicity of the archiver's values.
  • virtual void setArchPeriod( int per ); — Set the archiving periodicity.
  • virtual void start( ); — Start the archiver.
  • virtual void stop( bool full_del = false ); — Stop the archiver with the possibility of complete deleting if the full_del flag is set.
  • virtual TVArchEl *getArchEl( TVArchive &arch ); — Getting the arch archive, which is served by the archiver.
An archive element of values (child from TVArchEl):
  • virtual void fullErase( ); — Complete deleting of the part of archive in the archiver.
  • virtual int64_t end( ); — End time of the archive in the archiver.
  • virtual int64_t begin( ); — Start time of the archive in the archiver.
  • virtual TVariant getValProc( int64_t *tm, bool up_ord ); — Request processing function of the single value from the archive.
  • virtual void getValsProc( TValBuf &buf, int64_t beg, int64_t end ); — Function of the request processing by the module to get data group values buf for set time interval.
  • virtual void setValsProc( TValBuf &buf, int64_t beg, int64_t end ); — Function of the request processing by the module to set data values buf for set time interval.
API of the modules of subsystem "User interfaces".
User interface (child from TUI):
It does not contain specific functions!
API μξδσλει οξδρθρςεμϋ "Ροεφθΰλόνϋε”.
Specials (child from TSpecial):
It does not contain specific functions!