Documents/User API

Translate this page

Other languages:
Constr.png The translation checking and actualizing

Author: Roman Savochenko

Maxim Lysenko (2012) — the page translation

Contents

Before starting of programming into OpenSCADA you must learn a structure of objects of the program from the program manual of OpenSCADA. From the document you also will see that you can program next parts of OpenSCADA as the user:

User programming API is the tree of OpenSCADA objects, every object of which can provide own list of properties and functions. Properties and functions of the objects can be used by the user in procedures on the languages of user programming of OpenSCADA.

Currently OpenSCADA provides only one language of text programming that is JavaLikeCalc then you must learn it also before the starting! The entry point for access to the objects of OpenSCADA from user programming language JavaLikeCalc is the reserved word "SYS" of the root OpenSCADA object. For example, to access the function of outgoing transport you should write: SYS.Transport.Serial.out_ModBus.messIO(mess);.

API of the objects provided by the modules is described in the own documentation of the modules.

1 System-wide user objects

JavaLikeCalc provides the data type "Object" support. The data type "Object" is an associated container of properties and functions. The properties can support data of fourth basic types and other objects. The access to properties is doing through the dot to object obj.prop and also by property placement into the rectangle brackets obj["prop"]. It is obvious that the first mechanism is static, while the second lets you to specify the name of the property through a variable. Object's properties removing you can perform by the operator "delete". Reading of an undefined property will return EVAL. Creating an object is carried by the keyword new: varO = new Object(). The basic definition of the object does not contain functions. Copying of an object is actually makes the reference to the original object. When you delete an object is carried out the reducing of the reference count, and when a reference count is set to zero then object is removed physically.

Different components can define basic object with special properties and functions. The standard extension of the object is an array "Array", which is created by the command varO = new Array(prm1,prm2,prm3,...,prmN). Comma-separated parameters are placed in the array in the original order. If the parameter is the only one the array is initiated by the specified number of empty elements. Peculiarity of the array is that it works with the properties as the indexes and the main mechanism of addressing is placing the index into square brackets arr[1] is accessible. Array stores the properties in its own container of the one-dimensional array. Digital properties of the array are used to access directly to the array, and the characters work as object properties. For more details about the properties and functions of the array can be read here.

The object of regular expression "RegExp" is created by command varO = new RegExp(pat,flg), where pat — pattern of regular expression, and flg — match flags. The object for work with regular expressions, based on the library "PCRE". In the global search set object attribute "lastIndex", which allows you to continue searching for the next function call. In the case of an unsuccessful search for the attribute "lastIndex" reset to zero. For more details about the properties and functions of the regular expression object can be read here.

For random access to the arguments of the functions provided the arguments object, which you can refer to by the symbol "arguments". This object contains the property "length" with a number of arguments in functions and allows you to access to a value of the argument by its number or ID. Consider the enumeration of the arguments on the cycle:

args = new Array();
for(var i=0; i < arguments.length; i++)
  args[i] = arguments[i];

The basic types have the partial properties of the object. Properties and functions of the basic types are listed below:

Properties:
  • MAX_VALUE — maximum value;
  • MIN_VALUE — minimum value;
  • NaN — error value.
Functions:
  • bool isEVal(); — Check value to "EVAL".
  • string toExponential( int numbs = -1 ); — Return the string of the number, formatted in exponential notation, and with the number of significant digits numbs. If numbs is missing the number of digits will have as much as needed.
  • string toFixed( int numbs = 0, int len = 0, bool sign = false ); — Return the string of the number, formatted in the notation of fixed-point, and with the number of significant digits after the decimal point numbs for minimum length len and strong sign present sign. If numbs is missing the number of digits after the decimal point is equal to zero.
  • string toPrecision( int prec = -1 ); — Return the string of the formatted number with the number of significant digits prec.
  • string toString( int base = 10, int len = -1, bool sign = false ); — Return the string of the formatted number of integer type with the following representation base (2-36) for minimum length len and strong sign present sign.
Properties:
  • int length — string length.
