Documents/User API

Other languages:
English • ‎российский • ‎українська

Author: Roman Savochenko

Maxim Lysenko (2012) — the page translation

Contents

Before programming in OpenSCADA, you must examine the object structure of the program (Object Model) in OpenSCADA Program Manual and in Figure 1.

Fig. 1. User object model of the core OpenSCADA.

From the document you will see that you can program next parts of OpenSCADA as the user:

User programming API is the tree of the OpenSCADA objects (Fig.1), 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 the user programming of OpenSCADA.

Currently OpenSCADA provides only one language of the text programming — JavaLikeCalc then you must learn it also before the starting! The entry point for access to the objects of OpenSCADA (Fig.1) from the user programming language JavaLikeCalc is the reserved word "SYS" of the root OpenSCADA object. For example, to access the function of output 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 and here links to their are provided.

1 The user programming language JavaLikeCalc

1.1 Elements of the language

Keywords: if, else, while, for, break, continue, return, function, using, true, false.
Constants:

Types of variables:

Built-in constants: pi = 3.14159265..., e = 2.71828182..., EVAL_BOOL(2), EVAL_INT(-9223372036854775807), EVAL_REAL,EVAL(-1.79E308), EVAL_STR("<EVAL>")
Global attributes of the DAQ parameter (starting from the subsystem "DAQ", as follows {Type of DAQ module}.{Controller}.{Parameter}.{Attribute}).
The functions and parameters of the object model of OpenSCADA.

1.2 Operations of the language

The operations supported by the language are presented in the table below. Priority of the operations is reduced from top to bottom. Operations with the same priority are in the same color group.

SymbolDescription
()Call of function.
{}Program blocks.
++Increment (post and pre).
--Decrement (post and pre).
-Unary minus.
!Logical negation.
~Bitwise negation.
*Multiplication.
/Division.
%Remainder of integer division.
+Addition
-Subtraction
<<Bitwise shift left
>>Bitwise shift right
>Greater
>=Greater than or equal to
<Less
<=Less than or equal to
==Equals
!=Unequal
|Bitwise "OR"
&Bitwise "AND"
^Bitwise "Exclusive OR"
&&Boolean "AND"
||Boolean "OR"
?:Conditional operation "i=(i<0)?0:i;"
=Assignment.
+=Assignment with addition.
-=Assignment with subtraction.
*=Assignment with multiplication.
/=Assignment with division.

1.3 Embedded functions of the language

The virtual machine of the language provides the following set of built-in functions general-purpose:

To provide high speed work in mathematical calculations, the module provides built-in mathematical functions that are called at the level of the commands of the virtual machine:

1.4 Operators of the language

The total list of the operators of the language:

1.4.1 Conditional operators

The language supports two types of conditions. First — this is the operation of condition for use within the expression, second — a global, based on the conditional operators.

The condition inside an expression is based on the operations '?' and ':'. As an example we'll write the following practical expression st_open = (pos>=100) ? 

true : false;, which reads as: "If the variable pos greater than or equal to 100, the variable st_open is set to true, otherwise — to false".

The global condition is based on the conditional operators "if" and "else". As an example, we can show the same expression, but recorded in another way if(pos>100) st_open = true; else st_open = false;.

1.4.2 Loops

Two types of the loops are supported: while, for and for-in. The syntax of the loops corresponds to the programming languages: C++, Java and JavaScript.

Loop while is written generally as follows: while({condition}) {body of the loop};
Loop for is written as follows: for({pre-initialization};{condition};{post-calculation}) {body of the loop};
Loop for-in is written as follows: for({variable} in {object}) {body of the loop};
Where:

{condition} — expression, determining the condition;
{body of the loop} — the body of the loop of multiple execution;
{pre-initialization} — expression of pre-initialization of variables of the loop;
{post-calculation} — expression of modification of parameters of the loop after next iteration;
{variable} — variable, which will contain object's properties name at scan;
{object} — object for which the properties are scanned.

1.4.3 Internal functions

The language supports definition and call of internal functions. To determine the internal function, the keyword "function" is used and in general, the definition has a syntax: function {fName} ({var1}, {var2}, ... {varN}) { {the function body} }. Defining an internal function inside another is not allowed but it is allowed to call a previously defined one.

Calling an internal function is done in a typical way as a procedure {fName}({var1}, {var2}, ... {varN}); or as a function {vRez} = {fName}({var1}, {var2}, ... {varN});. The call of internal functions is valid only after their declaration is higher!

All defined variables into the main body inaccessible into the internal function and can be pass in only as two way arguments of the internal function call. All defined variables into the internal function have itself namespace and inaccessible from the main body or any other internal function and can be pass out to the main body only as two way arguments or return of the internal function call. Since the definition of variables-registers in this language is static and takes place during compilation, they are in fact the same for each function call, and therefore their recursive calling does not make sense here!

