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

This is an old revision of HomePageEn/Doc/API/part14 from 2010-11-02 09:52:05..

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:

• providing of the uniform access to system components, including the blocks of the dynamic access;
• building the distributed control interface.

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:

• Web interface of the configuration ;
• GUI configuration interface (QT, GTK+, ...);
• reflection of the configuration in the network for distributed management of multiple OpenSCADA-stations from the single management area;
• using as the protocol for objects' data access from the network;
• provision of service functions to access of the exterior application and the single OpenSCADA components to the internal data.

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

• information structure of the user configuration page;
• dynamic part in the form of requests for getting, modification of data and service requests;
• container or group of the above elements.

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.

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:

• inheritance of the TCntrNode object or its child;
• information structure formation;
• service of the requests to dynamic data.

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.

<branches id='br'> <grp id='/br/in_' descr='Incoming transport' acs='04'/> <grp id='/br/out_' descr='Outgoing transport' acs='04'/> </branches>

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

Tag	Description
<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 <tp>	Description
str	String type. <fld id="host" dscr="Host name" tp="str"/>
dec	Integer in decimal representation. <fld id="debug" dscr="Debug level" tp="dec"/>
oct	Integer in octal representation. <fld id="cr_file_perm" dscr="Make files permissions(default 0644)" tp="oct" len="3"/>
hex	Integer in hexadecimal representation.
real	Real value.
bool	Boolean sign ("false"|"true"). <fld id="log_sysl" dscr="Direct messages to syslog" tp="bool"/>
time	Time 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.

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

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

<el id="0">./MODULES/arh_base.o</el>
<el id="1">./MODULES/cntr_sys.o</el>

</get>String's addition| Request: command "add": <add path="/fld_teg" user="user" id="tst">Test</add>
To add the string with ID "tst" and value "Test". If the list is not indexed, then the id attribute is absent. Result: confirmation or an error message.Insert the string| Request: command "ins": <ins path="/fld_teg" user="user" pos="3" p_id="tst1" id="tst">Test</ins>
To insert the string with the ID "tst" and value "Test" in position 3 with the string "tst1". In the case of the index list p_id attribute contains the identifier, else - the text of the string. If the list is not indexed, then the ID attribute is absent. Result: confirmation or an error message.Deleting of the string| Request: command "del": <del path="/fld_teg" user="user" pos="3" id="tst">Test</del>
To delete the string with ID "tst" and value "Test" from the position 3. If the list is not indexed, then the ID attribute is absent. Result: confirmation or an error message.Edit of the string| Request:: command "edit": <edit path="/fld_teg" user="user" pos="3" p_id="tst1" id="tst" >Test</edit>
To replace the string at position 3 with the identifier "tst1" with the another string with the identifier "tst" and value "Test". In the case of the index list p_id attribute contains the identifier, else - the text of the string. If the list is not indexed, then the ID attribute is absent. Result: confirmation or an error message.Mooving of the string| Request: command "move": <move path="/fld_teg" user="user" pos="3" to="5"/>
To move the string from position 3 to position 5. Result: confirmation or an error message.Operation|ActionInterrogation| Request: command "get": <get path="/fld_teg" user="user" cols="0;2" rows="100;1000"/>
To get columns 0-2 and rows of them from 100 to 1000 table. Result: Confirmation with the data of the table or an error message. The result is formed in the form:
<get path="/fld_teg" user="user" cols="0;2" rows="100;1000" rez="0">

<list id="0" tp="str">

<el id="100">Sat Feb 21 18:04:16 2004</el>

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

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

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

<el id="100">*:(TSYS)Broken PIPE signal allow!</el>

</list>

