Version 5.

Logging And Trending Data

Citect Pty Ltd

3 Fitzsimmons Lane
Gordon NSW 2072
Australia
www.citect.com
DISCLAIMER

Citect Pty. Limited makes no representations or warranties with respect to this manual and, to the
maximum extent permitted by law, expressly limits its liability for breach of any warranty that may be
implied to the replacement of this manual with another. Further, Citect Pty. Limited reserves the
right to revise this publication at any time without incurring an obligation to notify any person of the
revision.

COPYRIGHT

© Copyright 2003 Citect Pty Limited. All rights reserved.

TRADEMARKS

Citect Pty Limited has made every effort to supply trademark information about company names,
products and services mentioned in this manual. Trademarks shown below were derived from
various sources.

CitectSCADA, CitectHMI/SCADA, CitectFacilities and CitectSCADA Batch are regisitered

trademarks of Citect Pty. Limited.

IBM, IBM PC and IBM PC AT are registered trademerks of Internatrional Business Machine
Corporation.

MS-DOS, Windows, Windows 98, Windows 2000, Windows XP and Excel are trademarks of
Microsoft Corporation.

dBase is a trademark of Borland Inc.

General Notice:

Some product names used in this manual are used for identification purposes only and may be
trademarks of their respective companies.

October 2003 Edition for CitectSCADA Version 5.5

Manual Revision 1.0

Logging And Trending Data 2

Trending Data

The trend system can provide a better understanding of the performance of your plant and
equipment. It can be used for dynamic visual analysis (trend and SPC graphs), production records,
or for regularly recording the status of equipment for efficiency and preventive maintenance.

Using Trend Tags, you can specify exactly what information you want to collect from your I/O
Device variables. This information can be logged at regular intervals (periodic trend), or only when
an event occurs (event trend). Event trends are used for trending data that is not time-based, for
example, for a product as it comes off an assembly line. Trend data is usually saved on disk for
analysis or displayed on a trend graph.

The trend system is based on real time samples. The trend system expects a return of one data
point each time it samples the data. Although gaps in the data can be filled, you should ensure that
your field device can return data values at the rate you specify (especially if you are using sample
periods of less than 100 ms).

CitectHMI/SCADA can collect and store any amount of data. The only restriction on the amount of
data that you can store is the size of the hard disk on your computer. (CitectHMI/SCADA uses an
efficient data storage method - ensuring that space on your computer's hard disk is maximised.)
For long term storage, you can archive the data to disk or tape (without disrupting your runtime
system). For efficient storage, you should store trend files on a compressed volume.

NOTE: If you are trending data across a network (distributed processing), it is recommended that
you enable time synchronisation using the Computer Setup Wizard.
You might also consider staggering your trend sample requests using the
[Trend]StaggerRequestSubgroups parameter.

¾ To configure a trend tag:

1. From the Tags menu select Trend Tags. Press F2 to view the extended Trend Tag form.
2. Complete the Trends Tags form. Use the Help button for more information about the fields.
3. Press the Add button to append a record you have created, or the Replace button if you have
modified a record.

Logging And Trending Data 3

Trend Tag Properties

Trend Tags have the following properties:

Trend Tag Name (31 Chars.)

The name assigned to the trend data. If the Trend Tag is logging a particular variable, it is
recommended that you use a 16 character name that somehow resembles the 32 character
name of the related Variable Tag. This will mean an association between the two is easily
recognisable.
If you are using Distributed Servers, the name must be unique to the cluster (e.g. you cannot
have the same trend tag name in more than one cluster). The first eight (8) characters of your
Trend tag names must NOT be the same as the first 8 characters of your SPC tag names.

Expression (64 Chars.)

The logged value of the trend tag. You can log individual variables by using a Variable Tag,
for example:

Expression LT131
Logs the Variable Tag LT131
Comment
The value of the process variable LT131 is logged. Variable LT131 must be defined as a
variable tag.
You can also log any Cicode expression or function, for example:

Expression LT131/COUNTER
Logs Variable Tag LT131 divided
Comment by the Variable Tag COUNTER

NOTE: When a variable tag is used in the expression field of a trend tag property, the 'Eng Zero
Scale' and 'Eng Full Scale' fields of that variable tag must be set appropriately, or data
will be lost because the trend logs negative values as invalid.

Trigger (64 Chars.)

The Cicode expression (or variable tag) that triggers data logging, for example:

Trigger LT131<50
In this example, logging occurs when the value of the variable tag (LT131) falls below 50.
For a periodic trend, data is logged only while the value of the trigger is TRUE. (The trend
graph will still scroll, but will display <GATED> where the trigger is FALSE.) In the above
example, data is logged continuously while the value of LT131 remains less than 50. Logging
ceases when the value rises to (or above) 50. Logging does not occur again until the value of
LT131 falls below 50.
You do not have to specify a trigger for a periodic trend. If you do not specify a trigger for a
periodic trend, logging occurs continuously.
For an event trend, data is logged once when the value of the trigger changes from FALSE to
TRUE. In the above example, one sample is logged when the value of LT131 first becomes
less than 50. Another sample is not logged until the value of LT131 rises to (or above 50) and
again falls below 50.

Logging And Trending Data 4

Sample Period (16 Chars.)
The sampling period of the data. You can either enter a period of your own, or select one from
the drop-down box.
Sampling periods of greater than one second should be entered in hh:mm:ss
(hours:minutes:seconds) format. If you enter a single digit, without the colon (:), it will be
considered a second. For example, if you enter 2, it will be interpreted as 2 seconds.
Sampling periods of less than one second must be entered as decimals. For example, to
enter a period of 200 milliseconds, you would enter 0.2.
If the sample period is less than one second, then one second must be divisible by the period
(to give an integer). For example, a sample period of 0.05 is valid, because 1/0.05 = 20,
whereas a sample period of 0.3 is not valid because 1/0.3 = 3.333. . .
NOTE: 1) Your I/O Device must be capable of providing data at the specified rate, otherwise
gaps will appear in the trend data and/or the hardware alarm Trend has missed
samples will be evoked. You can fill gaps in the file and graph using the
[Trend]GapFillTime parameter. Gaps in the graph only can be filled using the
TrnSetDisplayMode() function.
2) If trends with a sample period of less than a second are shared by a number of
clients across a network (distributed processing), it is recommended that you enable
time synchronisation using the Computer Setup Wizard.
CitectHMI/SCADA checks the Trigger each sample period. If the Trigger is TRUE (or has just
changed from FALSE to TRUE, in the case of event trends), CitectHMI/SCADA logs the value
of the Expression.
Examples:

Sample Period 30
Logs data every 30 seconds
Comment

Sample Period 10:00

Logs data every 10 minutes
Comment

Sample Period 10:00:00

Logs data every 10 hours
Comment

Sample Period 2:30:00

Logs data every 2 and a half
Comment hours
The sampling period of the fastest trend on the page is taken as the default value for the
display period of the page.
This property is optional. If you do not specify a sample period, the sampling period defaults to
10 seconds.
NOTE: If you edit this property in an existing project, you must delete the associated trend files
- before you run the new runtime system. (For location of the trend files, see File
Name.)

Logging And Trending Data 5

 Type (32 Chars.)
The type of trend:
1 TRN_PERIODIC
2 TRN_EVENT
3 TRN_PERIODIC_EVENT

Comment (48 Chars.)

Any useful comment.

NOTE: The following fields are implemented with extended forms (press F2).

File Name (64 Chars.)

The file where the data is to be stored. You must specify the full path or use path substitution.
When CitectHMI/SCADA collects data from your plant floor, it stores the data in a file on the
hard disk of your computer. When CitectHMI/SCADA subsequently uses the data to display a
trend or SPC graph, it reads the data from this file. (CitectHMI/SCADA uses a separate file for
each trend tag.)
By default, CitectHMI/SCADA stores the file in the \CITECT\DATA directory on the hard disk
where you installed CitectHMI/SCADA. The default name of the file is the first eight characters
of the trend tag name. However, you can specify an alternate file name. If you do specify a
file name, you can specify the full path, for example:

File Name C:\DATA\TRENDS\TANK131

or use the path substitution string:

File Name [DATA]:TANK131

where [DATA] specifies the disk and path for the data. Use path substitution to make your
project more ‘portable’.

NOTE: 1) With CitectHMI/SCADA Versions 5.xx, it is not possible to store trend files in the
Bin, Runtime, Backup or User directories; or any subdirectories of these. If you have
existing Version 3.xx or 4.xx projects that use these directories to store trend files, the
path for these will have to be changed to the Data directory.
2) The trend system will buffer the acquired data before saving it to a file. The
[Trend]CacheSize parameters determine the buffer sizes for returned data.
The File Name property is optional. If you do not specify a file name, the file name defaults to
\CITECT\DATA\<Name> on the hard disk where you installed CitectHMI/SCADA. <Name> is
the Trend Tag Name. If you do use this property, you should ensure that no other trend tags
have the same name, otherwise the data may be lost.
NOTE: 1) Do not use a file extension when specifying a file name. If you edit this property
(change the file name or path) in an existing project, all existing SPC data is ignored.
2) This file name must be different to your SPC tag file names.

