OpenSCADAWiki: Home Page En/Doc/API
 
Ukrainian (1 Kb) Óêðà¿íñüêà
Russian (1 Kb) Ðîññèéñêèé

 (2 Kb) This page is frozen, actual one here.

API system OpenSCADA

Author: Roman Savochenko, Maxim Lysenko (2012)

Contents

Introduction

This paper describes an application programming interface (API) of the OpenSCADA system.

OpenSCADA is the project of an open SCADA-system based on the modular principle. The document contains an exhaustive description of the internal system architecture of OpenSCADA. In addition to information on the architecture the background information on methods and attributes of the system is provided.
The document is intended for programmers wishing to understand the architecture of OpenSCADA and develop extensions for it. The document is not intended for users and integrators of OpenSCADA!

For understanding of this document it is necessary for you to know the concept of Object Oriented Programming (OOP) and Universal Modeling Language (UML), and for the possibility of studying the source code of the project it is required the knowledge of programming language C++. In addition, the document contains the mentioning of the following technologies: relational databases, XML.

1. The internal structure, API system OpenSCADA.

For the purpose of visual and affordable perception of the OpenSCADA system architecture in general the Figure 1 shows the static class diagram of OpenSCADA on the universal modeling language (UML). Based on the chart it is clear that the OpenSCADA system contains modular subsystems: "Archives", "Databases", "Transports", "Transport protocols", "User interfaces", "Data acquisition" and "Special", as well as subsystems: "Safety" and "Module's management". The chart graphically presents the relationship between modular subsystems and modules.


The static class diagram (175 Êá)
Fig. 1. The static class diagram

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 TTypeArchivator. At the same time, the normal subsystem does not contain such objects. For example TSecurity subsystem (Figure 2).


Hierarchical structure of OpenSCADA. (16 Êá)
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)

Inherits:TCntrNode.

Data:
Information variables of the program:


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


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


Structure of redundant station (class — TSYS::SStat):


Structure of OpenSCADA task (class — TSYS::STask):


Templates/definitions:


Public methods:


Public attributes:


Short calls for global functions into "OSCADA" namespace:

2.2. Object of the messages system (TMess)

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


Direction for the messages (enum — TMess::Direct):


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


Templates:


Public methods:

2.3. Object subsystem (TSubSYS)

Inherits:TCntrNode.
Inherited:TArchiveS, TProtocolS, TBDS, TFunctionS, TSesurity, TModShedul, TTransportS, TUIS, TSpecialS, TControllerS.

Public methods:

2.4. Object Module (TModule)

Inherits:TCntrNode.
Inherited:TProtocol, TTypeBD, TTypeArchive, TTypeTransport, TUI, Tspecial, TTypeDAQ.

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


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


Public methods:


Protected Attributes:


Protected methods are:


3. Subsystem "Database" (TBDS)

Subsystem "Databases" is represented by the object TBDS, which contains a modular objects of the following types of DB TTypeBD. Each type of database contains objects of individual databases of that type TBD. Each database in its turn, contains the objects of their tables TTable (Fig. 3).


Hierarchical structure of the database subsystem. (37 Êá)
Fig. 3. Hierarchical structure of the database subsystem.

The subsystem provides the basic functions to access the type of database, as well as generalized functions for the manipulation of the databases and tables. For example, to hide the source of data, which may be a configuration file, the functions of an abstract access to the data source are provided. For the storage system-wide data the system table and the function of the abstract to access it are provided. Consequently, system-wide data can be stored in the configuration file and in the database table. Priority source, in this case, is the database table.


Being a modular object, the type of database (TTypeBD) provides access to the implementation of the mechanism of one or another database. Access is made through a public databases of the module of a given type of database. Open/registered database is described in the table of databases to be opened or in the configuration file. There is, the so-called, the working database, which is always opens and is shown in the configuration file. DB which support the SQL-queries can grant access based on direct SQL-queries.


While working, the components of the OpenSCADA system open tables (TTable) available in the database and work with them.

3.1. Object of subsystem "Database" (TBDS)

Inherits:TSubSYS, TElem.

Data:
Flags of the queries to the system table (enum – TDBS::ReqGen):


Public methods:

3.2. Modular object of types of databases (TTypeBD)

Inherits:TModule.
Inherited:By root objects of the modules of subsystem "DB".

Public methods:

3.3. The object of the database (TBD)

Inherits:TCntrNode, TConfig.
Inherited:By the database objects of the modules of subsystem "DB".

Public methods:


Protected methods:

3.4. The object of the table (TTable)

Inherits:TCntrNode.
Inherited:By tables objects of the modules of subsystem "DB".

Public methods:


4. The subsystem "Data acquisition" (TDAQS)

The subsystem "Data acquisition" is represented by the TDAQS object which contains modular objects of the data sources' types TTypeDAQ and the objects of the libraries of parameters' templates of subsystem "Data acquisition" TPrmTmplLib. Object of the data sources types contains objects of the controllers TController and objects of the parameters' types TTypeParam. Parameters' types objects are provided by the controller module and contain the DB structure of the separate parameters' types (analog, digital ...). Controllers' objects contain parameters' objects TParamContr. Each parameter is associated with only one type of the parameter. For the attribute storage parameter is inherited from the values object TValue, which contains the attributes' values TVal. The library of the parameters' templates of this subsystem contains templates' objects TPrmTmpl. An example of the described hierarchical structure is shown in Fig. 4.


Hierarchical structure of the data acquisition subsystem. (41 Êá)
Fig. 4. Hierarchical structure of the data acquisition subsystem.

Subsystem contains the types of data sources. The source may be virtually any substance providing any data. Type of source can be divided into individual sources (controllers) within the limits of the particular type. For example, if we take the data from the operating system (OS), then the single source can be the separate operating system of the separate PC.


Data source (controller) is further divided (contains) into the parameters. The parameter is the part of the data source. In the case of the OS it will be, for example,: used RAM, the processor's frequency and many other parts.


Parameter, in its turn, contains the attributes, which provide the data. In addition to the basic data attributes can provide the related or detailing data. In the case of the same operating system and the memory usage, the attributes may not only provide the used memory, and also how much it all, how much in the swap, etc.


Some of the implementation of the data sources may provide the possibility of setting the structure of the parameter based on previously developed parameters' templates. For this purpose subsystem contains templates' libraries, which, in their turn, provide the parameters' templates . The example shows a library of templates "base" with the templates "digAlrm" and "smplBrd".


At the level of the subsystem the redundancy mechanism for data sources is provided. Redundancy means the possibility of coordinated work of several OpenSCADA stations to perform common task of data acquisition from the same data sources.

4.1. Object of subsystem "Data acquisition" (TDAQS)

Inherits:TSubSYS.

Public methods:

4.2. Modular object of the controller's type (TTypeDAQ)

Inherits:TModule, TElem.
Inherited:Root object of the modules of subsystem "Data acquisition".

Public methods:


Protected methods:

4.3. Controller's object (TController)

Inherits:TCntrNode, TConfig.
Inherited:Objects of the modules of subsystem "Data acquisition".

Data:
Redundancy modes (enum TController::Redundant):

Command specific

Public methods:


Protected attributes:


Protected methods:

4.4. Parameters' type object (TTypeParam)

