Документація/API користувача

This page is a translated version of the page Documents/User API and the translation is 100% complete.

Other languages:
English • ‎российский • ‎українська
Constr.png The translation checking and actualizing

Автор: Роман Савоченко

Contents

До початку програмування у OpenSCADA Ви маєте вивчити структуру об'єктів програми у посібнику по програмі OpenSCADA. З цього документу Ви побачите, що Ви можете як користувач програмувати наступні частини OpenSCADA:

API користувацького програмування представляє собою дерево об'єктів OpenSCADA, кожний об'єкт якого може надавати власний перелік властивостей та функцій. Властивості та функції об'єктів можуть використовуватися користувачем у процедурах на мовах користувацького програмування OpenSCADA.

На цей час OpenSCADA надає тільки одну мову текстового програмування це JavaLikeCalc, відповідно Ви також повинні її вивчити перед початком. Точкою входу для доступу до об'єктів OpenSCADA з мови користувацького програмування JavaLikeCalc є зарезервоване слово "SYS" кореневого об'єкту OpenSCADA. Наприклад, для доступу до функції вихідного транспорту треба записати: SYS.Transport.Serial.out_ModBus.messIO(mess);.

API об'єктів, які надаються модулями, описуються у власній документації модулів.

1 Загальносистемні користувацькі об'єкти

JavaLikeCalc надає підтримку типу даних об'єкт "Object". Об'єкт представляє собою асоціативний контейнер властивостей та функцій. Властивості можуть містити як дані чотирьох базових типів, так і інші об'єкти. Доступ до властивостей об'єкту може здійснюватися за посередництвом запису імен властивостей через точку до об'єкту obj.prop, а також за посередництвом заключення імені властивості у квадратні дужки obj["prop"]. Очевидно, що перший механізм статичний, а другий дозволяє вказувати ім'я властивості через змінну. Видалити властивість об'єкту можна директивою "delete". Читання невизначеної властивості поверне EVAL. Створення об'єкту здійснюється за посередництвом ключового слова new: varO = new Object(). Базове визначення об'єкту не містить функцій. Операції копіювання об'єкту насправді роблять посилання на вихідний об'єкт. При видаленні об'єкту здійснюється зменшення лічильника посилань, а при досягнення лічильника посилань нуля об'єкт видаляється фізично.

Різні компоненти можуть довизначати базовий об'єкт особливими властивостями та функціями. Стандартним розширенням об'єкту є масив "Array", який створюється командою varO = new Array(prm1,prm2,prm3,...,prmN). Перелічені через кому параметри поміщаються до масиву у вихідній послідовності. Якщо параметр тільки один тоді масив ініціюється вказаною кількістю порожніх елементів. Особливістю масиву є те, що він працює із властивостями як з індексами та основним механізмом звернення є заключення індексу у квадратні дужки arr[1]. Масив зберігає властивості у власному контейнері одномірного масиву. Цифрові властивості масиву використовуються для доступу безпосередньо до масиву, а символьні працюють як властивості об'єкту. Детальніше про властивості та функції масиву можна прочитати за посиланням.

Об'єкт регулярного виразу "RegExp" створюється командою varO = new RegExp(pat,flg), де pat — шаблон регулярного виразу, а flg — ознаки пошуку. Об'єкт роботи із регулярними виразами оснований на бібліотеці "PCRE". При глобальному пошуку встановлюється атрибут об'єкту "lastIndex", що дозволяє продовжити пошук при наступному виклику функції. У випадку невдалого пошуку атрибут "lastIndex" скидається у нуль. Детальніше про властивості та функції об'єкту регулярного виразу можна прочитати за посиланням.

Для довільного доступу до аргументів функції передбачено об'єкт аргументів, звернутися до якого можна за посередництвом символу "arguments". Цей об'єкт містить властивість "length" з кількістю аргументів у функції та дозволяє звернутися до значень аргументу за посередництвом його номеру або ідентифікатору. Розглянемо перебір аргументів по циклу:

args = new Array();
for(var i=0; i < arguments.length; i++)
  args[i] = arguments[i];

Часткові властивості об'єкту мають і базові типи. Властивості та функції базових типів приведено нижче:

