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

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

Other languages:
English • ‎российский • ‎українська
Constr.png The translation checking and actualizing

Автор: Роман Савоченко

Contents

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

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

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

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

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

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

Разные компоненты могут доопределять базовый объект особыми свойствами и функциями. Стандартным расширением объекта является массив "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];

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

Свойства:
  • MAX_VALUE — максимальное значение;
  • MIN_VALUE — минимальное значение;
  • NaN — недостоверное значение.
Функции:
  • bool isEVal(); — Проверка значения на "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.
Свойства:
  • int length — длина строки.
Функции:
  • bool isEVal(); — Проверка значения на "EVAL".
  • string charAt( int symb ); — Извлекает из строки символ номер symb, нумерация символов с нуля.
  • int charCodeAt( int symb ); — Извлекает из строки код символа symb.
  • string concat( string val1, string val2, ... ); — Возвращает новую строку сформированную путём присоединения значений val1 и т.д. к исходной.
  • int indexOf( string substr, int start ); — Возвращает позицию искомой строки substr в исходной строке начиная с позиции start. Если исходная позиция не указана то поиск начинается с начала. Если искомой строки не найдено то возвращается "-1".
  • int lastIndexOf( string substr, int start ); — Возвращает позицию искомой строки 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" устанавливается в исходную строку.
var rez = "1 плюс 2 плюс 3".match("\\d+","g");  // rez = [1], [2], [3]
  • Array match( TRegExp pat ); — Поиск в строке по шаблону "RegExp" pat. Возвращает массив с найденной подстрокой (0) и подвыражениями (>1). Атрибут "index" массива устанавливается в позицию найденной подстроки. Атрибут "input" устанавливается в исходную строку.
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 ); — Вставка в позицию pos текущей строки подстроку substr.
  • 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 = 0 ); — Преобразование текущей строки в целое число, в соответствии с основанием 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.


1.1 Объект Array

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

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

1.2 Объект RegExp

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

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

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

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

1.3 Объект XMLNodeObj

Функции:

0x01 — полная загрузка, с блоками текста и комментариями в специальных узлах;
0x02 — не удалять пробелы в начале и конце текста тега.
0x01 — прерывать строку перед открывающим тегом;
0x02 — прерывать строку после открывающего тега;
0x04 — прерывать строку после закрывающего тега;
0x08 — прерывать строку после текста;
0x10 — прерывать строку после инструкции;
0x1E — прерывать строку после всех;
0x20 — вставлять стандартный XML-заголовок;
0x40 — вставлять стандартный XHTML-заголовок;
0x80 — очищать сервисные теги: <??>, <!-- -->;
0x100 — опускать кодирование наименований тегов;
0x200 — опускать кодирование наименований атрибутов.

2 Система (SYS)

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

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

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

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

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

user — пользователь для проверки доступа;
mode — режим доступа (4-R, 2-W, 1-X);
owner — владелец ресурса;
group — группа ресурса;
access — режим доступа к ресурсу (RWXRWXRWX — 0777).

Функции объекта пользователя (SYS.Security["usr_User"]):

Функции объекта группы (SYS.Security["grp_Group"]):

5 Подсистема "БД" (SYS.BD)

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

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

6 Подсистема "Сбор данных" (SYS.DAQ)

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

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

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

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

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

6.1 Модуль DAQ.JavaLikeCalc

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

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

6.2 Модуль DAQ.LogicLev

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

6.3 Модуль DAQ.BlockCalc

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

6.4 Модуль DAQ.ModBus

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

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


7 Подсистема "Архивы" (SYS.Archive)

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

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

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

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

8 Подсистема "Транспорты" (SYS.Transport)

Функции объекта входящего транспорта (SYS.Transport["Modul"]["in_Transp"]):

Функции объекта исходящего транспорта (SYS.Transport["Modul"]["out_Transp"]):

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

9.1 Модуль Protocol.HTTP

Именно этот объект модуля "Protocol.HTTP" [SYS.Protocol.HTTP.pgCreator()]


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

10.1 Модуль UI.VCAEngine

Object "Session" ( this.ownerSess() )

Объект "Виджет" (this)

//Добавить новый виджет на основе виджета текстового примитива
nw = this.wdgAdd("nw", "Новый виджет", "/wlb_originals/wdg_Text");
nw.attrSet("geomX", 50).attrSet("geomY", 50);
//Установить ссылку восьмого тренда параметром
this.linkSet("el8.name", "prm:/LogicLev/experiment/Pi", true);

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


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

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

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

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

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

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

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

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

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

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


At.png Link to DB API libraries ...