OpenSCADA

Documents/API

This page contains changes which are not marked for translation.

English • ‎mRussian • ‎Українська

This page describes an application programming interface (API) of OpenSCADA.

OpenSCADA is a project of the open SCADA-system based on the modular principle. The document contains exhaustive information of the internal architecture of the OpenSCADA objects. Additionally there is provided of information about the object's attributes and methods.

At.png This document is intended for programmers wishing to understand the architecture of OpenSCADA and to develop extensions for it. The document is not intended mostly for users and integrators of OpenSCADA, although some things can be useful to them to understand the work.

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

Contents

1 Internal structure

For a visual and accessible understanding of the OpenSCADA architecture, Figure 1 shows a static diagram of the OpenSCADA classes in the Universal Modeling Language (UML).

It can be seen from the diagram that OpenSCADA contains modular subsystems: "Archives-History", "Databases", "Transports", "Transport protocols", "User Interfaces", "Data Acquisition" and "Special", as well as subsystems: "Security" and "Module's management". The diagram shows the relationships between modular subsystems and modules of the corresponding types.

Fig. 1. Static class diagram.

2 Overall structure of the program — modularity

The root, from which we construct the whole program, is the object #TSYS. The root contains subsystems #TSubSYS. The subsystems can be ordinary and modular. Difference the modular subsystems is clearly shown in Figure 1. Thus, modular subsystems necessarily contain a list of modular objects #TModule, for example, the archive-history subsystem #TArchiveS contains the modular objects #TTypeArchivator. Meanwhile, the normal subsystem does not contain such objects, for example, the security subsystem #TSecurity (Fig. 2).

Fig. 2. Hierarchical structure of OpenSCADA.

The root initialization process #TSYS defines a global variable "SYS" that can be used to directly access the root of the application from any of its nodes. The root initialisation is done once from the calling main function. After starting, control is captured by the root object of the program until it stops. The root object concentrates all the common functions of OpenSCADA.

The continuation of the root object #TSYS, which performs the functions of maintaining the flow of program messages, is the object #TMess, which is available through the global variable "Mess" initialised by the root of the program. The object contains functions of encoding, decoding and localisation of messages.

The subsystems #TSubSYS implement functions that are individual to each subsystem and with access common to all subsystems through the #TSubSYS object. The modular subsystem has the possibility of expanding functionality through modules, for which it provides access to modules of its type in the form of modular objects.

A module is a component of a modular subsystem. A module provides information about itself, its origin, and the functions it exports. A separate module implements 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:

1 — to syslog;
2 — to stdout;
4 — to stderr;
8 — to the archive.

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 "DB"

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).

Fig. 3. Hierarchical structure of the subsystem "DB".

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. More about the data organisation conception you can read in the Data in OpenSCADA and their storage section.

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 OpenSCADA open tables (TTable) available in the database and work with them.

3.1 Object of subsystem "Database" (TBDS)

Inherits: TSubSYS

Data:
Flags of the function dbList() (enum – TDBS::DBLsFlg):

Flags of the queries to the storage (enum – TDBS::ReqGenFlg):

Specific flags

Public generic static methods:

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 attributes:

Protected methods:

3.4 The object of the table (TTable)

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

Data:
Flags of the SQL requests (enum – TTable::SQLFeqFlag):

Item of the table structure (class — TTable::TStrIt):

Public methods:

Protected attributes:

4 Subsystem "Data acquisition"

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.

Fig. 4. Hierarchical structure of the subsystem "Data acquisition".

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:

At.png Will be removed in v1.0, use TController::tbl() instead.
At.png Will be removed in v1.0.

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".

Data:
Flags of the enabling/disabling modes of the node (enum TParamContr::EnDisFlag):

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:

4.9.1 The object of the implementation of the template's parameters of the "DAQ" subsystem (TPrmTempl::Impl)

Inherits: TValFunc

Data:
Structure of template links (class — TPrmTempl::Impl::SLnk):

Public methods:

Protected attributes:

Protected methods:

5 Subsystem "Archives-History"

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.

Fig. 5. Hierarchical structure of the 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 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: 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: TSubSYS

Modes of forming ID of the automatic created archives:

Public methods:

Public methods:

5.2 The object of the values' archive (TVArchive)

Inherits: TCntrNode, TValBuf, TConfig

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

The data combination mode (enumeration — TVArchive::CombMode):

Data modes of the service request "Requesting for values of the specified value archive" (enumeration — TVArchive::ServReqDtMode):

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"

"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 input and TTransportOut of the output transports. The overall structure of the subsystem is shown in Fig. 6.

Fig. 6. Hierarchical structure of the subsystem "Transports".

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 input transport TTransportIn provides an interface to the implementation of the modular method of input transport.

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

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

Inherits: TSubSYS

Data:
Definitions of space the Transport subsystem (definition):

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

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

Data types of the IO logs (enum — TTransportS::LogType):

Public methods:

"{TrModule}.[out_]{TrID}[:{TrAddr}]" — typical output with automatic creation TrID at it missing and allowing TrAddr;
"{TrModule}.in_{TrID}:{RemConId}" — initiative input with the connection identifier in RemConId.

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 input transports (TTransportIn)

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

Data:
Stages of the new Associated Output Transports processing (enum — TTransportIn::AssociateTrStage):

Public methods:

Protected methods:

Protected attributes:

6.4 The object of the output transports (TTransportOut)

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

Public methods:

Protected methods:

Protected attributes:

7 Subsystem "Transport protocols"

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 input protocols TProtocolIn.

TProtocolS object provides an access to the both: the input and the output protocols of the individual types of transport protocols. The inner side of output 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 input protocol's session (TProtocolIn)

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

Public methods:

8 Subsystem "User interfaces"

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"

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"

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 (TSecurity)

Inherits: TSubSYS

Data (definition):

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 scheduler"

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 OpenSCADA

Object model of OpenSCADA 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.

Fig. 7. Basis of the programming area of OpenSCADA.

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 OpenSCADA and their storage

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

The 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 that structure is enough to create, control and manage the real structure of the database. Elementary unit of the record is the cell TFld.

The 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 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 storing conception

OpenSCADA commonly defines and uses as the storage only the Configuration File and the Data Bases of different types of the "DB" subsystem. Where the Configuration File has the highest priority as an obligatory and always present storage.

The Generic Storage is a common system configuration field of selection a storage for common program data and as default storage value of OpenSCADA nodes to store. As the Generic Storage there can be selected whether the Configuration File "<cfg>" or a DB "{DB module}.{DB name}", and the same is pointed as "<gen>" for enabling the implicit data accessing method in OpenSCADA nodes.

There are provided two variants of the data accessing:

  1. directly and exclusively at the specified storage name;
  2. implicitly at specifying the Generic Storage name "<gen>", what commonly means of accessing to the Configuration File firstly and the Generic Storage DB secondary, at the data missing in the Configuration File.

The "DB" subsystem (the class TBDS) provides the functions dataSeek(), dataGet(), dataSet(), dataDel() of accessing the data which perform the data accessing variants in such ways:

  1. seeking data only the directly specified storage;
  2. throughout seeking the Configuration File and the Generic Storage DB.
  1. getting data only the directly specified storage;
  2. getting the present data in the Configuration File, next the Generic Storage DB data at missing in the Configuration File.
  1. setting data only to the directly specified storage;
  2. setting the present data in the Configuration File, next the Generic Storage DB data at missing in the Configuration File; provides the flag TBDS::OnlyCfg support to force the new data creation in the Configuration File.
  1. deleting data only in the directly specified storage;
  2. deleting the data both in the Configuration File and the Generic Storage DB.

The testing scenarios of the data accessing:

13.2 Data object (TConfig)

Inherits: TValElem
Inherited: TParamContr, TController, TMArchivator, TPrmTempl, TPrmTmplLib, TUser, TGroup, TTransportIn, TTransportOut, TBD, TVArchive, TVArchivator, as well as modular objects that store their data in the DB.

Public methods:

Protected methods:

13.3 Data cell (TCfg)

Inherits: TVariant

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

Requests flags (enum — ReqFlg):

Public methods:

13.4 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.5 Data structure cell (TFld)

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

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

Public methods:

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

Inherited: TValue, TConfig

Protected methods:

13.7 Data cell (TVariant)

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

Типы данных (enum — TVariant::Type):

Public methods:

13.8 User object (TVarObj)

Inherited: TArrayObj

Public methods:

14 Control Interface and dynamic tree of program objects

For complete coverage of the key components of the program by the network of objects the same structure, the object of the dynamic tree's node #TCntrNode is provided. The object 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, the node is able to preact the inclusion and exclusion/removing of the node from the tree with the possibility of reject from the exclusion/removal.

The Control Interface is included in the #TCntrNode object and it covers all nodes of the dynamic tree of the program, allowing uniform control of the program regardless of the client tool used. The Control Interface is made on the basis of the XML markup language and for which you can come up with many ways to use, for example, we note the following most indicative solutions:

The Control Interface is implemented by the following components:

The information hierarchical structure contains information about public control elements and it can be used to build user dialogs of the node's control of the program.

The dynamic part contains scripts for servicing requests to the control elements, which are described in the information structure, and to hidden control elements in the form of service functions used for unified access to the node.

The container allows you to assemble several information structures and dynamic parts into one request, thereby optimizing the request time, especially on high-latency network interfaces.

The general Control Interface is built from individual nodes of the dynamic tree. Hierarchical inheritance from the object #TCntrNode allows you to implement multi-level addition of the configuration of the Control Interface. The view of the dynamic tree of nodes is shown in Figure 8.

Nodes, containing data for the Control Interface, should also be connected to the dynamic object tree.

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

14.1 Syntax of the request and response of the Control Interface

All exchange with the Control Interface takes place through the XML language. At the same time, the internal exchange is carried out by the parsed structure of the XML language, and the external exchange is carried out by converting into a symbol stream of the solid XML-file and back.

The request is made by sending a tag with parameters in the attributes. The result is placed into the resulting tag with some attributes modified. In general, the request tag can be written: <{req} path="{path}" user="{user}">{text}</{req}>. Where:

The result of the request is marked in the response by setting the rez attribute to the value: 0-successful, 1-warning, 2-error. In the event of an error the message is written to the "text" of the tag and the attribute "mcat" (the message category) — <{req} path="{path}" user="{user}" rez="2" mcat="/sub_DAQ/mod_BlockCalc">Impossible to remove the node</{req}>. In the event of a warning the message is written to the attribute "mtxt" and the attribute "mcat" (the message category) with storing the main tag's data — <{req} path="{path}" user="{user}" rez="1" mcat="/sub_DAQ/mod_BlockCalc" mtxt="Restart after the operation!">{main data}</{req}>.

The 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 the 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 Requesting the control information structure — <info user='{user}' lang='{lang}' path='{path}' />

The information request returns the hierarchical structure of the configuration provided by the node. The request usually does not contain the "path" attribute and extends to the entire node, although in complex cases of requesting a part of the information tree, the path of the element of the branch from which to receive the configuration can be specified.

The request will result in the information structure of the page according to the privileges of the requesting user — the fields of which are considered uniform and are described below with respect to the specifics of the information here, as well as the available commands. Everything outside the unification is considered service requests with a specific structure, which are described accordingly in the service functions section.

Tags of information elements provide mandatory attributes:

  • 0 — no access at all, fields are deleted with such rights;
  • 4 (SEC_RD) — read access;
  • 2 (SEC_WR) — write access, usually this value does not make sense, since write access also implies read access;
  • 6 (SEC_RD|SEC_WR) — read and write access.
At.png That is, the lower three bits of the attribute "acs" number contain the actual access of the specified user, and the next three bits (3..5) contain the maximum possible rights, for example, 064(52) — is the maximum full access and actual only for reading.

Table. Table of all possible information elements in the structure.

Tag (contents) Description
oscada_cntr

(img, branches, area)

Represents the node as a whole, which, single — the ROOT is included directly in the tag info and contains information tags of elements and fields. Attributes:
  • id — NONE;
  • dscr — defines the localized description of the node;
  • doc — address of the documentation page of this node in the form "{WikiPage}|{OffLinePage}".

At.png The tag img directly in this one must be single, with the identifier (id) "ico" and it represents the page icon.

branches

(grp)

The container of the groups of child branches of the node. Attributes:
  • id — the container identifier, it is ALWAYS "br";
  • dscr — NONE.
grp The group of the child nodes. Attributes:
  • id — prefix of the group of child nodes in the program;
  • dscr — defines the localized description of the node group;
  • acs — access: SEC_RD — visibility (get), SEC_WR — adding (add) and removing (del) group elements.
  • idm — indication of presence of name in group elements and allowable size of the name for value > 1;
  • idSz — allowable size of element identifiers.
area

(area, fld, list, table, comm, img)

The visual areas. The page with the final elements-fields of the configuration must contain at least one area of visual display with the tag, where the first in the hierarchy in the configurators are tabs, and the rest are the included groups. Attributes:
  • acs — access: SEC_RD — visibility.
comm

(fld)

Commands to the node. 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, which described with "fld". Attributes:
  • acs — access: SEC_RD — visibility, SEC_WR — invoke the commands (set);
  • help — command help;
  • tp — command type, absent for ordinal commands or "lnk" for links (get for SEC_RD).
fld The standard data types representing and input. Attributes:
  • acs — access: SEC_RD — visibility (get), SEC_WR — modification (set);
  • help — help of the field;
  • tp — the element type:
    • "str" (len, dest, cols, rows) — the string element;
    • "dec" (len, max, min, dest) — integer in decimal;
    • "oct" (len, max, min, dest) — integer in octal;
    • "hex" (len, max, min, dest) — integer in hexadecimal;
    • "real" (len, max, min, dest) — real number;
    • "bool" — the boolean sign [0|1];
    • "time" — time-date in seconds, from 01/01/1970.

Related:

  • len — value length in chars;
  • min — minimum of the value;
  • max — maximum of the value;
  • cols — limiting number of columns;
  • rows (SnthHgl) — minimum rows number, > 1 means the text fields with syntax highlight rules at "SnthHgl";
  • dest — the input method:
    • "select" (select or sel_list, sel_id) — selective type;
    • "sel_ed" (select or sel_list, sel_id) — selective type with the possibility of editing.
  • select — path for requesting the dynamic selection list (get);
  • sel_list — static list of names, separator by ';';
  • sel_id — static list of the identifiers to the names in "sel_list", separator by ';';
  • SnthHgl — sign of the syntax highlight rules presence for the text fields, the rules getting by the command SnthHgl.
