OpenSCADAWiki: Home Page En/Doc/API/part14
 

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

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

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

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

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

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

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

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

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

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


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

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

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

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

Request is executed by sending a container with some parameters in the attributes. The result is placed in the resulting container with the changes in certain attributes of the root container. In general, the request container can be written as follows:
<cmd path="/TreePath" user="user" force="1"/>
Where:
cmd — request command;
path — path to the node or to the branch of the tree;
user — user of the system on behalf of which the request is sent;
force — the sign: to execute the request without warning.

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

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

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

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

Each page can contain groups of child branches. For descriptions of groups of branches there is the tag "branches". Tag contains the description of groups of branches through embedded tags grp. The group tag can be accessed as for the "read" (visibility) and for modification ( the execution of commands for adding and removing the elements of the group), hence the element of the triad of access may be:
00 — there is no any access;
04 — there is an access only for reading;
02 — there is only access fro the writing, usually this value has no meaning because the write access means access for reading;
06 — there is an access to read, and to write.


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

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

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

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

14.3.1. Area tag "area"

Areas are described with "area" tag and are intended to group the elements on different features. Area may include other elements and areas. The root ones form the bookmarks in the presentation of the user interface. To tag, you can access only to "read" or "visibility", hence the element of the triad of access can be set to 00, if access is absent, or 04, if it is present.
<area id="base" dscr="Base information">
  <fld id="host" dscr="Host name" tp="str"/>
  <fld id="user" dscr="Operated user" tp="str"/>
  <fld id="sys" dscr="Station system" tp="str"/>
  <area id="other" dscr="Other options">
     <fld id="val" dscr="Value" tp="real"/>
  </area>
</area>

14.3.2. Data tags

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

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

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


The tag can be accessed as to "read" and also to "write", therefore an element of the triad of access may be:
00 — there is no any access;
04 — there is an access only for reading;
02 — there is only access fro the writing, usually this value has no meaning because the write access means access for reading;
06 — there is an access to read, and to write.

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

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

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


The tag can be accessed as to "read" and also to "write"(modification), therefore an element of the triad of access may be:
00 — there is no any access;
04 — there is an access only for reading;
02 — there is only access fro the writing, usually this value has no meaning because the write access means access for reading;
06 — there is an access to read, and to write.

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

Table 4. Actions over the list.
OperationAction
InterrogationRequest: command "get": <get path="/fld_teg" user="user"/>
Result: confirmation with the result in the tag's text or an error message. The result is formed in the form:
<get path="/fld_teg" user="user" rez="0">
<el id="0">./MODULES/arh_base.o</el>
<el id="1">./MODULES/cntr_sys.o</el>
</get>
String's additionRequest: command "add": <add path="/fld_teg" user="user" id="tst">Test</add>
To add the string with ID "tst" and value "Test". If the list is not indexed, then the id attribute is absent.
Result: confirmation or an error message.
Insert the stringRequest: command "ins": <ins path="/fld_teg" user="user" pos="3" p_id="tst1" id="tst">Test</ins>
To insert the string with the ID "tst" and value "Test" in position 3 with the string "tst1". In the case of the index list p_id attribute contains the identifier, else — the text of the string. If the list is not indexed, then the ID attribute is absent.
Result: confirmation or an error message.
Deleting of the stringRequest: command "del": <del path="/fld_teg" user="user" pos="3" id="tst">Test</del>
To delete the string with ID "tst" and value "Test" from the position 3. If the list is not indexed, then the ID attribute is absent.
Result: confirmation or an error message.
Edit of the stringRequest:: command "edit": <edit path="/fld_teg" user="user" pos="3" p_id="tst1" id="tst" >Test</edit>
To replace the string at position 3 with the identifier "tst1" with the another string with the identifier "tst" and value "Test". In the case of the index list p_id attribute contains the identifier, else — the text of the string. If the list is not indexed, then the ID attribute is absent.
Result: confirmation or an error message.
Mooving of the stringRequest: command "move": <move path="/fld_teg" user="user" pos="3" to="5"/>
To move the string from position 3 to position 5.
Result: confirmation or an error message.
c) Tag "table"
<table id="a_mess" key="0" col_lst="0;1;2">
  <list id="0" dscr="Id" acs="4" tp="str"/>
  <list id="1" dscr="Name" acs="4" tp="str"/>
  <list id="2" dscr="Type" acs="4" tp="str"/>
  <list id="3" dscr="Hide" acs="4" tp="bool"/>
</table>


The tag of the table or single column can be accessed as to "read" and also to "write"(modification), therefore an element of the triad of access may be:
00 — there is no any access;
04 — there is an access only for reading;
02 — there is only access fro the writing, usually this value has no meaning because the write access means access for reading;
06 — there is an access to read, and to write.

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

