[?] РТС LUA API#

Предупреждение

В настоящее время документация в этом разделе дорабатывается.

Если Вам необходима документация по этой теме, то просьба сообщить об этом.

Скрипт – это описание программы без использования специальных средств для ее подготовки и выполнения.

Скрипты выполняются (интерпретируются) в программе непосредственно без предварительной подготовки дополнительными средствами.

В качестве синтаксического языка скрипта используется язык Lua, который является свободно распространяемым программным средством, поэтому предоставляется без каких либо гарантий в соответствии с лицензией (www.lua.org, http://www.lua.ru/doc).

Lua – это интерпретируемый язык программирования, разработанный подразделением Католического университета Рио-де-Жанейро (Computer Graphics Technology Group of Pontifical Catholic University of Rio de Janeiro in Brazil).

Lua является процедурным языком программирования, предоставляющим широкие возможности для объектно-ориентированной и функциональной разработки и обладающий всеми необходимыми выразительными средствами.

Lua является расширяемым языком и работает в среде исполнения, сокращенно называемой «хост».

Хост - это программа предоставляет доступ к структурам данных используемых в ней, специализированным функциям для манипулирования данными и позволяет запускать части кода, написанные на Lua.

Для получения подробной информации об особенностях применения языка рекомендуем обратиться к технической документации, доступной на официальном сайте Lua (www.lua.org).

В настоящее время язык LUA может применяться в следующий программах комплекса ПО:

С помощью языка LUA можно реализовывать алгоритмы обработки конфигурации в утилите Конфигуратор и реализовывать пользовательскую логику реакции на получение новых значений в утилите сервер РТС.

В текущей реализации, скрипты могут применяться для непрограммируемого (без использования дополнительных средств создания программ) и без вмешательства разработчика описания сложных взаимосвязей между измерениями значений различных переменных.

Скрипты позволяют:

обрабатывать каждое получаемое сервером значение до записи его в базу данных;
модифицировать получаемые значения «на лету» в зависимости от необходимости используемого алгоритма обработки;
генерировать команды управления для оборудования;
создавать новые измерения для любых переменных из конфигурации.

Учитывая, что язык Lua является легко расширяемым вне зависимости от разработчика, возможно решение очень широкого круга задач.

Для отладки алгоритмов реализованных с использованием языка LUA и предназначенных для исполнения в средах ПО IngortechSCADA предназначена утилита Отладчик скриптов LUA.

Сервис предоставляемый ПО#

Для того, чтобы можно было писать сложные алгоритмы управления и фильтрации данными, ПО предоставляет несколько видов сервисов доступа к внутренним данным.

Независимые глобальные переменные и константы

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

Сервисные процедуры, которые не зависят от конкретики данных, используемых в ПО в данный момент.

Можно рассматривать эти процедуры как набор утилит, которые позволяют выполнять узкий диапазон действий.
Независимые классы

Набор структур данных не относящихся к ПО RTS напрямую.

Эти классы можно использовать как отдельно от ПО так и при манипулировании с его данными.
Конфигурация RTS

Сервис доступа ко всем элементам конфигурации, используемой на сервере.

Этот элемент может быть использован только в корректно работающем ПО RTS.
Средства управления RTS

Набор процедур, которые позволяют выполнять специализированные задачи системы RTS (генерация команд, Генерация новых значений и т.д.).
Процедуры скрипта

Процедуры реализованные на языке скрипта, имеющие специальные имена и описанные параметры, которые будут вызываться автоматически из ПО сервера при выполнении определенных условий.

Эти процедуры являются основным местом, где выполняется весь алгоритм, реализуемый в скриптовом языке.

Глобальные переменные и константы#

Переменные и константы, которые существуют при запуске любого скрипта.

number isdebug
string platform

isdebug#

number isdebug

Переменная, определяющая контекст, в котором запущена программа скрипта.

Если переменная имеет не нулевое значение - это значит скрипт выполняется в отладчике.

platform#

string platform

Переменная, определяющая утилиту, в которой выполняется программа скрипта. Содержит текстовое обозначение утилиты, выполняющей программу скрипта. Строка может иметь следующие значения:

Идентификатор	Содержание строки	Утилита
LUA_NM_UNK	«unk»	Утилита неизвестна
LUA_NM_DEBUG	«dbg»	Отладчик
LUA_NM_SERVER	«svr»	Сервер РТС
LUA_NM_CONFIG	«cfg»	Конфигуратор РТС
LUA_NM_CFGEDIT	«opt»	Редактор конфигураций на основе LUA

Переменную platform можно использовать для проверки в процессе выполнения скрипта того, в какой утилите он выполняется для того, чтобы предпринять какие-то особые действия.

К примеру, при выполнении из программы РТС Сервер значения для всех переменных реального времени доступны и могут быть использованы без дополнительных проверок, в то время как при выполнении из программы Конфигуратор содержимое этой таблицы будет зависеть от этапа конфигурирования и для работы со значениями переменных требуются проверки наличия значений и корректности данных в них.

Глобальные процедуры#

Сервисные процедуры, которые не зависят от конкретики данных, используемых в ПО в данный момент.

Возвращаемое значение	Имя	Параметры
void	abort	()
boolean	AskYesNo	( формат [, …])
number	CfgInt	(имя[,значение])
string	CfgStr	(имя[, значение] )
boolean	contains	( таблица, значение )
void	dbg	( формат,… )
string	editor	( таблица[, текст] )
void	error	( «message», [«title»] )
string	FromOEM	( string )
string	getn	( объект, number )
string	GetScriptPath	()
string	GetStartupDir	()
string	input	( таблица[, текст] )
string,string	input2	( таблица[, текст[, текст1]] )
string	LastError	( [текст ошибки] )
void	library	( библиотека )
void	msg	( сообщение[,заголовок] )
void	printf	( формат, … )
void	print	( … )
table	str2table	( string )
string	table2str	( table )
string	ToOEM	( string )
void	use	( файл скрипта )

abort#

abort()

Прерывает выполнения скрипта с ошибкой «Операция отменена пользователем».

Программа вызвавшая скрипт сразу же получит управление и продолжит работу.

use#

use( файл скрипта )

Загружает и выполняет указанный файл программы.

Если имя файла задано без указания полного пути, то файл будет искаться в каталоге, относительном по сравнению с каталогом текущего выполняемого файла программы.

GetScriptPath#

string GetScriptPath()

Возвращает путь текущего выполняемого скрипта без завершающего символа \.

Можно использовать для обращения к файлам, расположенным относительно файла текущего скрипта.

GetStartupDir#

string GetStartupDir()

Возвращает путь файла, выполняющего скрипт (путь к основному файлу программы, такому как сервер, отладчик или конфигуратор) без завершающего символа \.

printf#

printf( формат,... )

Выводит в область лога форматированную строку.

Формат аналогичен формату в языке С.

Предупреждение

Тип формата должен точно совпадать с типом передаваемых переменных!

Т.е., к примеру, если указан символ формата %S то параметр должен быть строкой или типом, приводимым к строке. В противном случае будет сгенерирована ошибка выполнения.

print#

print( ... )

Выводит в область лога все переданные параметры по очереди.

Каждый вызов процедуры создает новую строку в области лога.

Предупреждение

Эта функция не использует форматированный вывод, который используется в функции printf. Функция print просто выводит все переданные ей параметры, без каких либо дополнительных разделителей и без обработки.

msg#

void msg( сообщение[,заголовок] )

Показывает сообщение с указанным текстом, кнопкой ОК и иконкой типа сообщение.

Если заголовок не указан, то будет использован текст «Сообщение!».

Информация

Эту функцию можно использовать в режиме работы программы в системе RTS. Сообщение будет показано в общем окне ошибок и сообщений и не остановит выполнение программы.

AskYesNo#

boolean AskYesNo( формат [, ...])

Функция форматирует текст в соответствии с форматом (см. форматирование текста в функции printf) и выводит интерактивный запрос с возможностью выбрать кнопки Да или Нет в качестве ответа.

Функция возвращает:

true – если выбран ответ Да
false – если выбран ответ Нет или диалог с вопросом закрыли без подтверждения.

value = 18;

if AskYesNo( "Введенное значение %d\nПродолжить?", value ) then
 printf( "continue" );
else
 printf( "abort" );
end

Приведенный пример приводит к показу диалога следующего содержания:

dbg#

dbg( формат, ... )

Функция аналогичная по параметрам и действию функции printf.

Отличие состоит в том, что текст выводится только при выполнении программы в отладчике.

При выполнении программы в рабочем режиме функция ничего не делает и игнорирует любые переданные ей параметры.

error#

error( "message", ["title"] )

Показывает сообщение с указанным текстом, кнопкой ОК и иконкой типа ошибка.

Если заголовок не указан, то будет использован текст «Ошибка!».

LastError#

string LastError( [текст ошибки] )

Возвращает строку с ошибкой для последней неудачной операции или устанавливает строку ошибки.

Предупреждение

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

Для функций, которые выполнились успешно, значение строки ошибки может быть произвольным.

-- Отправка переменной "v" на сервер RTS
rc = rts.NewValue( v )

-- Если ошибка обработки или неверно заданы параметры переменной
if rc ~= true then
-- Вывести в лог текст ошибки
    dbg( "== Error setting %s variable", nm );
    dbg( "== Error: %s", GetLastError() );
end

library#

void library( библиотека )

Загружает и инициализирует библиотеку функций.

Если средствами языка какие-то операции реализовать не удается то их можно реализовать на любом компилируемом языке и оформить в виде подключаемой библиотеки (DLL).

Эти библиотеки могут быть загружены в скрипт динамически и после этого функции библиотек станут доступны в скрипте.

библиотека:

имя файла загружаемой библиотеки.

Имя файла может содержать полный путь.

Если используются относительные пути то программа будет искать библиотеки с того каталога из которого запущена основная программа выполняющая скрипт.

CfgStr#

string CfgStr(имя[, значение] )

Читает или устанавливает настройку конфигурации из программы, в которой выполняется скрипт.

Функция предназначена для получения и установки значений настроек конкретной программы, которая выполняет LUA скрипт.

Настройки программы содержат большое количество разнообразных данных, описание и способы использования различных настроек описаны в документации по тем скриптам, для которых эти настройки предназначены.

Если значение указано, то настойка будет установлена в указанное значение. Если значение не указано, то функция вернет значение текущей настройки.

имя:

имя параметра настройки.

Имя должно точно совпадать с именем настройки, заданным при создании выполняющей программы;

значение:

значение.

Указанная настройка программы будет установлена в это значение.

CfgInt#

number CfgInt(имя[,значение])

Читает или устанавливает настройку конфигурации из программы, в которой выполняется скрипт.

Функция предназначена для получения значений настроек конкретной программы, которая выполняет LUA скрипт.

имя:

имя параметра настройки.

Имя должно точно совпадать с именем настройки, заданным при создании выполняющей программы;

значение:

значение.

Указанная настройка программы будет установлена в это значение.

contains#

boolean contains( таблица, значение )

Функция анализирует таблицу на вхождение указанного значения.

Если в таблице указанное значение найдено, то функция вернет true, если значения в таблице нет, то функция вернет false.

Значение, переданное для поиска может быть следующих типов: число, строка, логическое значение (boolean). Попытка поиска в таблице значения других типов приведут к ошибке выполнения программы.

Предупреждение

При анализе значения в таблице автоматического преобразования типов не производится. Т.е. даже если таблица содержит строку, которая может быть преобразована к числу, то эта строка не будет проверяться при поиске числового значения.

table2str#

string table2str( table )

Собирает одну строку из всех строковых элементов таблицы.

Процедура последовательно, начиная с нуля, перебирает все элементы таблицы и соединяет их в единую строку. Если какой-то элемент таблицы не может быть преобразован к строке, то он будет проигнорирован.

str2table#

table str2table ( string )

Преобразует переданную строку в таблицу, где каждый элемент таблицы является отдельной буквой строки. Все элементы таблицы являются строками из одного символа.

Если переданный параметр не является строкой, будет сгенерировано сообщение об ошибке.

Индексом в таблице является номер символа в строке. Нумерация в таблице начинается с нуля, т.е. первый символ стоки будет иметь индекс «0».

getn#

string getn( объект, number )

Возвращает символ строки в указанной позиции.

Если первый параметр функции строка, то возвращает строку, состоящую из единственного символа, соответствующего символу в переданной строке по указанному индексу.

Если указанный индекс выходит за пределы строки, то функция вернет nil.

Предупреждение

Первый элемент строки имеет индекс 0.

ToOEM#

string ToOEM( string )

Перекодирует переданную в качестве параметра строку из кодировки WIN (Windows-1251) в кодировку DOS (OEM-866).

FromOEM#

string FromOEM( string )

Перекодирует переданную в качестве параметра строку из кодировки DOS (OEM-866) в кодировку WIN (Windows-1251).

input#

string input( таблица[, текст] )

Функция выводит интерактивный диалог с возможностью редактирования текста переданного в качестве параметра и возвращает строку, которая содержит:

текст измененный пользователем при работе диалога, если операция редактирования была подтверждена.
оригинальный текст, если операция редактирования была отменена.

таблица:

содержит данные о формате диалога ввода

текст:

начальное значение редактируемого текста.

Текст может быть не задан в качестве параметра, в таком случае используется соответствующее значение из таблицы параметров.

Предупреждение

Возможности узнать изменил пользователь данные или отменил редактирование – не существует.

Таблица параметров может содержать следующие поля, которые будут использоваться для задания параметров диалога:

Caption, с:

должно быть строковым полем, в котором содержится заголовок диалога.

В случае если такого поля в таблице нет, то будет использовано значение «Введите данные».

Description, d:

должно быть строковым полем, в котором содержится текст подписи поля редактируемого текста.

В случае если такого поля в таблице нет, то будет использовано значение «Введите данные».

Text, t:

должно быть строковым полем, в котором содержится начальное значение редактируемой строки.

Значение, заданное в таблице параметров имеет меньший приоритет, чем текст переданный в качестве параметра, т.е. если задано оба текста, то будет использован текст, заданный в качестве параметра.

text = input{ c="Enter text", d="Enter text desc", t="base text" };

приведенный пример приводит к отображению диалога следующего содержания:

input2#

string,string input2( таблица[, текст[, текст1]] )

Функция выводит интерактивный диалог с возможностью редактирования двух строк текста переданных в качестве параметра и возвращает строку, которая содержит:

текст измененный пользователем при работе диалога, если операция редактирования была подтверждена.
оригинальный текст, если операция редактирования была отменена.

таблица:

содержит данные о формате диалога ввода;

текст:

начальное значение первого редактируемого текста.

текст1:

начальное значение второго редактируемого текста.

Предупреждение

Возможности узнать изменил пользователь данные или отменил редактирование – не существует.

Caption, с:

должно быть строковым полем, в котором содержится заголовок диалога.

В случае если такого поля в таблице нет, то будет использовано значение «Введите данные».

Description, d:

должно быть строковым полем, в котором содержится текст подписи для первого поля редактируемого текста.

В случае если такого поля в таблице нет, то будет использовано значение «Первое поле».

Description1, d1:

должно быть строковым полем, в котором содержится текст подписи для второго поля редактируемого текста.

В случае если такого поля в таблице нет, то будет использовано значение «Второе поле».

Text, t:

должно быть строковым полем, в котором содержится начальное значение первой редактируемой строки.

Text1, t1:

должно быть строковым полем, в котором содержится начальное значение второй редактируемой строки.

text, text1 = input2{ c="Enter text", d="Field desc", t="base text", d1="Field desc1", t1="base text11" };
printf( "Text: %s, %s", text, text1 );

text, text1 = input2( { c="Enter text", d="Field desc", t="base text", d1="Field desc1", t1="base text11" }, text, text1 );
printf( "Text: %s, %s", text, text1 );

Приведенный пример приводит к показу диалога следующего содержания:

editor#

string editor( таблица[, текст] )

Функция выводит интерактивный диалог с возможностью редактирования многострочного текста переданного в качестве параметра и возвращает строку, которая содержит:

текст измененный пользователем при работе диалога, если операция редактирования была подтверждена.
оригинальный текст, если операция редактирования была отменена.

таблица:

содержит данные о формате диалога ввода.

текст:

начальное значение редактируемого текста.

Предупреждение

Возможности узнать изменил пользователь данные или отменил редактирование – не существует.

Caption, с:

должно быть строковым полем, в котором содержится заголовок диалога.

В случае если такого поля в таблице нет, то будет использовано значение «Введите данные».

Text, t:

должно быть строковым полем, в котором содержится начальное значение редактируемого текста.

text = editor{ c="Enter text", t="base text" };
printf( "Text: %s", text );

Приведенный пример приводит к показу диалога следующего содержания:

Независимые классы#

Набор структур данных не относящихся к ПО RTS напрямую.

Эти классы можно использовать как отдельно от ПО так и при манипулировании с его данными.

Time

Класс для хранения даты и времени.
TimeOnly

Класс для хранения времени суток.
DateOnly

Класс для хранения даты.
Таймеры

Таймеры предназначены для выполнения периодических действий через заданные промежутки времени.

Time#

Класс предназначен для хранения даты и времени.

Поля класса

Имя	Тип	Доступ	Описание
year	Integer	RW	Год
mon	Integer	RW	Месяц
mday	Integer	RW	День месяца
hour	Integer	RW	Час
Min	Integer	RW	Минута
Sec	Integer	RW	Секунда
time	TimeOnly	RO	Время
Date	DateOnly	RO	Дата
Str	String	RO	Отформатированная срока даты и времени. Использует шаблон по умолчанию (см. GetStr).
tt	number	RW	Время в секундах

number tt

Чтение: время в секундах (аналог вызова функции GetTT() для этой переменной).

Запись: установка полей структуры из времени в секундах (аналог вызова функции SetTT() для этой переменной).

Глобальные функции

Time Time.new()

Создает новый пустой экземпляр объекта Time.

Time Time.now()

Создает новый экземпляр объекта Time, заполненный полями для текущего времени.

Функции переменной

string Time:GetStr( [string Format] )

Возвращает сроку даты и времени, форматированную по заданному шаблону.

Если указан параметр функции, то он будет использоваться в виде шаблона форматирования.

Шаблон по умолчанию:

«%d-%m-%Y %H:%M:%S»

TimeOnly Time:GetTO()

Возвращает объект TimeOnly из текущей переменной.

DateOnly Time:GetDO()

Возвращает объект DateOnly из текущей переменной.

Time Time:copy()

Создает новый экземпляр с данными текущего объекта.

number Time:GetTT( void )

Преобразует время переменной в количество секунд (сравнимое с value.measureF).

void Time:SetTT( number )

Устанавливает переменную в значение, соответствующее времени, заданном в виде числа секунд (значения сравнимого с value.measureF).

TimeOnly#

Класс предназначен для хранения времени суток.

Поля класса

Имя	Тип	Доступ	Описание
hour	INTEGER	RW	час
min	INTEGER	RW	минута
sec	INTEGER	RW	секунда
str	STRING	RO	Форматированная срока времени в формате ЧЧ:ММ:СС.
tt	INTEGER	RW	время в секундах

Глобальные функции

TimeOnly TimeOnly.new()

Создает новый экземпляр объекта TimeOnly.

Функции переменной

string TimeOnly:GetStr()

Возвращает форматированную сроку времени в формате ЧЧ:ММ:СС.

TimeOnly TimeOnly:copy()

Создает новый экземпляр с данными текущего объекта.

DateOnly#

Класс предназначен для хранения даты.

Поля класса

Имя	Тип	Доступ	Описание
Year	INTEGER	RW	год
Mon	INTEGER	RW	месяц
Mday	INTEGER	RW	день
Str	STRING	RO	Форматированная срока даты в формате ДД-ММ-ГГГГ.

Глобальные функции

DateOnly DateOnly.new()

Создает новый экземпляр объекта DateOnly.

Функции переменной

string DateOnly:GetStr()

Возвращает форматированную сроку даты в формате ДД-ММ-ГГГГ.

DateOnly DateOnly:copy()

Создает новый экземпляр с данными текущего объекта.

Таймеры#

Таймеры предназначены для выполнения периодических действий через заданные промежутки времени.

[<переменная_таймера> = ] SetTimer( <таблица_конфигурации> )

Функция SetTimer создает переменную таймера с настройками из таблицы конфигурации.

переменная_таймера:: содержит данные таймера и может быть использована для управления таймером: запуска, останови и смены процедуры таймера;
таблица_конфигурации:: содержит настройки для создания таймера.

Таблица конфигурации может быть динамической переменной (созданной в момент вызова функции создания таймера) или переменной типа таблица.

Таблица может содержать не все поля конфигурирования. Если поля в таблице нет, то будет использовано значение по умолчанию.

Таблица конфигурации таймера

Таблица конфигурации содержит именованные поля с предопределенными именами.

Из переданной таблицы будут использованы только поля с описанными ниже именами, остальная структура таблицы роли не играет.

Необходимые для конфигурирования поля должны иметь точно совпадающее с описанием имя и тип, автоматически приводимый к ожидаемому типу данных, в противном случае операции создания таймера завершится с ошибкой.

Поля переменной таймера и таблицы конфигурации

Имя	Тип	Доступ	Описание
Interval	integer	RW	Интервал срабатывания таймера, мс
boolean	Enabled	RW	Состояние разрешения или запрета таймера
function	OnTimer	RW	Функция, вызывающаяся при срабатывании таймера

Имя:

OnTimer

Прототип:

function( [<ПЕРЕМЕННАЯ ТАЙМЕРА>] )

Значение по умолчанию:

nil

Назначение:

Указывает функцию, которая будет вызвана при срабатывании таймера.

Функция может иметь необязательный параметр переменная_таймера. Ели этот параметр указан то в функцию будет передан объект таймера, с которым связана эта функция. Параметр объекта можно использовать для управления объектом таймера, для которого вызвана эта функция.

Имя:

Interval

Прототип:

integer

Значение по умолчанию:

1000

Назначение:

Задает интервал срабатывания таймера (мс).

Предупреждение

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

Имя:: Enabled
Прототип:: boolean
Значение по умолчанию:: true
Назначение:: Указывает начальное состояние, в котором создается таймер.

Если начальное состояние таймера Enabled = true (т.е. таймер разрешен), то он сработает через указанный период после вызова процедуры его создания.

Если начальное состояние таймера Enabled = true (т.е. таймер запрещен), то он не будет срабатывать до тех пор, пока его не разрешат и, после этого, не пройдет период времени указанный при создании таймера.

Предупреждение

При разрешении (установки Enabled в true) таймер сработает не моментально, а через тот период времени, который указан в его параметрах от момента его разрешения.

Функции переменной таймера

void Delete( void )

Удаляет таймер.

Предупреждение

Использование всех переменных, в которых хранилась переменная таймера, после вызова этой функции будет приводить к ошибке выполнения программы.

Примеры реализации таймера

В примере 2.1 создается таймер (1) с использованием динамической таблицы конфигурации, в которой указана динамическая функция таймера (2) и период (3) равный 2 секундам.

Таймер создается в запрещенном состоянии (4) и, после создания, запускается (5).

После запуска таймера будет выполнена динамическая функция (2), заданная в таблице конфигурации, которая изменяет параметры таймера: период (6) равен 1 секунде, разрешенное состояние по умолчанию, и устанавливает новую функцию для вызова Timer2 (7).

Функция Timer2 (8) печатает сообщение, удаляет объект таймера (9) и завершает выполнение программы вызовом функции abort.

function Timer2( tm )                         -- 8
  print( "on timer2. destroy timer2" );
  tm:Delete();                                -- 9
  abort();
end;

timer1 = SetTimer{                            -- 1
  OnTimer = function( timer1 )                -- 2
    print( "on timer1. Switch to another callback" );
    timer1.Interval = 1000;                   -- 6
    timer1.OnTimer = Timer2;                  -- 7
  end,
  Interval = 2000,                            -- 3
  Enabled  = false                            -- 4
}

timer1.Enabled = true                         -- 5

Конфигурация RTS#

Сервис доступа ко всем элементам конфигурации, используемой на сервере.

Выполнение скрипта всегда осуществляется при загруженной конфигурации, поэтому в любой части программы можно использовать доступ к данным текущей конфигурации.

Структура данных неизменна в течение всего периода выполнения программы. В случае если конфигурация будет изменена, программа скрипта будет остановлена и запущена заново с самого начала.

Любое обращение к переменной, функции или таблице, которое можно описать на языке, можно сохранить в переменной скрипта для дальнейшего использования в течении одного запуска скрипта. Тип такой переменной будет совпадать с типом данных, к которым обращаются. В дальнейшем, операции с такими переменными и полным обращением являются полностью эквивалентными.

Доступ к данным РТС#

Переменные доступа к данным из конфигурации делятся на три типа, определяющих способ доступа.

Данные независимого типа

Переменные такого типа не содержат в себе данных и ссылок на конкретные данные, а являются идентификаторами той области, к которой осуществляется доступ.

Переменные такого типа никак не зависят ни от структуры, ни от содержимого конфигурации.

Такие переменные можно рассматривать как «сокращенные синонимы», используемые для сокращения записи доступа к указанной области данных.

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

Переменные типа «ссылка»

Эти переменные ссылаются непосредственно на данные, которые они обозначают.

Изменение такой переменной ведет к прямому изменению содержимого базы конфигурации.

Переменные такого типа могут быть только записи какой-либо базы данных.

Этот тип нецелесообразно использовать. Если требуется изменение содержимого записи то, во избежание ошибок, более правильно использовать для доступа переменные типа «данные».

К переменным типа «ссылка» относятся поля таблиц конфигурации.

Переменные типа «данные»

Такие переменные содержат в себе копию данных, которая получена из базы данных в момент создания такой переменной.

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

К переменным типа «данные» относятся поля таблиц конфигурации.

Предупреждение

Переменные типа «данные» можно создать, только вызвав специальную функцию.

В этом основное отличие от стандартных встроенных типов, где сохранение данных в переменную приводит к автоматическому созданию копии данных, тогда как в аналогичных условиях для типов RTS автоматически будет создана переменная типа «ссылка».

Пример

Для записи на языке LUA:

local tbl = { 10, 20 }
local var = tbl[0]
var = 30

в переменной var будет создана копия значения из таблицы и при изменении значения переменной содержимое таблицы не изменится.

Для данных RTS аналогичная запись:

local var = rts.cfg.value[0]
var.value = 10

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

Для того чтобы создать переменную типа данные необходимо специально ее сконструировать:

local var = rts.cfg.value[0].copy()
var.value = 10

в таком случае переменная var будет содержать независимую копию данных, на которые она ссылается и, ее изменение не изменит оригинала на основании которого была создана новая переменная.

Данные RTS#

Доступ к данным и функциям RTS осуществляется с использованием указания области видимости rts.

rts - Область видимости RTS
rts.cfg - Область видимости конфигурации RTS
rts.cfg.<таблица> - Доступ к записям таблицы конфигурации с именем «таблица»
rts.cfg.<таблица>[ индекс ] - Доступ к записи таблицы конфигурации с именем «таблица» и индексом «индекс»

Предупреждение

Все объекты в области видимости rts имеют тип ссылка!

Это значит что изменение свойств объекта сохраненного с помощью промежуточной переменной изменяет данные оригинального объекта.

Область rts#

Область глобальных данных РТС.

Функции

Возвращаемое значение	Имя	Параметры
string	VarType2Str	(type )
string	VarState2Str	(type, state [,Invert] )
bool	VarValueValid	( type, state )
bool	IsErrorState	( type, state )
number	VarErrorState	( type )
number,number	StateRange	( type )
string	ProtoType2Str	( type )
string	Scheme2Str	( type )
string	SchemeJournal2Str	( type )
number	MaxType	( void )
number	MaxProto	( void )
number	MaxScheme	( void )
number	MaxState	( type )
string	RTName	( any var )
void	SendCommand	( any var, value )
bool	NewValue	( value fields )

rts.VarType2Str#

string rts.VarType2Str( type )

Возвращает строку, описывающую указанный тип type.

rts.VarState2Str#

string rts.VarState2Str(type, state [,Invert] )

Возвращает строку, описывающую указанный статус state для указанного типа переменной type.

Если параметр инверсии Invert установлен в ненулевое значение, то будет использована инверсия статусов для дискретных переменных.

rts.VarValueValid#

bool rts.VarValueValid( type, state )

Возвращает true если для указанного статуса state и типа переменной type значение может быть использовано (статус не указывает на неверную работу оборудования или недостоверные измерения).

rts.IsErrorState#

bool rts.IsErrorState( type, state )

Возвращает true, если для указанного типа type переменной указанный статус state указывает на неверную работу оборудования или недостоверные измерения.

rts.VarErrorState#

number rts.VarErrorState( type )

Возвращает номер «типового» статуса ошибки для указанного типа type переменной.

Значение этого статуса используется в ПО IngortechSCADA для начальной инициализации переменных, до того как получено хотя бы одно измерение.

rts.StateRange#

number,number rts.StateRange( type )

Возвращает пару значений, определяющих минимальное и максимальное значение статусов (диапазон статусов) для указанного типа переменной type.

rts.ProtoType2Str#

string rts.ProtoType2Str( type )

Возвращает строку, описывающую указанный тип протокола type.

rts.Scheme2Str#

string rts.Scheme2Str( type )

Возвращает строку, описывающую указанный тип номера схемы type в виде: «Цветовая», «Тревог», «Звуковая», «Системная», «Техническая», «Управления» or «Неизвестно».

rts.SchemeJournal2Str#

string rts.SchemeJournal2Str( type )

Возвращает строку, описывающую наименование журнала по типу номера схемы type в виде: «Цветовой», «Тревог», «Звуковой», «Системный», «Технический», «Управления» or «Неизвестно».

rts.MaxType#

number rts.MaxType( void )

Возвращает максимально допустимый тип переменной.

Минимальный тип имеет значение 0 (ноль).

rts.MaxProto#

number rts.MaxProto( void )

Возвращает максимально допустимый тип протокола.

Минимальный тип имеет значение 0 (ноль).

rts.MaxScheme#

number rts.MaxScheme( void )

Возвращает максимально допустимый номер схемы.

Минимальный тип имеет значение 0 (ноль).

rts.MaxState#

number rts.MaxState( type )

Возвращает максимально допустимый номер статуса для указанного типа type переменной.

Минимальный тип имеет значение 0 (ноль).

rts.RTName#

string rts.RTName( any var )

Специальная функция для определения имени типа данных системы RTS.

В случае если переданный параметр является типом RTS, функция вернет строку с его именем, в противном случае функция вернет nil.

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

В настоящее время используются следующие имена для типов данных РТС:

Глобальные объекты RTS:: cfg
Таблицы конфигурации:: users, usergroups, ls, types_ls, protocols, objs, points, pointgroups, type_point, types_sensor, sensor, reports, sch_alarm, sch_color, sch_snd, sch_ctrlj, sch_sysj, sch_techj, station, sens, value, user, groups
Имена записей таблиц конфигурации:: RTDB_groups_DB, RTDB_users_DB, RTDB_usergroups_DB, RTDB_protocols_DB, RTDB_objs_DB, RTDB_points_DB, RTDB_pointgroups_DB, RTDB_type_point_DB, RTDB_types_ls_DB, RTDB_types_sensor_DB, RTDB_reports_DB, RTDB_ls_DB, RTDB_sensor_DB, RTDB_sch_alarm_DB, RTDB_sch_color_DB, RTDB_sch_ctrlj_DB, RTDB_sch_snd_DB, RTDB_sch_sysj_DB, RTDB_sch_techj_DB, RTDB_station_DB, RTDB_sens_DB, RTDB_value_DB, RTDB_user_DB

Пример использования:

function PrintRTName( v )
  local nm = rts.RTName(v)
  if not nm then
    print( "Неизвестный тип" )
  end
  if nm == "RTDB_value_DB" then       print( "Структура value" );
  elseif nm == "RTDB_sens_DB" then    print( "Структура sens" );
  elseif nm == "RTDB_sensor_DB" then  print( "Структура sensor" );
  else
    print( "RTS тип: ", nm )
  end
end

Процедура PrintRTName выводит название известного типа данных РТС или текст «Неизвестный тип», если переданный ей параметр не является типом РТС.

rts.SendCommand#

void rts.SendCommand( any var, value )

Передает управляющее воздействие (команду) серверу РТС для указанную переменной var и использует указанной значение value как значение команды.

Предупреждение

Функция SendCommand может быть использована только с переменными типа VART_COMMAND (команда) и VART_ACOMMAND (аналоговая команда).

В случае если используется любой другой тип переменной, команда будет интерпретирована как «получение нового значения сервером RTS» и передана оборудованию связи не будет.

В случае успешной обработки функция возвращает true, в случае ошибки – false. В случае ошибки, текст ошибки можно получить с помощью функции LastError.

Информация

При передачи команды функция устанавливает статус указанной переменной с состояние VARS_C_ACC_N_BEING (передача ПО связи). Фактическая передача значения произойдет только в том случае, если эта переменная обрабатывается каким-либо ПО связи.

В отличие от функции rts.NewValue не производится полная обработка переданного значения переменной. При выполнении этой процедуры просто меняется значение указанной переменной без каких либо проверок и преобразований.

Параметры:

var:

индекс переменной системы РТС заданный любым из возможных способов:

цифровой индекс, соответствующий номеру переменной в текущей конфигурации;
ссылка на существующую переменную в конфигурации (из таблиц: value, sensor или sens);
переменную созданную копирование или клонированием из существующей переменной конфигурации.

value:

значение заданное в такой форме чтобы его можно было преобразовать в число с плавающей точкой (тип string или number).

Пример отправки управляющего воздействия с использованием команд с префиксом UC10 после получения сервером новых значений для переменных с префиксом LST10. Остальная часть имени переменной передается без изменений. Т.е.е при получении нового значения для переменной LST10#18 будет отправлено управляющее воздействия для команды с именем UC10#18 и значение 0 в случае если полученное значение больше нуля и 1, если полученное значение менее или равно нулю.

use("u_Utils.ut")

local db = rts.cfg.value

function OnNewVar( oldV, newV )
  local nm, cmd;

  -- get names
  nm = string.sub( newV.sensor.name, 1,  5 )
  cmd = "UC10" .. string.sub( newV.sensor.name, 6 )

  dbg( "var: %s, sub: %s, cmd: %s", newV.sensor.name, nm, cmd )

  if nm == "LST10" then
     if newV.value > 0 then
       rts.SendCommand( cmd, 0 )
      else
       rts.SendCommand( cmd, 1 )
     end;

     -- Ignore variable changes
     return false
  end

end

rts.NewValue#

bool rts.NewValue( value fields )

Формирует новое значение для существующей переменной с полным циклом обработки этого значения так, как если бы это значение было бы получено от ПО связи.

Из переданной в качестве параметра value таблицы будет сформировано новое значение переменной и обработано сервером как обычное новое значение.

В случае успешной передачи функция возвращает true, в случае ошибки false. Текст ошибки можно получить с помощью LastError.

Параметры формирования нового значения value:

Наименование	Тип	Значение по умолчанию
Var	Var
Value	Number
Volts	Number	Value
State	Number
Time	Time	Time.now()
Measure	Number	Time.now()

Поля таблицы обозначенные символом * обязаны присутствовать в таблице, остальные поля могут присутствовать или, если их не будет, будут использованы значения по умолчанию.

Var:

индекс переменной системы РТС заданный любым из возможных способов:

цифровой индекс, соответствующий номеру переменной в текущей конфигурации;
ссылка на существующую переменную в конфигурации (из таблиц: value, sensor или sens);
переменную созданную копирование или клонированием из существующей переменной конфигурации.

Value:

Инженерное значение переменной.

Volts:

Электрическое значение переменной. Если е указано, то значение будет вычислено из инженерного в соответствии с типом сигнала.

State:

Номер статуса. Значение статуса должно соответствовать типу используемой переменной.

Time:

Время измерения. Если не указано, то будет использовано текущее время.

Measure:

Штамп времени. Если е указан, то он будет вычислен из времени измерения.

ПРИМЕР

library( "LUA/Libs/GUI" );
vals = rts.cfg.value

--
-- Переменная "AI1#4" используется как триггер для запуска теста
-- Т.е. для его запуска надо вручную сгенерировать изменение этой переменной
--
local TEST_VARIABLE = "AI1#4"
printf( "Тестирование процедуры OnNewVar" )
printf( "Для теста измените значение переменной %s", TEST_VARIABLE )

--
-- Отображает получение новых значений
-- Функция будет вызываться как при ручном изменении значений так и при
-- генерации значений с использованием rts.NewValue
--
--
function OnNewVar( oldV, newV )
  -- Для переменной триггера запустить тест
  if rts.cfg.sens[ newV ].name == TEST_VARIABLE then
     DoSetValTest();
   else
  -- Для всех остальных переменных вывести поля переменной
     printf( "Var: %s, Val: %f,%f, St: %d, Tm: (%d) %s",
              rts.cfg.sens[ newV ].name,
              newV.value,
              newV.volts,
              newV.state,
              newV.measureF, newV.measure:GetStr() );
  end
end

-- Используется для того чтобы была пауза между новыми значениями переменных
-- и можно было увидеть разные времена изменения
function Pause() gui.Sleep(1000); end

--
-- Вызывает функцию NewValue
-- В качестве параметра принимает таблицу полей нового значения
--
function SetVal( v )

  -- Поле "Var" обязательное в таблице
  -- Получаем его и используем как имя
  nm = v.Var
  if nm ~= nil then
    -- Идентифицировать переменную можно разными методами.
    -- Преобразуем заданный способ в строку
    nm = tostring(nm);
   else
    nm = "<bad_name>";  -- Поле отсутствует
  end

  -- Формируем новое значение и вызываем диспетчер новых переменных
  -- Если Диспетчер сработает корректно то для этой переменной будет
  -- вызван обработчик OnNewVar

--- boolean NewValue{ value fields }
---   fields are:
---     Name    Type      Default
---     -----------------------------
---     Var     var       *
---     Value   number    *
---     Volts   number    Value
---     State   number    *
---     Time    Time      Time.now
---     Measure number    Time.now
---  где:
---    * - поля обязательные для указания.
---  остальные поля будут заменены значениями по умолчанию (Default).
---
  dbg( "== Set new value to \'%s\'...", nm )
  rc = rts.NewValue( v )

  -- Если ошибка обработки или неверно заданные параметры переменной
  if rc ~= true then
    dbg( "== Ошибка установки переменной %s", nm );
    dbg( "== Ошибка: %s", LastError() );
   else
    Pause()
  end
end

--
-- Тест
--
function DoSetValTest()
  -- Сохраняем текущее время для последующего использования
  tm = Time.now()

  -- Идентификация переменной по имени
  SetVal{
    Var = "AI1#1",
    Value = 1,
    State = 5 }

  -- Идентификация переменной по неверному имени
  SetVal{
    Var = "мусор",
    Value = 33,
    Volts = 3,
    State = 5,
    Measure = tm.tt }

  -- Идентификация переменной по индексу в таблице
  SetVal{
    Var = 2,
    Value = 2,
    State = 3 }

  -- Идентификация переменной по ссылке на нее в таблице значений
  SetVal{
    Var = vals[4],
    Value = 5,
    Volts = 55,
    State = 6 }

  -- Указываем время изменения для новой переменной в виде структуры Time
  SetVal{
    Var = vals[6],
    Volts = 3,
    State = 2,
    Time  = tm }

  -- Указываем время изменения для новой переменной в виде количества секунд
  SetVal{
    Var = vals[8],
    Value = 33,
    Volts = 3,
    State = 5,
    Measure = tm.tt }

  -- Завершаем программу
  abort();
end

Область rts.cfg#

Область данных текущей конфигурации РТС.

Область данных текущей конфигурации содержит таблицы конфигурации, описывающие структуру всех данных системы RTS. Так же конфигурация содержит некоторые функции для манипулирования данными и специальные таблицы, содержащие текущие значения переменных.

Функции

Набор глобальных функций доступных в области rts.cfg.

Возвращаемое значение	Имя	Параметры
number	Count	( void )
table	Tables	( void )
table	IDs	( void )

Таблицы конфигурации

Таблицы конфигурации – это массивы (линейная последовательность одинаковых записей) с данными, описывающими конфигурацию РТС.

Каждая таблица может содержать произвольное число одинаковых записей, каждая из которых имеет уникальную структуру соответствующую таблице (все записи одной таблицы имеют одинаковую структуру, записи различных таблиц имеют различную структуру).

Структура записей для всех таблиц конфигурации описана в разделе Структура конфигурации РТС.

Для доступа к записям таблиц в языке LUA используется синтаксис:

ТАБЛИЦА[ ИНДЕКС ]

ТАБЛИЦА:

Ссылка на объект таблицы к которому можно обратиться используя поля таблиц области rts.cfg.

ИНДЕКС:

Индекс таблицы.

В качестве индекса таблицы можно использовать следующие типы и переменные:

Числовой индекс таблицы.

rts.cfg.Count#

number rts.cfg.Count( void )

Возвращает общее число таблиц, которые содержит конфигурация.

Нумерация таблиц начинается с 0.

rts.cfg.Tables#

table rts.cfg.Tables( void )

Возвращает таблицу (массив) содержащий имена всех таблиц в строковом виде.

Нумерация таблиц начинается с 0.

rts.cfg.IDs#

table rts.cfg.IDs( void )

Возвращает таблицу (массив) содержащий идентификаторы всех таблиц в виде числа. Идентификатор таблицы – это уникальный номер таблицы определенного типа в конфигурации, т.е. таблица одного типа всегда имеет одинаковый идентификатор.

Нумерация таблиц начинается с 0.

Предупреждение

В текущей реализации порядковый номер таблицы совпадает с ее идентификатором, поэтому в качестве идентификатора можно использовать порядковый номер.

К примеру, запись rts.cfg.

Средства управления RTS#

Набор процедур, которые позволяют выполнять специализированные задачи системы RTS (генерация команд, Генерация новых значений и т.д.).

???

Процедуры скрипта#

Процедуры реализованные на языке скрипта, имеющие специальные имена и описанные параметры, которые будут вызываться автоматически из ПО сервера при выполнении определенных условий.

Эти процедуры являются основным местом, где выполняется весь алгоритм, реализуемый в скриптовом языке.

???

[?] РТС LUA API

Содержание

[?] РТС LUA API#

Сервис предоставляемый ПО#

Глобальные переменные и константы#

isdebug#

platform#

Глобальные процедуры#

abort#

use#

GetScriptPath#

GetStartupDir#

printf#

print#

msg#

AskYesNo#

dbg#

error#

LastError#

library#

CfgStr#

CfgInt#

contains#

table2str#

str2table#

getn#

ToOEM#

FromOEM#

input#

input2#

editor#

Независимые классы#

Time#

TimeOnly#

DateOnly#

Таймеры#

Конфигурация RTS#

Доступ к данным РТС#

Данные RTS#

Область rts#

rts.VarType2Str#

rts.VarState2Str#

rts.VarValueValid#

rts.IsErrorState#

rts.VarErrorState#

rts.StateRange#

rts.ProtoType2Str#

rts.Scheme2Str#

rts.SchemeJournal2Str#

rts.MaxType#

rts.MaxProto#

rts.MaxScheme#

rts.MaxState#

rts.RTName#

rts.SendCommand#

rts.NewValue#

Область rts.cfg#

rts.cfg.Count#

rts.cfg.Tables#

rts.cfg.IDs#

Средства управления RTS#

Процедуры скрипта#