Modules/FLibSYS

The module provides OpenSCADA for static library of functions for use in the user programming environment and the organization of extraordinary interaction algorithms.

To address the functions of the library you can use the static call address Special.FLibSYS.{Func}() or dynamic SYS.Special.FLibSYS["{Func}"].call(), SYS.Special.FLibSYS.{Func}(). Where {Func} — function identifier in the library.

1 System-wide functions

1.1 SYS: Call (sysCall)

Description: Calling the console commands of the OS. The function offers great opportunities to the OpenSCADA user by calling any system software, utilities and scripts, as well as getting the access to the huge volume of system data by means of them. For example the command "ls-l" returns the detailed contents of the working directory.
Parameters:

Example:

using Special.FLibSYS;
test=sysCall("ls -l");
messPut("Example",0,"Example: "+test);

1.2 SYS: Input/Output (IO)

Description: Input/Output to: file, string stream.
Parameters:

1.2.1 IO object

Values:

• valType — value types:
  • "uchar", "unsigned char", "char", "schar", "signed char";
  • "uint8";
  • "uint16", "ushort";
  • "uint32", "uint", "ulong";
  • "uint64";
  • "int8", "integer*1";
  • "int16", "short", "integer*2";
  • "int32", "int", "long", "integer*4", "integer";
  • "int64", "integer*8";
  • "float", "float32", "single", "real*4";
  • "double", "float64", "real*8", "real";
• accs — access mode and type:
  • — string stream;
  • 'r[+]' — read;
  • 'w[+]' — write from zero;
  • 'a[+]' — append.
• mFmt — machine format:
  • 'n' — native;
  • 'l' — LittleEndian;
  • 'b' — BigEndian.

Properties:

• length — stream length;
• pos (w) — stream read/write position;
• string (w) — string stream full value;
• mFormat (w) — machine data format;
• stringEncode (w) — file/stream substring encoding.

Functions:

• bool open(string name = "", string accs = "", string mFormat = "n", string enc = ""); — opens a new stream for string or the file name.
• bool close(); — closes the stream.
• {string|int|real|Array[int|real]} read(string valType = "char", int cnt = -1, string mFormatEnc = "n|NoEnc"); — reads a value of the valType in the cnt for the machine format or the input string encoding mFormatEnc.
• {int|IO} {write|wr}({string|int|real|Array} vals, string valType = "char", string mFormatEnc = "n|NoEnc", int cnt = 1); — writes the value(s) vals for the type valType for the machine format or the input string encoding mFormatEnc, and a repeat of scalar values in the amount cnt.

1.3 DB: SQL request (dbReqSQL)

Description: Formation of the SQL-request req to the DB addr, inside (trans=true), outside (trans=false) or no matter (trans=EVAL) to a transaction. At an error the result's property "err" sets to the error value.
Parameters:

1.4 XML: Node (xmlNode)

Description: Creating a XML node object.
Parameters:

Example:

using Special.FLibSYS;
//Creating the "get" object of the XML node.
req = xmlNode("get");
//Creating the "get" object of the XML node with attributes creating.
//sub_DAQ/mod_ModBus/cntr_1/prm_1 — path according to the project structure.
req = xmlNode("get").setAttr("path","/sub_DAQ/mod_ModBus/cntr_1/prm_1/%2fprm%2fst%2fen");

1.5 XML: Control request (xmlCntrReq)

Description: Requesting for control the program, by XML. The usual request is written in the form "<get path="/OPat/%2felem"/>". When we indicate the station the request to the specified external station is made.
Parameters:

Example (more examples see for the equal internal function SYS.cntrReq()):

using Special.FLibSYS;
//Getting status "Off/On" of the parameter "1" of the controller "1" of the module "ModBus".
//sub_DAQ/mod_ModBus/cntr_1/prm_1 —  the path according to the project structure.
req = xmlNode("get").setAttr("path","/sub_DAQ/mod_ModBus/cntr_1/prm_1/%2fprm%2fst%2fen");
rez = xmlCntrReq(req);
messPut("test",0,"Example: "+req.text());

//Setting the status "On" of the parameter "1" of the controller "1" of the module "ModBus".
req = xmlNode("set").setAttr("path","/sub_DAQ/mod_ModBus/cntr_1/prm_1/%2fprm%2fst%2fen").setText(1);
rez = xmlCntrReq(req);