Storage Method
Select either Scaled or Floating Point as the storage method for the trend. The key difference
between these two options is that Scaled is a two-byte data storage method, whereas Floating
Point uses eight bytes.
Floating Point storage has a dramatically expanded data range in comparison to Scaled
storage, allowing values to have far greater resolution. However, you need to consider that it
also uses a lot more disk space. Scaled should be used where compatibility with pre-V5.31
trend history files is required.
If you do not specify a storage method, it is set to Scaled by default.

Logging And Trending Data 6

 NOTE: If you edit this property in an existing project, you must delete the associated trend files
- before you run the new runtime system. (For location of the trend files, see the File
Name.)

Privilege (16 Chars.)

The privilege required by an operator to display the trend data on a trend.

Area (16 Chars.)

The area to which the trend data belongs.

Eng Units (8 Chars.)

The engineering units of the variable/expression being logged. The engineering units are
used by the trend scales and trend cursor displays.

Format (10 Chars.)

The format of the variable/expression being logged. The format is used by the trend scales
and trend cursor displays.
This property is optional. If you do not specify a format, the format defaults to ####.#.

No. Files (4 Chars.)

The number of history files stored on your hard disk (for this tag).
If you do not specify the number of files, 2 history files are stored on your hard disk. The
maximum number of files you can specify per trend tag is 270.
NOTE: If you edit this property in an existing project, you must delete the associated trend files
- before you run the new runtime system. (For location of the trend files, see the File
Name.)

Time (32 Chars.)

The time of day to synchronise the beginning of the history file, in hh:mm:ss
(hours:minutes:seconds).
If you do not specify a time, the file is synchronised at 0:00:00 (i.e. midnight).
NOTE: If you edit this property in an existing project, you must delete the associated trend files
- before you run the new runtime system. (For location of the trend files, see the File
Name.)

Period (32 Chars.)

The period of the history file, in hh:mm:ss (hours:minutes:seconds). Alternatively, you can:
„ Specify a weekly period by entering the day of the week on which to start the history file,
e.g. Monday, Tuesday, Wednesday, etc.
„ Specify a monthly period by entering the day of the month on which to start the history file,
e.g. 1st, 2nd, 3rd, 4th, 5th, etc.
„ Specify a yearly period by entering the day and the month on which to start the history file,
e.g. 1st January, 25th February, etc. The day and month must be separated by a space.
If you do not specify a period, the period defaults to Sunday (weekly).
NOTE: If you edit this property in an existing project, you must delete the associated trend files
- before you run the new runtime system. (For location of the trend files, see File
Name.)

Logging And Trending Data 7

Trend Graphs

A trend graph is a visual representation of past and current activity. It provides an effective way of
displaying plant-floor data. It builds a picture over time of how a variable (such as product output,
level, temperature, etc.) is changing or how a device or process is performing. You can monitor
current activity as it happens and scroll back through time to view the trend history.

As the values of variables change over time, or as events happen, the graph moves across the
page. The latest values are always displayed. You can scroll back through historical data to
display past values of the variable (or process).

You can trend any single variable or Cicode expression. You can display any number of trends on
the screen simultaneously, even if they have different sample periods. You can also display up to
eight trend tags (pens) in any trend window.

Historical data collection continues even when the display is not active. You can switch between
pages without affecting trend graphs. Trend data acquisition and storage of data (in trend history
files) continues even when the display is not active.

You can use the following standard trends:

„ A single full page trend, where one trend window displays on a graphics page.
„ A double full page trend, where two trend windows display on a graphics page.
„ A zoom trend with two trend windows and added functionality for zooming.
„ A pop-up trend that you can 'pop up' anywhere (in a separate window) on your computer
screen.
„ User-defined trends that you can position anywhere on any graphics page.

NOTE: Variable tags can also be visually trended using an SPC Control Chart. Statistical
Process Control (SPC) is a facility that enables you to control the quality of materials,
manufactured products, services, etc. This quality control is achieved by collecting,
arranging, analysing, and testing sampled data in a manner that detects lack of uniformity
or quality.

Creating Trend Pages

You can use any of the pre-defined trend templates for your trend pages, or use a pre-defined
template to produce your own trend templates. You can draw a trend background (such as
gridlines) on your trends.

To create multiple trend pages, you can either:

„ Create a trend page for each set of trends to display in the runtime system.
„ Create a single trend page and use the PageTrend() function to display trends as required.
With this function, you can display all the trends in the system with a single trend page
. Create the trend page with the Graphics Builder, and set all the pen names to blank. You then
display that page by calling this function and passing the required trend tags (up to 8). You
should call the PageTrend() function from a menu of trend pages.

