OpenSCADAWiki: Home Page En/Doc/Programm Manual/part5 ...

5. System-wide API of user programming.

User programming API is the tree of OpenSCADA objects, every object of which can provide own list of properties and functions. Properties and functions of objects can be used by the user in procedures on the languages of user programming of OpenSCADA. The entry point for access to the objects of system OpenSCADA from user programming language JavaLikeCalc is the reserved word "SYS" of the root OpenSCADA object. For example, to access the function of outgoing transport you should write: SYS.Transport.Serial.out_ModBus.messIO(mess);.

API of the objects provided by the modules is described in the own documentation of the module.

5.1. System-wide user objects.

Abstract object is an associative container of properties and functions. Properties can contain the data of four basic types and other objects. Access to the properties of an object is usually made by recording the names of properties through a point to the object <obj.prop>, as well as by entering the property name in brackets <obj["prop"]>. It is obvious that the first mechanism is static, while the second lets you to specify the name of the property through a variable. The basic definition of the object does not contain functions. Copying of an object actually makes reference to the original object. When you delete an object the reduce of the reference counter is made, and when the reference counter is equal to the zero object is removed physically.

Different components can redefine the basic object with special properties and functions. The standard extension of the object is an array "Array".

Array object

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 characters work as object properties.

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( ); — Deleting of the last element of the array and return of its value, as from the stack.
• Array reverse( ); — Changing the order of the elements of the array. Returns the initial array with changes.
• ElTp shift( ); — The shift of the array to the top. The first element is removed and its value is returned.
• int unshift( ElTp var, ... ); — Shift 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>.
• Array sort( ); — Sort array elements in lexicographical order.

RegExp object

Object for work with regular expressions, based on the library PCRE. In the global search set object attribute "lastIndex", which allows you to continue searching for the next function call. In the case of an unsuccessful search for the attribute "lastIndex" reset to zero.

As arguments passed to create the object put string with the text of regular expression and flags as a string of characters:

• 'g' — global match mode;
• 'i' — case insensitive match mode;
• 'm' — multi-line match mode;
• 'p' — expressions test by typical template with key symbols: '?', '*' and '\'.

Object's properties:

• source — Original regular expression pattern, read-only.
• global — Global match flag, read-only.
• ignoreCase — Ignore case flag, read-only.
• multiline — Multiline search, read-only.
• lastIndex — Index of a character of the substring from the last search. Used in global mode for match continue, at next call.

Object's functions:

• Array exec(string val); — Call match for string <val>. Return found substring (0) and subexpressions (>0) in array. Set attribute "index" of the array to matched substring position. Set attribute "input" of array to source string.
  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];

  
  
• bool test(string val); — Return "true" for match substring in <val>.
  var re = new RegExp("(\\d\\d)[-/](\\d\\d)[-/](\\d\\d(?:\\d\\d)?)","");
var OK = re.test("12/30/1969");

XMLNodeObj object

Functions:

• string name( ) — The name of the node, XML-tag.
• string text( ) — The text of the node, contents of the XML-tag.
• string attr( string id ) — The value of the node's attribute <id>.
• XMLNodeObj setName( string vl ) — Setting of the node's name to <vl>. Returns the current node.
• XMLNodeObj setText( string vl ) — Setting of the node's text to <vl>. Returns the current node.
• XMLNodeObj setAttr( string id, string vl ) — Setting the attribute <id> to the value <vl>. Returns the current node.
• int childSize( ) — Quantity of the embedded nodes.
• XMLNodeObj childAdd( ElTp no = XMLNodeObj ); XMLNodeObj childAdd(string no) — Addition of the object <no> as the embedded one. <no> may be the direct object-result of the function SYS.XMLNode(), and the string with the name of the new tag. Returns the embedded node.
• XMLNodeObj childIns( int id, ElTp no = XMLNodeObj ); XMLNodeObj childIns(int id, string no) — Insert of the object <no> as the embedded one to the position <id>. <no> may be the direct object-result of the function SYS.XMLNode(), and the string with the name of the new tag. Returns the embedded node.
• XMLNodeObj childDel( int id ) — Deleting the embedded node from the position <id>. Returns the current node.
• XMLNodeObj childGet( int id ) — Getting the embedded node in the position <id>.
• XMLNodeObj parent() — Get parent node.
• string load( string str, bool file = false, bool full = false, string cp = "UTF-8" ) — Loading the XML from the string <str> or from the file with the path in <str> if the <file> "true", with source encoding <cp>. <full> — for full loading, with texts and comments blocks into special nodes.
• string save( int opt = 0, string path = "", string cp = "UTF-8" ) — Saving the XML tree to the string or to the file <path> with the formatting parameter <opt> and target encoding <cp>. Returns the XML text or the error code. The following formatting options <opt> are provided:
  • 0x01 — interrupt the string before the opening tag;
  • 0x02 — interrupt the string after the opening tag;
  • 0x04 — interrupt the string after a closing tag;
  • 0x08 — interrupt the string after the text;
  • 0x10 — interrupt the string after the instruction;
  • 0x1E — interrupt the string after all;
  • 0x20 — insert standard XML-header;
  • 0x40 — insert standard XHTML-header.
• XMLNodeObj getElementBy( string val, string attr = "id" ) — get element from the tree by attribute <attr> value <val>.

5.2. System (SYS)

Object functions:

• string system( string cmd, bool noPipe = false); — calls the console commands <cmd> of OS returning the result by the channel. If <noPipe> is set the return code is returned the the execution of the programs in the background ("sleep 5 &") is possible. The function offers great opportunities to the OpenSCADA user by calling any system software, utilities and scripts, as well as by way of access to the huge volume of system data. For example the command "ls-l" returns the detailed contents of the working directory.
• string fileRead( string file ); — Return <file> content by string.
• int fileWrite( string file, string str, bool append = false ); — Write <str> to <file>, remove presented or <append>. Return wrote bytes count.
• int message( string cat, int level, string mess ); — formation of the system message <mess> with the category <cat>, level <level> (-7...7). The negative value of the level forms the alarms (Alarm).
• 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 ); — formation of the system message <mess> with the category <cat> and the appropriate level.
• XMLNodeObj XMLNode( string name = "" ); — creation of the XML node object with the name <name>.
• string cntrReq( XMLNodeObj req, string stat = "" ); — request of the control interface to the system via XML. The usual request is written as <get path="/OPath/%2felem"/>. If the station is indicated to the request to the external station is made.
  //Get the station identifier
req = SYS.XMLNode("get").setAttr("path","/%2fgen%2fid");
SYS.cntrReq(req);
idSt = req.text();

  
  
