OpenSCADAWiki: Doc/API/part3 ...

3. Подсистема "Базы Данных" (TBDS)

Подсистема "Базы Данных" представлена объектом TBDS, который содержит модульные объекты типов БД TTypeBD. Каждый тип базы данных содержит объекты отдельно взятых баз данных данного типа TBD. Каждая БД, в свою очередь, содержит объекты своих таблиц TTable (рис. 3).

Рис. 3. Иерархическая структура подсистемы БД.

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

Являясь модульным объектом, тип БД (TTypeBD) содержит доступ к реализации механизма той или иной БД. Доступ производится посредством открытых БД модуля отдельно взятого типа БД. Открываемые/регистрируемые БД описываются в таблице открываемых БД или в конфигурационном файле. Существует так называемая рабочая БД, которая открывается всегда и указывается в конфигурационном файле. БД, поддерживающие SQL-запросы, могут предоставлять доступ, основанный на прямых SQL-запросах.

В процессе использования компоненты системы OpenSCADA открывают таблицы (TTable) в доступных БД и работают с ними.

3.1. Объект подсистемы "Базы Данных" (TBDS)

Данные:
Флаги запросов к системной таблице (enum – TDBS::ReqGen):

• OnlyCfg — запрос только к конфигурационному файлу.
• UseTranslate — использовать перевод текстовой переменной.

Публичные методы:

• int subVer( ); — Версия подсистемы.
• static string realDBName( const string &bdn ); — Преобразование полного шаблонного имени БД или таблицы (вида *.*.myTbl) в реальное имя. Фактически выполняется замена специальных элементов '*' на элементы рабочей БД.
• void dbList( vector<string> &ls, bool checkSel = false ); — Список доступных БД. checkSel указывает на необходимость проверки факта загрузки из выбранной БД и вставки в список БД только выбранной.
• AutoHD<TTable> open( const string &bdn, bool create = false ); — Открытие таблицы bdn БД по её полному пути с созданием create в случае отсутствия.
• void close( const string &bdn, bool del = false ); — Закрытие таблицы bdn БД по её полному пути с возможностью удаления после закрытия del.
• bool dataSeek( const string &bdn, const string &path, int lev, TConfig &cfg, bool forceCfg = false, vector< vector<string> > *full = NULL ); — Общее сканирование записей источника данных. В качестве источника выступает конфигурационный файл или БД. В случае отсутствия БД используется конфигурационный файл. Если имя БД bdn или путь path конфигурационного файла не указаны, то их обработка пропускается. full определяется перед запросом для предзагрузки результата целиком и значительного ускорения.
• bool dataGet( const string &bdn, const string &path, TConfig &cfg, bool forceCfg = false, bool noEx = false ); — Получение записи из источника данных (БД или конфигурационный файл). Если имя БД bdn или путь path конфигурационного файла не указаны, то их обработка пропускается.
• void dataSet( const string &bdn, const string &path, TConfig &cfg, bool forceCfg = false, bool noEx = false ); — Установить/сохранить запись в источнике данных (БД или конфигурационный файл). Если имя БД bdn или путь path конфигурационного файла не указаны, то их обработка пропускается.
• bool dataDel( const string &bdn, const string &path, TConfig &cfg, bool useKeyAll = false, bool forceCfg = false, bool noEx = false ); — Удаление записи из источника данных (БД или конфигурационный файл). Если имя БД bdn или путь path конфигурационного файла не указаны, то их обработка пропускается. useKeyAll используется для указания необходимости установки всех ключей для использования их при удалении с восстановлением исходного состояний выбора ключей при выходе из функции. Если этот флаг не установлен, то используются ранее выбранные ключи для выполнения операции.
• static string genDBGet( const string &path, const string &oval = "", const string &user = "root", char rFlg = 0 ); — Получить общесистемные данные из конфигурационного файла или системной таблицы от имени пользователя user. Если данные отсутствуют, то возвращается значений oval.
• static void genDBSet( const string &path, const string &val, const string &user = "root", char rFlg = 0 ); — Установить/сохранить обще-системные данные в конфигурационном файле или системной таблице от имени пользователя user.
• string fullDBSYS( ); — Полное имя системной таблицы.
• string fullDB( ); — Полное имя таблицы с описанием зарегистрированных БД.
• TElem &openDB_E( ) — Структура таблицы зарегистрированных БД.
• AutoHD<TTypeBD> at( const string &iid ) — Обращение к модулю БД (типу БД).
• string optDescr( ); — Локализованная помощь по опциям командной строки и параметрам конфигурационного файла.

3.2. Модульный объект типов баз данных (TTypeBD)

Публичные методы:

• bool fullDeleteDB( ); — Признак полного удаления БД.
• void list( vector<string> &list ) const; — Список зарегистрированных (открытых) БД.
• bool openStat( const string &idb ) const; — Проверка на наличие указанной открытой БД.
• void open( const string &iid ); — Открытие БД.
• void close( const string &iid, bool erase = false ); — Закрытие БД. Если установлен признак erase, то БД будет полностью удалена.
• AutoHD<TBD> at( const string &name ) const; — Подключение к открытой БД.
• TBDS &owner( ) const; — Подсистема - владелец модуля.

3.3. Объект базы данных (TBD)

Публичные методы:

• TBD( const string &iid, TElem *cf_el ); — Инициализирующий конструктор.
• string id( ); — Идентификатор БД.
• string fullDBName( ); — Полное имя хранилища-БД.
• string name( ); — Имя БД.
• string dscr( ); — Описание БД.
• string addr( ) const; — Адрес БД. Форма записи отлична для каждого типа БД.
• string codePage( ); — Кодовая страница, в которой хранятся данные БД.
• bool enableStat( ) const; — Состояние БД: "Включена".
• bool toEnable( ); — Признак БД: "Включать".
• void setName( const string &inm ); — Установка имени БД.
• void setDscr( const string &idscr ); — Установка описания БД.
• void setAddr( const string &iaddr ); — Установка адреса БД.
• void setCodePage( const string &icp ); — Установка кодовой страницы хранения данных в БД.
• void setToEnable( bool ivl ); — Установка признака: "Включать".
• virtual void enable( ); — Включение БД.
• virtual void disable( ); — Отключение БД.
• virtual void allowList( vector<string> &list ) const; — Список таблиц, содержащихся в данной БД.
• void list( vector<string> &list ) const; — Список открытых таблиц.
• bool openStat( const string &table ) const; — Признак указывающий на то, что запрошенная таблица открыта.
• void open( const string &table, bool create ); — Открытие таблицы. Если установлен признак create, то в случае отсутствия таблица будет создана.
• void close( const string &table, bool del = false, long tm = -1 ); — Закрытие таблицы. Если установлен признак del, то таблица будет полностью удалена.
• AutoHD<TTable> at( const string &name ) const; — Подключение к таблице.
• virtual void sqlReq( const string &req, vector< vector<string> > *tbl = NULL, char intoTrans = EVAL_BOOL ); — Отправка SQL-запроса req на БД и получение результата в виде таблицы tbl. При установке intoTrans в true для запроса будет открыта транзакция, в false будет закрыта.
• virtual void transCloseCheck( ) — Периодически вызываемая функция для проверки транзакций и закрытия старых или содержащих много запросов.
• TTypeBD &owner( ) const; — Тип базы данных – владелец данной БД.

Защищённые методы:

• virtual TTable *openTable( const string &table, bool create ); — Модульный метод открытия таблицы.

3.4. Объект таблицы (TTable)

Публичные методы:

• TTable( const string &name ); — Инициализирующий конструктор.
• string name( ); — Имя таблицы.
• string fullDBName( ); — Полное имя хранилища-таблицы в БД.
• virtual void fieldStruct( TConfig &cfg ); — Получение структуры таблицы.
• virtual bool fieldSeek( int row, TConfig &cfg, vector< vector<string> > *full = NULL ); — Сканирование записей cfg таблицы по row, где full определяется перед запросом для предзагрузки результата целиком и значительного ускорения.
• virtual void fieldGet( TConfig &cfg ); — Запрос указанной записи. Запрашиваемая запись определяется значениями ключевых ячеек исходной записи cfg.
• virtual void fieldSet( TConfig &cfg ); — Установка значений указанной записи. В случае отсутствия запись будет создана.
• virtual void fieldDel( TConfig &cfg ); — Удаление указанной записи.
• TBD &owner( ) const; — БД – владелец данной таблицы.