Logging And Trending Data 8

Trend Interpolation

Trend interpolation is used to define the appearance of a trend graph when the incoming samples
fall out of sync with the display period or when samples are missed.

For example, a particular trend may be sampled five times between each update of the trend graph.
As only one value can be displayed for each update, a single value must be used that best
represents the five samples; and that could be the highest value, the lowest value, or an average.

To define how CitectHMI/SCADA calculates the value to use, you have to set a particular Trend
Interpolator Display Method.

The following table shows the available interpolator display methods, grouped into condense
methods (where the display period is longer than the sample period) and stretch methods (where
the display period is less than or equal to the sample period).

Condense methods Stretch methods

Average (default) - this displays Step (default) - This method
the average of the samples simply displays the value of the
within the previous display most recent sample.
period
Minimum - This displays the Ratio - This method uses the
lowest value that occurred ratio of sample times and
during the previous display values immediately before and
period. after the requested time to
interpolate a "straight line"
value.
Maximum - This displays the Raw Data - This method
highest value that occurred displays the actual raw values.
during the previous display
period.

The interpolation display method is set via TrnSetDisplayMode() function. You can also use the
[Trend]GapFillMode parameter, but it will interpolate values within the actual trend file as well as on
the trend graph.

Logging And Trending Data 9

¾ To configure a trend page:
1. Click on the New Page
tool.

- or -
1. From the File menu select New
2. Select Type: Page
3. Choose the Resolution (size) of the trend page.
4. Choose a trend Template for the trend page:
Singletrend One trend on the page
Doubletrend Two trends on the page
Eventtrend One event trend on the page
Zoomtrend Two trends on the page (one window for zooming)
Poptrend A single trend on the page (for display in a pop-up window)
5. Click on the OK button.

Logging And Trending Data 10

Printing and Exporting Trend Data
Printing Trend Data

You can print trend data using the following functions:

Function Purpose

TrnPrint Prints a trend that is displayed on the

screen.
TrnPlot Prints a plot of one or more trend
tags.
TrnComparePlot Prints two trends (one overlaid on the
other), each of up to four trend tags.
WinPrint Prints the active window

The standard trend templates have buttons that call these functions to print data - .

When you print using the TrnPrint function, the Plot Setup form will display. This form allows you to:
„ Specify the title of the trend.
„ Add a comment which is displayed beneath the title.
„ Specify whether the trend is going to print in black and white, or in colour. The selection that
you make here will become the setting for the [General]PrinterColourMode parameter.
„ Define your printer setup. The printer that you select here will be set as the default printer at
the [General]TrnPrinter parameter.
„ Specify whether or not the form displays the next time the function is used. This check box
sets the [General]DisablePlotSetupForm parameter.
Exporting Trend Data

You can export trend data to reports and databases with the following functions:

Function Purpose

TrnGetTable Retrieves trend information and stores it

in a Cicode array
TrnExportClip Copies trend data to the clipboard
TrnExportCSV Copies trend data to a CSV file
TrnExportDBF Copies trend data to a DBF file

The standard trend templates have buttons that call these functions to export data.

NOTE: You can also select part of your trend graph (click and drag) and copy the underlying
values to the Windows clipboard. You can then paste them into an Excel spreadsheet. (If
you are pasting millisecond values, you will need to create a custom format for the TIME
column to display these values correctly. To do this, select the column and select Format |
Cells. In the Number tab, select Custom for Category, and type h:mm:ss.000 AM/PM.)

Logging And Trending Data 11

Using Trend History Files

When CitectHMI/SCADA starts up for the first time, it creates all the trend files required by each
trend tag in the runtime system. (You can change this default using the [Trend}AllFiles parameter.)

CitectHMI/SCADA uses a system of rotational history files to store the trend data. Data is stored in
several files rather than in a single large file.

By default, CitectHMI/SCADA uses 2 files (for each trend tag). You can change the default by
specifying the number of files to use, for example:

No. Files 10
Use ten files for the data, as in the
Comment following diagram:

Tag Tag
name name
1. When Citect begins logging,
.010 .001 data is written to the first file
Tag Tag 2. At midnight the
name name following Sunday,
.009 .002 Citect writes to the
second file
4. After week 10 the
Tag first file is overwritten Tag 3. At midnight the
name name
.008
with new data following Sunday,
.003
Citect writes to the
third file and so on
Tag Tag
name name
.007 .004
Tag Tag
name name
.006 .005