Operator "return" into the internal function makes controllable finishing of the function execution and places a pointed variable or an expression result as the internal function call result.

An example of the internal function declaration and using in typical way shown bottom: 

function sum(a, b, c, d) { return a + ((b==EVAL)?0:b) + ((c==EVAL)?0:c) + ((d==EVAL)?0:d); }
rez = sum(1, 2);

1.4.4 Special characters of the string variables

The language supports the following special characters of the string variables:

"\n" — line feed;
"\t" — tabulation symbol;
"\b" — culling;
"\f" — page feed;
"\r" — carriage return;
"\\" — the character itself '\'.
"\041" — the '!' character, written in an octal number;
"\x21" — the '!' character, written in a hex number.


2 System-wide user objects

JavaLikeCalc provides support of the data type "Object". The data type "Object" is an associated container of properties and functions. The properties can support data of fourth basic types and other objects. Access to object properties can be done through the record of property names to the object obj.prop, through a dot, and also through the inclusion of the property name in square 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. The name of the property through the dot must not start with a digit and contain operations symbols; otherwise, for the first digit, the object prefix should be used — SYS.BD.SQLite.db_1s, or write in square brackets — SYS.BD.SQLite["1+s"], for operations symbols in the name. 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 the count is set to zero then the object is removed physically.

Different components of OpenSCADA can define the 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 the 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 the 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 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 the function 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:

  • real toReal(); — reads this Boolean as a real number.
  • int toInt(); — reads this Boolean as an integer number.
Properties:
  • MAX_VALUE — maximum value;
  • MIN_VALUE — minimum value;
  • NaN — error value.
Functions:
  • bool isEVal(); — checks value to "EVAL".
  • string toExponential( int numbs = -1 ); — returns the string of the number, formatted in the 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 ); — returns 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 compulsion to the presence of a sign. If numbs is missing, the number of digits after the decimal point is equal to zero.
  • string toPrecision( int prec = -1 ); — returns the string of the number, formatted with the number of significant digits prec.
  • string toString( int base = 10, int len = -1, bool sign = false ); — returns the string of the number of the integer type, formatted with the following representation base (2-36), for minimum length len and compulsion to the presence of a sign.
  • real toReal(); — reads this integer-real as a real number.
  • int toInt(); — reads this integer-real as an integer number.
Properties:
  • int length — string length.
Functions:
  • bool isEVal(); — checks 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 = "" ); — searches into the string by the pattern pat and pattern's flags flg. Returns found substring position or "-1" for else.
var rez = "Java123Script".search("script","i");  // rez = 7
  • int search( RegExp pat ); — searches into the string by the "RegExp" pattern pat. Returns found substring position or "-1" for else.
var rez = "Java123Script".search(new RegExp("script","i"));  // rez = 7
  • Array match( string pat, string flg = "" ); — calls match for the string by the pattern pat and flags flg. Returns matched substring (0) and subexpressions (>0) array. Sets "index" attribute of the array to the substring position. Sets the "input" attribute to the source string. Sets the "err" attribute to the operation error code.
var rez = "1 plus 2 plus 3".match("\\d+","g");  // rez = [1], [2], [3]
  • Array match( TRegExp pat ); — calls match for the string and "RegExp" pattern pat. Returns matched substring (0) and subexpressions (>0) array. Sets the "index" attribute of the array to substring position. Sets the "input" attribute to the source string. Sets the "err" attribute to the operation error code.
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 ); — returns the string extracted from the original one starting from the beg position and ending before the end (not included), numbering from zero. If the begin 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 ); — returns the array of strings separated by sep with the limit of the number of elements.
  • Array split( RegExp pat, int limit ); — returns the array of strings separated by the RegExp pattern pat with the limit of the number of elements.
rez = "1,2, 3 , 4 ,5".split(new RegExp("\\s*,\\s*"));  // rez = [1], [2], [3], [4], [5]
  • string insert( int pos, string substr ); — inserts the substring substr into this string's position pos.
  • string replace( int pos, int n, string str ); — replaces substring into the position pos and length n to the string str.
rez = "Javascript".replace(4,3,"67");  // rez = "Java67ipt"
  • string replace( string substr, string str ); — replaces all the substrings substr to the string str.
rez = "123 321".replace("3","55");  // rez = "1255 5521"
  • string replace( RegExp pat, string str ); — replaces substrings by the pattern pat to the string str.
