До начала программирования в 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 объектов, предоставляемых модулями, описывается в собственной документации модулей и тут предоставляются ссылки на неё.
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( int pos, string sep = ".", int off = 0 ); — выделяет из исходной строки элемент pos, для разделителя элементов sep и от смещения off. Результирующее смещение помещается назад в off.
- string parseLine( int pos, int off = 0 ); — выделяет строку с номером pos и от смещения off. Результирующее смещение помещается назад в off.
- string parsePath( int pos, int off = 0 ); — выделяет из исходного пути элемент 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 — не кодировать наименований атрибутов.
- 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-сущностей [><"&'] в ">", "<", """ и т.д.;
- "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.
- 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);
Функции объекта контроллера (SYS.DAQ["Modul"]["Controller"]):
- ElTp cfg( string nm ) — получает значение конфигурационного поля nm объекта.
- bool cfgSet( string nm, ElTp val ) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение val.
- string name( ) — имя объекта контроллера.
- string descr( ) — описание объекта и контроллера.
- string status( ) — статус контроллера.
- 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 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.
Объект "Библиотека функций" (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_" перед идентификатором библиотеки обязателен!
Объект "Параметр" [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.
Объект "Блок" (SYS.DAQ.BlockCalc["cntr"]["blk_block"])
- ElTp cfg(string nm) — получение значения конфигурационного поля nm объекта.
- bool cfgSet(string nm, ElTp val) [доступ к соответствующей подсистеме] — установка конфигурационного поля nm объекта в значение val.
- TCntrNodeObj cntr() — возвращает объект контроллера этого параметра, независимо от вложенности.
Объект "Контроллер" [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.
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 Подсистема "Транспорты" (SYS.Transport)
Функции объекта входящего транспорта (SYS.Transport["Modul"]["in_Transp"]):
- ElTp cfg( string nm ) — получает значение конфигурационного поля nm объекта.
- bool cfgSet( string nm, ElTp val ) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля nm объекта в значение val.
- string status() — строка статуса транспорта.
- string addr( string vl = "" ) — адрес транспорта, устанавливает в непустое значение vl.
- string writeTo( string sender, string mess ) — отправляет сообщение mess отправителю sender, как ответ.
- TArrayObj assTrsList( ) — список связанных выходных транспортов с данным входящим.
Функции объекта исходящего транспорта (SYS.Transport["Modul"]["out_Transp"]):
- bool isNetwork() — признак — "Транспорт сетевой", что определяет таймауты в секундах.
- ElTp cfg(string nm) — получает значение конфигурационного поля nm объекта.
- bool cfgSet(string nm, ElTp val) [доступ к соответствующей подсистеме] — устанавливает конфигурационное поле nm объекта в значение val.
- string status() — строка статуса транспорта.
- bool start( bool vl = EVAL, int tm = 0 ) — возвращает статус исполнения, запускает/останавливает по vl (если не <EVAL>). Для запуска можно указывать особый таймаут tm.
- string addr( string vl = "" ) — адрес транспорта, устанавливает в непустое значение vl.
- string timings( string vl = "", isDef = true ) — тайминги транспорта, устанавливает в непустое значение vl и по умолчанию для isDef.
- int attempts( int vl = EVAL ) — попыток подключения транспорта, устанавливает в не-EVAL значение vl.
- string messIO( string mess, real timeOut = 0, int inBufLen = -1 ); — отправляет сообщения mess через транспорт с таймаутом ожидания ответа timeOut (в секундах) и читает ответ (буфер) размером inBufLen байт. В случае нулевого таймаута это время берётся из настроек исходящего транспорта. Отрицательное время timeOut (< -1e-3) отключает работу транспорта в режиме запрос/ответ и позволяет независимо читать/писать в буфер ВВ, с таймаутом чтения timeOut, в абсолютном значении. Для отрицательного inBufLen размер буфера устанавливается в STR_BUF_LEN(10000), а "0" выключает чтение вообще.
Если Ваш транспорт в ответ на запрос подразумевает получение данных частями тогда используйте эту функцию в одном потоке для нескольких устройств на одной шине-транспорте поскольку здесь не существует способа блокирования транспорта из пользовательского API. Один поток это объект контроллера подсистемы "Сбор данных", а модуль "Протокол пользователя" блокирует транспорт внутри перед выполнением своих пользовательских процедур.
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 ); — отправляет запрос req к протоколу prt для осуществления сеанса связи через транспорт посредством протокола.
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)
Входная часть объекта модуля (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)
Объект модуля (SYS.UI.QTStarter)
- Array sensors() — получить все доступные сенсоры от Qt mobility, возвращает "false" если не доступно ни одного сенсора.
Объект "Сеанс" ( this.ownerSess() )
- string user( ) — текущий пользователь сеанса.
- int alrmQuietance( int quit_tmpl, string wpath = "", bool ret = false ) — квитирует нарушение wpath с шаблоном quit_tmpl. Если wpath это пустая строка то производится глобальное квитирование. В строке wpath, через символ ';', могут быть перечислены адреса нескольких виджетов. При установке ret осуществляется возврат квитирования.
- int reqTm( ) — время последнего запроса в секундах от эпохи 1.1.1970.
- string reqUser( ) — пользователь последнего запроса.
- string reqLang( ) — язык последнего запроса.
- int userActTm( ) — время последнего действия пользователя в секундах от эпохи 1.1.1970.
- bool uiCmd( string cmd, string prm, string src ) — отправляет UI команду управления страницами, как: "open", "next", "prev"; детальнее смотрите в секции сообщений. Эта функция должна быть приоритетной для использования при контроле страницами перед прямой записью в атрибут страниц "pgOpen" и "pgOpenSrc" поскольку это единственный метод корректной работы с линкованными страницами.
Объект "Виджет" (this)
- TCntrNodeObj ownerSess( ) — объект сеанса данного виджета.
- TCntrNodeObj ownerPage( ) — объект родительской страницы данного виджета.
- TCntrNodeObj ownerWdg( bool base = false ) — объект родительского виджета данного виджета. При указании base будут возвращены и объекты страниц.
- TCntrNodeObj wdgAdd( string wid, string wname, string parent ) — добавляет виджет wid с именем wname на основе библиотечного виджета parent.
//Добавляет новый виджет на основе виджета текстового примитива
nw = this.wdgAdd("nw", "Новый виджет", "/wlb_originals/wdg_Text");
nw.attrSet("geomX", 50).attrSet("geomY", 50);
- bool wdgDel( string wid ) — удаляет виджет wid.
- TCntrNodeObj wdgAt( string wid, bool byPath = false ) — подключается к дочернему или глобальному виджету, посредством пути byPath. В случае глобального подключения можно использовать абсолютный или относительный путь к виджету. Точкой отсчёта абсолютного адреса выступает объект корня модуля "VCAEngine", а значит, первым элементом абсолютного адреса является идентификатор сеанса, который опускается. Относительный адрес берёт отсчёт от текущего виджета. Специальным элементом относительного адреса является элемент вышестоящего узла "..".
- Array attrList() — перечень атрибутов виджета.
- bool attrPresent( string attr ) — проверяет атрибут виджета attr на факт присутствия.
- ElTp attr( string attr, bool fromSess = false ) — значение атрибута виджета attr или из сеанса fromSess. Для отсутствующих атрибутов возвращается пустая строка.
- TCntrNodeObj attrSet( string attr, ElTp vl, bool toSess = false ) — устанавливает значение vl в атрибут виджета attr или в сеанс, для toSess. Возвращает текущий объект, для конкатенации функций установки.
- string link( string attr, bool prm = false ) — ссылка атрибута виджета attr. При установке prm запрашивает ссылку группы атрибутов (параметр), представленную указанным атрибутом.
- string linkSet( string attr, string vl, bool prm = false ) — устанавливает ссылку атрибута виджета attr. При установке prm осуществляется установка ссылки группы атрибутов (параметр), представленной указанным атрибутом.
//Устанавливает ссылку восьмого тренда параметром
this.linkSet("el8.name", "prm:/LogicLev/experiment/Pi", true);
- string mime( string addr, string type = "" ) — "mime" объект по адресу addr (прямая ссылка на ресурс или атрибут виджета с этой ссылкой) с типом в type, из таблицы сеанса или источника. Предназначено для редактирования "mime" объекта и подстановки его в контексте сеанса, например, изображений SVG.
- int mimeSet( string addr, string data, string type = "" ) — устанавливает "mime" объект в data с типом type по адресу 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 ); — формирует сообщения программы mess с категорией — путь к данному виджету.
Объект "Виджет", примитива "Документ" (this)
- string getArhDoc( int nDoc) — текст документа архива на глубине nDoc (0-{aSize-1}).
12 Подсистема "Специальные" (SYS.Special)
Объект "Библиотека функций" (SYS.Special.FLibSYS)
- ElTp {funcID}(ElTp prm1, ...) — вызов функции библиотеки {funcID}. Возвращает результат вызываемой функции.
Объект "Пользовательская функция" (SYS.Special.FLibSYS["funcID"])
- ElTp call(ElTp prm1, ...) — вызов данной функции с параметрами <prm{N}>. Возвращает результат вызываемой функции.
Объект "Библиотека функций" (SYS.Special.FLibMath)
- ElTp {funcID}(ElTp prm1, ...) — вызов функции библиотеки {funcID}. Возвращает результат вызываемой функции.
Объект "Пользовательская функция" (SYS.Special.FLibMath["funcID"])
- ElTp call(ElTp prm1, ...) — вызов данной функции с параметрами <prm{N}>. Возвращает результат вызываемой функции.
Объект "Библиотека функций" (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.4 |
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 Ссылки