From OpenSCADAWiki
Jump to: navigation, search
Other languages:
Module Name Version License Source Languages Platforms Type Author Description
FLibSYS System functions 1.6 GPL2 spec_FLibSYS.so en,uk,ru,de x86,x86_64,ARM Special Roman Savochenko
  Maxim Lysenko (2009) — the page translation
Provides a library of the system functions of the user programming area of OpenSCADA.

Contents

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|double|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 implementing of the Cyclic Redundancy Code for the width in 8-64 bits.
Parameters:

Identifier Parameter Type Mode By defaults
rez Result Integer Return
data Data String Input
poly Polynomial (reversion) Integer Input 40961 (0xA001)
width Width Integer Input 16
init Initial Integer Input -1 (0xFFFFFFFFFFFFFFFF)

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.