Libs/Documents

Name	Version	License	Source	Languages	Author	Icon	Description
Reports' and documents' library	2.0, 2.1	GPLv2	OscadaLibs.db (SQL, GZip) > DAQ.JavaLikeCalc.doc vcaBase.db (SQL, GZip) > VCA.wlb_doc	en, uk, ru	Roman Savochenko		Provides the combined library of the reports, documents and related functions of common and the industrial automation. Founded: January 2008 Initially created, for the functions: in the old Wiki Used by: most projects on OpenSCADA To Do: - expand the document "Year report of the month values" in processing the manual entered counters overrun; - expand the document function "Diagram" in support the bar graphs.

The library is created to provide report and document elements-frames of the user interface and it contains graphic elements, often need when forming the user interface of the automation of technological and common processes. The library is mostly built on the basis the primitive "Document" and the internal programming language JavaLikeCalc, for the related functions also.

The element's names and their parameters are available in languages: English, Ukrainian and mRussian. Their source code wrote in human-language independent mode with calls for the translations by the function tr() and the message's translation also allowed for English, Ukrainian and mRussian.

1 Documents

Contains elements-frames of the documents of the template and end types, what intended to be placed in the "Documents" part (the type of view) of the project tree of the pages, built on the concept of the signal objects of the root page "RootPgSo". However, they may be located as separate entities or as a part of your own concept of the page management, but it should be take in account that frames often refer and call the panel of documents!

For connection the library part to a project of the OpenSCADA station you can obtain the database file as:

• supplied with a ready and proper package of the Linux distribution like to "openscada-libdb-vca", "openscada-LibDB.VCA";
• directly taken for most actual one from the subversion repository and converted to the DB SQLite file in the way:

wget http://oscada.org/svn/trunk/OpenSCADA/data/LibsDB/vcaBase.sql
sqlite3 -init vcaBase.sql vcaBase.db .exit

• downloaded for the one attached here.

This obtained file next you can place into the project directory of the station and create the database object for the DB module "SQLite", registering the database file in the configuration.

The frame, shown in Figure 1.1, is a template of documents of the archive type and it is provided as an example and for building own archive documents on it basis. The main specific of that document type is the periodic generating on the VCA-session level (in the background) and placing the final and ready to view documents to an archive, the VCA-project's session DB-table "prj_{ProjID}_ses".

The main advantage of this document type is the lowest load on CPU during the generation, which can be multi-step one during the main generation period, and the fast view, which involves simply opening the ready documents from the archive. But this document type has a significant disadvantage, which is the constant execution of single project session in the background and the absence of which leads to the omission of the documents generation in the archive.

Therefore, documents of this type are appropriated to use on the stationary AWPs of the operators, even if it is a reproduction from the visualisation server, and are useless in the WEB-interface!

Fig.1.1. The "Document - archival" frame in the development mode.

Using — development
The frame can only be used as a basis for creating your own archival type documents, for which you should it copy or inherit, by selecting the appropriate option in the copy dialog. Next, you need to edit the document template, in the appropriate attribute, according to the needs of your document, and write your own procedure for periodically and step-by-step formatting of the documents with closing to the archive, a sample of which can be obtained from the final documents based on this.

The document, shown in Figure 1.1.1, is provided for generating a day report of the hour-averaged values in view of the trends diagram and the data table. The document is initially the archival type but in time it is made dynamic also, so, depending from the execution mode, you can whether select a ready document from the archive or specify the data time and depth. The document commonly uses and represents the representative structure of the DAQ-template "Analog signal". As a data source of this document is the value archives of the DAQ-parameters.

Working in the primary archival mode performed with the 5 minutes period, when during an hour an one record-row data is formed. The last one record-row is closed at the 5 minute of a new hour (14:05 for example) and a new one record-row is started. Whole and complete document is archived at the 3 minute of the "Report hour (repHour)" of the next day (09:03 for example).

• Sponsored for the dynamization by: BLUE STAR GROUP Ltd and Vinnica Poultry Farm

Fig.1.1.1. The "Day report of the hour-averaged values" document in the runtime mode.

Using — development
The document is designed to perform the role of page-template, and should therefore be placed directly in the project's tree. To each document can be connected up to ten parameters, setting the links. Items, for which there are not set the links, will be hidden at runtime.

To each document can be set:

• the "Archive length (n)" attribute in need value of the document archive size or in 0 for the dynamic mode;
• the "Archiver (arch)" attribute in need archiver that maintains the specified parameters; you must not use archivers with worse at one minute quality;
• the "Report hour (repHour)" attribute in the document report hour — start hour of the day;
• the "Enable graph (enGraph)" attribute for enable/disable the graph;
• the "Title (title)" attribute in the document specific title.

Using — runtime
In the runtime mode, the items, for which links have been set, are displayed. Additionally you can control the display properties of documents, for what there is used the document control panel, which can be called clicking the left mouse button in the document area.

Linking and configuring the attributes

The document, shown in Figure 1.1.2, is provided for generating a month report of the day-averaged values in view of the trends diagram and the data table. The document is initially the archival type but in time it is made dynamic also, so, depending from the execution mode, you can whether select a ready document from the archive or specify the data time and depth. The document commonly uses and represents the representative structure of the DAQ-template "Analog signal". As a data source of this document is the value archives of the DAQ-parameters.

Working in the primary archival mode performed with the 5 minutes period, when during a day an one record-row data is formed. The last one record-row is closed at the 5 minute of a new day (05 09:05 for example) and a new one record-row is started. Whole and complete document is archived at the 3 minute of the "Report hour (repHour)" of the next month (05 09:03 for example).

• Sponsored for the dynamization by: BLUE STAR GROUP Ltd

Fig.1.1.2. The "Month report of the day-averaged values" document in the runtime mode.

Using — development
The document is designed to perform the role of page-template, and should therefore be placed directly in the project's tree. To each document can be connected up to ten parameters, setting the links. Items, for which there are not set the links, will be hidden at runtime.

To each document can be set:

• the "Archive length (n)" attribute in need value of the document archive size or in 0 for the dynamic mode;
• the "Archiver (arch)" attribute in need archiver that maintains the specified parameters; you must not use archivers with worse at one day quality;
• the "Report hour (repHour)" attribute in the document report hour — start hour of the day;
• the "Enable graph (enGraph)" attribute for enable/disable the graph;
• the "Title (title)" attribute in the document specific title.

Using — runtime
In the runtime mode, the items, for which links have been set, are displayed. Additionally you can control the display properties of documents, for what there is used the document control panel, which can be called clicking the left mouse button in the document area.

Linking and configuring the attributes

The frame, shown in Figure 1.2, is a template of documents of the dynamic type and it is provided as an example and for building own dynamic documents on it basis. The main specific of that document type is the synchronous generating at the requesting-opening.

The main advantage of this document type is the maximal actuality of the data and the document language, for the multilingual interfaces, that is the possibility of generating for the specified date and time. But this document type has a significant disadvantage, which is the high CPU load and long time of the synchronous generation for big archival data.

Therefore, documents of this type are allowed to use on every types of the interfaces, include the WEB-interfaces, but some documents based on big archival data require for not slow processing systems!

Fig.1.2. The "Document - dynamic" frame in the development mode.

Using — development
The frame can only be used as a basis for creating your own dynamic type documents, for which you should it copy or inherit, by selecting the appropriate option in the copy dialog. Next, you need to edit the document template, in the appropriate attribute, according to the needs of your document, and write your own common generation procedure, if it is not builtin into the document template.

The document, shown in Figure 1.2.1, is provided for generating a report of the instantaneous values in view of the trends diagram and the data table. The document is the dynamic type, so you can specify the data time and depth. The document commonly uses and represents the representative structure of the DAQ-template "Analog signal". As a data source of this document is the value archives of the DAQ-parameters.

Fig.1.2.1. The "Instantaneous values report" document in the runtime mode.

Using — development
The document is designed to perform the role of page-template, and should therefore be placed directly in the project's tree. To each document can be connected up to ten parameters, setting the links. Items, for which there are not set the links, will be hidden at runtime. The default document depth in the past is set at 10 minutes.

To each document can be set:

• the "Enable graph (enGraph)" attribute for enable/disable the graph;
• the "Title (title)" attribute in the document specific title.

Using — runtime
In the runtime mode, the items, for which links have been set, are displayed. Additionally you can control the display properties of documents, for what there is used the document control panel, which can be called clicking the left mouse button in the document area.

Linking and configuring the attributes

The document, shown in Figure 1.2.2, is provided for generating a report of the violations. The document is the dynamic type, so you can specify the data time and depth. The document commonly uses and represents the messages structure "Violations". As a data source of this document is the message archive.

