From OpenSCADAWiki
Jump to: navigation, search

Program-system (SYS)

Object functions:

  • {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.
  • int fileSize( string file ); — returns the file size.
  • 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.
  • 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.
  • int fileRemove( string file ); — removes the file. Returns the removing result.
  • 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.
  • 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.
  • XMLNodeObj XMLNode( string name = "" ); — creates of the XML node object with the name.
  • string cntrReq( XMLNodeObj req, string stat = "" ); — sends a request req in XML view to the Control Interface of the program. Returns a string with error in the format "{errCod}:{errText}", which is "0" for successful. A request is generally written in the form <get path="/OPath/%2felem" /> and with additional attributes specific to the particular request. If the station stat is specified into the request then the request will be sent to this external station. The address for the attribute "path" you can obtain into the OpenSCADA configurator, that is into the status line where the address appear at the mouse cursor point to a field of configuration or information. Some examples of common requests, more examples in description the Control Interface and releaseTests():
    • Reading a value of the element (the user name "test"): 
      req = SYS.XMLNode("get").setAttr("path","/sub_Security/usr_test/%2fprm%2fDESCR");
SYS.cntrReq(req);
idSt = req.text();
    • Writing a value to the element (the user name "test"): 
      req = SYS.XMLNode("set").setAttr("path","/sub_Security/usr_test/%2fprm%2fDESCR").setText("New test user name");
SYS.cntrReq(req);
    • Adding a new node (the user "test"): 
      req = SYS.XMLNode("add").setAttr("path","/sub_Security/%2fbr%2fusr_").setText("test");
SYS.cntrReq(req);
    • Deleting a node (the user "test"): 
      req = SYS.XMLNode("del").setAttr("path","/sub_Security/%2fbr%2fusr_").setText("test");
SYS.cntrReq(req);
    • Saving the node changes to DB (the user "test"): 
      req = SYS.XMLNode("save").setAttr("path","/sub_Security/usr_test/%2fobj");
SYS.cntrReq(req);
    • Loading the node from DB (the user "test"): 
      req = SYS.XMLNode("load").setAttr("path","/sub_Security/usr_test/%2fobj");
SYS.cntrReq(req);
  • string lang(string full); — returns the system language in two symbols and the full language in full.
  • 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).
  • 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.
  • int utime( ); int mtime( ); — returns the 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), 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).
  • 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).
  • 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).
  • 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.
  • 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. CRON is the standard form "* * * * *".
    Where items by the order
    • minutes (0-59);
    • hours (0-23);
    • days (1-31);
    • month (1-12);
    • week day (0[Sunday]-6).
    Where the item variants
    • "*" — any value;
    • "1,2,3" — list of the allowed values;
    • "1-5" — raw range of the allowed values;
    • "*/2" — divider to the all allowed values range.
    Examples
    • "* * * * *" — each minute;
    • "10 23 * * *" — only at 23 hour and 10 minute for any day and month;
    • "*/2 * * * *" — for minutes: 0,2,4,...,56,58;
    • "* 2-4 * * *" — for any minutes in hours from 2 to 4(include).
  • string strFromCharCode( int char1, int char2, int char3, ... ); — creates a string from symbol codes char1, char2 ... charN.
  • 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.
  • 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.
  • string strEncode( string src, string tp = "Bin", string opt = "" ); — encodes the string src by the rule tp and the option opt. Allowed rules:
    "PathEl" — symbols [/%] to "%2f" and "%25", respectively;
    "HttpURL" — symbols [ \t%] and "> 0x80" to "%20", "%09", "%25" and etc.;
    "HTML" — symbols of the HTML-entities [><"&'] to "&gt;", "&lt;", "&quot;" and etc.;
    "JavaScript" — symbol '\n' shielding to "\\n";
    "SQL" — shielding of the symbols ['"`\] by appending '\' or doubling of the listed symbols into opt;
    "Custom" — symbols into opt to the view "%NN";
    "Base64" — same Base 64 binary encoding, into opt sets a line termination symbol(s) after 57 symbols;
    "FormatPrint" — symbol '%' to "%%";
    "OscdID" — almost all symbols like [ /\&(] to '_';
    "Bin" — ASCII bytes list ("XX XX XX XX ...") to the binary represent;
    "Reverse" — reversion the sequence;
    "ToLower" — symbols to the lower register;
    "Limit" — limiting the string to the length into opt, counting UTF-8 variable length;
    "ShieldSymb" — shielding symbols from opt (by default ['"`]) with the slash symbol "\" like to '\n', '\r', ..., '\0NNN';
    "ShieldBin" — shielding all binary symbols [\x0-\x8\xB-\xC\x0E-\x1F] with the slash symbol "\".
  • string strDecode( string src, string tp = "Bin", string opt = "" ); — decodes the string src by the rule tp and the option opt. Allowed rules:
    "PathEl", "HttpURL", "Custom" — symbols like "%NN" to the binary represent;
    "Base64" — same from Base 64;
    "Bin" — the binary string to ASCII bytes ("XX XX XX XX .. A.b.c.."), opt points to the separator or "<text>" for enable the offset to the left and the text part to the right;
    "ShieldSymb" — shielded symbols like to '\n', '\r', ..., '\0NNN', '\xNN' to the binary represent.
Retrieved from "http://oscada.org/wiki/index.php?title=Translations:Documents/User_API/14/en&oldid=88467"