From OpenSCADAWiki
Jump to: navigation, search
This page is a translated version of the page Documents/User API and the translation is 93% complete.

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

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

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

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

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

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

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

Contents

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

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

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

  • десятичные: цифры 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), EVAL_REAL,EVAL(-1.79E308), EVAL_STR("<EVAL>")
Глобальные атрибуты параметров DAQ (начиная с подсистемы "DAQ" и в виде {Тип модуля DAQ}.{Объект контроллера}.{Параметр}.{Атрибут}).
Функции и параметры объектной модели OpenSCADA.

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 — оператор инициализации переменной; указание переменной без присваивания значения резервирует её со значением EVAL, что позволяет осуществлять одноразовую инициализацию сложных типов данных вроде объекта, через проверку на "isEVal()";
  • if — оператор условия "ЕСЛИ";
  • else — оператор условия "ИНАЧЕ";
  • while — определение цикла "ПОКА";
  • for — определение цикла "ДЛЯ";
  • in — разделитель цикла "ДЛЯ" для перебора свойств объекта;
  • break — прерывание выполнения цикла;
  • continue — продолжить выполнение цикла с начала;
  • function — определение внутренней функции;
  • using — позволяет установить область видимости внешних функций часто используемой библиотеки (using Special.FLibSYS;) для последующего обращения только по имени функции, не имеет эффекта для объектного доступа;
  • return — прерывание функции и возврат результата, который копируется в атрибут с флагом возврата (return 123;); в середине внутренней функции осуществляется её завершение с указанным результатом;
  • new — создание объекта, реализовано для: общий объект "Object", массив "Array" и регулярные выражения "RegExp";
  • delete — удаление/освобождение объекта или его свойств, при этом: внутренние переменные устанавливаются в 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==EVAL)?0:b) + ((c==EVAL)?0:c) + ((d==EVAL)?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"], для символов операций в названии. Чтение неопределённого свойства вернёт 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( ); — проверяет значение на "EVAL".
    • string toString(); — представляет значение в виде строки "true" или "false".
  • real toReal(); — читает логическое значение как вещественное число.
  • int toInt(); — читает логическое значение как целое число.
  • Целое и вещественное число:
Свойства:
  • MAX_VALUE — максимальное значение;
  • MIN_VALUE — минимальное значение;
  • NaN — недостоверное значение.
Функции:
  • bool isEVal(); bool isNaN( ); — проверяет значение на "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(); — читает целое-вещественное значение как целое число.
  • Строка:
Свойства:
  • int length — длина строки.
Функции:
  • bool isEVal(); — проверяет значение на "EVAL".
  • bool isNaN( bool whole = true ); — проверяет строку на не число, и в целом whole.
  • string charAt( int symb, string type = "" ); — достаёт из строки символ под номером symb типа type. Следующие типы символа поддерживаются: ""-ASCII и простой один байт, UTF-8, UTF-16, UTF-32. В случае с UTF-8, позиция символа symb меняется в позицию следующего символа поскольку длина символов этого типа переменная.
  • int charCodeAt( int symb, string type = "" ); — достаёт из строки код символа symb типа type. Следующие типы символа поддерживаются: ""-ASCII и простой один байт, UTF-8, UTF-16, UTF-16LE, UTF-16BE, UTF-32, UTF-32LE, UTF-32BE. В случае с UTF-8, позиция символа symb меняется в позицию следующего символа поскольку длина символов этого типа переменная.
  • string concat( string val1, string val2, ... ); — возвращает новую строку, сформированную путём присоединения значений val1 и т.д. к исходной.
  • int indexOf( string substr, int start = 0 ); — возвращает позицию искомой строки substr в исходной строке, начиная с позиции start. Если исходная позиция не указана то поиск начинается с начала. Если искомой строки не найдено то возвращается "-1".
  • int lastIndexOf( string substr, int start = {end} ); — возвращает позицию искомой строки substr в исходной строке, начиная с позиции start, при поиске с конца. Если исходная позиция не указана то поиск начинается с конца. Если искомой строки не найдено то возвращается "-1".
  • int search( string pat, string flg = "" ); — ищет в строке по шаблону pat и флагами шаблона flg. Возвращает положение найденной подстроки иначе "-1".
var rez = "Java123Script".search("script","i");  // rez = 7
  • int search( RegExp pat ); — ищет в строке по шаблону "RegExp" pat. Возвращает положение найденной подстроки иначе "-1".
var rez = "Java123Script".search(new RegExp("script","i"));  // rez = 7
  • Array match( string pat, string flg = "" ); — ищет в строке по шаблону pat и флагами шаблона flg. Возвращает массив с найденной подстрокой (0) и подвыражениями (>1). Атрибут "index" массива устанавливается в позицию найденной подстроки. Атрибут "input" устанавливается в исходную строку. Атрибут "err" устанавливается в код ошибки операции.
var rez = "1 плюс 2 плюс 3".match("\\d+","g");  // rez = [1], [2], [3]
  • Array match( TRegExp pat ); — ищет в строке по шаблону "RegExp" pat. Возвращает массив с найденной подстрокой (0) и подвыражениями (>1). Атрибут "index" массива устанавливается в позицию найденной подстроки. Атрибут "input" устанавливается в исходную строку. Атрибут "err" устанавливается в код ошибки операции.
var rez = "1 плюс 2 плюс 3".match(new RegExp("\\d+","g"));  // rez = [1], [2], [3]
  • string slice( int beg, int end ); string substring( int beg, int end ); — возвращает подстроку извлечённую из исходной, начиная с позиции beg и по end (не включая), нумерация с нуля. Если значение начала или конца отрицательно, то отсчёт ведётся с конца строки. Если конец не указан, то концом является конец строки. Например, конструкция substring(-2) вернет последние два символа строки.
  • Array split( string sep, int limit ); — возвращает массив элементов строки, разделённых sep и с ограничением количества элементов limit.
  • Array split( RegExp pat, int limit ); — возвращает массив элементов строки, разделённых шаблоном "RegExp" pat и с ограничением количества элементов limit.
rez = "1,2, 3 , 4 ,5".split(new RegExp("\\s*,\\s*"));  // rez = [1], [2], [3], [4], [5]
  • string insert( int pos, string substr ); — вставляет подстроку substr в позицию pos текущей строки.
  • string replace( int pos, int n, string str ); — заменяет подстроки с позиции pos и длиной n в текущей строке, на строку str.
rez = "Javascript".replace(4,3,"67");  // rez = "Java67ipt"
  • string replace( string substr, string str ); — заменяет все подстроки substr на строку str.
rez = "123 321".replace("3","55");  // rez = "1255 5521"
  • string replace( RegExp pat, string str ); — заменяет подстроки по шаблону pat на строку str.
rez = "value = \"123\"".replace(new RegExp("\"([^\"]*)\"","g"),"``$1''"));  // rez = "value = ``123''"
  • real toReal(); — преобразует текущую строку в вещественное число.
  • int toInt( int base = 10 ); — преобразует текущую строку в целое число, в соответствии с основанием base (от 2 до 36). Если основание равно 0 то будет учитываться префиксная запись для определения основания (123-десятичное; 0123-восьмеричное; 0x123-шестнадцатеричное).
  • string {parse,parseEnd}( int pos, string sep = ".", int off = {0,{length}}, bool mergeSepSymb = false ); — выделяет из исходной строки элемент pos, для разделителя элементов sep и от смещения off (останов на начале следующего токена, или конца для parseEnd). mergeSepSymb определяет разрешение объединения группы одинаковых символов в один разделитель. Результирующее смещение помещается назад в off. parseEnd() делает тоже самое, но с конца.
  • string parseLine( int pos, int off = 0 ); — выделяет строку с номером pos и от смещения off (останов на начале следующего токена). Результирующее смещение помещается назад в off.
  • string parsePath( int pos, int offCmptbl = 0, int off = 0 ); — выделяет из исходного пути элемент pos и от смещения off (останов на начале следующего токена) или offCmtbl (останов на следующем символе конца текущего токена — для совместимости). Результирующее смещение помещается назад в off или offCmtbl.
  • string parsePathEnd( int pos, int off = {length} ); — выделяет из конца строки исходного пути элемент pos и от смещения off (останов на конце следующего токена). Результирующее смещение помещается назад в off.
  • string path2sep( string sep = "." ); — преобразует путь в текущей строке в строку с разделителем sep.
  • string trim( string cfg = " \n\t\r" ); — обрезает строку с начала и конца, для символов cfg.


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

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

Массив предоставляет специальное свойство "length", для получения размера массива "var = arr.length;". Также массив предоставляет следующие функции:

  • string join( string sep = "," ), string toString( string sep = "," ), string valueOf( string sep = "," ) — возвращает строку с элементами массива, разделёнными sep или символом ','.
  • Array concat( Array arr ); — добавляет к исходному массиву элементы массива arr. Возвращает исходный массив с изменениями.
  • int push( ElTp var, ... ); — помещает элемент(ы) var в конец массива, как в стек. Возвращает новый размер массива.
  • ElTp pop( ); — удаляет последний элемент массива и возвращает его значения, как из стека.
  • Array reverse( ); — изменяет порядок расположения элементов массива. Возвращается исходный массив с изменениями.
  • ElTp shift( ); — сдвигает массив вверх, при этом первый элемент массива удаляется, а его значение возвращается.
  • int unshift( ElTp var, ... ); — задвигает элемент(ы) var в массив. Первый элемент в 0, второй в 1 и т.д.
  • Array slice( int beg, int end ); — возвращает фрагмент массива от beg к end (исключая). Если значение начала или конца отрицательно, то отсчёт ведётся с конца массива. Если конец не указан, то концом является конец массива.
  • Array splice( int beg, int remN, ElTp val1, ElTp val2, ... ); — вставляет, удаляет или заменяет элементы массива. Возвращает массив удалённых элементов. В первую очередь осуществляется удаление элементов с позиции beg и количеством remN, а затем вставляются значения val1 и т.д., начиная с позиции beg.
  • int indexOf( ElTp var, int start = 0 ); — возвращает индекс массиву нужной переменной var в исходной последовательности, начиная с позиции start. Если исходная позиция не указана то поиск начинается с начала. Если искомого значения не найдено то возвращается "-1".
  • int lastIndexOf( ElTp var, int start = {end} ); — возвращает индекс массива нужной переменной var в исходной последовательности, начиная с позиции start при поиске с конца. Если исходная позиция не указана то поиск начинается с конца. Если искомого значения не найдено то возвращается "-1".
  • double sum( int beg, int end ); — сумма значений части массива с позиции beg по end, исключая.
  • Array sort( ); — сортирует элементы массива в лексикографическом порядке.

2.2 Объект регулярного выражения (RegExp)

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

В качестве аргументов создания объекта передаётся строка с текстом регулярного выражения и флаги в виде строки символов:

  • 'g' — режим глобального поиска;
  • 'i' — режим регистронезависимого поиска;
  • 'm' — режим многострочного поиска;
  • 'u' — принудительное разрешение символов UTF-8, для других локалей;
  • 'p' — тестирование выражения по правила обычного шаблона с ключевыми символами: '?', '*' и '\'.

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

  • 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 (XMLNodeObj)

Функции:

  • string name( ) — имя узла, XML-тега.
  • string text( bool full = false ) — текст узла, содержимое XML-тега. Установить full для получения комбинированного текста со всех включенных узлов.
  • string attr( string id ) — значение атрибута узла id.
  • XMLNodeObj setName( string vl ) — устанавливает имя узла в vl. Возвращает текущий узел.
  • XMLNodeObj setText( string vl ) — устанавливает текст узла в vl. Возвращает текущий узел.
  • XMLNodeObj setAttr( string id, string vl ) — устанавливает атрибут id в значение vl. Возвращает текущий узел.
  • XMLNodeObj clear( bool full = false ) — очищает узел, удалением дочерних узлов, очищает текст и атрибуты, для full.
  • int childSize( ) — количество вложенных узлов.
  • XMLNodeObj childAdd( ElTp no = XMLNodeObj ); XMLNodeObj childAdd(string no) — добавляет объект no как вложенный. no может быть как непосредственно объектом-результатом функции "SYS.XMLNode()", так и строкой с именем нового тега. Возвращается вложенный узел.
  • XMLNodeObj childIns( int id, ElTp no = XMLNodeObj ); XMLNodeObj childIns(int id, string no) — вставляет объект no как вложенный, в позицию id. no может быть как непосредственно объектом-результатом функции "SYS.XMLNode()", так и строкой с именем нового тега. Возвращается вложенный узел.
  • XMLNodeObj childDel( int id ) — удаляет вложенный узел в позиции id. Возвращает текущий узел.
  • XMLNodeObj childGet( int id ) — получает вложенный узел в позиции id.
  • XMLNodeObj childGet( string name, int num = 0 ) — получает вложенный узел с именем тега name и порядковым номером num.
  • XMLNodeObj parent() — получает родительский узел.
  • string load( string str, bool file = false, int flg = 0, string cp = "UTF-8" ) — загружает XML из строки str или из файла с путём в str если file равно "true", с кодировкой cp. Где flg — флаги загрузки:
0x01 — полная загрузка, с блоками текста и комментариями в специальных узлах;
0x02 — не удалять пробелы в начале и конце текста тега.
  • string save( int flg = 0, string path = "", string cp = "UTF-8" ) — сохраняет дерево XML в строку или в файл path с параметрами форматирования flg и кодировкой cp. Возвращает текст XML или код ошибки. Предусмотрены следующие флаги форматирования flg:
0x01 — прерывать строку перед открывающим тегом;
0x02 — прерывать строку после открывающего тега;
0x04 — прерывать строку после закрывающего тега;
0x08 — прерывать строку после текста;
0x10 — прерывать строку после инструкции;
0x1E — прерывать строку после всех;
0x20 — вставлять стандартный XML-заголовок;
0x40 — вставлять стандартный XHTML-заголовок;
0x80 — очищать сервисные теги: <??>, <!-- -->;
0x100 — не кодировать наименований тегов;
0x200 — не кодировать наименований атрибутов;
0x400 — защита бинарных символов [\x0-\x8\xB-\xC\x0E-\x1F] и ошибочных UTF-8.
  • XMLNodeObj getElementBy( string val, string attr = "id" ) — получает элемент из дерева по атрибуту attr со значением val.
  • TArrayObj<XMLNodeObj> getElementsBy( string tag, string attrVal = "", string attr = "id" ) — получает массив элементов из дерева по тегу tag (пустой для всех) и атрибуту attr со значением attrVal (пустые для пропуска).

3 Программа-система (SYS)

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

  • {string|int} system( string cmd, bool noPipe = false); — вызывает консольные команды cmd ОС с возвратом результата по каналу. Если noPipe установлен то возвращается код возврата вызова и возможен запуск программ в фоне ("sleep 5 &"). Функция предоставляет пользователю OpenSCADA широкие возможности через вызов любых системных программ, утилит и скриптов, а также получения посредством них доступа к огромному объёму системных данных. Например команда "ls -l" вернёт детализированное содержимое рабочей директории.
  • int fileSize( string file ); — возвращает размер файла file.
  • string fileRead( string file, int off = 0, int sz = -1 ); — возвращает строку части файла file по смещению off и размером блока sz.
  • int fileWrite( string file, string str, bool append = false ); — записывает строку str в файл file, удаляя присутствующий файл или добавляя в него, append. Возвращает количество записанных байт.
  • int fileRemove( string file ); — удаляет файл file. Возвращает результат удаления.
  • int message( string cat, int level, string mess ); — формирует системное сообщение mess с категорией cat, уровнем level (-7...7). Отрицательное значение уровня формирует нарушения — "Alarm.
  • 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 ); — формирует системное сообщения mess с категорией cat и соответствующим к имени уровнем.
  • XMLNodeObj XMLNode( string name = "" ); — создаёт объект узла XML c именем name.
  • string cntrReq( XMLNodeObj req, string stat = "" ); — отправляет запрос интерфейса управления к программе-системе посредством XML. Обычный запрос записывается в виде <get path="/OPath/%2felem"/>. При указании станции в stat осуществляется запрос к указанной внешней станции. Адрес, атрибут "path", можно узнать в конфигураторе OpenSCADA, а именно в строке статуса, где этот адрес появляется при наведении курсора мыши на конфигурационное или информационное поле. Некоторые примеры распространённых запросов, больше примеров в releaseTests():
    • Чтение значения элемента (имя пользователя "test"):
      req = SYS.XMLNode("get").setAttr("path","/sub_Security/usr_test/%2fprm%2fDESCR");
      SYS.cntrReq(req);
      idSt = req.text();
      
    • Запись значения элемента (имя пользователя "test"):
      req = SYS.XMLNode("set").setAttr("path","/sub_Security/usr_test/%2fprm%2fDESCR").setText("New test user name");
      SYS.cntrReq(req);
      
    • Добавление нового узла (пользователя "test"):
      req = SYS.XMLNode("add").setAttr("path","/sub_Security/%2fbr%2fusr_").setText("test");
      SYS.cntrReq(req);
      
    • Удаление узла (пользователя "test"):
      req = SYS.XMLNode("del").setAttr("path","/sub_Security/%2fbr%2fusr_").setText("test");
      SYS.cntrReq(req);
      
    • Сохранение изменений узла в БД (пользователя "test"):
      req = SYS.XMLNode("save").setAttr("path","/sub_Security/usr_test/%2fobj");
      SYS.cntrReq(req);
      
    • Загрузка узла из БД (пользователя "test"):
      req = SYS.XMLNode("load").setAttr("path","/sub_Security/usr_test/%2fobj");
      SYS.cntrReq(req);
      
  • string lang(string full); — возврашает системный язык двумя символами и полный язык в full.
  • int sleep(real tm, int ntm = 0); — усыпляет поток исполнения на tm секунд (c точностью до наносекунд) и ntm наносекунд. Время сна можно установить не более STD_INTERF_TM (5 секунд).
  • int time( int usec ); — возвращает абсолютное время в секундах от эпохи 1.1.1970 и микросекунды в usec, если указан.
  • int utime( ); int mtime( ); — возвращает абсолютное время в микросекундах и миллисекундах от эпохи 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 ); — возвращает полную дату и время в секундах (sec), минутах (min), часах (hour), днях месяца (mday), месяце (month), годе (year), днях недели (wday), днях в году (yday) и признак летнего времени (isdst), исходя из абсолютного времени в секундах fullsec от эпохи 1.1.1970. gmtime возвращает время в GMT(UTC).
  • int {mktime|timegm}(int sec, int min, int hour, int mday, int month, int year, int wday, int yday, int isdst); — формирует время с эпохи 1.1.1970 из отдельно указанных секунд, минут, часов, дней, месяцев и т.д. Значения отдельных единиц времени могут указываться за границей их обычного диапазона, что позволяет использовать эту функцию при переборе, в последствии чего единицы времени будут откорректированы и возвращены в обычном диапазоне. timegm работает с временем в GMT(UTC).
  • string {strftime|strftimegm}( int sec, string form = "%Y-%m-%d %H:%M:%S" ); — преобразует абсолютное время sec в строку нужного формата form. Запись формата соответствует POSIX-функции strftime. strftimegm возвращает время в GMT(UTC).
  • int {strptime|strptimegm}( string str, string form = "%Y-%m-%d %H:%M:%S" ); — возвращает время в секундах от эпохи 1.1.1970, исходя из строковой записи времени str, в соответствии с указанным шаблоном form. Например, шаблону "%Y-%m-%d %H:%M:%S" соответствует время "2006-08-08 11:21:55". Описание формата шаблона можно получить из документации на POSIX-функцию strptime. strptimegm работает с временем в GMT(UTC).
  • int cron( string cronreq, int base = 0 ); — возвращает время, спланированное в формате стандарта Cron, cronreq, начиная от базового времени base или от текущего, если базовое не указано.
  • string strFromCharCode( int char1, int char2, int char3, ... ); — создаёт строку из кодов символов char1, char2 ... charN.
  • string strFromCharUTF([string type = "UTF-8",] int char1, int char2, int char3, ...); — создаёт строку из UTF-8 символов char1, char2 ... charN. Следующие типы символа поддерживаются: UTF-8, UTF-16, UTF-16LE, UTF-16BE, UTF-32, UTF-32LE, UTF-32BE.
  • string strCodeConv( string src, string fromCP, string toCP ); — перекодирует текст src из кодировки fromCP в toCP. Если кодировка опущена (пустая строка), то используется внутренняя.
  • string strEncode( string src, string tp = "Bin", string opt1 = "" ); — кодирует строку src по правилу tp и опции opt1. Доступные правила:
    "PathEl" — символы [/%] в "%2f" и "%25", соответственно;
    "HttpURL" — символы [ \t%] и "> 0x80" в "%20", "%09", "%25" и т.д.;
    "HTML" — символы HTML-сущностей [><"&'] в "&gt;", "&lt;", "&quot;" и т.д.;
    "JavaScript" — символ '\n' экранированием "\\n";
    "SQL" — экранирование-защита символов ['"`\], добавлением символа '\' или дублирование перечисленных в opt1 символов;
    "Custom" — символов указанных в opt1 в вид "%NN";
    "Base64" — бинарное кодирование в Base 64, где в opt1 устанавливается символ(ы) прерывания строки после 57 символов;
    "FormatPrint" — символ '%' в "%%";
    "OscdID" — почти все символы вроде [ /\&(] в '_';
    "Bin" — перечень ASCII байт ("XX XX XX XX ...") в бинарное представление;
    "Reverse" — инверсия последовательности;
    "ShieldSimb" — защищённые символы вида '\a', '\b', ..., '\0NNN', '\xNN' в бинарное представление;
    "ToLower" — символы к нижнему регистру;
    "Limit" — ограничение строки длиной в opt1, учитывая переменную длину UTF-8;
    "ShieldBin" — защита бинарных символов [\x0-\x8\xB-\xC\x0E-\x1F].
  • string strDecode( string src, string tp = "Bin", string opt1 = "" ); — декодирует строку src по правилу tp и опции opt1. Доступные правила:
    "PathEl", "HttpURL", "Custom" — символы вида "%NN" в бинарное представление;
    "Base64" — соответственно из Base 64;
    "Bin" — бинарную строку в ASCII байты ("XX XX XX XX .. A.b.c.."), opt1 указывает на разделитель или "<text>", для включения смещения слева и текстовой части справа.

4 Любой объект (TCntrNode) дерева OpenSCADA (SYS.*)

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

  • TArrayObj nodeList( string grp = "", string path = "" ); — возвращает список идентификаторов дочерних узлов для группы grp и узла по пути path. Если grp пусто то возвращаются узлы всех групп.
  • TCntrNodeObj nodeAt( string path, string sep = "" ); — подключает к узлу path в дереве объектов OpenSCADA (рис.1). Если указывается разделитель в sep то путь обрабатывается как строка с разделителем. Для отсутствующих и некорректных узлов эта функция будет возвращать "false", тогда как корректный узел, при преобразовании в BOOLEAN, вернёт "true".
  • TCntrNodeObj nodePrev( ); — возвращает предыдущий-родительский узел.
  • string nodePath( string sep = "", bool from_root = true ); — возвращает путь к текущему узлу в дереве объектов OpenSCADA (рис.1). Символ разделителя указывается в sep для получения пути через разделитель, например — "DAQ.ModBus.PLC1.P1.var", иначе — "/DAQ/ModBus/PLC1/P1/var". from_root указывает на необходимость формировать путь от корня и без указания идентификатора станции.
  • int messSys( int level, string mess ) — формирует системное сообщение mess с уровнем level, с путём узла в качестве категории и с читабельным путём перед сообщением.

5 Подсистема "Безопасность" (SYS.Security)

Функции объекта подсистемы (SYS.Security):

  • int access( string user, int mode, string owner, string group, int access ) — проверяет доступ пользователя user к ресурсу, который принадлежит owner и group с доступом access и для режима mode:
user — пользователь проверки доступа;
mode — режим доступа (4-R, 2-W, 1-X);
owner — владелец ресурса;
group — группа ресурса;
access — режим доступа к ресурсу (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 Подсистема "БД" (SYS.BD)

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

  • ElTp cfg(string nm) — получает значение конфигурационного поля nm объекта.
  • bool cfgSet(string nm, ElTp val) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение val.
  • Array SQLReq( string req, bool tr = EVAL ); — осуществляет SQL-запрос req к БД, внутри (tr=true), вне (tr=false) или безразлично (tr=EVAL) к транзакции. Возвращает массив строк таблицы результата с полями по индексам и по именам колонок. В случае ошибки её значение помещается в свойство "err" результата.
    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 Подсистема "Сбор данных" (SYS.DAQ)

Функции объекта подсистемы (SYS.DAQ):

  • TCntrNodeObj daqAt(string path, string sep = "", waitForAttr = true) — подключается к DAQ узлу (объект контролера, параметр, атрибут) по пути path или разделённой строки по разделителю sep, от DAQ-подсистемы. Проверять на атрибут в конце пути, по waitForAttr.
  • bool funcCall( string progLang, TVarObj args, string prog, string fixId = "", string err = "" ); — исполняет текст функции prog с аргументами в объекте args на языке программирования progLang и с идентификатором фиксации fixId (автоматически если пустой). Возвращает "true" при корректном вызове, иначе "false" и устанавливается "err". Фиксированная функция отличается от автоматической тем, что она не удаляется после исполнения, а используется повторно по адресу в fixId, заменяющего оригинальный идентификатор при первом вызове. Для переформирования функции нужно изменить программу или очистить fixId в её оригинальный идентификатор.
    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); — запрос правил подсветки синтаксиса языка программы progLang в XML-теге SnthHgl.

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

  • ElTp cfg( string nm ) — получает значение конфигурационного поля nm объекта.
  • bool cfgSet( string nm, ElTp val ) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение val.
  • string name( ) — имя объекта контроллера.
  • string descr( ) — описание объекта и контроллера.
  • string status( ) — статус контроллера.
  • bool messSet( string mess, int lev, string type2Code = "OP", string prm = "", string cat = "") — устанавливает сообщение источника данных mess с уровнем lev, для параметра prm ({PrmId}), дополнительной информацией категории cat и кодом типа type2Code. Эта функция формирует сообщения с унифицированной категорией транспортирования через источник данных {type2Code}{ModId}:{CntrId}[.{PrmId}][:{cat}], где:
    • type2Code — двухсимвольный код типа сообщения, по умолчанию означает действие оператора "OP";
    • CntrId — идентификатор объекта контроллера;
    • PrmId — идентификатор параметра, из аргумента prm;
    • CntrNm — название объекта контроллера;
    • cat — дополнительная информация категории которую определено для типа type2Code.
  • bool alarmSet( string mess, int lev = -5, string prm = "", bool force = false ) — устанавливает/снимает нарушение mess с уровнем lev (отрицательный для установки иначе снятие), для параметра prm ({PrmId}\n{PrmNm}). Очистка нарушений, как и установка, работает в режиме переключателя, что предусматривает пропуск сообщений очистки в буфер сообщений, и саму очистку, только при наличии соответствующего нарушения, что может быть отключено установкой force. Функция формирует нарушение с категорией al{ModId}:{CntrId}[.{PrmId}] и текстом {CntrNm} > {PrmNm}: {MessText}, где:
    • ModId — идентификатор модуля;
    • CntrId — идентификатор объекта контроллера;
    • PrmId — идентификатор параметра, из аргумента prm;
    • CntrNm — название объекта контроллера;
    • PrmNm — название параметра, из аргумента prm;
    • MessText — текст сообщения.
  • bool enable( bool newSt = EVAL ) — получает состояние "Включен" или изменяет его назначением атрибута newSt.
  • bool start( bool newSt = EVAL ) — получает состояние "Имполняется" или изменяет его назначением атрибута newSt.

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

  • ElTp cfg( string nm ) — получает значение конфигурационного поля nm объекта.
  • bool cfgSet( string nm, ElTp val ) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение val.
  • TCntrNodeObj cntr( ) — возвращает объект контроллера этого параметра, независимо от вложенности.
  • bool messSet( string mess, int lev, string type2Code = "OP", string cat = "") — устанавливает сообщение источника данных mess с уровнем lev, для параметра.
  • bool alarmSet( string mess, int lev = -5, bool force = false ) — устанавливает/снимает нарушение mess с уровнем lev (отрицательный для установки иначе снятие) для этого параметра. Очистка нарушений, как и установка, работает в режиме переключателя, что предусматривает пропуск сообщений очистки в буфер сообщений, и саму очистку, только при наличии соответствующего нарушения, что может быть отключено установкой force.

Функции объекта атрибута параметра контроллера (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 Модуль DAQ.JavaLikeCalc

Объектная модель пользователя модуля JavaLikeCalc.

Объект "Библиотека функций" (SYS.DAQ.JavaLikeCalc["lib_Lfunc"])

  • ElTp {funcID}(ElTp prm1, ...) — вызывает функцию "funcID" библиотеки "Lfunc" с параметрами prm{N}. Возвращает результат вызываемой функции. Префикс "lib_" перед идентификатором библиотеки обязателен!

Объект "Пользовательская функция" (SYS.DAQ.JavaLikeCalc["lib_Lfunc"]["func"])

  • ElTp call(ElTp prm1, ...) — вызывает функцию "func" библиотеки "Lfunc" с параметрами prm{N}. Возвращает результат вызываемой функции. Префикс "lib_" перед идентификатором библиотеки обязателен!

7.2 Модуль DAQ.LogicLev

Объект "Параметр" [this]

  • bool attrAdd( string id, string name, string tp = "real", string selValsNms = "" ) [для включенного параметра логического типа] — добавление атрибута id с именем name и типом tp. Если атрибут уже присутствует то будут применены свойства, которые возможно изменить "на ходу": имя, режим выбора и параметры выбора.
    • id, name — идентификатор и имя нового атрибута;
    • tp — тип атрибута [boolean | integer | real | string | text | object] + режим выбора [sel | seled] + только для чтения [ro];
    • selValsNms — две строки со значениями в первой и их именами во второй, разделённые ";".
  • bool attrDel( string id ) [для включенного параметра логического типа] — удаление атрибута id.

7.3 Модуль DAQ.BlockCalc

Объектная модель пользователя модуля BlockCalc.

Объект "Блок" (SYS.DAQ.BlockCalc["cntr"]["blk_block"])

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

7.4 Модуль DAQ.ModBus

Объектная модель пользователя модуля ModBus.

Объект "Контроллер" [this.cntr()]

  • string messIO(string pdu) — отправка PDU pdu через транспорт объекта контроллера посредством ModBus протокола. PDU результата запроса помещается вместо запроса в pdu, а ошибка возвращается в результате функции.

Объект "Параметр" [this]

  • bool attrAdd( string id, string name, string tp = "real", string selValsNms = "" ) [для включенного параметра логического типа] — добавление атрибута id с именем name и типом tp. Если атрибут уже присутствует то будут применены свойства, которые возможно изменить "на ходу": имя, режим выбора и параметры выбора.
    • id, name — идентификатор и имя нового атрибута;
    • tp — тип атрибута [boolean | integer | real | string | text | object] + режим выбора [sel | seled] + только для чтения [ro];
    • selValsNms — две строки со значениями в первой и их именами во второй, разделённые ";".
  • bool attrDel( string id ) [для включенного параметра логического типа] — удаление атрибута id.

7.5 Модуль DAQ.Siemens

Объект "Параметр" [this]

  • bool attrAdd( string id, string name, string tp = "real", string selValsNms = "" ) [для включенного параметра логического типа] — добавление атрибута id с именем name и типом tp. Если атрибут уже присутствует то будут применены свойства, которые возможно изменить "на ходу": имя, режим выбора и параметры выбора.
    • id, name — идентификатор и имя нового атрибута;
    • tp — тип атрибута [boolean | integer | real | string | text | object] + режим выбора [sel | seled] + только для чтения [ro];
    • selValsNms — две строки со значениями в первой и их именами во второй, разделённые ";".
  • bool attrDel( string id ) [для включенного параметра логического типа] — удаление атрибута id.

7.6 Модуль DAQ.OPC_UA

Объект "Параметр" [this]

  • bool attrAdd( string id, string name, string tp = "real", string selValsNms = "" ) [для включенного параметра логического типа] — добавление атрибута id с именем name и типом tp. Если атрибут уже присутствует то будут применены свойства, которые возможно изменить "на ходу": имя, режим выбора и параметры выбора.
    • id, name — идентификатор и имя нового атрибута;
    • tp — тип атрибута [boolean | integer | real | string | text | object] + режим выбора [sel | seled] + только для чтения [ro];
    • selValsNms — две строки со значениями в первой и их именами во второй, разделённые ";".
  • bool attrDel( string id ) [для включенного параметра логического типа] — удаление атрибута id.


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

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 nm ) — getting the connection parameter nm.
  • bool setConPrm( string nm, ElTp val ) — setting the connection parameter nm to the val.
  • 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.
    At.png 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((trez=SYS.Transport.Serial.out_ttyUSB0.messIO("")).length) rez += trez;
    
  • string messIO( XMLNodeObj req, string prt ); — sends the requests req to the protocol prt to perform a communication session through the transport and in assistance of the protocol.
    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 = "200 OK", string httpattrs = "Content-Type: text/html;charset={SYS}", string htmlHeadEls = "", string forceTmplFile = "", string lang = "" ) — формирует страницу или ресурс из содержимого 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 — файл прямо определённого шаблона для перекрытия внутреннего/сервисного или главной страницы.
    • lang — язык интерфейса, который формируется.


11 Подсистема "Пользовательские интерфейсы" (SYS.UI)

11.1 Модуль QTStarter

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

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

11.2 Модуль UI.VCAEngine

User object model of the module 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. Into 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.

Объект "Виджет", примитива "Документ" (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.0 GPLv2 OscadaLibs.db (SQL, GZip) > DAQ.tmplb_base en, uk, ru
Библиотека промышленных устройств 2.5 GPLv2 OscadaLibs.db (SQL, GZip) > DAQ.tmplb_DevLib en, uk, ru
Библиотека низкоуровневых сенсоров и чипов 1.5 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.1 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 Ссылки