Inherits:TElem.

Public methods:


Public attributes:

4.5. Object of the physical level parameter (TParamContr)

Inherits: TConfig, TValue.
Inherited: Objects of the module's parameters of subsystem "Data acquisition".

Public methods:


Protected methods:

4.6. Object of the value (TValue)

Inherits:TCntrNode, TValElem.
Inherited:TParamContr.

Public methods:


Protected methods:

4.7. Attribute's object (TVal).

Inherits:TCntrNode.

Data:
Additional flags to the object TFld (enum TVal::AttrFlag):


Public methods:

4.8. Object of the templates library of parameters of the "DAQ" subsystem (TPrmTmplLib)

Inherits:TCntrNode, TConfig.

Public methods:

4.9. The object of the parameter's template of the "DAQ" subsystem (TPrmTempl)

Inherits:TFunction, TConfig.

Data:
Additional flags to the attribute's object of the function IO (enum TPrmTempl::IOTmplFlgs):


Public methods:


5. Subsystem "Archives" (TArchiveS)

Subsystem "Archives" is represented by an object TArchiveS, which contains at the subsystem level the modular objects of the archivers types TTypeArchivator. Each object of the archiver type contains objects of the messages' archivers TMArchivator and values' archivers TVArchivator. In addition, the subsystem object contains the methods of the messages archive and objects of the values' archives TVArchive. The object of the values' archive TVArchive contains the buffer of values through the inheritance of the buffer object TValBuf. To connect the archive of values with the archivers the object of the value element TVArchEl is provided. This object is contained in the archiver and it is referenced by the archive. Structure of the subsystem "Archives" is presented in Fig. 5.


The hierarchical structure of subsystem \'Archives\'.\n (24 Êá)
Fig. 5. The hierarchical structure of subsystem "Archives".

Subsystem "Archives" contains the mechanisms for archiving of messages and values. It directly contains the messages' archive together with its buffer. Contains methods for accessing the archives of the values and for the archivers of values and messages. Besides it performs the actively data acquisition from sources of values for the archives of values, as well as archiving the archive of messages by the archivers.


Archive of values (TVArchive) contains the buffer (TValBuf) for intermediate values' accumulation before archiving. It is connected with the source of values in the person of OpenSCADA system parameters in active or passive mode, as well as with other sources in the passive mode. To archive to the physical storage it is connected with the values' archivers of various types.


Object of the buffer TValBuf contains an array of values of the main types of OpenSCADA system: string, integer, real and boolean. It is supported the storage of values in the modes of hard, soft grid and in the free access mode. It is also provided the mode of high-resolution time (microseconds). It is used for direct storage of large arrays of values, and for the exchange of large arrays by the frame-accurate method of access.


Root object of the module of subsystem "Archives" (TTypeArchivator) contains information about the specific type of module. Within the individual modules it can implement their own module-wide functions. In general, for modules of this type it contains methods to access the repositories of values and messages.


Object of the messages' archiver (TMArchivator) contains the specific implementation of the message storage. In general, for messages' archivers the interface of access to the implementation of an archiving mechanism in modules is provided.


Object of the values' archiver (TVArchivator) contains the specific implementation of the repository of values. In general, for the values' archivers the access interface to implementation of the archiving mechanism and the appointment of archives of values for service by archiver are provided.


Object of the archive element TVArchEl links the archive objects with the archivers. It is used to access the archiver from the archive, as well as to archives from the archiver, ie for cross-calls.

5.1. The object of the subsystem "Archives" (TArchiveS)

Inherits:SubSYS.

Public methods:


Public methods:

5.2. The object of the values' archive (TVArchive)

Inherits:TCntrNode, TValBuf, TConfig

Data:
The data acquisition mode/source (struct — TVArchive::SrcMode):


Public methods:

5.3. Object of the values' buffer (TValBuf)

Inherited:TVArchive

Public methods:


Protected methods:

5.4. The modular object of the archiver's type (TTypeArchivator)

Inherits:TModule.
Inherited:By the root objects of the modules of subsystem "Archives".

Public methods:


Protected methods:

5.5. The object of the messages' archiver (TMArchivator)

Inherits:TCntrNode, TConfig
Inherited:By the objects of the archivers of messages of modules of the subsystem "Archives".

Public methods:


Protected attributes:


Protected methods:

5.6. The object of the values' archiver (TVArchivator)

Inherits:TCntrNode, TConfig
Inherited:By the objects of the archivers of values of modules of the subsystem "Archives".

Public methods:


Protected methods:


Protected attributes:

5.7. The object of the archive's element in the archiver (TVArchEl)

Inherited:By the objects of the archivers of values of modules of the subsystem "Archives".

Public methods:


Public methods:


Protected methods:


6. Subsystem "Transports" (TTransportS)

"Transports" subsystem is represented by the TTransportS object, which contains modular objects of the transports' types TTypeTransport on the subsystem-level. Each type of transport contains objects TTransportIn of the incoming and TTransportOut of the outgoing transports. The overall structure of the subsystem is shown in Fig. 6.


The layered structure of the transports subsystem. (20 Êá)
Fig. 6. The layered structure of the transports subsystem.

The root object of the "Transports" subsystem's module provides information about the specific type of module and about the external OpenSCADA hosts/stations. As part of the single module it can be implemented the own general-module functionality. In general, for all modules, the access methods for both: inbound and outbound transports of the specific module are contained.


The object of the incoming transport TTransportIn provides an interface to the implementation of the modular method of incoming transport.


The object of the outgoing transport TTransportOut provides an interface to the implementation of the modular method of outgoing transport.

6.1. The object of the "Transports" subsystem (TTransportS)

Inherits:TSubSYS.

Data:
External hosts mode (enum — ExtHost::Mode):


The structure of the external OpenSCADA hosts/stations (class TTransportS::ExtHost):


Public methods:

6.2. The modular object of the transports' type (TTypeTransport)

Inherits:TModule.
Inherited:By the root object of the subsystem's "Transports" modules..

Public methods:


Protected methods:

6.3. The object of the incoming transports (TTransportIn)

Inherits:TCntrNode, TConfig.
Inherited:By the objects of incoming transports of the subsystem's "Transports" modules.

Public methods:


Protected methods:


Protected attributes:

6.4. The object of the outgoing transports (TTransportOut)

Inherits:TCntrNode, TConfig.
Inherited:By the objects of outgoing transports of the subsystem's "Transports" modules.

Public methods:


Protected attributes:


7. Subsystem "Communication interfaces' protocols" (TProtocolS)

Subsystem "Communication interfaces' protocols" is presented by the TProtocolS object, which contains modular objects of the separate protocols TProtocol on the a subsystem's level. Each protocol contains objects of the opened sessions of the incoming protocols TProtocolIn.


TProtocolS object provides an access to the both: the incoming and the outgoing protocols of the individual types of transport protocols. The inner side of outgoing protocol based on the steaming principle with the individual structure of the stream for each implementation of the protocol.

7.1. The object of the “Communication interfaces' protocols” subsystem (TProtocolS)

Inherits:TSubSYS.

Public methods:

7.2. The modular object of the protocol (TProtocol)

Inherits:TModule.
Inherited:By the root object of the subsystem's "Protocols" modules.

