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;
• 'u' — UTF-8 symbols force for other locales;
• '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.
• UTF8 — UTF-8 symbols allowed.
• 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.

• bool test( string val ); — Return "true" for match substring in val.

XMLNodeObj object

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 combined text all included nodes.
• 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.
• XMLNodeObj clear( bool full = false ) — Clear the node for the childs remove, text and attributes for full.
• 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 included node from the position id. Returns the current node.
• XMLNodeObj childGet( int id ) — Getting the included node in the position id.
• XMLNodeObj childGet( string name, int num = 0 ) — Getting the included node with tag name and position number num.
• XMLNodeObj parent( ) — Get parent node.
• string load( string str, bool file = false, int flg = 0, 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. flg — loading flags:
  0x01 — full loading, with texts and comments blocks into special nodes;
  0x02 — no remove spaces for begin and end tag's text.
  
• string save( int flg = 0, string path = "", string cp = "UTF-8" ) — Saving 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 — 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|int} 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 fileRemove( string file ); — Remove file. Return the removing result.
• 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 stat is indicated to the request then to the external station will send one. The address into attribute "path" you can obtain into OpenSCADA configurator, namely into status line where the address appear at the mouse cursor point to configuring or information field. Examples for wide requests:
  • Reading value from the element (user "test" name):
  req = SYS.XMLNode("get").setAttr("path","/sub_Security/usr_test/%2fprm%2fDESCR"); SYS.cntrReq(req); idSt = req.text();
  
  • Writing value to the element (user "test" name):
  req = SYS.XMLNode("set").setAttr("path","/sub_Security/usr_test/%2fprm%2fDESCR").setText("New test user name"); SYS.cntrReq(req);
  
  • Adding new node (user "test"):
  req = SYS.XMLNode("add").setAttr("path","/sub_Security/%2fbr%2fusr_").setText("test"); SYS.cntrReq(req);
  
  • Deleting node (user "test"):
  req = SYS.XMLNode("del").setAttr("path","/sub_Security/%2fbr%2fusr_").setText("test"); SYS.cntrReq(req);
  
  • Saving the node changes to DB (user "test"):
  req = SYS.XMLNode("save").setAttr("path","/sub_Security/usr_test/%2fobj"); SYS.cntrReq(req);
  
  • Loading the node from DB (user "test"):
  req = SYS.XMLNode("load").setAttr("path","/sub_Security/usr_test/%2fobj"); SYS.cntrReq(req);
  
• int sleep( real tm, int ntm = 0 ); — put to sleep the execution thread on the tm seconds (precised up to nanoseconds) and ntm ns. The sleeping time you can set up to STD_INTERF_TM (5 seconds).
• 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 utime( ); int mtime( ); — return absolute time in microseconds and milliseconds from the epoch of 1/1/1970.
• 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), 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. gmtime return time into GMT(UTC).
• int {mktime|timegm}( int sec, int min, int hour, int mday, int month, int year, int wday, int yday, int isdst ); — the time forming 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, that allow the function using for seek will correct and return the items values into typical range. timegm work into GMT(UTC) time.
• 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 return time into GMT(UTC).
• 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's format can be obtained from the documentation on POSIX-function "strptime". strptimegm work into GMT(UTC) time.
• 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 (empty string), it is used inside.
• string strEncode( string src, string tp = "Bin", string opt1 = "" ); — String src encoding by rules tp and option opt1 (symbols for "Custom"). Allowed rules:
  "PathEl" — symbols '/' and '%' to "%2f" and "%25", respectively;
  "HttpURL" — symbols ' ', '\t', '%' and "> 0x80" to "%20", "%09", "%25" and etc.;
  "HTML" — symbols of the HTML-entities '>', '<', '"', '&', '\'' to "&gt;", "&lt;", "&quot;" and etc.;
  "JavaScript" — symbol '\n' shielding "\\n";
  "SQL" — symbols shielding '\'', '\"', '`', '\\' or doubling of the listed symbols into opt1;
  "Custom" — set symbols into opt1 to "%NN";
  "Base64" — same Base 64 binary encoding, into opt1 sets 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 binary represent;
  "Reverse" — reversion the sequence;
  "ShieldSimb" — shielding symbols like '\a', '\b', ..., '\0NNN', '\xNN' to binary represent.
  
• string strDecode( string src, string tp = "Bin", string opt1 = "" ); — String src decoding by rules tp and option opt1 (separator for "Bin"). Allowed rules:
  "PathEl", "HttpURL", "Custom" — decoding symbols like "%NN" to binary represent;
  "Base64" — same from Base 64;
  "Bin" — the binary string to ASCII bytes ("XX XX XX XX ...").

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

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.
• 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.

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"]) object's functions:

• ElTp cfg( string nm ) — get value of configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) — set configuration field nm of the object to value val.
• Array groups( ) — groups list of the user

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