Властивості:
  • MAX_VALUE — максимальне значення;
  • MIN_VALUE — мінімальне значення;
  • NaN — недостовірне значення.
Функції:
  • bool isEVal(); — Перевірка значення на "EVAL".
  • string toExponential( int numbs = -1 ); — Повернення рядка, відформатованого числа у експоненціальній нотації та кількістю значущих цифр numbs. Якщо numbs відсутній то цифр буде стільки скільки потрібно.
  • string toFixed( int numbs = 0, int len = 0, bool sign = false ); — Повернення рядку відформатованого числа в нотації з фіксованою точкою та кількістю цифр після десяткової точки numbs з мінімальною довжиною len та обов'язковим знаком sign. Якщо numbs відсутній то кількість цифр після десяткової точки дорівнює нулю.
  • string toPrecision( int prec = -1 ); — Повернення рядка відформатованого числа з кількістю значущих цифр prec.
  • string toString( int base = 10, int len = -1, bool sign = false ); — Повернення рядку відформатованого числа цілого типу з базою представлення base (2-36) з мінімальною довжиною len та обов'язковим знаком sign.
Властивості:
  • int length — довжина рядка.
Функції:
  • bool isEVal(); — Перевірка значення на "EVAL".
  • string charAt( int symb ); — Вилучає із рядка символ номер symb, нумерація символів з нуля.
  • int charCodeAt( int symb ); — Вилучає із рядка код символу symb.
  • string concat( string val1, string val2, ... ); — Повертає новий рядок сформований шляхом приєднання значень val1 і т.п. до початкового.
  • int indexOf( string substr, int start ); — Повертає позицію пошукового рядка substr у вихідному рядку починаючи з позиції start. Якщо вихідна позиція не вказана то пошук починається з початку. Якщо шуканого рядка не знайдено то повертається "-1".
  • int lastIndexOf( string substr, int start ); — Повертає позицію шуканого рядка substr у вихідному рядку починаючи з позиції start, при пошуку з кінця. Якщо вихідна позиція не вказана то пошук починається з кінця. Якщо шуканого рядку не знайдено то повертається "-1".
  • int search( string pat, string flg = "" ); — Пошук у рядку за шаблоном pat та ознаками шаблону flg. Повертає положення найденого рядку інакше "-1".
var rez = "Java123Script".search("script","i");  // rez = 7
  • int search( RegExp pat ); — Пошук у рядку за шаблоном "RegExp" pat. Повертає положення найденого підрядку інакше "-1".
var rez = "Java123Script".search(new RegExp("script","i"));  // rez = 7
  • Array match( string pat, string flg = "" ); — Пошук в рядку за шаблоном pat та ознаками шаблону flg. Повертає масив із знайденим підрядком (0) та підвиразами (>1). Атрибут "index" масиву встановлюється у позицію знайденого підрядка. Атрибут "input" встановлюється у початковий рядок.
var rez = "1 плюс 2 плюс 3".match("\\d+","g");  // rez = [1], [2], [3]
  • Array match( TRegExp pat ); — Пошук у рядку за шаблоном "RegExp" pat. Повертає масив зі знайденим підрядком (0) та підвиразами (>1). Атрибут "index" масиву встановлюється у позицію знайденого підрядка. Атрибут "input" встановлюється у початковий рядок.
var rez = "1 плюс 2 плюс 3".match(new RegExp("\\d+","g"));  // rez = [1], [2], [3]
  • string slice( int beg, int end ); string substring( int beg, int end ); — Повернення підрядку вилученого з вихідного починаючи з позиції beg та до end (не включаючи), нумерація з нуля. Якщо значення початку або кінця негативне, то відлік ведеться з кінця рядку. Якщо кінець не вказано, то кінцем є кінець рядку. Наприклад, конструкція substring(-2) поверне останні два символи рядку.
  • Array split( string sep, int limit ); — Повернення масиву елементів рядку поділених sep з обмеженням кількості елементів limit.
  • Array split( RegExp pat, int limit ); — Повертає масив елементів рядку поділених шаблоном "RegExp" pat з обмеженням кількості елементів limit.