Public methods:

7.3. The object of the incoming protocol's session (TProtocolIn)

Inherits:TCntrNode.
Inherited:By the session objects of the incoming modules' protocol of the subsystem "Protocols".

Public methods:


8. Subsystem "User interfaces" (TUIS)

The subsystem "User Interfaces" is presented by the TUIS object, which contains modular objects of the TUI user interfaces' on the subsystem's level.

8.1. The object of the "User interfaces" subsystem (TUIS)

Inherits: TSubSYS.

Data:
Requests parameters (enum — GetOpts):


Public methods:

8.2. The modular object of the user interface (TUI)

Inherits: TModule.
Inherited: By the root objects of the "User interfaces" subsystem.

Protected attributes:


9. Subsystem “Specials” (TSpecialS)

The subsystem "Specials" is presented by TSpecialS object, which contains modular objects of TSpecial special on the subsystem's level.

9.1. The object of the “Specials” subsystem (TSpecialS)

Inherits:TSubSYS.

Public methods:

9.2. The modular object of the specials (TSpecial)

Inherits:TModule.
Inherited:By the root objects of the subsystem's “Specials” modules.

Protected attributes:


10. Subsystem “Security” (TSeñurity)

Security subsystem is presented by an object TSesurity, which contains group objects of TGroup and users TUser.


User object TUser contains user information and checks the authenticity of the user in accordance with the specified password.


TGroup user object contains information about the group of users and checks the user's belonging to the group.

10.1. The object of the "Security" subsystem. (TSeñurity)

Inherits:TSubSYS.

Public data:


Public methods:

10.2. The user's object (TUser)

Inherits:TCntrNode, TConfig.

Public methods:

10.3. The users' group object (TGroup)

Inherits:TCntrNode, TConfig.

Public methods:


11. Subsystem “Modules' sheduling” (TModSchedul)

Subsystem “Modules' sheduling” is presented by the object TModSchedul.


The subsystem contains the control mechanism for modules contained in shared libraries.

11.1. The object of the subsystem “Modules' sheduling” (TModSchedul)

Inherits:TSubSYS.

Data:
The structure of information about the shared library (struct – TModSchedul::SHD):


Public methods:


12. Components of the object model of the OpenSCADA system

Object model of the OpenSCADA system is based on the function object TFunction, on the parameters of the function IO and on the values' frame of the function TValFunc. Later the function's objects are included in the object tree, forming an object model of the system. Using the functions of the object model is made by linking the frame of values TValFunc with function.


The idea in general is shown in Fig. 7.


The basis of the programming area of the OpenSCADA system. (76 Êá)
Fig. 7. The basis of the programming area of the OpenSCADA system.

Object of the function (TFunction) provides an interface for the formation of function parameters and algorithm of the computing in the object which inherits it.


Object of the function's parameter (IO) contains the configuration of the single parameter.


Object of the values' frame (TValFunc) contains values in accordance with the structure of the linked function. While the execution of the algorithm by the associated function the values of this object are used.

12.1. The function object (TFunction)

Inherits:TCntrNode
Inherited:By the modules and nodes of the systems, which contains the functions for publication in the object model of the system.

Public methods:


Protected attributes:

12.2. The object of the function's parameter (IO)

Data:
Parameter's type (enum — IO::Type):


Parameter's flags (enum — IO::IOFlgs):


Public methods:

12.3. The object of the function's value (TValFunc).

Public methods:


Public attributes:


13. Data in the OpenSCADA system and their storage in the DB (TConfig)

Storing data in the system based on the objects TConfig and TElem. These objects store the structure and fields' values of the database, allowing for direct loading and saving the configuration via the "DB" subsystem. For the specialized different types data storage the TVariant object is provided.


TElem object contains the structure of database record. Structure of the record contains extensive information about the elements, their types, sizes and other parameters. Information in this structure is enough to create, control and manage the real structure of the database. Elementary unit of the record is the cell Tfld.


TConfig object is the heir of TElem and contains the actual values of elements. TConfig is used as the parameter in the functions of the manipulating with the table's records in the "DB" subsystem. Elementary unit of the record is the cell TCfg.


To provide an opportunity to inform the data storehouse about the changes in the structure it is provides an object TValElem, from which it is inherited the storehouse TConfig and the list of which is contained in the TElem structure.

13.1. Data object (TConfig)

Inherits:TValElem
Inherited:TParamContr, TController, TMArchivator, TPrmTempl, TPrmTmplLib, TUser, TGroup, TTransportIn, TTransportOut, TBD, TVArchive, TVArchivator, à òàêæå ìîäóëüíûå îáúåêòû õðàíÿùèå ñâîè äàííûå â ÁÄ.

Public methods:


Protected methods:

13.2. Data cell (TCfg)

Inherits:TVariant

Data:
Additional flags to TFld (enum — TCfg::AttrFlg):


Requests flags (enum — ReqFlg):


Public methods:

13.3. Data structure object (TElem)

Inherited: By the TTypeParam, TControllerS, TTypeDAQ, as well as by the modular objects, combining the functions of the structure storage .

Public methods:

13.4. Data structure cell (TFld)

Data:
Cell's type (enum – TFld::Type):


Cell's flags (enum — TFld::AttrFlg):


Public methods:

13.5. The object which preacts about changing of the structure (TValElem)

Inherited:TValue, TConfig.

Protected methods:

13.6. Data cell (TVariant)

Data:
Error values for the different data types (define):


Òèïû äàííûõ (enum — TVariant::Type):


Public methods:

13.7. User object (TVarObj)

Inherited:TArrayObj

Public methods:


14. The control interface of the system and the dynamic tree of the system objects (TCntrNode)

For complete coverage of the key components of the system by the network of the same structure objects the object of the dynamic tree node TCntrNode is provided. This objects provides the following functions:


Any object that has the need to provide dynamic access to itself or its components must be inherited from the object of the dynamic tree node TCntrNode. This relationship is automatically includes the node into the dynamic tree of objects covered by both: the direct and the reverse links, and also provides an opportunity to create containers for its own child nodes. In addition to this node is able to preact the inclusion and exclusion/remove of the node from the tree with the possibility of reject from the exclusion/removal.


The control interface of the system is included into the TCntrNode object and, accordingly, covers all the nodes of the dynamic tree of the system, allowing you to consistently manage the system regardless of the client tool used. The control interface of the system is based on the markup language XML. You can think of many ways to use control interface of system, as an example, we'll note the following most meaningful solutions:


The control interface of the system is implemented by the following components:


Information hierarchical structure contains information about public control elements and can be used to build custom dialogs for the node's control of the system.


The dynamic part contains the scripts of requests' to the control elements service which are described in the information structure; as well as hidden control elements in the form of service functions used for unified access to the node.


The container can also gather into the single request several information structures and dynamic parts, thereby optimizing the time of the request especially on the high latency network interfaces.


Overall control interface is built from individual components of the dynamic tree. Hierarchical inheritance from the TCntrNode object allows to realize multi-level addition of the configuration of the control interface. General view of the dynamic node tree is shown in Fig. 8.


Example of dynamic tree of the node in the OpenSCADA system. (127 Êá)
Fig. 8. Example of dynamic tree of the node in the OpenSCADA system.

