OpenSCADAWiki : Home Page En / Doc / VC Aconcept / part 4 / part 14

API of the user programming

API of the user programming of API of the visualization engine are represented by the OpenSCADA objects directly, which build user interface, and same "Session" and "Widget/page". These objects provide the set of control functions for the user:

Object "Session" ( this.ownerSess() )

string user( ) — current session user.
int alrmQuittance( int quit_tmpl, string wpath = "", bool ret = false ) — violations quittance wpath with the template quit_tmpl. If wpath is empty string then make global quittance. Into the string wpath, by symbol ';', can be enumerated addresses of several widgets. The ret sets will cause the quittance return.
int reqTm( ) — last request time.
string reqUser( ) — last request user.
string reqLang( ) — last request language.
int userActTm( ) — last user action time.

Object "Widget" (this)

TCntrNodeObj ownerSess( ) — the session's object is getting for current widget.
TCntrNodeObj ownerPage( ) — the parent object's page is getting for current widget.
TCntrNodeObj ownerWdg( bool base = false ) — the parent widget is getting for current widget. If set base then will return the parent pages' objects also.
TCntrNodeObj wdgAdd( string wid, string wname, string parent ) — add new widget wid with the name wname and based on the library widget parent.

//New widget adding, 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 ) — delete the widget wid.
TCntrNodeObj wdgAt( string wid, bool byPath = false ) — attach to child or global, by byPath, widget. 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 omitted. The relative address takes the countdown from the current widget. Special element of the relative address is an element of parent node "..".
bool attrPresent( string attr ) — the attribute attr of the widget checking to presence fact.
ElTp attr( string attr, bool fromSess = false ) — value of the attribute attr of the widget getting or from the session fromSess. For missing attributes will return empty string.
TCntrNodeObj attrSet( string attr, ElTp vl, bool toSess = false ) — value of the attribute attr of the widget setting to vl, or to the session toSess. The object is returned for the function concatenation.
string link( string attr, bool prm = false ) — the link return for the widget's 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 ) — the link set for the widget's attribute attr. At set prm makes the link set for the attributes block (parameter), represented by the attribute.

//Set link for eight trend to the parameter
this.linkSet("el8.name", "prm:/LogicLev/experiment/Pi", true);

string mime( string addr, string type = "" ) — the "mime" object by the address addr (the direct link to the resource or the widget's attribute contained the link) getting with the type to type, from the session table or the source. It is designed for the "mime" objects edition and that substitution to this session's context, for example, images SVG.
int mimeSet( string addr, string data, string type = "" ) — the "mime" object data with type type by address addr setting.
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 ); — formation of the system message mess with the category as the widget path.

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

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

The deprecated API of the user programming of the visualization engine are represented by the group of functions directly in the engine module of the VCA. Calling of these functions from the scripts of widgets can be performed directly by the ID of the function, since their area of names is indicated for the context of the scripts of widgets.

Widget list (WdgList)
Description: Returns a list of widgets in the container of widgets or a list of child widgets. If pg is set it returns a list of pages for the projects and sessions.
Parameters:

ID	Name	Type	Mode	By default
list	List	String	Return
addr	Address	String	Input
pg	Pages	Bool	Input	0

Presence of the node (NodePresent)
Description: Check for the presence of the node, including widgets, attributes and others.
Parameters:

ID	Name	Type	Mode	By default
rez	Result	Bool	Return
addr	Address	String	Input

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

ID	Name	Type	Mode	By default
list	List	String	Return
addr	Address	String	Input
noUser	Without user	Bool	Input	1

Request of the attribute (AttrGet)
Description: Request of the value of the attribute of the widget. 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 ID of the attribute in the attr.
Parameters:

ID	Name	Type	Mode	By default
val	Value	String	Return
addr	Address	String	Input
attr	Attribute	Bool	Input

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

ID	Name	Type	Mode	By default
addr	Address	String	Input
val	Value	String	Input
attr	Attribute	Bool	Input

Session user (SesUser)
Description: Return the session user by the session's widget path.
Parameters:

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

Service interfaces of OpenSCADA

