From OpenSCADAWiki
Jump to: navigation, search

1 API of the user programming and service interfaces of OpenSCADA

1.1 API of the user programming

API of the user programming of the visualization engine are represented directly by the OpenSCADA objects, which form the user interface, that is by the "Session" and "Widgets-pages". For the user, these objects provide a set of control functions:

User object model of the module VCAEngine.

Object "Session" ( this.ownerSess() )

  • string user( ) — current session user.
  • int alrmQuietance( int quit_tmpl, string wpath = "", bool ret = false ) — quiets of the violations wpath with the template quit_tmpl. If wpath is empty string then the global quietance makes. Into the string wpath, by symbol ';', can be enumerated addresses of several widgets. When set the ret, the quietance return is performed.
  • int reqTm( ) — last request time in seconds from the epoch of 1/1/1970.
  • string reqUser( ) — last request user.
  • string reqLang( ) — last request language.
  • int userActTm( ) — last user action time in seconds from the epoch of 1/1/1970.
  • bool uiCmd( string cmd, string prm, string src ) — sends a UI command of the pages managing, that is: "open", "next", "prev"; for more details see in the events section. This function must be in the priority of using to the pages managing before the direct writing to the page attributes "pgOpen" and "pgOpenSrc" due it is single method of the correct work with the linked pages.

Object "Widget" (this)

  • TCntrNodeObj ownerSess( ) — session object for the current widget.
  • TCntrNodeObj ownerPage( ) — parent page object for the current widget.
  • TCntrNodeObj ownerWdg( bool base = false ) — parent widget object for the current widget. If set base then returns the parent page objects also.
  • TCntrNodeObj wdgAdd( string wid, string wname, string parent ) — adds the new widget wid with the name wname and based on the library widget parent.
//Adds the new widget, based at the text primitive
nw = this.wdgAdd("nw", "New widget", "/wlb_originals/wdg_Text");
nw.attrSet("geomX", 50).attrSet("geomY", 50);
  • bool wdgDel( string wid ) — deletes the widget wid.
  • TCntrNodeObj wdgAt( string wid, bool byPath = false ) — attaches to child or global widget, by the path byPath. In the case of global connection, you can use absolute or relative path to the widget. For starting point of the absolute address acts the root object of the module "VCAEngine", which means the first element of the absolute address is session identifier, which is ignored. The relative address takes the countdown from the current widget. Special element of the relative address is an element of parent node "..".
  • Array attrList() — list of the widget attributes.
  • bool attrPresent( string attr ) — checks to presence fact of the attribute attr of the widget.
  • ElTp attr( string attr, bool fromSess = false ) — value of the attribute attr of the widget or from the session fromSess. For missing attributes will be return empty string.
  • TCntrNodeObj attrSet( string attr, ElTp vl, bool toSess = false ) — sets the value vl to the attribute attr of the widget or to the session, by toSess. The object is returned for the function concatenation.
  • string link( string attr, bool prm = false ) — link for the widget attribute attr. At set prm requests the link for the attributes block (parameter), represented by the attribute.
  • string linkSet( string attr, string vl, bool prm = false ) — sets the link for the widget attribute attr. At set prm, sets the link for the attributes block (parameter), represented by the attribute.
//Sets the link to the parameter for the eight trend
this.linkSet("el8.name", "prm:/LogicLev/experiment/Pi", true);
  • string {resource,mime}( string addr, string MIME = "" ) — resource object by the address addr (the direct link to the resource or the widget attribute contained the link) with the MIME, from the session table or the source. It is designed for the resource objects edition and that substitution to this session's context, for example, images SVG.
  • int {resourceSet,mimeSet}( string addr, string data, string MIME = "" ) — sets the resource object to data with MIME by the address addr.
  • int messDebug( string mess ); int messInfo( string mess ); int messNote( string mess ); int messWarning( string mess ); int messErr( string mess ); int messCrit( string mess ); int messAlert( string mess ); int messEmerg( string mess ); — formats of the program message mess with the category — the widget path.

