Документация/API пользователя - OpenSCADAWiki

# Документация/API пользователя

This page is a translated version of the page Documents/User API and the translation is 65% complete.

English • ‎mRussian • ‎Українська

- Автор: Роман Савоченко
- Изначально создано: в старой Wiki

До начала программирования в OpenSCADA Вы должны изучить структуру объектов программы (Объектная модель) из руководства по программе OpenSCADA и на рисунке 1.

Рис. 1. Пользовательская объектная модель ядра OpenSCADA.

Из этого документа Вы увидите, что можете, как пользователь, программировать следующие части OpenSCADA:

- Источники логического уровня подсистемы "Сбор данных".
- Транспортные протоколы, доступные для пользовательского программирования, такие как: Пользовательский протокол, ModBus узлы типа "Данные", Web-интерфейсы от пользователя, ...
- Среда Визуализации и Управления (СВУ) в процедурах виджетов.

API пользовательского программирования представляет собой дерево объектов OpenSCADA (Рис.1), каждый объект которого может представлять собственный перечень свойств и функций. Свойства и функции объектов могут использоваться пользователем в процедурах на языках пользовательского программирования OpenSCADA.

На данный момент OpenSCADA предоставляет только один язык текстового программирования — JavaLikeCalc, следовательно Вы также должны его изучить перед началом. Точкой входа для доступа к объектам OpenSCADA (Рис.1) из языка пользовательского программирования JavaLikeCalc является зарезервированное слово "SYS", корневого объекта OpenSCADA. Например, для доступа к функции исходящего транспорта нужно записать: SYS.Transport.Serial.out_ModBus.messIO(mess);.

API объектов, предоставляемых модулями, описывается в собственной документации модулей и тут предоставляются ссылки на неё.

## 1 Пользовательский язык программирования JavaLikeCalc

### 1.1 Элементы языка

Ключевые слова: if, else, while, for, in, break, continue, return, function, using.
Постоянные:

- десятичные: цифры 0-9 (12, 111, 678);
- восьмеричные: цифры 0-7 (012, 011, 076);
- шестнадцатеричные: цифры 0-9, буквы a-f или A-F (0x12, 0XAB);
- вещественные: 345.23, 2.1e5, 3.4E-5, 3e6;
- логические: true, false;
- строковые: "hello", без перехода на другую строку однако с поддержкой прямой конкатенации строковых констант.

Типы переменных:

- целое: -263 ... 263, EVAL_INT(-9223372036854775807);
- вещественное: 3.4*10308, EVAL_REAL(-1.79E308);
- логическое: false, true, EVAL_BOOL(2);
- строка: последовательность символов-байтов (0...255) любой длины, ограниченной объёмом памяти и хранилищем в БД; EVAL_STR("<EVAL>").

Встроенные константы: pi = 3.14159265..., e = 2.71828182..., EVAL_BOOL(2), EVAL_INT(-9223372036854775807), null,EVAL,EVAL_REAL(-1.79E308), EVAL_STR("<EVAL>")
Глобальные атрибуты параметров DAQ (начиная с подсистемы "DAQ" и в виде {Тип модуля DAQ}.{Объект контроллера}.{Параметр}.{Атрибут}).
Функции и параметры объектной модели 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 Операции языка

Операции, поддерживаемые языком, представлены в таблице ниже. Приоритет операций уменьшается сверху вниз. Операции с одинаковым приоритетом входят в одну цветовую группу.

Символ | Описание
() | Вызов функции.
{} | Программные блоки.
++ | Инкремент (пост и пре).
-- | Декремент (пост и пре).
- | Унарный минус.
! | Логическое отрицание.
~ | Побитовое отрицание.
* | Умножение.
/ | Деление.
% | Остаток от целочисленного деления.
+ | Сложение
- | Вычитание
<< | Поразрядный сдвиг влево
>> | Поразрядный сдвиг вправо
> | Больше
>= | Больше или равно
< | Меньше
<= | Меньше или равно
== | Равно
!= | Не равно
| | Поразрядное "ИЛИ"
& | Поразрядное "И"
^ | Поразрядное "Исключающее ИЛИ"
&& | Логический "И"
|| | Логический "ИЛИ"
?: | Условная операция "i=(i<0)?0:i;"
= | Присваивание.
+= | Присваивание со сложением.
-= | Присваивание с вычитанием.
*= | Присваивание с умножением.
/= | Присваивание с делением.

### 1.3 Встроенные функции языка

Виртуальной машиной языка предусматривается следующий набор встроенных функций общего назначения:

- double max(double x, double x1) — максимальное значение из x и x1;
- double min(double x, double x1) — минимальное значение из x и x1;
- string typeof(ElTp vl) — тип значения vl;
- string tr(string base) — перевод базового base сообщения.

