OpenSCADAWiki: Doc/API/part13 ...

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

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

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

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

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

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

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

• 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)

Данные:
Дополнительные флаги к 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)

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

• 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)

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

• 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)

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

• 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.