OpenSCADAWiki: Home Page En/Doc/API/part13 ...

13. Data in the OpenSCADA system and their storage in the DB (TConfig)

Storing data in the system based on the objects TConfig and TElem. These objects store the structure and fields' values of the database, allowing for direct loading and saving the configuration via the "DB" subsystem. For the specialized different types data storage the TVariant object is provided.

TElem object contains the structure of database record. Structure of the record contains extensive information about the elements, their types, sizes and other parameters. Information in this structure is enough to create, control and manage the real structure of the database. Elementary unit of the record is the cell Tfld.

TConfig object is the heir of TElem and contains the actual values of elements. TConfig is used as the parameter in the functions of the manipulating with the table's records in the "DB" subsystem. Elementary unit of the record is the cell TCfg.

To provide an opportunity to inform the data storehouse about the changes in the structure it is provides an object TValElem, from which it is inherited the storehouse TConfig and the list of which is contained in the TElem structure.

13.1. Data object (TConfig)

Public methods:

• TConfig( TElem *Elements = NULL ); — Initializing constructor.
• TConfig( const TConfig &src ); — Copying constructor.
• TConfig &operator=( const TConfig &cfg ); TConfig &exclCopy( const TConfig &cfg, const string &passCpLs = "", bool cpElsToSingle = false ); — Copying from cfg, passing fields into passCpLs and creating same this fields cpElsToSingle for combined configurations.
• void cfgList( vector<string> &list ) const; — Elements' list list.
• bool cfgPresent( const string &n_val ) const; — Check for the element's presence n_val.
• TCfg &cfg( const string &n_val ) const; — Getting of th element n_val.
• TCfg *at( const string &n_val, bool noExpt = false ) const; — Getting of the element's pointer n_val. If the element is absent an exception is generated or the null pointer is returned when setting noExpt.
• void cfgViewAll( bool val = true ); — Set/unset the sign of the visibility for all the elements.
• void cfgKeyUseAll( bool val ); — Set/unset the sign of the using the key for all the elements.
• TElem &elem( ); — The using structure.
• void setElem( TElem *Elements, bool first = false ); — Setting the structure in Elements.
• void cntrCmdMake( XMLNode *fld, const string &path, int pos, const string &user = "root", const string &grp = "root", int perm = 0664 ); — Formation of the information description of elements of the configuration for the management interface of OpenSCADA.
• void cntrCmdProc( XMLNode *fld, const string &elem, const string &user = "root", const string &grp = "root", int perm = 0664 ); — Requests' of the OpenSCADA management interface to the elements of the configuration processing.
• bool incomplTblStruct( ); — The DB struct incomplete flag.
• void setIncmplTblStrct( bool vl ); — Setting the DB struct incomplete flag to vl.
• bool reqKeys( ); — The sign "Requests key", mark for using the request keys by the group items.
• TVariant objFunc( const string &id, vector<TVariant> &prms, const string &user ); — The object's functions for access to configuration.

Protected methods:

• virtual bool cfgChange( TCfg &co, const TVariant &pc ); — Is called in the case of changing the contents of the configuration element.

13.2. Data cell (TCfg)

Data:
Additional flags to TFld (enum — TCfg::AttrFlg):

• TCfg::NoVal(0x100) — Do not reflect an element on the value of the TValue object.
• TCfg::Key(0x200) — key field.
• TCfg::Hide(0x400) — attribute is hidden.

Requests flags (enum — ReqFlg):

• TFld::ForceUse(0x01) — Forcing the setting of the flag of the element's using during the setting of its value.
• TFld::ExtValOne (0x02) — One/first (and default) value: set value for key.
• TFld::ExtValTwo (0x04) — Two/second value: base value for the key request or set.
• TFld::ExtValThree (0x08) — Three value: source address for translations.

Public methods:

• TCfg( TFld &fld, TConfig &owner ); — Initializing constructor.
• TCfg( const TCfg &cfg ); — Copy constructor.
• const string &name( ); — Cell name.
• bool operator==( TCfg &cfg ); — Comparison of the cells.
• TCfg &operator=( const TCfg &cfg ); — Copying of the cells.
• bool view( ) const; — The sign - "Cell is visible".
• bool keyUse( ) const; — The sign - "Use the key" for the dataSeek() and dataDel() requests.
• bool noTransl( ) const; — The sign "No translation" is provided to disable the translation of text variables for the record.
• bool reqKey( ) const; — The sign "Requests key", for group operations produce by the field as key.
• bool isKey( ) const; — Common sign of the field as key, depends from mode "Requests key" for the group.
• bool extVal( ) const; — The sign "Extended value", for mark the field to misc role for search and update the key value and translation.
• void setView( bool vw ); — Setting of the sign "The cell is visible" в vw.
• void setKeyUse( bool vl ); — Setting of the sign "Use the key" in vl.
• void setNoTransl( bool vl ); — Setting of the sign "No translation".
• void setReqKey( bool vl ); — Setting of the sign "Requests key".
• void setExtVal( bool vw ); — Setting of the sign "Extended value".
• TFld &fld( ) const; — Configuration of the cell.
• string getSEL( ); — Get the value of the selective type.
• string getS( ) const; string getS( uint8_t RqFlg ); — Get the value of the string type with the request flags RqFlg.
• const char *getSd( ); — Get the direct access to the string type value.
• double &getRd( ); — Get the direct access to the real type value.
• int64_t &getId( ); — Get the direct access to the integer type value.
• char &getBd( ); — Get the direct access to the boolean type value.
• void setSEL( const string &val, uint8_t RqFlg = 0 ); — Set the value of the selective type to the val with the request flags RqFlg.
• void setS( const string &val ); TCfg &operator=( const string &vl ); TCfg &operator=( const char *vl ); void setS( const string &val, uint8_t RqFlg ); — Set the value of the string type to the val with the request flags RqFlg.
• void setR( double val ); TCfg &operator=( double vl ); void setR( double val, uint8_t RqFlg ); — Set the value of the real type to the val with the request flags RqFlg.
• void setI( int64_t val ); TCfg &operator=( int64_t vl ); void setI( int64_t val, uint8_t RqFlg ); — Set the value of the integer type to the val with the request flags RqFlg.
• void setB( char val ); TCfg &operator=( bool vl ); void setB( char val, uint8_t RqFlg ); — Set the value of the boolean type to the val with the request flags RqFlg.
• TConfig &owner( ) const; — The object of container-owner.

13.3. Data structure object (TElem)

Public methods:

• TElem( const string &name = "" ); — Initialization of the structure with the specified name name.
• TElem( const TElem &src ); — Copying constructor.
• TElem &operator=( const TElem &src ); — Copying from src.
• string &elName( ); — The name if the structure.
• void fldList( vector<string> &list ); — The cell's list in the structure list.
• unsigned fldSize( ); — The number of cells in the structure.
• unsigned fldId( const string &name, bool noex = false ); — Getting the index of the cell from its identifier name. Set noex on no the cell present caused return overall cells number, without exception generation.
• bool fldPresent( const string &name ); — Check for the presence of the specified cell name.
• int fldAdd( TFld *fld, int id = -1 ); — Addition/insert of the cell fld to the position id (-1 — insert to the end).
• void fldDel( unsigned int id ); — Deleting of the cell id.
• TFld &fldAt( unsigned int id ); — Getting of the cell id.
• void fldClear( ); — Removing all cells.
• void valAtt( TValElem *cnt ); — Is called automatically when the structure is attached to the data storage cnt.
• void valDet( TValElem *cnt ); — Is called automatically when the structure is detached from the data storage cnt.
• ResMtx &resEl( ); — Mutex for access to containers of the fields.

13.4. Data structure cell (TFld)

Data:
Cell's type (enum – TFld::Type):

• TFld::Boolean(0) — boolean type;
• TFld::Integer(1) — integer type;
• TFld::Real(4) — real type;
• TFld::String(5) — string type;
• TFld::Object(6) — object type.
• TFld::GenMask(0x0F) — generic types mask;
• TFld::Int16(0x11) — signed integer 16 bits;
• TFld::Int32(0x01) — signed integer 32 bits;
• TFld::Int64(0x21) — signed integer 64 bits;
• TFld::Float(0x14) — float (4 bytes);
• TFld::Double(0x04) — double (8 bytes).

Cell's flags (enum — TFld::AttrFlg):

• TFld::NoFlag(0x00) — No flags;
• TFld::Selected(0x01) — selection mode from the available values, the selective type;
• TFld::SelfFld(0x02) — To create the own copy of this cell;
• TFld::NoWrite(0x04) — unwritable;
• TFld::HexDec(0x08) — integer type: hexadecimal notation;
• TFld::OctDec(0x10) — integer type: octal notation;
• TFld::DateTimeDec(0x20) — integer type: содержит дату в UTC;
• TFld::FullText(0x08) — Full-text, multi-string mode of the text type;
• TFld::TransltText(0x10) — Translate the text variables of the record.

Public methods:

• TFld( ); — Initialization by default.
• TFld( const TFld &ifld, const char *name = NULL ); — Copying constructor, with possibility for individual name set.
• 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 = "" ); — Initialization with the specified configuration.
• TFld &operator=( const TFld &fld ); — Copy of the cell from fld.
• const string &name( ) const; — Cell's name.
• const string &descr( ) const; — Cell's description.
• int len( ) const; — The size of the cell's value (symbols in symbolic representation).
• int dec( ) const; — The size of the fractional part of a real (symbols in symbolic representation).
• Type type( ) const; — Cell's type.
• static Type type(IO::Type tp); — Cell's type from IO::Type type.
• IO::Type typeIO( ) const; — Cell's type in IO::Type.
• unsigned flg( ) const; — Cell's flag.
• const string &def( ) const; — Default value.
• string values( ) const; — Working range of the value or a list of possible values for the selective type (as — "vl1;vl2;vl3").
• string selNames( ) const; — List of names of values for the selective type (as — "Value 1;Value 2;Value 3").
• const string &reserve( ) const; — Reserve parameter.
• void setDescr( const string &dscr ); — Set the descrition to the dscr.
• void setLen( int vl ); — Set the cell's size to the vl.
• void setDec( int vl ); — Set the fraction part of the real to the vl.
• void setDef( const string &def ); — Set the default value to the def.
• void setFlg( unsigned flg ); — Set the flags to flg.
• void setValues( const string &vls ); — Set the working range of value or the list of possible values for the selective type (as — "vl1;vl2;vl3") to the vls.
• void setSelNames( const string &slnms ); — Set the list of values' names for the selective type (as — "Value 1;Value 2;Value 3") to the slnms.
• void setReserve( const string &ires ); — Set of the reserve parameter to res.
• const vector<string> &selValS() const; — List of values' variants for the string type.
• const vector<int> &selValI() const; — List of values' variants for the integer type.
• const vector<double> &selValR() const; — List of values' variants for the real type
• const vector<bool> &selValB() const; — List of values' variants for the boolean type
• const vector<string> &selNm() const; — List of the names of values' variants.
• string selVl2Nm( const string &val ); — Get the selected name from the value val of the string type.
• string selVl2Nm( int64_t val ); — Get the selected name from the value val of the integer type.
• string selVl2Nm( double val ); — Get the selected name from the value val of the real type.
• string selVl2Nm( bool val ); string selVl2Nm( char val ); — Get the selected name from the value valof the boolean type.
• string selNm2VlS( const string &name ); — Get the value of string type from the selected name name.
• int64_t selNm2VlI( const string &name ); — Get the value of integer type from the selected name name.
• double selNm2VlR( const string &name ); — Get the value of real type from the selected name name.
• bool selNm2VlB( const string &name ); — Get the value of boolean type from the selected name name.
• XMLNode *cntrCmdMake( XMLNode *opt, const string &path, int pos, const string &user = "root", const string &grp = "root", int perm = 0664 ); — Create a form element in accordance with the parameters of the cell.

13.5. The object which preacts about changing of the structure (TValElem)

Protected methods:

• virtual void detElem( TElem *el ); — Notification by the element el of the container about it's wish to detach.
• virtual void addFld( TElem *el, unsigned id ) = 0; — Notification about the addition of the cell id of the element el.
• virtual void delFld( TElem *el, unsigned id ) = 0; — Notification about the deleting of the cell id of the element el.

13.6. Data cell (TVariant)

Data:
Error values for the different data types (define):

• EVAL_BOOL — Error value of the boolean type (2);
• EVAL_INT — Error value of the integer type (-2147483647);
• EVAL_REAL — Error value of the real type (-3.3E308);
• EVAL_STR — Error value of the string type ("<EVAL>").
• EVAL_INT16 — Error value of the integer 16 type (-32767);
• EVAL_INT32 — Error value of the integer 32 type (-2147483647);
• EVAL_INT64 — Error value of the integer 64 type (-9223372036854775807ll);
• EVAL_RFlt — Error value of the real type Float (-3.29E38);
• EVAL_RDbl — Error value of the real type Double (-1.79E308).

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

• TVariant::Null — data type and data is not set.
• TVariant::Boolean — boolean type (boolean, 8бит).
• TVariant::Integer — integer type (integer, 32бит).
• TVariant::Real — real type (double).
• TVariant::String — string.
• TVariant::Object — object.

Public methods:

• TVariant( ); — Default constructor.
• TVariant( char ivl ); TVariant( bool ivl ); — Boolean type constructor.
• TVariant( int64_t ivl ); TVariant( int ivl ); — Integer type constructor.
• TVariant( double ivl ); — Real type constructor.
• TVariant( string ivl ); — String type constructor.
• TVariant( const char *var ); — String type constructor.
• TVariant( AutoHD<TVarObj> ivl ); TVariant( TVarObj *ivl ); — Object constructor.
• TVariant( const TVariant &var ); — Copying constructor.
• bool operator==( const TVariant &vr ) const; — Check the object for equality.
• bool operator!=( const TVariant &vr ) const; — Check the object for not equality.
• TVariant &operator=( const TVariant &vr ); — Copy of the object.
• bool isNull( ) const; — Signs that the object is not initiated.
• bool isEVal( ) const; — Value into the object is error.
• Type type( ) const; — Value's type.
• void setType( Type tp, bool fix = false, bool stdStringOmit = false ); — Set type tp for fixing it fix and use as constant allow stdStringOmit.
• bool isModify( ); — Modification flag. It serves in the object functions to indicate the modification of variables.
• void setModify( bool vl = true ); — Set of the modification flag.
• virtual char getB( ) const; operator char( ); — Getting the value as the boolean one.
• virtual int64_t getI( ) const; operator int64_t( ); operator int( ); — Getting the value as the integer one.
• virtual double getR( ) const; operator double( ); — Getting the value as the real one.
• virtual string getS( ) const; operator string( ); — Getting the value as the string one.
• virtual AutoHD<TVarObj> getO( ) const; operator AutoHD<TVarObj>( ); — Getting the object.
• virtual void setB( char val ); — Set to the value the boolean one.
• virtual void setI( int64_t val ); — Set to the value the integer one.
• virtual void setR( double val ); — Set to the value the real one.
• virtual void setS( const string &val ); — Set to the value the string one.
• virtual void setO( AutoHD<TVarObj> val ); — Set the object.

13.7. User object (TVarObj)

Public methods:

• TVarObj( ); — Constructor.
• int connect( ); — Connection to the object.
• int disconnect( ); — Disconnection from the object.
• virtual void propList( vector<string> &ls ); — Object's properties list ls.
• virtual TVariant propGet( const string &id ); — Request of the object property with an ID id.
• TVariant propGet( const string &ids, char sep ); — Request of the object hierarchical property with a path ids and separator sep.
• virtual void propSet( const string &id, TVariant val ); — Set the object property with an ID id to the value val.
• void propSet( const string &ids, char sep, TVariant val ); — Set the object hierarchical property with a path ids and separator sep to the value val.
• void propClear( const string &ids = "" ); — Property ids clear or all properties clear for empty ids.
• virtual string getStrXML( const string &oid = "" ); — Conversion of the contents of the object in the XML flow.
• static AutoHD<TVarObj> parseStrXML( const string &str, XMLNode *nd = NULL, AutoHD<TVarObj> prev = NULL ); — Backward serialization for XML-stream to object.
• virtual TVariant funcCall( const string &id, vector<TVariant> &prms ); — Call of the object function with the ID id and with the parameters prms.