Fig.1.2.2. The "Protocol of violations" document in the runtime mode.

Using — development
The document is designed to perform the role of page-template, and should therefore be placed directly in the project's tree. To each document can be set own messages level and category of the processed violations in the attribute "Message category (messCat)", which is the generic one by default "1:al*:*" and can be specified by the data sources. The default document depth in the past is set at 1 day.

Using — runtime
In the runtime mode, the specified violation messages are displayed. Additionally you can control the display properties of documents, for what there is used the document control panel, which can be called clicking the left mouse button in the document area.

Linking and configuring the attributes

The document, shown in Figure 1.2.3, is provided for generating a report of the user interruptions. The document is the dynamic type, so you can specify the data time and depth. The document commonly uses and represents the messages structure "User-operator actions". As a data source of this document is the message archive.

Fig.1.2.3. The "Protocol of interruptions" document in the runtime mode.

Using — development
The document is designed to perform the role of page, and should therefore be placed directly in the project's tree. The document does not mean any configurations due to the interruption messages are common. The default document depth in the past is set at 1 day.

Using — runtime
In the runtime mode, the user interruption messages are displayed. Additionally you can control the display properties of documents, for what there is used the document control panel, which can be called clicking the left mouse button in the document area.

Linking and configuring the attributes

The document, shown in Figure 1.2.4, is provided for generating a report of different sort messages together, including: "Violations", "User-operator actions" and "System". The document is the dynamic type, so you can specify the data time and depth. The document so commonly uses and represents the messages structures: "Violations", "User-operator actions" and "System". As a data source of this document is the message archive.

The document also provides a simple filtering for selected criteria: "Disabled", "Date and time (dttm)", "Level (lev)", "Parameter (prm)", "Description (dscr)", "Value (alrm)".

• Sponsored by: Ustijancev Michael

Fig.1.2.4. The "Protocol of messages" document in the runtime mode.

Using — development
The document is designed to perform the role of page-template, and should therefore be placed directly in the project's tree.

To each document can be set own level and category of the processed messages in the attribute "Message category (messCat)", which is the generic one by default "1:/^(al|OP|/sub_UI/mod_VCAEngine)/" and can be specified for yourself. Also you can specify the only used archivers by setting the attribute "Archivers list (archLs)". The default document depth in the past is set at 1 day.

Using — runtime
In the runtime mode, the specified messages are displayed. Additionally you can control the display properties of documents, for what there is used the document control panel, which can be called clicking the left mouse button in the document area.

Selecting a filtering criteria and entering text required to presence, the user can see only needed messages.

Linking and configuring the attributes

The document, shown in Figure 1.2.5, is provided for generating a report of the hour values of up to 10 parameters for two working shift of day with the result sum for flows and related parameters. The document is the dynamic type, so you can specify the data time and depth (fixed). The document commonly uses and represents the representative structure of the DAQ-template "Analog signal". As a data source of this document is the value archives of the DAQ-parameters.

• Sponsored by: DIYA Ltd

Fig.1.2.5. The "Report of two working shifts" document in the runtime mode.

Using — development
The document is designed to perform the role of page-template, and should therefore be placed directly in the project's tree. To each document can be connected up to ten parameters, setting the links. Items, for which there are not set the links, will be hidden at runtime.

You must also specify an one-hour archiver in the "Archiver (arch)" attribute that maintains the specified parameters, since this document requires such data. If the start of the first working shift is different from 8 (eighth) hours, then you must specify the required hour in the "Start hour (stH) attribute.

Using — runtime
In the runtime mode, the items, for which links have been set, are displayed. Additionally you can control the display properties of documents, for what there is used the document control panel, which can be called clicking the left mouse button in the document area. Since the document fixes the depth in history at 12 hours (one working shift), the user can only change the document time!

Linking and configuring the attributes

The document, shown in Figure 1.2.6, is provided for generating a year report of the month values in view of the trends diagram and the data table. The document is the dynamic type. The document commonly uses and represents the representative structure of the DAQ-template "Analog signal". As a data source of this document is the value archives of the DAQ-parameters mostly.

The document first introduced the manual entry of archival values of a large measurement time interval, which in this case is a month, as an undetermined interval. This feature is of great relevance for counters that for one reason or another cannot be connected to the system directly, with continuous measurement or periodic uploading of archive parts. Determining the parameter to manual input performs by setting the constant isMan of the appropriate parameter, which enables the form elements at the top of the document under the appropriate rights ("root" or in the "ITW" group), and accessing the data for the table and trend strictly at the interval of the document — month, as well as entering them.