Для обеспечения высокой скорости работы в математических вычислениях модуль предоставляет встроенные математические функции, которые вызываются на уровне команд виртуальной машины:

- double sin(double x) — синус x;
- double cos(double x) — косинус x;
- double tan(double x) — тангенс x;
- double sinh(double x) — синус гиперболический от x;
- double cosh(double x) — косинус гиперболический от x;
- double tanh(double x) — тангенс гиперболический от x;
- double asin(double x) — арксинус от x;
- double acos(double x) — арккосинус от x;
- double atan(double x) — арктангенс от x;
- double rand(double x) — случайное число от 0 до x;
- double lg(double x) — десятичный логарифм от x;
- double ln(double x) — натуральный логарифм от x;
- double exp(double x) — экспонента от x;
- double pow(double x, double x1) — возведение x в степень x1;
- double sqrt(double x) — корень квадратный от x;
- double abs(double x) — абсолютное значение от x;
- double sign(double x) — знак числа x;
- double ceil(double x) — округление числа x до большего целого;
- double floor(double x) — округление числа x до меньшего целого.

### 1.4 Операторы языка

Общий перечень операторов языка:

- var — оператор инициализации переменной; указание переменной без присваивания значения резервирует её со значением null-EVAL, что позволяет осуществлять одноразовую инициализацию сложных типов данных вроде объекта, через прямое сравнение и проверку на isEVal();
- if — оператор условия "ЕСЛИ";
- else — оператор условия "ИНАЧЕ";
- while — определение цикла "ПОКА";
- for — определение цикла "ДЛЯ";
- in — разделитель цикла "ДЛЯ" для перебора свойств объекта;
- break — прерывание выполнения цикла;
- continue — продолжить выполнение цикла с начала;
- function — определение внутренней функции;
- using — позволяет установить область видимости внешних функций часто используемой библиотеки (using Special.FLibSYS;) для последующего обращения только по имени функции, не имеет эффекта для объектного доступа;
- return — прерывание функции и возврат результата, который копируется в атрибут с флагом возврата (return 123;); в середине внутренней функции осуществляется её завершение с указанным результатом;
- new — создание объекта, реализовано для: общий объект "Object", массив "Array" и регулярные выражения "RegExp";
- delete — удаление/освобождение объекта или его свойств, при этом: внутренние переменные устанавливаются в null-EVAL, внешние заменяются пустым объектом, а свойства объекта очищаются.

#### 1.4.1 Условные операторы

Языком поддерживаются два типа условий. Первый — это операции условия для использования внутри выражения, второй — глобальный, основанный на условных операторах.

Условие внутри выражения строится на операциях '?' и ':'. В качестве примера можно записать следующее практическое выражение:

    st_open = (pos >= 100) ? true : false;

Что читается как — если переменная pos больше или равна 100, то переменной st_open присваивается значение true, иначе — false.

Глобальное условие строится на основе условных операторов "if" и "else". В качестве примера можно привести тоже выражение, но записанное другим способом:

    if(pos > 100) st_open = true; else st_open = false;

#### 1.4.2 Циклы

Поддерживаются три типа циклов: while, for и for-in. Синтаксис циклов соответствует языкам программирования: C++, Java и JavaScript.

Цикл while, в общем, записывается следующим образом: while({условие}) {тело цикла};
Цикл for записывается следующим образом: for({пре-инициализ};{условие};{пост-вычисление}) {тело цикла};
Цикл for-in записывается следующим образом: for({переменная} in {объект}) {тело цикла};
Где:

  {условие} — выражение, определяющее условие;
  {тело цикла} — тело цикла множественного исполнения;
  {пре-инициализ} — выражение предварительной инициализации переменных цикла;
  {пост-вычисление} — выражение модификации параметров цикла после очередной итерации;
  {переменная} — переменная, которая будет содержать имя свойства объекта при переборе;
  {объект} — объект для которого осуществляется перебор свойств.

#### 1.4.3 Внутренние функции

Язык поддерживает определение и вызов внутренних функций. Для определения внутренней функции используется ключевое слово "function" и в целом определение имеет синтаксис: function {имяФ} ({пер1}, {пер2}, ... {перN}) { {тело функции} }. Определение внутренней функции внутри другой недопустимо однако допустим вызов ранее определённой.

Вызов внутренней функции осуществляется в типовой способ, как процедура {имяФ}({var1}, {var2}, ... {varN}); или как функция {перРез} = {имяФ}({пер1}, {пер2}, ... {перN});. Вызов внутренних функций допустим только после их декларации выше!

