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

3. Subsystem "Database" (TBDS)

Subsystem «Databases» is represented by the object TBDS, which contains a modular objects of the following types of DB TTipBD. Each type of database contains objects of individual databases of that type TBD. Each database in its turn, contains the objects of their tables TTable (Fig. 3).

Fig. 3. Hierarchical structure of the database subsystem.

The subsystem provides the basic functions to access the type of database, as well as generalized functions for the manipulation of the databases and tables. For example, to hide the source of data, which may be a configuration file, the functions of an abstract access to the data source are provided. For the storage system-wide data the system table and the function of the abstract to access it are provided. Consequently, system-wide data can be stored in the configuration file and in the database table. Priority source, in this case, is the database table.

Being a modular object, the type of database (TTipBD) provides access to the implementation of the mechanism of one or another database. Access is made through a public databases of the module of a given type of database. Open/registered database is described in the table of databases to be opened or in the configuration file. There is, the so-called, the working database, which is always opens and is shown in the configuration file. DB which support the SQL-queries can grant access based on direct SQL-queries.

While working, the components of the OpenSCADA system open tables (TTable) available in the database and work with them.

3.1. Object of subsystem «Database» (TBDS)

Data:
Flags of the queries to the system table (enum – TDBS::ReqGen):

• OnlyCfg — request only to the configuration file.
• UseTranslate — use the translation of text variable.

Public methods:

• int subVer( ); — Subsystem version.
• static string realDBName( const string &bdn ); — Conversion of the full template name of the database or table (of view *.*.myTbl) in the real name. Actually the replacement of the special elements '*' by the elements of the working DB.
• void dbList( vector<string> &ls, bool checkSel = false ); — A list of available databases.. checkSel points to the necessity to verify the fact of boot from the selected database and to insert to the db list the only selected one.
• AutoHD<TTable> open( const string &bdn, bool create = false ); — Opening the table bdn of the DB by its full path with the creation create in the case of its absence.
• void close( const string &bdn, bool del = false ); — Closing the table bdn of the DB by its full path with the possibility of deleting of it after closing del.
• bool dataSeek( const string &bdn, const string &path, int lev, TConfig &cfg, bool forceCfg = false ); — Total scanning of the records of the data source. The configuration file of the DB is the source if data. In the case of DB absence the configuration file is used. If the DB name bdn or path path to the configuration file are not indicated, their processing is skipped.
• bool dataGet( const string &bdn, const string &path, TConfig &cfg, bool forceCfg = false, bool noEx = false ); — Getting the record from the data source (database or configuration file). If the DB name bdn or path path to the configuration file are not indicated, their processing is skipped.
• void dataSet( const string &bdn, const string &path, TConfig &cfg, bool forceCfg = false, bool noEx = false ); — Set/Save the record in the data source (database or configuration file). If the DB name bdn or path path to the configuration file are not indicated, their processing is skipped.
• bool dataDel( const string &bdn, const string &path, TConfig &cfg, bool useKeyAll = false, bool forceCfg = false, bool noEx = false ); — Deleting the record in the data source (database or configuration file). If the DB name bdn or path path to the configuration file are not indicated, their processing is skipped. useKeyAll is used to indicate the necessity of the all keys set fro their using while deleting with the restoration of the original state of the keys selection when the function is finished. If this flag is not set, the early selected keys are used to perform the operation.
• static string genDBGet( const string &path, const string &oval = "", const string &user = "root", char rFlg = 0 ); — Get system-wide data from the configuration file or system tables on behalf of user name user. If data are not available the value oval is returned.
• static void genDBSet( const string &path, const string &val, const string &user = "root", char rFlg = 0 ); — Set/Save the system-wide data in the configuration file or system tables on behalf of user name user.
• string fullDBSYS( ); — The full name of the system table.
• string fullDB( ); — The full name of the table with a description of the registered databases.
• TElem &openDB_E( ) — The structure of the table of registered databases.
• AutoHD<TTipBD> at( const string &iid ) — Referencing to the DB module(DB type).
• string optDescr( ); — Localized help on the command line options and parameters in the configuration file.

3.2. Modular object of types of databases (TTipBD)

Public methods:

• bool fullDeleteDB( ); — Sign of the complete removal of the database.
• void list( vector<string> &list ); — The list of registered (opened) databases.
• bool openStat( const string &idb ); — Check the availability of the specified opened database.
• void open( const string &iid ); — Opening of the database.
• void close( const string &iid, bool erase = false ); — Closing the database. If the sign erase is set, the database will be completely removed.
• AutoHD<TBD> at( const string &name ); — Connection to the opened database.
• TBDS &owner( ); — Subsystem - the owner of the module.

3.3. The object of the database (TBD)

Public methods:

• TBD( const string &iid, TElem *cf_el ); — Initializing constructor.
• string id( ); — DB identifier.
• string name( ); — DB name.
• string dscr( ); — DB description.
• string addr( ); — Address of the database. The form of recording is different for each type of database.
• string codePage( ); — Codepage in which the data of the database are stored.
• bool enableStat( ); — The state of the database: «Enabled».
• bool toEnable( ); — Sign of the DB: "To Enable".
• void setName( const string &inm ); — Setting the DB name.
• void setDscr( const string &idscr ); — Setting the DB description.
• void setAddr( const string &iaddr ); — Setting the DB address.
• void setCodePage( const string &icp ); — Setting of the codepage for the storage of the DB data.
• void setToEnable( bool ivl ); — Setting of the sign: "To Enable".
• virtual void enable( ); — Enabling of the DB.
• virtual void disable( ); — Disabling of the DB.
• virtual void allowList( vector<string> &list ); — The list of the tables in this DB.
• void list( vector<string> &list ); — The list of opened tables.
• bool openStat( const string &table ); — The sign that indicates of the fact that the requested table is opened.
• void open( const string &table, bool create ); — Opening of the table. If the sign create is set, in the case of absence the table will be created.
• void close( const string &table, bool del = false, long tm = -1 ); — Closing of the table. If the sign del is set, the table will be completely removed.
• AutoHD<TTable> at( const string &name ); — Connection to the table.
• virtual void sqlReq( const string &req, vector< vector<string> > *tbl = NULL, char intoTrans = EVAL_BOOL ); — Sending the SQL-request req to the DB and receiving the result in tabular form tbl. If set intoTrans to true then will open transaction for the request, else if set to false then transaction will close.
• virtual void transCloseCheck( ) — The function call periodic for opened transaction check to close for old transaction or overloaded.
• TTipBD &owner( ); — DB type – the owner of the DB.

Protected methods:

• virtual TTable *openTable( const string &table, bool create ); — The modular method for opening the table.

3.4. The object of the table (TTable)

Public methods:

• TTable( const string &name ); — Initializing constructor.
• string name( ); — Table name.
• string fullDBName( ); — Full name a storage-table into DB.
• virtual void fieldStruct( TConfig &cfg ); — Getting the structure of the table.
• virtual bool fieldSeek( int row, TConfig &cfg ); — Scanning the records of the table.
• virtual void fieldGet( TConfig &cfg ); — Request the specified record. The requested record is determined by the values of key cells of the original record cfg.
• virtual void fieldSet( TConfig &cfg ); — Setting the values of the specified record. In te case of absence the record will be removed.
• virtual void fieldDel( TConfig &cfg ); — Deleting of the specified record.
• TBD &owner( ); — DB – the owner of the table.