OpenSCADAWiki: Doc/API/part3 ...

3. Ïîäñèñòåìà “Áàçû Äàííûõ” (TBDS)

Ïîäñèñòåìà «Áàçû Äàííûõ» ïðåäñòàâëåíà îáúåêòîì TBDS, êîòîðûé ñîäåðæèò ìîäóëüíûå îáúåêòû òèïîâ ÁÄ TTypeBD. Êàæäûé òèï áàçû äàííûõ ñîäåðæèò îáúåêòû îòäåëüíî âçÿòûõ áàç äàííûõ äàííîãî òèïà TBD. Êàæäàÿ ÁÄ, â ñâîþ î÷åðåäü, ñîäåðæèò îáúåêòû ñâîèõ òàáëèö TTable (ðèñ. 3).

Ðèñ. 3. Èåðàðõè÷åñêàÿ ñòðóêòóðà ïîäñèñòåìû ÁÄ.

Ïîäñèñòåìà ïðåäñòàâëÿåò áàçîâûå ôóíêöèè äëÿ äîñòóïà ê òèïàì ÁÄ, à òàêæå îáîáùàþùèå ôóíêöèè äëÿ ìàíèïóëÿöèè ñ áàçàìè äàííûõ è òàáëèöàìè. Òàê, äëÿ ñîêðûòèÿ èñòî÷íèêà äàííûõ, êîòîðûì ìîæåò áûòü è êîíôèãóðàöèîííûé ôàéë, ïðåäîñòàâëÿþòñÿ ôóíêöèè àáñòðàêòíîãî äîñòóïà ê èñòî÷íèêó äàííûõ. À äëÿ õðàíåíèÿ îáùåñèñòåìíûõ äàííûõ ïðåäîñòàâëÿåòñÿ ñèñòåìíàÿ òàáëèöà è ôóíêöèè àáñòðàêòíîãî äîñòóïà ê íåé. Ñëåäîâàòåëüíî, îáùåñèñòåìíûå äàííûå ìîãóò õðàíèòüñÿ êàê â êîíôèãóðàöèîííîì ôàéëå, òàê è â òàáëèöå ÁÄ. Ïðèîðèòåòíûì èñòî÷íèêîì â òàêîì ñëó÷àå ÿâëÿåòñÿ òàáëèöà ÁÄ.

ßâëÿÿñü ìîäóëüíûì îáúåêòîì, òèï ÁÄ (TTypeBD) ñîäåðæèò äîñòóï ê ðåàëèçàöèè ìåõàíèçìà òîé èëè èíîé ÁÄ. Äîñòóï ïðîèçâîäèòñÿ ïîñðåäñòâîì îòêðûòûõ ÁÄ ìîäóëÿ îòäåëüíî âçÿòîãî òèïà ÁÄ. Îòêðûâàåìûå/ðåãèñòðèðóåìûå ÁÄ îïèñûâàþòñÿ â òàáëèöå îòêðûâàåìûõ ÁÄ èëè â êîíôèãóðàöèîííîì ôàéëå. Ñóùåñòâóåò òàê íàçûâàåìàÿ ðàáî÷àÿ ÁÄ, êîòîðàÿ îòêðûâàåòñÿ âñåãäà è óêàçûâàåòñÿ â êîíôèãóðàöèîííîì ôàéëå. ÁÄ, ïîääåðæèâàþùèå SQL-çàïðîñû, ìîãóò ïðåäîñòàâëÿòü äîñòóï, îñíîâàííûé íà ïðÿìûõ SQL-çàïðîñàõ.

 ïðîöåññå èñïîëüçîâàíèÿ êîìïîíåíòû ñèñòåìû OpenSCADA îòêðûâàþò òàáëèöû (TTable) â äîñòóïíûõ ÁÄ è ðàáîòàþò ñ íèìè.

3.1. Îáúåêò ïîäñèñòåìû «Áàçû Äàííûõ» (TBDS)

Äàííûå:
Ôëàãè çàïðîñîâ ê ñèñòåìíîé òàáëèöå (enum – TDBS::ReqGen):

• OnlyCfg — çàïðîñ òîëüêî ê êîíôèãóðàöèîííîìó ôàéëó.
• UseTranslate — èñïîëüçîâàòü ïåðåâîä òåêñòîâîé ïåðåìåííîé.

Ïóáëè÷íûå ìåòîäû:

• int subVer( ); — Âåðñèÿ ïîäñèñòåìû.
• static string realDBName( const string &bdn ); — Ïðåîáðàçîâàíèå ïîëíîãî øàáëîííîãî èìåíè ÁÄ èëè òàáëèöû (âèäà *.*.myTbl) â ðåàëüíîå èìÿ. Ôàêòè÷åñêè âûïîëíÿåòñÿ çàìåíà ñïåöèàëüíûõ ýëåìåíòîâ '*' íà ýëåìåíòû ðàáî÷åé ÁÄ.
• void dbList( vector<string> &ls, bool checkSel = false ); — Ñïèñîê äîñòóïíûõ ÁÄ. checkSel óêàçûâàåò íà íåîáõîäèìîñòü ïðîâåðêè ôàêòà çàãðóçêè èç âûáðàííîé ÁÄ è âñòàâêè â ñïèñîê ÁÄ òîëüêî âûáðàííîé.
• AutoHD<TTable> open( const string &bdn, bool create = false ); — Îòêðûòèå òàáëèöû bdn ÁÄ ïî å¸ ïîëíîìó ïóòè ñ ñîçäàíèåì create â ñëó÷àå îòñóòñòâèÿ.
• void close( const string &bdn, bool del = false ); — Çàêðûòèå òàáëèöû bdn ÁÄ ïî å¸ ïîëíîìó ïóòè ñ âîçìîæíîñòüþ óäàëåíèÿ ïîñëå çàêðûòèÿ del.
• bool dataSeek( const string &bdn, const string &path, int lev, TConfig &cfg, bool forceCfg = false ); — Îáùåå ñêàíèðîâàíèå çàïèñåé èñòî÷íèêà äàííûõ.  êà÷åñòâå èñòî÷íèêà âûñòóïàåò êîíôèãóðàöèîííûé ôàéë èëè ÁÄ.  ñëó÷àå îòñóòñòâèÿ ÁÄ èñïîëüçóåòñÿ êîíôèãóðàöèîííûé ôàéë. Åñëè èìÿ ÁÄ bdn èëè ïóòü path êîíôèãóðàöèîííîãî ôàéëà íå óêàçàíû, òî èõ îáðàáîòêà ïðîïóñêàåòñÿ.
• bool dataGet( const string &bdn, const string &path, TConfig &cfg, bool forceCfg = false, bool noEx = false ); — Ïîëó÷åíèå çàïèñè èç èñòî÷íèêà äàííûõ (ÁÄ èëè êîíôèãóðàöèîííûé ôàéë). Åñëè èìÿ ÁÄ bdn èëè ïóòü path êîíôèãóðàöèîííîãî ôàéëà íå óêàçàíû, òî èõ îáðàáîòêà ïðîïóñêàåòñÿ.
• void dataSet( const string &bdn, const string &path, TConfig &cfg, bool forceCfg = false, bool noEx = false ); — Óñòàíîâèòü/ñîõðàíèòü çàïèñü â èñòî÷íèêå äàííûõ (ÁÄ èëè êîíôèãóðàöèîííûé ôàéë). Åñëè èìÿ ÁÄ bdn èëè ïóòü path êîíôèãóðàöèîííîãî ôàéëà íå óêàçàíû, òî èõ îáðàáîòêà ïðîïóñêàåòñÿ.
• bool dataDel( const string &bdn, const string &path, TConfig &cfg, bool useKeyAll = false, bool forceCfg = false, bool noEx = false ); — Óäàëåíèå çàïèñè èç èñòî÷íèêà äàííûõ (ÁÄ èëè êîíôèãóðàöèîííûé ôàéë). Åñëè èìÿ ÁÄ bdn èëè ïóòü path êîíôèãóðàöèîííîãî ôàéëà íå óêàçàíû, òî èõ îáðàáîòêà ïðîïóñêàåòñÿ. useKeyAll èñïîëüçóåòñÿ äëÿ óêàçàíèÿ íåîáõîäèìîñòè óñòàíîâêè âñåõ êëþ÷åé äëÿ èñïîëüçîâàíèÿ èõ ïðè óäàëåíèè ñ âîññòàíîâëåíèåì èñõîäíîãî ñîñòîÿíèé âûáîðà êëþ÷åé ïðè âûõîäå èç ôóíêöèè. Åñëè ýòîò ôëàã íå óñòàíîâëåí, òî èñïîëüçóþòñÿ ðàíåå âûáðàííûå êëþ÷è äëÿ âûïîëíåíèÿ îïåðàöèè.
• static string genDBGet( const string &path, const string &oval = "", const string &user = "root", char rFlg = 0 ); — Ïîëó÷èòü îáùåñèñòåìíûå äàííûå èç êîíôèãóðàöèîííîãî ôàéëà èëè ñèñòåìíîé òàáëèöû îò èìåíè ïîëüçîâàòåëÿ user. Åñëè äàííûå îòñóòñòâóþò, òî âîçâðàùàåòñÿ çíà÷åíèé oval.
• static void genDBSet( const string &path, const string &val, const string &user = "root", char rFlg = 0 ); — Óñòàíîâèòü/ñîõðàíèòü îáùå-ñèñòåìíûå äàííûå â êîíôèãóðàöèîííîì ôàéëå èëè ñèñòåìíîé òàáëèöå îò èìåíè ïîëüçîâàòåëÿ user.
• string fullDBSYS( ); — Ïîëíîå èìÿ ñèñòåìíîé òàáëèöû.
• string fullDB( ); — Ïîëíîå èìÿ òàáëèöû ñ îïèñàíèåì çàðåãèñòðèðîâàííûõ ÁÄ.
• TElem &openDB_E( ) — Ñòðóêòóðà òàáëèöû çàðåãèñòðèðîâàííûõ ÁÄ.
• AutoHD<TTypeBD> at( const string &iid ) — Îáðàùåíèå ê ìîäóëþ ÁÄ (òèïó ÁÄ).
• string optDescr( ); — Ëîêàëèçîâàííàÿ ïîìîùü ïî îïöèÿì êîìàíäíîé ñòðîêè è ïàðàìåòðàì êîíôèãóðàöèîííîãî ôàéëà.

3.2. Ìîäóëüíûé îáúåêò òèïîâ áàç äàííûõ (TTypeBD)

Ïóáëè÷íûå ìåòîäû:

• bool fullDeleteDB( ); — Ïðèçíàê ïîëíîãî óäàëåíèÿ ÁÄ.
• void list( vector<string> &list ); — Ñïèñîê çàðåãèñòðèðîâàííûõ (îòêðûòûõ) ÁÄ.
• bool openStat( const string &idb ); — Ïðîâåðêà íà íàëè÷èå óêàçàííîé îòêðûòîé ÁÄ.
• void open( const string &iid ); — Îòêðûòèå ÁÄ.
• void close( const string &iid, bool erase = false ); — Çàêðûòèå ÁÄ. Åñëè óñòàíîâëåí ïðèçíàê erase, òî ÁÄ áóäåò ïîëíîñòüþ óäàëåíà.
• AutoHD<TBD> at( const string &name ); — Ïîäêëþ÷åíèå ê îòêðûòîé ÁÄ.
• TBDS &owner( ); — Ïîäñèñòåìà - âëàäåëåö ìîäóëÿ.

3.3. Îáúåêò áàçû äàííûõ (TBD)

Ïóáëè÷íûå ìåòîäû:

• TBD( const string &iid, TElem *cf_el ); — Èíèöèàëèçèðóþùèé êîíñòðóêòîð.
• string id( ); — Èäåíòèôèêàòîð ÁÄ.
• string fullDBName( ); — Ïîëíîå èìÿ õðàíèëèùà-ÁÄ.
• string name( ); — Èìÿ ÁÄ.
• string dscr( ); — Îïèñàíèå ÁÄ.
• string addr( ); — Àäðåñ ÁÄ. Ôîðìà çàïèñè îòëè÷íà äëÿ êàæäîãî òèïà ÁÄ.
• string codePage( ); — Êîäîâàÿ ñòðàíèöà, â êîòîðîé õðàíÿòñÿ äàííûå ÁÄ.
• bool enableStat( ); — Ñîñòîÿíèå ÁÄ: "Âêëþ÷åíà".
• bool toEnable( ); — Ïðèçíàê ÁÄ: "Âêëþ÷àòü".
• void setName( const string &inm ); — Óñòàíîâêà èìåíè ÁÄ.
• void setDscr( const string &idscr ); — Óñòàíîâêà îïèñàíèÿ ÁÄ.
• void setAddr( const string &iaddr ); — Óñòàíîâêà àäðåñà ÁÄ.
• void setCodePage( const string &icp ); — Óñòàíîâêà êîäîâîé ñòðàíèöû õðàíåíèÿ äàííûõ â ÁÄ.
• void setToEnable( bool ivl ); — Óñòàíîâêà ïðèçíàêà: "Âêëþ÷àòü".
• virtual void enable( ); — Âêëþ÷åíèå ÁÄ.
• virtual void disable( ); — Îòêëþ÷åíèå ÁÄ.
• virtual void allowList( vector<string> &list ); — Ñïèñîê òàáëèö, ñîäåðæàùèõñÿ â äàííîé ÁÄ.
• void list( vector<string> &list ); — Ñïèñîê îòêðûòûõ òàáëèö.
• bool openStat( const string &table ); — Ïðèçíàê óêàçûâàþùèé íà òî, ÷òî çàïðîøåííàÿ òàáëèöà îòêðûòà.
• void open( const string &table, bool create ); — Îòêðûòèå òàáëèöû. Åñëè óñòàíîâëåí ïðèçíàê create, òî â ñëó÷àå îòñóòñòâèÿ òàáëèöà áóäåò ñîçäàíà.
• void close( const string &table, bool del = false, long tm = -1 ); — Çàêðûòèå òàáëèöû. Åñëè óñòàíîâëåí ïðèçíàê del, òî òàáëèöà áóäåò ïîëíîñòüþ óäàëåíà.
• AutoHD<TTable> at( const string &name ); — Ïîäêëþ÷åíèå ê òàáëèöå.
• virtual void sqlReq( const string &req, vector< vector<string> > *tbl = NULL, char intoTrans = EVAL_BOOL ); — Îòïðàâêà SQL-çàïðîñà req íà ÁÄ è ïîëó÷åíèå ðåçóëüòàòà â âèäå òàáëèöû tbl. Ïðè óñòàíîâêå intoTrans â true äëÿ çàïðîñà áóäåò îòêðûòà òðàíçàêöèÿ, â false áóäåò çàêðûòà.
• virtual void transCloseCheck( ) — Ïåðèîäè÷åñêè âûçûâàåìàÿ ôóíêöèÿ äëÿ ïðîâåðêè òðàíçàêöèé è çàêðûòèÿ ñòàðûõ èëè ñîäåðæàùèõ ìíîãî çàïðîñîâ.
• TTypeBD &owner( ); — Òèï áàçû äàííûõ – âëàäåëåö äàííîé ÁÄ.

Çàùèù¸ííûå ìåòîäû:

• virtual TTable *openTable( const string &table, bool create ); — Ìîäóëüíûé ìåòîä îòêðûòèÿ òàáëèöû.

3.4. Îáúåêò òàáëèöû (TTable)

Ïóáëè÷íûå ìåòîäû:

• TTable( const string &name ); — Èíèöèàëèçèðóþùèé êîíñòðóêòîð.
• string name( ); — Èìÿ òàáëèöû.
• string fullDBName( ); — Ïîëíîå èìÿ õðàíèëèùà-òàáëèöû â ÁÄ.
• virtual void fieldStruct( TConfig &cfg ); — Ïîëó÷åíèå ñòðóêòóðû òàáëèöû.
• virtual bool fieldSeek( int row, TConfig &cfg ); — Ñêàíèðîâàíèå çàïèñåé òàáëèöû.
• virtual void fieldGet( TConfig &cfg ); — Çàïðîñ óêàçàííîé çàïèñè. Çàïðàøèâàåìàÿ çàïèñü îïðåäåëÿåòñÿ çíà÷åíèÿìè êëþ÷åâûõ ÿ÷ååê èñõîäíîé çàïèñè cfg.
• virtual void fieldSet( TConfig &cfg ); — Óñòàíîâêà çíà÷åíèé óêàçàííîé çàïèñè.  ñëó÷àå îòñóòñòâèÿ çàïèñü áóäåò ñîçäàíà.
• virtual void fieldDel( TConfig &cfg ); — Óäàëåíèå óêàçàííîé çàïèñè.
• TBD &owner( ); — ÁÄ – âëàäåëåö äàííîé òàáëèöû.