Table 5. Actions over the table.
OperationAction
InterrogationRequest: command "get": <get path="/fld_teg" user="user" cols="0;2" rows="100;1000"/>
To get columns 0-2 and rows of them from 100 to 1000 table.
Result: Confirmation with the data of the table or an error message. The result is formed in the form:
<get path="/fld_teg" user="user" cols="0;2" rows="100;1000" rez="0">
<list id="0" tp="str">
<el id="100">Sat Feb 21 18:04:16 2004</el>
</list>
<list id="1" tp="str">
<el id="100">SYS</el>
</list>
<list id="2" tp="str">
<el id="100">*:(TSYS)Broken PIPE signal allow!</el>
</list>
</get>
Adding of the stringRequest: command "add": <add path="/fld_teg" user="user"/>
Result: confirmation or an error message.
Insert of the stringRequest: command "ins": <ins path="/fld_teg" user="user" row="3"/>
To insert the string in position 3. Command does not work when attribute key is set!
Result: confirmation or an error message.
Deleting of the stringRequest: command "del": <del path="/fld_teg" user="user" row="3"/> or <del path="/fld_teg" user="user" key_id="Test"/> for the key mode
To remove the string in position 3 or string in the position where the id column value is "Test".
Result: confirmation or an error message.
Moving of the stringRequest: command "move": <move path="/fld_teg" user="user" row="3" to="5"/>
To move the string from position 3 to position 5. Command does not work when attribute key is set!
Result: confirmation or an error message.
Change the cellRequest: command "set": <set path="/fld_teg" user="user" row="3" col="id">Test</set> or <set path="/fld_teg" user="user" key_id="Test" col="id">Test1</set> for the key mode
To set the cell's value in row 3 and column "id" to "Test" or set of the column named "id" of the row to the position where the id column value is "Test" to value "Test1". Practically, this command renames a key element of the specified row.
Result: confirmation or an error message.
d) Tag "img"
<img id="ico" descr="Page icon"/>


The tag can be accessed as to "read" and also to "write"(modification), therefore an element of the triad of access may be:
00 — there is no any access;
04 — there is an access only for reading;
02 — there is only access fro the writing, usually this value has no meaning because the write access means access for reading;
06 — there is an access to read, and to write.

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

The following requests' commands are supported:
The result is the confirmation with image data or an error message.
The result is the confirmation or error message.
e) Commands with the parameters. Tag "comm"
<comm id="add">
  <fld id="tm" tp="time"/>
  <fld id="cat" tp="str"/>
  <fld id="lvl" tp="dec" min="0" max="7"/>
  <fld id="mess" tp="str"/>
</comm>


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

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

The following request commands are supported:
<set path="/fld_teg" user="user"/>
  <fld id="tm">1023456244</fld>
  <fld id="cat">*</fld>
  <fld id="lvl">2</fld>
  <fld id="mess">Test mess</fld>
</set>

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


The result is the confirmation or error message.
f) Branches (child nodes)
<list id="k_br" dscr="Kernel branches" tp="br"/>


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

14.4 Hierarchical dependences of the information elements of the control language

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


Table 6. Hierarchical dependencies of the information elements of the language.
TagDescriptionAttributesContents
oscada_cntrThe root element of the page. It is the only and serves to identify the origin of language of control interface.id — ID;
dscr — description.		area, img, branches
branchesContainer of the groups of child branches of the node.id — Container's ID. It is equal: br.grp
grpThe group of the child nodes.id — prefix of the group of child nodes in the system;
dscr — description of the branches' group;
acs — access options.
areaGrouping of the standard tags.id — ID;
dscr — description;
acs — access options.		area, fld, list, table, comm, img
commCommands to the node.id — ID;
dscr — description;
help — command's help;
tp — command's type (lnk — ññûëêà);
acs — access options.		fld
fldDescription of the standard data types.id — ID;
dscr — description;
help — help;
acs — access options.
tp — element's type:
str(len, dest, cols, rows(SnthHgl)) — string element;
dec(len, max, min, dest) — integer in decimal representation;
oct(len, max, min, dest) — integer in octal;
hex(len, max, min, dest) — integer in hexadecimal;
real(len, max, min, dest) — real number;
bool — boolean sign;
time — time/date in seconds (from 01/01/1970).
Connected:
len — value length (char.);
min — minimum of value;
max — maximum of value;
cols — number of columns;
rows — number of rows;
dest — input method:
data — source of binary data (base64).
select(select) — selective type;
sel_ed(select) — selective type with the possibility of editing.
select — path to the hidden list;
sel_list — static list (separator ';');
sel_id — static list of the identifiers (separator ';').
listList of standard data types.id — ID;
dscr — description;
help — help list;
acs — access options;
tp — as in fld except:
br(br_pref) — child nodes.
idm — indexed list (0|1);
s_com — ways of the list's modification [add][,ins][,edit][,del]:
add — add rows;
ins — insert rows;
edit — modify rows;
del — delete rows.
Connected:
br_pref — child node's prefix;
dest — as in fld.
tableTable of standard data types.id — ID;
dscr — description;
help — table help;
acs — access options;
key — key columns (key="id,name,per");
cols — list of columns in the request attribute;
rows — range of rows in the attribute of the request;
s_com — types of the table's modification [add][,del][,ins][,move]:
add — add rows;
ins — insert rows;
del — delete rows;
move — move rows.
list
imgImage.id — ID;
dscr — description;
help — image help;
acs — access options;
h_sz — horizontal limitation;
v_sz — vertical limitation.

14.5. Object of the dynamic tree node (TCntrNode)

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

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

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

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

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

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

Protected methods: