Documents/User API

• Author: Roman Savochenko
    Maxim Lysenko (2012) — the page initial translation
• Initially created: in the old Wiki

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

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

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

• Logical level sources of the subsystem "DAQ".
• Transport protocols allowed for user programming that is: User protocol, ModBus nodes of the type "Data", Web-interfaces from the user, ...
• Visual Control Area (VCA) in procedures of the widgets.

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, in, break, continue, return, function, using.
Constants:

• decimal: digits 0-9 (12, 111, 678);
• octal: digits 0-7 (012, 011, 076);
• hexadecimal: digits 0-9, letters a-f or A-F (0x12, 0XAB);
• real: 345.23, 2.1e5, 3.4E-5, 3e6;
• boolean: true, false;
• string: "hello", without going to the next line, however, with the support of direct concatenation of the string constants.

Types of variables:

• integer: -2⁶³ ... 2⁶³, EVAL_INT(-9223372036854775807);
• real: 3.4*10³⁰⁸, EVAL_REAL(-1.79E308);
• Boolean: false, true, EVAL_BOOL(2);
• string: a sequence of character-bytes (0...255) of any length, limited by the capacity of the memory and DB storage; EVAL_STR("<EVAL>").

Built-in constants: pi = 3.14159265..., e = 2.71828182..., EVAL_BOOL(2), EVAL_INT(-9223372036854775807), null,EVAL,EVAL_REAL(-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.

The EVAL (Error VALue) variants and null are processed specially in conversion one to one depending on used the base type, that is you are free in use only null or EVAL for any cases.

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.

Symbol	Description
()	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:

• double max(double x, double x1) — maximum value of x and x1;
• double min(double x, double x1) — minimum value of x and x1;
• string typeof(ElTp vl) — type of the value vl;
• string tr(string base) — translation to the base message.

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:

• double sin(double x) — sine x;
• double cos(double x) — cosine x;
• double tan(double x) — tangent x;
• double sinh(double x) — hyperbolic sine of x;
• double cosh(double x) — hyperbolic cosine of x;
• double tanh(double x) — hyperbolic tangent of x;
• double asin(double x) — arcsine of x;
• double acos(double x) — arc cosine of x;
• double atan(double x) — arctangent of x;
• double rand(double x) — random number from 0 to x;
• double lg(double x) — decimal logarithm of x;
• double ln(double x) — natural logarithm of x;
• double exp(double x) — exponent of x;
• double pow(double x, double x1) — erection of x to the power x1;
• double sqrt(double x) — the square root of x;
• double abs(double x) — absolute value of x;
• double sign(double x) — sign of x;
• double ceil(double x) — rounding the number x to a greater integer;
• double floor(double x) — rounding the number x to a smaller integer.

1.4 Operators of the language

The total list of the operators of the language:

• var — operator of initialization of a variable; specifying a variable without assigning a value sets it to null-EVAL, which allows for one-time initialization of complex data types, such as an object, through the direct comparing and checking by isEVal();
• if — operator "IF" of the condition;
• else — operator "ELSE" of the condition;
• while — definition of the "WHILE" loop;
• for — definition of the "FOR" loop;
• in — separator of the "FOR" cycle for object's properties scan;
• break — interruption of the cycle;
• continue — continue the cycle from the beginning;
• function — definition of the internal function;
• using — allows you to set the visibility space of the external functions of the often used libraries (using Special.FLibSYS;) for the next access only by the name of the function, has no effect for object access;
• return — interrupt function and return the result that is copied to an attribute marked as return one (return 123;); in the middle of the internal function it is completed with a definite result;
• new — creating an object, implemented for: the generic object "Object", massif "Array" and regular expressions "RegExp".
• delete — delete/free of an object or its properties, while: internal variables are set in null-EVAL, external ones are replaced by an empty object, and the properties of the object are cleared.

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 as two way arguments of the internal function call or as the main function arguments. 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 as two way arguments, return of the internal function call or the main function arguments. The internal function variables are registered for saving/restoring their context after second and more entry to the function, so they completely support the recursive calls!

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 next:

function sum(a, b, c, d) { return a + ((b==null)?0:b) + ((c==null)?0:c) + ((d==null)?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 null-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 function arguments 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:

• NULL type, functions:
  • bool isEVal(); — returns "true".

• Logical type, functions:
  • bool isEVal(); bool isNaN( ); — checks the value to null-EVAL.
  • string toString(); — performs the value as the string "true" or "false".

• real toReal(); — reads this Boolean as a real number.
• int toInt(); — reads this Boolean as an integer number.

• Integer and real number:

Properties:

• MAX_VALUE — maximum value;
• MIN_VALUE — minimum value;
• NaN — error value.

Functions:

• bool isEVal(); bool isNaN( ); — checks the value to null-EVAL, and NaN for Real.
• 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.

• String:

Properties:

• int length — string length.

Functions:

• bool isEVal(); — checks value to null-EVAL.
• bool isNaN( bool whole = true ); — checks the string to Not A Number and in whole for whole.
• string charAt( int symb, string type = "" ); — extracts from the string the symbol symb for the type. These types of the symbol are supported: ""-ASCII and raw one byte code, UTF-8, UTF-16, UTF-32. In the case of UTF-8, the symbol position symb is changed to the next symbol position due to length of this symbols type is variable one.
• int charCodeAt( int symb, string type = "" ); — extracts from the string the symbol code symb for the type. These types of the symbol are supported: ""-ASCII and raw one byte code, UTF-8, UTF-16, UTF-16LE, UTF-16BE, UTF-32, UTF-32LE, UTF-32BE. In the case of UTF-8, the symbol position symb is changed to the next symbol position due to length of this symbols type is variable one.
• 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 = 0 ); — 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 = {end} ); — 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 = 0 ); — returns the array of strings separated by sep with the limit of the number of elements (0 for no limit).
• Array split( RegExp pat, int limit = 0 ); — returns the array of strings separated by the RegExp pattern pat with the limit of the number of elements (0 for no limit).

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,parseEnd}( int pos, string sep = ".", int off = {0,{length}}, bool mergeSepSymb = false ); — gets a token with the number pos from the string when separated by sep and from the offset off (stopping on the next token begin, end for parseEnd). mergeSepSymb specifies of allowing of merging of the group of identical symbols to one separator. Result offset is returned back to off. parseEnd() does the same but from the end.
• 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 (stopping on the next token begin).
• string parsePath( int pos, int offCmptbl = 0, int off = 0 ); — gets a path token with the number pos from the string and from the offset off (stopping on the next token begin) or offCmtbl (stopping on next symbol of the current token end — for compatibility). Result offset is returned back to off or offCmptbl.
• string parsePathEnd( int pos, int off = {length} ); — gets a path token with the number pos from the string end and from the offset off (stopping on the next token end). 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:

• string join( string sep = "," ), string toString( string sep = "," ), string valueOf( string sep = "," ) — returns the string with the array elements separated by sep or the character ','.
• Array concat( Array arr ); — adds to the initial array the elements of the arr array. Returns the initial array with changes.
• int push( ElTp var, ... ); — places the element(s) var to the end of the array, as to the stack. Returns the new array size.
• ElTp pop( ); — deletes of the last element of the array and returns of its value, as from the stack.
• Array reverse( ); — changes the order of the elements of the array. Returns the initial array with the changes.
• ElTp shift( ); — shifts of the array to the top. The first element is removed and its value is returned.
• int unshift( ElTp var, ... ); — shifts element(s) var to the array. The first element to the 0, second to the 1 and so on.
• Array slice( int beg, int end ); — returns an array fragment from beg to end (exclude). If the value of beginning or end is negative, then the count is made from the end of the array. If the end is not specified, then the end is the end of the array.
• Array splice( int beg, int remN, ElTp val1, ElTp val2, ... ); — inserts, deletes or replaces the elements of the array. Returns the removed elements array. Firstly it is made the removing of elements from the position beg and in the quantity of remN, and then the values val1 are inserted and so on, beginning from the position beg.
• int indexOf( ElTp var, int start = 0 ); — returns the array index of the required variable var 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 variable is not found then "-1" is returned.
• int lastIndexOf( ElTp var, int start = {end} ); — returns the array index of the required variable var in the original row from the position start when searching from the end. If the initial position is not specified then the search begins from the end. If the search variable is not found then "-1" is returned.
• double sum(int beg, int end); — sum of the array values part from the position beg to end, excluding.
• Array sort( ); — sorts array elements in the lexicographical order.

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:

• 'g' — global match mode;
• 'i' — case insensitive match mode;
• 'm' — multi-line match mode;
• 'u' — compulsion for UTF-8 characters resolution, for other locales;
• 'p' — testing the expression by the usual template rule with the key characters: '?', '*' and '\'.

Object properties:

• source — original pattern of the regular expression, read-only.
• global — flag of the global matching, read-only.
• ignoreCase — flag of disabling of the case sensitivity, read-only.
• multiline — flag of the multiline searching, read-only.
• UTF8 — flag of using UTF-8 characters, read-only.
• lastIndex — index of a character of the substring from the last search. Used in the global mode to continue the match, at next call.

Object functions:

• Array exec( string val ); — calls match for string val. Returns found sub-string (0) and sub-expressions (>0) in the array. Sets attribute "index" of the array to the matched substring position. Sets the attribute "input" of the array to the source string.

  var re = new RegExp("(\\d\\d)[-/](\\d\\d)[-/](\\d\\d(?:\\d\\d)?)","");
  var rez = re.exec("12/30/1969");
  var month = rez[1];
  var day = rez[2];
  var year = rez[3];
  

• bool test( string val ); — returns "true" for the match sub-string in val.

  var re = new RegExp("(\\d\\d)[-/](\\d\\d)[-/](\\d\\d(?:\\d\\d)?)","");
  var OK = re.test("12/30/1969");
  

2.3 XML node-tag object (XMLNodeObj)

Functions:

• string name( ) — the name of the node, XML-tag.
• string text( bool full = false ) — the text of the node, contents of the XML-tag. Set full for get the combined text of all included nodes.
• string attr( string id ) — the value of the node attribute id.
• XMLNodeObj setName( string vl ) — sets of the node name to vl. Returns the current node.
• XMLNodeObj setText( string vl ) — sets of the node text to vl. Returns the current node.
• XMLNodeObj setAttr( string id, string vl ) — sets the attribute id to the value vl. Returns the current node.
• XMLNodeObj clear( bool full = false ) — clears the node for the childs, removes the text and attributes for full.
• int childSize( ) — quantity of the included nodes.
• XMLNodeObj childAdd( ElTp no = XMLNodeObj ); XMLNodeObj childAdd( string no ) — addition of the object no as the included one. no may be the direct object-result of the function "SYS.XMLNode()", and the string with the name of a new tag. Returns the included node.
• XMLNodeObj childIns( int id, ElTp no = XMLNodeObj ); XMLNodeObj childIns( int id, string no ) — insert of the object no as the included one to the position id. no may be the direct object-result of the function "SYS.XMLNode()", and the string with the name of a new tag. Returns the embedded node.
• XMLNodeObj childDel( int id ) — deletes the included node from the position id. Returns current node.
• XMLNodeObj childGet( int id ) — gets the included node in the position id. Returns 0 at missing one.
• XMLNodeObj childGet( string name, int num = 0 ) — gets the included node with the tag name and the position number num. Returns 0 at missing one.
• XMLNodeObj parent( ) — gets the parent node. Returns false at missing one.
• string load( string str, bool file = false, int flg = 0, string cp = "UTF-8" ) — loads the XML from the string str or from the file with the path in str if the file equal "true", with the source encoding cp. Returns a string with error in the format "{errCod}:{errText}", which is "0" for successful loading. Where flg — loading flags:

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.