Functions:
  • bool isEVal(); — Check value to "EVAL".
  • string charAt( int symb ); — Extracts from the string the symbol symb, numbering from zero.
  • int charCodeAt( int symb ); — Extracts from the string the symbol code symb.
  • string concat( string val1, string val2, ... ); — Returns a new string formed by joining the values val1 etc. to the original one.
  • int indexOf( string substr, int start ); — Returns the position of the required string substr in the original row from the position start. If the initial position is not specified then the search starts from the beginning. If the search string is not found then "-1" is returned.
  • int lastIndexOf( string substr, int start ); — Returns the position of the search string substr in the original one beginning from the position of start when searching from the end. If the initial position is not specified then the search begins from the end. If the search string is not found then "-1" is returned.
  • int search( string pat, string flg = "" ); — Search into the string by pattern pat and pattern's flags flg. Return found substring position or "-1" for else.
var rez = "Java123Script".search("script","i");  // rez = 7
  • int search( RegExp pat ); — Search into the string by "RegExp" pattern pat. Return found substring position or "-1" for else.
var rez = "Java123Script".search(new RegExp("script","i"));  // rez = 7
  • Array match( string pat, string flg = "" ); — Call match for the string by pattern pat and flags flg. Return matched substring (0) and subexpressions (>0) array. Set "index" attribute of the array to substring position. Set "input" attribute to source string.
var rez = "1 plus 2 plus 3".match("\\d+","g");  // rez = [1], [2], [3]
  • Array match( TRegExp pat ); — Call match for the string and "RegExp" pattern pat. Return matched substring (0) and subexpressions (>0) array. Set "index" attribute of the array to substring position. Set "input" attribute to source string.
var rez = "1 plus 2 plus 3".match(new RegExp("\\d+","g"));  // rez = [1], [2], [3]
  • string slice( int beg, int end ); string substring( int beg, int end ); — Return the string extracted from the original one starting from the beg position and ending before the end (not included), numbering from zero. If the beginning or end is negative, then the count is conducted from the end of the line. If the end is not specified, then the end is the end of the line. For example, the construction substring(-2) return two last symbols of the string.
  • Array split( string sep, int limit ); — Return the array of strings separated by sep with the limit of the number of elements limit.
  • Array split( RegExp pat, int limit ); — Return the array of strings separated by RegExp pattern pat with the limit of the number of elements limit.
rez = "1,2, 3 , 4 ,5".split(new RegExp("\\s*,\\s*"));  // rez = [1], [2], [3], [4], [5]
  • string insert( int pos, string substr ); — Insert substring substr into this string's position pos.
  • string replace( int pos, int n, string str ); — Replace substring into position pos and length n to string str.
rez = "Javascript".replace(4,3,"67");  // rez = "Java67ipt"
  • string replace( string substr, string str ); — Replace all substrings "substr" to string "str".
rez = "123 321".replace("3","55");  // rez = "1255 5521"
  • string replace( RegExp pat, string str ); — Replace substrings by pattern pat to string str.
rez = "value = \"123\"".replace(new RegExp("\"([^\"]*)\"","g"),"``$1''"));  // rez = "value = ``123''"
  • real toReal(); — Convert this string to real number.
  • int toInt( int base = 0 ); — Convert this string to integer number in accordance with the base base (from 2 to 36). If base is 0, then the prefix will be considered a record for determining the base (123-decimal; 0123-octal; 0x123-hex).
  • string parse( int pos, string sep = ".", int off = 0 ); — Get token with number pos from the string when separated by sep and from offset off. Result offset is returned back to off.
  • string parseLine( int pos, int off = 0 ); — Get line number pos from the string and from offset off. Result offset is returned back to off.
  • string parsePath( int pos, int off = 0 ); — Get path token with number pos from the string and from offset off. Result offset is returned back to off.
  • string path2sep( string sep = "." ); — Convert path into this string to separated by sep string.
  • string trim( string cfg = " \n\t\r" ); — String trimming at begin and end for symbols cfg.


1.1 Array object

Peculiarity of the array is that it works with the properties like with the indexes, and complete their naming if senseless, and hence the mechanism of addressing is available only by the conclusion of the index in square brackets "arr[1]". Array stores the properties in its own container of one-dimensional array. Digital properties of the array are used to access directly to the array, and the characters work as object properties.

Array provides the special property "length" to get the array size "var = arr.length;". Also array provides the following functions:

1.2 RegExp object

Object for work with regular expressions, based on the library PCRE. In the global search set object attribute "lastIndex", which allows you to continue searching for the next function call. In the case of an unsuccessful search for the attribute "lastIndex" reset to zero.

As arguments passed to create the object put string with the text of regular expression and flags as a string of characters:

Object's properties:

Object's functions:

1.3 XMLNodeObj object