rez = "1,2, 3 , 4 ,5".split(new RegExp("\\s*,\\s*"));  // rez = [1], [2], [3], [4], [5]
  • string insert( int pos, string substr ); — Вставка в позицію pos поточного рядку підрядку substr.
  • string replace( int pos, int n, string str ); — Заміна підрядку з позиції pos та довжиною n у поточному рядку на рядок str.
rez = "Javascript".replace(4,3,"67");  // rez = "Java67ipt"
  • string replace( string substr, string str ); — Заміна всіх підрядків substr на рядок str.
rez = "123 321".replace("3","55");  // rez = "1255 5521"
  • string replace( RegExp pat, string str ); — Заміна підрядків за шаблоном pat на рядок str.
rez = "value = \"123\"".replace(new RegExp("\"([^\"]*)\"","g"),"``$1''"));  // rez = "value = ``123''"
  • real toReal(); — Перетворення поточного рядку у реальне число.
  • int toInt( int base = 0 ); — Перетворення поточного рядки в ціле число, у відповідності із основою base (от 2 до 36). Якщо основа дорівнює 0 тоді буде враховуватися префіксний запис для визначення основи (123-десяткове; 0123-вісімкове; 0x123-шістнадцяткове).
  • string parse( int pos, string sep = ".", int off = 0 ); — Виокремлення із вихідного рядку елементу pos для поділювача елементів sep від зміщення off. Результуюче зміщення поміщається назад до off.
  • string parseLine( int pos, int off = 0 ); — Виокремлення рядку з номером pos від зміщення off. Результуюче зміщення поміщається назад до off.
  • string parsePath( int pos, int off = 0 ); — Виділення із початкового шляху елементу pos від зміщення off. Результуюче зміщення поміщається назад до off.
  • string path2sep( string sep = "." ); — Перетворення шляху у поточному рядку у рядок з розділювачем sep.
  • string trim( string cfg = " \n\t\r" ); — Обрізка рядка з початку та кінцю для символів cfg.


1.1 Об'єкт Array

Особливістю масиву є те, що він працює з властивостями як з індексами та повне їх найменування не має сенсу, відтак доступний механізм звернення тільки заключенням індексу у квадратні дужки "arr[1]". Масив зберігає властивості у власному контейнері одномірного масиву. Цифрові властивості масиву використовуються для доступу безпосередньо до масиву, а символьні працюють як властивості об'єкту.

Масив надає спеціальну властивість "length" для отримання розміру масиву "var = arr.length;". Також масив надає наступні функції:

1.2 Об'єкт RegExp

Об'єкт роботи з регулярними виразами, засновано на бібліотеці PCRE. При глобальному пошуку встановлюється атрибут об'єкта "lastIndex", що дозволяє продовжити пошук при наступному виклику функції. У випадку невдалого пошуку атрибут "lastIndex" скидається у нуль.

У якості аргументів створення об'єкту передається рядок з текстом регулярного виразу та прапорці у вигляді рядка символів:

Властивості об'єкту:

Функції об'єкту:

1.3 Об'єкт XMLNodeObj

Функції:

0x01 — повне завантаження, з блоками тексту та коментарями у спеціальних вузлах;
0x02 — не видаляти пробіли на початку та кінці тексту тегу.
0x01 — переривати рядок перед відкриваючим тегом;
0x02 — переривати рядок після відкриваючого тегу;
0x04 — переривати рядок після закриваючого тегу;
0x08 — переривати рядок після тексту;
0x10 — переривати рядок після інструкції;
0x1E — переривати рядок після всіх;
0x20 — вставляти стандартний XML-заголовок;
0x40 — вставляти стандартний XHTML-заголовок;
0x80 — очищати сервісні теги: <??>, <!-- -->;
0x100 — опускати кодування назв тегів;
0x200 — опускати кодування назв атрибутів.

2 Система (SYS)

Функції об'єкту:

3 Будь який об'єкт (TCntrNode) дерева OpenSCADA (SYS.*)

Функції об'єкту:

4 Підсистема "Безпека" (SYS.Security)

Функції об'єкту підсистеми (SYS.Security):

user — користувач для перевірки доступу;
mode — режим доступу (4-R, 2-W, 1-X);
owner — власник ресурсу;
group — група ресурсу;
access — режим доступу до ресурсу (RWXRWXRWX — 0777).