System's nodes, containing data for the control interface of the system must also be connected to the dynamic tree of objects.


Connection of the node to the dynamic tree is done as follows:

14.1. The syntax of the request and response of the control interface

Whole exchange with the control interface is done through the XML language. The internal exchange is done through the parsed structure of XML language (DOM), and external — through the transformation in the stream the characters of continuous XML-file and vice versa.


Request is executed by sending a container with some parameters in the attributes. The result is placed in the resulting container with the changes in certain attributes of the root container. In general, the request container can be written as follows:
<cmd path="/TreePath" user="user" force="1"/>
Where:

cmd — request command;
path — path to the node or to the branch of the tree;
user — user of the system on behalf of which the request is sent;
force — the sign: to execute the request without warning.

As the confirmation of the request's result it is set the result's attribute rez in values: 0-request succeeds, 1-warning (with the possibility of execution), 2-error. In the case of error and warning the messages are written in the text of the container and in the attribute mcat (message category): <cmd path = "/TreePath" user="user" force="1" rez="2" mcat="sub_DAQ/mod_BlockCalc>; Unable to delete the node </cmd>


Grouping request "CntrReqs" is processed at the API level of the node and does not require separate processing in the user code. In fact, into the tag "CntrReqs" may be placed any other requests with the possibility of hierarchical grouping by including of the internal tags "CntrReqs". The only attribute of this tag is an attribute path, which indicates the path to the node and is the basis for internal requests.


<CntrReqs path="/sub_DAQ/cntr_gate">
  <get path="/%2fprm%2fcfg%2fNAME"/>
  <get path="/%2fprm%2fcfg%2fDESCR"/>
  <list path="/%2fserv%2fattr"/>
</CntrReqs>

14.2. Tag of the information structure for describing the groups of child branches of the page

Each page can contain groups of child branches. For descriptions of groups of branches there is the tag "branches". Tag contains the description of groups of branches through embedded tags grp. The group tag can be accessed as for the "read" (visibility) and for modification ( the execution of commands for adding and removing the elements of the group), hence the element of the triad of access may be:

00 — there is no any access;
04 — there is an access only for reading;
02 — there is only access fro the writing, usually this value has no meaning because the write access means access for reading;
06 — there is an access to read, and to write.


Actions over the group of elements coincide with the actions over the list of visual elements "list", which is described below.

14.3. Tags of the description of the information structure of the control interface

Information tags for the XML form the alphabet of the formation of the description the configuration dialogs. Request command of the information part is: <info path="/TreePath" user="user"/>


As the result of the request it will be received the information structure of the page in accordance with the privileges of the specified user.

14.3.1. Area tag "area"

Areas are described with "area" tag and are intended to group the elements on different features. Area may include other elements and areas. The root ones form the bookmarks in the presentation of the user interface. To tag, you can access only to "read" or "visibility", hence the element of the triad of access can be set to 00, if access is absent, or 04, if it is present.

<area id="base" dscr="Base information">
  <fld id="host" dscr="Host name" tp="str"/>
  <fld id="user" dscr="Operated user" tp="str"/>
  <fld id="sys" dscr="Station system" tp="str"/>
  <area id="other" dscr="Other options">
     <fld id="val" dscr="Value" tp="real"/>
  </area>
</area>

14.3.2. Data tags

Tags, which describe data, are shown in the table 1.


Table 1. Tags, which describe data

TagDescription
<fld>The simplest data of the string, integer, real or boolean types.
<list>Lists with data of string, real and boolean types.
<table>Tables with the data in cells of string, integer, real, boolean types.
<img>Images.

a) Tag "fld"

<fld id="host" dscr="Host name" tp="str"/>
<fld id="user" dscr="Operated user" tp="str"/>
<fld id="sys" dscr="Station system" tp="str"/>


The tag can be accessed as to "read" and also to "write", therefore an element of the triad of access may be:

00 — there is no any access;
04 — there is an access only for reading;
02 — there is only access fro the writing, usually this value has no meaning because the write access means access for reading;
06 — there is an access to read, and to write.

Type of the element, discribed by the "fld" tag, is specified by the tp attribute (table 2).


Table 2. Attribute's tp values of the "fld" tag.

Tag tpDescription
strString type.
<fld id="host" dscr="Host name" tp="str"/>
decInteger in decimal representation.
<fld id="debug" dscr="Debug level" tp="dec"/>
octInteger in octal representation.
<fld id="cr_file_perm" dscr="Make files permissions(default 0644)" tp="oct" len="3"/>
hexInteger in hexadecimal representation.
realReal value.
boolBoolean sign ("false"|"true").
<fld id="log_sysl" dscr="Direct messages to syslog" tp="bool"/>
timeTime in seconds (from 01/01/1970).
<fld id="v_beg" dscr="Start time" tp="time"/>

Table 3. Actions over the element, described by the "fld" tag.

OperationAction
InterrogationRequest: command "get": <get path="/fld_teg" user="user"/>.
Result: confirmation with the value in the text of the tag or an error message.
ModificationRequest: command "set": <set path="/fld_teg" user="user">value</set>
Result: confirmation or an error message.
Request for the rules of syntax highlight, for text fields (the attribute "rows" set).Request: command "SnthHgl": <SnthHgl path="/fld_teg" user="user"/>
Result: confirmation whith the rules of syntax highlight list:
<rule expr="\b(if|else|for|while|in|using|new|var|break|continue|return|Array|Object)\b" color="darkblue" font_weight="1"/>
<rule expr="(\?|\:)" color="darkblue" font_weight="1"/>
<rule expr="(\b0[xX][0-9a-fA-F]*\b|\b[+-]?[0-9]*\.?[0-9]+[eE]?[-+]?[0-9]*\b|\btrue\b|\bfalse\b)" color="blue"/>
<rule expr="&quot;[^&quot;]*&quot;" color="darkgreen"/>
<rule expr="//[^\n]*" color="gray" font_italic="1"/>
<blk beg="/\\*" end="\\*/" color="gray" font_italic="1"/>
b) Tag "list"

<list id="mod_auto" dscr="List of shared libs(modules)" tp="str" dest="file"/>


The tag can be accessed as to "read" and also to "write"(modification), therefore an element of the triad of access may be:

00 — there is no any access;
04 — there is an access only for reading;
02 — there is only access fro the writing, usually this value has no meaning because the write access means access for reading;
06 — there is an access to read, and to write.

Type of the elements in the list is specified by the attribute tp. tp attribute's values are given in Table 1.


Table 4. Actions over the list.

OperationAction
Interrogation

Request: command "get": <get path="/fld_teg" user="user"/>
Result: confirmation with the result in the tag's text or an error message. The result is formed in the form:

<get path="/fld_teg" user="user" rez="0">
<el id="0">./MODULES/arh_base.o</el>
<el id="1">./MODULES/cntr_sys.o</el>
</get>
String's addition

Request: command "add": <add path="/fld_teg" user="user" id="tst">Test</add>

To add the string with ID "tst" and value "Test". If the list is not indexed, then the id attribute is absent.

Result: confirmation or an error message.

Insert the string

Request: command "ins": <ins path="/fld_teg" user="user" pos="3" p_id="tst1" id="tst">Test</ins>