rez = "value = \"123\"".replace(new RegExp("\"([^\"]*)\"","g"),"``$1''"));  // rez = "value = ``123''"
  • real toReal(); — converts this string to a real number.
  • int toInt( int base = 0 ); — converts this string to an integer number in accordance with base (from 2 to 36). If the base is 0, then the prefix will be considered a prefix for determining the base (123-decimal; 0123-octal; 0x123-hex).
  • string parse( int pos, string sep = ".", int off = 0 ); — gets a token with the number pos from the string when separated by sep and from the offset off. Result offset is returned back to off.
  • string parseLine( int pos, int off = 0 ); — gets a line with the number pos from the string and from the offset off. Result offset is returned back to off.
  • string parsePath( int pos, int off = 0 ); — gets a path token with the number pos from the string and from the offset off. Result offset is returned back to off.
  • string path2sep( string sep = "." ); — converts path into this string to separated by sep string.
  • string trim( string cfg = " \n\t\r" ); — trims the string at the begin and the end for the symbols cfg.


2.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 character ones work as the object properties.

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

2.2 RegExp object

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

As arguments for creating the object, a string with regular expression text and a flags box in the form of a character string is passed:

Object properties:

Object functions:

2.3 XML node-tag object (XMLNodeObj)

Functions:

0x01 — full loading, with texts and comments blocks into special nodes;
0x02 — does not remove spaces from the begin and end of the tag text.
0x01 — end line before the opening tag;
0x02 — end line after the opening tag;
0x04 — end line after the closing tag;
0x08 — end line after the text;
0x10 — end line after the instruction;
0x1E — end line after all ones;
0x20 — inserts the standard XML-header;
0x40 — inserts the standard XHTML-header;
0x80 — cleans the service tags: <??>, <!-- -->;
0x100 — does not encode the tag name;
0x200 — does not encode the attribute.

3 Program-system (SYS)

Object functions:

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

Object functions:

5 Subsystem "Security" (SYS.Security)

Functions of the subsystem object (SYS.Security):

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

Functions of the object "User" (SYS.Security["usr_{User}"]):

Functions of the object "Users group" (SYS.Security["grp_{Group}"]):

6 Subsystem "DB" (SYS.BD)

Functions of the database object (SYS.BD["TypeDB"]["DB"]):

Functions of the table object (SYS.BD["TypeDB"]["DB"]["Table"]):

7 Subsystem "DAQ" (SYS.DAQ)

Functions of the subsystem object (SYS.DAQ):

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

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

Functions of the attribute object of the parameter of the controller (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:

7.1 Module DAQ.JavaLikeCalc

User object model of the module JavaLikeCalc.

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

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

7.2 Module DAQ.LogicLev

The object "Parameter" [this]

7.3 Module DAQ.BlockCalc

User object model of the module BlockCalc.

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

7.4 Module DAQ.ModBus

User object model of the module ModBus.

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

The object "Parameter" [this]


8 Subsystem "Archives-History" (SYS.Archive)

Functions of the subsystem 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"]):

9 Subsystem "Transports" (SYS.Transport)

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

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

10 Subsystem "Protocols" (SYS.Protocols)

10.1 Module Protocol.HTTP

The module object (SYS.Protocol.HTTP)


11 Subsystem "User interfaces" (SYS.UI)

11.1 Module QTStarter

The module object (SYS.UI.QTStarter)

11.2 Module UI.VCAEngine

User object model of the module VCAEngine.

Object "Session" ( this.ownerSess() )

Object "Widget" (this) 

//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);

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

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


12 "Special" subsystem (SYS.Special)

12.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"])

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

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

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

12.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"])


13 Libraries of the user functions

Currently, OpenSCADA has libraries of the user functions written using this API user. Some of them are designed for exclusive use with this API. All user libraries are presented in the following table:

Name Version License Source Languages
Main user protocol based library 1.8 Free (GPL2 by default) DB SQLite: File:OscadaLibs.db.gz, Most actual SQL en, uk, ru
Controllers library 1.1 Free (GPL) DB SQLite: File:OscadaLibs.db.gz, Most actual SQL en
Service procedures library 1.0 Free (GPL) DB SQLite: File:OscadaLibs.db.gz, Most actual SQL en
Regulation elements library 1.0 Free (GPL) DB SQLite: File:OscadaLibs.db.gz, Most actual SQL en
Library of preparation and data acquisition for reporting 1.0 Free (GPL) DB SQLite: File:OscadaLibs.db.gz, Most actual SQL en
Library of models of technological apparatuses 1.0 Free (GPL) DB SQLite: File:OscadaLibs.db.gz, Most actual SQL en
Graphic elements' libraries of OpenSCADA module UI.VCAEngine
Library of the electrical elements of the user's interface mnemonic schemes 0.2 Free (GPL) DB SQLite: File:VcaElectroEls.db.gz, Most actual SQL en, uk, ru
Main elements library of the user interface 1.1 Free (GPL) DB SQLite: File:VcaBase.db.gz, Most actual SQL en, uk, ru
Mnemonic elements library of the user interface 0.5 Free (GPL) DB SQLite: File:VcaBase.db.gz, Most actual SQL en, uk, ru


14 Links