list List of the standard data types. Attributes:
  • acs — access: SEC_RD — visibility (get), SEC_WR — invoke the commands from "s_com" (add, ins, del, edit, move);
  • help — help of the list;
  • tp — also as in fld except:
    • "br" (br_pref) — child nodes.
  • idm — sign of the indexed (with the identifiers) list (0|1);
  • idSz — allowable size of element identifiers;
  • s_com — ways of the list modification as the list "[add][,ins][,edit][,del][,move]":
    • "add" — rows adding;
    • "ins" — rows inserting;
    • "edit" — rows modifying;
    • "del" — rows deleting;
    • "move" — rows moving.

Related:

  • br_pref — prefix of the representing child nodes;
  • dest — the same as in fld.
table

(list)

Table of the standard data types. Attributes:
  • acs — access: SEC_RD — visibility (get), SEC_WR — invoke the commands from "s_com" (add, ins, del, move, {user}) and allow the cell values change (set);
  • help — help of the table;
  • key — list of the key columns, if the attribute is specified and it lists the columns, the work with the table moves to the addressing mode by the specified column values as the key.
  • rows — minimum table height in rows;
  • s_com — ways of the table modification as the list "[add][,ins][,del][,move][,{user}]":
    • "add[:{CustName}]" — rows adding, with the menu item custom name "CustName";
    • "ins[:{CustName}]" — rows inserting, with the menu item custom name "CustName";
    • "del[:{CustName}]" — rows deleting, with the menu item custom name "CustName";
    • "move" — rows moving;
    • "{user}[:{name}]" — user command to a row or in whole table with the menu item name "name".
img Image. That is provided for transferring the images to the clients of Control Interface. As the image may there can be: page icons, diagrams and other data that can be represented in the graphical form. Attributes:
  • acs — access: SEC_RD — visibility (get), SEC_WR — available for loading and clearing (set);
  • help — help of the image;
  • h_sz — horizontal size limitation;
  • v_sz — vertical size limitation.

The complex example of the informational structure:

<info lang="en" user="roman" rez="0"><oscada_cntr acs="36" dscr="OpenSCADA station: &quot;AGLCS&quot;" doc="Program_manual|Documents/Program_manual">
  <branches id="br" acs="36">
    <grp id='in_' descr='Input transport' acs='52' idSz='30' idm='50'/>
    <grp id='out_' descr='Output transport' acs='52' idSz='30' idm='50'/>
  </branches>
  <img id="ico" acs="36" />
  <area id="gen" acs="36" dscr="Station">
    <fld id="id" acs="36" dscr="Station" tp="str" help="Identifier" />
    <fld id="stat" acs="54" tp="str" help="Name" />
    <fld id="config" acs="36" dscr="Configuration file" tp="str" />
    <fld id="workdir" acs="36" dscr="Work directory" tp="str" dest="sel_ed" select="/gen/workDirList" />
    <fld id="moddir" acs="36" dscr="Modules directory" tp="str" dest="sel_ed" select="/gen/modDirList" />
    <area id="env" acs="36" dscr="Environment">
      <fld id="prog" acs="36" dscr="Program" tp="str" />
      <fld id="sys" acs="36" dscr="System" tp="str" len="30" />
      <fld id="time" acs="36" dscr="System time" tp="str" />
      <fld id="clk" acs="36" dscr="System planning clock" tp="str" />
      <fld id="user" acs="36" dscr="System user" tp="str" />
      <fld id="in_charset" acs="36" dscr="Language" tp="str" help="System locale charset." />
      <fld id="lang" acs="54" tp="str" dest="sel_ed" sel_list="en_US.UTF-8;uk_UA.UTF-8;ru_RU.UTF-8"
           help="Complete locale information with language, country and charset in the view &quot;en_GB.UTF-8&quot;." />
      <fld id="host" acs="36" dscr="Host name" tp="str" />
      <fld id="CPU" acs="36" dscr="CPU" tp="str" />
      <fld id="mainCPUs" acs="54" tp="str"
           help="Main CPUs set.&#010;To set up the processors you use, write a row of numbers separated by the character &#039;:&#039;.&#010;
Processor numbers start at 0." />
      <fld id="taskInvPhs" acs="54" dscr="Number of phases of the task invoking" tp="dec"
           help="To set up phasing of the task invoking in the determined phases number,&#010; &lt;= 0 to set optimal, 1 to disable the tasks phasing." />
    </area>
  </area>
  <area id="subs" acs="54" dscr="Subsystems">
    <list id="br" acs="36" dscr="Subsystems" idm="1" tp="br" br_pref="sub_" />
  </area>
  <area id="arch" acs="54" dscr="Archives">
    <table id="arch" acs="36" dscr="Archives">
      <list id="0" acs="36" dscr="Archive" tp="str" />
      <list id="1" acs="36" dscr="Period, seconds" tp="real" />
      <list id="2" acs="36" dscr="Buffer size" tp="dec" />
      <list id="3" acs="36" dscr="Last read buffer" tp="str" />
      <list id="4" acs="36" dscr="Files size" tp="str" />
    </table>
    <comm id="exp" acs="54" dscr="Export">
      <fld id="arch" acs="54" dscr="Archive" tp="str" dest="select" select="/arch/lst" />
      <fld id="beg" acs="54" dscr="Begin" tp="time" />
      <fld id="end" acs="54" dscr="End" tp="time" />
      <fld id="tfl" acs="54" dscr="Type" tp="str" dest="select" select="/arch/tpflst" />
      <fld id="file" acs="54" dscr="To file" tp="str" />
    </comm>
  </area>
</oscada_cntr></info>

14.3 Sending commands of the standard elements — <{cmd} path='{path}'>{text}</{cmd}>

The end configuration fields provide several commands starting from the dynamic information requesting and finishing the control commands. All these commands can be used in your internal procedures independently from requesting the information structure and for flexible OpenSCADA control both locally and remotely in any hierarchy by the User API function SYS.cntrReq().

Besides the unified command description for the standard elements you may need only the element path and which you can obtain in any OpenSCADA configurator what show the path in the status bar or context help. At.png Any not unified behaviour of the specific standard fields means the service requests and that you can learn in the service functions section!

14.3.1 The configuration field — "fld"

Getting the data
REQ: <get path="{path}" />
RESP: <get path="{path}" rez="0">{value}</get>

<get path="/sub_Security/usr_user/%2fprm%2fDESCR" rez="0" user="root">Simple user</get>

Setting the field
REQ: <set path="{path}">{value}</set>

<set path="/sub_Security/usr_user/%2fprm%2fDESCR">Renamed user</set>

Getting the syntax highlight rules of the text field
Allowed at the attribute "SnthHgl" setting in the corresponding information field.
REQ: <SnthHgl path="{path}" />
RESP: <SnthHgl path="{path}" rez="0">{rules tree}</get>

<SnthHgl font="monospace" path="/sub_DAQ/tmplb_base/tmpl_anUnif/%2fio%2fprog" rez="0" user="root">
  <rule color="darkgreen" expr="(&quot;(|\\{2}|\\{4}|\\{6}|\\{8})&quot;|&quot;.*[^\\](|\\{2}|\\{4}|\\{6}|\\{8})&quot;)" min="1">
    <rule color="green" expr="\\([xX][a-zA-Z0-9]{2}|[0-7]{3}|.{1})" font_weight="1" />
  </rule>
  <blk beg="/\*" color="gray" end="\*/" font_italic="1" />
  <rule color="gray" expr="//.*$" font_italic="1" />
  <rule color="darkblue" expr="\b(if|else|for|while|using|new|delete|break|continue|return|function|Array|Object|RegExp)\b" font_weight="1" />
  <rule color="darkblue" expr="\b(var|in)(?=\s+\w)" font_weight="1" />
  <rule color="darkblue" expr="(\?|\:)" font_weight="1" />
  <rule color="darkorange" expr="\b(0[xX][0-9a-fA-F]*|[0-9]*\.?[0-9]+|[0-9]*\.?[0-9]+[eE][-+]?[0-9]*|true|false)\b" />
  <rule color="darkblue" expr="(\=|\!|\+|\-|\&gt;|\&lt;|\*|\/|\%|\||\&amp;|\^|\~)" font_weight="1" />
  <rule color="blue" expr="(\;|\,|\{|\}|\[|\]|\(|\))" />
</SnthHgl>

14.3.2 The list field — "list"

Getting the data
REQ: <get path="{path}" />
RESP: <get path="{path}" rez="0">{elements list}</get>

<get path="/sub_BD/mod_SQLite/%2fdb%2fodb" rez="0" user="root">
  <el id="GenDB">Main DB</el>
  <el id="OscadaLibs">OscadaLibs</el>
  <el id="vcaBase">vcaBase</el>
  <el id="vcaElectroEls">vcaElectroEls</el>
  <el id="vcaTest">vcaTest</el>
</get>

Adding the item
Allowed at "add" in the attribute "s_com" of the corresponding information field.
REQ: <add path="{path}" id="{itId}">{itName}</add>

  <add path="/sub_BD/mod_SQLite/%2fdb%2fodb" id="test">Test</add>

Inserting the item
Allowed at "ins" in the attribute "s_com" of the corresponding information field.
REQ: <ins path="{path}" pos="{pos}" p_id="{posId}" id="{itId}">{itName}</ins>

  <ins path="/sub_BD/mod_SQLite/%2fdb%2fodb" pos="1" p_id="OscadaLibs" id="test">Test</ins>

Removing the item
Allowed at "del" in the attribute "s_com" of the corresponding information field.
REQ: <del path="{path}" pos="{pos}" id="{itId}">{itName}</del>

  <del path="/sub_BD/mod_SQLite/%2fdb%2fodb" id="test" />

Editing the item
Allowed at "edit" in the attribute "s_com" of the corresponding information field.
REQ: <edit path="{path}" pos="{pos}" p_id="{posId}" id="{itId}">{itName}</edit>

  <edit path="/sub_BD/mod_SQLite/%2fdb%2fodb" p_id="test" id="test1">Test 1</edit>

Moving the item
Allowed at "move" in the attribute "s_com" of the corresponding information field.
REQ: <move path="{path}" pos="{pos}" to="{toPos}" />

  <move path="/sub_BD/mod_SQLite/%2fdb%2fodb" pos="5" to="4" />

14.3.3 The table field — "table"

Getting the data
REQ: <get path="{path}" />
RESP: <get path="{path}" rez="0">{elements lists}</get>

<get path="/sub_DAQ/tmplb_base/tmpl_digitBlockUnif/%2fio%2fio" rez="0" user="root">
  <list acs="54" id="0">
    <el>com</el>
    <el>close</el>
    <el>stop</el>
    <el>st_open</el>
    <el>st_close</el>
    <el>tCmd</el>
    <el>last_cmd</el>
    <el>w_tm</el>
  </list>
  <list acs="54" id="1">
    <el>Command "Open"</el>
    <el>Command "Close"</el>
    <el>Command "Stop"</el>
    <el>State "Opened"</el>
    <el>State "Closed"</el>
    <el>Time to hold the command, seconds</el>
    <el>Last command</el>
    <el>Process command counter</el>
  </list>
  <list acs="54" id="2">
    <el>3</el>
    <el>3</el>
    <el>3</el>
    <el>3</el>
    <el>3</el>
    <el>1</el>
    <el>1</el>
    <el>2</el>
  </list>
  <list acs="54" id="3">
    <el>1</el>
    <el>1</el>
    <el>1</el>
    <el>0</el>
    <el>0</el>
    <el>0</el>
    <el>1</el>
    <el>1</el>
  </list>
  <list acs="54" id="4">
    <el>32</el>
    <el>32</el>
    <el>32</el>
    <el>16</el>
    <el>16</el>
    <el>0</el>
    <el>0</el>
    <el>0</el>
  </list>
  <list acs="54" id="5">
    <el>128</el>
    <el>128</el>
    <el>128</el>
    <el>128</el>
    <el>128</el>
    <el>64</el>
    <el>0</el>
    <el>0</el>
  </list>
  <list acs="54" id="6">
    <el>Crane|com</el>
    <el>Crane|close</el>
    <el>Crane|stop</el>
    <el>Crane|st_open</el>
    <el>Crane|st_close</el>
    <el>5</el>
    <el>0</el>
    <el>0</el>
  </list>
</get>

Setting for cell value of the specified row and column
Allowed at the SEC_WR permition.
REQ: <set path="{path}" row="{row}" key_{keyId}="{keyVal}" col="{colId}">{value}</set>

<set path="/sub_DAQ/tmplb_base/tmpl_digitBlockUnif/%2fio%2fio" row="3" col="1">State "Opened" 1</set>

Adding the row
Allowed at "add" in the attribute "s_com" of the corresponding information field.
REQ: <add path="{path}" />

<add path="/sub_DAQ/tmplb_base/tmpl_digitBlockUnif/%2fio%2fio" />

Inserting the row
Allowed at "ins" in the attribute "s_com" of the corresponding information field.
REQ: <ins path="{path}" row="{row}" />

<ins path="/sub_DAQ/tmplb_base/tmpl_digitBlockUnif/%2fio%2fio" row="3" />

Deleting the row
Allowed at "del" in the attribute "s_com" of the corresponding information field.
REQ: <del path="{path}" row="{row}" key_{keyId}="{keyVal}" />

<del path="/sub_DAQ/tmplb_base/tmpl_digitBlockUnif/%2fio%2fio" row="3" />

Moving the row
Allowed at "move" in the attribute "s_com" of the corresponding information field.
REQ: <move path="{path}" row="{row}" to="{toRow}" />

<move path="/sub_DAQ/tmplb_base/tmpl_digitBlockUnif/%2fio%2fio" row="12" to="3" />

User command to the row
Allowed at "{user}" in the attribute "s_com" of the corresponding information field.
REQ: <{user} path="{path}" row="{row}" key_{keyId}="{keyVal}" />

<remTrs path="/%2ftr%2fmess" key_base="BaseMess" />

14.3.4 The image field — "img"

Getting the data
REQ: <get path="{path}" />
RESP: <get path="{path}" rez="0" tp="{dataType}">{Base64 data}</get>

<get path="/sub_DAQ/%2fico" rez="0" tp="png" user="root">iVBORw0KGgoAAAANSUhEUgAAA...AABJRU5ErkJggg==</get>

Setting the data
Allowed at the SEC_WR permition.
REQ: <set path="{path}">{Base64 data}</set>

