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 ); - 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 ); - 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 ); - 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 ); - 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.
• const string &id( ); - DB identifier.
• string name( ); - DB name.
• const string &dscr( ); - DB description.
• const string &addr( ); - Address of the database. The form of recording is different for each type of database.
• const 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 ); - 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.
• const string &name( ); - Table name.
• 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.