To insert the string with the ID "tst" and value "Test" in position 3 with the string "tst1". In the case of the index list p_id attribute contains the identifier, else — the text of the string. If the list is not indexed, then the ID attribute is absent.

Result: confirmation or an error message.

Deleting of the string

Request: command "del": <del path="/fld_teg" user="user" pos="3" id="tst">Test</del>

To delete the string with ID "tst" and value "Test" from the position 3. If the list is not indexed, then the ID attribute is absent.

Result: confirmation or an error message.

Edit of the string

Request:: command "edit": <edit path="/fld_teg" user="user" pos="3" p_id="tst1" id="tst" >Test</edit>

To replace the string at position 3 with the identifier "tst1" with the another string with the identifier "tst" and value "Test". In the case of the index list p_id attribute contains the identifier, else — the text of the string. If the list is not indexed, then the ID attribute is absent.

Result: confirmation or an error message.

Mooving of the string

Request: command "move": <move path="/fld_teg" user="user" pos="3" to="5"/>

To move the string from position 3 to position 5.

Result: confirmation or an error message.

c) Tag "table"

<table id="a_mess" key="0" col_lst="0;1;2">
  <list id="0" dscr="Id" acs="4" tp="str"/>
  <list id="1" dscr="Name" acs="4" tp="str"/>
  <list id="2" dscr="Type" acs="4" tp="str"/>
  <list id="3" dscr="Hide" acs="4" tp="bool"/>
</table>


The tag of the table or single column can be accessed as to "read" and also to "write"(modification), therefore an element of the triad of access may be:

00 — there is no any access;
04 — there is an access only for reading;
02 — there is only access fro the writing, usually this value has no meaning because the write access means access for reading;
06 — there is an access to read, and to write.

If the attribute key is specified and it lists the key columns, the work with the table moves to the addressing mode by the identifiers for columns and keys.


Table 5. Actions over the table.

OperationAction
Interrogation

Request: command "get": <get path="/fld_teg" user="user" cols="0;2" rows="100;1000"/>

To get columns 0-2 and rows of them from 100 to 1000 table.

Result: Confirmation with the data of the table or an error message. The result is formed in the form:

<get path="/fld_teg" user="user" cols="0;2" rows="100;1000" rez="0">
<list id="0" tp="str">
<el id="100">Sat Feb 21 18:04:16 2004</el>

</list>
<list id="1" tp="str">

<el id="100">SYS</el>

</list>
<list id="2" tp="str">

<el id="100">*:(TSYS)Broken PIPE signal allow!</el>
</list>
</get>
Adding of the stringRequest: command "add": <add path="/fld_teg" user="user"/>
Result: confirmation or an error message.
Insert of the string

Request: command "ins": <ins path="/fld_teg" user="user" row="3"/>

To insert the string in position 3. Command does not work when attribute key is set!

Result: confirmation or an error message.

Deleting of the string

Request: command "del": <del path="/fld_teg" user="user" row="3"/> or <del path="/fld_teg" user="user" key_id="Test"/> for the key mode

To remove the string in position 3 or string in the position where the id column value is "Test".

Result: confirmation or an error message.

Moving of the string

Request: command "move": <move path="/fld_teg" user="user" row="3" to="5"/>

To move the string from position 3 to position 5. Command does not work when attribute key is set!

Result: confirmation or an error message.

Change the cell

Request: command "set": <set path="/fld_teg" user="user" row="3" col="id">Test</set> or <set path="/fld_teg" user="user" key_id="Test" col="id">Test1</set> for the key mode

To set the cell's value in row 3 and column "id" to "Test" or set of the column named "id" of the row to the position where the id column value is "Test" to value "Test1". Practically, this command renames a key element of the specified row.

Result: confirmation or an error message.

d) Tag "img"

<img id="ico" descr="Page icon"/>


The tag can be accessed as to "read" and also to "write"(modification), therefore an element of the triad of access may be:

00 — there is no any access;
04 — there is an access only for reading;
02 — there is only access fro the writing, usually this value has no meaning because the write access means access for reading;
06 — there is an access to read, and to write.

Tag is provided to transfer images to the clients of control interface. Under the image may be: pages' icons, graphics of the values' arrays and other data that can be presented in graphical form.


The following requests' commands are supported:

The result is the confirmation with image data or an error message.
The result is the confirmation or error message.
e) Commands with the parameters. Tag "comm"

<comm id="add">
  <fld id="tm" tp="time"/>
  <fld id="cat" tp="str"/>
  <fld id="lvl" tp="dec" min="0" max="7"/>
  <fld id="mess" tp="str"/>
</comm>


The tag can be accessed as to "read" or visibility + service of the requests, and for modification or execution of the command, hence an element of the triad of access can be set to 00, if access is absent at all; 04, if the command can be seen, and 06, if the command can be initiated.


It is provided for transmission of commands and actions to the node, and also can be used to create links to other pages. Commands may include options. Parameters are described with "fld".


The following request commands are supported:

<set path="/fld_teg" user="user"/>
  <fld id="tm">1023456244</fld>
  <fld id="cat">*</fld>
  <fld id="lvl">2</fld>
  <fld id="mess">Test mess</fld>
</set>

<get path="/fld_teg" user="user" tp="lnk"/>"


The result is the confirmation or error message.

f) Branches (child nodes)

<list id="k_br" dscr="Kernel branches" tp="br"/>


The branches are described by the usual list "list" with special attributes tp = "br". Methodology of the request and modification of branches coincides with the one of work with the list "list".


14.4 Hierarchical dependences of the information elements of the control language

Example of the node page of the control language:

<oscada_cntr>
  <area id="a_gen" dscr="Generic control">
    <fld id="config" dscr="Config file" tp="str" dest="file"/>
    <fld id="cr_file_perm" dscr="Files" tp="oct" len="3"/>
    <fld id="cr_dir_perm" dscr="Directories" tp="oct" len="3"/>
    <comm id="upd_opt" dscr="Update options(from config)"/>
    <comm id="quit" dscr="Quit"/>
  </area>
  <area id="a_kern" dscr="Kernels">
    <list id="k_br" dscr="Kernels" tp="br"/>
  </area>
</oscada_cntr>


Table 6. Hierarchical dependencies of the information elements of the language.

TagDescriptionAttributesContents
oscada_cntrThe root element of the page. It is the only and serves to identify the origin of language of control interface.id — ID;
dscr — description.
area, img, branches
branchesContainer of the groups of child branches of the node.id — Container's ID. It is equal: br.grp
grpThe group of the child nodes.id — prefix of the group of child nodes in the system;
dscr — description of the branches' group;
acs — access options.
areaGrouping of the standard tags.id — ID;
dscr — description;
acs — access options.
area, fld, list, table, comm, img
commCommands to the node.id — ID;
dscr — description;
help — command's help;
tp — command's type (lnk — ññûëêà);
acs — access options.
fld
fldDescription of the standard data types.

id — ID;
dscr — description;
help — help;
acs — access options.
tp — element's type:

str(len, dest, cols, rows(SnthHgl)) — string element;
dec(len, max, min, dest) — integer in decimal representation;
oct(len, max, min, dest) — integer in octal;
hex(len, max, min, dest) — integer in hexadecimal;
real(len, max, min, dest) — real number;
bool — boolean sign;
time — time/date in seconds (from 01/01/1970).