//Setting the status "Off of the parameter "1" of the controller "1" of the module "ModBus".
req = xmlNode("set").setAttr("path","/sub_DAQ/mod_ModBus/cntr_1/prm_1/%2fprm%2fst%2fen").setText(0);
rez = xmlCntrReq(req);

2 Functions of working with time

2.1 Time: Time (tmTime)

Description: Returns the absolute time in seconds from the epoch of 1/1/1970 and the microseconds part into usec, if such a variable is indicated and its value is negative.
Parameters:

2.2 Time: Date and time (tmDate)

Description: Full date and time in seconds, minutes, hours, etc., based on the absolute time in seconds from the epoch of 1.1.1970.
Parameters:

Example:

using Special.FLibSYS;
curMin=curHour=curDay=curMonth=curYear=0;
tmDate(tmTime(),0,curMin,curHour,curDay,curMonth,curYear);
messPut("test",0,"Current minute: "+curMin);
messPut("test",0,"Current hour: "+curHour);
messPut("test",0,"Current day: "+curDay);
messPut("test",0,"Current month: "+curMonth);
messPut("test",0,"Current Year: "+curYear);

2.3 Time: String time (tmFStr)

Description: Getting the time in the formatted string. Recording of the format corresponds to the POSIX-function "strftime()".
Parameters:

Example:

using Special.FLibSYS;
test = tmFStr(SYS.time(),"%d %m %Y");
messPut("Example",0,"tmFStr(): "+test);

2.4 Time: String to time (tmStrPTime)

Description: Converting the string data and time, for the form, to the time in seconds since 01.01.1970. For example, template "%Y-%m-%d %H:%M:%S" corresponds the time "2006-08-08 11:21:55". Description of the format of the template can be obtained from the documentation on the POSIX-function "strptime()".
Parameters:

Example:

using Special.FLibSYS;
curMin=curHour=curDay=curMonth=curYear=0;
tmDate(tmTime(),0,curMin,curHour,curDay,curMonth,curYear);
test = tmStrPTime(""+curYear+"-"+(curMonth+1)+"-"+curDay+" 9:0:0","%Y-%m-%d %H:%M:%S");
messPut("Example",0,"tmStrPTime(): "+test);

2.5 Time: Schedule time at CRON (tmCron)

Description: Scheduling the time at the CRON standard, returning the planned time from the base time or from the current time, if the base is not specified.
Parameters:

2.6 Time: sleep (tmSleep)

Description: Short sleeping from nanoseconds and up to STD_INTERF_TM (5 seconds).
Parameters:

3 Functions of the strings processing

3.1 String: Get size (strSize)

Description: Getting size of the string.
Parameters:

Example:

using Special.FLibSYS;
messPut("Example",1,"ReturnString: "+strSize("Example"));

3.2 String: Get substring (strSubstr)

Description: Getting of the substring.
Parameters:

Example:

using Special.FLibSYS;
test = strSubstr("Example", 0, strSize("Example")-1);
messPut("Example", 1, "ReturnString: "+test);

3.3 String: Insert a string to other string (strInsert)

Description: Inserting a string to another string.
Parameters:

3.4 String: Replace a part of the string by another string (strReplace)

Description: Replacing a part of the string by another string.
Parameters:

3.5 String: Parse with a separator (strParse)

Description: Parsing the string with a separator.
Parameters:

Example:

using Special.FLibSYS;
ExapleString = "Example:123";
test = strParse(ExapleString, 1, ":");
messPut("Example", 0, "strParse(): "+test);

3.6 String: Parse of the path (strParsePath)

Description: Parsing of the path for items.
Parameters:

Example:

using Special.FLibSYS;
test = strParsePath(path, 0, "/");
messPut("Example", 1, "strParsePath(): "+test);

3.7 String: Path to separated string (strPath2Sep)

Description: Converting the path to the separated string.
Parameters:

Example:

//Converting the value "/ses_AGLKS/pg_so" of the attribute "path" to the value "ses_AGLKS.pg_so"
using Special.FLibSYS;
test = strPath2Sep(path);
messPut("Example", 0, "path: "+path);
messPut("Example", 0, "strPath2Sep(): "+test);

3.8 String: Encode string to HTML (strEnc2HTML)