Все переменные, определённые в основном теле, недоступны в середине внутренних функций и могут быть переданы через двухсторонние аргументы вызываемой внутренней функции или через аргументы основной функции. Все переменные, определённые в середине внутренней функции, имеют собственную область имён и недоступны из основного тела, или любой другой внутренней функции, и могут быть переданы в основное тело через двухсторонние аргументы, результат вызываемой внутренней функции или через аргументы основной функции. Переменные внутренней функции регистрируются для сохранения/восстановления их контекста после второго и более входа в функцию, т.е. они целиком поддерживают рекурсивные вызовы!

Оператор "return", в середине внутренней функции, осуществляет контролируемое её завершение и помещение указанной переменной, или результата выражения, как результат вызываемой внутренней функции.

Пример типового определения и использования внутренней функции представлен далее:

    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 Специальные символы строковых переменных

Языком предусмотрена поддержка следующих специальных символов строковых переменных:

  "\n" — перевод строки;
  "\t" — символ табуляции;
  "\b" — забой;
  "\f" — перевод страницы;
  "\r" — возврат каретки;
  "\\" — сам символ '\';
  "\041" — символ '!', записанный восьмеричным числом;
  "\x21" — символ '!', записанный шестнадцатеричным числом.

## 2 Общесистемные пользовательские объекты

JavaLikeCalc предоставляет поддержку типа данных объект "Object". Объект представляет собой ассоциативный контейнер свойств и функций. Свойства могут содержать как данные четырёх базовых типов, так и другие объекты. Доступ к свойствам объекта может осуществляться посредством записи имён свойств к объекту obj.prop, через точку, а также посредством заключения имени свойства в квадратные скобки obj["prop"]. Очевидно, что первый механизм статичен, а второй позволяет указывать имя свойства через переменную. Удалить свойство объекта можно директивой "delete". Имя свойства через точку не должно начинаться с цифры и содержать символы операций, иначе, для первой цифры, должен использоваться префикс объекта — SYS.BD.SQLite.db_1s, или осуществляться запись в квадратных скобках — SYS.BD.SQLite["1+s"], для символов операций в названии. Чтение неопределённого свойства вернёт null-EVAL. Создание объекта осуществляется посредством ключевого слова new: varO = new Object(). Базовое определение объекта не содержит функций. Операции копирования объекта, на самом деле, делают ссылку на исходный объект. При удалении объекта осуществляется уменьшение счётчика ссылок, а при достижении счётчика нуля, объект удаляется физически.

Разные компоненты OpenSCADA могут доопределять базовый объект особыми свойствами и функциями. Стандартным расширением объекта является массив "Array", который создаётся командой varO = new Array(prm1,prm2,prm3,...,prmN). Перечисленные через запятую параметры помещаются в массив в исходном порядке. Если параметр только один то массив инициируется указанным количеством пустых элементов. Особенностью массива является то, что он работает со свойствами, как с индексами и основным механизмом обращения является заключение индекса в квадратные скобки arr[1]. Массив хранит свойства в собственном контейнере одномерного массива. Цифровые свойства массива используются для доступа непосредственно к массиву, а символьные работают как свойства объекта. Детальнее про свойства и функции массива можно прочитать по ссылке.

Объект регулярного выражения "RegExp" создаётся командой varO = new RegExp(pat, flg), где pat — шаблон регулярного выражения, а flg — флаги поиска. Объект работы с регулярными выражениями основан на библиотеке "PCRE". При глобальном поиске устанавливается атрибут объекта "lastIndex", что позволяет продолжить поиск при следующем вызове функции. В случае неудачного поиска атрибут "lastIndex" сбрасывается в ноль. Детальнее про свойства и функции объекта регулярного выражения можно прочитать по ссылке.

Для произвольного доступа к аргументам функции предусмотрен объект аргументов, обратиться к которому можно посредством символа "arguments". Этот объект содержит свойство "length" с количеством аргументов у функции и позволяет обратиться к значению аргумента посредством его номера или идентификатора. Рассмотрим перебор аргументов по циклу:

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

Частичными свойствами объекта обладают и базовые типы. Свойства и функции базовых типов приведены ниже:

- Нулевой тип, функции:
  - bool isEVal(); — возвращает "true".

- Логический тип, функции:
  - bool isEVal(); bool isNaN( ); — проверяет значение на null-EVAL.
  - string toString(); — представляет значение в виде строки "true" или "false".

  - real toReal(); — читает логическое значение как вещественное число.
  - int toInt(); — читает логическое значение как целое число.