• string sleep(int tm, int ntm = 0); — put to sleep the execution thread on the <tm> seconds and <ntm> ns. The function is added only for completeness and is not highly recommended for use, especially in the procedures of the user interface because it will freeze the interface.
• int time( int usec ); — returns the absolute time in seconds from the epoch of 1/1/1970 and in microseconds, if <usec> is specified.
• int localtime( 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), month (month), year (year), days in the week (wday), days in the year (yday) and sign of summer time (isdst), based on the absolute time in seconds <fullsec> from the epoch 1.1.1970.
• string strftime( 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.
• int strptime( 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's format can be obtained from the documentation on POSIX-function "strptime".
• int cron( string cronreq, int base = 0 ); — returns the time, planned in the format of the standard Cron <cronreq>, beginning from basic time <base> or from the current, if the basic is not specified.
• string strFromCharCode( int char1, int char2, int char3, ... ); — String creation from symbol's codes char1, char2 ... charN.
• string strCodeConv( string src, string fromCP, string toCP ); — Encoding the text <src> from the encoding <fromCP> to <toCP>. If encoding is omitted, it is used inside.

5.3. Any object (TCntrNode) of OpenSCADA objects tree (SYS.*)

Object functions:

• TArrayObj nodeList(string grp = "", string path = ""); — Get child nodes 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.
• 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.

5.4. "Security" subsystem (SYS.Security)

The subsystem object's functions (SYS.Security):

• int access(string user, int mode, string owner, string group, int access) — Check for <user> access to resource what owned by <owner> and <group> and <access> for <mode>:
  user — user for access check;
  mode — access mode (4-R, 2-W, 1-X);
  owner — resource owner;
  group — resource group;
  access — resource access mode (RWXRWXRWX — 0777).

The user (SYS.Security["usr_User"]) or group (SYS.Security["grp_Group"]) object's functions:

• ElTp cfg(string nm) — get value of configuration field <nm> of the object.
• ElTp cfgSet(string nm, ElTp val) — set configuration field <nm> of the object to value <val>.

5.5. "DB" subsystem (SYS.BD)

DB object functions (SYS.BD["TypeDB"]["DB"]):

• ElTp cfg(string nm) — get value of configuration field <nm> of the object.
• ElTp cfgSet(string nm, ElTp val) — set configuration field <nm> of the object to value <val>.
• Array SQLReq( string req ); — Formation of the SQL-request to the DB.
  DBTbl=SYS.BD.MySQL.GenDB.SQLReq("SELECT * from DB;");
for( var i_rw = 0; i_rw < DBTbl.length; i_rw++ )
{
  var rec = "";
  for( var i_fld = 0; i_fld < DBTbl[i_rw].length; i_fld++ )
    rec += DBTbl[i_rw][i_fld]+"\t";
  SYS.messDebug("TEST DB","Row "+i_rw+": "+rec);
  //> Get column value by name
  if(i_rw) SYS.messDebug("TEST DB: ","Row "+i_rw+": 'NAME'"+DBTbl[i_rw]["NAME"]);
}

Table object functions (SYS.BD["TypeDB"]["DB"]["Table"]):

• XMLNodeObj fieldStruct(); — The table structure get in XML-node "field" with child node-columns <RowId type="real" len="10.2" key="1" def="Default value">{Value}</RowId>, wher:
  • {RowId} — column identifier;
  • {Value} — column value;
  • type — value's type for column: str — string, int — integer, real — real and bool — boolean;
  • len — value's length for column, in chars;
  • key — the flag for key-column, and used for search by it value;
  • def — default value for column.
• string fieldSeek(int row, XMLNodeObj fld); — Seek field <row> of table. For success returned "1" else "0". On error case returned "0:Error".
• string fieldGet(XMLNodeObj fld); — Field value request. On error case returned "0:Error".
  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());

  
  
• string fieldSet(XMLNodeObj fld); — Field set. On error case returned "0:Error".
• string fieldDel(XMLNodeObj fld); — Field remove. On error case returned "0:Error".

5.6. Subsystem "DAQ" (SYS.DAQ)

Functions of subsystem's object (SYS.DAQ):

• bool funcCall(string progLang, TVarObj args, string prog); — call function text <prog> whith arguments <args> for programm language <progLang>. Return "true" on well call.
  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);

Functions of object of controller (SYS.DAQ["Modul"]["Controller"]):

• ElTp cfg(string nm) — get value of configuration field <nm> of the object.
• ElTp cfgSet(string nm, ElTp val) — set configuration field <nm> of the object to value <val>.
• string name() — controller name.
• string descr() — controller description.
• string status() — controller status.
• bool alarmSet(string mess, int lev = -5, string prm = "") — set/remove of violations <mess> with the level <lev> (negative for remove otherwise for set), for the parameter <prm>.
• bool enable(bool newSt = EVAL) — get enable status or change it by argument <newSt> assign.
• bool start(bool newSt = EVAL) — get start status or change it by argument "<newSt>" assign.

Functions of object of controller's parameter (SYS.DAQ["Modul"]["Controller"]["Parameter"]):

• ElTp cfg(string nm) — get value of configuration field <nm> of the object.
• ElTp cfgSet(string nm, ElTp val) — set configuration field <nm> of the object to value <val>.