Connected:
len — value length (char.);
min — minimum of value;
max — maximum of value;
cols — number of columns;
rows — number of rows;
dest — input method:

data — source of binary data (base64).
select(select) — selective type;
sel_ed(select) — selective type with the possibility of editing.
select — path to the hidden list;
sel_list — static list (separator ';');
sel_id — static list of the identifiers (separator ';').
listList of standard data types.

id — ID;
dscr — description;
help — help list;
acs — access options;
tp — as in fld except:

br(br_pref) — child nodes.

idm — indexed list (0|1);
s_com — ways of the list's modification [add][,ins][,edit][,del]:

add — add rows;
ins — insert rows;
edit — modify rows;
del — delete rows.
Connected:
br_pref — child node's prefix;
dest — as in fld.
tableTable of standard data types.id — ID;
dscr — description;
help — table help;
acs — access options;
key — key columns (key="id,name,per");
cols — list of columns in the request attribute;
rows — range of rows in the attribute of the request;
s_com — types of the table's modification [add][,del][,ins][,move]:
add — add rows;
ins — insert rows;
del — delete rows;
move — move rows.
list
imgImage.id — ID;
dscr — description;
help — image help;
acs — access options;
h_sz — horizontal limitation;
v_sz — vertical limitation.

14.5. Object of the dynamic tree node (TCntrNode)

Inherited:By all the dynamic and controlled objects directly or through the childs.

Data:
Named rights of access to control elements (define):


Dynamic node's flags (enum TCntrNode::Flag):


Flags of the enabling/disabling modes of the node (enum TCntrNode::Flag):


Modification of the node flags (enum TCntrNode::ModifFlag):


Public methods:

static XMLNode *ctrMkNode( const char *n_nd, XMLNode *nd, int pos, const char *req, const string &dscr int perm = 0777, const char *user = "root", const char *grp = "root", int n_attr = 0, ... );
static XMLNode *ctrMkNode2( const char *n_nd, XMLNode *nd, int pos, const char *req, const string &dscr, int perm = 0777, const char *user = "root", const char *grp = "root", ... ); — Adding the control element to the page. It is possible to specify the set of additional attributes in the number of n_attr as follows: "{attribute1},{values1},{attribute2},{values2},..." or by zero pointer at the end of the pair sequence.

Protected methods:


15. XML in the OpenSCADA system (XMLNode)

XML in the OpenSACDA system is represented by the object of the XML-tag — XMLNode.

15.1. XML-tag (XMLNode)

Data:
Options for XML-file loading (enum — XMLNode::LoadFlgs):


Options of the function of XML-file generation (enum - XMLNode::SaveView):


Public methods:


16. Resources in the OpenSCADA system (Res, ResAlloc, ResMtx, MtxAlloc, AutoHD)

Most of the units and subsystems of the OpenSCADA are dynamic, ie they allow the creation/deletion/configuration while the system is working. Taking into account the multi-threading of the system, this functionality imposes stringent requirements for synchronization of threads. For synchronization in the system the resources are used, functions of which are localized in the objects "Res" and "ResAlloc". Object "Res" provides storage of the resource, providing the functions of capture/release for the read and write. In object "ResAlloc" the automatic release of the resource functions are implemented. Automatic resource involves the creation of a local resource object with its automatic release at fracture (in the destructor). Using of automatic resource makes the work with resources when using the exceptions much easier.


Any dynamic system object is inherited from "TCntrNode" object, which contains a mechanism to connect via the "AutoHD" template. The main function of the template is to store the link to the object and the capture of the resource, excluding the deleting of the object at the time of use. Template supports copying the resource and its release in case of destruction of the template object. For clarity of the access to the objects generated by "TCntrNode" the "AutoHD" template supports casting, based on the dynamic cast.

16.1. Resource R/W lock object (ResRW)

Public methods:

16.2. Automatic resource RW unlock object (ResAlloc)

Public methods:

16.3. Template (AutoHD)

Public methods:

16.4. Resources allocation object, by mutex (ResMtx)

Public methods:

16.5. Object of the string with the access shared by the resource (ResString)

Public methods:

16.6. Conditional variable object, by mutex (CondVar)

Public methods:

16.7. Object of automatic unlock POSIX mutex (MtxAlloc)

Public methods:

16.8. Object of the string with the access shared by the global the data resource (mutex) (MtxString)

Public methods:


17. Organization and structure of the database of the system components

Nodes and subsystems of OpenSCADA may have their own tables in the database to store their own data. The structure of tables is individual and determined by the <TConfig> object. Nodes and subsystems must create and configure the <TConfig> object under their demands.

17.1. System tables

OpenSCADA system has two system tables: BD and SYS. Table BD contains records of registered databases and the table SYS contains data of system-wide parameters.


Table 7. Structure if the table of system-wide parameters (SYS).

User <user>Parameter's ID <id>Parameter's value <val>
root/DemoStation/MessLev0
user/DemoStation/Workdir/mnt/home/roman/work/OScadaD/share/OpenScada
user/DemoStation/UI/QTStarter/StartModQTCfg

Table 8. Structure if the table of registered DB.

ID <ID>DB Type <TYPE>Name <NAME>Description <DESCR>Address <ADDR>Codepage of the database contents <CODEPAGE>To enable <EN>
LibBDMySQLFunction's library server.diya.org;roman;123456;oscadaUserLibsKOI8-U1
AnastModelSQLiteAGLKS model ./DATA/AGLKSModel.dbUTF81
GenDBMySQLMain DB server.diya.org;roman;123456;oscadaDemoStKOI8-U1

17.2. Tables of the "Data acquisition" subsystem

Controllers (data sources) of the subsystem "Data acquisition" are stored in the tables of their subsystems named DAQ_<ModName>. The structures of these tables can differ significantly, but all of them have the obligatory fields. The overall structure of the controllers' tables is presented in table 9.


Table 9. The overall structure of the controllers' tables of the subsystem "Data acquisition" (DAQ_<ModName>).

ID <ID>Controller's name <NAME>Description <DESCR>To enable<ENABLE>To start <START>Individual parameters
AutoDAAutomatic sourceData acquisition from active sources with automatic identification of them.11 ...

Like the controller's table, the parameter's table for different types of data sources can differ significantly, but also have the obligatory fields. In addition to the differences which is typical to the type of data source, parameter's tables can still be different for different types of parameters. The overall structure of the parameters' tables is given in Table 10.


Table 10. The overall structure of the parameters' tables of the subsystem "Data acquisition".

Parameter's shifr <SHIFR>Parameter's name <NAME>Parameter's description <DESCR>To enable <EN>Individual parameters
P3P3Pressure on the diaphragm1...

In addition to controllers and parameters the subsystem "Data acquisition" contains parameter's templates. Parameter's templates are grouped by templates' libraries and are stored in tables of three types: templates' library table (ParamTemplLibs) — table 11, parameter's templates table — table 12 and template's parameters table — table 13.


Table 11. Structure of the templates' library table.

ID <ID>Name <NAME>Description <DESCR>DB table of the library <DB>
baseBasic templatesBasic templates' librarytmplib_base
S7 Templates' Library for Siemens S7 series controllers.tmplib_S7