Description: Encoding the string to use into the HTML source.
Parameters:

3.9 String: Encode text to binary (strEnc2Bin)

Description: Encoding the text to the binary, for the text format <00 A0 FA DE>.
Parameters:

3.10 String: Decode text from binary (strDec4Bin)

Description: Decoding the text from the binary, for the text format <00 A0 FA DE>.
Parameters:

3.11 String: Real to string (real2str)

Description: Converting the real value to the string format.
Parameters:

3.12 String: Integer to string (int2str)

Description: Converting the integer value to the string format.
Parameters:

3.13 String: String to real (str2real)

Description: Converting the string value to the real format.
Parameters:

3.14 String: String to integer (str2int)

Description: Converting the string value to the integer format.
Parameters:

3.15 Cyclic Redundancy Code (CRC)

Description: Unified and completed implementing of the Cyclic Redundancy Code for the width in 1-64 bits with normal polynomial, the initial CRC, the input and output reference, and the XOR for output.
The previous notation of the function is supported also, where the reversed polynomial is placed in the width place!
Parameters:

3.16 Message Digest 5 (MD5)

Description: Calculating for the message Digest 5 of the data.
Parameters:

4 Functions for the real processing

4.1 Float: Split to the words (floatSplitWord)

Description: Splitting the float value (4 bytes) to the two words (2 bytes).
Parameters:

4.2 Float: Merge from the words (floatMergeWord)

Description: Forming the float value (4 bytes) from the two words (2 bytes).
Parameters:

4.3 Float: Extract (floatExtract)

Description: Extracting for mantissa and exponent from the float value.
Parameters:

5 Functions of archives

5.1 Mess: Get (messGet)

Description: Get messages of the program.
Parameters:

5.2 Mess: Put (messPut)

Description: Put a message to the program.
Parameters:

Example:

rnd_sq_gr11_lineClr="red";
Special.FLibSYS.messPut("Example",1,"Event: "+rnd_sq_gr12_leniClr);

5.3 Val: Archive (vArh)

Description: Getting the value archive object (VArchObj) through connecting to the archive at its address.
Parameters:

5.3.1 VArchObj object

Functions:

• bool isNull() — object is not initiated.
• int begin( int usec = 0, string archiver = "" ) — start time of the archive, through the return of seconds and microseconds usec for the archiver.
• int end( int usec = 0, string archiver = "" ) — end time of the archive, through the return of seconds and microseconds usec for the archiver.
• int period( int usec = 0, string archiver = "" ) — period of the archive, through the return of seconds and microseconds usec for the archiver.
• ValObj get( int sec, int usec, bool upOrd = false, string archiver = "" ) — value from the archive at the time sec:usec linked to the top upOrd for the archiver. Real time of the obtained value is set in sec:usec.
• bool set( ValObj val, int sec, int usec, string archiver = "" ) [access to the Archive-History subsystem for archive operations] — writes of the value val to the archive for the time sec:usec for the archiver.
• bool copy( VArchObj src, int begSec, int begUSec, int endSec, int endUSec, string archiver = "" ) [access to the Archive-History subsystem for archive operations] — copies of the part of the source archive src, or its buffer, in the current one beginning from begSec:begUSec and ending with endSec:endUSec for the archiver.
• ArrayObj FFT( int tm, real size, string archiver = "", int tm_usec = 0 ) — performs the Fast Fourier Transformation using the FFT algorithm. Returns an array of amplitudes of the frequencies for archive's values window for begin time tm:tm_usec (seconds:microseconds), depth to history size (seconds) and for archiver.
  

Example:

using Special.FLibSYS;
val = vArh(strPath2Sep(addr)).get(time,uTime,0,archtor);
return val.isEval() ? "Empty" : real2str(val,prec);

5.4 Val: Archive buffer (vArhBuf)

Description: Getting a value buffer object (VArchObj) for temporary values storing and performing the intermediate operations on frames of data.
Parameters:

6 User programming API

The module, as an object, provides user programming functions.

The object "Functions library" (SYS.Special.FLibSYS)

• ElTp {funcID}(ElTp prm1, ...) — call the library function {funcID}. Return result of the called function.

The object "User function" (SYS.Special.FLibSYS["funcID"])

• ElTp call(ElTp prm1, ...) — call the function with parameters prm{N}. Return result of the called function.