Manually entered data is stored whether traditionally in an archive of values, with only one value recorded per representative interval, that is, with unreliable values between them; or as a separate entry with a value in the message archive, also introduced for the first time by this document:

CATEGORY: defines the source ID SrcID in the form "val{SrcID}", where:

• "val*" — the typical template-sign of a value, that can be directly used in the category filter to determine only the values in messages;
• SrcID — source identifier, what directly entered by a constant in the parameter address var.

TEXT: the parameter Name and Value in the form "{Name}: {Value}".

The message archiver of the module FSArch must be set for the next attributes to correct work perform together this document: set "Prevent duplicates", "Consider duplicates and prevent, for equal time, category, level" and set "Time size of the archive files" to 3660 days. The module DBArch must work without such kind specific.

Fig.1.2.6. The "Year report of the month values" document in the runtime mode.

Using — development
The document is designed to perform the role of page-template, and should therefore be placed directly in the project's tree. To each document can be connected up to ten parameters, setting the links. Items, for which there are not set the links, will be hidden at runtime.

To each document can be set:

• the "Archiver (arch)" attribute in required value and message archiver in the form {ValArch};{MessArch}, these maintain the specified parameters; you must not use archivers with worse at one hour quality for values;
• the "Enable graph (enGraph)" attribute for enable/disable the graph;
• the "Title (title)" attribute in the document specific title.

Using — runtime
In the runtime mode, the items, for which links have been set, are displayed. The year of the document formation is available for selection on the top of this document, from the current year and for ten years in depth.

With the rights ("root" or in the "ITW" group), the user can enter parameter values with the manual entry sign (isMan) using the form elements above, where you can select the month, parameter and value that will be recorded immediately after confirmation and shown in the document.

Linking and configuring the attributes

2 Service related functions

The service functions of the frames of reports and documents are intended to perform the characteristic tasks of obtaining reporting data, for which you need to perform some verification or counting, for example, to check the validity and to summarize. Forming complex data, such as charts embedded in a document, can also be a service function.

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

For connection the library part to a project of the OpenSCADA station you can obtain the database file as:

• supplied with a ready and proper package of the Linux distribution like to "openscada-libdb-main", "openscada-LibDB.Main";
• directly taken for most actual one from the subversion repository and converted to the DB SQLite file in the way:

wget http://oscada.org/svn/trunk/OpenSCADA/data/LibsDB/OscadaLibs.sql
sqlite3 -init OscadaLibs.sql OscadaLibs.db .exit

• downloaded for the one attached here.

This obtained file next you can place into the project directory of the station and create the database object for the DB module "SQLite", registering the database file in the configuration.

Query the value for the specified time (time:uTime) from the assigned archiver archtor (FSArch.1m) and issuing results with the specified number of digits prec after the dot.

The function works with the DAQ-parameter attribute objects to which the archive is attached and the address addr is written to it in full path, like "/DAQ/LogicLev/gen/prm_F3/a_var". For the empty archtor, the request will be made generally to everyone with the archive buffer periodicity!

In the process of obtaining a value, the time of this value may be different from the requested one, if the archive is not currently present and returns the closest value, preventing why you may by setting strong. When you need to get the closest valid value in a controlled way, for counters to example, you have the "tryTo" time argument to which to look for the closest valid value. The time in tryTo may be both lesser and bigger than the request time.

Initially, the result is presented as a string of real value with a certain number of digits prec after the dot, and with the value "Empty" for not valid values, allowing it to be inserted into the document without further processing. However, at requiring of additional processing and specific formatting, the result can be obtained with an unformatted real value, for prec less than 0.

Parameters

Calculate the average value over a specified period of the time [bTime...eTime], for the archiver archtor (FSArch.1m) data and issuing results with the specified number of digits prec after the dot.

The function works with the DAQ-parameter attribute objects to which the archive is attached and the address addr is written to it in full path, like "/DAQ/LogicLev/gen/prm_F3/a_var". For the empty archtor, the request will be made generally to everyone with the archive buffer periodicity!