Функції об'єкту користувача (SYS.Security["usr_User"]):

Функції об'єкту групи (SYS.Security["grp_Group"]):

5 Підсистема "БД" (SYS.BD)

Функції об'єкту БД (SYS.BD["TypeDB"]["DB"]):

Функції об'єкту Таблиця (SYS.BD["TypeDB"]["DB"]["Table"]):

6 Підсистема "Збір даних" (SYS.DAQ)

Функції об'єкту підсистеми (SYS.DAQ):

Функції об'єкту контролеру (SYS.DAQ["Modul"]["Controller"]):

Функції об'єкту параметру контролеру (SYS.DAQ["Modul"]["Controller"]["Parameter"]):

Функції об'єкту атрибута параметра контролера (SYS.DAQ["Modul"]["Controller"]["Parameter"]["Attribute"]):

Функції об'єкта бібліотеки шаблона (SYS.DAQ[tmplb_Lib"]) та шаблону (SYS.DAQ[tmplb_Lib"]["Tmpl"]) параметра контролеру:

6.1 Модуль DAQ.JavaLikeCalc

Об'єкт "Бібліотека функцій" (SYS.DAQ.JavaLikeCalc["lib_Lfunc"])

Об'єкт "Користувацька функція" (SYS.DAQ.JavaLikeCalc["lib_Lfunc"]["func"])

6.2 Модуль DAQ.LogicLev

Об'єкт "Параметр" [this]

6.3 Модуль DAQ.BlockCalc

Об'єкт "Блок" (SYS.DAQ.BlockCalc["cntr"]["blk_block"])

6.4 Модуль DAQ.ModBus

Об'єкт "Контролер" [this.cntr()]

Об'єкт "Параметр" [this]


7 Підсистема "Архіви" (SYS.Archive)

Функції об'єкту підсистеми:

Функції об'єкту архіватору повідомлень (SYS.Archive["mod_Modul"]["mess_Archivator"]):

Функції об'єкту архіватору значень (SYS.Archive["val_Modul"]["val_Archivator"]):

Функції об'єкту архіву (SYS.Archive["va_Archive"]):

8 Підсистема "Транспорти" (SYS.Transport)

Функції об'єкту вхідного транспорту (SYS.Transport["Modul"]["in_Transp"]):

Функції об'єкту вихідного транспорту (SYS.Transport["Modul"]["out_Transp"]):

9 Підсистема "Протоколи" (SYS.Protocols)

9.1 Модуль Protocol.HTTP

Саме цей об'єкт модуля "Protocol.HTTP" [SYS.Protocol.HTTP.pgCreator()]


10 Підсистема "Користувацькі інтерфейси" (SYS.UI)

10.1 Модуль UI.VCAEngine

Object "Session" ( this.ownerSess() )

Object "Widget" (this)

//New widget adding, based at the text primitive
nw = this.wdgAdd("nw", "New widget", "/wlb_originals/wdg_Text");
nw.attrSet("geomX", 50).attrSet("geomY", 50);
//Set link for eight trend to the parameter
this.linkSet("el8.name", "prm:/LogicLev/experiment/Pi", true);

Object "Widget" of the primitive "Document" (this)


11 Підсистема "Спеціальні" (SYS.Special)

11.1 Модуль Бібліотека системного API середовища користувацького програмування (Special.FLibSYS)

Об'єкт "Бібліотека функцій" (SYS.Special.FLibSYS)

Об'єкт "Користувацька функція" (SYS.Special.FLibSYS["funcID"])

11.2 Модуль Бібліотека стандартних математичних функцій (Special.FLibMath)

Об'єкт "Бібліотека функцій" (SYS.Special.FLibMath)

Об'єкт "Користувацька функція" (SYS.Special.FLibMath["funcID"])

11.3 Модуль Бібліотека функцій сумісності з SCADA Complex1 фірми ТОВ НІП "DIYA" (Special.FLibComplex1)

Об'єкт "Бібліотека функцій" (SYS.Special.FLibComplex1)

Об'єкт "Користувацька функція" (SYS.Special.FLibComplex1["funcID"])


At.png Link to DB API libraries ...