Object "Widget" of the primitive "Document" (this)

  • string getArhDoc( int nDoc) — text of the archive document to "nDoc" depth (0-{aSize-1}).


Deprecated, but supported, the API is represented by a group of functions directly in the module of the VCA engine. Calling these functions from the widget procedure can be done directly by the identifier, since their namespace is defined in the context of the widget procedures.

Widgets list (WdgList)
Description: Returns a list of the widgets, into the widgets container, or the child list. If set pg then returns the pages list for projects and sessions.
Parameters:

Identifier Name Type Mode By default
list List String Return
addr Address String Input
pg Pages Boolean Input 0

Node presence (NodePresent)
Description: Checking for the node presence, including widgets, attributes and other.
Parameters:

Identifier Name Type Mode By default
rez Result Boolean Return
addr Address String Input

Attributes list (AttrList)
Description: Returns an attributes list of the widget. If set noUser then returns only not user attributes.
Parameters:

Identifier Name Type Mode By default
list List String Return
addr Address String Input
noUser Not user Boolean Input 1

Get the attribute (AttrGet)
Description: Getting value of the widget attribute. The request can be done as by indicating the full address of the attribute in addr, and by: indicating separately the address of the widget in addr and the the attribute identifier in the attr.
Parameters:

Identifier Name Type Mode By default
val Value String Return
addr Address String Input
attr Attribute Boolean Input

Set the attribute (AttrSet)
Description: Setting value of the widget attribute. Setting can be done as by indicating the full address of the attribute in addr, and by: indicating separately the address of the widget in addr and the the attribute identifier in the attr.
Parameters:

Identifier Name Type Mode By default
addr Address String Input
val Value String Input
attr Attribute Boolean Input

Session user (SesUser)
Description: Returns the session user by the session widget path.
Parameters:

Identifier Name Type Mode By default
user User String Return
addr Address String Input

1.2 Service interfaces of OpenSCADA

Service interfaces are the interfaces for access to OpenSCADA through the OpenSCADA control interface. This mechanism is the basis of all mechanisms of exchange within OpenSCADA, implemented through weak links and the standard exchange protocol of OpenSCADA .

1.2.1 Access to the attributes values of the visualization elements (widgets)

In order to provide unitized, grouping and relatively fast access to the attributes values of the visual elements, the service function of the visual element "/serv/attr" and get-set commands of values of the attributes are provided:

  • get: <get path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr"/>;
  • set: <set path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr"/>.

Table. Attributes of the commands for get-set of the attributes of the visual elements.

Identifier Name Value
Requesting command of the visual attributes of the widget: <get path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr"/>
tm Time-counter of the changes Time-counter of the changes set up for the query of the only changed attributes.
<el id="{attr}" p="{a_id}">{val}</el> Formation of the child elements with the results of the attributes In the child element are specified: string identifier attr, index a_id and value val of the attribute.
Setting command of the visual attributes of the widget: <set path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr"/>
<el id="{attr}">{val}</el> Setting of the attributes In the child elements are specified: the string identifier attr and value val of the attribute.
Activation-creation command of the specific attribute for the visualizer: <activate path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr/{attrId}" aNm="{Name}" aTp="{Type} aFlg="{Flags}"/>
attrId Attribute identifier
aNm Attribute name
aTp Attribute type
aFlg Attribute flags
1.2.2 Group access to the values of the attributes of the visualization elements (widgets)

In order to optimize network traffic by eliminating the small queries and use one large, the group query of the attributes' values of the visual elements is made. Grouping of this query involves a request of attributes of the entire branch of the widget, including the included elements. For this request the service command "/serv/attrBr" provides. Request of this service command is equivalent to the service command "/serv/attr" and looks as follows: <get path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattrBr"/>

tm — time-counter of the changes. time-counter of the changes set up for the query of the only changed attributes.

Result:

<el id="{attr}" p="{a_id}">{val}</el> — elements with the results of the attributes. In the element are specified: string identifier attr, index a_id and value val of the attribute.
<w id="{wid}" lnkPath="{lnk_path}">{childs+attrs}</w> — elements with the child widgets and their attributes. The element specifies: identifier of the child widget wid and the widget path, to which this widget refers if it is a link lnk_path.
1.2.3 Access to the session pages

In order to unify and optimize the access to the pages, the service function of the session "/serv/pg" and commands are provided:

  • query of the list of opened pages: <openlist path="/UI/VCAEngine/ses_{Session}/%2fserv%2fpg"/>;
  • open the page: <open path="/UI/VCAEngine/ses_{Session}/%2fserv%2fpg"/>;
  • close the page: <close path="/UI/VCAEngine/ses_{Session}/%2fserv%2fpg"/>.

The result of the query is child elements <el>{OpPage}</el>, which contain the full path of the open page. In addition to the list of open pages, the query returns the value of the current counter for calculating the session, in the attribute tm. If this attribute is set during the query, then for, each open page, it returns the list of changed, since the moment of the specified value of the counter, widgets of the open page.

1.2.4 Control for signaling (alarming)

To provide a mechanism for global control of the signaling of the session, the service function of the session "/serv/alarm" and commands are provided:

  • query of the signals status: <get path="/UI/VCAEngine/ses_{Session}/%2fserv%2falarm"/>;
  • quietance of the signals: <quietance path="/UI/VCAEngine/ses_{Session}/%2fserv%2falarm"/>.

Request for the signals status returns generalized state of the signals, as well as the resource of the notification if the "mode" attribute is "resource". The result of the notification resource request is usually a sound file for playback. At the same time, the tracking of the sequence of signaling and the quietance of individual notification resources is provided.

Request for the quietance performs the quietance of the widget, specified in the attribute wdg, in accordance with the template in the attribute tmpl.

1.2.5 Manipulation with the sessions of the projects

To provide a unitize mechanism for manipulation of the sessions, the module of the VCA engine (VCAEngine), for the visualizers of VCA, is provided the service function "/serv/sess" and the commands:

  • query of the list of open sessions: <list path="/UI/VCAEngine/%2fserv%2fsess"/>;
  • connection-creation of the new session: <connect path="/UI/VCAEngine/%2fserv%2fsess"/>;
  • disconnection-deleting of the session: <disconnect path="/UI/VCAEngine/%2fserv%2fsess"/>.

Table. Attributes of commands of the mechanism of manipulation with sessions

Identifier Name Value
Command of requesting of a list of open sessions for the project: <list path="/UI/VCAEngine/%2fserv%2fsess"/>
prj Indication of the project Specifies the project for which to return the list of opened sessions.
<el>{Session}</el> Control of the sessions' list The child elements specify the sessions opened to the requested project.
Command of the connection-opening the session: <connect path="/UI/VCAEngine/%2fserv%2fsess"/>
sess Installation and control of the session name If the attribute is defined, then the connection to the current session is made, otherwise — the creation of a new session. In the case of opening a new session, the name of the new session is placed to the given attribute.
prj Setting the name of the project It is used to open a new session for the indicated project and when the attribute sess is not specified.
Command of the disconnection-closing of the session: <disconnect path="/UI/VCAEngine/%2fserv%2fsess"/>
sess Setting the name of the session Specifies the name of the session from which disconnection or closure is performed. Sessions that are not background and which are not connected to any visualizer are automatically closed.
1.2.6 Group request for the tree of the widgets libraries

In order to optimize the performance of local and, especially, network interaction, the service function "/serv/wlbBr" and the command of the query of the tree of the widgets libraries: <get path="/UI/VCAEngine/%2fserv%2fwlbBr"/> are provided. The result of the query is a tree with the elements of the widgets libraries — tags wlb. The tags of widgets libraries are included: icon tag ico and the widgets library tags w. The widgets tags, in their turn, contain the icon tag and tags of the child widgets cw.