• string save( int flg = 0, string path = "", string cp = "UTF-8" ) — saves the XML tree to the string or to the file path with the formatting flags flg and target encoding cp. Returns the XML text or the error code. The following formatting options flg are provided:

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;

0x400 — shield the binary symbols [\x0-\x8\xB-\xC\x0E-\x1F] and wrong UTF-8.

• XMLNodeObj getElementBy( string val, string attr = "id" ) — gets an element from the tree by the attribute attr in value val.
• TArrayObj<XMLNodeObj> getElementsBy( string tag, string attrVal = "", string attr = "id", int limit = 0, int from = 0 ) — gets an elements array from the tree by the tag (empty for all) and attribute attr in value attrVal (empty for pass), also starting the tag number from and limiting them number in limit (zero for no limit).

3 Program-system (SYS)

Object functions:

• {string|int} system( string cmd, bool noPipe = false ); — calls the console commands cmd of the OS returning the result by the channel. If noPipe is set then the callback code is returned and program can be started in the background ("sleep 5 &"). The function provides OpenSCADA with a wide range of capabilities by calling any system programs, utilities, and scripts, as well as by providing them with access to a huge amount of system data. For example the command "ls-l" returns the detailed content of the working directory.
• int fileSize( string file ); — returns the file size.
• string fileRead( string file, int off = 0, int sz = -1 ); — returns a string of part of the file for the offset off and the block size sz.
• int fileWrite( string file, string str, bool append = false ); — writes the string str to the file, removes presented one, at append. Returns the wrote bytes count.
• int fileRemove( string file ); — removes the file. Returns the removing result.
• int message( string cat, int level, string mess ); — forms of the system message mess with the category cat, level level (-7...7). The negative value of the level forms the alarms.
• int messDebug( string cat, string mess ); int messInfo( string cat, string mess ); int messNote( string cat, string mess ); int messWarning( string cat, string mess ); int messErr( string cat, string mess ); int messCrit( string cat, string mess ); int messAlert( string cat, string mess ); int messEmerg( string cat, string mess ); — forms of the system message mess with the category cat and the appropriate level by the name.
• XMLNodeObj XMLNode( string name = "" ); — creates of the XML node object with the name.
• string cntrReq( XMLNodeObj req, string stat = "" ); — sends a request req in XML view to the Control Interface of the program. Returns a string with error in the format "{errCod}:{errText}", which is "0" for successful. A request is generally written in the form <get path="/OPath/%2felem" /> and with additional attributes specific to the particular request. If the station stat is specified into the request then the request will be sent to this external station. The address for the attribute "path" you can obtain into the OpenSCADA configurator, that is into the status line where the address appear at the mouse cursor point to a field of configuration or information. Some examples of common requests, more examples in description the Control Interface and releaseTests():
  • Reading a value of the element (the user name "test"):

    req = SYS.XMLNode("get").setAttr("path","/sub_Security/usr_test/%2fprm%2fDESCR");
    SYS.cntrReq(req);
    idSt = req.text();
    

  • Writing a value to the element (the user name "test"):

    req = SYS.XMLNode("set").setAttr("path","/sub_Security/usr_test/%2fprm%2fDESCR").setText("New test user name");
    SYS.cntrReq(req);
    

  • Adding a new node (the user "test"):

    req = SYS.XMLNode("add").setAttr("path","/sub_Security/%2fbr%2fusr_").setText("test");
    SYS.cntrReq(req);
    

  • Deleting a node (the user "test"):

    req = SYS.XMLNode("del").setAttr("path","/sub_Security/%2fbr%2fusr_").setText("test");
    SYS.cntrReq(req);
    

  • Saving the node changes to DB (the user "test"):

    req = SYS.XMLNode("save").setAttr("path","/sub_Security/usr_test/%2fobj");
    SYS.cntrReq(req);
    

  • Loading the node from DB (the user "test"):

    req = SYS.XMLNode("load").setAttr("path","/sub_Security/usr_test/%2fobj");
    SYS.cntrReq(req);
    