Table 12. Structure of the templates' table.

ID <ID>Name <NAME>Description <DESCR>Text of the template procedure <PROGRAM>
digAlarmDigital signalAlarm over the discrete parameterJavaLikeCalc.JavaScript
simpleBoardSimple boardsFormation of the simple boards of the analog signal.JavaLikeCalc.JavaScript

Table 13. Structure of the table of the template's parameters.

Template's ID <TMPL_ID>Parameter's ID <ID>Name <NAME>Type <TYPE>Flags <FLAGS>Value <VALUE>Position <POS>
digAlarminÂõîä3144 2
digitBlockcmdOpenOpen command3161 0

17.3. Tables of the "Transports" subsystem

Subsystem "Transports" is divided into incoming and outgoing transports. For each type of transport there is its own table with its own structure. Table names, respectively: Transport_In and Transport_Out. Tables can be supplemented by fields, typical to the type of transport.


Table 14. Structure of the incoming transport's table (Transport_in).

ID <ID>Type <MODULE>Name <NAME>Description <DESCRIPT>Address <ADDR>Protocol <PROT>To start <START>Individual fields of the transports' types
web1SocketsWeb 1Work web transport for proced http requests.TCP::10002:0HTTP1...
SelfSelfSystemTCP 1Test TCP input socket!SocketsTCP::10001:11...

Table 15. Structure of the outgoing transport's table (Transport_out).

ID <ID>Type <MODULE>Name <NAME>Description <DESCRIPT>Address <ADDR>To start <START>Individual fields of the transports' types
tcp_o1SocketsTCP Out 1Output TCP transport 1TCP::100011...

For the centralized description of the list of external OpenSCADA stations it is used the table of external hosts (CfgExtHosts). The structure of this table is shown in Table 16.


Table 16. The structure of the table of external OpenSCADA hosts (CfgExtHosts).

User of the system <OP_USER>ID <ID>Name <NAME>Transport <TRANSP>Address of the remote host <ADDR>User of the external host <USER>Password of the user of the external host <PASS>
tcp_o1SocketsTCP Out 1Output TCP transport 1TCP::100011...

17.4. Tables of the "Archives" subsystem

Subsystem "Archives" contains three tables with fixed names:


Tables of the archivers can be complemented by fields, typical for each type of archiver.


Table 17. Structure of the table of the values' archive (Archive_val).

ID <ID>Name <NAME>Description <DESCR>To start <START>The mode of the values' source <SrcMode>Source of the values <Source>Type of the values <VTYPE>Buffer's periodicity <BPER>Buffer's size <BSIZE>Buffer's hard grid <BHGRD>High resolution of the buffer's time <BHRES>List of the serviced archivers <ArchS>
CPULoad_load 11DAQ.System.AutoDA.CPULoad.load4110000FSArch.1s;DBArch.1m;FSArch.1m;
ai1_dP 00 40.000110011FSArch.POMP_20070301;FSArch.1s;

Table 18. Structure of the table of the values' archivers (Archive_val_proc).

ID <ID>Archiver's type <MODUL>Name <NAME>Description <DESCR>To start <START>Address <ADDR>Values' period <V_PER>Archiving period <A_PER>Individual fields of the archivers' types
1sFSArch One second1ARCHIVES/VAL/1s160...
POMP_20070301FSArch 0ARCHIVES/VAL/POMP_200703010.000160...

Table 19. Structure of the table of the messages' archivers (Archive_mess_proc).

ID <ID>Archiver's type <MODUL>Name <NAME>Description <DESCR>To start <START>Template of the messages' category <CATEG>Messages' level <LEVEL>Address <ADDR>Individual fields of the archivers' types
StatErrorsFSArhStation error 1/DemoStation*4ARCHIVES/MESS/stError/...
NetRequstsFSArhNetwork requests 1/DemoStation/Transport/Sockets*1ARCHIVES/MESS/Net/...

17.5. Tables of the "Security" subsystem

Subsystem "Security" contains two tables: table of the system's users (Security_user) and groups of the system (Security_grp).


Table 20. Structure of the table of the system's users (Security_user).

Name <NAME>Description <DESCR>Password <PASS>Picture <PICTURE>
rootSuperUseropenscada
userUseruser

Table 21. Structure of the table of the system's users groups (Security_grp).

Name <NAME>Description <DESCR>Users in the group <USERS>
rootSuperUser's grouproot;user
usersUser's grouptoot;user

17.6. The structure of the databases of the modules

Each module can have its own database tables to store individual data. Structure of database tables of the modules can be formed freely, based on internal needs.


18. Service functions of the OpenSCADA control interface

Service functions — is an interface to access the OpenSCADA system through the OpenSCADA control interface from external systems. This mechanism is the basis for all exchange mechanisms within OpenSCADA, implemented through weak links and standard exchange protocol of OpenSCADA. Its main advantage is the priority processing and the possibility of using non-standard packaging data. For access to normal data you can use the standard commands of the control interface.

18.1. Group access to the values of the parameter's attributes of the subsystem "Data acquisition", as well as to the detailed information

These requests let you to obtain detailed information about the parameters of the subsystem "Data acquisition", to acquire the values of all attributes of the parameters, and also to make the group setting. Detailed information about requests is given in Table 23.


Table 23. Attributes of the request commands of the attributes' parameters of the subsystem "Data acquisition"

IdNameValue
Request command of information about the attributes of the parameter: <list path="/sub_DAQ/mod_{SRC}/cntr_{CNTR}/prm_{PRM}/%2fserv%2fattr"/>
<el id="iatr"/> Information of the attributes In separate tags the information about attribute is returned.
id
Attribute's ID The character identifier of the single attribute.
nm
Attribute's name The name of the single attribute.
flg
Attribute's flags Flags of the single attribute.
tp
Attribute's type The type of the single attribute.
vals
Values area of the attribute. Values area of the single attribute.
names
The names of the attribute's values for the selective type. The names of the single attribute's values for the selective type.
Team request command of the all values of attributes of the parameter: <get path="/sub_DAQ/mod_{SRC}/cntr_{CNTR}/prm_{PRM}/%2fserv%2fattr"/>
<el id="iatr">val</el> Attributes' values In separate tags the values of the attributes are returned.
The set command of the the values of the specified attributes of the parameter: <set path="/sub_DAQ/mod_{SRC}/cntr_{CNTR}/prm_{PRM}/%2fserv%2fattr"/>
<el id="iatr">val</el> The values of attributes are specified In separate tags the values of attributes are specified.

18.2. Access to archived data of the archives of messages

To request and set the archive data in the archiving subsystem of the messages archive's object the following command is provided <info path="/sub_Archive/%2fserv%2fmess"/>, <get path="/sub_Archive/%2fserv%2fmess"/> and <set path="/sub_Archive/%2fserv%2fmess"/> to request the information about the archive, archive's values and set values to archive, respectively. Into the object of controller of subsystem "Data acquisition" provides service request for messages generated by the data source <get path="/sub_DAQ/{DAQ_TP}/{DAQ_CNTR}/%2fserv%2fmess"/>. The detailed description of these commands is presented in Table 24.


