OpenSCADAWiki : Doc/API/part13

13. Данные в системе OpenSCADA и их хранение в БД (TConfig)

Хранение данных в системе основано на объектах TConfig и TElem. Эти объекты хранят структуру и значения полей БД, что позволяет выполнять прямую загрузку и сохранение конфигурации через подсистему "БД". Для специализированного хранения данных разных типов предусмотрен объект TVariant.

Объект TElem содержит структуру записи БД. Структура записи содержит исчерпывающую информацию об элементах, их типах, размерах и остальных параметрах. Информации в данной структуре достаточно для создания, контроля и управления реальной структурой БД. Элементарной единицей записи является ячейка Tfld.

Объект TСonfig является наследником от TElem и содержит реальные значения элементов. TConfig используется в качестве параметра в функциях манипуляции с записями таблиц в подсистеме "БД". Элементарной единицей записи является ячейка TCfg.

Для предоставления возможности предупреждения хранилища данных о смене структуры предусмотрен объект TValElem, от которого наследуется хранилище TConfig и список которых содержится в структуре TElem.

13.1. Объект данных (TConfig)

Наследует:	TValElem
Наследуется:	TParamContr, TController, TMArchivator, TPrmTempl, TPrmTmplLib, TUser, TGroup, TTransportIn, TTransportOut, TBD, TVArchive, TVArchivator, а также модульные объекты хранящие свои данные в БД.

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

TConfig( TElem *Elements = NULL ); — Инициализирующий конструктор.
TConfig( const TConfig &src ); — Копирующий конструктор.
TConfig &operator=( const TConfig &cfg ); TConfig &exclCopy( const TConfig &cfg, const string &passCpLs = "", bool cpElsToSingle = false ); — Копирование из cfg, опуская поля passCpLs и создавая сами поля cpElsToSingle для совмещённых конфигураций.
void cfgList( vector<string> &list ) const; — Список элементов list.
bool cfgPresent( const string &n_val ) const; — Проверка на наличие элемента n_val.
TCfg &cfg( const string &n_val ) const; — Получение элемента n_val.
TCfg *at( const string &n_val, bool noExpt = false ) const; — Получение указателя на элемент n_val. В случае отсутствия элемента генерируется исключение или возвращается нулевой указатель при установке noExpt.
void cfgViewAll( bool val = true ); — Установка/снятие признака видимости для всех элементов.
void cfgKeyUseAll( bool val ); — Установка/снятие признака использования ключа для всех элементов.
TElem &elem( ); — Используемая структура.
void setElem( TElem *Elements, bool first = false ); — Назначение структуры в Elements.
void cntrCmdMake( XMLNode *fld, const string &path, int pos, const string &user = "root", const string &grp = "root", int perm = 0664 ); — Формирование информационного описания элементов конфигурации для интерфейса управления OpenSCADA.
void cntrCmdProc( XMLNode *fld, const string &elem, const string &user = "root", const string &grp = "root", int perm = 0664 ); — Обработка запросов интерфейса управления OpenSCADA к элементам конфигурации.
bool incomplTblStruct( ); — Флаг неполноты структуры БД.
void setIncmplTblStrct( bool vl ); — Установка флага неполноты структуры БД в vl.
bool reqKeys( ); — Признак "Ключ запроса", указание на использование ключа запроса элементами группы.
TVariant objFunc( const string &id, vector<TVariant> &prms, const string &user ); — Объектные функции доступа к конфигурации.

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

virtual bool cfgChange( TCfg &co, const TVariant &pc ); — Вызывается в случае изменения содержимого элемента конфигурации.

13.2. Ячейка данных (TCfg)

Наследует:

TVariant

Данные:
Дополнительные флаги к TFld (enum — TCfg::AttrFlg):

TCfg::NoVal(0x100) — не отражать элемент на значение объекта TValue.
TCfg::Key(0x200) — ключевое поле.
TCfg::Hide(0x400) — атрибут скрыт.

Флаги запросов (enum — ReqFlg):

TFld::ForceUse(0x01) — Форсирование установки флага использования элемента при установке его значения.
TFld::ExtValOne (0x02) — Один/первое (по умолчанию) значения: значение установки для ключа.
TFld::ExtValTwo (0x04) — Два/второе значение: базовое значение для ключа при запросе или установке.
TFld::ExtValThree (0x08) — Третье значение: адрес источника при переводе.

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

