OpenSCADAWiki: Home Page En/Doc/API/part2 ...

2. The overall structure of the system. Modularity (TSubSYS, TModule)

The root, from which we construct the whole system is the object of TSYS. The root contains a subsystem (TSubSYS). Subsystems can be: the ordinary and modular. The difference between the modular subsystems is clearly shown in Fig. 1. Thus, the modular subsystems necessarily contain a list of modular structures (TModule), such as subsystem TArchiveS contain modular objects TTipArchivator. At the same time, the normal subsystem does not contain such objects. For example TSesurity subsystem (Figure 2).

Fig. 2. Hierarchical structure of OpenSCADA.

In the process of initializing the root (TSYS) the global variable SYS is defined. The variable SYS can be used for direct access to the root of the system from any of its node. Initialization of the root is performed only one time from the main calling function. After starting the management is captured by the system object till stop. The root object concentrate all system functions of the OpenSCADA system.

Extension of the root object (TSYS) is the object TMess, which performs the functions of service of the flow of system messages. The object is accessible through the global variable Mess, which is initialized by the root of the system. The object contains the functions of encoding, decoding, and localization of messages.

In the subsystems (TSubSYS) the functions typical for each subsystem individually with the general access for all subsystems are carried out through the object TSubSYS. Modular subsystem is able to extend its functionality by means of modules. For this purpose, modular subsystem provides access to the modules of its type in the form of modular objects.

Module is the component of the modular subsystem. In general, for all modules and subsystems, the module provides information about itself, its origin and export functions. Individual module implements the functionality according to its own needs.

2.1. The root object system (TSYS)

Data:
Information variables of the program:

• PACKAGE_LICENSE - Distribution license of the program
• PACKAGE_DESCR - Brief description of the program
• PACKAGE_AUTHOR - Author of the program
• PACKAGE_SITE - Web site of the program support

Methods for coding of symbol sequences (enum - TSYS::Code):

• PathEl - element of the path (the characters: '/' and '%' to the form '%2f');
• HttpURL - address of the browser (http url);
• Html - special characters for use in html;
• JavaSc - end of line character for JavaScript;
• SQL - SQL-query value;
• Custom - selective coding of the specified characters;
• base64 - Mime encoding in the standard Base64;
• FormatPrint - Coding/masking of the formating elements for functions like "printf";
• oscdID - coding of the nodes' identifiers.
• Bin - Encoding of the binary data in text and vice versa.
• Reverse - Invert the order of characters in the line.
• ShieldSimb - Shielded symbols like "\n" encoding to real code.

Types of representations of the integer in the function TSYS::int2str(), and TSYS::ll2str() (enum - TSYS::IntView):

• Dec - decimal;
• Oct - octal;
• Hex - hexadecimal.

Standard error codes in the OpenSCADA system (enum - TSYS::Errors):

• DBInit (1) - Error initializing the database;
• DBConn (2) - Error connecting to the database;
• DBInernal (3) - Internal error of the DB;
• DBRequest (4) - Error in the query to the database;
• DBOpen (5) - Error opening the database;
• DBOpenTable (6) - Error opening the table;
• DBClose (7) - Error closing the database;
• DBTableEmpty (8) - The database table is empty;
• DBRowNoPresent (9) - An entry in the table is missing.

Templates:

• TO_FREE - The value of the free object (NULL).
• STR_BUF_LEN - Standard length of string buffers in the OpenSCADA (3000).
• STD_WAIT_DELAY - Standard quantum of the waiting time cycles (100ms).
• STD_WAIT_TM - Standard interval of the event waiting.
• __func__ - The full name of the calling function.
• vmin (a,b) - Determination of the minimum value.
• vmax (a,b) - Definition of the maximum value.

Public methods:

• TSYS( int argi, char **argb, char **env ); — The initializing constructor.
• int start( ); — Start of the system. The function is finished only with the finishing of the system. The return code is returned.
• void stop( ); — The command of the system stop.
• int stopSignal( ); — The return code in the case of system shutdown. Can be used as a sign of «System shutdown» of the various subsystems.
• string id( ); — station ID.
• string name( ); — Localized name of the station.
• string user( ); — The system user on behalf of which the system is running .
• string host( ); — Host name for the station run.
• void list( vector<string> &list ); — A list of registered subsystems in the system.
• bool present( const string &name ); — Check the availability of the subsystem.
• void add( TSubSYS *sub ); — Add/registration of the subsystem.
• void del( const string &name ); — Removing the subsystem.
• AutoHD<TSubSYS> at( const string &name ); — Connection to the specified subsystem.
• AutoHD<TUIS> ui( ); — Direct access to the subsystem «User interfaces».
• AutoHD<TArchiveS> archive( ); — Direct access to the subsystem «Archives».
• AutoHD<TBDS> db( ); — Direct access to the subsystem «Databases».
• AutoHD<TControllerS> daq( ); — Direct access to the subsystem «Data acquisition».
• AutoHD<TProtocolS> protocol( ); — Direct access to the subsystem «Protocols».
• AutoHD<TTransportS> transport( ); — Direct access to the subsystem «Transports».
• AutoHD<TSpecialS> special( ); — Direct access to the subsystem «special».
• AutoHD<TModSchedul> modSchedul( ); — Direct access to the subsystem «Module».
• AutoHD <TSesurity> sesurity( ); — Direct access to the subsystem «Security».
• string workDir( ); — Working directory of the station.
• string icoDir( ); — Directory of the icons of OpenSCADA.
• string modDir( ); — Directory of the modules of OpenSCADA.
• void setWorkDir( const string &wdir ); — Setting the working directory of the station.
• void setIcoDir( const string &idir ); — Specifying of the directory of icons of OpenSCADA.
• void setModDir( const string &mdir ); — Specifying the directory of modules of OpenSCADA.
• string cfgFile( ); — Name of configuration file of the system.
• XMLNode &cfgRoot( ); — Parsed structure of the configuration file.
• XMLNode *cfgNode( const string &path, bool create = false ); — Node of configuration getting by it path <path>. Elements of the path creation by it miss <create>.
• void modifCfg( ); — Configuration mark to modification, for next saving to file.
• string workDB( ); — The full name of the working database.
• string selDB( ); — Chosen DB. Used for selective loading from the specified database in the subsystem «DB».
• bool chkSelDB( const string &wDB ); — The function of checking for compliance of the specified database <wDB> with the selected selDB( ).
• void setWorkDB( const string &wdb ); — Setting of the full name of the working database.
• void setSelDB( const string &vl ); — Installation of the selected database for the specified boot.
• bool saveAtExit( ); — Sign - «Save configuration on exit».
• void setSaveAtExit( bool vl ); — Setting of the sign - «Save configuration on exit».
• int savePeriod( ); — Frequency of the automatically saving the station in the database (seconds).
• void setSavePeriod( int vl ); — Set the frequency of the automatically saving of the station to the database (seconds).
• string optDescr( ); — Localized help on the options of the command line and parameters of the configuration file.
• static void sighandler( int signal ); — Function of the default handler of the signals of the system as a whole.
• unsigned long long sysClk( ); — The estimated frequency of the processor on which the system works (Hz).
• void clkCalc( ); — Calculation of frequency of the processor on which the system works. It is called periodically for the systems with variable CPU frequency.
• unsigned long long shrtCnt( ); — The function of the measurement of small intervals of time by the counter of the CPU cycles. Returns the value of the counter of CPU cycles.
• static long HZ( ); — Time of the system teak of the CPU.
• bool cntrEmpty( ); — Debug counters checking to empty.
• double cntrGet( const string &id ); — Debug counter <id> getting.
• void cntrSet( const string &id, double vl ); — Debug counter <id> setting to value <vl>.
• void cntrIter( const string &id, double vl ); — Debug counter <id> iteration to value <vl>.
• void taskCreate( const string &path, int priority, void *(*start_routine)(void *), void *arg, int wtm = 5, pthread_attr_t *pAttr = NULL, bool *startSt = NULL ); — Create task (thread) with id <path>, priority <priority> (-1...99), task's function <start_routine> and it argument <arg>, and also wait for user's code start by flag <startSt>.
• void taskDestroy( const string &path, bool *endrunCntr = NULL, int wtm = 5, bool noSignal = false ); — Destroy task with id <path>, start control flag <startCntr>. Use <noSignal> for exclude signal SIGALRM send to the task.
• static int sysSleep( float tm ); — System sleep in seconds up to nanoseconds (1e-9).
• static long long curTime( ); — The actual time in microsecond from the beginning of the era (01.01.1970).
• static void taskSleep( long long per, time_t cron=0 ); — The function of the flow sleep by the grid of absolute time with the period <per> in the nanosecond or for the scheduled time <cron>.
• static time_t cron( const string &vl, time_t base=0 ); — Planning the execution time on the format of the standard Cron <vl> beginning at the basic time <base> or at the current time if the base is not specified.
• static bool eventWait( bool &m_mess_r_stat, bool exempl, const string &loc, time_t time=0 ); — Function of the event waiting <exempl> for the variable <m_mess_r_stat> within a specified time interval <time> for the source <loc>.
• static string int2str( int val, IntView view=Dec ); — Transformation of a signed integer to the string of the type of view <view>.
• static string uint2str( unsigned val, IntView view=Dec ); — Transformation of unsigned integer to the string type of view <view>.
• static string ll2str( long long val, IntView view=Dec ); — Transformation of a long integer (64bit) to the string type of view <view>.
• static string real2str( double val, int prec=15, char tp='g'); — Real transformation with an accuracy <prec> signs and type <tp> to the string.
• static double realRound( double val, int dig=0, bool toint=false ); — Rounding the real number to the specified digit <dig> after the decimal point with the possibility of transformation to integer after rounding <toint>.
• static string time2str( time_t tm, const string &format ); — UNIX time <tm> conversion to string, by format <format> of POSIX-function strftime().
• static string time2str( double utm ); — Convert time interval to string like "1hour 23min 10sec".
• static string cpct2str( double cnt ); — Traffic counter <cnt> (bytes) convert to string like "12.5KiB".
• static string addr2str( void *addr ); — Convert addresses into string.
• static void *str2addr( const string &str ); — Convert string into the address.
• static string strNoSpace( const string &val ); — Deletes from the original string <val> empty characters at the beginning and end of it.
• static string strSepParse( const string &path, int level, char sep, int *off=NULL ); — Parsing of the string <path> into the components separated by the dividing symbol <sep>, beginning with the offset <off> and controlling the offset of the element end in itself.
• static string strParse( const string &str, int level, const string &sep, int *off = NULL, bool mergeSepSymb = false ); — Parse function's strSepParse() expanded version which allow using multi-symbols separators and one symbols merging.
• static string strLine( const string &str, int level, int *off = NULL ); — Parsing text lines for different ways to the end of a line (CR, LF and CR/LF).
• static string pathLev( const string &path, int level, bool encode=true, int *off=NULL ); — The allocation of the elements of the path <path> with the ability of their decode, starting with the offset <off> and controlling the offset of the element end in itself.
• static string path2sepstr( const string &path, char sep='.' ); — Transformation the path into string with the separator <sep> of the elements.
• static string sepstr2path( const string &str, char sep='.' ); — Transformation of the string with the separator <sep> of the elements into the path.
• static string strEncode( const string &in, Code tp, const string &symb="\t\n"); — Encoding of the string by the specified rule <tp>//.
• static string strDecode( const string &in, Code tp=Custom ); — Decoding of the string by the specified rule <tp>.
• static string strMess( const char *fmt, ... ); — Formation of the string by the template <fmt> and arguments. It is implemented on the basis of printf.
• string strCompr( const string &in, int lev=-1); — Compression of the string <in> with the compression level <lev>.
• string strUncompr( const string &in ); — Decompression of the string <in>.
• static inline uint16_t getUnalign16(const void *p); — Unaligned read for unsigned integer in 16-bit from buffer by offset.
• static inline uint32_t getUnalign32(const void *p); — Unaligned read for unsigned integer in 32-bit from buffer by offset.
• static inline uint64_t getUnalign64(const void *p); — Unaligned read for unsigned integer in 64-bit from buffer by offset.
• static inline int getUnalignInt(const void *p); — Unaligned read for integer from buffer by offset.
• static inline float getUnalignFloat(const void *p); — Unaligned read by real "float" from buffer by offset.
• static inline double getUnalignDbl(const void *p); — Unaligned read by real "double" from buffer by offset.
• static float floatLE(float in); — Real number "float" conversion from internal to format IEEE754 Little-Endian (LE).
• static float floatLErev(float in); — Real number "float" conversion from format IEEE754 Little-Endian (LE) to internal.
• static double doubleLE(double in); — Real number "double" conversion from internal to format IEEE754 Little-Endian (LE).
• static double doubleLErev(double in); — Real number "double" conversion from format IEEE754 Little-Endian (LE) to internal.

