View source for Documents/User API

<languages/>
<translate>
<!--T:1-->
{{Info|
* '''Author:''' {{Author|[[User:RomanSavochenko|Roman Savochenko]]|Maxim Lysenko (2012) — the page initial translation}}
* '''Initially created:''' in [http://wiki.oscada.org/HomePageEn/Doc/ProgrammManual the old Wiki] }}

<!--T:2-->
Before programming in OpenSCADA, you must examine the object structure of the program (Object Model) in [[Special:MyLanguage/Documents/Program_manual|OpenSCADA Program Manual]] and in Figure 1.

<!--T:36-->
[[File:oscada_UserOM.png|center|frame|Fig. 1. User object model of the core OpenSCADA.]]
<!--[[File:oscada_UserOM.png|center|thumb|800px|Fig. 1. User object model of the core OpenSCADA.]]-->

<!--T:38-->
From this document you will see that you can program next parts of OpenSCADA as the user:
* [[Special:MyLanguage/Documents/DAQ#Virtual|Logical level sources of the subsystem "DAQ"]].
* Transport protocols allowed for user programming that is: [[Special:MyLanguage/Modules/UserProtocol|User protocol]], [[Special:MyLanguage/Modules/ModBus|ModBus nodes of the type "Data"]], [[Special:MyLanguage/Modules/WebUser|Web-interfaces from the user]], ...
* [[Special:MyLanguage/Modules/VCAEngine|Visual Control Area (VCA)]] in procedures of the widgets.

<!--T:3-->
User programming API is the tree of the OpenSCADA objects (Fig.1), every object of which can provide own list of properties and functions. Properties and functions of the objects can be used by the user in procedures on the languages of the user programming of OpenSCADA.

<!--T:4-->
Currently OpenSCADA provides only one language of the text programming — [[#JavaLikeCalc|JavaLikeCalc]] then you must learn it also before the starting! The entry point for access to the objects of OpenSCADA (Fig.1) from the user programming language JavaLikeCalc is the reserved word "SYS" of the root OpenSCADA object. For example, to access the function of output transport you should write: '''SYS.Transport.Serial.out_ModBus.messIO(mess);'''.

<!--T:5-->
API of the objects provided by the modules is described in the own documentation of the modules and here links to their are provided.

== {{Anch|JavaLikeCalc|[[Special:MyLanguage/Modules/JavaLikeCalc|The user programming language JavaLikeCalc]]}} == <!--T:40-->
{{#lst:Modules/JavaLikeCalc|LANG}}

== System-wide user objects == <!--T:6-->
{{#lst:Modules/JavaLikeCalc|OBJ}}

=== {{Anch|Array|Array object}} === <!--T:7-->
Peculiarity of the array is that it works with the properties like with the indexes, and complete their naming if senseless, and hence the mechanism of addressing is available only by the conclusion of the index in square brackets "'''arr[1]'''". Array stores the properties in its own container of one-dimensional array. Digital properties of the array are used to access directly to the array, and the character ones work as the object properties.

<!--T:8-->
Array provides the special property "length" to get the array size "'''var = arr.length;'''". Also array provides the following functions:
* ''string join( string sep = "," )'', ''string toString( string sep = "," )'', ''string valueOf( string sep = "," )'' — returns the string with the array elements separated by ''sep'' or the character ','.
* ''Array concat( Array arr );'' — adds to the initial array the elements of the ''arr'' array. Returns the initial array with changes.
* ''int push( ElTp var, ... );'' — places the element(s) ''var'' to the end of the array, as to the stack. Returns the new array size.
* ''ElTp pop( );'' — deletes of the last element of the array and returns of its value, as from the stack.
* ''Array reverse( );'' — changes the order of the elements of the array. Returns the initial array with the changes.
* ''ElTp shift( );'' — shifts of the array to the top. The first element is removed and its value is returned.
* ''int unshift( ElTp var, ... );'' — shifts element(s) ''var'' to the array. The first element to the 0, second to the 1 and so on.
* ''Array slice( int beg, int end );'' — returns an array fragment from ''beg'' to ''end'' (exclude). If the value of beginning or end is negative, then the count is made from the end of the array. If the end is not specified, then the end is the end of the array.
* ''Array splice( int beg, int remN, ElTp val1, ElTp val2, ... );'' — inserts, deletes or replaces the elements of the array. Returns the removed elements array. Firstly it is made the removing of elements from the position ''beg'' and in the quantity of ''remN'', and then the values ''val1'' are inserted and so on, beginning from the position ''beg''.
* ''int indexOf( ElTp var, int start = 0 );'' — returns the array index of the required variable ''var'' in the original row from the position ''start''. If the initial position is not specified then the search starts from the beginning. If the search variable is not found then "-1" is returned.
* ''int lastIndexOf( ElTp var, int start = {end} );'' — returns the array index of the required variable ''var'' in the original row from the position ''start'' when searching from the end. If the initial position is not specified then the search begins from the end. If the search variable is not found then "-1" is returned.
* ''double sum(int beg, int end);'' — sum of the array values part from the position ''beg'' to ''end'', excluding.
* ''Array sort( );'' — sorts array elements in the lexicographical order.

=== {{Anch|RegExp|RegExp object}} === <!--T:9-->
Object of work with the regular expressions, based on the library PCRE. In the global search sets object attribute "lastIndex", which allows you to continue the searching at the next function call. In the case of an unsuccessful search the attribute "lastIndex" resets to zero.

<!--T:10-->
As arguments for creating the object, a string with regular expression text and a flags box in the form of a character string is passed:
* 'g' — global match mode;
* 'i' — case insensitive match mode;
* 'm' — multi-line match mode;
* 'u' — compulsion for UTF-8 characters resolution, for other locales;
* 'p' — testing the expression by the usual template rule with the key characters: '?', '*' and '\'.

<!--T:11-->
Object properties:
* ''source'' — original pattern of the regular expression, read-only.
* ''global'' — flag of the global matching, read-only.
* ''ignoreCase'' — flag of disabling of the case sensitivity, read-only.
* ''multiline'' — flag of the multiline searching, read-only.
* ''UTF8'' — flag of using UTF-8 characters, read-only.
* ''lastIndex'' — index of a character of the substring from the last search. Used in the global mode to continue the match, at next call.

<!--T:12-->
Object functions:
<ul>
<li>''Array exec( string val );'' — calls match for string ''val''. Returns found sub-string (0) and sub-expressions (>0) in the array. Sets attribute "index" of the array to the matched substring position. Sets the attribute "input" of the array to the source string.
<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 );'' — returns "true" for the match sub-string in ''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) === <!--T:13-->
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 the current node.
* ''XMLNodeObj childGet( int id )'' — gets the included node in the position ''id''.
* ''XMLNodeObj childGet( string name, int num = 0 )'' — gets the included node with the tag ''name'' and the position number ''num''.
* ''XMLNodeObj parent( )'' — gets the parent node.
* ''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''. 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" )'' — gets an elements array from the tree by the ''tag'' (empty for all) and attribute ''attr'' in value ''attrVal'' (empty for pass).

== {{Anch|SYS|Program-system (SYS)}} == <!--T:14-->
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 of [[Special:MyLanguage/Documents/API#CntrNode|the control interface]] request to the program-system via XML. The usual request is written as '''<get path="/OPath/%2felem"/>'''. If the station ''stat'' is indicated into the request then the request will be send to this external station. The address into the attribute "path" you can obtain into an 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 queries, more examples in [[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>''int cron( string cronreq, int base = 0 );'' — 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.</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 opt1 = "" );'' — encodes the string ''src'' by the rule ''tp'' and option ''opt1''. 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 ''opt1'';
:"Custom" — symbols into ''opt1'' to the view "%NN";
:"Base64" — same Base 64 binary encoding, into ''opt1'' 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;
:"ShieldSimb" — shielded symbols like '\a', '\b', ..., '\0NNN', '\xNN' to the binary represent;
:"ToLower" — symbols to the lower register;
:"Limit" — limiting the string to the length into ''opt1'', counting UTF-8 variable length;
:"ShieldBin" — shield the binary symbols [\x0-\x8\xB-\xC\x0E-\x1F].
</li>
<li>''string strDecode( string src, string tp = "Bin", string opt1 = "" );'' — decodes the string ''src'' by the rule ''tp'' and the option ''opt1''. 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.."), ''opt1'' points to the separator or "<text>" for enable the offset to the left and the text part to the right.
</li></ul>

== {{Anch|TCntrNode|Any object (TCntrNode) of OpenSCADA objects tree (SYS.*)}} == <!--T:15-->
Object functions:
* ''TArrayObj nodeList( string grp = "", string path = "" );'' — Get child nodes identifiers list for group ''grp'' and node from path ''path''. If ''grp'' empty then return nodes for all groups.
* ''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.

== Subsystem "Security" (SYS.Security) == <!--T:16-->
Functions of the subsystem object (SYS.Security):
* ''int access( string user, int mode, string owner, string group, int access )'' — checks for access of the ''user'' to resource which owned by the ''owner'' and ''group'' and for the ''access'' and ''mode'':
::''user'' — user of the access checking;
::''mode'' — access mode (4-R, 2-W, 1-X);
::''owner'' — owner of the resource;
::''group'' — group of the resource;
::''access'' — access mode of the resource (RWXRWXRWX — 0777).

<!--T:17-->
Functions of the object "User" (SYS.Security["usr_{User}"]):
* ''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.
* ''bool cfgSet( string nm, ElTp val )'' [<span style='color:red'>access to the appropriate subsystem</span>] — sets the configuration field ''nm'' of the object to the value ''val''.
* ''bool auth( string pass )'' — returns TRUE at successful authentication the user for ''pass''.
* ''Array groups( )'' — returns the groups list of the user.

<!--T:18-->
Functions of the object "Users group" (SYS.Security["grp_{Group}"]):
* ''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.
* ''bool cfgSet( string nm, ElTp val )'' [<span style='color:red'>access to the appropriate subsystem</span>] — sets the configuration field ''nm'' of the object to the value ''val''.
* ''bool user( string nm )'' — checks for the user ''nm'' presence into the group.

== {{Anch|SYS.BD|Subsystem "DB" (SYS.BD)}} == <!--T:19-->
Functions of the database object (SYS.BD["TypeDB"]["DB"]):
<ul>
<li>''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.</li>
<li>''bool cfgSet( string nm, ElTp val )'' [<span style='color:red'>access to the appropriate subsystem</span>] — sets the configuration field ''nm'' of the object to the value ''val''.</li>
<li>''Array SQLReq( string req, bool tr = EVAL );'' — performs the SQL-request ''req'' to the DB, inside (''tr''=true), outside (''tr''=false) or no matter (''tr''=EVAL) to the transaction. Returns an array of rows of the result table with the fields both per indexes and column names. At an error the result property "err" sets to the error value.
<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>

<!--T:20-->
Functions of the table object (SYS.BD["TypeDB"]["DB"]["Table"]):
<ul>
<li>''XMLNodeObj fieldStruct( );'' — gets the table structure in XML-node "field" with the child node-columns "'''<RowId type="real" len="10.2" key="1" def="Default value">{Value}</RowId>'''", where:<ul>
<li>{RowId} — column identifier;</li>
<li>{Value} — column value;</li>
<li>type — value type of the column: ''str'' — string, ''int'' — integer, ''real'' — real and ''bool'' — boolean;</li>
<li>len — value length of the column, in chars;</li>
<li>key — a sign that the column is the key, and the search is carried out according to its meaning;</li>
<li>def — default value of the column.</li>
</ul></li>
<li>''string fieldSeek( int row, XMLNodeObj fld );'' — seeks the field ''row'' of the table. For success returned "1" else "0". In case of error, returns "0: Error".</li>
<li>''string fieldGet( XMLNodeObj fld );'' — requests the field value. In case of error, returns "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 );'' — sets the field. In case of error, returns "0: Error".</li>
<li>''string fieldDel( XMLNodeObj fld );'' — removes the field. In case of error, returns "0: Error".</li>
</ul>

== {{Anch|SYS.DAQ|Subsystem "DAQ" (SYS.DAQ)}} == <!--T:21-->
Functions of the subsystem object (SYS.DAQ):
<ul>
<li>''TCntrNodeObj daqAt(string path, string sep = "", waitForAttr = true)'' — attaches to a DAQ node (controller object, parameter, attribute) in the ''path'' or the separated string by the separator ''sep'', from the DAQ-subsystem. Check for an attribute in the path last element, at ''waitForAttr''.</li>
<li>''bool funcCall(string progLang, TVarObj args, string prog, string fixId = "", string err = "");'' — executes the function text ''prog'' with the arguments ''args'' on the program language ''progLang'' and with the function fixing identifier ''fixId'' (automatic if it is empty). Returns "true" when it is executed correctly or "false" and set ''err''. The fixed function differ from the automatic one by it does not remove after execution and uses repeatedly by an address into ''fixId'', which replaces that original identifier in first call. To recreate the function, you must change the program or clear the ''fixId'' in its original id.
<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);'' — requesting the program language ''progLang'' syntax highlight rules in [[Special:MyLanguage/Documents/API#SnthHgl|the XML-tag ''SnthHgl'']].</li>
</ul>

<!--T:22-->
Functions of the controller object (SYS.DAQ["Modul"]["Controller"]):
* ''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.
* ''bool cfgSet( string nm, ElTp val )'' [<span style='color:red'>access to the appropriate subsystem</span>] — sets the configuration field ''nm'' of the object to the value ''val''.
* ''string name( )'' — name of the controller object.
* ''string descr( )'' — description of the controller object and controller.
* ''string status( )'' — status of the controller.
* ''bool messSet( string mess, int lev, string type2Code = "OP", string prm = "", string cat = "")'' — sets of the DAQ-sourced message ''mess'' with the level ''lev'', for the parameter ''prm'' ('''{PrmId}'''), additional category information ''cat'' and the type code ''type2Code''. This function [[Special:MyLanguage/Documents/Program_manual#ArchMess|forms the messages]] with the unified DAQ-transparency category '''{type2Code}{ModId}:{CntrId}[.{PrmId}][:{cat}]''', where:
** ''type2Code'' — the message type two-symbol code, by default means the operator actions "OP";
** ''ModId'' — identifier of the module;
** ''CntrId'' — identifier of the controller object;
** ''PrmId'' — parameter identifier, from the argument ''prm'';
** ''cat'' — additional category information which specific for the type ''type2Code''.
* ''bool alarmSet( string mess, int lev = -5, string prm = "", bool force = false )'' — sets/removes of the violation ''mess'' with the level ''lev'' (negative to set otherwise to remove), for the parameter ''prm'' ('''{PrmId}\n{PrmNm}'''). The alarms clearance, as the setting also, works in the toggling mode, so means of passing the clearance messages to the message buffer, and the same clearance, only at the according violations presence, what may be disabled setting ''force''. The function forms the alarms with the category '''al{ModId}:{CntrId}[.{PrmId}]''' and the text '''{CntrNm} > {PrmNm}: {MessText}''', where:
** ''ModId'' — identifier of the module;
** ''CntrId'' — identifier of the controller object;
** ''PrmId'' — parameter identifier, from the argument ''prm'';
** ''CntrNm'' — name of the controller object;
** ''PrmNm'' — parameter name, from the argument ''prm'';
** ''MessText'' — message text.
* ''bool enable( bool newSt = EVAL )'' — gets the status "Enabled" or changes it by the argument ''newSt'' assign.
* ''bool start( bool newSt = EVAL )'' — gets the status "Running" or changes it by the argument ''newSt'' assign.

<!--T:23-->
Functions of the parameter object of the controller (SYS.DAQ["Modul"]["Controller"]["Parameter"]):
* ''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.
* ''bool cfgSet( string nm, ElTp val )'' [<span style='color:red'>access to the appropriate subsystem</span>] — sets the configuration field ''nm'' of the object to the value ''val''.
* ''TCntrNodeObj cntr( )'' — returns the controller object regardless of the nesting parameters.
* ''bool messSet( string mess, int lev, string type2Code = "OP", string cat = "")'' — sets of the DAQ-sourced message ''mess'' with the level ''lev'', for the parameter.
* ''bool alarmSet( string mess, int lev = -5, bool force = false )'' — sets/removes of the violation ''mess'' with the level ''lev'' (negative to set otherwise to remove) for the parameter. The alarms clearance, as the setting also, works in the toggling mode, so means of passing the clearance messages to the message buffer, and the same clearance, only at the according violations presence, what may be disabled setting ''force''.

<!--T:24-->
Functions of the attribute object of the parameter of the controller (SYS.DAQ["Modul"]["Controller"]["Parameter"]["Attribute"]):
* ''ElTp get( int tm = 0, int utm = 0, bool sys = false );'' — gets the attribute value at the time ''tm.utm'' and system access flag ''sys''. The time attributes ''tm.utm'' is outputs also then real time of the gotten value also places here if their are variables.
* ''bool set( ElTp val, int tm = 0, int utm = 0, bool sys = false );'' — writes the value ''val'' to the attribute with the time label ''tm.utm'' and system access flag ''sys''.
* ''TCntrNodeObj arch( );'' — gets the archive associated with this attribute. Returns "false" in the case of absence the associated archive.
* ''string descr( );'' — description of the attribute.
* ''int time( int utm );'' — time of the last value of the attribute in seconds and microseconds into ''utm'', if it is pointed and is a variable.
* ''int len( );'' — length of the field in DB.
* ''int dec( );'' — float resolution of the field in DB.
* ''int flg( );'' — flags of the field.
* ''string def( );'' — default value.
* ''string values( );'' — allowed values list or range.
* ''string selNames( );'' — names list of the allowed values.
* ''string reserve( );'' — reserve string property of the value.

<!--T:25-->
Functions of object of templates library (SYS.DAQ[tmplb_Lib"]) and template (SYS.DAQ[tmplb_Lib"]["Tmpl"]) of controller's parameter:
* ''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.
* ''bool cfgSet( string nm, ElTp val )'' [<span style='color:red'>access to the appropriate subsystem</span>] — sets the configuration field ''nm'' of the object to the value ''val''.

=== Module [[Special:MyLanguage/Modules/JavaLikeCalc|DAQ.JavaLikeCalc]] === <!--T:26-->
{{#lst:Modules/JavaLikeCalc|API}}
=== Module [[Special:MyLanguage/Modules/LogicLev|DAQ.LogicLev]] ===
{{#lst:Modules/LogicLev|API}}
=== Module [[Special:MyLanguage/Modules/BlockCalc|DAQ.BlockCalc]] ===
{{#lst:Modules/BlockCalc|API}}
=== Module [[Special:MyLanguage/Modules/ModBus|DAQ.ModBus]] ===
{{#lst:Modules/ModBus|API}}
=== Module [[Special:MyLanguage/Modules/Siemens|DAQ.Siemens]] ===
{{#lst:Modules/Siemens|API}}
=== Module [[Special:MyLanguage/Modules/OPC_UA|DAQ.OPC_UA]] ===
{{#lst:Modules/OPC_UA|API}}

== {{Anch|SYS.Archive|Subsystem "Archives-History" (SYS.Archive)}} == <!--T:27-->
Functions of the subsystem object:
* ''Array messGet( int btm, int etm, string cat = "", int lev = 0, string arch = "", int upTm = 0 );'' — requests of the program messages or alarms for the time from ''btm'' to ''etm'' for the category ''cat'', level ''lev'' (-7...7) and archivers ''arch'' (separated by the symbol ';'; "" — buffer and archivers; "<buffer>" — buffer; "{ArhMod}.{Arh}" — concrete archiver of the module). ''upTm'' sets the operation continuance limit to time; a negative value used as relative time; less to STD_INTERF_TM (5). Returns time of stopping of the reading (attribute "tm" of the array) and an array of the message objects with the preset attributes:
** ''tm'' — time of the message, seconds;
** ''utm'' — time of the message, microseconds;
** ''categ'' — category of the message;
** ''level'' — level of the message;
** ''mess'' — text of the message.
* ''bool messPut( int tm, int utm, string cat, int lev, string mess, string arch = "" );'' — writes the message ''mess'' with the category ''cat'', level ''lev'' (-7...7) and time ''tm.utm'' to the archivers ''arch'' (separated by the symbol ';') or/and the alarms list.

<!--T:28-->
Functions of object's archiver of messages (SYS.Archive["mod_Modul"]["mess_Archivator"]):
* ''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.
* ''bool cfgSet( string nm, ElTp val )'' [<span style='color:red'>access to the appropriate subsystem</span>] — sets the configuration field ''nm'' of the object to the value ''val''.
* ''bool status( )'' — status "Running" of the archiver.
* ''int end( )'' — end time of data of the archiver.
* ''int begin( )'' — begin time of data of the archiver.

<!--T:29-->
Functions of object's archiver of values (SYS.Archive["val_Modul"]["val_Archivator"]):
* ''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.
* ''bool cfgSet( string nm, ElTp val )'' [<span style='color:red'>access to the appropriate subsystem</span>] — sets the configuration field ''nm'' of the object to the value ''val''.
* ''bool status( )'' — status "Running" of the archiver.

<!--T:30-->
{{Anch|SYS.Archive|Functions of object's archive (SYS.Archive["va_Archive"]):}}
* ''ElTp cfg( string nm )'' — gets the value of the configuration field ''nm'' of the object.
* ''bool cfgSet( string nm, ElTp val )'' [<span style='color:red'>access to the appropriate subsystem</span>] — sets the configuration field ''nm'' of the object to the value ''val''.
* ''bool status( )'' — status "Running" of the archive.
* ''int end( string arch = "" )'' — end time of data of the archive for the archiver ''arch'', in microseconds.
* ''int begin( string arch = "" )'' — begin time of data of the archive for the archiver ''arch'', in microseconds.
* ''int period( string arch = "" )'' — period of data of the archive for the archiver ''arch'', in microseconds.
* ''TArrayObj archivatorList( )'' — list of archivers that use this archive as a source.
* ''VarType getVal( int tm, bool up_ord = false, string arch = "" )'' — gets a value from the archive for the time ''tm'', tightening up ''up_ord'' and archiver ''arch'':
** ''tm'' — time of the requested value, in microseconds, set to 0 for "end()"; this attribute is also an output, so the real time of the received value is placed here if it is a variable;
** ''up_ord'' — tighten the time of the requested value to the top of the grid;
** ''arch'' — request archiver, set in an empty line to check all archivers, set to "<buffer>" to handle only the buffer.
* ''bool setVal( int tm, VarType vl, string arch = "" )'' [<span style='color:red'>access to the Archive-History subsystem</span>] — sets the value ''vl'' to the archive for the time ''tm'' and the archiver ''arch'':
** ''tm'' — time of the set value, in microseconds;
** ''vl'' — value;
** ''arch'' — archiver of the set request, set in an empty line for all archivers, set to "<buffer>" to handle only the buffer.
* ''Array getVals( int begTm, int endTm, int period, string arch = "" )'' — gets for the archive/history values from ''begTm'' and up to ''endTm'' for the archiver ''arch'':
** ''begTm'' — begin time of the requesting data range, in microseconds, will be changed to the real data begin;
** ''endTm'' — end time of the requesting data range, in microseconds;
** ''period'' — period of the data, in microseconds, must be necessarily specified and will be used the maximum one from the archive, will be changed to the real data period;
** ''arch'' — requesting archiver, set to empty to try for the buffer and all archivers, set to "<buffer>" to process only the buffer.
* ''bool setVals( Array buf, int tm, int period, string arch = "" )'' [<span style='color:red'>access to the Archive-History subsystem</span>] — sets for the archive/history values ''buf'' to the archive from the begin time ''tm'', the values period ''period'' and the archiver ''arch''.
** ''buf'' — array of the values to set;
** ''tm'' — begin time of the setting data range, in microseconds;
** ''period'' — period of the setting data, in microseconds, must be necessarily specified and will be used the maximum one from the archive, will be changed to the real data period;
** ''arch'' — setting archiver, set to empty to set for the buffer and all archivers, set to "<buffer>" to set only the buffer.

== {{Anch|SYSTransport|Subsystem "Transports" (SYS.Transport)}} == <!--T:31-->
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.

<!--T:41-->
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 )'' [<span style='color:red'>access to the appropriate subsystem</span>] — 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''.

<!--T:32-->
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 )'' [<span style='color:red'>access to the appropriate subsystem</span>] — 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 nm )'' — getting the connection parameter ''nm''.</li>
<li>''bool setConPrm( string nm, ElTp val )'' — setting the connection parameter ''nm'' to the ''val''.</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.<br/>
[[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((trez=SYS.Transport.Serial.out_ttyUSB0.messIO("")).length) rez += trez; </syntaxhighlight></li>
<li>''string messIO( XMLNodeObj req, string prt );'' — sends the requests ''req'' to the protocol ''prt'' to perform a communication session through the transport and in assistance of the protocol.
<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>

== Subsystem "Protocols" (SYS.Protocols) == <!--T:33-->
=== Module [[Special:MyLanguage/Modules/HTTP|Protocol.HTTP]] ===
{{#lst:Modules/HTTP|API}}

== {{Anch|SYSUI|Subsystem "User interfaces" (SYS.UI)}} == <!--T:34-->
=== Module [[Special:MyLanguage/Modules/QTStarter|QTStarter]] ===
{{#lst:Modules/QTStarter|API}}
=== Module [[Special:MyLanguage/Modules/VCAEngine|UI.VCAEngine]] ===
{{#lst:Sub-projects/VCA|API}}

== "Special" subsystem (SYS.Special) == <!--T:35-->
=== Module [[Special:MyLanguage/Modules/FLibSYS|Library of the system API of the user programming area (Special.FLibSYS)]] ===
{{#lst:Modules/FLibSYS|API}}
=== Module [[Special:MyLanguage/Modules/FLibMath|Library of standard mathematical functions (Special.FLibMath)]] ===
{{#lst:Modules/FLibMath|API}}
=== Module [[Special:MyLanguage/Modules/FLibComplex1|Library of functions of compatibility with SCADA Complex1 of the firm DIYA Ltd (Special.FLibComplex1)]] ===
{{#lst:Modules/FLibComplex1|API}}

== Libraries of the user functions  == <!--T:39-->
Currently, OpenSCADA has libraries of the user functions written using this API user. Some of them are designed for exclusive use with this API. All user libraries are presented in the following table: 
{{:Libs}}

== Links == <!--T:37-->
* [[:File:Oscada UserOM.odg|Diagram: User object model of the core OpenSCADA.]]
</translate>