- Целое и вещественное число:

  Свойства:
  - MAX_VALUE — максимальное значение;
  - MIN_VALUE — минимальное значение;
  - NaN — недостоверное значение.
  Функции:
  - bool isEVal(); bool isNaN( ); — проверяет значение на null-EVAL, и не число для Вещественного.
  - string toExponential( int numbs = -1 ); — возвращает строку отформатированного числа, в экспоненциальной нотации и количеством значащих цифр numbs. Если numbs отсутствует то цифр будет столько сколько необходимо.
  - string toFixed( int numbs = 0, int len = 0, bool sign = false ); — возвращает строку отформатированного числа в нотации с фиксированной точкой и количеством цифр после десятичной точки numbs, с минимальной длиной len и обязательным знаком sign. Если numbs отсутствует то количество цифр после десятичной точки равно нулю.
  - string toPrecision( int prec = -1 ); — возвращает строку отформатированного числа с количеством значащих цифр prec.
  - string toString( int base = 10, int len = -1, bool sign = false ); — возвращает строку отформатированного числа целого типа с базой представления base (2-36), с минимальной длиной len и обязательным знаком sign.
  - real toReal(); — читает целое-вещественное значение как вещественное число.
  - int toInt(); — читает целое-вещественное значение как целое число.

- 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. For the not global search 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. For the global search just returns an array of the found items.

    var rez = "1 plus 2 plus 3".match("\\d+");      // rez = [1], index=0, input="1 plus 2 plus 3"
    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. For the not global search 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. For the global search just returns an array of the found items.

    var rez = "1 plus 2 plus 3".match(new RegExp("\\d+"));      // rez = [1], index=0, input="1 plus 2 plus 3"
    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 = "." ); string sep2path( string sep = "." ); — converts path into this string to separated by sep string and back.
  - string trim( string cfg = " \n\t\r" ); — trims the string at the begin and the end for the symbols cfg.

### 2.1 Объект массива (Array)

Особенностью массива является то, что он работает со свойствами, как с индексами, и полное их именование бессмысленно, а значит доступен только механизм обращения заключением индекса в квадратные скобки "arr[1]". Массив хранит свойства в собственном контейнере одномерного массива. Цифровые свойства массива используются для доступа непосредственно к массиву, а символьные работают как свойства объекта.

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 = {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.
- Array splice( int beg, int remN = {end}[, ElTp val1[, ElTp val2, ...]] ); — deletes the elements from beg in quantity remN and next inserts the elements val1, val2, ... to the array. Returns the removed elements' array.
- 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 = {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)

Объект работы с регулярными выражениями, основан на библиотеке PCRE. При глобальном поиске устанавливается атрибут объекта "lastIndex", что позволяет продолжить поиск при следующем вызове функции. В случае неудачного поиска атрибут "lastIndex" сбрасывается в ноль.

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, that is meant the request repeating for processing all expressions up to empty result array;
- '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 '\'.

Свойства объекта:

- source — исходный шаблон регулярного выражения, только чтение.
- global — признак глобального поиска, только чтение.
- ignoreCase — признак игнорирования регистра символов при поиске, только чтение.
- multiline — признак многострочного поиска, только чтение.
- UTF8 — признак разрешения UTF-8 символов, только чтение.
- lastIndex — индекс символа за подстрокой последнего поиска, используется в глобальном режиме для продолжения сканирования, при следующем вызове.

Функции объекта:

- Array exec(string val); — вызывает поиск по строке val. Возвращает найденную подстроку (0) и подвыражения (>0) в массиве. Устанавливает атрибут массива "index" в позицию найденной подстроки. Устанавливает атрибут массива "input" в значение исходной строки.

      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); — возвращает "true" если подстрока найдена в 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,nameSet}( string vl ) — sets of the node name to vl. Returns the current node.
- XMLNodeObj {setText,textSet}( string vl ) — sets of the node text to vl. Returns the current node.
- XMLNodeObj {setAttr,attrSet}( 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 ); XMLNodeObj childDel( ElTp no ) — deletes the included node from the position id or for the children node no. 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 — don't remove spaces from the begin and end of the tag text;
    0x04 — process for specific the pure HTML like to: tags without closing, attributes without a value, attribute values without quoting, closing tags switching; sets already from the DOCTYPE HTML header.

- 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 — break before the open tag;
    0x02 — break after the open tag;
    0x04 — break after the close tag;
    0x08 — break after the text;
    0x10 — break after the special block;
    0x1E — break after all;
    0x20 — include standard XML header;
    0x40 — include standard XHTML header;
    0x80 — clean the service tags: <??>, <!-- -->;
    0x100 — omit for tag's name encoding;
    0x200 — omit for attribute's name encoding;
    0x400 — shield the binary symbols [\x0-\x8\xB-\xC\x0E-\x1F] and wrong UTF-8;
    0x800 — hold empty attributes, mostly as the sign in the pure HTML.

- XMLNodeObj getElementBy( string val, string attr = "id" ) — gets an element from the tree by the attribute attr in value val, returns null-EVAL at missing requesting element.
- 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:

- 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.
- {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.
- bool fileRotate( string file, real size = 1.0, int cnt = 10 ); — rotates file at size bigger size and up to number the rotated files in cnt.
- 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 obj2str( TVarObj obj, string type = "json" ); — Conversion-serialisation contents of the object obj to the XML stream for type in "xml" or not the generic object and not array; else to JSON.
- string time2str( real tm, bool inParts = true ); — Converts the time interval tm in seconds to human string like "1hour 23minutes 10s" at setting inParts or "1.5 hour" else.
- string cpct2str( real cnt ); — Converts the capacity cnt in bytes to the human representing string.
- TVarObj str2obj( string str ); — Deserialization the stream str to the object firstly from JSON and at an error to XML.
- string str2time( string val, bool inParts = true ); — Converts the human representing relative time val of the function time2str() to the time in seconds, with parsing parts at setting inParts.
- 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', '\uXXXX' to the binary represent.

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

Object functions:

- PropTp property(string id, PropTp val = null); — Returns of the object's property id for the group grp with setting its at val non null and EVAL. Where val in EVAL is clearing the property and null (no the argument) just sets nothing. You can access directly the properties for the TCntrNode objects, of course at their absence in the Object Model.
- 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 missing 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 perm ) — checking for access of the user to resource which owned by the owner and group and for the perm 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;
    perm — permition of the resource (RWXRWXRWX — 0777).

Функции объекта "Пользователь" (SYS.Security["usr_{User}"]):

- ElTp cfg( string nm ) — получает значение конфигурационного поля nm объекта.
- bool cfgSet( string nm, ElTp val ) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение val.
- bool auth( string pass ) — возвращает TRUE в случае удачной аутентификации пользователя по pass.
- Array groups( ) — возвращает перечень групп пользователя.

Функции объекта "Группа пользователей" (SYS.Security["grp_{Group}"]):

- ElTp cfg( string nm ) — получает значение конфигурационного поля nm объекта.
- bool cfgSet( string nm, ElTp val ) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение val.
- bool user( string nm ) — проверяет присутствие пользователя nm в данной группе.

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

Функции объекта "Таблица" (SYS.BD["TypeDB"]["DB"]["Table"]):

- XMLNodeObj fieldStruct( ); — получает структуру таблицы в виде XML узла "field" с дочерними узлами-колонками <RowId type="real" len="10.2" key="1" def="Default value">{Value}</RowId>, где:
  - {RowId} — идентификатор колонки;
  - {Value} — значение колонки;
  - type — тип значения колонки: str — строка, int — целое, real — вещественное и bool — логическое;
  - len — размер значения колонки, в знаках;
  - key — признак того, что колонка является ключом, и поиск осуществляется по его значению;
  - def — значение колонки по умолчанию.
- string fieldSeek( int row, XMLNodeObj fld ); — запрашивает поле row таблицы. Если поле получено то возвращается "1" иначе "0". В случае ошибки возвращается "0:Error".
- string fieldGet( XMLNodeObj fld ); — запрашивает значение поля. В случае ошибки возвращается "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 ); — устанавливает поле. В случае ошибки возвращается "0:Error".
- string fieldDel(XMLNodeObj fld); — удаляет поле. В случае ошибки возвращается "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. Returns "false" in the case of absence specified DAQ-Node.
- 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}\n{PrmNm}), 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}] and the text {CntrNm} > {PrmNm} > {MessText}, 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;
  - CntrNm — name of the controller object, that is inserted whether from the description field "MessName: {Name}" (even empty for hide) or from not empty name;
  - PrmNm — parameter name, from the argument prm;
  - cat — additional category information which specific for the type type2Code;
  - MessText — message text.
- 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, that is inserted whether from the description field "MessName: {Name}" (even empty for hide) or from not empty name;
  - 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, whose name inserted hierarchically to the text whether from the description field "MessName: {Name}" (even empty for hide) or from not empty name;
- 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, whose name inserted hierarchically to the text whether from the description field "MessName: {Name}" (even empty for hide) or from not empty name. 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.
- bool attrAdd( string id, string name, string tp = "real", string selValsNms = "" ) [for enabled dynamically controlled parameter] — 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. Values of the dynamically added attributes can be saved and loaded like to IOs of the DAQ-Templates of the Logical Leveled sources.
  - id, name — identifier and name of the new attribute;
  - tp — attribute type [bool[ean] | int[eger] | real | str[ing] | text | obj[ect] ] + 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 dynamically controlled parameter] — removes the attribute id.

Функции объекта атрибута параметра контроллера (SYS.DAQ["Modul"]["Controller"]["Parameter"]["Attribute"]):

- ElTp get( int tm = 0, int utm = 0, bool sys = false ) — запрашивает значение атрибута на время tm.utm и признаком системного доступа sys. Атрибуты времени tm.utm являются также выходами, соответственно реальное время полученного значения помещается в них, если это переменные.
- bool set( ElTp val, int tm = 0, int utm = 0, bool sys = false ) — записывает значение val в атрибут с меткой времени tm:utm и признаком системного доступа sys.
- TCntrNodeObj arch( ) — получает объект архива, связанный с этим атрибутом. В случае отсутствия связанного архива возвращается "false".
- string descr( ) — описание атрибута.
- int time( int utm ) — время последнего значения в секундах и микросекундах в utm, если указан и является переменной.
- int len( ) — длина поля в БД.
- int dec( ) — разрешение вещественного числа поля в БД.
- int flg( ) — флаги поля.
- string def( ) — значение по умолчанию.
- string values( ) — список допустимых значений или диапазон.
- string selNames( ) — список имён допустимых значений.
- string reserve( ) — резервное свойство значения.

Функции объекта библиотеки шаблона (SYS.DAQ[tmplb_Lib"]) и шаблона (SYS.DAQ[tmplb_Lib"]["Tmpl"]) параметра контроллера:

- ElTp cfg( string nm ) — получает значение конфигурационного поля nm объекта.
- bool cfgSet( string nm, ElTp val ) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение 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.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.3 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.
- ElTp value( string addr, ElTp setVl = NULL ) — direct accessing a value-registers with registering for acquisition.
  - addr — the value-registers address in the standard format;
  - setVl — setting value, NULL (not specified) only for getting.

### 7.4 Module DAQ.Siemens

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

- ElTp value( string addr, ElTp setVl = NULL ) — direct accessing a value with registering for acquisition.
  - addr — the value address in the standard format;
  - setVl — setting value, NULL (not specified) only for getting.

### 7.5 Module DAQ.OPC_UA

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

- ElTp value( string addr, ElTp setVl = NULL ) — direct accessing a value-node with registering for acquisition.
  - addr — the value-node address in the standard format;
  - setVl — setting value, NULL (not specified) only for getting.

## 8 Подсистема "Архивы-История" (SYS.Archive)

Функции объекта подсистемы:

- Array messGet( int btm, int etm, string cat = "", int lev = 0, string arch = "", int upTm = 0 ); — запрашивает сообщения программы или нарушения (lev < 0) за время от btm до etm для категории cat, уровня lev (-7...7) и архиваторов arch (разделены символом ';'; "" — буфер и архиваторы; "<buffer>" — буфер; "{ArhMod}.{Arh}" — конкретный архиватор модуля). upTm устанавливает ограничение продолжительности операции в указанное время; отрицательное значение используется как относительное время; менее чем STD_INTERF_TM (5). Возвращается время останова чтения (атрибут "tm" массива) и массив объектов сообщений/нарушений со свойствами:
  - tm — время сообщения, секунды;
  - utm — время сообщения, микросекунды;
  - categ — категория сообщения;
  - level — уровень сообщения;
  - mess — текст сообщения.
- bool messPut( int tm, int utm, string cat, int lev, string mess, string arch = "" ); — записывает сообщение mess с категорией cat, уровнем lev (-7...7) и временем tm.utm в архиваторы arch (разделены символом ';') и/или список нарушений.

Функции объекта архиватора сообщений (SYS.Archive["mod_Modul"]["mess_Archivator"]):

- ElTp cfg( string nm ) — получает значение конфигурационного поля nm объекта.
- bool cfgSet( string nm, ElTp val ) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение val.
- bool status( ) — статус архиватора "Исполнение".
- int end( ) — время окончания данных архиватора.
- int begin( ) — время начала данных архиватора.

Функции объекта архиватора значений (SYS.Archive["val_Modul"]["val_Archivator"]):

- ElTp cfg( string nm ) — получает значение конфигурационного поля nm объекта.
- bool cfgSet( string nm, ElTp val ) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение val.
- bool status( ) — статус архиватора "Исполнение".

Функции объекта архива (SYS.Archive["va_Archive"]):

- ElTp cfg( string nm ) — получает значение конфигурационного поля nm объекта.
- bool cfgSet( string nm, ElTp val ) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение val.
- bool status( ) — статус архиватора "Исполнение".
- int end( string arch = "" ) — время конца данных архива для архиватора arch, в микросекундах.
- int begin( string arch = "" ) — время начала данных архива для архиватора arch, в микросекундах.
- int period( string arch = "" ) — период данных архива для архиватора arch, в микросекундах.
- TArrayObj archivatorList( ) — список архиваторов, использующих данный архив как источник.
- VarType getVal( int tm, bool up_ord = false, string arch = "" ) — получает значение из архива на время tm, подтяжкой к верху up_ord и архиватора arch:
  - tm — время запрашиваемого значения, в микросекундах, установить в 0 для "end()"; этот атрибут также является выходом, соответственно реальное время полученного значения помещается сюда, если это переменная;
  - up_ord — подтягивать время запрашиваемого значения к верху сетки;
  - arch — архиватор запроса, установить в пустую строку для проверки всех архиваторов, установить в "<buffer>" для обработки только буфера.
- bool setVal( int tm, VarType vl, string arch = "" ) [доступ к подсистеме Архивы-История] — устанавливает значение vl в архив на время tm и архиватор arch:
  - tm — время устанавливаемого значения, в микросекундах;
  - vl — значение;
  - arch — архиватор установки, установить в пустую строку для всех архиваторов, установить в "<buffer>" для обработки только буфера.
- Array getVals( int begTm, int endTm, int period, string arch = "" ) — получает архив/историю значений от begTm и по endTm для архиватора arch:
  - begTm — время начала запрошенного диапазона данных, в микросекундах, будет изменено в реальное начало данных;
  - endTm — время окончания запрошенного диапазона данных, в микросекундах;
  - period — период данных, в микросекундах, должно быть обязательно определено и будет использовано максимальное значение для этого архива, будет изменено в периодичность реальных данных;
  - arch — архиватор запроса, установить в пустую строку для проверки всех архиваторов, установить в "<buffer>" для обработки только буфера.
- bool setVals( Array buf, int tm, int period, string arch = "" ) [доступ к подсистеме Архивы-История] — устанавливает значение архиву/истории buf в архив от времени начала tm, для периода значений period и архиватора arch.
  - buf — массив значений к установке;
  - tm — время начала устанавливаемого диапазона данных, в микросекундах;
  - period — период устанавливаемых данных, в микросекундах, должно быть обязательно определено и будет использовано максимальное значение для этого архива, будет изменено в периодичность реальных данных;
  - arch — архиватор запроса, установить в пустую строку для проверки всех архиваторов, установить в "<buffer>" для обработки только буфера.

## 9 Subsystem "Transports" (SYS.Transport)

Functions of the subsystem object:

- TCntrNodeObj outAt( string addr ); — common-unified output transport connection at the address addr. At errors of creation the transport the function will return "false" when a correct node in it conversion to BOOLEAN will return "true". The address is specified 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 Подсистема "Протоколы" (SYS.Protocols)

### 10.1 Модуль Protocol.HTTP

Входная часть объекта модуля (SYS.Protocol.HTTP.{In})

- bool setUser( string user ) — меняет пользователя связанного с идентификатором сеанса аутентификации.
  - user — пользователя для смены.
- bool pgAccess(string URL) — проверяет доступность страницы, определённой в URL.
  - URL — URL страницы, которая проверяется.
- string pgCreator(string cnt, string rcode = "", string httpattrs = "Content-Type: text/html;charset={SYS}", string htmlHeadEls = "", string forceTmplFile = "") — формирует страницу или ресурс из содержимого cnt, обёрнутого в HTTP с результатом rcode, с дополнительными атрибутами HTTP httpattrs, дополнительным элементом заголовка HTML htmlHeadEls и использованием файла шаблона forceTmplFile.
  - cnt — содержимое страницы или ресурса (изображения, XML, CSS, JavaScript, ...);
  - rcode — результирующий код HTTP, вроде "200 OK"; пустое значение выключает добавление HTTP заголовка;
  - httpattrs — дополнительные атрибуты HTTP, в основном это "Content-Type" со значением по умолчанию "text/html;charset={SYS}"; только для "Content-Type: text/html" будет осуществляться заворачивание во внутренний/сервисный, или определённый forceTmplFile, HTML-шаблон;
  - htmlHeadEls — дополнительный тег заголовка HTML, в основном это META с "Refresh" для указанного URL;
  - forceTmplFile — файл прямо определённого шаблона для перекрытия внутреннего/сервисного или главной страницы.

## 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 Модуль QTStarter

Объект модуля (SYS.UI.QTStarter)

- Array sensors() — получить все доступные сенсоры от Qt mobility, возвращает "false" если не доступно ни одного сенсора.

### 11.2 Модуль 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. For missing and invalid widgets the function will return "false" when a correct widget in it conversion to BOOLEAN will return "true". 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.

Объект "Виджет", примитива "Документ" (this)

- string getArhDoc( int nDoc) — текст документа архива на глубине nDoc (0-{aSize-1}).

## 12 Подсистема "Специальные" (SYS.Special)

### 12.1 Модуль Библиотека системного API среды пользовательского программирования (Special.FLibSYS)

Объект "Библиотека функций" (SYS.Special.FLibSYS)

- ElTp {funcID}(ElTp prm1, ...) — вызов функции библиотеки {funcID}. Возвращает результат вызываемой функции.

Объект "Пользовательская функция" (SYS.Special.FLibSYS["funcID"])

- ElTp call(ElTp prm1, ...) — вызов данной функции с параметрами <prm{N}>. Возвращает результат вызываемой функции.

### 12.2 Модуль Библиотека стандартных математических функций (Special.FLibMath)

Объект "Библиотека функций" (SYS.Special.FLibMath)

- ElTp {funcID}(ElTp prm1, ...) — вызов функции библиотеки {funcID}. Возвращает результат вызываемой функции.

Объект "Пользовательская функция" (SYS.Special.FLibMath["funcID"])

- ElTp call(ElTp prm1, ...) — вызов данной функции с параметрами <prm{N}>. Возвращает результат вызываемой функции.

### 12.3 Модуль Библиотека функций совместимости со SCADA Complex1 фирмы ООО НИП "DIYA" (Special.FLibComplex1)

Объект "Библиотека функций" (SYS.Special.FLibComplex1)

- ElTp {funcID}(ElTp prm1, ...) — вызов функции библиотеки {funcID}. Возвращает результат вызываемой функции.

Объект "Пользовательская функция" (SYS.Special.FLibComplex1["funcID"])

- ElTp call(ElTp prm1, ...) — вызов данной функции с параметрами <prm{N}>. Возвращает результат вызываемой функции.

## 13 Библиотеки функций пользователя

На данное время OpenSCADA имеет библиотеки функций пользователя, написанные с использованием этого API пользователя. Некоторые из них разработаны для использования исключительно из этого API. Все библиотеки пользователя представлены в следующей таблице:

Наименование | Версия | Лицензия | Источник | Языки
--- | --- | --- | --- | ---
Библиотеки источников данных, служб и обработки
Основная библиотека | 2.3 | GPLv2 | OscadaLibs.db (SQL, GZip) > DAQ.tmplb_base | en, uk, ru
Библиотека промышленных устройств | 3.1 | GPLv2 | OscadaLibs.db (SQL, GZip) > DAQ.tmplb_DevLib | en, uk, ru
Библиотека низкоуровневых сенсоров и чипов | 1.6 | GPLv2 | OscadaLibs.db (SQL, GZip) > DAQ.tmplb_LowDevLib | en, uk, ru
Библиотека сервисных процедур | 1.2 | GPLv2 | OscadaLibs.db (SQL, GZip) > DAQ.JavaLikeCalc.servProc | en, uk, ru
Библиотека элементов регулирования | 1.0 | GPLv2 | OscadaLibs.db (SQL, GZip) > DAQ.JavaLikeCalc.regEl | en, uk, ru
Библиотека моделей аппаратов технологических процессов | 2.0 | GPLv2 | OscadaLibs.db (SQL, GZip) > DAQ.JavaLikeCalc.techApp | en, uk, ru
Библиотеки графических элементов OpenSCADA модуля UI.VCAEngine
Библиотека основных элементов интерфейса пользователя | 2.3 | GPLv2 | vcaBase.db (SQL, GZip) > VCA.wlb_Main | en, uk, ru
Библиотека элементов мнемосхем интерфейса пользователя | 1.0 | GPLv2 | vcaBase.db (SQL, GZip) > VCA.wlb_mnEls | en, uk, ru
Библиотека электрических элементов пользовательского интерфейса | 2.0 | GPLv2 | vcaElectroEls.db (SQL, GZip) > VCA.wlb_ElectroEls | en, uk, ru
Комбинированные библиотеки
Библиотека отчётов и документов | 2.0, 2.1 | GPLv2 | OscadaLibs.db (SQL, GZip) > DAQ.JavaLikeCalc.doc vcaBase.db (SQL, GZip) > VCA.wlb_doc | en, uk, ru
Рецепты | 1.1, 1.1 | GPLv2 | OscadaLibs.db (SQL, GZip) > DAQ.tmplb_PrescrTempl vcaBase.db (SQL, GZip) > VCA.wlb_prescr | en, uk, ru

## 14 Ссылки

- Диаграмма: Пользовательская объектная модель ядра OpenSCADA.

Documents/User_API/ru - GFDL | July 2026 | OpenSCADA 1+r3070