The maximum number of files you can specify per trend tag is 270.

You can also specify the period between files, i.e. when a new history file is used, for example:

Period 1:00:00
Use a new file each hour
Comment

Period 6:00:00
Use a new file every six hours
Comment

Period 72:00:00
Use a new file every three days
Comment

Period Monday
Use a new file each week beginning on
Comment Monday

Logging And Trending Data 12

 Period 15th
Use a new file every month beginning on
Comment the 15th of each month

Period 25th June

Use a new file every year beginning on
Comment the 25th of June

You can also specify the time of day to synchronise the start of the history file, for example:

Time 6:00:00
Synchronise the file at 6:00 am
Comment

Time 12:00:00
Synchronise the file at 12:00 midday
Comment

Time 18:30:00
Synchronise the file at 6:30 pm
Comment

Storage method

CitectHMI/SCADA allows you to select which storage method you want to use for Trend tags and
SPC tags. You are given a choice of either Scaled or Floating Point, the key difference being that
Scaled represents a two-byte data storage method, whereas Floating Point uses eight bytes,
delivering far greater precision.

Floating Point storage has a dramatically expanded data range in comparison to Scaled storage,
allowing values to be more precise. However, you need to consider that it also uses a lot more disk
space. Scaled should be used where compatibility with pre-V5.31 trend history files is required.

You can set the required storage method via the Trend Tag or SPC Tag properties form (press the
F2 key to view the extended form). The storage method is set to Scaled by default.

Calculating Disk Storage

The following equations allow you to calculate the total disk space required to store a trend across a
specified period of time.
Note that the storage method used for a trend (Scaled or Floating Point) affects the number of bytes
required for each sample, so it is important to base your calculations on the appropriate formula.
To find out which storage method a particular trend is using, refer to the extended Trend Tag
Properties dialog. (By default, the Scaled storage method is used.)

Scaled
Each data sample requires two bytes of storage. You can therefore calculate the total disk storage
required for each trend by using the following formula:

Logging And Trending Data 13

 ( )
File Period (secs) x (No.Files) x 2
Bytes reqd = 464 x No. Files + 176 +
for each Sam ple Period
trend (secs)

For example, if a trend record produces one sample every ten seconds for one week, and you are
using five data files (five weeks), the number of bytes required is:

( )
(7 x 24 x 60 x 60) x 5 x 2
Bytes required = 464 x 5 + 176 +
10
= 607296 bytes

Floating Point
Each data sample requires eight bytes of storage. This alters the equation to:

( )
Period (secs) x (No.Files) x 8
Bytes reqd = 704 x No. Files + 160 +
for each Sam ple Period
trend ( )

The number of bytes required then becomes:

( )
(7 x 24 x 60 x 60) x 5 x 8
Bytes required = 704 x 5 + 160 +
10
= 2422976 bytes

Note that the calculations above do not take into account the space required to store the history file
for each trend. This is because these files remain at a set size and therefore do not significantly
impact the amount of disk space required.

NOTE: For efficient trends storage, you can use Windows NT file compression. Customers have
reported getting files down to 10% of their original size using this method, though the
actual amount of compression varies depending on the rate of change of the data.

Reconfiguring History Files

If you change the configuration of your trend history files (in an existing project), or you change the
configuration of a trend tag that affects the number, time, or period of the trend files, you must delete
all the existing trend files - before you run the new system.

If you change the path of your trend history files (in an existing project), all existing trend data is
ignored.

NOTE: You must not delete history files (that CitectHMI/SCADA creates) from your hard disk -
while your system is running.

Logging And Trending Data 14

Using Path Substitution

Instead of specifying the full path to data files in your system, you can use path substitution.

With path substitution, you define a name that is a substitution for the full directory path. You can
then use the substitution name in the following format:

File Name [SUBSTITUTION]:<filename>

For example, if you decide to store a trend data file called MYFILE in a directory called
C:\CITECT\DATA\MYTRENDS, you can specify the full path to the file, for example:

File Name C:\CITECT\DATA\MYTRENDS\MYFILE

or define a path substitution (for example MYDATA) and specify the path as:

File Name [MYDATA]:MYFILE

Path substitution provides greater control of data storage. You can change the location of all data
files by changing the definition of the data path - instead of locating and changing each occurrence
of the data path.
Default Path Definitions

CitectHMI/SCADA has the following predefined path substitutions:

Path Name Default Directory

Bin \CITECT\BIN
Data \CITECT\DATA
User \CITECT\USER
Run The current project directory
Copy The current copy project directory
Back The current backup project directory

Logging And Trending Data 15