Public attributes:

• static bool finalKill - Sign «The final killing of». It is used for forced disconnection of blocked objects on the the final stage of shutdown.
• const int argc - Counter of the arguments of the the command line.
• const char **argv - Buffer of the command line arguments.
• const char **envp - Pointer to the list of parameters of the environment.

2.2. Object of the messages system (TMess)

Data:
Types (levels) of messages (enum - TMess:: Type):

• Debug - debug;
• Info - information;
• Notice - the notification;
• Warning - warning;
• Error - error;
• Crit - critical situation;
• Alert - alert;
• Emerg - emergency.

The structure of the message (class - TMess:: SRec):

• time_t time; - time of the message;
• int utime; - microsecond of the message time;
• string categ; - category of messages (usually the way inside the system);
• Type level; - the level of the message;
• string mess; - message.

Templates:

• _( mess ) - A wrapper over the translation of the messages function for the provision of the accepted by the most of the programs translation of the messages.
• FTM( rec ) - Get a full time of the message, in microseconds, using the two fields of time of the message structure.
• message( cat, lev, fmt, args ... ) - Formation of the the full message.
• mess_debug( cat, fmt, args ... ) - Formation of the debug message.
• mess_info( cat, fmt, args ... ) - Formation of the information message.
• mess_note( cat, fmt, args ... ) - Formations of the message - notification.
• mess_warning( cat, fmt, args ... ) - Formation of the warning message.
• mess_err( cat, fmt, args ... ) - Formation of the error message.
• mess_crit( cat, fmt, args ... ) - Formation of the critical condition message.
• mess_alert( cat, fmt, args ... ) - Formation of the alarm message.
• mess_emerg( cat, fmt, args ... ) - Formation of the emergency message.