In the process of calculation, the data in the archive is checked for validity and the value of the percentage of reliable data actPerc that participated in the result is formed. In general, you should use intermediate archivers — medium quality archivers, so that there is not too much data in a given interval to reduce performance, and that it does not have one value at all.

Initially, the result is presented as a string of real value with a certain number of digits prec after the dot, and with the value "Empty" for not valid values, allowing it to be inserted into the document without further processing. However, at requiring of additional processing and specific formatting, the result can be obtained with an unformatted real value, for prec less than 0.

Parameters

Calculate the summary value over a specified period of the time [bTime...eTime], for the archiver archtor (FSArch.1m) data and issuing results with the specified number of digits prec after the dot.

The function works with the DAQ-parameter attribute objects to which the archive is attached and the address addr is written to it in full path, like "/DAQ/LogicLev/gen/prm_F3/a_var". For the empty archtor, the request will be made generally to everyone with the archive buffer periodicity!

In the process of calculation, the data in the archive is checked for validity.

Initially, the result is presented as a string of real value with a certain number of digits prec after the dot, and with the value "Empty" for not valid values, allowing it to be inserted into the document without further processing. However, at requiring of additional processing and specific formatting, the result can be obtained with an unformatted real value, for prec less than 0.

Parameters

Building trends diagram to SVG, which may be builtin next to the XHTML-document, for specified period of the time [(end-size)...end] and from the sources srcs.

• Total complexity: 1.3 HD^[!]
• Sponsored by, for initial implementation on 1.0 HD^[!]: Magomed, SAVTECH

The diagram forming code is based on code of the primitive "Diagram" of the visualisers, and which was quite simply migrated from C++ to the JavaLikeCalc embedded language. Currently, only trends have been moved-implemented!

The appearance of the diagram is determined by its dimensions hsz*vsz and the source SVG-template tmpl, a number attributes of the root tag of which has special meaning and corresponding to the primitive "Diagram":

• Scale: Markers: font (sclMarkFont), by default "Arial 10".
• Scale: horizontal (sclHor), by default "Markers (2)" and generally provided: "No draw (0)", "Grid (1)", "Markers (2)", "Grid and markers (3)".
• Scale: vertical (sclVer), by default "Grid and markers (3)" and generally provided: "No draw (0)", "Grid (1)", "Markers (2)", "Grid and markers (3)", "Grid (log) (5)", "Markers (log) (6)", "Grid and markers (log) (7)".
• Scale: color (sclColor), by default "gray".
• Scale: Markers: color (sclMarkColor), by default "gray".

Currently, only value archives can be used as a data source, either directly to them or through the DAQ-parameter attribute with the archive. The number of data sources is not directly limited and is written in separate lines of the argument srcs in the format "{addr}:{min}:{max}:{color}[:{scale}[:{width}]]", where:

• addr — address to:
  • the value archive ("/Archive/va_CPULoad_load") or the DAQ-parameter attribute ("/DAQ/LogicLev/gen/F3/var");
  • the direct data in the form "<d s='1' aprox='1' per='1'>{p0}={pV0},{p1}={pV1},...,{pN}={pVN}</d>", by set the attribute "s" it will allows the period setting in seconds; "aprox" — approximate the transition from one point to another instead of the previous value to all the periodicity points from the packaging;
• min, max — minimum and maximum of the scale, in the scale absence (min >= max), it will be calculated from the real data;
• color — colour of the trend curve;
• scale — separate definition of the trend scale, by default "Global (0)" and generally provided: "Global (0)", "Markers (2)", "Grid and markers (3)", "Markers (log) (6)", "Grid and markers (log) (7)".
• width — width of the trend curve, by default 2.

Fig.2.4. The function "Diagram" default result in a XHTML-document.

Parameters

/DAQ/LogicLev/gen/F3/var:0:100:#ae77c3:2
/Archive/va_CPULoad_load:0:0:darkcyan:2

<svg xmlns="http://www.w3.org/2000/svg" version="1.1" sclMarkFont="Arial 10" sclHor="2" sclVer="3" sclColor="gray" sclMarkColor="gray">
    <style type="text/css">
	    #scVer rect { stroke: none; }
	    #scVer text { stroke: none; }
	    #scHor rect { stroke: none; }
	    #scHor text { stroke: none; }
	    #drawArea path { fill: none; }
    </style>
    <!--Draw grid and markers-->
    <g id="scVer" />
    <g id="scHor" />
    <!--Curves area -->
    <g id="drawArea" />
</svg>