Модуль <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", "unsigned char", "char", "schar", "signed char";
- "uint8";
- "uint16", "ushort";
- "uint32", "uint", "ulong";
- "uint64";
- "int8", "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}>. Повертає результат викликаної функції.
Посилання