Export translations

Settings

Group
Language
Format	Export for off-line translation Export in native format

{{DISPLAYTITLE:Документация/API пользователя}}<languages/>
{{Info|
* '''Автор:''' [[User:RomanSavochenko|Роман Савоченко]]
* '''Изначально создано:''' в [http://wiki.oscada.org/HomePageEn/Doc/ProgrammManual старой Wiki] }}

До начала программирования в OpenSCADA Вы должны изучить структуру объектов программы (Объектная модель) из [[Special:MyLanguage/Documents/Program_manual|руководства по программе OpenSCADA]] и на рисунке 1.

Из этого документа Вы увидите, что можете, как пользователь, программировать следующие части OpenSCADA:
* [[Special:MyLanguage/Documents/DAQ#Virtual|Источники логического уровня подсистемы "Сбор данных"]].
* Транспортные протоколы, доступные для пользовательского программирования, такие как: [[Special:MyLanguage/Modules/UserProtocol|Пользовательский протокол]], [[Special:MyLanguage/Modules/ModBus|ModBus узлы типа "Данные"]], [[Special:MyLanguage/Modules/WebUser|Web-интерфейсы от пользователя]], ...
* [[Special:MyLanguage/Modules/VCAEngine|Среда Визуализации и Управления (СВУ)]] в процедурах виджетов.

API пользовательского программирования представляет собой дерево объектов OpenSCADA (Рис.1), каждый объект которого может представлять собственный перечень свойств и функций. Свойства и функции объектов могут использоваться пользователем в процедурах на языках пользовательского программирования OpenSCADA.

На данный момент OpenSCADA предоставляет только один язык текстового программирования — [[#JavaLikeCalc|JavaLikeCalc]], следовательно Вы также должны его изучить перед началом. Точкой входа для доступа к объектам OpenSCADA (Рис.1) из языка пользовательского программирования JavaLikeCalc является зарезервированное слово "SYS", корневого объекта OpenSCADA. Например, для доступа к функции исходящего транспорта нужно записать: '''SYS.Transport.Serial.out_ModBus.messIO(mess);'''.

API объектов, предоставляемых модулями, описывается в собственной документации модулей и тут предоставляются ссылки на неё.

== {{Anch|JavaLikeCalc|[[Special:MyLanguage/Modules/JavaLikeCalc|Пользовательский язык программирования JavaLikeCalc]]}} ==
{{#lst:Modules/JavaLikeCalc/ru|LANG}}

== Общесистемные пользовательские объекты ==
{{#lst:Modules/JavaLikeCalc/ru|OBJ}}

=== {{Anch|Array|Объект массива (Array)}} ===
Особенностью массива является то, что он работает со свойствами, как с индексами, и полное их именование бессмысленно, а значит доступен только механизм обращения заключением индекса в квадратные скобки "'''arr[1]'''". Массив хранит свойства в собственном контейнере одномерного массива. Цифровые свойства массива используются для доступа непосредственно к массиву, а символьные работают как свойства объекта.

Массив предоставляет специальное свойство "length", для получения размера массива "'''var = arr.length;'''". Также массив предоставляет следующие функции:
* ''string join( string sep = "," )'', ''string toString( string sep = "," )'', ''string valueOf( string sep = "," )'' — возвращает строку с элементами массива, разделёнными ''sep'' или символом ','.
* ''Array concat( Array arr );'' — добавляет к исходному массиву элементы массива ''arr''. Возвращает исходный массив с изменениями.
* ''int push( ElTp var, ... );'' — помещает элемент(ы) ''var'' в конец массива, как в стек. Возвращает новый размер массива.
* ''ElTp pop( );'' — удаляет последний элемент массива и возвращает его значения, как из стека.
* ''Array reverse( );'' — изменяет порядок расположения элементов массива. Возвращается исходный массив с изменениями.
* ''ElTp shift( );'' — сдвигает массив вверх, при этом первый элемент массива удаляется, а его значение возвращается.
* ''int unshift( ElTp var, ... );'' — задвигает элемент(ы) ''var'' в массив. Первый элемент в 0, второй в 1 и т.д.
* ''Array slice( int beg, int end );'' — возвращает фрагмент массива от ''beg'' к ''end'' (исключая). Если значение начала или конца отрицательно, то отсчёт ведётся с конца массива. Если конец не указан, то концом является конец массива.
* ''Array splice( int beg, int remN, ElTp val1, ElTp val2, ... );'' — вставляет, удаляет или заменяет элементы массива. Возвращает массив удалённых элементов. В первую очередь осуществляется удаление элементов с позиции ''beg'' и количеством ''remN'', а затем вставляются значения ''val1'' и т.д., начиная с позиции ''beg''.
* ''int indexOf( ElTp var, int start = 0 );'' — возвращает индекс массиву нужной переменной ''var'' в исходной последовательности, начиная с позиции ''start''. Если исходная позиция не указана то поиск начинается с начала. Если искомого значения не найдено то возвращается "-1".
* ''int lastIndexOf( ElTp var, int start = {end} );'' — возвращает индекс массива нужной переменной ''var'' в исходной последовательности, начиная с позиции ''start'' при поиске с конца. Если исходная позиция не указана то поиск начинается с конца. Если искомого значения не найдено то возвращается "-1".
* ''double sum( int beg, int end );'' — сумма значений части массива с позиции ''beg'' по ''end'', исключая.
* ''Array sort( );'' — сортирует элементы массива в лексикографическом порядке.

=== {{Anch|RegExp|Объект регулярного выражения (RegExp)}} ===
Объект работы с регулярными выражениями, основан на библиотеке PCRE. При глобальном поиске устанавливается атрибут объекта "lastIndex", что позволяет продолжить поиск при следующем вызове функции. В случае неудачного поиска атрибут "lastIndex" сбрасывается в ноль.

В качестве аргументов создания объекта передаётся строка с текстом регулярного выражения и флаги в виде строки символов:
* 'g' — режим глобального поиска;
* 'i' — режим регистронезависимого поиска;
* 'm' — режим многострочного поиска;
* 'u' — принудительное разрешение символов UTF-8, для других локалей;
* 'p' — тестирование выражения по правила обычного шаблона с ключевыми символами: '?', '*' и '\'.

Свойства объекта:
* ''source'' — исходный шаблон регулярного выражения, только чтение.
* ''global'' — признак глобального поиска, только чтение.
* ''ignoreCase'' — признак игнорирования регистра символов при поиске, только чтение.
* ''multiline'' — признак многострочного поиска, только чтение.
* ''UTF8'' — признак разрешения UTF-8 символов, только чтение.
* ''lastIndex'' — индекс символа за подстрокой последнего поиска, используется в глобальном режиме для продолжения сканирования, при следующем вызове.

Функции объекта:
<ul>
<li>''Array exec(string val);'' — вызывает поиск по строке ''val''. Возвращает найденную подстроку (0) и подвыражения (>0) в массиве. Устанавливает атрибут массива "index" в позицию найденной подстроки. Устанавливает атрибут массива "input" в значение исходной строки.
<syntaxhighlight lang="JavaScript">
var re = new RegExp("(\\d\\d)[-/](\\d\\d)[-/](\\d\\d(?:\\d\\d)?)","");
var rez = re.exec("12/30/1969");
var month = rez[1];
var day = rez[2];
var year = rez[3]; </syntaxhighlight></li>
<li>''bool test(string val);'' — возвращает "true" если подстрока найдена в ''val''.
<syntaxhighlight lang="JavaScript">
var re = new RegExp("(\\d\\d)[-/](\\d\\d)[-/](\\d\\d(?:\\d\\d)?)","");
var OK = re.test("12/30/1969"); </syntaxhighlight></li>
</ul>

=== XML node-tag object (XMLNodeObj) ===
Functions:
* ''string name( )'' — the name of the node, XML-tag.
* ''string text( bool full = false )'' — the text of the node, contents of the XML-tag. Set ''full'' for get the combined text of all included nodes.
* ''string attr( string id )'' — the value of the node attribute ''id''.
* ''XMLNodeObj setName( string vl )'' — sets of the node name to ''vl''. Returns the current node.
* ''XMLNodeObj setText( string vl )'' — sets of the node text to ''vl''. Returns the current node.
* ''XMLNodeObj setAttr( string id, string vl )'' — sets the attribute ''id'' to the value ''vl''. Returns the current node.
* ''XMLNodeObj clear( bool full = false )'' — clears the node for the childs, removes the text and attributes for ''full''.
* ''int childSize( )'' — quantity of the included nodes.
* ''XMLNodeObj childAdd( ElTp no = XMLNodeObj ); XMLNodeObj childAdd( string no )'' — addition of the object ''no'' as the included one. ''no'' may be the direct object-result of the function "SYS.XMLNode()", and the string with the name of a new tag. Returns the included node.
* ''XMLNodeObj childIns( int id, ElTp no = XMLNodeObj ); XMLNodeObj childIns( int id, string no )'' — insert of the object ''no'' as the included one to the position ''id''. ''no'' may be the direct object-result of the function "SYS.XMLNode()", and the string with the name of a new tag. Returns the embedded node.
* ''XMLNodeObj childDel( int id )'' — deletes the included node from the position ''id''. Returns current node.
* ''XMLNodeObj childGet( int id )'' — gets the included node in the position ''id''. Returns '''0''' at missing one.
* ''XMLNodeObj childGet( string name, int num = 0 )'' — gets the included node with the tag ''name'' and the position number ''num''. Returns '''0''' at missing one.
* ''XMLNodeObj parent( )'' — gets the parent node. Returns '''false''' at missing one.
* ''string load( string str, bool file = false, int flg = 0, string cp = "UTF-8" )'' — loads the XML from the string ''str'' or from the file with the path in ''str'' if the ''file'' equal "true", with the source encoding ''cp''. Returns a string with error in the format "'''{errCod}:{errText}'''", which is "0" for successful loading. Where ''flg'' — loading flags:
::0x01 — full loading, with texts and comments blocks into special nodes;
::0x02 — does not remove spaces from the begin and end of the tag text.
* ''string save( int flg = 0, string path = "", string cp = "UTF-8" )'' — saves the XML tree to the string or to the file ''path'' with the formatting flags ''flg'' and target encoding ''cp''. Returns the XML text or the error code. The following formatting options ''flg'' are provided:
::0x01 — end line before the opening tag;
::0x02 — end line after the opening tag;
::0x04 — end line after the closing tag;
::0x08 — end line after the text;
::0x10 — end line after the instruction;
::0x1E — end line after all ones;
::0x20 — inserts the standard XML-header;
::0x40 — inserts the standard XHTML-header;
::0x80 — cleans the service tags: <nowiki><??>, </nowiki>;
::0x100 — does not encode the tag name;
::0x200 — does not encode the attribute;
::0x400 — shield the binary symbols [\x0-\x8\xB-\xC\x0E-\x1F] and wrong UTF-8.
* ''XMLNodeObj getElementBy( string val, string attr = "id" )'' — gets an element from the tree by the attribute ''attr'' in value ''val''.
* ''TArrayObj<XMLNodeObj> getElementsBy( string tag, string attrVal = "", string attr = "id", int limit = 0, int from = 0 )'' — gets an elements array from the tree by the ''tag'' (empty for all) and attribute ''attr'' in value ''attrVal'' (empty for pass), also starting the tag number ''from'' and limiting them number in ''limit'' (zero for no limit).

== {{Anch|SYS|Program-system (SYS)}} ==
Object functions:
<ul>
<li>''{string|int} system( string cmd, bool noPipe = false );'' — calls the console commands ''cmd'' of the OS returning the result by the channel. If ''noPipe'' is set then the callback code is returned and program can be started in the background ("sleep 5 &"). The function provides OpenSCADA with a wide range of capabilities by calling any system programs, utilities, and scripts, as well as by providing them with access to a huge amount of system data. For example the command "ls-l" returns the detailed content of the working directory.</li>
<li>''int fileSize( string file );'' — returns the ''file'' size.</li>
<li>''string fileRead( string file, int off = 0, int sz = -1 );'' — returns a string of part of the ''file'' for the offset ''off'' and the block size ''sz''.</li>
<li>''int fileWrite( string file, string str, bool append = false );'' — writes the string ''str'' to the ''file'', removes presented one, at ''append''. Returns the wrote bytes count.</li>
<li>''int fileRemove( string file );'' — removes the ''file''. Returns the removing result.</li>
<li>''int message( string cat, int level, string mess );'' — forms of the system message ''mess'' with the category ''cat'', level ''level'' (-7...7). The negative value of the level forms the alarms.</li>
<li>''int messDebug( string cat, string mess ); int messInfo( string cat, string mess ); int messNote( string cat, string mess ); int messWarning( string cat, string mess ); int messErr( string cat, string mess ); int messCrit( string cat, string mess ); int messAlert( string cat, string mess ); int messEmerg( string cat, string mess );'' — forms of the system message ''mess'' with the category ''cat'' and the appropriate level by the name.</li>
<li>''XMLNodeObj XMLNode( string name = "" );'' — creates of the XML node object with the ''name''.</li>
<li>''string cntrReq( XMLNodeObj req, string stat = "" );'' — sends a request ''req'' in XML view to the [[Special:MyLanguage/Documents/API#CntrNode|Control Interface]] of the program. Returns a string with error in the format "'''{errCod}:{errText}'''", which is "0" for successful. A request is generally written in the form '''<get path="/OPath/%2felem" />''' and with additional attributes specific to the particular request. If the station ''stat'' is specified into the request then the request will be sent to this external station. The address for the attribute "path" you can obtain into the OpenSCADA configurator, that is into the status line where the address appear at the mouse cursor point to a field of configuration or information. Some examples of common requests, more examples in [[Special:MyLanguage/Documents/API#CntrNode|description the Control Interface]] and [[Special:MyLanguage/Libs/Service_procedures#releaseTests|releaseTests()]]:
<ul>
 <li>Reading a value of the element (the user name "test"):
<syntaxhighlight lang="JavaScript">
req = SYS.XMLNode("get").setAttr("path","/sub_Security/usr_test/%2fprm%2fDESCR");
SYS.cntrReq(req);
idSt = req.text(); </syntaxhighlight></li>
 <li>Writing a value to the element (the user name "test"):
<syntaxhighlight lang="JavaScript">
req = SYS.XMLNode("set").setAttr("path","/sub_Security/usr_test/%2fprm%2fDESCR").setText("New test user name");
SYS.cntrReq(req); </syntaxhighlight></li>
 <li>Adding a new node (the user "test"):
<syntaxhighlight lang="JavaScript">
req = SYS.XMLNode("add").setAttr("path","/sub_Security/%2fbr%2fusr_").setText("test");
SYS.cntrReq(req); </syntaxhighlight></li>
 <li>Deleting a node (the user "test"):
<syntaxhighlight lang="JavaScript">
req = SYS.XMLNode("del").setAttr("path","/sub_Security/%2fbr%2fusr_").setText("test");
SYS.cntrReq(req); </syntaxhighlight></li>
 <li>Saving the node changes to DB (the user "test"):
<syntaxhighlight lang="JavaScript">
req = SYS.XMLNode("save").setAttr("path","/sub_Security/usr_test/%2fobj");
SYS.cntrReq(req); </syntaxhighlight></li>
 <li>Loading the node from DB (the user "test"):
<syntaxhighlight lang="JavaScript">
req = SYS.XMLNode("load").setAttr("path","/sub_Security/usr_test/%2fobj");
SYS.cntrReq(req); </syntaxhighlight></li>
</ul></li>
<li>''string lang(string full);'' — returns the system language in two symbols and the full language in ''full''.</li>
<li>''int sleep( real tm, int ntm = 0 );'' — puts the execution thread to sleep on the ''tm'' seconds (precised up to nanoseconds) and ''ntm'' nanoseconds. The sleeping time you can set up to STD_INTERF_TM (5 seconds).</li>
<li>''int time( int usec );'' — returns the absolute time in seconds from the epoch of 1/1/1970 and the microseconds part into ''usec'' if specified.</li>
<li>''int utime( ); int mtime( );'' — returns the absolute time in microseconds and milliseconds from the epoch of 1/1/1970.</li>
<li>''int {localtime|gmtime}( int fullsec, int sec, int min, int hour, int mday, int month, int year, int wday, int yday, int isdst );'' — returns the full date in seconds (sec), minutes (min), hours (hour), days of the month (mday), months (month), years (year), days in the week (wday), days in the year (yday) and sign of the summer time (isdst), based on the absolute time in seconds ''fullsec'' from the epoch 1/1/1970. ''gmtime'' returns time in GMT(UTC).</li>
<li>''int {mktime|timegm}( int sec, int min, int hour, int mday, int month, int year, int wday, int yday, int isdst );'' — forms the time since Epoch 1/1/1970 from separated seconds, minutes, hours, days, month etc. The values for separated time items can be set out from this typical range, which allows you to use this function during checking, and as a result, units of time will be fixed and rotated in the normal range. ''timegm'' runs in time at GMT(UTC).</li>
<li>''string {strftime|strftimegm}( int sec, string form = "%Y-%m-%d %H:%M:%S" );'' — converts an absolute time ''sec'' to the string of the desired format ''form''. Record of the format corresponds to the POSIX-function ''strftime''. ''strftimegm'' returns time into GMT(UTC).</li>
<li>''int {strptime|strptimegm}( string str, string form = "%Y-%m-%d %H:%M:%S" );'' — returns the time in seconds from the epoch of 1/1/1970, based on the string record of time ''str'', in accordance with the specified template ''form''. For example the template "%Y-%m-%d %H:%M:%S" corresponds with the time "2006-08-08 11:21:55". Description of the template format can be obtained from the documentation on POSIX-function ''strptime''. ''strptimegm'' works into GMT(UTC) time.</li>
<li>''{{Anch|CRON|<nowiki>int cron( string cronreq, int base = 0 );</nowiki>}}'' — returns the time, planned in the format of the standard CRON, ''cronreq'', beginning from the basic time ''base'' or current, if the basic is not specified. CRON is the standard form "* * * * *".
; Where items by the order:
* minutes (0-59);
* hours (0-23);
* days (1-31);
* month (1-12);
* week day (0[Sunday]-6).
; Where the item variants:
* "*" — any value;
* "1,2,3" — list of the allowed values;
* "1-5" — raw range of the allowed values;
* "*/2" — divider to the all allowed values range.
; Examples:
* "* * * * *" — each minute;
* "10 23 * * *" — only at 23 hour and 10 minute for any day and month;
* "*/2 * * * *" — for minutes: 0,2,4,...,56,58;
* "* 2-4 * * *" — for any minutes in hours from 2 to 4(include).
</li>
<li>''string strFromCharCode( int char1, int char2, int char3, ... );'' — creates a string from symbol codes ''char1'', ''char2'' ... ''charN''.</li>
<li>''string strFromCharUTF([string type = "UTF-8",] int char1, int char2, int char3, ...);'' — creates a string from UTF symbols ''char1'', ''char2'' ... ''charN''. These types of the symbol are supported: UTF-8, UTF-16, UTF-16LE, UTF-16BE, UTF-32, UTF-32LE, UTF-32BE.</li>
<li>''string strCodeConv( string src, string fromCP, string toCP );'' — transcodes the text ''src'' from the encoding ''fromCP'' to ''toCP''. If the encoding is omitted (empty string), it is used the internal one.</li>
<li>''string strEncode( string src, string tp = "Bin", string opt = "" );'' — encodes the string ''src'' by the rule ''tp'' and the option ''opt''. Allowed rules:
:"PathEl" — symbols '''[/%]''' to "%2f" and "%25", respectively;
:"HttpURL" — symbols '''[ \t%]''' and "> 0x80" to "%20", "%09", "%25" and etc.;
:"HTML" — symbols of the HTML-entities '''[><"&']''' to "&amp;gt;", "&amp;lt;", "&amp;quot;" and etc.;
:"JavaScript" — symbol '\n' shielding to "\\n";
:"SQL" — shielding of the symbols '''['"`\]''' by appending '\' or doubling of the listed symbols into ''opt'';
:"Custom" — symbols into ''opt'' to the view "%NN";
:"Base64" — same Base 64 binary encoding, into ''opt'' sets a line termination symbol(s) after 57 symbols;
:"FormatPrint" — symbol '%' to "%%";
:"OscdID" — almost all symbols like '''[ /\&(]''' to '_';
:"Bin" — ASCII bytes list ("XX XX XX XX ...") to the binary represent;
:"Reverse" — reversion the sequence;
:"ToLower" — symbols to the lower register;
:"Limit" — limiting the string to the length into ''opt'', counting UTF-8 variable length;
:"ShieldSymb" — shielding symbols from ''opt'' (by default ['"`]) with the slash symbol "\" like to '\n', '\r', ..., '\0NNN';
:"ShieldBin" — shielding all binary symbols [\x0-\x8\xB-\xC\x0E-\x1F] with the slash symbol "\".
</li>
<li>''string strDecode( string src, string tp = "Bin", string opt = "" );'' — decodes the string ''src'' by the rule ''tp'' and the option ''opt''. Allowed rules:
:"PathEl", "HttpURL", "Custom" — symbols like "%NN" to the binary represent;
:"Base64" — same from Base 64;
:"Bin" — the binary string to ASCII bytes ("XX XX XX XX .. A.b.c.."), ''opt'' points to the separator or "<text>" for enable the offset to the left and the text part to the right;
:"ShieldSymb" — shielded symbols like to '\n', '\r', ..., '\0NNN', '\xNN' to the binary represent.
</li></ul>

== {{Anch|TCntrNode|Any object (TCntrNode) of OpenSCADA objects tree (SYS.*)}} ==
Object functions:
* ''TArrayObj nodeList( string grp = "", string path = "" );'' — Get child nodes full identifiers list for group ''grp'' and node from path ''path''. If ''grp'' empty then return nodes for all groups. The full identifier is "{grp}{nID}".
* ''TCntrNodeObj nodeAt( string path, string sep="" );'' — Attach to node ''path'' into OpenSCADA objects tree. If a separator set into ''sep'' then path process as separated string. For missed and invalid nodes the function will return "false" when a correct node in it conversion to BOOLEAN will return "true".
* ''TCntrNodeObj nodePrev( );'' — Get previous, parent, node.
* ''string nodePath( string sep = "", bool from_root = true );'' — Getting the path of the current node in the object tree OpenSCADA. One separator character is specified in ''sep'' to get the path through the separator, for example, "DAQ.ModBus.PLC1.P1.var", otherwise "/DAQ/ModBus/PLC1/P1/var". ''from_root'' indicates a need to form a path from the root, and without the Station ID.
* ''int messSys( int level, string mess )'' — Formation of the system message ''mess'' with the ''level'' with the node path as a category and with the human readable path before the message.

== Подсистема "Безопасность" (SYS.Security) ==
Функции объекта подсистемы (SYS.Security):
* ''int access( string user, int mode, string owner, string group, int access )'' — проверяет доступ пользователя ''user'' к ресурсу, который принадлежит ''owner'' и ''group'' с доступом ''access'' и для режима ''mode'':
::''user'' — пользователь проверки доступа;
::''mode'' — режим доступа (4-R, 2-W, 1-X);
::''owner'' — владелец ресурса;
::''group'' — группа ресурса;
::''access'' — режим доступа к ресурсу (RWXRWXRWX — 0777).

Функции объекта "Пользователь" (SYS.Security["usr_{User}"]):
* ''ElTp cfg( string nm )'' — получает значение конфигурационного поля ''nm'' объекта.
* ''bool cfgSet( string nm, ElTp val )'' [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля ''nm'' объекта в значение ''val''.
* ''bool auth( string pass )'' — возвращает TRUE в случае удачной аутентификации пользователя по ''pass''.
* ''Array groups( )'' — возвращает перечень групп пользователя.

Функции объекта "Группа пользователей" (SYS.Security["grp_{Group}"]):
* ''ElTp cfg( string nm )'' — получает значение конфигурационного поля ''nm'' объекта.
* ''bool cfgSet( string nm, ElTp val )'' [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля ''nm'' объекта в значение ''val''.
* ''bool user( string nm )'' — проверяет присутствие пользователя ''nm'' в данной группе.

== {{Anch|SYS.BD|Подсистема "БД" (SYS.BD)}} ==
Функции объекта "БД" (SYS.BD["TypeDB"]["DB"]):
<ul>
<li>''ElTp cfg(string nm)'' — получает значение конфигурационного поля ''nm'' объекта.</li>
<li>''bool cfgSet(string nm, ElTp val)'' [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля ''nm'' объекта в значение ''val''.</li>
<li>''Array SQLReq( string req, bool tr = EVAL );'' — осуществляет SQL-запрос ''req'' к БД, внутри (''tr''=true), вне (''tr''=false) или безразлично (''tr''=EVAL) к транзакции. Возвращает массив строк таблицы результата с полями по индексам и по именам колонок. В случае ошибки её значение помещается в свойство "err" результата.
<syntaxhighlight lang="JavaScript">
DBTbl = SYS.BD.MySQL.GenDB.SQLReq("SELECT * from DB;");
if(DBTbl.err.length) SYS.messInfo("TEST DB","Error: "+DBTbl.err);
else for(var iRw = 0; iRw < DBTbl.length; iRw++) {
 var rec = "";
 for(var iFld = 0; iFld < DBTbl[iRw].length; iFld++) rec += DBTbl[iRw][iFld] + "\t";
 SYS.messInfo("TEST DB", "Row "+iRw+": "+rec);
 //Get column value by the name
 if(iRw) SYS.messInfo("TEST DB", "Row "+iRw+": 'NAME'"+DBTbl[iRw]["NAME"]);
} </syntaxhighlight></li>
</ul>

Функции объекта "Таблица" (SYS.BD["TypeDB"]["DB"]["Table"]):
<ul>
<li>''XMLNodeObj fieldStruct( );'' — получает структуру таблицы в виде XML узла "field" с дочерними узлами-колонками '''<RowId type="real" len="10.2" key="1" def="Default value">{Value}</RowId>''', где:<ul>
 <li>{RowId} — идентификатор колонки;</li>
 <li>{Value} — значение колонки;</li>
 <li>type — тип значения колонки: ''str'' — строка, ''int'' — целое, ''real'' — вещественное и ''bool'' — логическое;</li>
 <li>len — размер значения колонки, в знаках;</li>
 <li>key — признак того, что колонка является ключом, и поиск осуществляется по его значению;</li>
 <li>def — значение колонки по умолчанию.</li>
</ul></li>
<li>''string fieldSeek( int row, XMLNodeObj fld );'' — запрашивает поле ''row'' таблицы. Если поле получено то возвращается "1" иначе "0". В случае ошибки возвращается "0:Error".</li>
<li>''string fieldGet( XMLNodeObj fld );'' — запрашивает значение поля. В случае ошибки возвращается "0:Error".
<syntaxhighlight lang="JavaScript">
req = SYS.XMLNode("field");
req.childAdd("user").setAttr("type","str").setAttr("key","1").setText("root");
req.childAdd("id").setAttr("type","str").setAttr("key","1").setText("/Lang2CodeBase");
req.childAdd("val").setAttr("type","str");
SYS.BD.MySQL.GenDB.SYS.fieldGet(req);
SYS.messDebug("TEST DB","Value: "+req.childGet(2).text()); </syntaxhighlight></li>
<li>''string fieldSet( XMLNodeObj fld );'' — устанавливает поле. В случае ошибки возвращается "0:Error".</li>
<li>''string fieldDel(XMLNodeObj fld);'' — удаляет поле. В случае ошибки возвращается "0:Error".</li>
</ul>

== {{Anch|SYS.DAQ|Подсистема "Сбор данных" (SYS.DAQ)}} ==
Функции объекта подсистемы (SYS.DAQ):
<ul>
<li>''TCntrNodeObj daqAt(string path, string sep = "", waitForAttr = true)'' — подключается к DAQ узлу (объект контролера, параметр, атрибут) по пути ''path'' или разделённой строки по разделителю ''sep'', от DAQ-подсистемы. Проверять на атрибут в конце пути, по ''waitForAttr''.</li>
<li>''bool funcCall( string progLang, TVarObj args, string prog, string fixId = "", string err = "" );'' — исполняет текст функции ''prog'' с аргументами в объекте ''args'' на языке программирования ''progLang'' и с идентификатором фиксации ''fixId'' (автоматически если пустой). Возвращает "true" при корректном вызове, иначе "false" и устанавливается "err". Фиксированная функция отличается от автоматической тем, что она не удаляется после исполнения, а используется повторно по адресу в ''fixId'', заменяющего оригинальный идентификатор при первом вызове. Для переформирования функции нужно изменить программу или очистить ''fixId'' в её оригинальный идентификатор.
<syntaxhighlight lang="JavaScript">
var args = new Object();
args.y = 0;
args.x = 123;
SYS.DAQ.funcCall("JavaLikeCalc.JavaScript",args,"y=2*x;");
SYS.messDebug("TEST Calc","TEST Calc rezult: "+args.y); </syntaxhighlight></li>
<li>''string funcSnthHgl(string progLang);'' — запрос правил подсветки синтаксиса языка программы ''progLang'' в [[Special:MyLanguage/Documents/API#SnthHgl|XML-теге ''SnthHgl'']].</li>
</ul>

Функции объекта контроллера (SYS.DAQ["Modul"]["Controller"]):
* ''ElTp cfg( string nm )'' — получает значение конфигурационного поля ''nm'' объекта.
* ''bool cfgSet( string nm, ElTp val )'' [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля ''nm'' объекта в значение ''val''.
* ''string name( )'' — имя объекта контроллера.
* ''string descr( )'' — описание объекта и контроллера.
* ''string status( )'' — статус контроллера.
* ''bool messSet( string mess, int lev, string type2Code = "OP", string prm = "", string cat = "")'' — устанавливает сообщение источника данных ''mess'' с уровнем ''lev'', для параметра ''prm'' ('''{PrmId}'''), дополнительной информацией категории ''cat'' и кодом типа ''type2Code''. Эта функция [[Special:MyLanguage/Documents/Program_manual#ArchMess|формирует сообщения]] с унифицированной категорией транспортирования через источник данных '''{type2Code}{ModId}:{CntrId}[.{PrmId}][:{cat}]''', где: 
** ''type2Code'' — двухсимвольный код типа сообщения, по умолчанию означает действие оператора "OP";
** ''CntrId'' — идентификатор объекта контроллера;
** ''PrmId'' — идентификатор параметра, из аргумента ''prm'';
** ''CntrNm'' — название объекта контроллера;
** ''cat'' — дополнительная информация категории которую определено для типа ''type2Code''.
* ''bool alarmSet( string mess, int lev = -5, string prm = "", bool force = false )'' — устанавливает/снимает нарушение ''mess'' с уровнем ''lev'' (отрицательный для установки иначе снятие), для параметра ''prm'' ('''{PrmId}\n{PrmNm}'''). Очистка нарушений, как и установка, работает в режиме переключателя, что предусматривает пропуск сообщений очистки в буфер сообщений, и саму очистку, только при наличии соответствующего нарушения, что может быть отключено установкой ''force''. Функция формирует нарушение с категорией '''al{ModId}:{CntrId}[.{PrmId}]''' и текстом '''{CntrNm} > {PrmNm}: {MessText}''', где:
** ''ModId'' — идентификатор модуля;
** ''CntrId'' — идентификатор объекта контроллера;
** ''PrmId'' — идентификатор параметра, из аргумента ''prm'';
** ''CntrNm'' — название объекта контроллера;
** ''PrmNm'' — название параметра, из аргумента ''prm'';
** ''MessText'' — текст сообщения.
* ''bool enable( bool newSt = EVAL )'' — получает состояние "Включен" или изменяет его назначением атрибута ''newSt''.
* ''bool start( bool newSt = EVAL )'' — получает состояние "Имполняется" или изменяет его назначением атрибута ''newSt''.

Функции объекта параметра контроллера (SYS.DAQ["Modul"]["Controller"]["Parameter"]):
* ''ElTp cfg( string nm )'' — получает значение конфигурационного поля ''nm'' объекта.
* ''bool cfgSet( string nm, ElTp val )'' [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля ''nm'' объекта в значение ''val''.
* ''TCntrNodeObj cntr( )'' — возвращает объект контроллера этого параметра, независимо от вложенности.
* ''bool messSet( string mess, int lev, string type2Code = "OP", string cat = "")'' — устанавливает сообщение источника данных ''mess'' с уровнем ''lev'', для параметра.
* ''bool alarmSet( string mess, int lev = -5, bool force = false )'' — устанавливает/снимает нарушение ''mess'' с уровнем ''lev'' (отрицательный для установки иначе снятие) для этого параметра. Очистка нарушений, как и установка, работает в режиме переключателя, что предусматривает пропуск сообщений очистки в буфер сообщений, и саму очистку, только при наличии соответствующего нарушения, что может быть отключено установкой ''force''.

Функции объекта атрибута параметра контроллера (SYS.DAQ["Modul"]["Controller"]["Parameter"]["Attribute"]):
* ''ElTp get( int tm = 0, int utm = 0, bool sys = false )'' — запрашивает значение атрибута на время ''tm.utm'' и признаком системного доступа ''sys''. Атрибуты времени ''tm.utm'' являются также выходами, соответственно реальное время полученного значения помещается в них, если это переменные.
* ''bool set( ElTp val, int tm = 0, int utm = 0, bool sys = false )'' — записывает значение ''val'' в атрибут с меткой времени ''tm:utm'' и признаком системного доступа ''sys''.
* ''TCntrNodeObj arch( )'' — получает объект архива, связанный с этим атрибутом. В случае отсутствия связанного архива возвращается "false".
* ''string descr( )'' — описание атрибута.
* ''int time( int utm )'' — время последнего значения в секундах и микросекундах в ''utm'', если указан и является переменной.
* ''int len( )'' — длина поля в БД.
* ''int dec( )'' — разрешение вещественного числа поля в БД.
* ''int flg( )'' — флаги поля.
* ''string def( )'' — значение по умолчанию.
* ''string values( )'' — список допустимых значений или диапазон.
* ''string selNames( )'' — список имён допустимых значений.
* ''string reserve( )'' — резервное свойство значения.

Функции объекта библиотеки шаблона (SYS.DAQ[tmplb_Lib"]) и шаблона (SYS.DAQ[tmplb_Lib"]["Tmpl"]) параметра контроллера:
* ''ElTp cfg( string nm )'' — получает значение конфигурационного поля ''nm'' объекта.
* ''bool cfgSet( string nm, ElTp val )'' [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля ''nm'' объекта в значение ''val''.

=== Модуль [[Special:MyLanguage/Modules/JavaLikeCalc|DAQ.JavaLikeCalc]] ===
{{#lst:Modules/JavaLikeCalc/ru|API}}
=== Модуль [[Special:MyLanguage/Modules/LogicLev|DAQ.LogicLev]] ===
{{#lst:Modules/LogicLev/ru|API}}
=== Модуль [[Special:MyLanguage/Modules/BlockCalc|DAQ.BlockCalc]] ===
{{#lst:Modules/BlockCalc/ru|API}}
=== Модуль [[Special:MyLanguage/Modules/ModBus|DAQ.ModBus]] ===
{{#lst:Modules/ModBus/ru|API}}
=== Модуль [[Special:MyLanguage/Modules/Siemens|DAQ.Siemens]] ===
{{#lst:Modules/Siemens/ru|API}}
=== Модуль [[Special:MyLanguage/Modules/OPC_UA|DAQ.OPC_UA]] ===
{{#lst:Modules/OPC_UA/ru|API}}

== {{Anch|SYS.Archive|Подсистема "Архивы-История" (SYS.Archive)}} ==
Функции объекта подсистемы:
* ''Array messGet( int btm, int etm, string cat = "", int lev = 0, string arch = "", int upTm = 0 );'' — запрашивает сообщения программы или нарушения (lev < 0) за время от ''btm'' до ''etm'' для категории ''cat'', уровня ''lev'' (-7...7) и архиваторов ''arch'' (разделены символом ';'; "" — буфер и архиваторы; "<buffer>" — буфер; "{ArhMod}.{Arh}" — конкретный архиватор модуля). ''upTm'' устанавливает ограничение продолжительности операции в указанное время; отрицательное значение используется как относительное время; менее чем STD_INTERF_TM (5). Возвращается время останова чтения (атрибут "tm" массива) и массив объектов сообщений/нарушений со свойствами:
** ''tm'' — время сообщения, секунды;
** ''utm'' — время сообщения, микросекунды;
** ''categ'' — категория сообщения;
** ''level'' — уровень сообщения;
** ''mess'' — текст сообщения.
* ''bool messPut( int tm, int utm, string cat, int lev, string mess, string arch = "" );'' — записывает сообщение ''mess'' с категорией ''cat'', уровнем ''lev'' (-7...7) и временем ''tm.utm'' в архиваторы ''arch'' (разделены символом ';') и/или список нарушений.

Функции объекта архиватора сообщений (SYS.Archive["mod_Modul"]["mess_Archivator"]):
* ''ElTp cfg( string nm )'' — получает значение конфигурационного поля ''nm'' объекта.
* ''bool cfgSet( string nm, ElTp val )'' [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля ''nm'' объекта в значение ''val''.
* ''bool status( )'' — статус архиватора "Исполнение".
* ''int end( )'' — время окончания данных архиватора.
* ''int begin( )'' — время начала данных архиватора.

Функции объекта архиватора значений (SYS.Archive["val_Modul"]["val_Archivator"]):
* ''ElTp cfg( string nm )'' — получает значение конфигурационного поля ''nm'' объекта.
* ''bool cfgSet( string nm, ElTp val )'' [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля ''nm'' объекта в значение ''val''.
* ''bool status( )'' — статус архиватора "Исполнение".

{{Anch|SYS.Archive|Функции объекта архива (SYS.Archive["va_Archive"]):}}
* ''ElTp cfg( string nm )'' — получает значение конфигурационного поля ''nm'' объекта.
* ''bool cfgSet( string nm, ElTp val )'' [доступ к соответствующей подсистеме] — устанавливает конфигурационное поля ''nm'' объекта в значение ''val''.
* ''bool status( )'' — статус архиватора "Исполнение".
* ''int end( string arch = "" )'' — время конца данных архива для архиватора ''arch'', в микросекундах.
* ''int begin( string arch = "" )'' — время начала данных архива для архиватора ''arch'', в микросекундах.
* ''int period( string arch = "" )'' — период данных архива для архиватора ''arch'', в микросекундах.
* ''TArrayObj archivatorList( )'' — список архиваторов, использующих данный архив как источник.
* ''VarType getVal( int tm, bool up_ord = false, string arch = "" )'' — получает значение из архива на время ''tm'', подтяжкой к верху ''up_ord'' и архиватора ''arch'':
** ''tm'' — время запрашиваемого значения, в микросекундах, установить в 0 для "end()"; этот атрибут также является выходом, соответственно реальное время полученного значения помещается сюда, если это переменная; 
** ''up_ord'' — подтягивать время запрашиваемого значения к верху сетки;
** ''arch'' — архиватор запроса, установить в пустую строку для проверки всех архиваторов, установить в "<buffer>" для обработки только буфера.
* ''bool setVal( int tm, VarType vl, string arch = "" )'' [доступ к подсистеме Архивы-История] — устанавливает значение ''vl'' в архив на время ''tm'' и архиватор ''arch'':
** ''tm'' — время устанавливаемого значения, в микросекундах;
** ''vl'' — значение;
** ''arch'' — архиватор установки, установить в пустую строку для всех архиваторов, установить в "<buffer>" для обработки только буфера.
* ''Array getVals( int begTm, int endTm, int period, string arch = "" )'' — получает архив/историю значений от ''begTm'' и по ''endTm'' для архиватора ''arch'':
** ''begTm'' — время начала запрошенного диапазона данных, в микросекундах, будет изменено в реальное начало данных;
** ''endTm'' — время окончания запрошенного диапазона данных, в микросекундах;
** ''period'' — период данных, в микросекундах, должно быть обязательно определено и будет использовано максимальное значение для этого архива, будет изменено в периодичность реальных данных;
** ''arch'' — архиватор запроса, установить в пустую строку для проверки всех архиваторов, установить в "<buffer>" для обработки только буфера.
* ''bool setVals( Array buf, int tm, int period, string arch = "" )'' [доступ к подсистеме Архивы-История] — устанавливает значение архиву/истории ''buf'' в архив от времени начала ''tm'', для периода значений ''period'' и архиватора ''arch''.
** ''buf'' — массив значений к установке;
** ''tm'' — время начала устанавливаемого диапазона данных, в микросекундах;
** ''period'' — период устанавливаемых данных, в микросекундах, должно быть обязательно определено и будет использовано максимальное значение для этого архива, будет изменено в периодичность реальных данных;
** ''arch'' — архиватор запроса, установить в пустую строку для проверки всех архиваторов, установить в "<buffer>" для обработки только буфера.

== {{Anch|SYSTransport|Subsystem "Transports" (SYS.Transport)}} ==
Functions of the subsystem object:
* ''TCntrNodeObj outAt( string addr );'' — common-unified output transport connection at the address ''addr'' in the forms:
:: "'''{TrModule}.[out_]{TrID}[:{TrAddr}]'''" — typical output with automatic creation ''TrID'' at it missing and allowing ''TrAddr'';
:: "'''{TrModule}.in_{TrID}:{RemConId}'''" — initiative input with the connection identifier in ''RemConId''.
:* ''TrModule'' — transport module, as is [[Special:MyLanguage/Modules/Sockets|Sockets]], [[Special:MyLanguage/Modules/SSL|SSL]], [[Special:MyLanguage/Modules/Serial|Serial]];
:* ''TrID'' — transport identifier;
:* ''TrAddr'' — transport specific address;
:* ''RemConId'' — remote initiative connection ID.

Functions of the input transport object (SYS.Transport["Modul"]["in_Transp"]):
* ''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.
* ''bool cfgSet( string nm, ElTp val )'' [access to the appropriate subsystem] — sets the configuration field ''nm'' of the object to the value ''val''.
* ''string status()'' — string status of the transport.
* ''string addr( string vl = "" )'' — address of the transport, sets the non-empty value ''vl''.
* ''string writeTo(string sender, string mess)'' — sends the message ''mess'' to the sender ''sender'', as a reply.
* ''TArrayObj associateTrsList()'' — associated output transports list to that input one.
* ''TCntrNodeObj associateTr( string id )'' — getting the associated transport at that connection ''id''.
* ''ElTp conPrm( string id, ElTp val = EVAL, string cfg = "" )'' — common handling the connection time parameter ''id'' with setting to the value ''val'' at presence; request for configuration parameter of the connection time with registration at the first time from the configuration ''cfg'' in the form "{SRC}\n{NAME}\n{HELP}".
* ''bool setConPrm( string id, ElTp val )'' — setting the connection time parameter ''id'' to the value ''val'', only for compatibility.

Functions of the output transport object (SYS.Transport["Modul"]["out_Transp"]):
<ul>
<li>''bool isNetwork( )'' — the sign — "The transport is network one", what is specified by the timeouts in seconds.</li>
<li>''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.</li>
<li>''bool cfgSet( string nm, ElTp val )'' [access to the appropriate subsystem] — sets the configuration field ''nm'' of the object to the value ''val''.</li>
<li>''string status()'' — string status of the transport.</li>
<li>''bool start( bool vl = EVAL, int tm = 0 )'' — returns the transport status "Running", starts/stops it by ''vl'' (if it is not EVAL). For starting you can set the specific timeout ''tm''.</li>
<li>''string addr( string vl = "" )'' — address of the transport, sets the non-empty value ''vl''.</li>
<li>''string timings( string vl = "", isDef = true )'' — timings of the transport, sets the non-empty value ''vl'' and as default one for ''isDef''.</li>
<li>''int attempts( int vl = EVAL )'' — attempts of the transport connection, sets the non-EVAL value ''vl''.</li>
<li>''ElTp conPrm( string id, ElTp val = EVAL, string cfg = "" )'' — common handling the connection time parameter ''id'' with setting to the value ''val'' at presence; request for configuration parameter of the connection time with registration at the first time from the configuration ''cfg'' in the form "{SRC}\n{NAME}\n{HELP}".</li>
<li>''bool setConPrm( string id, ElTp val )'' — setting the connection time parameter ''id'' to the value ''val'', only for compatibility.</li>
<li>''string messIO( string mess, real timeOut = 0, int inBufLen = -1 );'' — sends the message ''mess'' via the transport with the waiting time of the response ''timeOut'' (in seconds) and reads an response (Buffer) in ''inBufLen'' byte. In the case of a zero timeout, this time is taken from the settings of the output transport. The ''timeOut'' in negative (< -1e-3) disables the transport request/respond mode and allows for independent reading/writing to a buffer IO, with the reading timeout ''timeOut'' in absolute. For negative ''inBufLen'' the buffer size sets to STR_BUF_LEN(10000) and "0" disables the reading at all. 
[[File:at.png]] If your transport means getting data in parts for a request then for several devices on single bus-transport, use the function into single thread but there is not a way to lock the transport into the user API. Single thread that is any object of controller of DAQ and [[Special:MyLanguage/Modules/UserProtocol|the module "User protocol"]] locks the transport internally before self user procedures execution.
<syntaxhighlight lang="JavaScript">
rez = SYS.Transport.Serial.out_ttyUSB0.messIO(SYS.strFromCharCode(0x4B,0x00,0x37,0x40),0.2);
//Wait for all the message tail by timeout and empty result
while(rez.length && (trez=SYS.Transport.Serial.out_ttyUSB0.messIO("")).length) rez += trez; </syntaxhighlight></li>
<li>''string messIO( XMLNodeObj req, string prt );'' — sends the request ''req'' to the protocol ''prt'' to perform a communication session through the transport and in assistance of the protocol. Returns a string with error in the format "'''{errCod}:{errText}'''" which empty for successful request.
<syntaxhighlight lang="JavaScript">
req = SYS.XMLNode("TCP");
req.setAttr("id","test").setAttr("reqTm",500).setAttr("node",1).setAttr("reqTry",2).setText(SYS.strFromCharCode(0x03,0x00,0x00,0x00,0x05));
SYS.Transport.Sockets.out_testModBus.messIO(req,"ModBus");
test = Special.FLibSYS.strDec4Bin(req.text()); </syntaxhighlight></li>
</ul>

== Подсистема "Протоколы" (SYS.Protocols) ==
=== Модуль [[Special:MyLanguage/Modules/HTTP|Protocol.HTTP]] ===
{{#lst:Modules/HTTP/ru|API}}

== {{Anch|SYSUI|Subsystem "User interfaces" (SYS.UI)}} ==
Functions of the subsystem object:
* ''string mimeGet(string fnm);'' — obtaining the MIME type at the file name ''fnm''.

=== Модуль [[Special:MyLanguage/Modules/QTStarter|QTStarter]] ===
{{#lst:Modules/QTStarter/ru|API}}
=== Модуль [[Special:MyLanguage/Modules/VCAEngine|UI.VCAEngine]] ===
{{#lst:Sub-projects/VCA/ru|API}}

== Подсистема "Специальные" (SYS.Special) ==
=== Модуль [[Special:MyLanguage/Modules/FLibSYS|Библиотека системного API среды пользовательского программирования (Special.FLibSYS)]] ===
{{#lst:Modules/FLibSYS/ru|API}}
=== Модуль [[Special:MyLanguage/Modules/FLibMath|Библиотека стандартных математических функций (Special.FLibMath)]] ===
{{#lst:Modules/FLibMath/ru|API}}
=== Модуль [[Special:MyLanguage/Modules/FLibComplex1|Библиотека функций совместимости со SCADA Complex1 фирмы ООО НИП "DIYA" (Special.FLibComplex1)]] ===
{{#lst:Modules/FLibComplex1/ru|API}}

== Библиотеки функций пользователя  ==
На данное время OpenSCADA имеет библиотеки функций пользователя, написанные с использованием этого API пользователя. Некоторые из них разработаны для использования исключительно из этого API. Все библиотеки пользователя представлены в следующей таблице:
{{:Libs/ru}}

== Ссылки ==
* [[:File:Oscada UserOM_uk.odg|Диаграмма: Пользовательская объектная модель ядра OpenSCADA.]]

Export translations

Views

Navigation menu

OpenSCADA

OpenSCADA Wiki

Search

Tools

MediaWiki

Personal tools