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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1.2 Операции языка

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1.4.2 Циклы

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

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

{условие} — выражение, определяющее условие;

{тело цикла} — тело цикла множественного исполнения;

{пре-инициализ} — выражение предварительной инициализации переменных цикла;

{пост-вычисление} — выражение модификации параметров цикла после очередной итерации;

{переменная} — переменная, которая будет содержать имя свойства объекта при переборе;

{объект} — объект для которого осуществляется перебор свойств.

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

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

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

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

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

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

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

1.4.4 Специальные символы строковых переменных

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

"\n" — перевод строки;

"\t" — символ табуляции;

"\b" — забой;

"\f" — перевод страницы;

"\r" — возврат каретки;

"\\" — сам символ '\';

"\041" — символ '!', записанный восьмеричным числом;

"\x21" — символ '!', записанный шестнадцатеричным числом.

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

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

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

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

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

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

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

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

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

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

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

Свойства:

• MAX_VALUE — максимальное значение;
• MIN_VALUE — минимальное значение;
• NaN — недостоверное значение.

Функции:

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

• Строка:

Свойства:

• int length — длина строки.

Функции:

• bool isEVal(); — проверяет значение на null-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 node-tag object (XMLNodeObj)

Functions:

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

0x01 — full loading, with texts and comments blocks into special nodes;

0x02 — does not remove spaces from the begin and end of the tag text.

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

0x01 — end line before the opening tag;

0x02 — end line after the opening tag;

0x04 — end line after the closing tag;

0x08 — end line after the text;

0x10 — end line after the instruction;

0x1E — end line after all ones;

0x20 — inserts the standard XML-header;

0x40 — inserts the standard XHTML-header;

0x80 — cleans the service tags: <??>, <!-- -->;

0x100 — does not encode the tag name;

0x200 — does not encode the attribute;

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

• XMLNodeObj getElementBy( string val, string attr = "id" ) — gets an element from the tree by the attribute attr in value val.
• TArrayObj<XMLNodeObj> getElementsBy( string tag, string attrVal = "", string attr = "id" ) — gets an elements array from the tree by the tag (empty for all) and attribute attr in value attrVal (empty for pass).

3 Program-system (SYS)

Object functions:

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

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

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

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

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

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

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

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

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

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

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

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

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

  Where items by the order

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

  Where the item variants

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

  Examples

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

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

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

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

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

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

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

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

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

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

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

  "Reverse" — reversion the sequence;

  "ToLower" — symbols to the lower register;

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

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

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

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

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

  "Base64" — same from Base 64;

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

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

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

Object functions:

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

5 Подсистема "Безопасность" (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

Объект "Библиотека функций" (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

Объект "Блок" (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

Объект "Контроллер" [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.
• ElTp conPrm( string id, ElTp val = EVAL, string cfg = "" ) — common handling the connection time parameter id with setting to the value val at presence; request for configuration parameter of the connection time with registration at the first time from the configuration cfg in the form "{SRC}\n{NAME}\n{HELP}".
• bool setConPrm( string id, ElTp val ) — setting the connection time parameter id to the value val, only for compatibility.

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

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

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

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

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

10 Подсистема "Протоколы" (SYS.Protocols)

10.1 Модуль Protocol.HTTP

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

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

11 Subsystem "User interfaces" (SYS.UI)

Functions of the subsystem object:

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

11.1 Модуль QTStarter

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

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

11.2 Модуль UI.VCAEngine

Object "Session" ( this.ownerSess() )

• string user( ) — current session user.
• int alrmQuietance( int quit_tmpl, string wpath = "", bool ret = false ) — quiets of the violations wpath with the template quit_tmpl. If wpath is empty string then the global quietance makes. In the string wpath, by symbol ';', can be enumerated addresses of several widgets. When set the ret, the quietance return is performed.
• int reqTm( ) — last request time in seconds from the epoch of 1/1/1970.
• string reqUser( ) — last request user.
• string reqLang( ) — last request language.
• int userActTm( ) — last user action time in seconds from the epoch of 1/1/1970.
• bool uiCmd( string cmd, string prm, string src ) — sends a UI command of the pages managing, that is: "open", "next", "prev"; for more details see in the events section. This function must be in the priority of using to the pages managing before the direct writing to the page attributes "pgOpen" and "pgOpenSrc" due it is single method of the correct work with the linked pages.
• int period( bool isReal = false ) — getting the session processing period, isReal for the real one.

Object "Widget" (this)

• TCntrNodeObj ownerSess( ) — session object for the current widget.
• TCntrNodeObj ownerPage( ) — parent page object for the current widget.
• TCntrNodeObj ownerWdg( bool base = false ) — parent widget object for the current widget. If set base then returns the parent page objects also.
• TCntrNodeObj wdgAdd( string wid, string wname, string parent ) — adds the new widget wid with the name wname and based on the library widget parent.

//Adds the new widget, based at the text primitive
nw = this.wdgAdd("nw", "New widget", "/wlb_originals/wdg_Text");
nw.attrSet("geomX", 50).attrSet("geomY", 50);

• bool wdgDel( string wid ) — deletes the widget wid.
• TCntrNodeObj wdgAt( string wid, bool byPath = false ) — attaches to child or global widget, by the path byPath. 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. Все библиотеки пользователя представлены в следующей таблице:

14 Ссылки

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