OpenSCADAWiki: Doc/ОписаниеПрограммы/part5 ...

5. Общесистемное API пользовательского программирования.

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

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

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

Абстрактный объект представляет собой ассоциативный контейнер свойств и функций. Свойства могут содержать как данные четырёх базовых типов, так и другие объекты. Доступ к свойствам объекта обычно осуществляется посредством записи имён свойств через точку к объекту <obj.prop>, а также посредством заключения имени свойства в квадратные скобки <obj["prop"]>. Очевидно, что первый механизм статичен, а второй позволяет указывать имя свойства через переменную. Базовое определение объекта не содержит функций. Операции копирования объекта на самом деле делают ссылку на исходный объект. При удалении объекта осуществляется уменьшения счётчика ссылок, а при достижении счётчика ссылок нуля объект удаляется физически.

Разные компоненты могут доопределять базовый объект особыми свойствами и функциями. Стандартным расширением объекта является массив "Array".

Объект 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>.
• Array sort( ); — Сортировка элементов массива в лексикографическом порядке.

Объект RegExp

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

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

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

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

• source — Исходный шаблон регулярного выражения, только чтение.
• global — Признак глобального поиска, только чтение.
• ignoreCase — Признак игнорировать регистр символов при поиске, только чтение.
• multiline — Признак многострочного поиска, только чтение.
• 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");

Объект XMLNodeObj

Функции:

• string name( ) — Имя узла, XML-тега.
• string text( ) — Текст узла, содержимое XML-тега.
• string attr( string id ) — Значение атрибута узла <id>.
• XMLNodeObj setName( string vl ) — Установка имени узла в <vl>. Возвращает текущий узел.
• XMLNodeObj setText( string vl ) — Установка текста узла в <vl>. Возвращает текущий узел.
• XMLNodeObj setAttr( string id, string vl ) — Установка атрибута <id> в значение <vl>. Возвращает текущий узел.
• 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 parent() — Получить родительский узел.
• string load( string str, bool file = false, bool full = false, string cp = "UTF-8" ) — Загрузка XML из строки <str> или из файла с путём в <str> если <file> "true", с кодировкой <cp>. <full> — для полной загрузки, с блоками текста и комментариями в специальных узлах.
• string save( int opt = 0, string path = "", string cp = "UTF-8" ) — Сохранение дерева XML в строку или в файл <path> с параметрами форматирования <opt> и кодировкой <cp>. Возвращает текст XML или код ошибки. Предусмотрены следующие опции форматирования <opt>:
  • 0x01 — прерывать строку перед открывающим тегом;
  • 0x02 — прерывать строку после открывающего тега;
  • 0x04 — прерывать строку после закрывающего тега;
  • 0x08 — прерывать строку после текста;
  • 0x10 — прерывать строку после инструкции;
  • 0x1E — прерывать строку после всех;
  • 0x20 — вставлять стандартный XML-заголовок;
  • 0x40 — вставлять стандартный XHTML-заголовок.
• XMLNodeObj getElementBy( string val, string attr = "id" ) — получить элемент из дерева по атрибуту <attr> со значением <val>.

5.2. Система (SYS)

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

• string system( string cmd, bool noPipe = false); — осуществляет вызов консольных команд <cmd> ОС с возвратом результата по каналу. Если <noPipe> установлен то возвращается код возврата вызова и возможен запуск программ в фоне ("sleep 5 &"). Функция открывает широкие возможности пользователю OpenSCADA путём вызова любых системных программ, утилит и скриптов, а также получения посредством них доступа к огромному объёму системных данных. Например команда "ls -l" вернёт детализированное содержимое рабочей директории.
• string fileRead( string file ); — Возвращает содержимое файла <file> в строке.
• int fileWrite( string file, string str, bool append = false ); — Записывает строку <str> в файл <file>, удаляя присутствующий файл или добавляя в него <append>. Возвращает количество записанных байт.
• 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"/>. При указании станции осуществляется запрос к внешней станции.
  //Get the station identifier
req = SYS.XMLNode("get").setAttr("path","/%2fgen%2fid");
SYS.cntrReq(req);
idSt = req.text();

  
  
• string sleep(int tm, int ntm = 0); — усыпить поток исполнения на <tm> секунд и <ntm> наносекунд. Функция добавлено только для полноты и крайне не рекомендована к использованию, особенно в процедурах пользовательского интерфейса поскольку это приведет к блокированию интерфейса.
• int time( int usec ); — возвращает абсолютное время в секундах от эпохи 1.1.1970 и микросекундах, если <usec> указан.
• int localtime( 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.
• string strftime( int sec, string form = "%Y-%m-%d %H:%M:%S" ); — Преобразует абсолютное время <sec> в строку нужного формата <form>. Запись формата соответствует POSIX-функции strftime.
• int strptime( 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".
• int cron( string cronreq, int base = 0 ); — Возвращает время, спланированное в формате стандарта Cron <cronreq>, начиная от базового времени <base> или от текущего, если базовое не указано.
• string strFromCharCode( int char1, int char2, int char3, ... ); — Создание строки из кодов символов char1, char2 ... charN.
• string strCodeConv( string src, string fromCP, string toCP ); — Кодирование текста <src> из кодировки <fromCP> в <toCP>. Если кодировка опущена, то используется внутренняя.

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

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

• TArrayObj nodeList(string grp = "", string path = ""); — Получение списка дочерних узлов для группы <grp> и узла по пути <path>. Если <grp> пуста то возвращаются узлы всех групп.
• TCntrNodeObj nodeAt(string path, string sep=""); — Подключение к узлу <path> в дереве объектов OpenSCADA. Если указывается разделитель в <sep> то путь обрабатывается как строка с разделителем.
• TCntrNodeObj nodePrev(); — Получить предыдущий, родительский, узел.
• string nodePath(string sep = "", bool from_root = true); — Получение пути к текущему узлу, в дереве объектов OpenSCADA. Один символ разделителя указывается в <sep> для получения пути через разделитель, например, "DAQ.ModBus.PLC1.P1.var", иначе "/DAQ/ModBus/PLC1/P1/var". <from_root> указывает на необходимость формировать путь от корня и без указания идентификатора станции.

5.4. Подсистема "Безопасность" (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"]) и группы (SYS.Security["grp_Group"]):

• ElTp cfg(string nm) — получение значения конфигурационного поля <nm> объекта.
• ElTp cfgSet(string nm, ElTp val) — установка конфигурационного поля <nm> объекта в значение <val>.

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

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

• ElTp cfg(string nm) — получение значения конфигурационного поля <nm> объекта.
• ElTp cfgSet(string nm, ElTp val) — установка конфигурационного поля <nm> объекта в значение <val>.
• Array SQLReq( string req ); — Формирование SQL-запроса к БД.
  DBTbl=SYS.BD.MySQL.GenDB.SQLReq("SELECT * from DB;");
for(var i_rw = 0; i_rw < DBTbl.length; i_rw++)
{
  var rec = "";
  for( var i_fld = 0; i_fld < DBTbl[i_rw].length; i_fld++ )
    rec += DBTbl[i_rw][i_fld]+"\t";
  SYS.messDebug("TEST DB","Row "+i_rw+": "+rec);
  //> Get column value by name
  if(i_rw) SYS.messDebug("TEST DB: ","Row "+i_rw+": 'NAME'"+DBTbl[i_rw]["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".

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

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

• bool funcCall(string progLang, TVarObj args, string prog); — вызов текста функции <prog> с аргументами в объекте <args> для языка программирования <progLang>. Возвращает "true" при корректном вызове.
  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> объекта.
• ElTp cfgSet(string nm, ElTp val) — установка конфигурационного поля <nm> объекта в значение <val>.
• string name() — имя контроллера.
• string descr() — описание контроллера.
• string status() — статус контроллера.
• bool alarmSet(string mess, int lev = -5, string prm = "") — установка/снятие нарушения <mess> с уровнем <lev> (отрицательный для установки иначе снятие), для параметра <prm>.
• bool enable(bool newSt = EVAL) — получение состояния "Включен" или изменение его назначением атрибута <newSt>.
• bool start(bool newSt = EVAL) — получение состояния "Запущен" или изменение его назначением атрибута <newSt>.

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

• ElTp cfg(string nm) — получение значения конфигурационного поля <nm> объекта.
• ElTp cfgSet(string nm, ElTp val) — установка конфигурационного поля <nm> объекта в значение <val>.

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

• ElTp get( int tm = 0, int utm = 0, bool sys = false ) — запрос значения атрибута на время <tm:utm> и признаком системного доступа <sys>.
• 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> объекта.
• ElTp cfgSet(string nm, ElTp val) — установка конфигурационного поля <nm> объекта в значение <val>.

5.6.1. Модуль DAQ.JavaLikeCalc

5.6.2. Модуль DAQ.ModBus

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

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

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

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

• ElTp cfg(string nm) — получение значения конфигурационного поля <nm> объекта.
• ElTp cfgSet(string nm, ElTp val) — установка конфигурационного поля <nm> объекта в значение <val>.
• bool status() — получение статуса архиватора.
• int end() — поучение времени окончания данных архиватора.
• int begin() — поучение времени начала данных архиватора.

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

• ElTp cfg(string nm) — получение значения конфигурационного поля <nm> объекта.
• ElTp cfgSet(string nm, ElTp val) — установка конфигурационного поля <nm> объекта в значение <val>.

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

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

• ElTp cfg(string nm) — получение значения конфигурационного поля <nm> объекта.
• ElTp cfgSet(string nm, ElTp val) — установка конфигурационного поля <nm> объекта в значение <val>.

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

• ElTp cfg(string nm) — получение значения конфигурационного поля <nm> объекта.
• ElTp cfgSet(string nm, ElTp val) — установка конфигурационного поля <nm> объекта в значение <val>.
• string messIO( string mess, real timeOut = 0 ); — отправка сообщения <mess> через транспорт с таймаутом ожидания <timeOut> (в секундах). В случае нулевого таймаута это время берётся из настроек исходящего транспорта.
  rez=SYS.Transport.Serial.out_ttyUSB0.messIO(SYS.strFromCharCode(0x4B,0x00,0x37,0x40),0.2);
while(true)
{
  trez = SYS.Transport.Serial.out_ttyUSB0.messIO("");
  if( !trez.length ) break;
  rez+=trez;
}

  
  
• int 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());

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

5.9.1. Модуль UI.VCAEngine

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

5.10.1. Модуль Special.FLibSYS

5.10.2. Модуль Special.FLibMath

5.10.3. Модуль Special.FLibComplex1