ПерекладМодуль <FLibSYS> підсистеми "Спеціальні"
| Модуль: | FLibSYS |
| Ім'я: | Бібліотека функцій системного API. |
| Тип: | Спеціальні |
| Джерело: | spec_FLibSYS.so |
| Версія: | 1.3.0 |
| Автор: | Роман Савоченко |
| Опис: | Надає бібліотеку системного API середовища користувацького програмування. |
| Ліцензія: | GPL |
Вступ
Спеціальний модуль FLibSYS надає в систему OpenSCADA статичну бібліотеку функцій для роботи з системою OpenSCADA на рівні її системного API. Ці функції можуть використовуватися у середовищі користувацького програмування системи OpenSCADA для організації неординарних алгоритмів взаємодії.
Для адресації до функції цієї бібліотеки можна використовувати статичну адресу виклику "Special.FLibSYS.{Func}()" або динамічну "SYS.Special.FLibSYS["{Func}"].call()", "SYS.Special.FLibSYS.{Func}()". Де {Func} — ідентифікатор функції у бібліотеці.
Нижче наведено опис кожної функції бібліотеки. Для кожної функції здійснювалася оцінка часу виконання. Вимірювання здійснювалося на системі з наступними параметрами: Athlon 64 3000+ (ALTLinux 4.0(32біт)) шляхом заміру загального часу виконання функції при виклику її 1000 разів. Вибірка здійснювалася із п'яти обчислень із округленням до меншого цілого. Час оточується кутовими дужками та вимірюється у мікросекундах.
1. Загальносистемні функції
1.1. Виклик консольних команд та утиліт операційної системи (sysCall)
Опис: Здійснює виклик консольних команд ОС. Функція відкриває широкі можливості користувачу OpenSCADA шляхом виклику будь-яких системних програм, утиліт та скриптів, а також отримання за посередництвом них доступу до величезного об'єму системних даних. Наприклад команда "ls -l" поверне деталізований вміст робочої теки.
Параметри:
| ID | Ім'я | Тип | Режим | По замовченню |
| rez | Результат | Рядок | Повернення | |
| com | Команда | Рядок | Вхід |
Приклад:
using Special.FLibSYS;
test=sysCall("ls -l");
messPut("Example",0,"Example: "+test);1.2. SQL запит (dbReqSQL)
Опис: Формування SQL-запиту до БД.
Параметри:
| ID | Ім'я | Тип | Режим | По замовченню |
| rez | Результат | Об'єкт(Масив) | Повернення | |
| addr | Адреса БД | рядок | Вхід | |
| req | SQL-запит | Рядок | Вхід |
1.3. Вузол XML (xmlNode)
Опис: Створення об'єкту вузла XML.
Параметри:
| ID | Ім'я | Тип | Режим | По замовченню |
| rez | Результат | Об'єкт(XMLNodeObj) | Повернення | |
| name | Ім'я | Рядок | Вхід |
Приклад:
using Special.FLibSYS;
//Створення об'єкту "get" вузла XML.
req = xmlNode("get");
//Створення об'єкту "get" вузла XML із створенням атрибутів.
//sub_DAQ/mod_ModBus/cntr_1/prm_1 — шлях згідно структури проекту
req = xmlNode("get").setAttr("path",);1.4. Запит інтерфейсу управління (xmlCntrReq)
Опис: Запит інтерфейсу управління до системи за посередництвом XML. Звичайний запит записується у вигляді "<get path="/OPath/%2felem"/>". При вказанні станції здійснюється запит до зовнішньої станції.
Параметри:
| ID | Ім'я | Тип | Режим | По замовченню |
| rez | Результат | Рядок | Повернення | |
| req | Запит | Об'єкт(XMLNodeObj) | Вихід | |
| stat | Станція | Рядок | Вхід |
Приклад:
using Special.FLibSYS;
//Отримання ознаки "Включений/Виключений" параметрау "1" контролеру "1" модуля "ModBus".
//sub_DAQ/mod_ModBus/cntr_1/prm_1 — шлях згідно структури проекту
req = xmlNode("get").setAttr("path",);
rez = xmlCntrReq(req);
messPut("test",0,"Значення: "+req.text());
//Встановлення ознаки "Включений" параметру "1" контролеру "1" модуля "ModBus".
req = xmlNode("set").setAttr("path",).setText(1);
rez = xmlCntrReq(req);
//Встановлення ознаки "Виключений" параметру "1" контролеру "1" модуля "ModBus".
req = xmlNode("set").setAttr("path",).setText(0);
rez = xmlCntrReq(req);Переклад
1.5. Архив значений (vArh)
Описание: Получение объекта архива значений (VArchObj) путём подключения к архиву по его адресу.
Параметры:
| ID | Имя | Тип | Режим | По умолчанию |
| rez | Результат | Объект(VArchObj) | Возврат | |
| name | Имя, адрес к атрибуту параметра с архивом (DAQ.{Module}.{Cntr}.{Prm}.{Attr}) или непосредственно к архиву значений (Archive.va_{ValArchive}). | Строка | Вход |
Объект VArchObj
Функции:
- bool isNull() — объект не инициирован.
- int begin( int usec = 0, string archivator = "" ) — получение времени начала архива путём возврата секунд и микросекунд usec для архиватора archivator.
- int end( int usec = 0, string archivator = "" ) — получение времени окончания архива путём возврата секунд и микросекунд usec для архиватора archivator.
- int period( int usec = 0, string archivator = "" ) — получение периодичности архива путём возврата секунд и микросекунд usec для архиватора archivator.
- ValObj get( int sec, int usec, bool upOrd = false, string archivator = "" ) — получение значения из архива на время sec:usec с привязкой к верху upOrd и для архиватора archivator. Реальное время полученного значения устанавливается в sec:usec.
- bool set( ValObj val, int sec, int usec ) — запись значения val в буфер архива на время sec:usec.
- bool copy( VArchObj src, int begSec, int begUSec, int endSec, int endUSec, string archivator = "" ) — копирование части исходного src архива или его буфера в текущий начиная с begSec:begUSec и заканчивая endSec:endUSec для архиватора archivator.
- ArrayObj FFT( int tm, real size, string archivator = "", int tm_usec = 0 ) — выполняет разложение в ряд Фурье с помощью FFT алгоритма. Возвращается массив амплитуд частот для окна значений из архива с временем начала tm:tm_usec (секунды:микросекунды), глубиной в историю архива size (секунд) и для архиватора archivator.
Пример:
using Special.FLibSYS; val = vArh(strPath2Sep(addr)).get(time,uTime,0,archivator); return val.isEval() ? "Пусто" : real2str(val,prec);
1.6. Буфер архива значений (vArhBuf)
Описание: Получение объекта буфера архива значений (VArchObj) для выполнения промежуточных операций над кадрами данных.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Объект(VArchObj) | Возврат | |
| tp | Тип значений архива (0-Boolean, 1-Integer, 4-Real, 5-String) | Целый | Вход | 1 |
| sz | Максимальный размер буфера | Целый | Вход | 100 |
| per | Периодичность буфера (в микросекундах) | Целый | Вход | 1000000 |
| hgrd | Режим "Жесткая сетка времени" | Логический | Вход | 0 |
| hres | Режим "Высокого разрешения времени (микросекунды)" | Логический | Вход | 0 |
1.7. Ввод/Вывод (IO)
Описание: Ввод/Вывод в: файл, строковый поток.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Объект(IO) | Возврат | |
| name | Имя файла или данные (для строкового потока) | Строка | Вход | |
| accs | Доступ к файлу (''-строковый поток;'r[+]'-чтение;'w[+]'-запись с нуля;'a[+]'-добавление;...) | Строка | Вход | |
| mFormat | Формат данных машины ('n'-сист. порядок;'b'-BigEndian;'l'-LittleEndian) | Целое | Вход | "n" |
| enc | Кодировка строки в файле | Логический | Вход |
IO объект
Значения:
- valType — типы значений:
- "uchar", "uint8", "unsigned char";
- "uint16", "ushort";
- "uint32", "uint", "ulong";
- "uint64";
- "char", "int8", "schar", "signed char", "integer*1";
- "int16", "short", "integer*2";
- "int32", "int", "long", "integer*4", "integer";
- "int64", "integer*8";
- "float", "float32", "single", "real*4";
- "double", "float64", "real*8", "real";
- accs — режим доступа и тип:
- '' — строковый поток;
- 'r[+]' — чтение;
- 'w[+]' — запись с нуля;
- 'a[+]' — добавление.
- mFormat — формат данных машины:
- 'n' — нативный;
- 'l' — LittleEndian;
- 'b' — BigEndian.
Свойства:
- length — длина потока;
- pos (w) — позиция чтения/записи потока.
- string (w) — полное значение строкового потока;
- mFormat (w) — формат данных машины;
- stringEncode (w) — кодировка подстрок файла/строки.
Функции:
- bool open(string name = "", string accs = "", string mFormat = "n", string enc = ""); — Открытие нового потока для строки или файла name.
- bool close(); — Закрытие потока.
- {string|int|real|Array[int|real]} read(string valType = "char", int cnt = -1, string mFormatEnc = "n|NoEnc"); — Чтение значения типа valType в количестве cnt для формата машины или входной кодировки строки mFormatEnc.
- {int|IO} {write|wr}({string|int|double|Array} vals, string valType = "char", string mFormatEnc = "n|NoEnc", int cnt = 1); — Запись значения(ий) vals для типа valType для формата машины или входной кодировки строки mFormatEnc, и повтора скалярных значений в количестве cnt.
2. Функции для работы с астрономическим временем
2.1. Строка времени (tmFStr) <3047>
Описание: Преобразует абсолютное время в строку нужного формата. Запись формата соответствует POSIX-функции strftime.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| val | Строка полной даты | Строка | Возврат | |
| sec | Секунды | Целый | Вход | 0 |
| form | Формат | Строка | Вход | %Y-%m-%d %H:%M:%S |
Пример:
using Special.FLibSYS;
test=tmFStr(SYS.time(),);
messPut("Example",0,"tmFStr(): "+test);2.2. Полная дата (tmDate) <973>
Описание: Возвращает полную дату в секундах, минутах, часах и т.д, исходя из абсолютного времени в секундах от эпохи 1.1.1970.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| fullsec | Полные секунды | Целый | Вход | 0 |
| sec | Секунды [0...59] | Целый | Выход | 0 |
| min | Минуты [0...59] | Целый | Выход | 0 |
| hour | Часы [0...23] | Целый | Выход | 0 |
| mday | День месяца [1...31] | Целый | Выход | 0 |
| month | Месяц [0...11] | Целый | Выход | 0 |
| year | Год, от 1900 | Целый | Выход | 0 |
| wday | День недели [0...6] | Целый | Выход | 0 |
| yday | День в году [0...365] | Целый | Выход | 0 |
| isdst | Летнее время | Целый | Выход | 0 |
Пример:
using Special.FLibSYS;
curMin=curHour=curDay=curMonth=curYear=0;
tmDate(tmTime(),0,curMin,curHour,curDay,curMonth,curYear);
messPut("test",0,"Текущая минута: "+curMin);
messPut("test",0,"Текущий час : "+curHour);
messPut("test",0,"Текущий день: "+curDay);
messPut("test",0,"Текущий месяц: "+curMonth);
messPut("test",0,"Текущий год: "+curYear);2.3. Абсолютное время (tmTime) <220>
Описание: Возвращает абсолютное время в секундах от эпохи 1.1.1970 и микросекундах, если usec установлен в неотрицательное значение.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| sec | Секунды | Целый | Возврат | 0 |
| usec | Микросекунды | Целый | Выход | -1 |
2.4. Конвертация времени из символьного представлении во время в секундах, от эпохи 1.1.1970 (tmStrPTime) <2600>
Описание: Возвращает время в секундах от эпохи 1.1.1970, исходя из строковой записи времени, в соответствии с указанным шаблоном. Например, шаблону "%Y-%m-%d %H:%M:%S" соответствует время "2006-08-08 11:21:55". Описание формата шаблона можно получить из документации на POSIX-функцию "strptime".
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| sec | Секунды | Целый | Возврат | 0 |
| str | Строка даты | Строка | Вход | |
| form | Формат записи даты | Строка | Вход | %Y-%m-%d %H:%M:%S |
Пример:
using Special.FLibSYS;
curMin=curHour=curDay=curMonth=curYear=0;
tmDate(tmTime(),0,curMin,curHour,curDay,curMonth,curYear);
test = tmStrPTime(""+curYear+"-"+(curMonth+1)+"-"+curDay+" 9:0:0",);
messPut("Example",0,"tmStrPTime(): "+test);2.5. Планирование времени в формате Cron (tmCron)
Описание: Возвращает время спланированное в формате стандарта Cron начиная от базового времени или от текущего если базовое не указано.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| res | Результат | Целый | Возврат | 0 |
| str | Запись в стандарте Cron | Строка | Вход | * * * * * |
| base | Базовое время | Целый | Вход | 0 |
2.6. Сон (tmSleep)
Описание: Короткий сон от наносекунд и до STD_INTERF_TM (5 секунд).
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| res | Результат | Целый | Возврат | 0 |
| tm | Время | Вещественный | Вход | 0 |
3. Функции работы с сообщениями
3.1. Запрос сообщений (messGet)
Описание: Запрос системных сообщений.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Объект(Массив) | Возврат | |
| btm | Время начала | Целое | Вход | |
| etm | Время конца | Целое | Вход | |
| cat | Категория сообщения | Строка | Вход | |
| lev | Уровень сообщения | Целый | Вход | |
| arch | Архиватор | Строка | Вход |
3.2. Генерация сообщения (messPut)
Описание: Формирование системного сообщения.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| cat | Категория сообщения | Строка | Вход | |
| lev | Уровень сообщения | Целый | Вход | |
| mess | Текст сообщения | Строка | Вход |
Пример:
rnd_sq_gr11_lineClr="red";
Special.FLibSYS.messPut("Example",1,"Event: "+rnd_sq_gr12_leniClr);4. Функции работы с строками
4.1. Получение размера строки (strSize) <114>
Описание: Используется для получения размера.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Целый | Возврат | |
| str | Строка | Строка | Вход |
Пример:
Special.FLibSYS.messPut("Example",1,"ReturnString: "+strSize("Example"));4.2. Получение части строки (strSubstr) <413>
Описание: Используется для получения части строки.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Строка | Возврат | |
| str | Строка | Строка | Вход | |
| pos | Позиция | Целый | Вход | 0 |
| n | Количество | Целый | Вход | -1 |
Пример:
using Special.FLibSYS;
test=strSubstr("Example", 0, strSize("Example")-1);
messPut("Example",1,"ReturnString: "+test);4.3. Вставка одной строки в другую (strInsert) <1200>
Описание: Используется для вставки одной строки в другую.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| str | Строка | Строка | Выход | |
| pos | Позиция | Целый | Вход | 0 |
| ins | Вставляемая строка | Строка | Вход |
4.4. Замена части строки другой (strReplace) <531>
Описание: Используется для замены части сроки другой строкой.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| str | Строка | Строка | Выход | |
| pos | Позиция | Целый | Вход | 0 |
| n | Количество | Целый | Вход | -1 |
| repl | Заменяющая строка | Строка | Вход |
4.5. Разбор строки по разделителю (strParse) <537>
Описание: Используется в разборе строки по разделителю.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Строка | Возврат | |
| str | Строка | Строка | Вход | |
| lev | Уровень | Целый | Вход | |
| sep | Разделитель | Строка | Вход | "." |
| off | Смещение | Целый | Выход |
Пример:
using Special.FLibSYS;
ExapleString="Example:123";
test=strParse(ExapleString,1,":");
messPut("Example",0,"strParse(): "+test);4.6. Разбор пути (strParsePath) <300>
Описание: Используется в разборе пути на элементы.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Строка | Возврат | |
| path | Путь | Строка | Вход | |
| lev | Уровень | Целый | Вход | |
| off | Смещение | Целый | Выход |
Пример:
using Special.FLibSYS;
test=strParsePath(path,0,"/");
messPut("Example",1,"strParsePath(): "+test);4.7. Путь в строку с разделителем (strPath2Sep)
Описание: Используется для преобразования пути в строку с разделителем.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Строка | Возврат | |
| src | Источник | Строка | Вход | |
| sep | Разделитель | Строка | Вход | "." |
Пример:
//Преобразуем значение "/ses_AGLKS/pg_so" атрибута "path" в значение "ses_AGLKS.pg_so"
using Special.FLibSYS;
test = strPath2Sep(path);
messPut("Example",0,"path: "+path);
messPut("Example",0,"strPath2Sep(): "+test);4.8. Кодирование строки в HTML (strEnc2HTML)
Описание: Используется для кодирования строки для использования в исходнике HTML.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Строка | Возврат | |
| src | Источник | Строка | Вход |
4.9. Кодирование текста в бинарный вид (strEnc2Bin)
Описание: Используется для кодирования текста в бинарный вид, из формата <00 A0 FA DE>.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Строка | Возврат | |
| src | Источник | Строка | Вход |
4.10. Декодирование текста из бинарного вида (strDec4Bin)
Описание: Используется для декодирования текста из бинарного вида в формат <00 A0 FA DE>.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Строка | Возврат | |
| src | Источник | Строка | Вход |
4.11. Преобразование вещественного в строку (real2str)
Описание: Используется для преобразования вещественного в строку.
Параметры:
| ID | Имя | Тип | Режим | По умолчанию |
| rez | Результат | Строка | Возврат | |
| val | Значение | Вещественное | Вход | |
| prc | Точность | Целое | Вход | 4 |
| tp | Тип | Строка | Вход | "f" |
4.12. Преобразование целого в строку (int2str)
Описание: Используется для преобразования целого в строку.
Параметры:
| ID | Имя | Тип | Режим | По умолчанию |
| rez | Результат | Строка | Возврат | |
| val | Значение | Целое | Вход | |
| base | База, поддерживаются: 8, 10, 16 | Целое | Вход | 10 |
4.13. Преобразование строки в вещественное (str2real)
Описание: Используется для преобразования строки в вещественное.
Параметры:
| ID | Имя | Тип | Режим | По умолчанию |
| rez | Результат | Вещественное | Возврат | |
| val | Значение | Строка | Вход |
4.14. Преобразование строки в целое (str2int)
Описание: Используется для преобразования строки в целое.
Параметры:
| ID | Имя | Тип | Режим | По умолчанию |
| rez | Результат | Целое | Возврат | |
| val | Значение | Строка | Вход | |
| base | Основа | Целый | Вход | 0 |
4.15. Циклический Избыточный Код (CRC)
Описание: Реализация Циклического Избыточного Кода для длин 8-64 бит.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Целое | Возврат | |
| data | Данные | Строка | Вход | |
| poly | Полином (реверсивный) | Целый | Вход | 40961 (0xA001) |
| width | Ширина | Целый | Вход | 16 |
| init | Инициализация | Целый | Вход | -1 (0xFFFFFFFFFFFFFFFF) |
4.16. Слепок сообщения 5 (MD5)
Описание: Расчёт слепка сообщения 5.
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Строка | Возврат | |
| data | Данные | Строка | Вход |
5. Функции работы с вещественным
5.1. Разделение float на слова (floatSplitWord) <56>
Описание: Разделение float (4 байтов) на слова (2 байта).
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| val | Значение | Вещественное | Вход | |
| w1 | Слово 1 | Целый | Выход | |
| w2 | Слово 2 | Целый | Выход |
5.2. Объединение float из слов (floatMergeWord) <70>
Описание: Объединение float (4 байтов) из слов (2 байта).
Параметры:
| ID | Параметр | Тип | Режим | По умолчанию |
| rez | Результат | Вещественное | Возврат | |
| w1 | Слово 1 | Целый | Вход | |
| w2 | Слово 2 | Целый | Вход |
6. API пользовательского программирования
Некоторые объекты модуля предоставляют функции пользовательского программирования.
Объект "Библиотека функций" (SYS.Special.FLibSYS)
- ElTp {funcID}(ElTp prm1, ...) — вызов функции библиотеки {funcID}. Возвращает результат вызываемой функции.
Объект "Пользовательская функция" (SYS.Special.FLibSYS["funcID"])
- ElTp call(ElTp prm1, ...) — вызов данной функции с параметрами <prm{N}>. Возвращает результат вызываемой функции.
Ссылки