• string lang(string full); — returns the system language in two symbols and the full language in full.
• int sleep( real tm, int ntm = 0 ); — puts the execution thread to sleep on the tm seconds (precised up to nanoseconds) and ntm nanoseconds. The sleeping time you can set up to STD_INTERF_TM (5 seconds).
• int time( int usec ); — returns the absolute time in seconds from the epoch of 1/1/1970 and the microseconds part into usec if specified.
• int utime( ); int mtime( ); — returns the absolute time in microseconds and milliseconds from the epoch of 1/1/1970.
• int {localtime|gmtime}( int fullsec, int sec, int min, int hour, int mday, int month, int year, int wday, int yday, int isdst ); — returns the full date in seconds (sec), minutes (min), hours (hour), days of the month (mday), months (month), years (year), days in the week (wday), days in the year (yday) and sign of the summer time (isdst), based on the absolute time in seconds fullsec from the epoch 1/1/1970. gmtime returns time in GMT(UTC).
• int {mktime|timegm}( int sec, int min, int hour, int mday, int month, int year, int wday, int yday, int isdst ); — forms the time since Epoch 1/1/1970 from separated seconds, minutes, hours, days, month etc. The values for separated time items can be set out from this typical range, which allows you to use this function during checking, and as a result, units of time will be fixed and rotated in the normal range. timegm runs in time at GMT(UTC).
• string {strftime|strftimegm}( int sec, string form = "%Y-%m-%d %H:%M:%S" ); — converts an absolute time sec to the string of the desired format form. Record of the format corresponds to the POSIX-function strftime. strftimegm returns time into GMT(UTC).
• int {strptime|strptimegm}( string str, string form = "%Y-%m-%d %H:%M:%S" ); — returns the time in seconds from the epoch of 1/1/1970, based on the string record of time str, in accordance with the specified template form. For example the template "%Y-%m-%d %H:%M:%S" corresponds with the time "2006-08-08 11:21:55". Description of the template format can be obtained from the documentation on POSIX-function strptime. strptimegm works into GMT(UTC) time.
• int cron( string cronreq, int base = 0 ); — returns the time, planned in the format of the standard CRON, cronreq, beginning from the basic time base or current, if the basic is not specified. CRON is the standard form "* * * * *".

  Where items by the order

  • minutes (0-59);
  • hours (0-23);
  • days (1-31);
  • month (1-12);
  • week day (0[Sunday]-6).

  Where the item variants

  • "*" — any value;
  • "1,2,3" — list of the allowed values;
  • "1-5" — raw range of the allowed values;
  • "*/2" — divider to the all allowed values range.

  Examples

  • "* * * * *" — each minute;
  • "10 23 * * *" — only at 23 hour and 10 minute for any day and month;
  • "*/2 * * * *" — for minutes: 0,2,4,...,56,58;
  • "* 2-4 * * *" — for any minutes in hours from 2 to 4(include).
