Модуль <FLibSYS> подсистемы "Специальные"

Модуль:	FLibSYS
Имя:	Библиотека функций системного API.
Тип:	Специальные
Источник:	spec_FLibSYS.so
Версия:	1.4
Автор:	Роман Савоченко
Описание:	Предоставляет библиотеку системного API среды пользовательского программирования.
Лицензия:	GPL

Contents

Введение

1. Общесистемные функции

1.1. Вызов консольных команд и утилит операционной системы (sysCall)

1.2. DB: SQL запрос (dbReqSQL)

1.3. Узел XML (xmlNode)

1.4. Запрос интерфейса управления (xmlCntrReq)

1.5. Архив значений (vArh)

Объект VArchObj

1.6. Буфер архива значений (vArhBuf)

1.7. Ввод/Вывод (IO)

IO объект

2. Функции для работы с астрономическим временем

2.1. Строка времени (tmFStr) <3047>

2.2. Полная дата (tmDate) <973>

2.3. Абсолютное время (tmTime) <220>

2.4. Конвертация времени из символьного представлении во время в секундах, от эпохи 1.1.1970 (tmStrPTime) <2600>

2.5. Планирование времени в формате Cron (tmCron)

2.6. Сон (tmSleep)

3. Функции работы с сообщениями

3.1. Запрос сообщений (messGet)

3.2. Генерация сообщения (messPut)

4. Функции работы с строками

4.1. Получение размера строки (strSize) <114>

4.2. Получение части строки (strSubstr) <413>

4.3. Вставка одной строки в другую (strInsert) <1200>

4.4. Замена части строки другой (strReplace) <531>

4.5. Разбор строки по разделителю (strParse) <537>

4.6. Разбор пути (strParsePath) <300>

4.7. Путь в строку с разделителем (strPath2Sep)

4.8. Кодирование строки в HTML (strEnc2HTML)

4.9. Кодирование текста в бинарный вид (strEnc2Bin)

4.10. Декодирование текста из бинарного вида (strDec4Bin)

4.11. Преобразование вещественного в строку (real2str)

4.12. Преобразование целого в строку (int2str)

4.13. Преобразование строки в вещественное (str2real)

4.14. Преобразование строки в целое (str2int)

4.15. Циклический Избыточный Код (CRC)

4.16. Слепок сообщения 5 (MD5)

5. Функции работы с вещественным

5.1. Float: Разделение на слова (floatSplitWord)

5.2. Float: Объединение из слов (floatMergeWord)

5.3. Float: Извлечение (floatExtract)

6. API пользовательского программирования

Ссылки

Введение

Специальный модуль 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. DB: SQL запрос (dbReqSQL)

Описание: Формирование SQL-запроса req к БД addr, внутри (trans=true), вне (trans=false) или безразлично (trans=EVAL) к транзакции. В случае ошибки её значение помещается в свойство "err" результата.
Параметры:

ID	Имя	Тип	Режим	По умолчанию
rez	Результат	Объект(Массив)	Возврат
addr	Адрес БД, "{TypeDB}.{DB}"	Строка	Вход
req	SQL-запрос	Строка	Вход
trans	Транзакция	Логический	Вход	EVAL

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","/sub_DAQ/mod_ModBus/cntr_1/prm_1/%2fprm%2fst%2fen");

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","/sub_DAQ/mod_ModBus/cntr_1/prm_1/%2fprm%2fst%2fen"); rez = xmlCntrReq(req); messPut("test",0,"Значение: "+req.text()); //Установка признака "Включен" параметра "1" контроллера "1" модуля "ModBus". req = xmlNode("set").setAttr("path","/sub_DAQ/mod_ModBus/cntr_1/prm_1/%2fprm%2fst%2fen").setText(1); rez = xmlCntrReq(req); //Установка признака "Выключен" параметра "1" контроллера "1" модуля "ModBus". req = xmlNode("set").setAttr("path","/sub_DAQ/mod_ModBus/cntr_1/prm_1/%2fprm%2fst%2fen").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";
  • "char", "int8", "schar", "signed char", "integer*1";
  • "int16", "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(),"%d %m %Y"); 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","%Y-%m-%d %H:%M:%S"); 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)

Описание: Разделение float (4 байтов) на слова (2 байта).
Параметры:

ID	Параметр	Тип	Режим	По умолчанию
val	Значение	Вещественное	Вход
w1	Слово 1	Целый	Выход
w2	Слово 2	Целый	Выход

5.2. Float: Объединение из слов (floatMergeWord)

Описание: Объединение float (4 байтов) из слов (2 байта).
Параметры:

ID	Параметр	Тип	Режим	По умолчанию
rez	Результат	Вещественное	Возврат
w1	Слово 1	Целый	Вход
w2	Слово 2	Целый	Вход

5.3. Float: Извлечение (floatExtract)

Описание: Извлечение мантиссы и экспоненты из вещественного значения.
Параметры:

ID	Параметр	Тип	Режим	По умолчанию
magn	Размер	Вещественный	Возврат
val	Значение	Вещественный	Вход
exp	Экспонента	Целый	Выход

6. API пользовательского программирования

Некоторые объекты модуля предоставляют функции пользовательского программирования.


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

• ElTp {funcID}(ElTp prm1, ...) — вызов функции библиотеки {funcID}. Возвращает результат вызываемой функции.

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

• ElTp call(ElTp prm1, ...) — вызов данной функции с параметрами <prm{N}>. Возвращает результат вызываемой функции.

Ссылки

Referring pages:

Doc
Doc/DAQ
Doc/FLibSYS