<set path="/sub_DAQ/%2fico">iVBORw0KGgoAAAANSUhEUgAAA...AABJRU5ErkJggg==</set>

14.3.5 The command field — "comm"

Getting the link value
Actual only for links — the attribute "tp" is "lnk" of the corresponding information field.
REQ: <get path="{path}" />
RESP: <get path="{path}" rez="0">{lnkVal}</get>

<get path="/sub_DAQ/mod_DAQGate/cntr_test/%2fcntr%2fcfg%2fhost_lnk" lang="en" user="roman" rez="0">/Transport</get>

Invoking the command
Allowed at the SEC_WR permition.
REQ: <set path="{path}">{fields}</set>

<set path="/sub_Archive/mod_FSArch/val_1s/%2farch%2fexp" lang="en">
  <fld id="arch">CPULoad_load</fld>
  <fld id="beg">1673942400</fld>
  <fld id="end">1673944800</fld>
  <fld id="tfl">ascii</fld>
  <fld id="file">testComm</fld>
</set>

14.4 Service commands-functions

Service functions are an interface for accessing OpenSCADA from external systems through the Control Interface. This mechanism is the basis of all exchange within OpenSCADA, implemented through weak links and OpenSCADA's own exchange protocol. Its main advantage is priority processing and the possibility of using non-standard data packaging. You can use standard Control Interface commands to access common data.

At.png Not all service functions-requests are described here so to familiarise all presented or them detailing you must see to the function cntrCmdProc() of proper parts of OpenSCADA in the project sources.

14.4.1 Root Node and generic for all nodes

Getting the generic status of the station redundancy
REQ: <st path="/%2fserv%2fredundant" />
RESP: <st path="/%2fserv%2fredundant" rez="0" StLevel="{lev}" />

Scanning the configuration file
REQ[root-root]: <scan path="/%2fgen%2fconfig" />

Node-object requests

Getting for flag of the node modification
REQ: <modify path="/{nPath}/%2fobj" />
  • nPath — path to need node.
RESP: <modify path="/{nPath}/%2fobj" rez="0">{flag}</modify>
  • flag — the node modification status-flag, see to the enumeration TCntrNode::ModifFlag for the details.
<modify path="/Security/user/%2fobj" rez="0" user="roman">1</modify>
Loading the node
REQ: <load path="/{nPath}/%2fobj" force="{force}">{CfgCtx}</load>
  • nPath — path to need node;
  • force — the force loading sign [0|1], the node may be not marked as modified;
  • CfgCtx — the configuration context in the tags "fld" for loading from that, used for remote copying the node configuration.
Saving the node
REQ: <save path="/{nPath}/%2fobj" force="{force}" ctx="{toCfgCtx}" />
  • nPath — path to need node;
  • force — the force saving sign [0|1], the node may be not marked as modified;
  • toCfgCtx — sign [0|1] of saving the node configuration to the configuration context, used for remote copying the node configuration.
RESP: <save path="/{nPath}/%2fobj" force="{force}" ctx="{toCfgCtx}" rez="0">{CfgCtx}</save>
Local copying the specified node
REQ: <copy path="/{nPath}/%2fobj" src="{source}" dst="{destination}" />
  • nPath — path to need node, can be any node in this operation;
  • source — path to the source node;
  • destination — path to the destination node.
Obtaining for child nodes of the specified node, optimised for the networks
REQ: <chlds path="/{nPath}/%2fobj" grp="{group}" icoCheck="{icoCheck}" />
  • nPath — path to need node;
  • group — the child nodes group-prefix;
  • icoCheck — sign [0|1] of only checking the icon presence by setting the attribute "icoSize".
RESP: <chlds path="/{nPath}/%2fobj" grp="{group}" icoCheck="{icoCheck}" rez="0">{nodes}</chlds>
  • nodes — nodes in the tags "el", where the name is in the tag text and the identifier in the attribute "id" for nodes with identifiers; the "el" tags contains additional tags and attributes:
    • ico — tag with data of the icon at not setting "icoCheck";
    • icoSize — size of the node icon at it presence and setting "icoCheck";
    • grp — tags of groups of the child nodes with the extra attributes:
      • chPresent — sign of the child nodes presence for the group.
<chlds grp="mod_" icoCheck="1" path="/Transport/%2fobj" rez="0" user="roman">
  <el icoSize="10348" id="Sockets">Sockets
    <grp acs="54" chPresent="1" dscr="Input transport" id="in_" idSz="20" idm="100" />
    <grp acs="54" chPresent="1" dscr="Output transport" id="out_" idSz="20" idm="100" />
  </el>
  <el icoSize="7148" id="Serial">Serial interfaces
    <grp acs="54" chPresent="1" dscr="Input transport" id="in_" idSz="20" idm="100" />
    <grp acs="54" chPresent="1" dscr="Output transport" id="out_" idSz="20" idm="100" />
  </el>
  <el icoSize="8944" id="SSL">SSL
    <grp acs="54" chPresent="1" dscr="Input transport" id="in_" idSz="20" idm="100" />
    <grp acs="54" chPresent="1" dscr="Output transport" id="out_" idSz="20" idm="100" />
  </el>
</chlds>

Generic lists

Obtaining the list of the DBs or tables
REQ: <get path="/{nPath}/%2fdb%2flist[:onlydb]" />
<get path="/{nPath}/%2fdb%2ftblList[:onlydb]" />
  • nPath — path to need node, can be any node in this operation;
  • "onlydb" — the address addition to point of listing only data bases without the group marks.
RESP: <get path="/{nPath}/%2fdb%2flist[:onlydb]" rez="0">{list}</get>
<get path="/{nPath}/%2fdb%2ftblList[:onlydb]" rez="0">{list}</get>
  • list — elements in the tags "el".
<get path="/%2fdb%2flist:onlydb" rez="0" user="roman">
  <el>SQLite.vcaTest</el>
  <el>SQLite.vcaBase</el>
  <el>SQLite.vcaAGLKS</el>
  <el>MySQL.vcaTest</el>
  <el>MySQL.vcaBase</el>
  <el>PostgreSQL.testRelease</el>
  <el>PostgreSQL.test</el>
  <el>FireBird.testRelease</el>
  <el>FireBird.testFB</el>
  <el>FireBird.arch</el>
  <el>DBF.testRelease</el>
</get>
Obtaining the list of the supported internal programming languages
REQ: <get path="/{nPath}/%2fplang%2flist" />
  • nPath — path to need node, can be any node in this operation.
RESP: <get path="/{nPath}/%2fplang%2flist" rez="0">{list}</get>
  • list — elements in the tags "el".
<get path="/%2fplang%2flist" rez="0" user="roman">
  <el />
  <el>JavaLikeCalc.JavaScript</el>
</get>

14.4.2 The subsystem "Data Bases (DB)"

Sending the SQL request to the DB
REQ[root-BD]: <call path="/BD/{MOD}/{DB}/%2fserv%2fSQL" withRez="{withResult}" intoTrans="{intoTrans}">{request}</call>

RESP: <call path="/BD/{MOD}/{DB}/%2fserv%2fSQL" withRez="{withResult}" intoTrans="{intoTrans}" rez="0">{result}</call>

<call path="/BD/SQLite/GenDB/%2fserv%2fSQL" rez="0" user="roman" withRez="1">
  <list>
    <el>user</el>
    <el>root</el>
    <el>root</el>
    <el>roman</el>
    <el>roman</el>
    <el>roman</el>
  </list>
  <list>
    <el>id</el>
    <el>/sub_Protocol/mod_HTTP/AuthTime</el>
    <el>/sub_Protocol/mod_HTTP/AutoLogin</el>
    <el>/sub_UI/mod_QTCfg/st</el>
    <el>/sub_UI/mod_VCAEngine/wdgAttr</el>
    <el>/sub_BD/mod_SQLite/ReqTm</el>
  </list>
  <list>
    <el>val</el>
    <el>10</el>
    <el>&lt;aLog&gt;&lt;it addrs="*" user="user" /&gt;&lt;/aLog&gt;</el>
    <el>1272:942:AAAA/wAAAAEAAAACAAABTwAABh8B/////wEAAAABAA==</el>
    <el>doc</el>
    <el>204us</el>
  </list>
</call>

Requesting the field structure of the specified DB table
REQ: <call path="/BD/{MOD}/{DB}/%2fserv%2ffieldStruct" tbl="{table}" />

RESP: <call path="/BD/{MOD}/{DB}/%2fserv%2ffieldStruct" tbl="{table}" rez="0">{structure}</call>

  • TP — type of the cell, see to the object #TFld;
  • FLAG — flags of the cell, see to the object #TCfg;
  • LEN — whole length of the cell, see lenS() of the object #TFld;
  • DEF — default value of the cell, see def() of the object #TFld;
  • FView, FKeyUse, FNoTransl, FReqKey, FExtVal — dynamic flags of the object #TCfg: view(), keyUse(), noTransl(), reqKey(), extVal().
<call path="/BD/SQLite/GenDB/%2fserv%2ffieldStruct" rez="0" tbl="SYS" user="roman">
  <fld id_str="5:512:16777215.0::1:0:0:0:0" uk#val_str="5:0:16777215.0::1:0:0:0:0" user_str="5:512:16777215.0::1:0:0:0:0" val_str="5:0:16777215.0::1:0:0:0:0" />
</call>

Seeking the fields of the specified DB table
REQ: <call path="/BD/{MOD}/{DB}/%2fserv%2ffieldSeek" tbl="{table}" row="{row}" cacheKey="{cacheKey}">{field}</call>

RESP: <call path="/BD/{MOD}/{DB}/%2fserv%2ffieldSeek" tbl="{table}" row="{row}" cacheKey="{cacheKey}" rez="0" fRez="{fRez}">{field}</call>

<call path="/BD/SQLite/GenDB/%2fserv%2ffieldSeek" tbl="SYS" row="5" cacheKey="0x7f17c8fcd5e0" user="roman" rez="0" fRez="1">
  <fld user="roman" user_str="5:512:16777215.0::1:0:0:0:0" 
       id="/sub_BD/mod_SQLite/ReqTm" id_str="5:512:16777215.0::1:0:0:0:0" 
       val="204us" val_str="5:0:16777215.0::1:0:0:0:0" uk#val_str="5:0:16777215.0::1:0:0:0:0" />
</call>

Getting the field of the specified DB table
REQ: <call path="/BD/{MOD}/{DB}/%2fserv%2ffieldGet" tbl="{table}">{field}</call>

RESP: <call path="/BD/{MOD}/{DB}/%2fserv%2ffieldGet" tbl="{table}" rez="0">{field}</call>

<call path="/BD/SQLite/GenDB/%2fserv%2ffieldGet" rez="0" tbl="SYS" user="roman">
  <fld id="/sub_BD/mod_SQLite/ReqTm" id_str="5:512:16777215.0::1:0:0:0:0"
       user="roman" user_str="5:512:16777215.0::1:0:0:0:0"
       val="204us" val_str="5:0:16777215.0::1:0:0:0:0" uk#val_str="5:0:16777215.0::1:0:0:0:0" />
</call>

Setting the field of the specified DB table
REQ[root-BD]: <call path="/BD/{MOD}/{DB}/%2fserv%2ffieldSet" tbl="{table}">{field}</call>

<call path="/BD/SQLite/GenDB//%2fserv%2ffieldSet" tbl="SYS">
  <fld user_ext="roman" user_str="5:512:16777215.0::0:1:0:0:1"
       id_ext="/sub_BD/mod_SQLite/ReqTm" id_str="5:512:16777215.0::0:1:0:0:1"
       val="205us" val_str="5:0:16777215.0::1:0:0:0:0" />
</call>

Deleting the field of the specified DB table
REQ[root-BD]: <call path="/BD/{MOD}/{DB}/%2fserv%2ffieldDel" tbl="{table}">{field}</call>

<call path="/BD/SQLite/GenDB//%2fserv%2ffieldDel" tbl="SYS">
  <fld user="roman" user_str="5:512:16777215.0::0:1:0:0:0"
       id="/sub_BD/mod_SQLite/ReqTm" id_str="5:512:16777215.0::0:1:0:0:0" />
</call>

14.4.3 The subsystem "Data Acquisition (DAQ)"

Getting the subsystem status of the station redundancy
REQ: <st path="/DAQ/%2fserv%2fredundant" />
RESP: <st path="/DAQ/%2fserv%2fredundant" rez="0" inProc="1" StLevel="{lev}">{status}</st>

<st StLevel="10" inProc="1" path="/DAQ/%2fserv%2fredundant" rez="0" user="roman">
  <cntr id="BlockCalc.CM101" run="1" />
  <cntr id="BlockCalc.CM102" run="1" />
  <cntr id="BlockCalc.CM102cntr" run="1" />
  ...
  <cntr id="ModBus.testTCP" run="1" />
  <cntr id="OPC_UA.test" run="1" />
  <cntr id="System.AutoDA" run="1" />
</st>

Getting list of the DAQ parameters and attributes for browsing
The request reflects the function TDAQS::ctrListPrmAttr() to the network.
REQ: <list path="/DAQ/%2fserv%2fPrmAttr" base="{base}" toPrm="{forPrm}" sep="{sep}" pref="{pref}" />

RESP: <list path="/DAQ/%2fserv%2fPrmAttr" base="{base}" toPrm="{forPrm}" sep="{sep}" pref="{pref}" rez="0">{prmAttrs}</list>

<list base="BlockCalc.gen.F3" path="/DAQ/%2fserv%2fPrmAttr" pref="prm:" rez="0" sep="." toPrm="0" user="roman">
  <el>prm:</el>
  <el>prm:BlockCalc</el>
  <el>prm:BlockCalc.gen</el>
  <el>prm:BlockCalc.gen.F3</el>
  <el>=== Attributes ===</el>
  <el>prm:BlockCalc.gen.F3.SHIFR</el>
  <el>prm:BlockCalc.gen.F3.NAME</el>
  <el>prm:BlockCalc.gen.F3.DESCR</el>
  <el>prm:BlockCalc.gen.F3.err</el>
  <el>prm:BlockCalc.gen.F3.var</el>
</list>

The controller objects

Getting messages related the controller object
That are messages generated by the data sources and requested by TArchiveS::messGet() with proper categories of the data source.
REQ: <get path="/DAQ/{MOD}/{CNTR}/%2fserv%2fmess" tm="{TmUNIX}" tm_grnd="{TmGrndUNIX}" lev="{level}" />
  • MOD, CNTR — the DAQ module and controller object;
  • TmUNIX, TmGrndUNIX — the requested messages' end and start UNIX time stamp from 01.01.1970; at zero "tm" there used whether the current system time or the last redundant message time for redundant systems;
  • level — minimum level of the requested messages, from 0[X] to 7[X].