Public methods:

• void load( ); - Download.
• void save( ); - Saving.
• string codeConv( const string &fromCH, const string &toCH, const string &mess); - Conversion of the codepage of the messages.
• string codeConvIn( const string &fromCH, const string &mess); - Conversion the codepage of the messages into the internal system codepage.
• string codeConvOut ( const string &toCH, const string &mess); - Conversion of the message from the internal system codepage.
• static const char *I18N( const char *mess, const char *d_name = NULL ); - Getting the message in system the language.
• static string I18Ns( const string &mess, const char *d_name = NULL ); - Getting the message in the system language.
• string lang( ); - Language of the system, as en_US.UTF-8.
• string lang2Code( ); - Language of the system in bi-symbolic codepage (en).
• string lang2CodeBase( ); - The language of basic variables of the text messages in bi-symbolic codepage(en).
• string &charset( ); - The system codepage.
• int logDirect( ); - Receivers to whom the system messages (stdout, stderr, syslog, archive) are sent;
• int messLevel( ); - The level below which the messages are ignored.
• bool isUTF8( ); - Internal codepage is UTF-8.
• void setLang( const string &lang ); - Setting of the system language (localization).
• void setLang2CodeBase( const string &vl ); - Setting the language of the basic message of text variables in the bi-symbolic codepage (en).
• void setLogDirect( int dir ); - Setting receivers to which the system messages are sent. For <dir> the bit mask is used. Where:
  1 - to syslog;
  2 - to stdout;
  4 - to stderr;
  8 - to the archive.
  