• ElTp cfg( string nm ) — get value of configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) — set configuration field nm of the object to value val.
• bool user( string nm ) — checking for user nm presence into the group.

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.
• bool cfgSet( string nm, ElTp val ) — set configuration field nm of the object to value val.
• Array SQLReq( string req, bool tr = EVAL ); — Formation of the SQL-request to the DB, inside (tr=true), outside (tr=false) or no matter (tr=EVAL) to transaction. At an error the result's property "err" sets to the error value.

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".

• 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, string fixId = ""); — call function text prog with arguments args for program language progLang and with the function fixing identifier fixId (automatic if it is empty). Return "true" on well call. The fixed function differ from the automatic by it does not remove after execution and uses repeatedly by an address into fixId, which replaces that original identifier in first call. For the fixed function recreate you need change the program or clean up fixId by the function original id.

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

• ElTp cfg( string nm ) — get value of configuration field nm of the object.
• bool 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. The function forming alarm with category: al{ModId}:{CntrId}[.{PrmId}], where:
  • ModId — the module identifier;
  • CntrId — the controller identifier;
  • PrmId — parameter identifier, from argument 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.
• bool cfgSet( string nm, ElTp val ) — set configuration field nm of the object to value val.
• TCntrNodeObj cntr() — return the object of controller for the parameter nesting independent.

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.
• bool 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.LogicLev

5.6.3. The module DAQ.BlockCalc

5.6.4. 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 = "", int upTm = 0 ); — request of the system messages or alarms for the time from btm to etm for the category cat, level lev (-7...7) and archivators arch (separated by symbol ';'; "" — buffer and archivators; "<buffer>" — buffer; "{ArhMod}.{Arh}" — concrete archivator of the module). upTm sets the operation continuance limit to time; a negative value used as relative time; less to STD_INTERF_TM (5). Return time of stopping of the reading (attribute "tm" of the array) and array of the message's objects with 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 = "" ); — write message mess with category cat, level lev (-7...7) and time tm.utm to archivators arch (separated by symbol ';') or/and alarms list.

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

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

Functions of object's archiver of values (SYS.Archive["val_Modul"]["val_Archivator"]):

• ElTp cfg( string nm ) — get value of configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) — set configuration field nm of the object to value val.
• bool status( ) — get the archiver start status.

Functions of object's archive (SYS.Archive["va_Archive"]):

• ElTp cfg( string nm ) — get value of configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) — set configuration field nm of the object to value val.
• bool status( ) — get the archive start status.
• int end(string arch = "") — get the archive data end time for the archiver arch, in microseconds.
• int begin(string arch = "") — get the archive data begin time for the archiver arch, in microseconds.
• int period(string arch = "") — get the archive data period for the archiver arch, in microseconds.
• TArrayObj archivatorList() — get the archivers list which using the archive as source.
• VarType getVal(int tm, bool up_ord = false, string arch = "") — get one value from the archive for the time tm, up order up_ord and the archiver arch:
  • tm — the time for requested value, in microseconds. Set to 0 for end().
  • up_ord — fit the requested value time to up for the grid.
  • arch — the archiver for the request. Set to empty for buffer and all archivers try. Set to "<buffer>" for the buffer only process.
• bool setVal(int tm, VarType vl, string arch = "") — set one value vl to the archive for the time tm and the archiver arch:
  • tm — the time for set value, in microseconds.
  • vl — the value.
  • arch — the archiver for the query. Set to empty for buffer and all archivers. Set to "<buffer>" for the buffer only process.

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.
• bool cfgSet( string nm, ElTp val ) — set configuration field nm of the object to value val.
• string status() — the transport status.
• string addr( string vl = "" ) — the transport address return, set the to no empty vl.
• string writeTo(string sender, string mess) — Send the message mess to sender sender.
• TArrayObj assTrsList() — assigned output transports list to the input.

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

• ElTp cfg( string nm ) — get value of configuration field nm of the object.
• bool cfgSet( string nm, ElTp val ) — set configuration field nm of the object to value val.
• string status() — the transport status.
• bool start( bool vl = <EVAL>, int tm = 0 ) — the transport start status return, start/stop it by vl (if it is not <EVAL>). For starting you can set the specific timeout tm.
• string addr( string vl = "" ) — the transport address return, set the to no empty vl.
• string timings( string vl = "" ) — the transport timings return, set the to no empty vl.
• string messIO( string mess, real timeOut = 0, int inBufLen = -1 ); — sending the message mess through the transport with the waiting reply timeout timeOut (in seconds) and the reply reading (buffer) size inBufLen bytes. In the case of a zero timeout is the time taken from the settings of outgoing transport. The timeOut in negative (< -1e-3) disables the transport's request/respond mode and allow 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.

• string 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.

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