RESP: <get path="/DAQ/{MOD}/{CNTR}/%2fserv%2fmess" tm="{TmUNIX}" tm_grnd="{TmGrnUNIX}" lev="{level}" rez="0">{messages}</get>
  • TmUNIX — is set in time of the end redundant message or system one - 1, at zero in the request;
  • messages — messages in the "el" tags: <el time="{time}" utime="{utime}" cat="{cat}" lev="{lev}">{mess}</el>
    • time — the message time, as the UNIX time stamp from 01.01.1970;
    • utime — the microsecond part of the message time;
    • cat — the message category;
    • lev — the message level;
    • mess — the message text.
<get lev="1" path="/DAQ/LogicLev/gen/%2fserv%2fmess" rez="0" tm="1674401446" tm_grnd="1674401300" user="roman">
  <el cat="alLogicLev:gen.F3" lev="-2" time="1674401357" utime="386070">
Genericstation &gt; F3: Gas flow through the pipe to Glinsk: Lower warning border error
  </el>
</get>
Setting the message related the controller object
Generating-setting the data source message of the transferred type with the request by TController::messSet().
REQ: <set path="/DAQ/{MOD}/{CNTR}/%2fserv%2fmess" lev="{level}" type2Code="{type2Code}" prm="{prm}" cat="{cat}">{mess}</set>
  • MOD, CNTR — the DAQ module and controller object;
  • level — the message level;
  • type2Code — two symbols ID of the transferred message in the category;
  • prm — identifier of the source parameter, which can be appended by the corresponding attribute ID in the view "{PrmID}.{AttrId}";
  • cat — addition to the unified category with the user information and so on;
  • mess — the message text with the named address before that.
<set path="/DAQ/LogicLev/gen/%2fserv%2fmess" lev="1" type2Code="OP" prm="F3" cat="roman">Value changed : 0 : 1</set>

The DAQ parameters