TCfg( TFld &fld, TConfig &owner ); — Инициализирующий конструктор.
TCfg( const TCfg &cfg ); — Копирующий конструктор.
const string &name( ); — Имя ячейки.
bool operator==( TCfg &cfg ); — Сравнение ячеек.
TCfg &operator=( const TCfg &cfg ); — Копирование ячеек.
bool view( ) const; — Признак - "Ячейка видима".
bool keyUse( ) const; — Признак - "Использовать ключ", для запросов dataSeek() и dataDel().
bool noTransl( ) const; — Признак "Отключить перевод" предназначен для отключения механизма перевода текстовых переменных для данной записи.
bool reqKey( ) const; — Признак "Ключ запроса", для выполнения групповых операций по данному полю, как ключу.
bool isKey( ) const; — Сборный признак поля как ключ, в зависимости от режима "Ключ запроса" для группы.
bool extVal( ) const; — Признак "Расширенное значение", для указания совмещения полем роли поиска по ключу и обновления самого ключа и перевода.
void setView( bool vw ); — Установка признака "Ячейка видима" в vw.
void setKeyUse( bool vl ); — Установка признака "Использовать ключ" в vl.
void setNoTransl( bool vl ); — Установка признака "Отключить перевод".
void setReqKey( bool vl ); — Установка признака "Ключ запроса".
void setExtVal( bool vw ); — Установка признака "Расширенное значение".
TFld &fld( ) const; — Конфигурация ячейки.
string getSEL( ); — Получить значение выборочного типа.
string getS( ) const; string getS( uint8_t RqFlg ); — Получить значение строкового типа с флагами запроса RqFlg.
const char *getSd( ); — Получить прямой доступ к значению строкового типа, только для чтения.
double &getRd( ); — Получить прямой доступ к значению вещественного типа.
int64_t &getId( ); — Получить прямой доступ к значению целого типа.
char &getBd( ); — Получить прямой доступ к значению логического типа.
void setSEL( const string &val, uint8_t RqFlg = 0 ); — Установить значение выборочного типа в val с флагами запроса RqFlg.
void setS( const string &val ); TCfg &operator=( const string &vl ); TCfg &operator=( const char *vl ); void setS( const string &val, uint8_t RqFlg ); — Установить значение строкового типа в val с флагами запроса RqFlg.
void setR( double val ); TCfg &operator=( double vl ); void setR( double val, uint8_t RqFlg ); — Установить значение вещественного типа в val с флагами запроса RqFlg.
void setI( int64_t val ); TCfg &operator=( int64_t vl ); void setI( int64_t val, uint8_t RqFlg ); — Установить значение целого типа в val с флагами запроса RqFlg.
void setB( char val ); TCfg &operator=( bool vl ); void setB( char val, uint8_t RqFlg ); — Установить значение логического типа в val с флагами запроса RqFlg.
TConfig &owner( ) const; — Объект контейнера-владельца.

13.3. Объект структуры данных (TElem)

Наследуется:

TTypeParam, TControllerS, TTypeDAQ, а также модульными объектами, совмещающими функции хранения структуры.

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

TElem( const string &name = "" ); — Инициализация структуры с указанным именем name.
TElem( const TElem &src ); — Копирующий конструктор.
TElem &operator=( const TElem &src ); — Копирование из src
string &elName( ); — Имя структуры.
void fldList( vector<string> &list ); — Список ячеек в структуре list.
unsigned fldSize( ); — Количество ячеек в структуре.
unsigned fldId( const string &name, bool noex = false); — Получение индекса ячейки по её идентификатору name. В случае установки noex, при отсутствии ячейки будет возвращаться общее количество ячеек, а не осуществляться генерация исключения.
bool fldPresent( const string &name ); — Проверка на наличие указанной ячейки name.
int fldAdd( TFld *fld, int id = -1 ); — Добавление/вставка ячейки fld в позицию id (-1 — вставка в конец).
void fldDel( unsigned int id ); — Удаление ячейки id.
TFld &fldAt( unsigned int id ); — Получение ячейки id.
void fldClear( ); — Удаление всех ячеек.
void valAtt( TValElem *cnt ); — Вызывается автоматически в случае подключения структуры к хранилищу данных cnt.
void valDet( TValElem *cnt ); — Вызывается автоматически в случае отключения структуры от хранилища данных cnt.
ResMtx &resEl( ); — Мютекс для доступа к контейнерам полей.

13.4. Ячейка структуры данных (TFld)

Данные:
Тип ячейки (enum – TFld::Type):

TFld::Boolean(0) — логический тип;
TFld::Integer(1) — целочисленный тип;
TFld::Real(4) — вещественный тип;
TFld::String(5) — строковый тип;
TFld::Object(6) — объектный тип;
TFld::GenMask(0x0F) — маска основных типов;
TFld::Int16(0x11) — целое знаковое 16 разрядов;
TFld::Int32(0x01) — целое знаковое 32 разрядов;
TFld::Int64(0x21) — целое знаковое 64 разрядов;
TFld::Float(0x14) — float (4 байта);
TFld::Double(0x04) — double (8 байт).

Флаги ячейки (enum — TFld::AttrFlg):

TFld::NoFlag(0x00) — флаги отсутствуют;
TFld::Selected(0x01) — режим выборки из доступных значений, выборочный тип;
TFld::SelfFld(0x02) — создавать собственную копию этой ячейки;
TFld::NoWrite(0x04) — недоступна для записи;
TFld::HexDec(0x08) — целый тип: шестнадцатеричное представление;
TFld::OctDec(0x10) — целый тип: восьмеричное представление;
TFld::DateTimeDec(0x20) — целый тип: содержит дату в UTC;
TFld::FullText(0x08) — полнотекстовый, многострочный, режим тестового типа;
TFld::TransltText(0x10) — переводить текстовые переменные записи.

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

TFld( ); — Инициализация по умолчанию.
TFld( const TFld &ifld, const char *name = NULL ); — Копирующий конструктор, с возможностью индивидуальной установки имени name.
TFld( const char *name, const char *descr, Type type, unsigned char flg, const char *valLen = "", const char *valDef = "", const char *vals = "", const char *nSel = "", const char *res = "" ); — Инициализация с указанной конфигурацией.
TFld &operator=( const TFld &fld ); — Копирование ячейки из fld.
const string &name( ) const; — Имя ячейки.
const string &descr( ) const; — Описание ячейки.
int len( ) const; — Размер значения ячейки (символов в символьном представлении).
int dec( ) const; — Размер дробной части для вещественного (символов в символьном представлении).
Type type( ) const; — Тип ячейки.
static Type type(IO::Type tp); — Тип ячейки из IO::Type типа.
IO::Type typeIO( ) const; — Тип ячейки в IO::Type.
unsigned flg( ) const; — Флаги ячейки.
const string &def( ) const; — Значение по умолчанию.
string values( ) const; — Рабочий диапазон значения или перечень возможных значений для выборочного типа (в виде — "vl1;vl2;vl3").
string selNames( ) const; — Перечень имён значений для выборочного типа (в виде — "Value 1;Value 2;Value 3").
const string &reserve( ) const; — Резервный параметр.
void setDescr( const string &dscr ); — Установка описания в dscr.
void setLen( int vl ); — Установка размера ячейки в vl.
void setDec( int vl ); — Установка дробной части для вещественного, в vl.
void setDef( const string &def ); — Установка значения по умолчанию в def.
void setFlg( unsigned flg ); — Установка флагов в flg.
void setValues( const string &vls ); — Установка рабочего диапазона значения или перечня возможных значений для выборочного типа (в виде — "vl1;vl2;vl3") в vls.
void setSelNames( const string &slnms ); — Установка перечня имён значений для выборочного типа (в виде — "Value 1;Value 2;Value 3") в slnms.
void setReserve( const string &ires ); — Установка резервного параметра в res.
const vector<string> &selValS() const; — Список вариантов значений для строкового типа.
const vector<int> &selValI() const; — Список вариантов значений для целого типа.
const vector<double> &selValR() const; — Список вариантов значений для вещественного типа.
const vector<bool> &selValB() const; — Список вариантов значений для логического типа.
const vector<string> &selNm() const; — Список имён вариантов значений.
string selVl2Nm( const string &val ); — Получить выбранное имя по значению val строкового типа.
string selVl2Nm( int64_t val ); — Получить выбранное имя по значению целого val типа.
string selVl2Nm( double val ); — Получить выбранное имя по значению val вещественного типа.
string selVl2Nm( bool val ); string selVl2Nm( char val ); — Получить выбранное имя по значению val логического типа.
string selNm2VlS( const string &name ); — Получить значение строкового типа по выбранному имени name.
int64_t selNm2VlI( const string &name ); — Получить значение целого типа по выбранному имени name.
double selNm2VlR( const string &name ); — Получить значение вещественного типа по выбранному имени name.
bool selNm2VlB( const string &name ); — Получить значение логического типа по выбранному имени name.
XMLNode *cntrCmdMake( XMLNode *opt, const string &path, int pos, const string &user = "root", const string &grp = "root", int perm = 0664 ); — Создать элемент формы в соответствии с параметрами ячейки.

13.5. Объект упреждения про смену структуры (TValElem)

Наследуется:

TValue, TConfig.

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

virtual void detElem( TElem *el ); — Уведомление элементом el контейнера про желание отключиться.
virtual void addFld( TElem *el, unsigned id ) = 0; — Уведомление про добавление ячейки id елемента el.
virtual void delFld( TElem *el, unsigned id ) = 0; — Уведомление про удаление ячейки id елемента el.

13.6. Ячейка данных (TVariant)

Данные:
Значения ошибки для различных типов данных (define):

EVAL_BOOL — Значение ошибки логического (2);
EVAL_INT — Значение ошибки целого (-2147483647);
EVAL_REAL — Значение ошибки вещественного (-3.3E308);
EVAL_STR — Значение ошибки строкового ("<EVAL>");
EVAL_INT16 — Значение ошибки целого 16 (-32767);
EVAL_INT32 — Значение ошибки целого 32 (-2147483647);
EVAL_INT64 — Значение ошибки целого 64 (-9223372036854775807ll);
EVAL_RFlt — Значение ошибки вещественного Float (-3.29E38);
EVAL_RDbl — Значение ошибки вещественного Double (-1.79E308).

Типы данных (enum — TVariant::Type):

TVariant::Null — тип данных и данные не установлены.
TVariant::Boolean — логический тип (boolean, 8бит).
TVariant::Integer — целочисленный тип (integer, 32бит).
TVariant::Real — вещественный тип (double).
TVariant::String — строка.
TVariant::Object — объект.

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

TVariant( ); — Конструктор по умолчанию.
TVariant( char ivl ); TVariant( bool ivl ); — Конструктор для логического типа.
TVariant( int64_t ivl ); TVariant( int ivl ); — Конструктор для целого типа.
TVariant( double ivl ); — Конструктор для вещественного типа.
TVariant( string ivl ); — Конструктор для строки.
TVariant( const char *var ); — Конструктор для строки.
TVariant( AutoHD<TVarObj> ivl ); TVariant( TVarObj *ivl ); — Конструктор для объекта.
TVariant( const TVariant &var ); — Копирующий конструктор.
bool operator==( const TVariant &vr ) const; — Сравнение объекта на равенство.
bool operator!=( const TVariant &vr ) const; — Сравнение объекта на неравенство.
TVariant &operator=( const TVariant &vr ); — Копирование объекта.
bool isNull( ) const; — Признак того, что объект не инициирован.
bool isEVal( ) const; — Признак того, что содержится ошибочное значение.
Type type( ) const; — Тип значения.
void setType( Type tp, bool fix = false, bool stdStringOmit = false ); — Установка типа tp для его фисации fix и возможности использования как постоянная stdStringOmit.
bool isModify( ); — Флаг модификации. Служит в объектных функциях для индикации модификации переменных.
void setModify( bool vl = true ); — Установка флага модификации.
virtual char getB( ) const; operator char( ); — Получение значения как логическое.
virtual int64_t getI( ) const; operator int64_t( ); operator int( ); — Получение значения как целого.
virtual double getR( ) const; operator double( ); — Получение значения как вещественного.
virtual string getS( ) const; operator string( ); — Получение значения как строки.
virtual AutoHD<TVarObj> getO( ) const; operator AutoHD<TVarObj>( ); — Получение объекта.
virtual void setB( char val ); — Установка в значение логического.
virtual void setI( int64_t val ); — Установка в значение целого.
virtual void setR( double val ); — Установка в значение вещественного.
virtual void setS( const string &val ); — Установка в значение строки.
virtual void setO( AutoHD<TVarObj> val ); — Установка объекта.

13.7. Пользовательский объект (TVarObj)

Наследуется:

TArrayObj

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

TVarObj( ); — Конструктор.
int connect( ); — Подключение к объекту.
int disconnect( ); — Отключение от объекта.
virtual void propList( vector<string> &ls ); — Список свойств ls объекта.
virtual TVariant propGet( const string &id ); — Запрос свойства объекта с идентификатором id.
TVariant propGet( const string &ids, char sep ); — Запрос иерархического свойства объекта с путём ids и разделителем sep.
virtual void propSet( const string &id, TVariant val ); — Установка свойства объекта с идентификатором id в значение val.
void propSet( const string &ids, char sep, TVariant val ); — Установка иерархического свойства объекта с путём ids и разделителем sep в значение val.
void propClear( const string &ids = "" ); — Очистка свойства ids или всех свойств для пустого ids.
virtual string getStrXML( const string &oid = "" ); — Преобразование содержимого объекта в поток XML.
static AutoHD<TVarObj> parseStrXML( const string &str, XMLNode *nd = NULL, AutoHD<TVarObj> prev = NULL ); — Обратное преобразование XML-потока в объект.
virtual TVariant funcCall( const string &id, vector<TVariant> &prms ); — Вызов функции объекта с идентификатором id и параметрами prms.