• void setMessLevel( int level ); - Setting a minimum level of processed messages.
• void put( const char *categ, int8_t level, const char *fmt, ... ); - Create a message for the current time.
• void get( time_t b_tm, time_t e_tm, vector<TMess::SRec> &recs, const string &category = "", int8_t level = Debug ); - Get the message from the archive for the period of time <b_tm> - e_tm under the category template <category> and minimum level <level>.

2.3. Object subsystem (TSubSYS)

Public methods:

• TSubSYS( const char *id, const char *name, bool mod = false ); — Initialize the constructor. Sign <mod> indicates that subsystem is module one.
• string subId( ); — ID of the subsystem.
• string subName( ); — Localized name of the subsystem.
• bool subStartStat( ); — Sign of the subsystem execution.
• bool subModule( ); — Sign of the modularity of the subsystem.
• virtual int subVer( ); — Version of the subsystems.
• virtual void subStart( ); — Start of the the subsystem.
• virtual void subStop( ); — Stop of the subsystem.
• void modList( vector <string> &list ); — List <list> of the modules of the modular subsystem.
• bool modPresent( const string &name ); — Check for the availability of the module <name>.
• void modAdd( TModule *modul ); — Add/registration of the module <modul>.
• void modDel( const string &name ); — Deleting of the module <name>.
• AutoHD <TModule> modAt( const string &name ); — Connection to the module <name>.
• virtual void perSYSCall( unsigned int cnt ); — Periodic call from system thread, with period 10 seconds and seconds counter <cnt>.
• TSYS &owner( ); — The system - the owner of the subsystem.

2.4. Object Module (TModule)

Data:
The data structure which identifies the module (class - TModule::SAt):

• SAt( const string &iid, const string &itype = "", int itver = 0 ); - initialize the constructor;
• bool operator ==(const TModule::SAt &amst ) const; - comparison function identifiers modules;
• string id; - the identifier of the module;
• string type; - the type of module (subsystem);
• int t_ver; - version of the type of module (subsystem) to which the module is designed.

The structure of exported functions (class - TModule::ExpFunc):

• string prot; - a prototype of the function;
• string dscr; - localized description of the function;
• void (TModule::*ptr) (); - relative address of the function (with respect to the object module).

Public methods:

• TModule( const string &id ); - Initialize the constructor of module <id>.
• string modId( ); - ID of the module.
• string modName( ); - Localized name of the module.
• virtual void modStart( ); - Start of the module.
• virtual void modStop( ); - Stop of the module.
• virtual void modInfo( vector<string> &list ); - A list of information items <list> of the module.
• virtual string modInfo (const string & name ); - Getting the contents of the specified information item <name>.
• virtual void perSYSCall( unsigned int cnt ); — Periodic call from system thread, with period 10 seconds and seconds counter <cnt>.
• void modFuncList( vector<string> &list ); - The list of exported functions <list> of the module.
• bool modFuncPresent( const string &prot ); - Check the availability of the specified function by its prototype <prot>.
• ExpFunc &modFunc (const string & prot); - Get the information about exported function of the module <prot>.
• void modFunc( const string &prot, void(TModule::**offptr)() ); - Getting the relative addresse <offptr> of exported function <prot>.
• const char *I18N( const char *mess ); - Localization of modular message <mess> in accordance with the current locale.
• TSubSYS &owner( ); - Subsystem - the owner of the module.

Protected Attributes:

• string mName; - Name of the module.
• string mDescr; - Description of the module.
• string mType; - Type of module.
• string mVers; - Version of the module.
• string mAutor; - Author of the module.
• string mLicense; - License of the module.
• string mSource; - Source/origin of the module.

Protected methods are:

• void modFuncReg (ExpFunc * func); - Registration of the exported by module functions.