• string strFromCharCode( int char1, int char2, int char3, ... ); — creates a string from symbol codes char1, char2 ... charN.
• string strFromCharUTF([string type = "UTF-8",] int char1, int char2, int char3, ...); — creates a string from UTF symbols char1, char2 ... charN. These types of the symbol are supported: UTF-8, UTF-16, UTF-16LE, UTF-16BE, UTF-32, UTF-32LE, UTF-32BE.
• string strCodeConv( string src, string fromCP, string toCP ); — transcodes the text src from the encoding fromCP to toCP. If the encoding is omitted (empty string), it is used the internal one.
• string strEncode( string src, string tp = "Bin", string opt = "" ); — encodes the string src by the rule tp and the option opt. Allowed rules:

  "PathEl" — symbols [/%] to "%2f" and "%25", respectively;

  "HttpURL" — symbols [ \t%] and "> 0x80" to "%20", "%09", "%25" and etc.;

  "HTML" — symbols of the HTML-entities [><"&'] to "&gt;", "&lt;", "&quot;" and etc.;

  "JavaScript" — symbol '\n' shielding to "\\n";

  "SQL" — shielding of the symbols ['"`\] by appending '\' or doubling of the listed symbols into opt;

  "Custom" — symbols into opt to the view "%NN";

  "Base64" — same Base 64 binary encoding, into opt sets a line termination symbol(s) after 57 symbols;

  "FormatPrint" — symbol '%' to "%%";

  "OscdID" — almost all symbols like [ /\&(] to '_';

  "Bin" — ASCII bytes list ("XX XX XX XX ...") to the binary represent;

  "Reverse" — reversion the sequence;

  "ToLower" — symbols to the lower register;

  "Limit" — limiting the string to the length into opt, counting UTF-8 variable length;

  "ShieldSymb" — shielding symbols from opt (by default ['"`]) with the slash symbol "\" like to '\n', '\r', ..., '\0NNN';

  "ShieldBin" — shielding all binary symbols [\x0-\x8\xB-\xC\x0E-\x1F] with the slash symbol "\".

• string strDecode( string src, string tp = "Bin", string opt = "" ); — decodes the string src by the rule tp and the option opt. Allowed rules:

  "PathEl", "HttpURL", "Custom" — symbols like "%NN" to the binary represent;

  "Base64" — same from Base 64;

  "Bin" — the binary string to ASCII bytes ("XX XX XX XX .. A.b.c.."), opt points to the separator or "<text>" for enable the offset to the left and the text part to the right;

  "ShieldSymb" — shielded symbols like to '\n', '\r', ..., '\0NNN', '\xNN' to the binary represent.

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

Object functions:

• TArrayObj nodeList( string grp = "", string path = "" ); — Get child nodes full identifiers list for group grp and node from path path. If grp empty then return nodes for all groups. The full identifier is "{grp}{nID}".
• TCntrNodeObj nodeAt( string path, string sep="" ); — Attach to node path into OpenSCADA objects tree. If a separator set into sep then path process as separated string. For missed and invalid nodes the function will return "false" when a correct node in it conversion to BOOLEAN will return "true".
• TCntrNodeObj nodePrev( ); — Get previous, parent, node.
• string nodePath( string sep = "", bool from_root = true ); — Getting the path of the current node in the object tree OpenSCADA. One separator character is specified in sep to get the path through the separator, for example, "DAQ.ModBus.PLC1.P1.var", otherwise "/DAQ/ModBus/PLC1/P1/var". from_root indicates a need to form a path from the root, and without the Station ID.
• int messSys( int level, string mess ) — Formation of the system message mess with the level with the node path as a category and with the human readable path before the message.

5 Subsystem "Security" (SYS.Security)

Functions of the subsystem object (SYS.Security):

• int access( string user, int mode, string owner, string group, int access ) — checks for access of the user to resource which owned by the owner and group and for the access and mode:

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}"]):

• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.
• bool auth( string pass ) — returns TRUE at successful authentication the user for pass.
• Array groups( ) — returns the groups list of the user.

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

• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.
• bool user( string nm ) — checks for the user nm presence into the group.

6 Subsystem "DB" (SYS.BD)

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

• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.
• Array SQLReq( string req, bool tr = EVAL ); — performs the SQL-request req to the DB, inside (tr=true), outside (tr=false) or no matter (tr=EVAL) to the transaction. Returns an array of rows of the result table with the fields both per indexes and column names. At an error the result property "err" sets to the error value.

  DBTbl = SYS.BD.MySQL.GenDB.SQLReq("SELECT * from DB;");
  if(DBTbl.err.length) SYS.messInfo("TEST DB","Error: "+DBTbl.err);
  else for(var iRw = 0; iRw < DBTbl.length; iRw++) {
    var rec = "";
    for(var iFld = 0; iFld < DBTbl[iRw].length; iFld++) rec += DBTbl[iRw][iFld] + "\t";
    SYS.messInfo("TEST DB", "Row "+iRw+": "+rec);
    //Get column value by the name
    if(iRw) SYS.messInfo("TEST DB", "Row "+iRw+": 'NAME'"+DBTbl[iRw]["NAME"]);
  }
  

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

• XMLNodeObj fieldStruct( ); — gets the table structure in XML-node "field" with the child node-columns "<RowId type="real" len="10.2" key="1" def="Default value">{Value}</RowId>", where:
  • {RowId} — column identifier;
  • {Value} — column value;
  • type — value type of the column: str — string, int — integer, real — real and bool — boolean;
  • len — value length of the column, in chars;
  • key — a sign that the column is the key, and the search is carried out according to its meaning;
  • def — default value of the column.
• string fieldSeek( int row, XMLNodeObj fld ); — seeks the field row of the table. For success returned "1" else "0". In case of error, returns "0: Error".
• string fieldGet( XMLNodeObj fld ); — requests the field value. In case of error, returns "0: Error".

  req = SYS.XMLNode("field");
  req.childAdd("user").setAttr("type","str").setAttr("key","1").setText("root");
  req.childAdd("id").setAttr("type","str").setAttr("key","1").setText("/Lang2CodeBase");
  req.childAdd("val").setAttr("type","str");
  SYS.BD.MySQL.GenDB.SYS.fieldGet(req);
  SYS.messDebug("TEST DB","Value: "+req.childGet(2).text());
  

• string fieldSet( XMLNodeObj fld ); — sets the field. In case of error, returns "0: Error".
• string fieldDel( XMLNodeObj fld ); — removes the field. In case of error, returns "0: Error".

7 Subsystem "DAQ" (SYS.DAQ)

Functions of the subsystem object (SYS.DAQ):

• TCntrNodeObj daqAt(string path, string sep = "", waitForAttr = true) — attaches to a DAQ node (controller object, parameter, attribute) in the path or the separated string by the separator sep, from the DAQ-subsystem. Check for an attribute in the path last element, at waitForAttr.
• bool funcCall(string progLang, TVarObj args, string prog, string fixId = "", string err = ""); — executes the function text prog with the arguments args on the program language progLang and with the function fixing identifier fixId (automatic if it is empty). Returns "true" when it is executed correctly or "false" and set err. The fixed function differ from the automatic one by it does not remove after execution and uses repeatedly by an address into fixId, which replaces that original identifier in first call. To recreate the function, you must change the program or clear the fixId in its original id.

  var args = new Object();
  args.y = 0;
  args.x = 123;
  SYS.DAQ.funcCall("JavaLikeCalc.JavaScript",args,"y=2*x;");
  SYS.messDebug("TEST Calc","TEST Calc rezult: "+args.y);
  

• string funcSnthHgl(string progLang); — requesting the program language progLang syntax highlight rules in the XML-tag SnthHgl.

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

• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.
• string name( ) — name of the controller object.
• string descr( ) — description of the controller object and controller.
• string status( ) — status of the controller.
• bool messSet( string mess, int lev, string type2Code = "OP", string prm = "", string cat = "") — sets of the DAQ-sourced message mess with the level lev, for the parameter prm ({PrmId}), additional category information cat and the type code type2Code. This function forms the messages with the unified DAQ-transparency category {type2Code}{ModId}:{CntrId}[.{PrmId}][:{cat}], where:
  • type2Code — the message type two-symbol code, by default means the operator actions "OP";
  • ModId — identifier of the module;
  • CntrId — identifier of the controller object;
  • PrmId — parameter identifier, from the argument prm;
  • cat — additional category information which specific for the type type2Code.
• bool alarmSet( string mess, int lev = -5, string prm = "", bool force = false ) — sets/removes of the violation mess with the level lev (negative to set otherwise to remove), for the parameter prm ({PrmId}\n{PrmNm}). The alarms clearance, as the setting also, works in the toggling mode, so means of passing the clearance messages to the message buffer, and the same clearance, only at the according violations presence, what may be disabled setting force. The function forms the alarms with the category al{ModId}:{CntrId}[.{PrmId}] and the text {CntrNm} > {PrmNm}: {MessText}, where:
  • ModId — identifier of the module;
  • CntrId — identifier of the controller object;
  • PrmId — parameter identifier, from the argument prm;
  • CntrNm — name of the controller object;
  • PrmNm — parameter name, from the argument prm;
  • MessText — message text.
• bool enable( bool newSt = EVAL ) — gets the status "Enabled" or changes it by the argument newSt assign.
• bool start( bool newSt = EVAL ) — gets the status "Running" or changes it by the argument newSt assign.

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

• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.
• TCntrNodeObj cntr( ) — returns the controller object regardless of the nesting parameters.
• bool messSet( string mess, int lev, string type2Code = "OP", string cat = "") — sets of the DAQ-sourced message mess with the level lev, for the parameter.
• bool alarmSet( string mess, int lev = -5, bool force = false ) — sets/removes of the violation mess with the level lev (negative to set otherwise to remove) for the parameter. The alarms clearance, as the setting also, works in the toggling mode, so means of passing the clearance messages to the message buffer, and the same clearance, only at the according violations presence, what may be disabled setting force.

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

• ElTp get( int tm = 0, int utm = 0, bool sys = false ); — gets the attribute value at the time tm.utm and system access flag sys. The time attributes tm.utm is outputs also then real time of the gotten value also places here if their are variables.
• bool set( ElTp val, int tm = 0, int utm = 0, bool sys = false ); — writes the value val to the attribute with the time label tm.utm and system access flag sys.
• TCntrNodeObj arch( ); — gets the archive associated with this attribute. Returns "false" in the case of absence the associated archive.
• string descr( ); — description of the attribute.
• int time( int utm ); — time of the last value of the attribute in seconds and microseconds into utm, if it is pointed and is a variable.
• int len( ); — length of the field in DB.
• int dec( ); — float resolution of the field in DB.
• int flg( ); — flags of the field.
• string def( ); — default value.
• string values( ); — allowed values list or range.
• string selNames( ); — names list of the allowed values.
• string reserve( ); — reserve string property of the value.

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

• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.

7.1 Module DAQ.JavaLikeCalc

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

• ElTp {funcID}(ElTp prm1, ...) — calls the function "funcID" of the library "Lfunc" with the parameters prm{N}. Returns result of the called function. The prefix "lib_" before the library identifier is required!

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

• ElTp call(ElTp prm1, ...) — calls the function "func" of the library "Lfunc" with the parameters prm{N}. Returns result of the called function. The prefix "lib_" before the library identifier is required!

7.2 Module DAQ.LogicLev

The object "Parameter" [this]

• bool attrAdd( string id, string name, string tp = "real", string selValsNms = "" ) [for enabled parameter of the logical type] — adds the attribute id with the name name and the type tp. If the attribute is already present, the properties will be applied that can be changed on the go: name, selection mode and selection options.
  • id, name — identifier and name of the new attribute;
  • tp — attribute type [boolean | integer | real | string | text | object] + selection mode [sel | seled] + read-only [ro];
  • selValsNms — two lines with values in first and their names in second, separated by ";".
• bool attrDel( string id ) [for enabled parameter of the logical type] — removes the attribute id.

7.3 Module DAQ.BlockCalc

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

• ElTp cfg( string nm ) — get value of configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — set configuration field nm of the object to value val.
• TCntrNodeObj cntr( ) — return the object of controller for the parameter nesting independent.

7.4 Module DAQ.ModBus

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

• string messIO(string pdu) — sends pdu through the transport of the controller object by means of the ModBus protocol. PDU query result is placed instead of the query pdu, and the error returned by the function.

The object "Parameter" [this]

• bool attrAdd( string id, string name, string tp = "real", string selValsNms = "" ) [for enabled parameter of the logical type] — adds the attribute id with the name name and the type tp. If the attribute is already present, the properties will be applied that can be changed on the go: name, selection mode and selection options.
  • id, name — identifier and name of the new attribute;
  • tp — attribute type [boolean | integer | real | string | text | object] + selection mode [sel | seled] + read-only [ro];
  • selValsNms — two lines with values in first and their names in second, separated by ";".
• bool attrDel( string id ) [for enabled parameter of the logical type] — removes the attribute id.

7.5 Module DAQ.Siemens

The object "Parameter" [this]

• bool attrAdd( string id, string name, string tp = "real", string selValsNms = "" ) [for enabled parameter of the logical type] — adds the attribute id with the name name and the type tp. If the attribute is already present, the properties will be applied that can be changed on the go: name, selection mode and selection options.
  • id, name — identifier and name of the new attribute;
  • tp — attribute type [boolean | integer | real | string | text | object] + selection mode [sel | seled] + read-only [ro];
  • selValsNms — two lines with values in first and their names in second, separated by ";".
• bool attrDel( string id ) [for enabled parameter of the logical type] — removes the attribute id.

7.6 Module DAQ.OPC_UA

The object "Parameter" [this]

• bool attrAdd( string id, string name, string tp = "real", string selValsNms = "" ) [for enabled parameter of the logical type] — adds the attribute id with the name name and the type tp. If the attribute is already present, the properties will be applied that can be changed on the go: name, selection mode and selection options.
  • id, name — identifier and name of the new attribute;
  • tp — attribute type [boolean | integer | real | string | text | object] + selection mode [sel | seled] + read-only [ro];
  • selValsNms — two lines with values in first and their names in second, separated by ";".
• bool attrDel( string id ) [for enabled parameter of the logical type] — removes the attribute id.

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

Functions of the subsystem object:

• Array messGet( int btm, int etm, string cat = "", int lev = 0, string arch = "", int upTm = 0 ); — requests of the program messages or alarms for the time from btm to etm for the category cat, level lev (-7...7) and archivers arch (separated by the symbol ';'; "" — buffer and archivers; "<buffer>" — buffer; "{ArhMod}.{Arh}" — concrete archiver of the module). upTm sets the operation continuance limit to time; a negative value used as relative time; less to STD_INTERF_TM (5). Returns time of stopping of the reading (attribute "tm" of the array) and an array of the message objects with the preset attributes:
  • tm — time of the message, seconds;
  • utm — time of the message, microseconds;
  • categ — category of the message;
  • level — level of the message;
  • mess — text of the message.
• bool messPut( int tm, int utm, string cat, int lev, string mess, string arch = "" ); — writes the message mess with the category cat, level lev (-7...7) and time tm.utm to the archivers arch (separated by the symbol ';') or/and the alarms list.

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

• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.
• bool status( ) — status "Running" of the archiver.
• int end( ) — end time of data of the archiver.
• int begin( ) — begin time of data of the archiver.

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

• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.
• bool status( ) — status "Running" of the archiver.

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

• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.
• bool status( ) — status "Running" of the archive.
• int end( string arch = "" ) — end time of data of the archive for the archiver arch, in microseconds.
• int begin( string arch = "" ) — begin time of data of the archive for the archiver arch, in microseconds.
• int period( string arch = "" ) — period of data of the archive for the archiver arch, in microseconds.
• TArrayObj archivatorList( ) — list of archivers that use this archive as a source.
• VarType getVal( int tm, bool up_ord = false, string arch = "" ) — gets a value from the archive for the time tm, tightening up up_ord and archiver arch:
  • tm — time of the requested value, in microseconds, set to 0 for "end()"; this attribute is also an output, so the real time of the received value is placed here if it is a variable;
  • up_ord — tighten the time of the requested value to the top of the grid;
  • arch — request archiver, set in an empty line to check all archivers, set to "<buffer>" to handle only the buffer.
• bool setVal( int tm, VarType vl, string arch = "" ) [access to the Archive-History subsystem] — sets the value vl to the archive for the time tm and the archiver arch:
  • tm — time of the set value, in microseconds;
  • vl — value;
  • arch — archiver of the set request, set in an empty line for all archivers, set to "<buffer>" to handle only the buffer.
• Array getVals( int begTm, int endTm, int period, string arch = "" ) — gets for the archive/history values from begTm and up to endTm for the archiver arch:
  • begTm — begin time of the requesting data range, in microseconds, will be changed to the real data begin;
  • endTm — end time of the requesting data range, in microseconds;
  • period — period of the data, in microseconds, must be necessarily specified and will be used the maximum one from the archive, will be changed to the real data period;
  • arch — requesting archiver, set to empty to try for the buffer and all archivers, set to "<buffer>" to process only the buffer.
• bool setVals( Array buf, int tm, int period, string arch = "" ) [access to the Archive-History subsystem] — sets for the archive/history values buf to the archive from the begin time tm, the values period period and the archiver arch.
  • buf — array of the values to set;
  • tm — begin time of the setting data range, in microseconds;
  • period — period of the setting data, in microseconds, must be necessarily specified and will be used the maximum one from the archive, will be changed to the real data period;
  • arch — setting archiver, set to empty to set for the buffer and all archivers, set to "<buffer>" to set only the buffer.

9 Subsystem "Transports" (SYS.Transport)

Functions of the subsystem object:

• TCntrNodeObj outAt( string addr ); — common-unified output transport connection at the address addr in the forms:

"{TrModule}.[out_]{TrID}[:{TrAddr}]" — typical output with automatic creation TrID at it missing and allowing TrAddr;

"{TrModule}.in_{TrID}:{RemConId}" — initiative input with the connection identifier in RemConId.

• TrModule — transport module, as is Sockets, SSL, Serial;
• TrID — transport identifier;
• TrAddr — transport specific address;
• RemConId — remote initiative connection ID.

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

• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.
• string status() — string status of the transport.
• string addr( string vl = "" ) — address of the transport, sets the non-empty value vl.
• string writeTo(string sender, string mess) — sends the message mess to the sender sender, as a reply.
• TArrayObj associateTrsList() — associated output transports list to that input one.
• TCntrNodeObj associateTr( string id ) — getting the associated transport at that connection id.
• ElTp conPrm( string id, ElTp val = EVAL, string cfg = "" ) — common handling the connection time parameter id with setting to the value val at presence; request for configuration parameter of the connection time with registration at the first time from the configuration cfg in the form "{SRC}\n{NAME}\n{HELP}".
• bool setConPrm( string id, ElTp val ) — setting the connection time parameter id to the value val, only for compatibility.

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

• bool isNetwork( ) — the sign — "The transport is network one", what is specified by the timeouts in seconds.
• ElTp cfg( string nm ) — gets the value of the configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) [access to the appropriate subsystem] — sets the configuration field nm of the object to the value val.
• string status() — string status of the transport.
• bool start( bool vl = EVAL, int tm = 0 ) — returns the transport status "Running", starts/stops it by vl (if it is not EVAL). For starting you can set the specific timeout tm.
• string addr( string vl = "" ) — address of the transport, sets the non-empty value vl.
• string timings( string vl = "", isDef = true ) — timings of the transport, sets the non-empty value vl and as default one for isDef.
• int attempts( int vl = EVAL ) — attempts of the transport connection, sets the non-EVAL value vl.
• ElTp conPrm( string id, ElTp val = EVAL, string cfg = "" ) — common handling the connection time parameter id with setting to the value val at presence; request for configuration parameter of the connection time with registration at the first time from the configuration cfg in the form "{SRC}\n{NAME}\n{HELP}".
• bool setConPrm( string id, ElTp val ) — setting the connection time parameter id to the value val, only for compatibility.
• string messIO( string mess, real timeOut = 0, int inBufLen = -1 ); — sends the message mess via the transport with the waiting time of the response timeOut (in seconds) and reads an response (Buffer) in inBufLen byte. In the case of a zero timeout, this time is taken from the settings of the output transport. The timeOut in negative (< -1e-3) disables the transport request/respond mode and allows for independent reading/writing to a buffer IO, with the reading timeout timeOut in absolute. For negative inBufLen the buffer size sets to STR_BUF_LEN(10000) and "0" disables the reading at all.
  If your transport means getting data in parts for a request then for several devices on single bus-transport, use the function into single thread but there is not a way to lock the transport into the user API. Single thread that is any object of controller of DAQ and the module "User protocol" locks the transport internally before self user procedures execution.

  rez = SYS.Transport.Serial.out_ttyUSB0.messIO(SYS.strFromCharCode(0x4B,0x00,0x37,0x40),0.2);
  //Wait for all the message tail by timeout and empty result
  while(rez.length && (trez=SYS.Transport.Serial.out_ttyUSB0.messIO("")).length) rez += trez;
  

• string messIO( XMLNodeObj req, string prt ); — sends the request req to the protocol prt to perform a communication session through the transport and in assistance of the protocol. Returns a string with error in the format "{errCod}:{errText}" which empty for successful request.

  req = SYS.XMLNode("TCP");
  req.setAttr("id","test").setAttr("reqTm",500).setAttr("node",1).setAttr("reqTry",2).setText(SYS.strFromCharCode(0x03,0x00,0x00,0x00,0x05));
  SYS.Transport.Sockets.out_testModBus.messIO(req,"ModBus");
  test = Special.FLibSYS.strDec4Bin(req.text());
  

10 Subsystem "Protocols" (SYS.Protocols)

10.1 Module Protocol.HTTP

Input part of the module object (SYS.Protocol.HTTP.{In})

• bool setUser( string user ) — changes the user linked to the authentication session ID.
  • user — user to change.
• bool pgAccess(string URL) — checks for accessing the page, pointed by the URL.
  • URL — URL of the checking page.
• string pgCreator(string cnt, string rcode = "", string httpattrs = "Content-Type: text/html;charset={SYS}", string htmlHeadEls = "", string forceTmplFile = "" ) — forms for a page or a resource from the content cnt, wrapped to HTTP with the result rcode, with HTTP additional attributes httpattrs, HTML additional head's element htmlHeadEls, forced to template file forceTmplFile.
  • cnt — content of the page or the resource (images, XML, CSS, JavaScript, ...) ;
  • rcode — HTTP result code, like to "200 OK"; empty value there disables addition of the HTTP header;
  • httpattrs — additional HTTP-attributes, mostly this is "Content-Type" which by default sets to "text/html;charset={SYS}"; only for "Content-Type: text/html" will be wrapped to internal/service or force forceTmplFile HTML-template;
  • htmlHeadEls — additional HTML-header's tag, it's mostly META with "Refresh" to the specified URL;
  • forceTmplFile — force template file to override the internal/service or the main-page template.

11 Subsystem "User interfaces" (SYS.UI)

Functions of the subsystem object:

• string mimeGet(string fnm); — obtaining the MIME type at the file name fnm.

11.1 Module QTStarter

The module object (SYS.UI.QTStarter)

• Array sensors() — get all available sensors of the Qt mobility, returns "false" if no sensor is available.

11.2 Module UI.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. In 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.
• int period( bool isReal = false ) — getting the session processing period, isReal for the real one.

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.
• int calcPer( int set = EVAL ) — the actual calculation-processing period getting and setting at set not EVAL. There reserved the special values:
  • 0 — if you want the session period processing;
  • -1 — if you want to use the parent widget/page/project processing period in the cascade;
  • -2 — for disable the periodic processing in whole;
  • -3 — no session time period, getting the projecting one.

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

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

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.FLibSYS)

• ElTp {funcID}(ElTp prm1, ...) — call the library function {funcID}. Return result of the called function.

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

• ElTp call(ElTp prm1, ...) — call the function with parameters prm{N}. Return result of the called function.

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

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

• ElTp {funcID}(ElTp prm1, ...) — call the library function {funcID}. Return result of the called function.

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

• ElTp call(ElTp prm1, ...) — call the function with parameters prm{N}. Return result of the called function.

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)

• ElTp {funcID}(ElTp prm1, ...) — call the library function {funcID}. Return result of the called function.

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

• ElTp call(ElTp prm1, ...) — call the function with parameters prm{N}. Return result of the called function.

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
Libraries of the data sources, services and processing
Main library	2.3	GPLv2	OscadaLibs.db (SQL, GZip) > DAQ.tmplb_base	en, uk, ru
Industrial devices library	3.0	GPLv2	OscadaLibs.db (SQL, GZip) > DAQ.tmplb_DevLib	en, uk, ru
Low level sensors and chips library	1.6	GPLv2	OscadaLibs.db (SQL, GZip) > DAQ.tmplb_LowDevLib	en, uk, ru
Service procedures library	1.2	GPLv2	OscadaLibs.db (SQL, GZip) > DAQ.JavaLikeCalc.servProc	en, uk, ru
Regulation elements library	1.0	GPLv2	OscadaLibs.db (SQL, GZip) > DAQ.JavaLikeCalc.regEl	en, uk, ru
Library of models of the technological apparatuses	2.0	GPLv2	OscadaLibs.db (SQL, GZip) > DAQ.JavaLikeCalc.techApp	en, uk, ru
Graphical elements' libraries of the OpenSCADA module UI.VCAEngine
Main elements library of the user interface	2.2	GPLv2	vcaBase.db (SQL, GZip) > VCA.wlb_Main	en, uk, ru
Mnemonic elements library of the user interface	1.0	GPLv2	vcaBase.db (SQL, GZip) > VCA.wlb_mnEls	en, uk, ru
Electrical elements library of the user interface	2.0	GPLv2	vcaElectroEls.db (SQL, GZip) > VCA.wlb_ElectroEls	en, uk, ru
Combined libraries
Reports' and documents' library	2.0, 2.1	GPLv2	OscadaLibs.db (SQL, GZip) > DAQ.JavaLikeCalc.doc vcaBase.db (SQL, GZip) > VCA.wlb_doc	en, uk, ru
Prescriptions	1.1, 1.1	GPLv2	OscadaLibs.db (SQL, GZip) > DAQ.tmplb_PrescrTempl vcaBase.db (SQL, GZip) > VCA.wlb_prescr	en, uk, ru

14 Links

• Diagram: User object model of the core OpenSCADA.