Table 24. Attributes of request commands of information about the archive of values and archive data

IdNameValue
Request command of the information about the archive: <info path="/sub_Archive/%2fserv%2fmess"/>
arch Setting the name of the archive's archiver Archive's archiver, for which to specify the parameters.
end Control of the archive's top in the given archiver As a result of the request points to the real top of the messages' archive in the given archiver <arch>.
beg Control of the archive's depth in the given archiver As a result of the request points to the real depth of the messages' archive in the given archiver <arch>.
Request command of the archival and/or current data: <get path="/sub_Archive/%2fserv%2fmess"/>
tm Time set Time of the block's top of the messages' archive.
tm_grnd Time set of the foundation/beginning of the archive Points to the foundation/beginning of the archive.
arch Setting of the archive's archiver Specifies at what archiver to request the values. If the archiver is not specified, the request will be made consistently in all archivers with the exception of duplicates.
cat Setting the message's category Specify the category/template of the requested messages.
lev Setting the level of importance Specifies the importance level of messages for which and above to get the messages.
<el>{mess}</el> Messages In separate tags the messages are returned.
time, utime
Message's time (seconds, microseconds) Time of the separate message.
cat
Message's category Category of the separate message.
lev
Message's level Level of the separate message.
Set command of the archival data: <set path="/sub_Archive/%2fserv%2fmess"/>
<el>{mess}</el> Messages In separate tags the messages for set.
time, utime
Message's time (seconds, microseconds) Time of the separate message.
cat
Message's category Category of the separate message.
lev
Message's level Level of the separate message.
Request command of the archival and/or current data of the data source: <get path="/sub_DAQ/{DAQ_TP}/{DAQ_CNTR}/%2fserv%2fmess"/>
tm Time set Time of the block's top of the messages' archive. If the value is zero then set and return here current time value.
tm_grnd Time set of the foundation/beginning of the archive Points to the foundation/beginning of the archive.
<el>{mess}</el> Messages In separate tags the messages are returned.
time, utime
Message's time (seconds, microseconds) Time of the separate message.
cat
Message's category Category of the separate message.
lev
Message's level Level of the separate message.

18.3. Access to archived data of the values' archive

To request the archive data in the archiving subsystem of the values archive's object and parameter's attribute object of "Data acquisition" subsystem the following command is provided <info path="{a_p_addr}/%2fserv%2fval"/> è <get path="{a_p_addr}/%2fserv%2fval"/> to request the information about the archive's and archive values respectively. Attributes of these commands, involving various mechanisms of the request are presented in Table 25.


Table 25. Attributes of the request commands of information about the archive of archive data

IdNameValue
Request command of the information about the archive: <info path="{a_p_addr}/%2fserv%2fval"/>
arch Setting the name of the archive's archiver Archive's archiver, for which to specify the parameters.
end Control of the archive's top in the given archiver As a result of the request points to the real top of the values' archive in the given archiver <arch>. In the case of the archive's absence the attribute is set to "0".
beg Control of the archive's depth in the given archiver As a result of the request points to the real depth of the values' archive in the given archiver <arch>. In the case of the archive's absence the attribute is set to "0".
per Control of the archive's periodicity in the given archiver As a result of the request points to the real periodicity of the values' archive in the given archiver <arch>. In the case of the archive's absence the attribute is set to "0".
vtp Control of the archive's/parameter's type of value Returns the code of the type of the archive data values: 0 — Boolean, 1 — Integer, 4 — Real, 5 — String. But this property is only available in the case of request at the parameter without archive!
Request command of archive or/and current data <get path="{a_p_addr}/%2fserv%2fval"/>
tm Setting and control of time Time of the requested value or top of the archive values' block. If the attribute is not specified or equal to "0", the last value is returned. The value of this attribute is set to the value of time of obtained value or of the top of the archival data block.
tm_grnd Setting and control of the foundation/beginning time of the archive Points to the foundation/beginning of the archive. If the attribute is not specified or equal to "0", then the request of one value is made. The value of this attribute is set to the foundation of the block of archival data time.
per Setting and control of the periodicity of the obtained values Periodicity of requested values. If the attribute is not specified or equal to "0" or less than the real periodicity of the archive, then the values will be returned with the real periodicity of the archive and the value of this attribute will be set to the real periodicity value. If the attribute's value is more than the actual periodicity, the values of the archive will be averaged to the specified periodicity.
arch Setting and control of the archive's archiver Specifies at what archiver to request the values. If the archiver is not specified, the request will be made consistent with the priority from best to worst. The name of the archiver, from whom the values are obtained, will be indicated in this attribute when returning the result. If the archiver for this parameter is not set, or such archiver is not present, then the value of this attribute will be reset. In the case of the request, crossing several archivers, the processing occurs only for the first archiver with the specification of its name and dimension in the relevant attributes. To request the data of follow-up archivers the request is repeated starting from the dimension of the previous request.
mode Setting and control of the mode of transfer of the archive data

The form in which it is desirable to obtain the archive data is specified. The following modes/forms of transfer of archives' data are provided:

0 — Simple record: single value — one string without packaging of the related values. In the case of string archive the values are encoded to exclude the newlines characters. Example of the writing form:
34.5678
23.6543
65.8754
34.6523

1 — Packed record on the principle of folding the related values: one value — one record. Before each value it is indicated its position number, separated by the space:

0 34.5678
1 23.6543
4 65.8754
6 34.6523

2 — The array of unpackaged binary values encoded by Mime Base64. Can not be used for string archives.
real_prec Setting the precision of the real values Specifies the precision with which to transmit the data of real values in the "0" and "1" mode. By default, this precision is 6 digits.
round_perc Setting the rounding percent Indicates the rounding percentage of related numeric values for the mode of "1".
Request name for archived parameter or same archive: <name path="{a_p_addr}/%2fserv%2fval"/>

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!

20. Debugging and Testing the OpenSCADA project

To monitor the quality of code and test the performance of various parts of the system the special modules are written that perform testing with the issue of testing protocol. These modules must be executed after the completion of any part of the project.

21. Rules for design and commenting of the sources of OpenSCADA and its modules

When writing and design of the sources of the OpenSCADA system and its modules you must to follow the rules:

indent -bli0 -i4 -ts8 -l100 -npsl -npcs -nprs -nsaf -nsai -nsaw -brs -br -cdw -nbc -lp <filename>.

Commenting rules of the OpenSCADA sources:

22. Ñonventional signs in the text and source code

???? — doubt in the usefulness of this section;
?!?! — the section is not fully implemented;
!!!! — the section requires a rethinking.


Ññûëêè

Referring pages: HomePageEn/Doc
HomePageEn/Doc/ModuleBuild
HomePageEn/Doc/OPCUA
HomePageEn/Doc/OpenSCADA060
HomePageEn/Doc/ProgrammManual/part5
HomePageEn/Doc/SelfSystem
HomePageEn/Doc/VCAEngine
HomePageEn/Doc/VCAconcept
HomePageEn/Doc/VCAconcept/part4
HomePageEn/Doc/VCAconcept/part4/part14
HomePageEn/Doc/VCAconcept/part4/part5
HomePageEn/Doc/VCAconcept/part6/part1
HomePageUk/Doc/SelfSystem