Service interfaces are interfaces of access to the OpenSCADA system by means of OpenSCADA control interface from external systems. This mechanism — is the basis of all the mechanisms for interaction within OpenSCADA, implemented through the weak ties, and standard exchange protocol of OpenSCADA.

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

In order to provide unitized, grouping and relatively fast access to the values of attributes of the visual elements the service function of the visual element "/serv/attr" and get/set commands of the attributes' values are provided: <get path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr"/> and <set path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr"/>.

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

Id	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>	The formation of the child elements with the results of the attributes	In the child element are specified: string ID attr of the attribute, index a_id of the attribute and its value val.
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 the ID of the attribute attr and its value val are specified.
Activation-creation command of specific for the visualizer attribute: <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

Group access to the values of the attributes of the visualization elements (widgets)

In order to optimize network traffic by eliminating the small queries, but use one, but a large the group query of the attributes' values of visual elements is made. Grouping of this query involves a request of attributes of the entire branch of the widget, including the embedded 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 ID attr of the attribute, index a_id of the attribute and its value val.
<w id="{wid}" lnkPath="{lnk_path}">{childs+attrs}</w> — elements with the child widgets and their attributes. The identifier of the child widget wid and the path to the widget on which the current widget links to, if its is the link lnk_path, are specified in the element.

Access to the pages of the session

In order to unify and optimize the access to the pages the service function of the session "/serv/pg" and commands of the query of the list of open pages <openlist path="/UI/VCAEngine/ses_{Session}/%2fserv%2fpg"/>; of opening the pages <open path="/UI/VCAEngine/ses_{Session}/%2fserv%2fpg"/>; and closing of the pages <close path="/UI/VCAEngine/ses_{Session}/%2fserv%2fpg"/> are provided.

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.

Signaling (alarm) management

To provide a mechanism for global control of the signaling of the session the service function of the session "/serv/alarm" and commands of the query of the signals status <get path="/UI/VCAEngine/ses_{Session}/%2fserv%2falarm"/>; and of the quittance <quittance path="/UI/VCAEngine/ses_{Session}/%2fserv%2falarm"/> are provided.

Request for the status of signals returns generalized condition of the signals, as well as additional a notification resource by attribute "mode" sets to "resource". The notification resource request result is typically a sound file, for playback, and at that time it performs monitoring of the sequence of signaling and quittance of individual the notification resources of the messages.

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

Manipulation with the sessions of the projects

To provide a unitize mechanism for manipulation of the sessions by the visualizers of VCA in the module of the VCA engine (VCAEngine) are provided the service function "/serv/sess" and the query commands of the list of open sessions, connection/creation of the new session and disconnection/deleting of the session: <list path="/UI/VCAEngine/%2fserv%2fsess"/>, <connect path="/UI/VCAEngine/%2fserv%2fsess"/> and <disconnect path="/UI/VCAEngine/%2fserv%2fsess"/> accordingly.

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

Id	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 open sessions.
<el>{Session}</el>	Control of the sessions' list	In the child element the open for the requested project sessions are specified.
The command of the connection/opening of the session: <connect path="/UI/VCAEngine/%2fserv%2fsess"/>
sess	Installation and control of the session name	If the attribute is defined, then connecting to an existing session is to be made, else — creation of the new session is to be made. In the case of opening of the new session in this attribute its name is is placed.
prj	Setting the name of the project	It is used to open a new session for indicated project and when the attribute sess is not specified.
The command of disconnection/closing of the session: <disconnect path="/UI/VCAEngine/%2fserv%2fsess"/>
sess	Setting the name of the session	Specify the name of the session from that it is made the disconnection or closing. Sessions, not the background, and to which none of the visualizers is not connected, are automatically closed.

Group request for the tree of widget 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 widget libraries: <get path="/UI/VCAEngine/%2fserv%2fwlbBr"/> are provided. The result of the query is a tree with the elements of the libraries of widgets, tags wlb. Inside the tags of libraries of widgets 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.

OpenSCADAWiki: Home Page En/Doc/VC Aconcept/part4/part14 ...