Obtaining the attributes list of the DAQ parameter (#TValue) with detailed info
REQ: <list path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/%2fserv%2fattr" />
  • MOD, CNTR, PRM — the DAQ module, controller object and parameters.
RESP: <list path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/%2fserv%2fattr" rez="0">{attributes}</list>
  • attributes — attributes in the "el" tags with the detailed information: <el id="{id}" nm="{name}" tp="{type}" flg="{flags}" vals="{values}" names="{names}" />
    • id — identifier of the attribute;
    • name — name of the attribute;
    • type — type of the attribute, see the types in the object #TFld;
    • flags — flags of the attribute, see the flags in the object #TVal;
    • values — the attribute values for the selective types;
    • names — names to values for the selective types.
<list path="/DAQ/LogicLev/gen/prm_F3/%2fserv%2fattr" rez="0" user="roman">
  <el flg="516" id="SHIFR" nm="Identifier" tp="5" />
  <el flg="16" id="NAME" nm="Name" tp="5" />
  <el flg="24" id="DESCR" nm="Description" tp="5" />
  <el flg="260" id="err" nm="Error" tp="5" />
  <el flg="772" id="var" nm="Variable" tp="4" />
  <el flg="784" id="ed" nm="Dimension" tp="5" />
  <el flg="768" id="min" nm="Scale: minimum" tp="4" />
  <el flg="768" id="max" nm="Scale: maximum" tp="4" />
  <el flg="768" id="scSqr" nm="Scale: square" tp="0" />
  <el flg="769" id="subMode" names="no;last;substitute" nm="Substitute: mode" tp="1" vals="0;1;2" />
  <el flg="768" id="subVar" nm="Substitute: variable" tp="4" />
  <el flg="768" id="alSup" nm="Violations suppress" tp="0" />
  <el flg="768" id="alDelay" nm="Violations delay, seconds" tp="4" />
  <el flg="768" id="alNormForceStart" nm="Force NORM violation at the start" tp="0" />
  <el flg="768" id="aMin" nm="Border down alarm" tp="4" />
  <el flg="768" id="aMax" nm="Border up alarm" tp="4" />
  <el flg="768" id="wMin" nm="Border down warning" tp="4" />
  <el flg="768" id="wMax" nm="Border up warning" tp="4" />
  <el flg="768" id="HystBnd" nm="Hysteresis of boders violation" tp="4" />
  <el flg="768" id="speed" nm="Motion speed, %/cycle" tp="4" />
  <el flg="768" id="prec" nm="Precision, signs" tp="1" />
  <el flg="768" id="log" nm="Logarithmic scale" tp="0" />
  <el flg="768" id="Tf" nm="Filter time, seconds" tp="4" />
</list>
Requesting the attributes' values of the DAQ parameter (#TValue)
Very generic request of the attributes' values which the current values and archive-history.
REQ: <get path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/%2fserv%2fattr" sepReq="{sepReq}" hostTm="{hostTm}" prcTm="{prcTm}">{attributes}</get>
  • MOD, CNTR, PRM — the DAQ module, controller object and parameters;
  • sepReq — sign of the separated attributes requesting [0|1];
  • hostTm — use the host time for the current values, so doesn't add the attribute "tm", [0|1];
  • prcTm — the processing time of the previous call, used mostly in the redundancy;
  • attributes — directly requested attributes in the tags:
    • "el": <el id="{id}" />
      • id — identifier of the attribute.
    • "ael" (for archive-history): <ael id="{id}" tm="{time}" />
      • time — begin time of the archive-history requesting in microseconds and the seconds part as the UNIX time stamp from 01.01.1970, that is the time of the last value from the previous request.
RESP: <get path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/%2fserv%2fattr" sepReq="{sepReq}" hostTm="{hostTm}" rez="0" prcTm="{prcTm}">{attributes}</get>
  • prcTm — the system time of the host, as the UNIX time stamp from 01.01.1970;
  • attributes — attributes in the tags:
    • "el": <el id="{id}" tm="{time}">{value}</el>
      • time — the value time in microseconds and the seconds part as the UNIX time stamp from 01.01.1970;
      • value — the current value or at the specified time of the archive in the string form.
    • "ael": <ael id="{id}" tm="{time}" per="{period}">{values}</ael>
      • period — the archive periodicity in microseconds;
      • values — values of the archive part in the tags "v": <v>{value}</v>
    • "del" (only for configuration the new dynamic ones): <del id="{id}" name="{name}" type="{type}" flg="{flags}" values="{values}" selNames="{names}" />
      • type — type of the dynamic attribute, see the types in the object #TFld;
      • flags — flags of the dynamic attribute, see the flags in the object #TVal;
      • values — the dynamic attribute values for the selective types;
      • names — names to values for the selective types of the dynamic attribute.
<get hostTm="1" path="/DAQ/LogicLev/gen/prm_F3/%2fserv%2fattr" prcTm="1674546677" rez="0" user="roman">
  <ael id="var" per="1000000" tm="1674546650000000">
    <v>45.1063015741995</v>
    <v>45.1021080127945</v>
    <v>45.0979561451232</v>
    <v>45.0938498037577</v>
  </ael>
  <el id="SHIFR">F3</el>
  <el id="NAME">F3</el>
  <el id="DESCR">Gas flow through the pipe to Glinsk</el>
  <el id="err">0</el>
  <el id="var">45.0139468054579</el>
  <el id="ed">ton/h</el>
  <el id="min">0</el>
  <el id="max">100</el>
  <el id="scSqr">0</el>
  <el id="subMode">0</el>
  <el id="subVar">0</el>
  <el id="alSup">0</el>
  <el id="alDelay">0</el>
  <el id="alNormForceStart">0</el>
  <el id="aMin">10</el>
  <el id="aMax">90</el>
  <el id="wMin">35</el>
  <el id="wMax">80</el>
  <el id="HystBnd">0</el>
  <el id="speed">0</el>
  <el id="prec">2</el>
  <el id="log">0</el>
  <el id="Tf">2</el>
</get>
Setting multiple attributes' values of the DAQ parameter (#TValue)
REQ[root-DAQ]: <set path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/%2fserv%2fattr">{attributes}</set>
  • MOD, CNTR, PRM — the DAQ module, controller object and parameters;
  • attributes list — attributes in the tags "el": <el id="{id}">{value}</el>
    • id — identifier of the attribute;
    • value — the setting value in the string form.
<set path="/DAQ/LogicLev/gen/prm_F3/%2fserv%2fattr">
  <el id="ed">ton/hour</el>
  <el id="alDelay">1</el>
</set>

Attributes of the DAQ parameter

Requesting the attribute information of the DAQ parameter (#TVal)
Redirection to the archive request "<info path='/Archive/va_{ARCH}/%2fserv%2fval' />" at linking an archive, so for extra attributes and result see there.
REQ: <info path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/a_{ATTR}/%2fserv%2fval" />
  • MOD, CNTR, PRM, ATTR — the DAQ module, controller object, parameters and attribute.
RESP: <info path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/a_{ATTR}/%2fserv%2fval" rez="0" end="0" beg="0" per="0" vtp="{valTp}" />
  • "0" — archive parameters at the archive missing is set to 0;
  • valTp — value type, see to the object #TFld.
<info beg="0" end="0" path="/DAQ/LogicLev/gen/prm_F3/a_ed/%2fserv%2fval" per="0" rez="0" user="roman" vtp="5" />
Requesting the attribute value of the DAQ parameter (#TVal)
Redirection to the archive request "<get path='/Archive/va_{ARCH}/%2fserv%2fval' />" at linking an archive, so for extra attributes and result see there.
REQ: <get path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/a_{ATTR}/%2fserv%2fval" tm="{time}" />
  • MOD, CNTR, PRM, ATTR — the DAQ module, controller object, parameters and attribute;
  • time — time of the requested value in microseconds and the seconds part as the UNIX time stamp from 01.01.1970; for zero value there used the system current time and you'll get the current value at the archive missing.
RESP: <get path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/a_{ATTR}/%2fserv%2fval" tm="{time}" rez="0">{value}</get>
  • time — is set to the requested value real time;
  • value — value of the attribute.
<get path="/DAQ/LogicLev/gen/prm_F3/a_var/%2fserv%2fval" rez="0" tm="1675449270029270" user="roman">45.141100502986</get>
Requesting for name of the attribute for archive linked to that
REQ: <name path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/a_{ATTR}/%2fserv%2fval" />
  • MOD, CNTR, PRM, ATTR — the DAQ module, controller object, parameters and attribute.
RESP: <name path="/DAQ/{MOD}/{CNTR}/prm_{PRM}[/prm_{PRM}]/a_{ATTR}/%2fserv%2fval" rez="0">{name}</get>
  • name — name of the archive.
<name path="/DAQ/LogicLev/gen/prm_F3/a_var/%2fserv%2fval" rez="0" user="roman">F3.Variable</name>
14.4.3.1 The module JavaLikeCalc

Getting for values of the function IO of the controller object
REQ: <get path="/DAQ/JavaLikeCalc/{CNTR}/%2fserv%2ffncAttr" />

RESP: <get path="/DAQ/JavaLikeCalc/{CNTR}/%2fserv%2ffncAttr" rez="0">{IOs}</get>

<get path="/DAQ/JavaLikeCalc/testCalc/%2fserv%2ffncAttr" rez="0" user="roman">
  <a id="f_frq">0.1</a>
  <a id="f_start">0</a>
  <a id="f_stop">0</a>
  <a id="this">&lt;TCntrNodeObj path="/sub_DAQ/mod_JavaLikeCalc/cntr_testCalc/"/&gt;</a>
  <a id="offset">100</a>
  <a id="out">50</a>
  <a id="test">1</a>
  <a id="rez" />
  <a id="inFarg">3</a>
</get>

Setting for values of the function IO of the controller object
REQ[root-DAQ]: <set path="/DAQ/JavaLikeCalc/{CNTR}/%2fserv%2ffncAttr">{IOs}</set>

<set path="/DAQ/JavaLikeCalc/testCalc/%2fserv%2ffncAttr">
  <a id="out">50</a>
  <a id="test">1</a>
</set>


14.4.3.2 The module LogicLev

Getting for values of the template IO of the Logical Level parameter of the controller object
REQ: <get path="/DAQ/LogicLev/{CNTR}/prm_{PRM}[/prm_{PRM}]/%2fserv%2ftmplAttr" />

RESP: <get path="/DAQ/LogicLev/{CNTR}/prm_{PRM}[/prm_{PRM}]/%2fserv%2ftmplAttr" rez="0">{IOs}</get>

<get path="/DAQ/LogicLev/gen/prm_F3/%2fserv%2ftmplAttr" rez="0" user="roman">
  <ta id="in">44.9998202036118</ta>
  <ta id="inProc" />
  <ta id="var">44.9999585116556</ta>
  <ta id="ed">ton/h</ta>
  <ta id="min">0</ta>
  <ta id="max">100</ta>
  <ta id="scSqr">0</ta>
</get>

Setting for values of the template IO of the Logical Level parameter of the controller object
REQ[root-DAQ]: <set path="/DAQ/LogicLev/{CNTR}/prm_{PRM}[/prm_{PRM}]/%2fserv%2ftmplAttr">{IOs}</set>

<set path="/DAQ/LogicLev/gen/prm_F3/%2fserv%2ftmplAttr">
  <ta id="in">44.9998202036118</ta>
  <ta id="var">44.9999585116556</ta>
</set>


14.4.3.3 The module BlockCalc

Getting for values of all block attributes of the controller object
REQ: <get path="/DAQ/BlockCalc/{CNTR}/blk_{BLK}/%2fserv%2fattr" />

RESP: <get path="/DAQ/BlockCalc/{CNTR}/blk_{BLK}/%2fserv%2fattr" rez="0">{attributes}</get>

<get path="/DAQ/BlockCalc/CM101/blk_AT101_1/%2fserv%2fattr" rez="0" user="roman">
  <a id="Fi">50.3839725707191</a>
  <a id="Pi">10.2588208891757</a>
  <a id="Ti">331.149550201738</a>
  <a id="Si">0.071</a>
  <a id="li">10</a>
</get>

Setting for values of list the block attributes of the controller object
REQ[root-DAQ]: <set path="/DAQ/BlockCalc/{CNTR}/blk_{BLK}/%2fserv%2fattr">{attributes}</set>

<set path="/DAQ/BlockCalc/CM101/blk_AT101_1/%2fserv%2fattr">
  <a id="Fi">50.3839725707191</a>
  <a id="Pi">10.2588208891757</a>
</set>


14.4.4 The subsystem "Archives-history"

Getting the subsystem status of the station redundancy
REQ: <st path="/Archive/%2fserv%2fredundant" />
RESP: <st path="/Archive/%2fserv%2fredundant" rez="0" inProc="1" StLevel="{lev}">{status}</st>

<st StLevel="10" inProc="1" path="/Archive/%2fserv%2fredundant" rez="0" user="roman">
  <archM id="DBArch.test" run="1" />
  <archM id="FSArch.NetRequsts" run="1" />
  <archM id="FSArch.StatErrors" run="1" />
  <archM id="FSArch.test" run="1" />
</st>

The message archive

Obtaining the information of the message archiving
REQ: <info path="/Archive/%2fserv%2fmess" arch="{archiver}" />
  • archiver — whole identifier of the message archiver of requesting this information or empty for whole message archive.
RESP: <info path="/Archive/%2fserv%2fmess" arch="{archiver}" rez="0" end="{end}" beg="{begin}" />
  • end — time of the last message in the archive, as the UNIX time stamp from 01.01.1970;
  • begin — time of the first message in the archive, as the UNIX time stamp from 01.01.1970.
<info beg="1639859386" end="1674549889" path="/Archive/%2fserv%2fmess" rez="0" user="roman" />
Requesting the messages of the message archive
Very generic request of the archive messages.
REQ: <get path="/Archive/%2fserv%2fmess" tm="{time}" tm_grnd="{tmGrnd}" arch="{archiver}" cat="{catTmpl}" lev="level" />
  • time — time of the last requested message, as the UNIX time stamp from 01.01.1970; at the zero value there used the current system time - 1;
  • tmGrnd — time of the first requested message, as the UNIX time stamp from 01.01.1970;
  • archiver — whole identifier of the message archiver of requesting or empty for whole message archive;
  • catTmpl — template of the requesting messages;
  • level — minimum level of the requesting messages.
RESP: <get path="/Archive/%2fserv%2fmess" tm="{time}" tm_grnd="{tmGrnd}" arch="{archiver}" cat="{catTmpl}" lev="level" rez="0" >{messages}</get>
  • time — there placed the last processed message time (biggest one), as the UNIX time stamp from 01.01.1970;
  • messages — requested messages in the tags "el": <el time="{time}" utime="{utime}" cat="{category}" lev="{level}">{mess}</el>
    • time — the message time, as the UNIX time stamp from 01.01.1970;
    • utime — the microsecond part of the message time;
    • cat — the message category;
    • lev — the message level;
    • mess — the message text.
<get cat="/*" lev="1" path="/Archive/%2fserv%2fmess" rez="0" tm="0" tm_grnd="1674549800" user="roman">
  <el cat="/sub_UI/mod_QTCfg/" lev="1" time="1674549865" utime="856668">
roman| '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fio%2fin' changed to: '&lt;info path="/Archive" /&gt;'!
  </el>
  <el cat="/sub_UI/mod_QTCfg/" lev="1" time="1674549867" utime="640815">
roman| Pressed down '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fcalc'!
  </el>
  <el cat="/sub_UI/mod_QTCfg/" lev="1" time="1674549888" utime="266062">
roman| '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fio%2fin' changed to: '&lt;info path="/Archive/%2fserv%2fmess" /&gt;'!
  </el>
  <el cat="/sub_UI/mod_QTCfg/" lev="1" time="1674549889" utime="843894">
roman| Pressed down '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fcalc'!
  </el>
</get>
Setting the group messages to the message archive
REQ[root-Archive]: <set path="/Archive/%2fserv%2fmess">{messages}</set>
  • messages — messages in the tags "el": <el time="{time}" utime="{utime}" cat="{category}" lev="{level}">{mess}</el>
    • time — the message time, as the UNIX time stamp from 01.01.1970;
    • utime — the microsecond part of the message time;
    • cat — the message category;
    • lev — the message level;
    • mess — the message text.
<set path="/Archive/%2fserv%2fmess">
  <el cat="/sub_UI/mod_QTCfg/" lev="1" time="1674549865" utime="856668">
roman| '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fio%2fin' changed to: '&lt;info path="/Archive" /&gt;'!
  </el>
  <el cat="/sub_UI/mod_QTCfg/" lev="1" time="1674549867" utime="640815">
roman| Pressed down '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fcalc'!
  </el>
</set>

The message archivers

Requesting the messages of the message archiver
REQ: <get path="/Archive/{MOD}/mess_{ARCHR}/%2fserv%2fmess" eTm="{endTime}" bTm="{begTime}" cat="{catTmpl}" lev="level" />
  • MOD, ARCHR — the message archiving module and identifier of the archiver;
  • endTime — time of the last requested message, as the UNIX time stamp from 01.01.1970; at the zero value there used the current system time;
  • begTime — time of the first requested message, as the UNIX time stamp from 01.01.1970;
  • catTmpl — template of the requesting messages;
  • level — minimum level of the requesting messages.
RESP: <get path="/Archive/{MOD}/{ARCHR}/%2fserv%2fmess" eTm="{endTime}" bTm="{begTime}" cat="{catTmpl}" lev="level" rez="0" tm="{time}" >{messages}</get>
  • time — there placed the last processed message time (biggest one), as the UNIX time stamp from 01.01.1970;
  • messages — the requested messages in the tags "it": <it tm="{time}" tmu="{utime}" cat="{category}" lev="{level}">{mess}</it>
    • time — the message time, as the UNIX time stamp from 01.01.1970;
    • utime — the microsecond part of the message time;
    • cat — the message category;
    • lev — the message level;
    • mess — the message text.
<get bTm="1674549800" cat="/*" eTm="1674549889" lev="1" path="/Archive/FSArch/mess_SYS/%2fserv%2fmess" rez="0" tm="1674549889" user="roman">
  <it cat="/sub_UI/mod_QTCfg/" lev="1" tm="1674549865" tmu="856668">
roman| '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fio%2fin' changed to: '&lt;info path="/Archive" /&gt;'!
  </it>
  <it cat="/sub_UI/mod_QTCfg/" lev="1" tm="1674549867" tmu="640815">
roman| Pressed down '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fcalc'!
  </it>
  <it cat="/sub_UI/mod_QTCfg/" lev="1" tm="1674549888" tmu="266062">
roman| '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fio%2fin' changed to: '&lt;info path="/Archive/%2fserv%2fmess" /&gt;'!
  </it>
  <it cat="/sub_UI/mod_QTCfg/" lev="1" tm="1674549889" tmu="843894">
roman| Pressed down '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fcalc'!
  </it>
</get>
Setting the group messages to the message archiver
REQ[root-Archive]: <put path="/Archive/{MOD}/mess_{ARCHR}/%2fserv%2fmess" redundancy="{redundancy}">{messages}</put>
  • MOD, ARCHR — the message archiving module and identifier of the archiver;
  • redundancy — sign of sending the messages to the redundant stations [0|1];
  • messages — the setting messages in the tags "it": <it tm="{time}" tmu="{utime}" cat="{category}" lev="{level}">{mess}</it>
    • time — the message time, as the UNIX time stamp from 01.01.1970;
    • utime — the microsecond part of the message time;
    • cat — the message category;
    • lev — the message level;
    • mess — the message text.
<put path="/Archive/FSArch/mess_SYS/%2fserv%2fmess">
  <it cat="/sub_UI/mod_QTCfg/" lev="1" tm="1674549865" tmu="856668">
roman| '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fio%2fin' changed to: '&lt;info path="/Archive" /&gt;'!
  </it>
  <it cat="/sub_UI/mod_QTCfg/" lev="1" tm="1674549867" tmu="640815">
roman| Pressed down '/SimulatorStation/sub_DAQ/mod_JavaLikeCalc/lib_Controller/fnc_test1/%2fexec%2fcalc'!
  </it>
</put>

The value archives

Obtaining the information of the value archive
REQ: <info path="/Archive/va_{ARCH}/%2fserv%2fval" arch="{archiver}" />
  • ARCH — identifier of the value archive;
  • archiver — whole identifier of the value archiver or empty for the value buffer.
RESP: <info path="/Archive/va_{ARCH}/%2fserv%2fval" arch="{archiver}" rez="0" end="{end}" beg="{begin}" per="{period}" vtp="{valTp}" />
  • end — time of the last value in the archive in microseconds and the seconds part as the UNIX time stamp from 01.01.1970;
  • begin — time of the first value in the archive in microseconds and the seconds part as the UNIX time stamp from 01.01.1970;
  • period — the archiver periodicity or the value buffer at the archiver missing, in microseconds;
  • valTp — value type, see to the object #TFld.
<info arch="FSArch.1s" beg="1665239503000000" end="1674581638000000" path="/Archive/va_F3_var/%2fserv%2fval" per="1000000" rez="0" user="roman" vtp="4" />
Requesting the values of the value archive
Very generic request of values of the value archives.
REQ: <get path="/Archive/va_{ARCH}/%2fserv%2fval" tm="{time}" tm_grnd="{tmGrnd}" arch="{archiver}" local="{localReq}" per="{period}" mode="{mode}" round_perc="{rndPerc}" real_prec="{realPrec}" />
  • ARCH — identifier of the value archive;
  • time — time of the last requesting value in microseconds and the seconds part as the UNIX time stamp from 01.01.1970; for zero value there used the system current time;
  • tmGrnd — time of the first requesting value in microseconds and the seconds part as the UNIX time stamp from 01.01.1970; for zero value there performed only current value request;
  • archiver — whole identifier of the value archiver or empty for the priority request at the selection priority and from the best to the worst;
  • localReq — sign [0|1] of the local requesting without requesting the redundant station for the missing data;
  • period — period in which the values request, in microseconds; there used the maximum period from the archive period;
  • mode — mode of the archive values representing, see to the enumeration ServReqDtMode of the #TVArchive object;
  • DMSimple(0) — simple record, one item per line; in the case of the string archive type the values are encoded to exclude the newlines characters;
34.5678
23.6543
65.8754
34.6523
  • DMPack(1) — packed record, one adjacent equal (rounded) value per line; before each value there is indicated its position number separated by the space from the value;
0 34.5678
1 23.6543
4 65.8754
6 34.6523
  • DMBin(2) — array of unpacked binary values, encoded by Base64; cannot to be used for string archives.
  • rndPerc — percent of the real values rounding, that is meant as equal ones;
  • realPrec — precision of the real values at conversion in string, 15 by default.
RESP: <get path="/Archive/va_{ARCH}/%2fserv%2fval" tm="{time}" tm_grnd="{tmGrnd}" arch="{archiver}" local="{localReq}" per="{period}" mode="{mode}" round_perc="{rndPerc}" real_prec="{realPrec}" rez="0" vtp="{valType}">{values}</get>
  • archiver — is set to the selected archiver at empty here in the request;
  • time — is set to the requested value real time at the single value requesting or to time of the last-end value at the value block;
  • tmGrnd — is set to the first-ground value of the value block;
  • period — is set to the real data period in the value block;
  • valType — is set to the data type in the value block;
  • values — one value for the single value requesting or the value block formatted corresponding to the "mode".
<get arch="FSArch.1s" mode="1" path="/Archive/va_F3_var/%2fserv%2fval" per="10000000" real_prec="7" rez="0" round_perc="0.1"
     tm="1674581630000000" tm_grnd="1674581500000000" user="roman" vtp="4">
0 &lt;EVAL&gt;
7 45.23046
11 45.16198
13 45.08281
</get>
Requesting the name of the archive depending on presence the DAQ attribute link
REQ: <name path="/Archive/va_{ARCH}/%2fserv%2fval" />
  • ARCH — the value archive identifier.
RESP: <name path="/Archive/va_{ARCH}/%2fserv%2fval" rez="0">{name}</name>
  • name — name of the requested archive.
<name path="/Archive/va_F3_var/%2fserv%2fval" rez="0" user="roman">F3.var</name>

14.4.5 The subsystem "User Interfaces (UI)"

14.4.5.1 The module VCAEngine

Service functions are an interface for accessing OpenSCADA from external systems through the Control Interface. This mechanism is the basis of all exchange within OpenSCADA, implemented through weak links and OpenSCADA's own exchange protocol.

The common widgets

Getting for values of specified or all visual attributes of the widget
REQ: <get path="/UI/VCAEngine/{wAddr}/%2fserv%2fattr">{attributes}</get>
  • wAddr — the widget local address, like to "/wlb_AGLKS/wdg_CM101/wdg_ElFigure1";
  • attributes — the only requested attributes in the tags "el" with only one attribute of the identifier "id"; there can be no the attribute tags for requesting all available ones.
RESP: <get path="/UI/VCAEngine/{wAddr}/%2fserv%2fattr" rez="0">{attributes}</get>
  • attributes — processed attributes in the tags "el": <el id="{ID}" p="{pos}" act="{active}">{value}</el>
    • ID — identifier of the attribute;
    • pos — position-index of the attribute for the standard ones;
    • active — activity state of the attribute, only at the direct requesting;
    • value — value of the attribute.
<get path="/UI/VCAEngine/wlb_AGLKS/wdg_CM101/wdg_ElFigure1/%2fserv%2fattr" rez="0" user="roman">
  <el id="id">ElFigure1</el>
  <el id="path">/wlb_AGLKS/wdg_CM101/wdg_ElFigure1</el>
  <el id="parent">/wlb_originals/wdg_ElFigure</el>
  <el id="owner">root:UI</el>
  <el id="perm">948</el>
  <el id="root" p="1">ElFigure</el>
  <el id="name" />
  <el id="dscr" />
</get>
Setting for group values of the specified widget attributes
REQ[root-UI]: <set path="/UI/VCAEngine/{wAddr}/%2fserv%2fattr">{attributes}</set>
  • wAddr — the widget local address in the module, like to "/wlb_AGLKS/wdg_CM101/wdg_ElFigure1";
  • attributes — attributes with values in the tags "el": <el id="{ID}">{value}</el>
    • ID — identifier of the attribute;
    • value — setting value of the attribute.
<set path="/UI/VCAEngine/wlb_AGLKS/wdg_CM101/wdg_ElFigure1/%2fserv%2fattr">
  <el id="name">New name</el>
  <el id="dscr">New description</el>
</set>
Getting for values of the visual attributes of the widget branch, optimised for the networks
REQ: <get path="/UI/VCAEngine/{wAddr}/%2fserv%2fattrBr" />
  • wAddr — the widget local address in the module, like to "/wlb_AGLKS/wdg_CM101/wdg_ElFigure1".
RESP: <get path="/UI/VCAEngine/{wAddr}/%2fserv%2fattrBr" rez="0">{attributes} {widgets}</get>
  • attributes — processed attributes in the tags "el": <el id="{ID}" p="{pos}">{value}</el>
    • ID — identifier of the attribute;
    • pos — position-index of the attribute for the standard ones;
    • value — value of the attribute.
  • widgets — child widgets in the tags "w": <w id="{ID}" lnkPath="{lnkPath}">{attributes} {widgets}</w>
    • ID — identifier of the widget;
    • lnkPath — path to the linked widget for child widgets of the widget libraries.
<get path="/UI/VCAEngine/wlb_AGLKS/wdg_CM101/%2fserv%2fattrBr" rez="0" user="roman">
  <el id="id">CM101</el>
  <el id="path">/wlb_AGLKS/wdg_CM101</el>
  <el id="parent">/wlb_originals/wdg_Box</el>
  <el id="owner">root:UI</el>
  <el id="perm">948</el>
  <el id="root" p="1">Box</el>
  <el id="name">CM101</el>
  <w id="AT101_1" lnkPath="/wlb_mnEls/wdg_cooler">
    <el id="id">AT101_1</el>
    <el id="path">/wlb_AGLKS/wdg_CM101/wdg_AT101_1</el>
    <el id="parent">/wlb_mnEls/wdg_cooler</el>
    <el id="owner">root:UI</el>
    <el id="perm">948</el>
    <el id="root" p="1">ElFigure</el>
    <el id="name">АТ101 1</el>
  </w>
</get>

The widget libraries

Obtaining the widget libraries' tree, optimised for the networks
REQ: <get path="/UI/VCAEngine/%2fserv%2fwlbBr" item="{item}" disIconsW="{disIconsW}" disIconsCW="{disIconsCW}" />
  • item — the library item for obtaining, as the path "wlb_{WLib}[/wdg_{Wdg}[/wdg_{ChildWdg}]]", for empty there will be obtained all the tree;
  • disIconsW — disable for obtaining the icon data of the widgets [0|1];
  • disIconsCW — disable for obtaining the icon data of the child widgets [0|1].
RESP: <get path="/UI/VCAEngine/%2fserv%2fwlbBr" item="{item}" disIconsW="{disIconsW}" disIconsCW="{disIconsCW}" rez="0">{wlibs}</get>
  • wlibs — the widget libraries in the "wlb" tags: <wlb id="{ID}" doc="{doc}">{name} {icon} {widgets}</wlb>
    • icon — the "icon" tag with the Base64 encoded data of the icon;
    • widgets — the "w" tags with the library widgets description: <w id="{ID}" doc="{doc}" parent="{parent}">{name} {icon} {widgets}</w>
      • parent — address of the widget parent;
      • widgets — the "сw" tags with the child widgets description: <cw id="{ID}" doc="{doc}">{name} {icon}</cw>
<get disIconsCW="1" disIconsW="1" item="/wlb_AGLKS" path="/UI/VCAEngine/%2fserv%2fwlbBr" rez="0" user="roman">
  <wlb id="AGLKS">AGLKS
    <ico>iVBORw0KGgoAA...U5ErkJggg==</ico>
    <w id="CM101" parent="/wlb_originals/wdg_Box">CM101
      <cw id="AT101_1">АТ101 1</cw>
      <cw id="AT101_2">АТ101 1</cw>
      <cw id="C101_1">C101/1</cw>
      <cw id="C101_2">C101/1</cw>
      <cw id="C101_3">C101/1</cw>
      <cw id="CM101">CM101</cw>
      <cw id="CM101_1">CM101_1</cw>
      <cw id="CM101_2">CM101_2</cw>
      <cw id="ElFigure1">ElFigure1</cw>
      <cw id="ElFigure2">ElFigure2</cw>
      <cw id="ElFigure3">ElFigure3</cw>
      <cw id="ElFigure4">ElFigure4</cw>
      <cw id="ElFigure5">ElFigure5</cw>
      <cw id="ElFigure6">ElFigure6</cw>
      <cw id="ElFigure7">ElFigure7</cw>
    </w>
    <w id="KCH_MN1" parent="/wlb_originals/wdg_Box">KCH_MN1
      <cw id="BC1">Ball crane</cw>
      <cw id="BC2">Ball crane</cw>
      <cw id="BC21">Ball crane</cw>
      <cw id="BC22">Ball crane</cw>
    </w>
    <w id="comprEn" parent="/wlb_originals/wdg_ElFigure">Compressor run</w>
  </wlb>
</get>

The VCA projects

Obtaining the project list expanded by some options
REQ: <get path="/UI/VCAEngine/[%2fbr%2fprj_|%2fprm%2fcfg%2fprj]" chkUserPerm="{chkUserPerm}" getChPgN="{getChPgN}" noName="{noName}" />
  • chkUserPerm — checking for the user permition before listing [0|1];
  • getChPgN — requesting for quantity of the child pages in the projects [0|1];
  • noName — do not return for names of the pages [0|1].
RESP: <get path="/UI/VCAEngine/[%2fbr%2fprj_|%2fprm%2fcfg%2fprj]" chkUserPerm="{chkUserPerm}" getChPgN="{getChPgN}" noName="{noName}" rez="0">{projects}</get>
  • projects — projects list in the tags "el", where the name is in the tag text and the identifier in the attribute "id". Expanded by the extra attributes:
    • "chPgN" — quantity of the child pages in the project at setting "getChPgN".
<get getChPgN="1" path="/UI/VCAEngine/%2fbr%2fprj_" rez="0" user="roman">
  <el chPgN="2" id="AGLKS">AGLKS</el>
  <el chPgN="2" id="archBrowser">Archives browser</el>
  <el chPgN="2" id="tmplSO">Signal groups (template)</el>
</get>
Checking for read access to the project from the user of the request
REQ: <read path="/UI/VCAEngine/prj_{proj}/%2fserv%2faccess" />
  • proj — identifier of the project.
RESP: <read path="/UI/VCAEngine/prj_{proj}/%2fserv%2faccess" rez="0">{access}</get>
  • access — the access presence status [0|1].

</translate>

<read path="/UI/VCAEngine/prj_AGLKS/%2fserv%2faccess" rez="0" user="roman">1</read>

<translate> The project sessions

Obtaining the session list expanded by some options
REQ: <get path="/UI/VCAEngine/[%2fbr%2fses_|%2fses%2fses]" chkUserPerm="{chkUserPerm}" onlyMy="{onlyMy}" />
  • chkUserPerm — checking for the user permition before listing [0|1];
  • onlyMy — listening only my own sessions [0|1].
RESP: <get path="/UI/VCAEngine/[%2fbr%2fses_|%2fses%2fses]" chkUserPerm="{chkUserPerm}" onlyMy="{onlyMy}" rez="0">{sessions}</get>
  • sessions — sessions list in the tags "el", where the identifier is in the tag text. Expanded by the extra attributes:
    • "user" — user of the session;
    • "proj" — project of the session.

</translate>

<get path="/UI/VCAEngine/%2fses%2fses" rez="0" onlyMy="1" user="roman">
  <el user="roman" proj="AGLKS">AGLKS</el>
  <el user="roman" proj="AGLKS">AGLKS0</el>
</get>

<translate>

Obtaining the sessions list of the specified VCA project
REQ: <list path="/UI/VCAEngine/%2fserv%2fsess" prj="{project}" />
  • project — identifier of the requested project.
RESP: <list path="/UI/VCAEngine/%2fserv%2fsess" prj="{project}" rez="0">{sessions}</list>
  • sessions — sessions in the "el" tags.
<list path="/UI/VCAEngine/%2fserv%2fsess" prj="AGLKS" rez="0" user="roman">
  <el>AGLKS</el>
</list>
Connection to the specified VCA project or the project session
REQ: <connect path="/UI/VCAEngine/%2fserv%2fsess" prj="{project}" sess="{session}" userChange="{userChange}" onlyMy="{onlyMy}" />
  • project — identifier of the requested project, empty for connection to the available session;
  • session — identifier of the already present session, empty at a new session creation;
  • onlyMy — sign of connection-reconnection to the session only when it is my;
  • userChange — sign of the user changing [0|1] of the session, that is updation the user information.
RESP: <connect path="/UI/VCAEngine/%2fserv%2fsess" prj="{project}" sess="{session}" userChange="{userChange}" onlyMy="{onlyMy}" rez="0" conId="{conId}" userIsRoot="{userIsRoot}" />
  • conId — the session connection identifier, used in next requests;
  • project — the project identifier of the successfully connected session;
  • session — identifier of the new created session of the successfully connected project;
  • userIsRoot — the user has the root permition [0|1].

</translate>

<connect conId="50860885" path="/UI/VCAEngine/%2fserv%2fsess" prj="AGLKS" rez="0" sess="AGLKS" user="roman" userIsRoot="1" />

<translate>

Disconnection the specified VCA project session
Sessions with zero connections are closed here also.
REQ: <disconnect path="/UI/VCAEngine/%2fserv%2fsess" sess="{session}" conId="{conId}" />
  • session — identifier of the present session;
  • conId — the session connection identifier.
<disconnect path="/UI/VCAEngine/%2fserv%2fsess" sess="AGLKS" conId="50860885" />
Getting for the opened pages list of the project session
REQ[{owner}-{grp}]: <openlist path="/UI/VCAEngine/ses_{session}/%2fserv%2fpg" conId="{conId}" tm="{clock}" />
  • owner, grp — reading access for the project owner or a user in group and regarding to the project permissions;
  • session — identifier of the session;
  • conId — the session connection identifier;
  • clock — the internal clock (the live cycle) value from the previous processed request, for checking of the changed ones.
RESP: <openlist path="/UI/VCAEngine/ses_{session}/%2fserv%2fpg" conId="{conId}" tm="{clock}" rez="0">{pages}</openlist>
  • clock — the internal clock (the live cycle) value - 1 at the request time;
  • pages — pages in the tags "pg": <pg pgGrp="{pgGrp}" updWdg="{nUpdWdgs}">{ID}</pg>
    • ID — identifier of the page;
    • pgGrp — the pages group for early calculation the page including;
    • nUpdWdgs — quantity of the updated widgets after the last request and for not empty "clock".

</translate>

<openlist conId="52760577" path="/UI/VCAEngine/ses_AGLKS/%2fserv%2fpg" rez="0" tm="1403" user="roman">
  <pg>/ses_AGLKS/pg_so</pg>
  <pg pgGrp="so">/ses_AGLKS/pg_so/pg_1/pg_mn/pg_1</pg>
  <pg pgGrp="cntr">/ses_AGLKS/pg_control/pg_ElCadr</pg>
</openlist>

<translate>

Opening or closing for the specified page of the project session
REQ[{owner}-{grp}]: <[open|close] path="/UI/VCAEngine/ses_{session}/%2fserv%2fpg" pg="{page}" />
  • owner, grp — writing access for the project owner or a user in group and regarding to the project permissions;
  • session — identifier of the session;
  • page — address of the page in the session context, like to "/ses_AGLKS/pg_so/pg_1/pg_mn/pg_1".
Getting for the alarm status and the notification resource of the project session
REQ[{owner}-{grp}]: <get path="/UI/VCAEngine/ses_{session}/%2fserv%2falarm" mode="{mode}" tp="{typeNtf}" wdg="{widget}" />
  • owner, grp — reading access for the project owner or a user in group and regarding to the project permissions;
  • session — identifier of the session;
  • mode — the requesting mode, only "resource" for obtaining the notification resources and empty for the status only;
  • typeNtf — the notification type of obtaining the notification resource, see the alarming section;
  • widget — address of the widget for forming the notification resource, empty for global.
RESP: <get path="/UI/VCAEngine/ses_{session}/%2fserv%2falarm" mode="{mode}" tp="{typeNtf}" rez="0" alarmSt="{alarmSt}" tm="{clock}" wdg="{widget}" resTp="{resTp}" mess="{message}" lang="{language}">{resource}</get>
  • alarmSt — the alarm status as that described in the alarming section;
  • clock — the internal clock (the live cycle) value at the notification resource form;
  • widget — address of the source widget at the notification resource form;
  • message — message of notification from the text;
  • language — language of the notification, for the "message" mostly;
  • resTp — type of the notification resource;
  • resource — resource of the notification encoded by Base64 for the binary data.
<get path="/UI/VCAEngine/ses_AGLKS/%2fserv%2falarm" mode="resource" tp="1" rez="0" user="roman"
     alarmSt="460554" tm="0" resTp="audio/ogg;73.3428" lang="en_US.UTF-8">
T2dnUwACA...Dg6gwAjo+PAQ==
</get>
Quietance of the alarm notification of the project session
REQ[{owner}-{grp}]: <quietance path="/UI/VCAEngine/ses_{session}/%2fserv%2falarm" wdg="{widget}" tmpl="{template}" ret="{return}" />
  • owner, grp — reading access for the project owner or a user in group and regarding to the project permissions;
  • session — identifier of the session;
  • widget — address of the widget for quietance the notification, empty for global;
  • template — template of the quietance, that is bitset corresponding to the quieting notification types;
  • return — sign of the notification return, that is the quietance disabling.
<quietance path="/UI/VCAEngine/ses_AGLKS/%2fserv%2falarm" tmpl="7" />
Getting for values of the modified visual attributes of the session widget
Redefines the common service request of the widgets "<get path='/UI/VCAEngine/{wAddr}/%2fserv%2fattr' />" for the session specific.
REQ: <get path="/UI/VCAEngine/ses_{wAddr}/%2fserv%2fattr" tm="{clock}" />
  • wAddr — the session widget local address, like to "/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/wdg_ElFigure1";
  • clock — the internal clock (the live cycle) value from the previous processed request, for checking of the changed ones; at zero value there force appended the service-virtual attributes: "perm", "name".
RESP: <get path="/UI/VCAEngine/ses_{wAddr}/%2fserv%2fattr" tm="{clock}" rez="0">{attributes}</get>
  • attributes — modified from "clock" attributes in the tags "el": <el id="{ID}" p="{pos}">{value}</el>
    • ID — identifier of the attribute;
    • pos — position-index of the attribute for the standard ones;
    • value — value of the attribute.
<get path="/UI/VCAEngine/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/wdg_ElFigure1/%2fserv%2fattr" rez="0" tm="0" user="roman">
  <el id="perm" p="-3">6</el>
  <el id="root" p="1">ElFigure</el>
  <el id="en" p="5">1</el>
  <el id="active" p="6">0</el>
  <el id="geomX" p="7">488</el>
  <el id="geomY" p="8">250</el>
  <el id="geomW" p="9">16</el>
  <el id="geomH" p="10">100</el>
  <el id="geomXsc" p="13">1</el>
  <el id="geomYsc" p="14">0.75</el>
  <el id="geomZ" p="11">-9</el>
</get>
Setting for group values of the specified attributes of the session widget
Redefines the common service request of the widgets "<set path='/UI/VCAEngine/{wAddr}/%2fserv%2fattr' />" for the session specific like to the "event" attribute processing and detection the user activity-inactivity.
REQ[{owner}-{grp}]: <set path="/UI/VCAEngine/ses_{wAddr}/%2fserv%2fattr" noUser="{noUser}">{attributes}</set>
  • owner, grp — writing access for the project owner or a user in group and regarding to the project permissions;
  • wAddr — the session widget local address, like to "/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/wdg_ElFigure1";
  • noUser — don't mark that as a user activity;
  • attributes — attributes with values in the tags "el": <el id="{ID}">{value}</el>
    • ID — identifier of the attribute;
    • value — setting value of the attribute.
<set path="/UI/VCAEngine/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/wdg_ElFigure1/%2fserv%2fattr">
  <el id="name">New name</el>
  <el id="dscr">New description</el>
</set>
Activating the attribute for using as the visual one and creating that at missing
REQ: <activate path="/UI/VCAEngine/ses_{wAddr}/%2fserv%2fattr%2f{aID}" aNm="{aName}" aTp="{aType}" aFlg="{aFlags}" aVls="{aValues}" aNms="{aNames}">{aDef}</activate>
  • wAddr — the session widget local address, like to "/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/wdg_ElFigure1";
  • aID — identifier of the attribute;
  • aName — name of the attribute at it creation;
  • aType — type of the attribute at it creation, see to the object TFld;
  • aFlags — flags of the attribute at it creation, see to the object TFld;
  • aDef — default value of the attribute at it creation;
  • aValues — the attribute values for the selective types at it creation;
  • aNames — names to values of the attribute for the selective types at it creation.
<activate path="/UI/VCAEngine/ses_AGLKS/pg_so/%2fserv%2fattr%2frunWin" aNm="Run window" aTp="1" aFlg="1" aVls="0;1;2" aNms="Original size;Maximize;Full screen">0</activate>
Getting for values of the visual attributes of the widget branch of the session, optimised for the networks
Redefines the common service request of the widgets "<get path='/UI/VCAEngine/{wAddr}/%2fserv%2fattrBr' />" for the session specific.
REQ: <get path="/UI/VCAEngine/ses_{wAddr}/%2fserv%2fattrBr" tm="{clock}" FullTree="{FullTree}" />
  • wAddr — the session widget local address, like to "/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/wdg_ElFigure1";
  • clock — the internal clock (the live cycle) value from the previous processed request, for checking of the changed ones; at zero value there force appended the service-virtual attributes: "perm", "name";
  • fullTree — obtaining the full widgets tree independent from presence the changes, without the attributes.
RESP: <get path="/UI/VCAEngine/ses_{wAddr}/%2fserv%2fattrBr" tm="{clock}" FullTree="{FullTree}" rez="0">{attributes} {widgets}</get>
  • attributes — processed attributes in the tags "el": <el id="{ID}" p="{pos}">{value}</el>
    • ID — identifier of the attribute;
    • pos — position-index of the attribute for the standard ones;
    • value — value of the attribute.
  • widgets — child widgets in the tags "w": <w id="{ID}">{attributes} {widgets}</w>
    • ID — identifier of the widget.
<get path="/UI/VCAEngine/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/%2fserv%2fattrBr" rez="0" tm="0" user="roman">
  <el id="name" p="-4">CM101</el>
  <el id="perm" p="-3">6</el>
  <el id="root" p="1">Box</el>
  <el id="en" p="5">1</el>
  <el id="active" p="6">0</el>
  <el id="geomX" p="7">0</el>
  <el id="geomY" p="8">0</el>
  <el id="geomW" p="9">900</el>
  <el id="geomH" p="10">580</el>
  <w id="AT101_1">
    <el id="perm" p="-3">6</el>
    <el id="root" p="1">ElFigure</el>
    <el id="en" p="5">1</el>
    <el id="active" p="6">0</el>
    <el id="geomX" p="7">338</el>
    <el id="geomY" p="8">320</el>
    <el id="geomW" p="9">80</el>
    <el id="geomH" p="10">100</el>
  </w>
</get>
Getting for value of the session specific attribute of the session widget
REQ: <get path="/UI/VCAEngine/ses_{wAddr}/%2fserv%2fattrSess%2f{aID}" />
  • wAddr — the session widget local address, like to "/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/wdg_ElFigure1";
  • aID — identifier of the session specific attribute.
RESP: <get path="/UI/VCAEngine/ses_{wAddr}/%2fserv%2fattrSess%2f{aID}" rez="0">{value}</get>
  • value — value of the attribute.
<get path="/UI/VCAEngine/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/%2fserv%2fattrSess%2ftestA" rez="0" user="roman">test val</get>
Setting for value of the session specific attribute of the session widget
REQ[{owner}-{grp}]: <set path="/UI/VCAEngine/ses_{wAddr}/%2fserv%2fattrSess%2f{aID}">{value}</get>
  • owner, grp — writing access for the project owner or a user in group and regarding to the project permissions;
  • wAddr — the session widget local address, like to "/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/wdg_ElFigure1";
  • aID — identifier of the session specific attribute;
  • value — value of the attribute.
<set path="/UI/VCAEngine/ses_AGLKS/pg_so/pg_2/pg_mn/pg_CM101/%2fserv%2fattrSess%2ftestA">test val</set>


14.5 Object of the dynamic tree node (TCntrNode)

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

Data:

Masks of the security access (definition):
Named rights of access to control elements (definition):

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

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

Enable flags
Disable flags

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 = RWRWRW, 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 = RWRWRW, 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 Resources locking

Most of the units and subsystems of 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.

15.1 Resource R/W lock object (ResRW)

Public methods:

15.2 Automatic resource RW unlock object (ResAlloc)

Public methods:

15.3 Template (AutoHD)

Public methods:

15.4 Resources allocation object, by mutex (ResMtx)

Public methods:

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

Public methods:

15.6 Conditional variable object, by mutex (CondVar)

Public methods:

15.7 Object of automatic unlock POSIX mutex (MtxAlloc)

Public methods:

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

Public methods:

16 Other generic objects

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

Errors of the exceptions are handled by the error object "TError".

16.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.2 Error exception (TError)

Data:
Error codes (enum — TError::Codes):

Public methods:

Public attributes:

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 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/MessLev 0
user /DemoStation/Workdir /mnt/home/roman/work/OScadaD/share/OpenScada
user /DemoStation/UI/QTStarter/StartMod QTCfg

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>
LibBD MySQL Function's library server.diya.org;roman;123456;oscadaUserLibs KOI8-U 1
AnastModel SQLite AGLKS model ./DATA/AGLKSModel.db UTF8 1
GenDB MySQL Main DB server.diya.org;roman;123456;oscadaDemoSt KOI8-U 1

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
AutoDA Automatic source Data acquisition from active sources with automatic identification of them. 1 1 ...

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
P3 P3 Pressure on the diaphragm 1 ...

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>
base Basic templates Basic templates' library tmplib_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>
digAlarm Digital signal Alarm over the discrete parameter JavaLikeCalc.JavaScript
simpleBoard Simple boards Formation 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>
digAlarm in Вход 3 144 2
digitBlock cmdOpen Open command 3 161 0

17.3 Tables of the "Transports" subsystem

Subsystem "Transports" is divided into input and output 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 input 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
web1 Sockets Web 1 Work web transport for proced http requests. TCP::10002:0 HTTP 1 ...
Self SelfSystem TCP 1 Test TCP input socket! Sockets TCP::10001:1 1 ...

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

ID <ID> Type <MODULE> Name <NAME> Description <DESCRIPT> Address <ADDR> Individual fields of the transports' types
tcp_o1 Sockets TCP Out 1 Output TCP transport 1 TCP::10001 ...

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_o1 Sockets TCP Out 1 Output TCP transport 1 TCP::10001 1 ...

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 1 1 DAQ.System.AutoDA.CPULoad.load 4 1 100 0 0 FSArch.1s;DBArch.1m;FSArch.1m;
ai1_dP 0 0 4 0.0001 100 1 1 FSArch.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
1s FSArch One second 1 ARCHIVES/VAL/1s 1 60 ...
POMP_20070301 FSArch 0 ARCHIVES/VAL/POMP_20070301 0.0001 60 ...

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
StatErrors FSArh Station error 1 /DemoStation* 4 ARCHIVES/MESS/stError/ ...
NetRequsts FSArh Network requests 1 /DemoStation/Transport/Sockets* 1 ARCHIVES/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>
root SuperUser openscada
user User user

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

Name <NAME> Description <DESCR> Users in the group <USERS>
root SuperUser's group root;user
users User's group toot;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 API of the module

Modules in OpenSCADA are implemented as shared libraries and one such library can contain many modules of the OpenSCADA subsystems, actually acting as a container. Those containers also can be included-builtin in the OpenSCADA Core Library if you build very tightly solutions.

The first step in connecting the shared libraries (SO — Shared Object) is the connection of the initialization functions. These functions should be defined as usual "C" functions to avoid distortion of them names. Usually this is done as follows:

//================== CUT =========================
extern "C"
{
#ifdef MOD_INCL
    TModule::SAt bd_Tmpl_module( int n_mod )
#else
    TModule::SAt module( int n_mod )
#endif
    {
        if(n_mod == 0) return TModule::SAt(MOD_ID, MOD_TYPE, VER_TYPE);
        return TModule::SAt("");
    }

<!--T:348-->
#ifdef MOD_INCL
    TModule *bd_Tmpl_attach( const TModule::SAt &AtMod, const string &source )
#else
    TModule *attach( const TModule::SAt &AtMod, const string &source )
#endif
    {
        if(AtMod == TModule::SAt(MOD_ID,MOD_TYPE,VER_TYPE)) return new BDTmpl::BDMod(source);
        return NULL;
    }
}
//================== CUT =========================

The entry point of any module are the following functions:

Common to all modules is the inheritance of the root object-class of the module from the class of the module subsystem TModule, which indicates the presence of a common part of the module interface, which we will consider further. To get a vision of the architecture of the modules in the context of the overall OpenSCADA architecture, it is strongly recommended to have the overall OpenSCADA class diagram in front of your eyes!

All module interface objects inherit the node class TCntrNode, which provides the control interface mechanism. One task of the mechanism is to provide the object configuration interface in any OpenSCADA configurator.

Common API
TCntrNode — OpenSCADA Node:
  • virtual void preEnable( int flag );, virtual void postEnable( int flag ); — connecting the module to the dynamic tree of objects, called before and after the actual activation of the module, respectively.
  • virtual void preDisable( int flag );, virtual void postDisable( int flag ); — excluding the module from the dynamic tree of objects before freeing the object, called before and after the actual exclusion of the module, respectively.
  • virtual void load_( TConfig *cfg );, virtual void load_( ); — loading the module from the "cfg" storage context and in general, called at the stage of loading the module configuration from the storage.
  • virtual void save_( ); — saving the module, called at the stage of saving the configuration of the module to the storage, usually at the initiative of the user.
TModule — OpenSCADA Module:
  • virtual void modStart( ); — module starting, called at the stage of starting tasks of the module's background functions, if these are provided by the module.
  • virtual void modStop( ); — stopping the module, called at the stage of stopping the tasks of performing the background functions of the module, if these are provided by the module.
  • virtual void modInfo( vector<string> &list ); — a request for a list of information properties of the module, which is provided with a standard set of properties "Module", "Name", "Type", "Source", "Version", "Author", "Description", "License", and which can be extended by own-specific properties.
  • virtual string modInfo( const string &name ); — a request for the information element name at which there performed also the requests processing of own-specific properties of the module.
  • void modFuncReg( ExpFunc *func ); — registration of the module's exported function, which is part of the mechanism of intermodule interaction that registers the internal function of the module for external call by the name-symbol of the function and its pointer relative to the object of the module. Currently, this mechanism is used by few modules!
  • virtual void perSYSCall( unsigned int cnt ); — a call from the system-service thread-task with the periodicity 10 seconds and a second counter "cnt", can be used to perform periodic-rare service procedures.
API of the modules of the "Data Bases (DB)" subsystem
Intended for the integration of OpenSCADA with a database or DBMS which is implemented by the module. Provides two common approaches in the modules implementation:
  1. ANSI SQL Mode — is the simplest way which means of direct using the core functions fieldSQLSeek(), fieldSQLGet(), fieldSQLSet(), fieldSQLDel() in fieldSeek(), fieldGet(), fieldSet(), fieldDel() respectively; all SQL-modules are used now this approach.
  2. Full Implementation — is the hardest way which means of the complete implementation; modules of such approach using are whether old or specific ones: DBF, LDAP.
TTypeBD->TModule — the root module object of the "DB" subsystem:
  • virtual string features( ); — keyword list of features supported by the DB.
  • virtual int lsPr( ); — the DB priority base [0...9] in the generic storages list.
  • virtual TBD *openBD( const string &id ); — called when a new DB object is opened or created by this module with the identifier id.
TBD — the database object:
  • virtual void enable( ); — enabling the DB.
  • virtual void disable( ); — disabling the DB.
  • virtual void allowList( vector<string> &list ) const; — requesting the table list in the DB.
  • virtual void sqlReq( const string &req, vector< vector<string> > *tbl = NULL, char intoTrans = EVAL_BOOL ); — processing the SQL-query req to the DB and receiving the result in the form of the tbl table, if the selection request and the pointer are non-zero. When intoTrans is set to TRUE, a transaction must be open for the request, and closed to FALSE. This function should be implemented for DBMSs that support SQL-queries.
  • virtual void transCloseCheck( ); — the periodically called function to check the transactions and closing the old or contain many requests ones.
  • virtual TTable *openTable( const string &name, bool create ); — called when you open or create a new table object.
TTable — the table object in the database:
  • void fieldStruct( TConfig &cfg ); — getting the current structure of the table in the object cfg.
  • bool fieldSeek( int row, TConfig &cfg, const string &cacheKey = "" ); — sequential scanning of table entries by incrementing row at the object cfg and returning FALSE after completion, with addressing by active keyUse() key fields. The cache key cacheKey is specified to prefetch the full response to the cache, extracting the following records from there.
  • void fieldGet( TConfig &cfg ); — request of the record specified in the "cfg" object with addressing by key fields.
  • void fieldSet( TConfig &cfg ); — transfer of the record specified in the "cfg" object with addressing by key fields.
  • void fieldDel( TConfig &cfg ); — deletion of the specified record by the key fields of the "cfg" object.
Specific for SQL Data Bases
  • void fieldFix( TConfig &cfg, const string &langLs = "" ); — correction of DB table structure to cfg and for translation languages langLs, usually after a failed transfer.
  • string getSQLVal( TCfg &cf, uint8_t RqFlg = 0 ); — return a SQL-specific wrapped cf value for the ReqFlg flags of the RqFlg call.
  • void setSQLVal( TCfg &cf, const string &vl, bool tr = false ); — parsing the SQL value vl to translate tr and with writing to cf.
API of the modules of the "Transports" subsystem
Provides OpenSCADA communications through the interface, often it is the network one which is implemented by the module.
TTypeTransport->TModule — the root module object of the "Transports" subsystem:
  • virtual bool isNetwork( ); — the sign of network implementation by this module.
  • virtual string outAddrHelp( ); — address format help of the output transports.
  • virtual TTransportIn *In( const string &id, const string &stor ); — called when a new input transport object is opened or created by this module with the identifier id and the storage stor.
  • virtual TTransportOut *Out( const string &name, const string &stor ); — called when a new output transport object is opened or created by this module with the identifier id and the storage stor.
TTransportIn — the input transport object:
  • virtual unsigned keepAliveReqs( ); — maximum Keep Alive requests.
  • virtual unsigned keepAliveTm( ); — keep Alive time.
  • virtual string getStatus( ); — getting the status of the transport.
  • virtual void start( ); — starting the transport.
  • virtual void stop( ); — stopping the transport.
  • virtual int writeTo( const string &sender, const string &data ); — sending data backward to the sender. At.png Deprecated mostly and replaced by the polling mode of the input transport protocol, Initially implemented in transports with support of the initiative sending, not only at a request.
TTransportOut — the output transport object:
  • virtual string timings( ); — transport timeouts.
  • virtual unsigned short attempts( ); — connection attempts.
  • virtual string getStatus( ); — getting the status of the transport.
  • virtual void setTimings( const string &vl, bool isDef = false ); — setting the transport timeouts, as default one for isDef.
  • virtual void setAttempts( unsigned short vl ); — setting the connection attempts.
  • virtual void start( int time = 0 ); — starting the transport with the connection timeout time. When you start the output transport the actual connection to the remote station is established for the interfaces that works by the connection. At this time the errors can occur if the connection is impossible and the transport should return to the stopped state.
  • virtual void stop( ); — stopping the transport.
  • virtual int messIO( const char *oBuf, int oLen, char *iBuf = NULL, int iLen = 0, int time = 0 ); — sending of the data over the transport. The waiting timeout time of the connection in milliseconds. The time in negative disables the transport's request/respond mode and allows for the independently reading/writing to a buffer IO, with the reading timeout time in absolute.
API of the modules of the "Transport protocols" subsystem
Provides OpenSCADA with the protocol layer communications, implemented by the module, for the data access from the external systems and for the OpenSCADA data providing for the external systems.
TProtocol->TModule — the root module object of the "Transport protocols" subsystem:
  • virtual void itemListIn( vector<string> &ls, const string &curIt = "" ); — the list ls of the input protocol sub-elements from the current item curIt, if the protocol provides them. It is used when selecting an object in the input transport configuration.
  • virtual void outMess( XMLNode &io, TTransportOut &tro ); — the data transfer by the objects of the OpenSCADA core in the XML tree io to the remote system via the tro transport and the current output protocol. Presenting the data in the XML tree is non-standardized and specific to the logical structure of the protocol. This data are serialized — converted in a sequence of bytes according to the protocol, and are sent via the specified tro output transport by the messIO() function.
  • virtual TProtocolIn *in_open( const string &id ); — called when a new transport protocol object is opened or created by this module with the identifier id.
TProtocolIn — the input object of the transport protocol of the input requests processing from the input transport object TTransportIn. For each session of the input request the object of the associated input protocol is created, which remains alive until completion of the full "request->answer" session. Address of the transport, which opened the protocol instance, is specified in srcTr():
  • virtual unsigned waitReqTm( ) — the request waiting time on the input transport in milliseconds, call after what to the protocol with the empty message — the polling mode. Setting it to zero disable the polling mode.
  • virtual void setSrcTr( TTransportIn *vl ) — setting of the transport-source of the opening of the session of the input protocol.
  • virtual void setSrcAddr( const string &vl ); — setting of the sender address.
  • virtual bool mess( const string &request, string &answer ); — transfer of the request data sequence to the protocol object for it parsing accordingly to the protocol implementation. The protocol function should process the request, generate the response in answer and return FALSE in the case of the completeness of the request. If the request is not complete, it is necessary to return TRUE for the transport to indicate the "expectation of the completion", the previous parts of the request should be saved in the context of the protocol object.
API of the modules of the "Data AcQuisition" subsystem
Provides the realtime data acquisition from the external systems or it formation in the calculators, implemented by the module. That is the main subsystem since SCADA is about the Data Acquisition primarily. As the main subsystem it provides several approaches in the modules implementation, which mostly about the attributes structure formation and storing:
  1. Static formation through definition a set of the parameter types inherited from TTypeParam, that is the structures applying is performed as an attributes set with the parameter type change. This method is least flexible and it used by such modules: GPIO, SMH2Gi, AMRDevs.
  2. Dynamic formation with the structure container TElem managing in the parameter object TParamContr. This method is most flexible and used in most modules which mean of the structure be configurable.
  3. As an extension of the dynamic formation there is the Logical Level parameter type, what can be added to any module, but that used mostly in the universal data sources: LogicLev, ModBus, Siemens, OPC_UA.
TTypeDAQ->TModule — the root module object of the "Data AcQuisition" subsystem:
  • virtual bool compileFuncLangs( vector<string> *ls = NULL ); — request the list ls of languages for which it is realised the possibility of formation of user procedures in this module, and check for fact of that support.
  • virtual void compileFuncSnthHgl( const string &lang, XMLNode &shgl ); — request the rules of the syntax highlight shgl for the specified language lang.
  • virtual string compileFunc( const string &lang, TFunction &fnc_cfg, const string &prog_text, const string &usings = "", int maxCalcTm = 0 ); — compiling-registering of the user function on the supported programming language lang and on the source code of procedure prog_text, based on the procedure parameters fnc_cfg. Returns address of the compiled function's object, ready for execution.
  • virtual bool redntAllow( ); — state of support the redundancy mechanisms by the module. Should be overridden and return TRUE if supported, otherwise FALSE.
  • virtual TController *ContrAttach( const string &id, const string &daq_db ); — called when a new controller object is opened or created by this module with the identifier id.
TController — the data source controller object. In the context of the object is usually run a task of the periodic or scheduled polling of the realtime data of one physical controller or physically separated block of data. In the case of data getting by the packages, they are placed directly into the archive associated with the parameter attribute TVAl::arch(), and the current value is set by the TVAl::set() function with the attribute "sys"=TRUE:
  • virtual string getStatus( ); — request function of the controller status.
  • virtual void enable_( ); — enabling of the controller object. Usually at this stage the initialisation of the parameters' objects and their interfaces in the form of attributes is made, the attributes can sometimes be requested from the associated remote source.
  • virtual void disable_( ); — disabling the controller object.
  • virtual void start_( ); — starting the controller object. Usually at this stage the task of periodic or scheduled polling is created and started.
  • virtual void stop_( ); — stopping the controller object.
  • virtual void redntDataUpdate( ); — operation of the data receiving from the backup station, called automatically by the service procedure of the redundancy scheme of the subsystem.
  • virtual string catsPat( ); — list of the regular expression rules, separated by '|', for matching by category the messages generated by the object.
  • virtual void messSet( const string &mess, int lev, const string &type2Code = "OP", const string &prm = "", const string &cat = "" ); — formation of the DAQ-sourced messages for the parameter object prm (PrmId) or the controller object in whole if the parameter object is not specified, for the message mess, level lev and for the type code type2Code. This function generates the messages with the unified DAQ-transparency category "{type2Code}{ModId}:{CntrId}[.{prm}][:{cat}]".
  • virtual TParamContr *ParamAttach( const string &id, int type ); — called when a new object of the controller parameter is opened or created by this module with the identifier id.
TParamContr->TValue — the controller parameter object of the data source. Contains attributes with real data in a set defined by physically available data. The values to the attributes come from the polling task of the controller, in the asynchronous mode, or are requested during the access, in the synchronous mode, and through the methods of the inherited type TValue:
  • virtual TElem *dynElCntr( ); — container of the dynamic elements of the DAQ attributes. Defined mostly by the logical level sources what provide such kind containers.
  • virtual void enable( ); — enabling the parameter object, the formation of the attributes set and filling them with the value of unreliability is made.
  • virtual void disable( ); — disabling the parameter object.
  • virtual void setType( const string &tpId ); — called to change the parameter type to tpId and can be processed in the module object to change own data.
  • virtual TVal* vlNew( ); — called at the stage of a new attribute creation. Can be overridden to implement special behavior within its object, inherited from TVal, when accessing the attribute.
  • virtual void vlGet( TVal &vo ); — called for the attribute vo with the direct reading mode TVal::DirRead when reading the value in order to directly-synchronous read from the physical source or the object buffer.
  • virtual void vlSet( TVal &vo, const TVariant &vl, const TVariant &pvl ); — called for the attribute vo with the direct recording mode TVal::DirWrite when setting the value in order to directly-synchronous set to the physical source or the object buffer, with the previous value pvl.
  • virtual void vlArchMake( TVal &val ); — called at the stage of creation the values archive with the val attribute as the source in the order to initialise the qualitative characteristics of the archive buffer according to the characteristics of the data source and polling.
API of the modules of the "Archives-History" subsystem
Used for archiving and maintaining the history of messages and realtime values received in the "Data AcQuisition" subsystem, and in the means implemented by the module.
TTypeArchivator->TModule — the root module object of the "Archives-History" subsystem:
  • virtual TMArchivator *AMess( const string &id, const string &stor ); — called when a new object of the message archiver is opened or created by this module with the identifier id and in the storage stor.
  • virtual TVArchivator *AVal( const string &id, const string &stor ); — called when a new object of the value archiver is opened or created by this module with the identifier id and in the storage stor.
TMArchivator — the message archiver object.
  • virtual void redntDataUpdate( ); — operation of the data receiving from the backup station, called automatically by the service procedure of the redundancy scheme of the subsystem.
  • virtual void start( ); — starting the archiver object, the archiver starts for receiving messages and placing them into the storage.
  • virtual void stop( ); — stopping the archiver object.
  • virtual time_t begin( ); — begin time of the archiver data accordingly with the current state of the storage.
  • virtual time_t end( ); — end time of the archiver data accordingly with the current state of the storage.
  • virtual bool put( vector<TMess::SRec> &mess, bool force = false ); — placing the message group mess to the archiver. Returns TRUE on the successful operation. Set force for direct writing to the archiver omit the redundancy.
  • virtual time_t get( time_t bTm, time_t eTm, vector<TMess::SRec> &mess, const string &category = "", char level = 0, time_t upTo = 0 ); — getting the messages to mess from the archiver for the specified filter parameters. Returns time of the request stop, useful for proceeding from this position as the end time, i.e. iteratively digging into the story. The filter specified by the time range [bTm...eTm], category rules, level and limited up to the time upTo. In the absence of a direct definition of the limiting time upTo, this limitation is set to prmInterf_TM — 7 seconds.
TVArchivator — the value archiver object.
  • virtual void start( ); — starting the archiver object, the archiver starts for receiving values and placing them into the storage.
  • virtual void stop( bool full_del = false ); — stopping the archiver object with the ability to completely remove its data from the storage at full_del.
  • virtual TVArchEl *getArchEl( TVArchive &arch ); — getting the element object of the value archive for the specified archive arch.
  • virtual void pushAccumVals( ); — pushing the accumulated values by the archivation task, for the accumulative archivers.
TVArchEl — the element object of the value archiver.
  • virtual void fullErase( ); — called to complete removal of the archive part in the archiver.
  • virtual int64_t end( ); — end time in microseconds of the available values in the archive of the archiver.
  • virtual int64_t begin( ); — begin time in microseconds of the available values in the archive of the archiver.
  • virtual TVariant getValProc( int64_t *tm, bool up_ord ); — requesting of one value from the archive for the time tm and fine-tuning to the upper value in the sampling grid up_ord.
  • virtual void getValsProc( TValBuf &buf, int64_t beg, int64_t end ); — requesting of a value group to buf from the archive and for the time range [beg...end].
  • virtual void setValsProc( TValBuf &buf, int64_t beg, int64_t end, bool toAccum ); — setting of the value group buf to the archive, for the time range [beg...end] and through the accumulation toAccum.
API of the modules of the "User Interfaces" subsystem
The user interface is formed according to the concept and mechanisms of external known standards and libraries.
TUI->TModule — the root module object of the "User Interfaces" subsystem:

At.png It contains no specific functions!

API of the modules of the "Special" subsystem
Implements the specific functions that are not included in any of the above subsystems. The specific functions are formed accordingly to their own need and with using all features of the OpenSCADA API.
TSpecial->TModule — the root module object of the "User Interfaces" subsystem:

At.png It contains no specific functions!


19 Debugging and Testing OpenSCADA

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.

20 Rules for design and commenting of the sources of OpenSCADA and its modules

When writing and design of the sources of OpenSCADA 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 OpenSCADA:

21 Conventional signs in the text and source code

????[{TAGS}] — must be implemented shortly or according to the schedule in TAGS:

?!?! — section is not completely implemented and can be implemented not at the schedule but an occasion;
!!!! — section requires rethinking and explains-clears-warns such sort of implementing-commenting.

22 Links

Documents/API/en - GFDLMay 2024OpenSCADA 0.9.7