Functions:

0x01 — full loading, with texts and comments blocks into special nodes;
0x02 — no remove spaces for begin and end tag's text.
0x01 — interrupt the string before the opening tag;
0x02 — interrupt the string after the opening tag;
0x04 — interrupt the string after a closing tag;
0x08 — interrupt the string after the text;
0x10 — interrupt the string after the instruction;
0x1E — interrupt the string after all;
0x20 — insert standard XML-header;
0x40 — insert standard XHTML-header;
0x80 — clean service tags: <??>, <!-- -->;
0x100 — miss for tag's name encoding;
0x200 — miss for attribute's name encoding.

2 System (SYS)

Object functions:

3 Any object (TCntrNode) of OpenSCADA objects tree (SYS.*)

Object functions:

4 Subsystem "Security" (SYS.Security)

The subsystem object's functions (SYS.Security):

user — user for access check;
mode — access mode (4-R, 2-W, 1-X);
owner — resource owner;
group — resource group;
access — resource access mode (RWXRWXRWX — 0777).

The user (SYS.Security["usr_User"]) object's functions:

The group (SYS.Security["grp_Group"]) object's functions:

5 Subsystem "DB" (SYS.BD)

DB object functions (SYS.BD["TypeDB"]["DB"]):

Table object functions (SYS.BD["TypeDB"]["DB"]["Table"]):

6 Subsystem "DAQ" (SYS.DAQ)

Functions of subsystem's object (SYS.DAQ):

Functions of object of controller (SYS.DAQ["Modul"]["Controller"]):

Functions of object of controller's parameter (SYS.DAQ["Modul"]["Controller"]["Parameter"]):

Functions of object of atribute of controller's parameter (SYS.DAQ["Modul"]["Controller"]["Parameter"]["Attribute"]):

Functions of object of templates library (SYS.DAQ[tmplb_Lib"]) and template (SYS.DAQ[tmplb_Lib"]["Tmpl"]) of controller's parameter:

6.1 Module DAQ.JavaLikeCalc

The object "Functions library" (SYS.DAQ.JavaLikeCalc["lib_Lfunc"])

The object "User function" ( SYS.DAQ.JavaLikeCalc["lib_Lfunc"]["func"] )

6.2 Module DAQ.LogicLev

The object "Parameter" [this]

6.3 Module DAQ.BlockCalc

The object "Block" (SYS.DAQ.BlockCalc["cntr"]["blk_block"])

6.4 Module DAQ.ModBus

The object "Controller" [this.cntr()]

The object "Parameter" [this]


7 Subsystem "Archives" (SYS.Archive)

Functions of the subsystem's object:

Functions of object's archiver of messages (SYS.Archive["mod_Modul"]["mess_Archivator"]):

Functions of object's archiver of values (SYS.Archive["val_Modul"]["val_Archivator"]):

Functions of object's archive (SYS.Archive["va_Archive"]):

8 Subsystem "Transports" (SYS.Transport)

Functions of the ingoing transport object (SYS.Transport["Modul"]["in_Transp"]):

Functions of the outgoing transport object (SYS.Transport["Modul"]["out_Transp"]):

9 Subsystem "Protocols" (SYS.Protocols)

9.1 Module Protocol.HTTP

The same module's object "Protocol.HTTP" [SYS.Protocol.HTTP.pgCreator()]


10 Subsystem "User interfaces" (SYS.UI)

10.1 Module UI.VCAEngine

Object "Session" ( this.ownerSess() )

Object "Widget" (this)

//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);
//Set link for eight trend to the parameter
this.linkSet("el8.name", "prm:/LogicLev/experiment/Pi", true);

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


11 "Special" subsystem (SYS.Special)

11.1 Module Library of the system API of the user programming area (Special.FLibSYS)

The object "Functions library" (SYS.Special.FLibMath)

The object "User function" (SYS.Special.FLibMath["funcID"])

11.2 Module Library of standard mathematical functions (Special.FLibMath)

The object "Functions library" (SYS.Special.FLibMath)

The object "User function" (SYS.Special.FLibMath["funcID"])

11.3 Module Library of functions of compatibility with SCADA Complex1 of the firm DIYA Ltd (Special.FLibComplex1)

The object "Functions library" (SYS.Special.FLibComplex1)

The object "User function" (SYS.Special.FLibComplex1["funcID"])


At.png Link to DB API libraries ...