</get>Adding of the string| Request: command "add": <add path="/fld_teg" user="user"/>Result: confirmation or an error message.Insert of the string| Request: command "ins": <ins path="/fld_teg" user="user" row="3"/>
To insert the string in position 3. Command does not work when attribute <key> is set! Result: confirmation or an error message.Deleting of the string| Request: command "del": <del path="/fld_teg" user="user" row="3"/> or <del path="/fld_teg" user="user" key_id="Test"/> for the key mode
To remove the string in position 3 or string in the position where the <id> column value is "Test". Result: confirmation or an error message.Moving of the string| Request: command "move": <move path="/fld_teg" user="user" row="3" to="5"/>
To move the string from position 3 to position 5. Command does not work when attribute <key> is set! Result: confirmation or an error message.Change the cell| Request: command "set": <set path="/fld_teg" user="user" row="3" col="id">Test</set> or <set path="/fld_teg" user="user" key_id="Test" col="id">Test1</set> for the key mode
To set the cell's value in row 3 and column "id" to "Test" or set of the column named "id" of the row to the position where the <id> column value is "Test" to value "Test1". Practically, this command renames a key element of the specified row. Result: confirmation or an error message.Tag|Description|Attributes|Contentsoscada_cntr|The 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, branchesbranches|Container of the groups of child branches of the node.| id - Container's ID. It is equal: br.|grpgrp|The 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.| area|Grouping of the standard tags.| id - ID; dscr - description; acs - access options.|area, fld, list, table, comm, imgcomm|Commands to the node.| id - ID; dscr - description; help - command's help; tp - command's type (lnk - ññûëêà); acs - access options.|fldfld|Description of the standard data types.| id - ID; dscr - description; help - help; acs - access options. tp - element's type:
str(len, dest, cols, rows) - 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 ';').| list|List 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>.| table|Table 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.|listimg|Image.| id - ID; dscr - description; help - image help; acs - access options; h_sz - horizontal limitation; v_sz - vertical limitation.| Inherited:|By all the dynamic and controlled objects directly or through the childs.||

Operation	Action
Interrogation	Request: command «get»: <get path="/fld_teg" user="user"/>. Result: confirmation with the value in the text of the tag or an error message.
Modification	Request: 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).
	# 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. #
	# 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. #
	# 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: <get path="/fld_teg" user="user"/>. - image request; The result is the confirmation with image data or an error message. <set path="/fld_teg" user="user">img</set> - çàãðóçêà èçîáðàæåíèÿ. 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: Command execution: <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> Load the link to another page: <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. #
	# 14.5. Object of the dynamic tree node (TCntrNode) #

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

• R_R_R_ (0444) - access to all read-only;
• R_R___ (0440) - read access only to the owner and group;
• R_____ (0400) - read access only to the owner;
• RWRWRW (0666) -full access to all;
• RWRWR_ (0664) - full access to the owner and group, and for the rest - the read-only;
• RWR_R_ (0644) - full access to the owner and for the group and the rest - the read-only;
• RWR___ (0640) - full access to the owner, read-only - to the group and closed for the rest;
• RW____ (0600) - full access to the owner, but for the group and everyone else is closed.

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

• TCntrNode::MkDisable - switching-off (0);
• TCntrNode::Disable - disabled (1);
• TCntrNode::MkEnable - switching-on (2);
• TCntrNode::Enable - enabled (3);
• TCntrNode::SelfModify - sign of the node's modification (0x04).

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

• TCntrNode::NodeConnect - connection of the node;
• TCntrNode::NodeRestore - restoration of the connection of the node;
• TCntrNode::NodeShiftDel - the sign -deleting of the node is suspended.

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

• TCntrNode::Self - the given node is modified;
• TCntrNode::Child - the child nodes are modified;
• TCntrNode::All - the given node and the child ones are modified.

Public methods:

• TCntrNode( TCntrNode *prev = NULL ); - Initialization with an indication of the parent node <prev>.
• virtual TCntrNode &operator=( TCntrNode &node ); - Virtual copy function of the dynamic tree nodes.
• void cntrCmd( XMLNode *opt, int lev = 0, const string &path = "", int off = 0 ); - Command of work with the control interface of the system. The transport transitions to the full path of the following form are supported: ãäå %2fgen - encoded sub-path to a particular field of the page (/gen).
• static XMLNode *ctrId( XMLNode *inf, const string &n_id, bool noex = false ); - Getting the XML node by the attribute's value "id" <n_id>. XML requests of the node by the full path to it are supported (node1/node2/node3).
• 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, ... ); - 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>,... .
• bool ctrRemoveNode( XMLNode *nd, const char *path ); - Removing the control element <path> from the page <nd>.
• static bool ctrChkNode( XMLNode *nd, const char *cmd="get", int perm=0444, const char *user="root", const char *grp="root", char mode=04, const char *warn = NULL ); - Checking for the dynamic command getting <cmd> and for the existence of rights to its execution.
• virtual Res &nodeRes( ); - Resource of the node's using.
• virtual const string &nodeName( ); - Node's name.
• string nodePath( char sep = 0, bool from_root = false ); - Getting the full path to the node, beginning from the root <from_root>, and using the separator <sep> or standard path recording.
• void nodeList( vector<string> &list, const string& gid = "" ); - Child nodes list <list> in the specified group <gid>.
• AutoHD<TCntrNode> nodeAt( const string &path, int lev = 0, char sep = 0, int off = 0 ); - Attachment to the child node.
• void nodeDel( const string &path, char sep = 0, int flag = 0 ); - Deleting the node using its path.
• static void nodeCopy( const string &src, const string &dst, const string &user = "root" ); - Copying the nodes of the dynamic tree.
• TCntrNode *nodePrev( bool noex = false ); - Address of the parent node.
• char nodeFlg( ); - Node's flag.
• char nodeMode( ); - Node's status.
• unsigned nodeUse( ); - Number of the connections to the node.
• unsigned nodePos( ); - The position of the node in the parent-node's container. It is valid only for ordered containers.
• int isModify( int mflg = TCntrNode::All ); - Checking for the modification of the node or nodes' branch.
• void modif( ); - Setting the sign of the node's modification.
• void modifG( ); - Setting the sign of the nodes' branch modification.
• void modifClr( ); - Clear the sign of the node's modification .
• void load( bool force = false ); - Load the dynamic tree node.
• void save( ); - Saving the dynamic tree node.
• void AHDConnect( ); - Connection to the node (capture of the resource).
• void AHDDisConnect( ); - Disñonnection from the node (release of the resource).
• virtual TVariant objPropGet( const string &id ); - Request of the node's property as the user's object.
• virtual void objPropSet( const string &id, TVariant val ); - Setting the node's property as the user's object.
• virtual TVariant objFuncCall( const string &id, vector<TVariant> &prms ); - Node's function calling as the user's object.

Protected methods:

• virtual void cntrCmdProc( XMLNode *req ); - Function of requests' processing of the control interface. It must be redefined by the child.
• void nodeEn( int flag = 0 ); - Node's enabling.
• void nodeDis( long tm = 0, int flag = 0 ); - Disabling of the node with the flag transfer.
• void nodeDelAll( ); - Clear all containers with child nodes.
• void setNodePrev( TCntrNode *node ); - Setting the parent node to <node>.
• void setNodeMode( char mode ); - Setting the node's status.
• AutoHD<TCntrNode> chldAt( unsigned gr, const string &name, const string &user = "" ); - Attachment to the child node <name> of the container <gr> of the user <user>.
• void chldList( unsigned gr, vector<string> &list ); - The list of the child nodes <list> in the specified container <gr>.
• bool chldPresent( unsigned gr, const string &name ); - Check for the presence of the specified child node <name> in the container <gr>.
• void chldAdd( unsigned gr, TCntrNode *node, int pos = -1 ); - Adding the child node <node> to the container <gr> and position <pos>.
• void chldDel( unsigned gr, const string &name, long tm = -1, int flag = 0 ); - Deleting the child node <name> from the container <gr> with the flag <flag>.
• unsigned grpSize( ); - Number of the containers with the child nodes.
• char grpId( const string &sid ); - Getting the index of the group by its ID.
• GrpEl &grpAt( char id ); - Access to the structure of the group.
• unsigned grpAdd( const string &id, bool ordered = false ); - Adding the container of the child nodes with the prefix <id> and the possibility of an orderly storage <ordered>. Returns the ID of the new container.
• virtual void preEnable( int flag ); - The connection preact. It is called before the actual connection.
• virtual void postEnable( int flag ); - The connection preact. It is called after the actual connection.
• virtual void preDisable( int flag ); - The disconnection preact. It is called before the actual disconnection.
• virtual void postDisable( int flag ); - The disconnection preact. It is called before the actual disconnection (before deleting).
• virtual void load_( ); - The function of the loading child node calling.
• virtual void save_( ); - The function of the saving child node calling.

2010-11-02 09:52:05 | Owner: Maxim Lysenko | | Search: