API OpenSCADA для розробника OpenSCADA та модулів до неї описано у відповідному документі "API OpenSCADA", який завжди має бути під рукою при розробці для OpenSCADA. В цьому ж документі наголос здійснено на детальному роз'яснені основних моментів модульного API.
Модулі в OpenSCADA реалізуються як поділювані бібліотеки та одна така бібліотека може містити багато модулів підсистем OpenSCADA, фактично виступаючи як контейнер. Такі контейнери також можуть бути включені-вбудовані до Бібліотеки Ядра OpenSCADA якщо ви будуєте дуже компактні рішення.
Першим кроком підключення поділюваних бібліотек (SO — Поділювані Об'єкти) є підключення функцій ініціалізації. Такі функції мають бути визначені як звичайні "C" функції для запобігання спотворенню їх назв. Зазвичай це здійснюється наступним чином:
//================== CUT =========================
extern "C"
{
#ifdef MOD_INCL
TModule::SAt bd_Tmpl_module( int n_mod )
#else
TModule::SAt module( int n_mod )
#endif
{
if(n_mod == 0) return TModule::SAt(MOD_ID, MOD_TYPE, VER_TYPE);
return TModule::SAt("");
}
<!--T:348-->
#ifdef MOD_INCL
TModule *bd_Tmpl_attach( const TModule::SAt &AtMod, const string &source )
#else
TModule *attach( const TModule::SAt &AtMod, const string &source )
#endif
{
if(AtMod == TModule::SAt(MOD_ID,MOD_TYPE,VER_TYPE)) return new BDTmpl::BDMod(source);
return NULL;
}
}
//================== CUT =========================
Загальним для всіх модулів є наслідування кореневого об'єкта-класу модуля від класу модульної підсистеми TModule, що вказує на наявність спільної частини інтерфейсу модуля який розглянемо далі. Для отримання уявлення про архітектуру модулів у контексті загальної архітектури OpenSCADA наполегливо рекомендується мати перед очима загальну діаграму класів OpenSCADA!
| Загальне API
|
TCntrNode — Вузол OpenSCADA:
- void preEnable( int flag );, void postEnable( int flag ); — підключення модуля до динамічного дерева об'єктів, викликається перед та після фактичного увімкнення модуля відповідно.
- void preDisable( int flag );, void postDisable( int flag ); — виключення модуля із динамічного дерева об'єктів перед звільненням об'єкту, викликається перед та після фактичного виключення модуля відповідно.
- void load_( TConfig *cfg );, void load_( ); — завантаження модуля із контексту сховища cfg та загалом, викликається на стадії завантаження конфігурації модуля зі сховку.
- void save_( ); — збереження модуля, викликається на стадії збереження конфігурації модуля до сховку, зазвичай за ініціативою користувача.
|
TModule — Модуль OpenSCADA:
- void modStart( ); — запуск модуля, викликається на стадії запуску завдань виконання фонових функцій модуля, якщо такі модулем надаються.
- void modStop( ); — зупинка модуля, викликається на стадії зупинки завдань виконання фонових функцій модуля, якщо такі модулем надаються.
- void modInfo( vector<string> &list ); — запит переліку інформаційних властивостей модуля, яким надається стандартний набір властивостей "Module", "Name", "Type", "Source", "Version", "Author", "Description", "License", та що може бути розширено власними-специфічними властивостями.
- string modInfo( const string &name ); — запит елементу інформації name за якого здійснюється обробка запитів і до власних-специфічних властивостей модуля.
- void modFuncReg( ExpFunc *func ); — реєстрація експортованої функції модуля, яка є частиною механізму міжмодульної взаємодії що реєструє внутрішню функцію модуля для зовнішнього виклику за назвою-символом функції та її вказівником відносно об'єкта модуля. Наразі цей механізм мало якими модулями використовується!
- void perSYSCall( unsigned int cnt ); — виклик із системного-сервісного потоку-завдання з періодичністю 10 секунд та секундним лічильником cnt, може використовуватися для виконання періодичних-рідких сервісних процедур.
|
| API модулів підсистеми "Бази Даних (БД)"
|
Призначено для інтеграції OpenSCADA із БД чи СУБД, яка реалізується модулем. Надає два загальних підходи до реалізації модулів:
- Режим ANSI SQL — є найпростішим шляхом який передбачає безпосереднє використання функцій ядра fieldSQLSeek(), fieldSQLGet(), fieldSQLSet(), fieldSQLDel() у fieldSeek(), fieldGet(), fieldSet(), fieldDel() відповідно; всі SQL-модулі використовують наразі цей підхід.
- Повна Реалізація — є найскладнішим шляхом який передбачає повну реалізацію; модулі, що використовують такий підхід є або старими або специфічними: DBF, LDAP.
|
TTypeBD->TModule — кореневий об'єкт модуля підсистеми "БД":
- string features( ); — перелік ключових слів підтримуваних властивостей БД.
- int lsPr( ); — базовий приорітет БД [0...9] у загальному переліку сховків.
- TBD *openBD( const string &id ); — викликається при відкритті або створені нового об'єкта БД даним модулем з ідентифікатором id.
|
TBD — об'єкт бази даних:
- void enable( ); — включення БД.
- void disable( ); — відключення БД.
- void allowList( vector<string> &list ) const; — запит переліку list таблиць у БД.
- void sqlReq( const string &req, vector< vector<string> > *tbl = NULL, char intoTrans = EVAL_BOOL ); — обробка SQL-запиту req до БД та отримання результату у вигляді таблиці tbl, якщо запит вибірки та вказівник ненульовий. При встановлені intoTrans у TRUE для запиту мусить бути відкрита транзакція, у FALSE закрита. Ця функція має реалізовуватися для СУБД, які підтримують SQL-запити.
- void transCloseCheck( ); — періодично викликається для перевірки транзакцій та закриття старих або які містять багато запитів.
- TTable *openTable( const string &name, bool create ); — викликається при відкритті або створені нового об'єкта таблиці.
|
TTable — об'єкт таблиці у базі даних:
- void fieldStruct( TConfig &cfg ); — отримання поточної структури таблиці у об'єкті cfg.
- bool fieldSeek( int row, TConfig &cfg, const string &cacheKey = "" ); — послідовне сканування записів таблиці перебором row за об'єктом cfg та повернення FALSE по закінченню, з адресацією за активними keyUse() ключовими полями. Ключ кешу cacheKey вказується для предзавантаженням повної відповіді до кешу, із витягненням наступних записів звідти.
- void fieldGet( TConfig &cfg ); — запит вказаного у об'єкті cfg запису із адресацією за ключовими полями.
- void fieldSet( TConfig &cfg ); — передача вказаного у об'єкті cfg запису з адресацією за ключовими полями.
- void fieldDel( TConfig &cfg ); — видалення вказаного запису за ключовими полями об'єкту cfg.
- Специфічне для SQL Баз Даних
- void fieldFix( TConfig &cfg, const string &langLs = "" ); — виправлення структури таблиці БД до cfg та для мов перекладу langLs, зазвичай після невдалого запису.
- string getSQLVal( TCfg &cf, uint8_t RqFlg = 0 ); — повернення специфічно до SQL обгорненого значення cf для прапорців ReqFlg звернення RqFlg.
- void setSQLVal( TCfg &cf, const string &vl, bool tr = false ); — розбір SQL-значення vl для перекладу tr та із записом до cf.
|
| API модулів підсистеми "Транспорти"
|
| Забезпечує OpenSCADA комунікаціями через інтерфейс, часто це мережі які реалізуються цим модулем.
|
TTypeTransport->TModule — кореневий об'єкт модуля підсистеми "Транспорти":
- virtual bool isNetwork( ); — ознака реалізації мережі цим модулем.
- virtual string outAddrHelp( ); — допомога із формату адреси вихідного транспорту.
- virtual TTransportIn *In( const string &id, const string &stor ); — викликається модулем за відкриття або створення нового об'єкту вхідного транспорту із ідентифікатором id та сховком stor.
- virtual TTransportOut *Out( const string &name, const string &stor ); — викликається модулем за відкриття або створення нового об'єкту вихідного транспорту із ідентифікатором id та сховком stor.
|
TTransportIn — об'єкт вхідного транспорту:
- virtual unsigned keepAliveReqs( ); — максимум запитів "Збереження Життя".
- virtual unsigned keepAliveTm( ); — час "Збереження Життя".
- virtual string getStatus( ); — отримання статусу транспорту.
- virtual void start( ); — запуск транспорту.
- virtual void stop( ); — зупинка транспорту.
- virtual int writeTo( const string &sender, const string &data ); — надсилання даних data назад відправнику sender.
 Переважно застаріле та заміщене режимом опитування вхідного транспортного протоколу, Початково реалізується у транспортах із підтримкою ініціативного відправлення, не лише за запитом.
|
TTransportOut — об'єкт вихідного транспорту:
- virtual string timings( ); — таймаути транспорту.
- virtual unsigned short attempts( ); — спроб підключення.
- virtual string getStatus( ); — отримання статусу транспорту.
- virtual void setTimings( const string &vl, bool isDef = false ); — встановлення таймаутів транспорту, як типове за isDef.
- virtual void setAttempts( unsigned short vl ); — встановлення спроб підключення.
- virtual void start( int time = 0 ); — запуск транспорту із таймаутом підключення time. Із запуском вихідного транспорту встановлюється підключення до віддаленої станції для інтерфейсів які передбачають підключення. На цей час можуть виникати помилки якщо підключення неможливе та транспорт має повернутися до стану зупинки.
- virtual void stop( ); — зупинка транспорту.
- virtual int messIO( const char *oBuf, int oLen, char *iBuf = NULL, int iLen = 0, int time = 0 ); — відправка даних через транспорт. Таймаут очікування time підключення в мілісекундах. Негативне значення time вимикає режим транспорту запит/відповідь для незалежного читання/запису до буферу ВВ, із таймаутом читання time у абсолютному значені.
|
| API модулів підсистеми "Транспортні протоколи"
|
| Забезпечує OpenSCADA комунікаціями рівня протоколу, які реалізуються модулем, щодо доступу до даних із зовнішніх систем та надання даних OpenSCADA для зовнішніх систем.
|
TProtocol->TModule — кореневий об'єкт модуля підсистеми "Транспортні протоколи":
- virtual void itemListIn( vector<string> &ls, const string &curIt = "" ); — перелік ls під'елементів вхідного протоколу від поточного елементу curIt, якщо протокол їх надає. Використовується при обранні об'єкта у конфігурації вхідного транспорту.
- virtual void outMess( XMLNode &io, TTransportOut &tro ); — передавання даних об'єктами ядра OpenSCADA у дереві XML io до віддаленої системи через транспорт tro та поточний вихідний протокол. Представлення даних у дереві XML не стандартизоване та специфічне до логічної структури протоколу. Ці дані серіалізуються — перетворюються у послідовність байтів відповідно до протоколу, та надсилаються через визначений вихідний транспорт tro функцією messIO().
- virtual TProtocolIn *in_open( const string &id ); — викликається модулем за відкриття або створення нового об'єкту транспортного протоколу із ідентифікатором id.
|
TProtocolIn — вхідний об'єкт транспортного протоколу з опрацювання вхідних запитів від вхідного транспортного об'єкту TTransportIn. Для кожного сеансу вхідного запиту створюється асоційований об'єкт вхідного протоколу, який залишається живим до завершення повного сеансу "запит->відповідь". Адреса транспорту, який відкриває входження протоколу, визначається у srcTr():
- virtual unsigned waitReqTm( ) — час очікування запиту на вхідному транспорті у мілісекундах, після якого звертається до протоколу із порожнім повідомленням — режим опитування. Встановлення його у нуль вимикає режим опитування.
- virtual void setSrcTr( TTransportIn *vl ) — встановлення транспорту-джерела відкритого сеансу вхідного протоколу.
- virtual void setSrcAddr( const string &vl ); — встановлення адреси відправника.
- virtual bool mess( const string &request, string &answer ); — передавання послідовності даних запиту request до об'єкту протоколу для її розбору відповідно до реалізації протоколу. Ця функція протоколу має опрацювати запит request, згенерувати відповідь у answer та повернути FALSE у випадку повноти запиту. Якщо запит request не повний, необхідно повернути транспорту TRUE для індикації "очікування завершення", попередні частини запиту повинні зберігатися у контексті об'єкту протоколу.
|
| API of the modules of the "Data AcQuisition" subsystem
|
Provides the realtime data acquisition from the external systems or it formation in the calculators, implemented by the module. That is the main subsystem since SCADA is about the Data Acquisition primarily. As the main subsystem it provides several approaches in the modules implementation, which mostly about the attributes structure formation and storing:
- Static formation through definition a set of the parameter types inherited from TTypeParam, that is the structures applying is performed as an attributes set with the parameter type change. This method is least flexible and it used by such modules: GPIO, SMH2Gi, AMRDevs.
- Dynamic formation with the structure container TElem managing in the parameter object TParamContr. This method is most flexible and used in most modules which mean of the structure be configurable.
- As an extension of the dynamic formation there is the Logical Level parameter type, what can be added to any module, but that used mostly in the universal data sources: LogicLev, ModBus, Siemens, OPC_UA.
|
TTypeDAQ->TModule — the root module object of the "Data AcQuisition" subsystem:
- virtual bool compileFuncLangs( vector<string> *ls = NULL ); — request the list ls of languages for which it is realised the possibility of formation of user procedures in this module, and check for fact of that support.
- virtual void compileFuncSnthHgl( const string &lang, XMLNode &shgl ); — request the rules of the syntax highlight shgl for the specified language lang.
- virtual string compileFunc( const string &lang, TFunction &fnc_cfg, const string &prog_text, const string &usings = "", int maxCalcTm = 0 ); — compiling-registering of the user function on the supported programming language lang and on the source code of procedure prog_text, based on the procedure parameters fnc_cfg. Returns address of the compiled function's object, ready for execution.
- virtual bool redntAllow( ); — state of support the redundancy mechanisms by the module. Should be overridden and return TRUE if supported, otherwise FALSE.
- virtual TController *ContrAttach( const string &id, const string &daq_db ); — called when a new controller object is opened or created by this module with the identifier id.
|
TController — the data source controller object. In the context of the object is usually run a task of the periodic or scheduled polling of the realtime data of one physical controller or physically separated block of data. In the case of data getting by the packages, they are placed directly into the archive associated with the parameter attribute TVAl::arch(), and the current value is set by the TVAl::set() function with the attribute "sys"=TRUE:
- virtual string getStatus( ); — request function of the controller status.
- virtual void enable_( ); — enabling of the controller object. Usually at this stage the initialisation of the parameters' objects and their interfaces in the form of attributes is made, the attributes can sometimes be requested from the associated remote source.
- virtual void disable_( ); — disabling the controller object.
- virtual void start_( ); — starting the controller object. Usually at this stage the task of periodic or scheduled polling is created and started.
- virtual void stop_( ); — stopping the controller object.
- virtual void redntDataUpdate( ); — operation of the data receiving from the backup station, called automatically by the service procedure of the redundancy scheme of the subsystem.
- virtual string catsPat( ); — list of the regular expression rules, separated by '|', for matching by category the messages generated by the object.
- virtual void messSet( const string &mess, int lev, const string &type2Code = "OP", const string &prm = "", const string &cat = "" ); — formation of the DAQ-sourced messages for the parameter object prm (PrmId) or the controller object in whole if the parameter object is not specified, for the message mess, level lev and for the type code type2Code. This function generates the messages with the unified DAQ-transparency category "{type2Code}{ModId}:{CntrId}[.{prm}][:{cat}]".
- virtual TParamContr *ParamAttach( const string &id, int type ); — called when a new object of the controller parameter is opened or created by this module with the identifier id.
|
TParamContr->TValue — the controller parameter object of the data source. Contains attributes with real data in a set defined by physically available data. The values to the attributes come from the polling task of the controller, in the asynchronous mode, or are requested during the access, in the synchronous mode, and through the methods of the inherited type TValue:
- virtual TElem *dynElCntr( ); — container of the dynamic elements of the DAQ attributes. Defined mostly by the logical level sources what provide such kind containers.
- virtual void enable( ); — enabling the parameter object, the formation of the attributes set and filling them with the value of unreliability is made.
- virtual void disable( ); — disabling the parameter object.
- virtual void setType( const string &tpId ); — called to change the parameter type to tpId and can be processed in the module object to change own data.
- virtual TVal* vlNew( ); — called at the stage of a new attribute creation. Can be overridden to implement special behavior within its object, inherited from TVal, when accessing the attribute.
- virtual void vlGet( TVal &vo ); — called for the attribute vo with the direct reading mode TVal::DirRead when reading the value in order to directly-synchronous read from the physical source or the object buffer.
- virtual void vlSet( TVal &vo, const TVariant &vl, const TVariant &pvl ); — called for the attribute vo with the direct recording mode TVal::DirWrite when setting the value in order to directly-synchronous set to the physical source or the object buffer, with the previous value pvl.
- virtual void vlArchMake( TVal &val ); — called at the stage of creation the values archive with the val attribute as the source in the order to initialise the qualitative characteristics of the archive buffer according to the characteristics of the data source and polling.
|
| API модулів підсистеми "Архіви-Історія"
|
| Використовується для архівування та ведення історії повідомлень і значень реального часу отриманих у підсистемі "Збір Даних", та у засіб реалізований модулем.
|
TTypeArchivator->TModule — кореневий об'єкт модуля підсистеми "Архіви-Історія":
- virtual TMArchivator *AMess( const string &id, const string &stor ); — викликається модулем за відкриття або створення нового об'єкту архіватору повідомлень із ідентифікатором id та у сховку stor.
- virtual TVArchivator *AVal( const string &id, const string &stor ); — викликається модулем за відкриття або створення нового об'єкту архіватору значень із ідентифікатором id та у сховку stor.
|
TMArchivator — об'єкт архіватору повідомлень.
- virtual void redntDataUpdate( ); — операція отримання даних із резервної станції, автоматично викликається сервісною процедурою схеми резервування підсистеми.
- virtual void start( ); — запуск об'єкту архіватору, архіватор запускається для отримання повідомлень та розміщення їх до сховку.
- virtual void stop( ); — зупинка об'єкту архіватору.
- virtual time_t begin( ); — час початку даних архіватору у відповідності до поточного стану сховку.
- virtual time_t end( ); — час закінчення даних архіватору у відповідності до поточного стану сховку.
- virtual bool put( vector<TMess::SRec> &mess, bool force = false ); — розташування групи повідомлень mess до архіватору. Повертає TRUE за успішної операції. Встановити force для прямого запису до архіву оминаючи резервування.
- virtual time_t get( time_t bTm, time_t eTm, vector<TMess::SRec> &mess, const string &category = "", char level = 0, time_t upTo = 0 ); — отримання повідомлень до mess із архіватору для визначених параметрів фільтрації. Повертає час зупинки запиту, корисно для продовження від цієї позиції як часу закінчення, тобто ітераційно заглиблюючись в історію. Фільтр визначається діапазоном часу [bTm...eTm], правилами категорії category, рівнем level та обмежено до часу upTo. За відсутності прямого визначення обмежувального часу upTo, це обмеження встановлюється у prmInterf_TM — 7 секунд.
|
TVArchivator — об'єкт архіватору значень.
- virtual void start( ); — запуск об'єкту архіватору, архіватор запускається для отримання значень та розміщення їх у сховок.
- virtual void stop( bool full_del = false ); — зупинка об'єкту архіватору із можливістю повного видалення його даних зі сховку за full_del.
- virtual TVArchEl *getArchEl( TVArchive &arch ); — отримання об'єкту елемента архіву значень для визначеного архіву arch.
- virtual void pushAccumVals( ); — виштовхування накопичених завданням архівації значень, для акумулювальних архіваторів.
|
TVArchEl — об'єкт елементу архіватору значень.
- virtual void fullErase( ); — викликається для цілковитого видалення архівної частини архіватору.
- virtual int64_t end( ); — час завершення у мікросекундах щодо наявних значень у архіві архіватору.
- virtual int64_t begin( ); — час початку у мікросекундах щодо наявних значень у архіві архіватору.
- virtual TVariant getValProc( int64_t *tm, bool up_ord ); — запит одного значення із архіву на час tm та із підтягненням до верхнього значення у ґратці вимірювання up_ord.
- virtual void getValsProc( TValBuf &buf, int64_t beg, int64_t end ); — запит групи значень до buf із архіву та для діапазону часу [beg...end].
- virtual void setValsProc( TValBuf &buf, int64_t beg, int64_t end, bool toAccum ); — встановлення групи значень buf до архіву, для діапазону часу [beg...end] та через акумуляцію toAccum.
|
| API модулів підсистеми "Користувацькі Інтерфейси"
|
| Користувацький інтерфейс формується згідно до концепції та механізмів зовнішніх розповсюджених стандартів та бібліотек.
|
TUI->TModule — кореневий об'єкт модуля підсистеми "Користувацькі Інтерфейси":
Не містить специфічних функцій!
|
| API модулів підсистеми "Спеціальне"
|
| Реалізує специфічні функції, які не увійшли до жодної з вищеперелічених підсистем. Специфічні функції формуються згідно їх власних вимог та із використанням всіх можливостей API OpenSCADA.
|
TSpecial->TModule — кореневий об'єкт модуля підсистеми "Спеціальне":
Не містить специфічних функцій!
|