Functions of object of atribute of controller's parameter (SYS.DAQ["Modul"]["Controller"]["Parameter"]["Attribute"]):

• ElTp get( int tm = 0, int utm = 0, bool sys = false ); — get attribute value at time <tm:utm> and system access flag <sys>.
• bool set( ElTp val, int tm = 0, int utm = 0, bool sys = false ); — write value <val> to attribute with time label <tm:utm> and system access flag <sys>.
• TCntrNodeObj arch(); — gets the archive associated with this attribute. In case of absence the associated archive returns "false".
• string descr(); — get attribute description.
• int time(int utm); — last attribute's value time in seconds and microseconds in <utm>.
• int len(); — field length.
• int dec(); — float resolution.
• int flg(); — field's flags.
• string def(); — default value.
• string values(); — allowed values list or range.
• string selNames(); — names of allowed values list.
• string reserve(); — reserve string property value.

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) — get value of configuration field <nm> of the object.
• ElTp cfgSet(string nm, ElTp val) — set configuration field <nm> of the object to value <val>.

5.6.1. The module DAQ.JavaLikeCalc

5.6.2. The module DAQ.ModBus

5.7. "Archives" subsystem (SYS.Archive)

Functions of the subsystem's object:

• Array messGet( int btm, int etm, string cat = "", int lev = 0, string arch = "" ); — request of the system messages for the time from <btm> to <etm> for the category <cat>, level <lev> and archiver <arch>. Return array of the message's objects whith 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); — write message <mess> with category <cat>, level <lev> (-7...7) and time <tm>.<utm> to archive or/and allarms list.

Functions of object's archivator of messages (SYS.Archive["mod_Modul"]["mess_Archivator"]):

• ElTp cfg(string nm) — get value of configuration field <nm> of the object.
• ElTp cfgSet(string nm, ElTp val) — set configuration field <nm> of the object to value <val>.
• bool status() — get archivator status.
• int end() — get archivator data end time.
• int begin() — get archivator data begin time.

Functions of object's archive (SYS.Archive["va_Archive"]) and archivator of values (SYS.Archive["val_Modul"]["val_Archivator"]):

• ElTp cfg(string nm) — get value of configuration field <nm> of the object.
• ElTp cfgSet(string nm, ElTp val) — set configuration field <nm> of the object to value <val>.

5.8. "Transports" subsystem (SYS.Transport)

Functions of the ingoing transport object (SYS.Transport["Modul"]["in_Transp"]):

• ElTp cfg(string nm) — get value of configuration field <nm> of the object.
• ElTp cfgSet(string nm, ElTp val) — set configuration field <nm> of the object to value <val>.

Functions of the outgoing transport object (SYS.Transport["Modul"]["out_Transp"]):

• ElTp cfg(string nm) — get value of configuration field <nm> of the object.
• ElTp cfgSet(string nm, ElTp val) — set configuration field <nm> of the object to value <val>.
• string messIO( string mess, real timeOut = 0 ); — sending the message <mess> through the transport with the waiting timeout <timeOut> (in seconds). In the case of a zero timeout is the time taken from the settings of outgoing transport.
  rez=SYS.Transport.Serial.out_ttyUSB0.messIO(SYS.strFromCharCode(0x4B,0x00,0x37,0x40),0.2);
while(true)
{
  trez = SYS.Transport.Serial.out_ttyUSB0.messIO("");
  if( !trez.length ) break;
  rez+=trez;
}

  
  
• int messIO( XMLNodeObj req, string prt ); — sending the request <req> to the protocol <prt> for the implementation of a connection session through the transport by means of protocol.
  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());

5.9. "User interfaces" subsystem (SYS.UI)

5.9.1. The module UI.VCAEngine

5.10. "Special" subsystem (SYS.Special)

5.10.1. Module Special.FLibSYS

5.10.2. Module Special.FLibMath

5.10.3. Module Special.FLibComplex1