Modules/FLibSYS

---

Module	Name	Version	License	Source	Languages	Platforms	Type	Author	Description
FLibSYS	System functions	1.8	GPL2	spec_FLibSYS.so	en,uk,ru,de	x86,x86_64,ARM	Special	Roman Savochenko   Maxim Lysenko (2009) — the page initial translation	Provides a library of the system functions of the user programming area of OpenSCADA.

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:

Identifier	Name	Type	Mode	By defaults
rez	Result	String	Return
com	Command	String	Input

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:

Identifier	Parameter	Type	Mode	By defaults
rez	Result	Object(IO)	Return
name	File name or data (for string stream)	String	In
accs	File access (""-string stream;"r[+]"-read;"w[+]"-write from zero;"a[+]"-append;...)	String	In
mFormat	Machine data format ('n'-sys order;'b'-BigEndian;'l'-LittleEndian)	Integer	In	"n"
enc	String encoding in the file/stream	Boolean	In

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:

Identifier	Name	Type	Mode	By defaults
rez	Result	Object(Array)	Return
addr	DB address, "{TypeDB}.{DB}"	String	Input
req	SQL request	String	Input
trans	Transaction	Boolean	Input	EVAL

1.4 XML: Node (xmlNode)

Description: Creating a XML node object.
Parameters:

Identifier	Name	Type	Mode	By defaults
rez	Result	Object(XMLNodeObj)	Return
name	Name	String	Input

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:

Identifier	Name	Type	Mode	By defaults
rez	Result	String	Return
req	Request	Object(XMLNodeObj)	Output
stat	Station	String	Input

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:

Identifiers	Parameter	Type	Mode	By defaults
sec	Seconds	Integer	Return	0
usec	Microseconds	Integer	Output	-1

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:

Identifier	Parameter	Type	Mode	By defaults
fullsec	Full seconds	Integer	Input	0
sec	Seconds [0...59]	Integer	Output	0
min	Minutes [0...59]	Integer	Output	0
hour	Hours [0...23]	Integer	Output	0
mday	Day of the month [1...31]	Integer	Output	0
month	Month [0...11]	Integer	Output	0
year	Year, from 1900	Integer	Output	0
wday	Day of the week [0...6]	Integer	Output	0
yday	Day of the year [0...365]	Integer	Output	0
isdst	Daylight saving time	Integer	Output	0

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:

Identifier	Parameter	Type	Mode	By defaults
val	Date and time string	String	Return
sec	Seconds	Integer	Input	0
form	Date and time format	String	Input	%Y-%m-%d %H:%M:%S

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:

Identifier	Parameter	Type	Mode	By defaults
sec	Seconds	Integer	Return	0
str	Date and time string	String	Input
form	Date and time format	String	Input	%Y-%m-%d %H:%M:%S

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:

Identifier	Parameter	Type	Mode	By defaults
res	Result, seconds	Integer	Return	0
str	CRON	String	Input	* * * * *
base	Base time, seconds	Integer	Input	0

2.6 Time: sleep (tmSleep)

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

Identifier	Parameter	Type	Mode	By defaults
res	Result	Integer	Return	0
tm	Time, seconds	Real	Input

3 Functions of the strings processing

3.1 String: Get size (strSize)

Description: Getting size of the string.
Parameters:

Identifier	Parameter	Type	Mode	By defaults
rez	Result	Integer	Return
str	String	String	Input

Example:

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

3.2 String: Get substring (strSubstr)

Description: Getting of the substring.
Parameters:

Identifier	Parameter	Type	Mode	By defaults
rez	Result	String	Return
str	String	String	Input
pos	Position	Integer	Input	0
n	Number	Integer	Input	-1

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:

Identifier	Parameter	Type	Mode	By defaults
str	String	String	Output
pos	Position	Integer	Input	0
ins	String to insert	String	Input

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

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

Identifier	Parameter	Type	Mode	By defaults
str	String	String	Output
pos	Position	Integer	Input	0
n	Number	Integer	Input	-1
repl	String to replace	String	Input

3.5 String: Parse with a separator (strParse)

Description: Parsing the string with a separator.
Parameters:

Identifier	Parameter	Type	Mode	By defaults
rez	Result	String	Return
str	String	String	Input
lev	Level	Integer	Input
sep	Separator	String	Input	"."
off	Offset	Integer	Output

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:

Identifier	Parameter	Type	Mode	By defaults
rez	Result	String	Return
path	Path	String	Input
lev	Level	Integer	Input
off	Offset	Integer	Output

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:

Identifier	Parameter	Type	Mode	By defaults
rez	Result	String	Return
src	Source	String	Input
sep	Separator	String	Input	"."

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:

Identifier	Parameter	Type	Mode	By defaults
rez	Result	String	Return
src	Source	String	Input

3.9 String: Encode text to binary (strEnc2Bin)

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

Identifier	Parameter	Type	Mode	By defaults
rez	Result	String	Return
src	Source	String	Input

3.10 String: Decode text from binary (strDec4Bin)

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

Identifier	Parameter	Type	Mode	By defaults
rez	Result	String	Return
src	Source	String	Input

3.11 String: Real to string (real2str)

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

Identifier	Parameter	Type	Mode	By defaults
rez	Result	String	Return
val	Value	Real	Input
prc	Precision	Integer	Input	4
tp	Type	String	Input	"f"

3.12 String: Integer to string (int2str)

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

Identifier	Parameter	Type	Mode	By defaults
rez	Result	String	Return
val	Value	Integer	Input
base	Base (8, 10, 16)	Integer	Input	10

3.13 String: String to real (str2real)

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

Identifier	Parameter	Type	Mode	By defaults
rez	Result	Real	Return
val	Value	String	Input

3.14 String: String to integer (str2int)

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

ID	Parameter	Type	Mode	By defaults
rez	Result	Integer	Return
val	Value	String	Input
base	Base (2...36)	Integer	Input	0

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:

Identifier	Parameter	Type	Mode	By defaults
rez	Result	Integer	Return
data	Data	String	Input
width	Width	Integer	Input	16
poly	Polynomial	Integer	Input	32773 (0x8005)
init	Initial	Integer	Input	-1 (0xFFFFFFFFFFFFFFFF)
RefIn	Reference input	Bool	Input	1
RefOut	Reference output	Bool	Input	1
XorOut	XOR for output	Integer	Input	0

3.16 Message Digest 5 (MD5)

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

Identifier	Parameter	Type	Mode	By defaults
rez	Result	String	Return
data	Data	String	Input

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:

Identifier	Parameter	Type	Mode	By defaults
val	Value	Real	Input
w1	Word 1	Integer	Output
w2	Word 2	Integer	Output

4.2 Float: Merge from the words (floatMergeWord)

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

Identifier	Parameter	Type	Mode	By defaults
rez	Result	Real	Return
w1	Word 1	Integer	Input
w2	Word 2	Integer	Input

4.3 Float: Extract (floatExtract)

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

Identifier	Parameter	Type	Mode	By defaults
magn	Magnitude	Real	Return
val	Value	Real	Input
exp	Exponent	Integer	Output

5 Functions of archives

5.1 Mess: Get (messGet)

Description: Get messages of the program.
Parameters:

Identifier	Parameter	Type	Mode	By defaults
rez	Result	Object(Array)	Return
btm	Begin time, seconds	Integer	Input
etm	End time, seconds	Integer	Input
cat	Category	String	Input
lev	Level	Integer	Input
arch	Archiver	String	Input

5.2 Mess: Put (messPut)

Description: Put a message to the program.
Parameters:

Identifier	Parameter	Type	Mode	By defaults
cat	Category	String	Input
lev	Level	Integer	Input
mess	Message	String	Input

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:

Identifier	Name	Type	Mode	By defaults
rez	Result	Object(VArchObj)	Return
name	Name — address to the attribute of the parameter (DAQ.{Module}.{Cntr}.{Prm}.{Attr}) with the archive or directly to the value archive (Archive.va_{ValArchive}).	String	Input

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:

Identifier	Parameter	Type	Mode	By defaults
rez	Result	Object(VArchObj)	Return
tp	Type of the archive values (0-Boolean, 1-Integer, 4-Real, 5-String)	Integer	Input	1
sz	Maximum buffer size	Integer	Input	100
per	Period of the buffer values, microseconds	Integer	Input	1000000
hgrd	Hard time grid	Boolean	Input	0
hres	High time resolution (microseconds)	Boolean	Input	0

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.