e-terracontrol Reference Manual:

User Interface Applications

This document describes modeling and configuring the user interface applications that
are provided as a part of e-terracontrol.

Software Version: e-terracontrol 3.9

Document Date: December 9, 2015
Copyright and Proprietary Information

Copyright © 2015 ALSTOM Grid Inc. or Affiliate. All Rights Reserved.

NOTE: CONTAINS PROPRIETARY INFORMATION OWNED BY ALSTOM GRID INC. AND/OR ITS
AFFILIATES. DO NOT COPY, STORE IN A RETRIEVAL SYSTEM, REPRODUCE, DISTRIBUTE,
TRANSMIT OR DISCLOSE TO ANY THIRD PARTY WITHOUT PRIOR WRITTEN PERMISSION FROM
ALSTOM GRID INC.
__________________________________________________________________

Trademarks

“ESCA” and “HABITAT” are registered trademarks of ALSTOM Grid Inc. “eterra” is a registered
trademark and/or service mark of E-Terra, LLC, licensed for use by ALSTOM Grid Inc. in connection with
its e-terra family of products and services.

Other product and company names in these materials may be trademarks or registered trademarks of
other companies, and are the property of their respective owners. They are used only for explanation and
to the respective owners’ benefit, without intent to infringe.
Contents
About This Document .............................................................................................. vii
Purpose of This Document ........................................................................................... vii
Who Should Use This Document ................................................................................. vii
Structure of This Document ......................................................................................... vii
For More Information................................................................................................... viii
Conventions .................................................................................................................. x
Change Summary ......................................................................................................... x

1. Measurement History Application ........................................................................ 1

1.1 Measurement History User Interface....................................................................... 1
1.2 Viewing Historical Data ........................................................................................... 2
1.3 Setting the Default Database and Directory ............................................................ 3
1.4 Exporting History to a File ....................................................................................... 3

2. Sequence of Events Applications ......................................................................... 5

2.1 SOE Compiler ......................................................................................................... 5
2.1.1 SOE Compiler Command-Line Arguments ........................................................ 5
2.1.1.1 Exit on Completion ........................................................................................ 6
2.1.1.2 File Path ........................................................................................................ 6
2.1.1.3 File Name Customization .............................................................................. 6
2.1.1.4 Working Folder Path ..................................................................................... 7
2.1.1.5 Fixed-Length Point Names ........................................................................... 7
2.1.1.6 Exclusion of Invalid Time Records ................................................................ 7
2.1.1.7 Analog Limit Excursion Files ......................................................................... 7
2.1.1.8 Log File Size ................................................................................................. 8
2.1.1.9 Intermediate File Storage .............................................................................. 8
2.1.1.10 Period of Work Session .............................................................................. 8
2.1.1.11 Time Base ................................................................................................... 8
2.1.1.12 File Cleanup ................................................................................................ 8
2.1.1.13 Diagnostics ................................................................................................. 9
2.1.1.14 Three-State Point Processing ..................................................................... 9
2.1.1.15 SOE Event Archival .................................................................................. 10
2.1.1.16 SXBIT Field Processing ............................................................................ 10
2.1.1.17 SCADA Server Listen Port ........................................................................ 10
2.1.2 Starting the SOE Compiler Using the Process Starter ..................................... 10
2.1.3 SOE Compiler Dialog Box ................................................................................ 11
2.1.3.1 Menu Bar .................................................................................................... 12
2.1.4 Work Orders..................................................................................................... 12
2.2 SOE and ALE Viewers .......................................................................................... 13
2.2.1 SOE Viewer/ALE Viewer Command-Line Arguments ...................................... 13
2.2.1.1 File Path ...................................................................................................... 14
2.2.1.2 User Interface Refresh Period..................................................................... 14
2.2.1.3 Log Level Filter ........................................................................................... 14
2.2.1.4 Log File Size ............................................................................................... 15

Proprietary – See Copyright Page iii

 2.2.1.5 Time Filter Selection ................................................................................... 15
2.2.2 Starting the SOE and ALE Viewers Using the Process Starter ........................ 15
2.2.3 Loading SOE Files ........................................................................................... 16
2.2.4 Settings Menu .................................................................................................. 16
2.2.5 SOE (and ALE) Viewer User Interface ............................................................. 17
2.2.5.1 SOE Viewer User Interface - SOE Data Tab .............................................. 17
2.2.5.2 SOE Viewer User Interface - Log Tab......................................................... 19
2.2.5.3 SOE Viewer User Interface - Files Tab ....................................................... 20

3. Simulator Application .......................................................................................... 22

3.1 Simulator User Interface ....................................................................................... 23
3.2 Simulator Menu Bar .............................................................................................. 24
3.3 Create Toolbar ...................................................................................................... 25
3.4 Simulator Options Dialog Box ............................................................................... 26
3.5 Debug Output Window .......................................................................................... 26

4. SMP Display Linker Application ......................................................................... 28

4.1 SMP Display Linker Command-Line Parameters .................................................. 28
4.2 SMP Display Linker User Interface ....................................................................... 29
4.3 Using the SMP Display Linker ............................................................................... 29

5. Virtual Chart System ............................................................................................ 31

5.1 Creating a Chart Configuration Text File ............................................................... 31
5.2 Virtual Chart System Command-Line Arguments.................................................. 32
5.3 Starting the Virtual Chart System Using the Process Starter ................................ 32
5.4 Starting the Virtual Chart System Using a Windows Shortcut ............................... 34
5.5 Virtual Chart System Display Window ................................................................... 35
5.6 Virtual Chart System User Interface ...................................................................... 36
5.6.1 Menu Bar ......................................................................................................... 37
5.6.2 Chart Configuration Dialog Box ........................................................................ 38
5.6.2.1 Layout Tab .................................................................................................. 39
5.6.2.2 Colors Tab .................................................................................................. 41
5.6.2.3 Points Tab ................................................................................................... 42
5.6.2.4 Scales Tab .................................................................................................. 43
5.6.2.5 Limits Tab ................................................................................................... 45
5.6.2.6 Time Range Tab ......................................................................................... 46
5.6.2.7 Miscellaneous Tab ...................................................................................... 47

6. Alarm Viewer Application .................................................................................... 49

6.1 Alarm Viewer User Interface Overview ................................................................. 50
6.1.1 Query View ...................................................................................................... 50
6.1.2 Results View .................................................................................................... 52
6.1.2.1 Pasting Events into Microsoft Excel ............................................................ 53
6.2 Alarm Viewer Startup ............................................................................................ 53
6.3 Performance Considerations ................................................................................. 54
6.4 Configuration ......................................................................................................... 54
6.4.1 Required Configuration .................................................................................... 54

Proprietary – See Copyright Page iv

 6.4.2 Redundancy Configuration............................................................................... 55
6.4.3 Permission Configuration ................................................................................. 55
6.4.4 Optional Configuration ..................................................................................... 55
6.4.5 Miscellaneous Configuration ............................................................................ 57
6.5 Alarm Viewer Operations ...................................................................................... 57
6.5.1 Save Query ...................................................................................................... 57
6.5.2 Load Query ...................................................................................................... 58
6.5.3 Save Preferences ............................................................................................ 59
6.5.4 Set Font ........................................................................................................... 59
6.5.5 Clear Cache ..................................................................................................... 59
6.5.6 Command Interface (e-terrabrowser Only) ...................................................... 59
6.6 Alarm Viewer Printing ............................................................................................ 60
6.7 e-terrabrowser Integration .................................................................................... 60
6.8 Alarm Viewer Help System.................................................................................... 60
6.9 Archive File Management ..................................................................................... 60
6.9.1 Archive File Loading......................................................................................... 61
6.9.2 Archive File Publishing ..................................................................................... 61

Appendix A. Configuring Rsync for Use with Alarm Viewer ................................ 63

A.1 Rsync Scheduled Task ......................................................................................... 63

Figures
Figure 1. Measurement History User Interface ................................................................ 1
Figure 2. SOE Compiler Dialog Box .............................................................................. 11
Figure 3. Work Orders Dialog Box ................................................................................ 12
Figure 4. Work Order Process Flow .............................................................................. 13
Figure 5. SOE Viewer User Interface - SOE Data Tab .................................................. 17
Figure 6. SOE Viewer User Interface - Log Tab ............................................................ 19
Figure 7. SOE Viewer User Interface - Files Tab .......................................................... 20
Figure 8. Simulator Main Window - Tree View .............................................................. 23
Figure 9. Simulator Main Window with Create Toolbar Showing ................................... 25
Figure 10. Simulator Options Dialog Box ...................................................................... 26
Figure 11. Simulator Debug Output Window ................................................................. 26
Figure 12. SMP Display Linker User Interface .............................................................. 29
Figure 13. Properties Dialog Box - Shortcut Tab ........................................................... 34
Figure 14. Illustration of a Typical Trend ....................................................................... 35
Figure 15. Virtual Chart System Display Window - Printing Defaults............................. 36
Figure 16. Chart Configuration Dialog Box - Layout Tab ............................................... 39
Figure 17. Chart Configuration Dialog Box - Colors Tab ............................................... 41
Figure 18. Chart Configuration Dialog Box - Points Tab................................................ 42
Figure 19. Chart Configuration Dialog Box - Scales Tab ............................................... 43
Figure 20. Chart Configuration Dialog Box - Limits Tab ................................................ 45
Figure 21. Chart Configuration Dialog Box - Time Range Tab ...................................... 46
Figure 22. Chart Configuration Dialog Box - Miscellaneous Tab ................................... 47

Proprietary – See Copyright Page v

Figure 23. Alarm Viewer Main Screen ........................................................................... 50
Figure 24. Event Details Window .................................................................................. 53
Figure 25. Save Query Dialog Box ................................................................................ 58
Figure 26. Load Query Dialog Box ................................................................................ 58
Figure 27. Archive Web Server Configuration ............................................................... 62

Proprietary – See Copyright Page vi

About This Document
This document is supplied as a part of Alstom Grid’s e-terracontrol product.

Purpose of This Document

This document is intended for use as follows:
• To introduce the reader to the user interface applications that are provided with
e-terracontrol, which include the Measurement History application, the Sequence of
Events (SOE) Compiler and SOE Viewer applications, the Simulator application, the
SMP Display Linker application, the Virtual Chart System (VCS), and the
Alarm Viewer application.
• To provide configuration and modeling information for the user interface applications

Who Should Use This Document

This document is intended for all users of e-terracontrol.

Structure of This Document

This document is structured in the following manner:
• Chapter 1 provides information about configuring and using the Measurement
History application.
• Chapter 2 provides information about configuring and using the SOE Compiler and
SOE Viewer applications.
• Chapter 3 provides information about configuring and using the Simulator
application.
• Chapter 4 provides information about configuring and using the SMP Display Linker
application.
• Chapter 5 provides information about configuring and using the Virtual Chart
System.
• Chapter 6 provides information about configuring and using the Alarm Viewer
application.
• Appendix A describes how to configure Rsync for use with the Alarm Viewer
application.

Proprietary – See Copyright Page vii

For More Information
For more information about configuring and modeling e-terracontrol, refer to the
following:
• e-terracontrol Reference Manual: Introduction and Configuration: Features non-
specific application configuration issues such as client- server architecture,
redundancy, and line switching.
• e-terracontrol Reference Manual: Applications: Describes the modeling and
configuration activities for the principal applications: SCADA Server and Process
Starter; and the ancillary applications: Alarm Logger, Alarm Pager, Automatic
Database Update, Change Data Source, Copy History, Space Saver, and Validator.
• e-terracontrol Reference Manual: Interfaces to Field Devices: Features applications
designed to retrieve measurements from field devices such as Remote Terminal
Units (RTUs), Programmable Logic Controllers (PLCs), and Intelligent Electrical
Devices (IEDs). These applications include CFE Reader, CFE Performance Driver,
OPC DA Client, PLC Reader (Modbus Reader and TI Reader), TrueTime Reader,
and Relay Reader.
• e-terracontrol Reference Manual: Interfaces to External Systems: Features
applications designed to communicate with external systems such as EMS, DCS, or
other SCADA systems. These applications include ADO/SMP, DDEML/SMP,
InterSite Data, Modbus/SMP, OPC DA Server, PI/SMP, ICCP, and XX/SMP.
For other information about e-terracontrol, refer to the following:
• e-terracontrol Release Notes
• e-terracontrol Programmer’s Guide: Describes the interfaces that allow external
processes to communicate with e-terracontrol.
• e-terracontrol Protocol Modeling Guide: Provides modeling details for the
e-terracontrol protocol implementations that are supported in the CFE Reader
application.
• e-terracontrol Display Builder Guidelines: Explains the features and capabilities of
e-terracontrol–based e-terrabrowser displays. It should be helpful to anyone
seeking to build e-terracontrol displays.
For more information about e-terrabrowser, refer to the following:
• e-terrabrowser Software Installation and Maintenance Guide: Provides information
about and instructions for the configuration of the e-terrabrowser Viewer application.
• e-terrabrowser User’s Guide: Provides a guide to the use of e-terrabrowser, the
Web technology–based version of e-terrahabitat’s user interface processor and
command language.

Proprietary – See Copyright Page viii

For more information about designing displays for viewing in e-terrabrowser, refer to the
following:
• Display Builder User’s Guide: An introduction to the concepts, features, and
components of the Display Builder software, including instructions for how to use the
Display Builder software to build displays and how to define display components for
viewing in e-terrabrowser.
For more information about the e-terracontrol/ICCP application, refer to the following:
• e-terracontrol/ICCP User’s Guide: Modeling: Provides instructions for the modeling
of the e-terracontrol/ICCP application.
• e-terracontrol/ICCP User’s Guide: Real-Time Operation: Provides information about
and instructions for the operation of the e-terracontrol/ICCP application.
• e-terracontrol/ICCP Release Notes
For more information about RTUMMU, refer to the following:
• RTU Miscellaneous Message Utility User’s Guide: Details the use of and user notes
for the Remote Terminal Unit Miscellaneous Messages Utility (RTUMMU).
For more information about security configuration aspects of the XX/SMP application,
refer to the following:
• ProtocolPak Security Configuration User’s Guide: Provides information about the
configuration of the xx2smp application for use in secure networks.

Proprietary – See Copyright Page ix

Conventions
The following conventions are used throughout this document. Commands that are
specific to an operating system are shown with the corresponding prompt symbol.

Command Prompts
Operating Prompt Description
System
Linux % All commands preceded by a percent sign prompt
(%) are issued from a Linux terminal window. Note
that all Linux commands are case sensitive.
Windows > All commands preceded by a greater than sign
prompt (>) are issued from a Windows command
line window.
All Operating The absence of any prompt character before a
Systems command indicates that the command is valid on
all operating systems.

Command Strings
Operating Delimiter Description
System
Linux Italics Text in italics indicates information you must
supply. (*)
Linux [] Text enclosed in square brackets "[ ]" indicates
optional qualifiers, arguments, or data. (*)
All Operating Select When used in command strings, the term “Select”
Systems means placing the pointer over the specified item
and pressing the left (default) mouse button.
(*) Note: All Linux commands are case sensitive and must be typed exactly as
shown.

Change Summary
The following changes were made to this document for e-terracontrol 3.9:
• Added section 2.1.1.17 SCADA Server Listen Port.
• Minor editorial and formatting corrections.

Proprietary – See Copyright Page x

1. Measurement History Application
The Measurement History application displays historical analog, status, and
accumulator data contained in history (.his) files created by the SCADA application.
Using the Ending and For text boxes, you can precisely modify the window of time
displayed. After viewing the history, you can choose to print a hard copy of the
information, or you can save the information to a comma-separated-value (.csv) file or a
text (.txt) file.
History files are automatically created every hour, and they are stored in the same
directory as the SCADA database (.sdb) files. History files are fully self-contained, and
they can be copied to another directory or a PC.
This application runs on the server/host or client machine.

1.1 Measurement History User Interface

Figure 1. Measurement History User Interface

The Measurement History user interface includes the following items:

• Database Name: Enter the name of the desired database. If you do not know the
name of the database, click Browse to locate it using the .his file listing.
• Directory: Enter the path to the database.
• Browse: Click this button to find the location of the desired SCADA database. A
standard Windows File Open dialog box is displayed. Select any history file for the
desired database and click Open; the file date is irrelevant. Once the desired history

Proprietary – See Copyright Page 1 Measurement History Application

e-terracontrol Reference Manual: User Interface Applications
 file is located and opened, both the Database Name and Directory text boxes are
filled in (see section 1.3 Setting the Default Database and Directory).
• Provider: Select SCADA (OLE DB) if using the .his files generated by the SCADA
Server application. Select Other if using a .csv file.
• Get History: Click this button to retrieve the measurement history for the specified
date and time. (Before you use this function, you must use the Get Names function.)
The historical measurement values appear in the right column.
• Print History: Click this button to print the measurement history for the specified
date and time. The Print History button is only visible after the Get History function
has been selected.
• Ending: Enter the end date and time for the history measurement to be retrieved.
• For: Enter the time period for viewing history. The time is local-dependent. This is
the amount of time that the Measurement History application counts backward from,
in order for the Ending time to compile historical data. Select Hours or Minutes.
• Get Names: Click this button to view the names of the measurements whose data
changed before the specified end time. Select one of the following filters:
– All: Select to view all measurement types.
– Analog: Select to view only analog measurements.
– Status: Select to view only status measurements.
– Accumulator: Select to view only accumulator measurements.

1.2 Viewing Historical Data

Historical data can be viewed by implementing the following procedure:
1. Start the Measurement History application.
2. Enter the database name and directory for the desired history (*.his) file.
If you are unsure of the location of the desired file, click Browse to locate it (this step
may not be necessary if the Measurement History application was launched with a
pre-configured Windows shortcut).
3. Enter the ending date and time for the desired history segment.
This should be at least one minute in the past, because SCADA may not have
flushed the history to disk during the last minute.
4. In the For text box, enter the duration of the desired history segment.
5. Select one of the measurement filtering options: All, Analog, Status, or Accumulator
(see section 1.1 Measurement History User Interface).
6. Click Get Names.
7. Click Get History.

Proprietary – See Copyright Page 2 Measurement History Application

e-terracontrol Reference Manual: User Interface Applications
1.3 Setting the Default Database and Directory
To avoid typing in the database name and directory, or using the Browse button to
locate them, the Measurement History application can be configured to use defaults
(this has already been done for the 60 bus measurement history on the Samples Start
menu).
1. On the Windows task bar, right-click the Start menu, and select Open.
If there is more than one choice labeled Open, try both to locate the correct one.
2. Locate the shortcut for the Measurement History application.
With the default installation, this is located in
Programs\eterra\e_terracontrol\Measurement History
3. Right-click the Measurement History icon, and select Properties.
With the default installation, the Target field under the Shortcut tab reads
“C:\Eterra\e_terracontrol\bin\MeasHist.exe”. Adding the database name and the
working directory name to this path causes the application to start with those
settings as defaults.
For the 60 bus database, the target is:
“C:\eterra\e_terracontrol\bin\MeasHist.exe esca60
C:\eterra\e_terracontrol\samples”
The format is: "MeasHist.exe DatabaseName LocationOfHistoryFiles(.his)"
4. After altering the Target field, click OK to save the changes.

Note: If the histories of several different databases are viewed frequently, it is useful
to create separate shortcuts with the default settings for each database. Simply make
a copy of the existing Measurement History shortcut, and repeat steps 2 through 4.

1.4 Exporting History to a File

To export History to a file, implement the following procedure:
1. Open the Measurement History application.
2. Enter the database name and directory for the desired SCADA history file.
3. To view the names of the measurements whose data changed before the specified
end time, click Get Names.
4. Select one of the stations, and click Get History to retrieve the measurement history
for the specified date and time.
5. Select File > Save.
The Save As dialog box appears.
6. Enter a name for the file.

Proprietary – See Copyright Page 3 Measurement History Application

e-terracontrol Reference Manual: User Interface Applications
7. In the Save As Type list box, select the type of file to which you want to export your
history file: comma-separated text (*.csv) or plain text (*.txt).
8. Make sure that you are saving in the desired directory, then click Save.
The History file has now been exported.

Proprietary – See Copyright Page 4 Measurement History Application

e-terracontrol Reference Manual: User Interface Applications
2. Sequence of Events Applications
e-terracontrol includes two applications that are designed to process and view the
Sequence of Events (SOE) files that are produced by the CFE Reader application (refer
to the e-terracontrol Reference Manual: Interfaces to Field Devices).
The SOE Compiler application processes the SOE files, and the SOE Viewer
application allows you to view the processed SOE files.
These applications run on the server/host or client machine.

2.1 SOE Compiler

The CFE Reader application (see the e-terracontrol Reference Manual: Interfaces to
Field Devices) periodically produces Sequence of Events (SOE) files. These files are
used as input by the SOE Compiler application. The SOE Compiler then performs the
following tasks:
• Clean: Deletes all output and intermediate files on startup when the -c
command-line argument is supplied (see section 2.1.1.12 File Cleanup).
• Compile: Translates the communication topology names into the substation
topology equivalents, and numeric state values into more-meaningful text.

Note: When an SOE file is compiled, to avoid processing the same SOE file
several times, the SOE Compiler appends to its name the extension
.processed.at.yyyy-MM-dd-HH-mm-ss.archive. YYYY represents the year, MM the
month, dd the day, HH the hour, mm the minute, and ss the second at which the
SOE Compiler compiled the SOE file.

• Sort: Sorts the file contents by time and date.

• Merge: Combines the files for multiple CFE Readers for any given day.
• Distribute: Places copies of the produced output files in one or more folders on one
or more machines.

2.1.1 SOE Compiler Command-Line Arguments

Because there are command-line arguments associated with this application, an SOE
Compiler shortcut is not created during the installation of e-terracontrol. The application
can be launched from the Process Starter (refer to the e-terracontrol Reference
Manual: Applications), a command line, a batch file, or a Windows shortcut you create
with the appropriate command-line arguments included.
The following formats are acceptable, where “p” is the command-line argument switch
and <Argument> is the command-line argument value:
-p
-p <Argument>

Proprietary – See Copyright Page 5 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
-p=<Argument>
/p
/p <Argument>
/p=<Argument>
The command-line arguments must be separated by a single space; however, it is
important to note that the majority of the command-line arguments are optional.
An example command-line statement is:
~\SOECompiler -i F:\SOE_Files -o F:\SOE_Files -p=36:00:00 -r

2.1.1.1 Exit on Completion

The “x” command-line argument instructs the SOE Compiler to exit upon completion. It
is only supported since this behavior is the behavior by default.
-x

Note: This setting overrides the period of work session setting if the “x” and “p” period
of work session command-line arguments are supplied.

The -x argument is optional. By default, when the -p setting is not set, the SOE
Compiler exits on completion.

2.1.1.2 File Path

The “i” command-line argument instructs the SOE Compiler where to locate the input
(CFE Control–dumped .soe type) files. Each CFE Control requires its own input file
path. These paths are then separated with semicolons in the command. Partial paths
that are relative to the current working directory are acceptable. Network shares to
external machines must be mapped on the local machine.
-i <InputFilePath>
The “o” command-line argument instructs the SOE Compiler where to save the output
(.csv type) files. More than one path can be supplied, to allow replication of data.
Multiple paths must be separated with semicolons in the command. Partial paths that
are relative to the current working directory are acceptable. Network shares to external
machines must be mapped on the local machine.
-o <OutputFilePath>
The -i and -o arguments are required.

2.1.1.3 File Name Customization

The SOE Compiler appends the PC name (or the name supplied via the “n” argument)
to output file names.

Proprietary – See Copyright Page 6 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
The “n” command-line argument instructs the SOE Compiler to append the supplied
custom name to output file names.
-n <Custom Name>
The -n argument is optional.

Note: The SOE Compiler does not allow dashes or underscores in the string
appended to the output file names. Dashes and underscores present in the PC name
(or the string supplied via the “n” argument) are automatically removed.

2.1.1.4 Working Folder Path

The “w” command-line argument instructs the SOE Compiler where to locate its working
folder. Partial paths that are relative to the current working directory are acceptable. If
not supplied, the default is the current working directory.
-w <WorkingFolderPath>
The -w argument is optional.

2.1.1.5 Fixed-Length Point Names

The “f” command-line argument instructs the SOE Compiler to impose the fixed-length
naming convention in the Station Topology (SUBTOP) point names: station name
(8 characters), type name (6 characters), device name (14 characters), and point name
(4 characters). Excluding this command-line argument instructs the SOE Compiler to
impose long names.
-f

Note: The SOE Compiler application does not support overridden external names.

2.1.1.6 Exclusion of Invalid Time Records

The “e” command-line argument instructs the SOE Compiler to exclude records from its
input files whose system date does not correspond to the date in the input file’s name.
-e
The -e argument is optional.

2.1.1.7 Analog Limit Excursion Files

The “l” command-line argument instructs the SOE Compiler to compile Analog Limit
Excursion (ALE) files instead of Sequence of Event files.
-l
The -l argument is optional.

Proprietary – See Copyright Page 7 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
2.1.1.8 Log File Size
The “m” command-line argument instructs the SOE Compiler to set a maximum size (in
number of lines) for its log file.
-m <Max Lines>
The -m argument is optional.

2.1.1.9 Intermediate File Storage

By default, the SOE Compiler deletes all intermediate files. These file types include
compiled (.soc) and sorted (.sos) files.
The “k” command-line argument instructs the SOE Compiler to keep all intermediate
files, including compiled (.soc) and sorted (.sos) files.

Note: This option should only be used for diagnostic purposes.

-k
The -k argument is optional.

2.1.1.10 Period of Work Session

The “p” command-line argument instructs the SOE Compiler as to the amount of time
between work sessions. The valid range is 000:00:10 (10 seconds) to 168:00:00 (one
week). The default setting is 0, which instructs the SOE Compiler to run to completion.

Note: The period should be set with system performance in mind. The shorter the
periodicity, the larger the impact this application has on system resources.

-p <hh:mm:ss>
The -p argument is optional.

2.1.1.11 Time Base

The “b” command-line argument informs the SOE Compiler of the execution schedule.
The default is 00:00:00 (midnight). You can choose to supply a time base other than the
default, in order to balance system resources.
-b <hh:mm:ss>
The -b argument is optional.

2.1.1.12 File Cleanup

The “c” command-line argument instructs the SOE Compiler to delete all output (.csv)
and intermediate (.soc and .sos) files on application startup.

Proprietary – See Copyright Page 8 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
-c
The -c argument is optional.

2.1.1.13 Diagnostics
The “r” command-line argument instructs the SOE Compiler to retain the Work Order
List.

Note: This parameter is used only for diagnostic purposes. When using this
parameter, the memory usage increases continually. Do not use this parameter on a
production system.

-r
The “s” command-line argument instructs the SOE Compiler to use a simulation
database in place of the SCADA database.

Note: This option is recommended only for testing and/or debugging.

-s
The “t” command-line argument does not instruct the SOE Compiler to do any work; it
merely displays the form for diagnostic purposes.

Note: This option is recommended only for testing and/or debugging.

-t
The -r, -s, and -t arguments are optional.

2.1.1.14 Three-State Point Processing

The “y” command-line argument instructs the SOE Compiler to utilize special
processing for three-state points. The valid values are “single”, “opposite”, and
“extended”. The default is to handle each bit change as a single-bit change (“single”).
If you select “opposite”, the SOE Compiler assumes that only the S bit of any three-
state point is reporting SOE data. In this case, the compiler assumes that the X bit of
any three-state point is in the opposite state of the S bit. The combined S and
(assumed) X bit values are then used to look up the corresponding point state name for
the transition.
-y opposite
If you select “extended”, the SOE Compiler processes the X bit as a two-bit status and
assumes that the value of the S bit is 0. The combined S and (assumed) X bit values
are then used to look up the corresponding point state name for the transition.
-y extended
The -y argument is optional.

Proprietary – See Copyright Page 9 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
2.1.1.15 SOE Event Archival
The “g” command-line argument is used to instruct the SOE Compiler to output SOE
event data files in an alternate format for the purpose of archiving. The valid values are
“archive” and “noarchive”. The default is to output the event data in the normal SOE
format (“noarchive”).
If the “archive” option is selected, the SOE Compiler outputs the SOE events in pseudo
alarm format rather than the normal SOE format. The resulting file cannot be viewed
using the SOE Viewer application.
-g archive
The -g argument is optional.

2.1.1.16 SXBIT Field Processing

The “q” command-line argument is used to instruct the SOE Compiler to process the
SXBIT field from the SOE Log file. Normally, the SOE log contains only the STATE field;
however, in some applications, the SXBIT field is also logged. In these cases, the
STATE field and the SXBIT field are used to form the two-bit status value.
-q
The -q argument is optional.

2.1.1.17 SCADA Server Listen Port

The “d” command-line argument is used to designate the SCADA listening port to
communicate with SOE Compiler. If this argument is not provided, the port number
defaults to 5020 for NTLM/Kerberos authentication and 7000 for Certificate-based
authentication. If multiple SOE Compilers are communicating with different SCADA
instances, it is import to assign the port numbers to match each SCADA instance.
-d=5021
The -d argument is optional for a single SCADA instance, but required for environments
with multiple SCADA instances.
If this parameter is defined and the -n parameter is not defined, the machine name plus
the port number defined here will be added to the output file name, this is to make sure
different SCADA instances can have identifiable SOE output files.

2.1.2 Starting the SOE Compiler Using the Process Starter

The Process Starter application (refer to the e-terracontrol Reference Manual:
Applications) can start and restart programs as required. This is useful in situations
where you want the SOE Compiler application to remain continuously active on certain
PCs.

Proprietary – See Copyright Page 10 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
1. From the Windows Start menu, open the Process Starter Console application, and
be sure that the Process Starter service is running. Then connect the console to the
Process Starter service by clicking the Connect button on the Process Starter
Console toolbar.
2. To create a new Process Starter group, proceed to step 3. To add the SOE Compiler
application to an existing group, select File > Upload, and choose the desired .psc
file to display the Configuration tab for Processes.

Note: Prior to adding a process to an existing group, you must end all processes
by clicking Stop on the Process Starter toolbar or via the Actions menu item.

3. To create a new Process Starter group, select Processes > Add Process.
The Configuration tab for Processes opens.
4. Enter the required information in the Name, Program, Params, and Directory text
boxes. If you do not know the location of the SOECompiler.exe file, click the Ellipsis
button (…) next to the Program text box to browse for the file.
Sample values are as follows:
– Name: SOE Compiler
– Program: C:\eterra\e_terracontrol\bin\SOECompiler.exe
– Params: -i F:\SOE_Files -o F:\SOE_Files -p=36:00:00 -r
– Directory: C:\eterra\e_terracontrol\data
5. If desired, select the Minimize check box.
6. If you do not want to see the GUI, uncheck the Visible check box.
7. In the Restart frame, select the On Exit radio button.
8. Click OK.
9. Save the file.

2.1.3 SOE Compiler Dialog Box

The messages generated from the SOE Compiler are listed in the dialog box.

Figure 2. SOE Compiler Dialog Box

Proprietary – See Copyright Page 11 Sequence of Events Applications
e-terracontrol Reference Manual: User Interface Applications
2.1.3.1 Menu Bar
On the menu bar, the non-standard options are as follows:
File Menu
• Clear: Clears the contents of the message window.
• WorkOrders: Launches the Work Orders dialog box (Figure 3).

2.1.4 Work Orders

The SOE Compiler deletes (optional), compiles, sorts, merges, and distributes SOE
files. The Work Orders dialog box (Figure 3) lists work that is to be performed by the
SOE Compiler.

Note: The Work Orders dialog box is only available if the -r command-line argument is
supplied.

Figure 3. Work Orders Dialog Box

The following are included in the Work Orders dialog box:

• Index: Displays the sequence number of the work order.
• Status: Displays the status of the work order (Unknown, Pending, Active, or
Complete).
• Command: Displays the current process step (Compile, Sort, Merge, Copy, or
Delete).
• Source: Displays the input file name.
• Destination: Displays the output file name.

Proprietary – See Copyright Page 12 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
Figure 4 shows the process flow for this application:

CFEReader 1

compile sort
.soe .soc .sos

m
er
ge
CFEReader 2

compile sort merge distribute

.soe .soc .sos .csv .csv

CFEReader 3

e
g
er
m
compile sort
.soe .soc .sos

Figure 4. Work Order Process Flow

2.2 SOE and ALE Viewers

Once the SOE Compiler processes the SOE data collected by the CFE Reader, you can
view the SOE data using the SOE Viewer and ALE Viewer applications.
The SOE Viewer application is for SOE status data, and the ALE Viewer application is
for SOE Analog Limit Excursion data.

2.2.1 SOE Viewer/ALE Viewer Command-Line Arguments

SOE Viewer and ALE Viewer shortcuts are not created during the installation of
e-terracontrol because there are command-line arguments associated with these
applications.
The following formats are acceptable, where “p” is the command-line argument switch
and <Argument> is the command-line argument value:
-p
-p <Argument>
-p=<Argument>
/p
/p <Argument>
/p=<Argument>
An example command-line statement is:
~\SOEViewer -i F:\SOE_Files;G:\Files;Z:\Files_For_SOE

Proprietary – See Copyright Page 13 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
2.2.1.1 File Path
The “i” command-line argument passes the location of the SOE Compiler output (.csv)
files to the Viewer. If this command-line argument is not supplied, the application
searches for the files in the current working directory. Multiple file locations in the
arguments are separated by semicolons.
-i <InputFilePaths>
The -i argument is optional.

2.2.1.2 User Interface Refresh Period

The “p” command-line argument instructs the Viewer as to the amount of time between
UI updates. The valid range is 000:00:10 (10 seconds) to 168:00:00 (one week). This
option allows you to utilize the Process Starter for dynamic refreshing. The default
setting is 0, which instructs the SOE Viewer to respond to user input only (no dynamic
refresh) completion.
-p <hh:mm:ss>

Note: When using this option, it is recommended that you not enter a value in the End
Time text box on the Viewer user interface. Otherwise, this dynamic refreshing
functionality refreshes the statically defined data.

The -p argument is optional.

2.2.1.3 Log Level Filter

The “l” command-line argument directs the Viewer as to the types of diagnostic
messages to be displayed in the Log display box. Excluding this argument defaults to
the “-l WARNING” configuration.
-l <Level>
where Level options are:
NONE: Displays no diagnostic messages
ERROR: Displays only error messages
WARNING: Displays error and warning messages
OTHER: Displays error, warning, and information messages
The -l argument is optional.

Proprietary – See Copyright Page 14 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
2.2.1.4 Log File Size
The “m” command-line argument instructs the Viewer to set a maximum size (in number
of lines) for its log file.
-m <Max Lines>
The -m argument is optional.

2.2.1.5 Time Filter Selection

The “t” command-line argument directs the Viewer as to which time field (Field Time or
System Time) to apply user-entered dates/times to.
-t <TimeSource>
where TimeSource options are:
FIELD: Filters on Field Time
SYSTEM: Filters on Field Time (default)
The -t argument is optional.

2.2.2 Starting the SOE and ALE Viewers Using the Process Starter
The Process Starter application (refer to the e-terracontrol Reference Manual:
Applications) can start and restart programs as required. This is useful in situations
where you want the SOE and/or ALE Viewers to remain continuously active on certain
PCs.
1. From the Windows Start menu, open the Process Starter Console application, and
be sure that the Process Starter service is running. Then connect the console to the
Process Starter service by clicking the Connect button on the Process Starter
Console toolbar.
2. To create a new Process Starter group, proceed to step 3. To add the SOE and/or
ALE Viewer applications to an existing group, select File > Upload, and choose the
desired .psc file to display the Configuration tab for Processes.

Note: Prior to adding a process to an existing group, you must end all processes
by clicking Stop on the Process Starter toolbar or via the Actions menu item.

3. To create a new Process Starter group, select Processes > Add Process.
The Configuration tab for Processes opens.
4. Enter the required information in the Name, Program, Params, and Directory text
boxes. If you do not know the location of the SOEViewer.exe file, click the Ellipsis
button (…) next to the Program text box to browse for the file.

Proprietary – See Copyright Page 15 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
 Sample values are as follows:
– Name: SOEViewer
– Program: C:\eterra\e_terracontrol\bin32\SOEViewer.exe
– Params: -i F:\SOE_Files;G:\Files;Z:\Files_For_SOE
– Directory: c:\eterra\e_terracontrol\bin32
5. If desired, select the Minimize check box.
6. If you do not want to see the GUI, uncheck the Visible check box.
7. In the Restart frame, select the On Exit radio button.
8. Click OK.
9. Save the file.

2.2.3 Loading SOE Files

There are four types of file queries:
• All: All available files are loaded by the application when the Start Time and End
Time text boxes are left blank.
• Since: The application loads all available files since (and including) the specified
Start Time. The End Time text boxes must be left blank.
• Up To: The application loads all available files up to (and including) the specified
End Time. The Start Time text box must be left blank.
• Range: The application loads all available files between (and including) the specified
Start Time and End Time.

2.2.4 Settings Menu

The Settings pull-down menu allows you to modify the “t” and “u” arguments after the
application has been started.

Proprietary – See Copyright Page 16 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
2.2.5 SOE (and ALE) Viewer User Interface
The Viewer user interface is divided into three tabs: SOE Data, Log, and Files.

2.2.5.1 SOE Viewer User Interface - SOE Data Tab

Figure 5. SOE Viewer User Interface - SOE Data Tab

The following are included on the SOE Data tab:

Header
• Start Time: Beginning date of the SOE information to be displayed (yyyy/mm/dd
format, or any other Microsoft Visual Basic–recognized date format). Leaving this
field blank provides no lower boundary for the query.
• End Time: Ending date of the SOE information to be displayed (yyyy/mm/dd format,
or any other Visual Basic–recognized date format). Leaving this field blank provides
no higher boundary for the query.
• OK: Retrieves SOE information based on the values entered for Start Time and End
Time. It also stores the latest Start Time and End Time entries in memory.
• Cancel: Retrieves the previously stored Start Time and End Time entries from
memory.

Proprietary – See Copyright Page 17 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
• Clear: Clears the contents of the Start Time, End Time, and List View text boxes.
List View
• File No.: File number of the SOE data file.
• Field Time: Date/time stamp of the event (yyyy/mm/dd hh:mm:ss.sss format) as
reported by the field device.
• System Time: Date/time stamp of the event (yyyy/mm/dd hh:mm:ss.sss format) as
received by the SCADA server.
• Comm: Communication topology name.
• Name: Substation topology name.
• State (SOE only): State of the status measurement.
• Duration (ALE only): Time the analog was out of limits.
• Extreme (ALE only): Highest/lowest value recorded for the analog while out of
limits.
• Average (ALE only): Average value recorded for the analog while out of limits.
• Quality: CFE Reader–generated quality information.
The displayed SOE information can be sorted on any of the List View column headings
by clicking the heading name.

Proprietary – See Copyright Page 18 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
2.2.5.2 SOE Viewer User Interface - Log Tab
The Viewer log messages are shown on the Log tab of the Viewer user interface:

Figure 6. SOE Viewer User Interface - Log Tab

Proprietary – See Copyright Page 19 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
2.2.5.3 SOE Viewer User Interface - Files Tab

Figure 7. SOE Viewer User Interface - Files Tab

The following are included on the Files tab:

Header
• User-Entered Start Time: Beginning date of the SOE information as entered on the
SOE Viewer User Interface - SOE Data Tab.
• User-Entered End Time: Ending date of the SOE information as entered on the
SOE Viewer User Interface - SOE Data Tab.

Proprietary – See Copyright Page 20 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
• Viewer-Derived Start Time: Starting date and time of the SOE information as
derived by the SOE Viewer application from the user entry. If a user-entered start
time is not supplied, a default start time of 12/11/1995 is used.
• Viewer-Derived End Time: Ending date and time of the SOE information as derived
by the SOE Viewer application from the user entry. If a user-entered end time is not
supplied, a default end time of 12/31/9999 is used.
List View
• File No.: File number of the SOE data file.
• File Path: File path of the SOE data file.
• File Name: File name of the SOE data file.

Proprietary – See Copyright Page 21 Sequence of Events Applications

e-terracontrol Reference Manual: User Interface Applications
3. Simulator Application
The Simulator application allows you to construct a fictional substation or to re-create an
actual substation for simulation purposes.
The modeled measurements within the SCADA server are connected to the created
simulation database through a data source. This can be a powerful tool for operators
who are new to e-terracontrol and for system modelers who wish to simulate their
modeled systems prior to “going live” with them.
In the standard e-terracontrol offering, two sample simulator models, for the Kincard
and Snohomish stations, are included. The Kincard model is configured to connect to
the TransSim data source within the esca60 sample SCADA database, whereas the
Snohomish model is configured to connect to the SpSim data source within the esca60
sample SCADA database. Both sample simulators can be launched from Windows
Start > Programs > Eterra > e_terracontrol > Samples.
The simulator application reads a *.sim file, which contains the station configuration to
simulate along with the configuration for connecting to the SCADA server. By default,
the simulator application connects to the SCADA server running on port 5020 for
NTLM/Kerberos authentication and port 7000 for Certificate-based authentication on the
same machine. By changing the “Port” configuration item, you can specify the SCADA
port that the simulator application will use to connect.
This application runs on the server/host machine.

Proprietary – See Copyright Page 22 Simulator Application

e-terracontrol Reference Manual: User Interface Applications
3.1 Simulator User Interface

Figure 8. Simulator Main Window - Tree View

The following are included in the Simulator user interface:

Header
• Connect to SCADA: Connects to or disconnects from the SCADA source name, as
specified in the Options dialog box (see section 3.4 Simulator Options Dialog Box).

Note: The specified data source must be configured in the active SCADA Server
application.

• Simulation: Enables or disables the simulation.

• Date/Time: Date/time stamp of the last simulation interval scan.
• Now: Demands a simulation scan.
• Labels: Enables/disables the display of point names.

Proprietary – See Copyright Page 23 Simulator Application

e-terracontrol Reference Manual: User Interface Applications
• Topology
• Power Flow
• Debug: Launches the Debug Output window (see section 3.5 Debug Output
Window).

3.2 Simulator Menu Bar

On the menu bar, the non-standard options are as follows:
Tools Menu
• Show Create Toolbar: Select this menu option to replace the Tree view (Figure 8)
with a listing of available equipment types.
• Options: Select this item to launch the Options dialog box (see section 3.4
Simulator Options Dialog Box).
• Find New Measurements: Select this option to search the SCADA server for
measurements that were newly added and assigned the data source name (Figure
9).
• Show Tree View: Select this option to display the simulation model tree (Figure 8).

Proprietary – See Copyright Page 24 Simulator Application

e-terracontrol Reference Manual: User Interface Applications
3.3 Create Toolbar

Figure 9. Simulator Main Window with Create Toolbar Showing

The Create Toolbar view includes the following equipment types:

• Breaker
• Bus
• Capacitor
• Generator
• Injection
• Line
• Load
• Reactor
• Relay
• Switch
• Transformer
It also includes the following additional items:
• Create Toolbar
• Snap to Grid, Grid X, and Grid Y: Used for device placement

Proprietary – See Copyright Page 25 Simulator Application

e-terracontrol Reference Manual: User Interface Applications
3.4 Simulator Options Dialog Box

Figure 10. Simulator Options Dialog Box

The following are included in the Simulator Options dialog box:

• Simulation Interval (ms): The time interval of the simulation processing scans in
milliseconds.
• Relay Time Step (ms): The time interval of the relay step in milliseconds.
• SCADA Source Name: Name of the connecting data source name in the SCADA
Server application.
• Put SCADA Online When Initializing: When selected, the Simulator application
automatically connects to SCADA when it initializes, including at application start-up.
• Turn Simulator On When Initializing: When selected, the Simulator application
automatically starts the simulator when it initializes, including at application start-up.

3.5 Debug Output Window

Figure 11. Simulator Debug Output Window

Proprietary – See Copyright Page 26 Simulator Application

e-terracontrol Reference Manual: User Interface Applications
The following are included in the Simulator Debug Output window:
• Limit Length to…MB: When checked, the amount of debug text displayed is limited
to the value entered in the adjacent text box, in megabytes. This is also the
maximum size of individual log files, when the Log Errors in File check box is
selected.
• Disable Output: Toggle ON to disable output messages.
• Log Errors in File: Toggle ON to save the messages generated to a file. Log files
are generated in the application directory path with the name
Simulator_yyyymmdd_hhmmss.log, where yyyymmdd is the date and hhmmss is the
time.

Proprietary – See Copyright Page 27 Simulator Application

e-terracontrol Reference Manual: User Interface Applications
4. SMP Display Linker Application
The SMP Display Linker application is used when building e-terrabrowser displays. If
the SCADA database is already in place and the visual components of a display have
been created, the Linker application can be used to link the display objects to the
database. Effective use of the Linker can greatly reduce the time needed to construct
e-terrabrowser displays.

Note: The SCADA server must be running to allow the SMP Display Linker to
function.

4.1 SMP Display Linker Command-Line Parameters

The SMP Display Linker application accepts the following as optional command-line
parameters:
• The hostname where the SCADA Server application is running.
• The port number that the SCADA Server application uses as its listening port.
Usage example:
C:\eterra\e_terracontrol\bin\SMPLinker.exe host1=smp1 host2=smp2 host3=smp3
host4=smp4 scadaport=5021
Where:
• The host1, host2, host3, and host4 command-line arguments are used to designate
the host name(s) of the e-terracontrol server(s):
host1=<ComputerName>
host2=<ComputerName>
host3=<ComputerName>
host4=<ComputerName>
where <ComputerName> is the name of the computer running the e-terracontrol
server. These IP alias names must be defined in the host file.
• Scadaport is an optional argument for specifying the port that the SCADA server is
listening on if it is not the default port (5020 for NTLM/Kerberos authentication and
7000 for Certificate-based authentication).
Usage example: scadaport=5025

Proprietary – See Copyright Page 28 SMP Display Linker Application

e-terracontrol Reference Manual: User Interface Applications
4.2 SMP Display Linker User Interface

Figure 12. SMP Display Linker User Interface

The following are included on the SMP Display Linker user interface:
• The drop-down list box is used to select a data type: Stations, Analogs, Statuses, or
Accumulators.
• The Tree view displays equipment groups.

4.3 Using the SMP Display Linker

To familiarize yourself with this program, complete the following example:
1. Launch the 60 bus SCADA Server application.
This sample SCADA server can be launched from Windows Start > Programs >
Eterra > e_terracontrol > Samples.

Proprietary – See Copyright Page 29 SMP Display Linker Application

e-terracontrol Reference Manual: User Interface Applications
2. Launch the Display Builder application.
This application can be launched from Windows Start > Programs > Eterra >
e_terracontrol.
3. In the Display Builder, open the file
C:\eterra\e_terracontrol\ddl\smp60_dset.ddl
The file path may vary, and it is dependent on the file path selected during
installation.
4. From the display list, double-click the Kirkland display.
5. Double-click the top right circuit breaker icon (the little red square).
The pop-up should say:
SUBSTN = KIRKLAND
DEVTYP = CB
DEVICE = 530C
POINT = BKR
6. Delete all of the text and click OK.
Double-clicking the breaker icon a second time should confirm that the deletion was
effective.
7. From Windows Start > Programs > Eterra > e_terracontrol, select SMP Display
Linker.
8. In the left drop-down list box, scroll down and select Statuses.
9. In the tree view, select Kirkland.
10. Resize and position the Builder and Linker windows so that both are visible at the
same time. Then drag and drop the KIRKLAND.CB.530C.BKR link (from the SMP
Display Linker application) onto its respective red circuit breaker icon (in the Display
Builder application).
Double-clicking the breaker icon should confirm that the linking action was effective.

Note: The Alt+Tab windowing technique can also be used in the linking process. From
the Linker application, once the left mouse button is depressed and held, the Alt+Tab
feature can switch the active window to the Display Builder. Then the mouse pointer
can be positioned over the desired graphic component, and the left mouse button can
be released.

Proprietary – See Copyright Page 30 SMP Display Linker Application

e-terracontrol Reference Manual: User Interface Applications
5. Virtual Chart System
The Virtual Chart System (VCS) was developed to replace existing hardware chart
recorders with video-display-equivalent chart recorders. The VCS is an improvement
over the old hardware solutions, which required excessive user interaction to change
paper and dried-out pens, to stamp the time on the paper, and to store the paper charts
for later analysis.
You can customize the Virtual Chart System. Accordingly, you can control the contents
and appearance of the charts that appear in the VCS display window (see section 5.5
Virtual Chart System Display Window). The customized settings are saved in a Chart
Configuration text file (see section 5.1 Creating a Chart Configuration Text File) for
future use. If you need to view more than one collection of charts, you can create
multiple Chart Configuration text files and save them on the same computer.
The operator runs the Virtual Chart System as an option from the Windows Start menu,
via the Process Starter, or by using a Windows shortcut (see section 5.4 Starting the
Virtual Chart System Using a Windows Shortcut). When starting the Virtual Chart
System using either of these methods, references are made in the command line to the
Chart Configuration text file (see section 5.1 Creating a Chart Configuration Text File).
The VCS automatically connects and reconnects to the active host as required. The
VCS has the capability to chart trends from real-time or historical data.
This application runs on the server/host or client machine.

5.1 Creating a Chart Configuration Text File

Prior to adding the Virtual Chart System to the Process Starter or creating a Windows
shortcut, the creation of a Chart Configuration text file is required.
To create a Chart Configuration text file, use the following procedure:
1. Make sure that the correct SCADA database is running on the host computer.
2. Launch the file Charts.exe.
By default, Charts.exe is located in C:\eterra\e_terracontrol\bin32.
3. In the dialog box that requests the name of a Chart Configuration text file to open,
click Cancel.
4. To launch the Chart Configuration display window, select Edit > Layout (Figure 16).
5. Design the layout of your Virtual Chart display (see section 5.6.2 Chart Configuration
Dialog Box).
6. To save the Chart Configuration text file, select File > Save As.
Once the file is created, you can modify the design of the Virtual Chart display at any
time. However, to preserve your changes, the file must be saved after each
modification.

Proprietary – See Copyright Page 31 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
5.2 Virtual Chart System Command-Line Arguments
Placing the Chart Configuration text file directly after the executable file name (see
section 5.1 Creating a Chart Configuration Text File) notifies the application to load the
specified file upon application start-up. The configuration file path must also be specified
if it differs from the executable file path.
For a client configuration, you must also specify the server, or pair of servers (redundant
configuration), where the SCADA database resides. If the SCADA database’s listening
port is different from its default port (5020 for NTLM/Kerberos authentication and 7000
for Certificate-based authentication), you can specify the listening port of the SCADA
Server application. You can configure up to four network connections for redundant
e-terracontrol servers, with redundant network addresses on the servers. This
command-line argument is only required for client configurations.
The following example demonstrates the syntax for these command-line arguments:
C:\eterra\e_terracontrol\bin32\Charts.exe ..\samples\Kirkland.txt /SCADAHOST1
PC8822 /SCADAHOST2 PC352 /PORT 5021
To start the application in the minimized state, you can use the command-line argument
“/STARTMIN”. Syntax:
C:\eterra\e_terracontrol\bin32\Charts.exe ..\samples\Kirkland.txt /STARTMIN

Note: The configuration file name must come before the /SCADAHOST or
/STARTMIN argument in the command.

The server argument is required for client configurations.

5.3 Starting the Virtual Chart System Using the Process Starter
The Process Starter application (refer to the e-terracontrol Reference Manual:
Applications) can start and restart programs as required. This is useful in situations
where you want the Virtual Chart System to remain continuously active on certain PCs.
1. From the e-terracontrol Start menu, open the Process Starter Console application,
and be sure that the Process Starter service is running. Then connect the console to
the Process Starter service by clicking the Connect button on the Process Starter
Console toolbar.
2. To create a new Process Starter group, proceed to step 3. To add the Virtual Chart
System to an existing group, select File > Upload, and choose the desired .psc file to
display the Configuration tab for Processes.

Note: Prior to adding a process to an existing group, you must end all processes
by clicking Stop on the Process Starter toolbar or via the Actions menu item.

3. To create a new Process Starter group, select Processes > Add Process.
The Configuration tab for Processes opens.

Proprietary – See Copyright Page 32 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
4. Enter the required information in the Name, Program, Params, and Directory text
boxes. If you do not know the location of the Charts.exe file, click the Ellipsis button
(…) next to the Program text box to browse for the file.
Sample values are as follows:
– Name: Virtual Charts
– Program: C:\eterra\e_terracontrol\bin32\Charts.exe
– Params: chartconfig1.txt /SCADAHOST1 PC8822
– Directory: C:\eterra\e_terracontrol\bin32
5. If desired, select the Minimize check box.
6. If you do not want to see the GUI, uncheck the Visible check box.
7. In the Restart frame, select the On Exit radio button.
8. Click OK.
9. Save the file.

Proprietary – See Copyright Page 33 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
5.4 Starting the Virtual Chart System Using a Windows Shortcut
Once the Chart Configuration text file (see section 5.1 Creating a Chart Configuration
Text File) has been saved, a Windows shortcut can be created to launch the Virtual
Chart System.

Figure 13. Properties Dialog Box - Shortcut Tab

1. From Microsoft Windows Explorer, open the appropriate Start menu folder.
For example:
C:\Documents and Settings\All Users\Start
Menu\Programs\Eterra\E_TERRACONTROL\
2. Right-click anywhere in the folder, and select New > Shortcut.
3. Browse for the Charts.exe file, but do not click Next yet.
By default, the file Charts.exe is located in C:\eterra\e_terracontrol\bin.

Proprietary – See Copyright Page 34 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
4. In the command-line text box, insert a blank space after the Charts.exe path, and
enter the name of the Chart Configuration text file (see section 5.1 Creating a Chart
Configuration Text File) followed optionally by the SCADAHOST command-line
arguments (see section 5.2 Virtual Chart System Command-Line Arguments).
5. Click Next.
6. Enter a user-definable shortcut name, such as “My Virtual Charts Shortcut”.
7. Right-click the newly created shortcut, and select Properties.
8. On the Shortcut tab (Figure 13), enter the path where the specified Chart
Configuration text file is located in the Target text box.
9. Click OK.
If you need to view more than one collection of charts, you can create multiple Windows
shortcuts by copying the shortcut and changing the contents of the Target text box.

5.5 Virtual Chart System Display Window

The Virtual Chart System provides the mechanism to create and view “virtual” strip chart
recorders. That is, the VCS re-creates a physical strip chart recorder in a computer
application.
The Virtual Chart System can trend one or more selected points (analog values) in the
SCADA database. These trends present a graph of the value of the point over time
within a definable scale. There can be multiple traces on a single graph (Figure 14).

Figure 14. Illustration of a Typical Trend

The VCS supports properties for changing the visual attributes of the trend. These
properties include:
• Direction of the paper: down, up, left, and right
• Number of traces to be displayed up to 16, along with their color, label, and scale

Proprietary – See Copyright Page 35 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
• Indicator box colors and visibility
• Visibility of scale and label attributes
• Trace box colors
• Major timeline interval, style, and color
• Minor timeline interval, style, and color
• Timestamp interval
• Major scale line interval, style, and color (reflects the current trace)
• Minor scale line interval, style, and color (reflects the current trace)

5.6 Virtual Chart System User Interface

Figure 15. Virtual Chart System Display Window - Printing Defaults

The Virtual Chart System can display trends on a computer screen, a video display
device, or a projection screen.
Figure 15 illustrates the VCS as it looks with default configuration settings.

Proprietary – See Copyright Page 36 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
The Virtual Chart System display window contains only the actual charts; six are
displayed by default.
To modify the chart view, three actions can be taken from the display window:
• Double-click: Double-clicking an individual chart expands that chart to fill the
screen. Double-clicking again returns the view to multiple charts.
• Single-click: Clicking a chart with multiple traces displays the scale and label of the
trace nearest to the cursor below the chart. This feature works from both the single
chart and multiple chart views.
• Right-click: Right-clicking a chart displays a pop-up window, from which you can
select the trace that is to be displayed.

Note: The single-click and right-click functions work only if the View Names and/or
View Scales options in the Chart Configuration dialog box are set to Selected Trace
(see section 5.6.2 Chart Configuration Dialog Box).

5.6.1 Menu Bar

The Virtual Chart System has the following non-standard menu options:
Edit Menu
The selections under this menu are used to bring up different tabs in the Chart
Configuration dialog box.
• Layout
• Colors
• Points
• Scales
• Limits
• Time range
• Miscellaneous
Connection Menu
The commands under this menu allow you to connect, disconnect, and reconnect the
Virtual Chart System to SCADA. You can also reset logon information from this menu.
• Disconnect
• Connect
• Reconnect
• Reset login info
Startup Menu
From this menu, you can copy the startup configurations to the clipboard and tell the
VCS to start minimized.

Proprietary – See Copyright Page 37 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
After the startup configurations are copied to the clipboard, they can easily be viewed
using a text editor such as Notepad. This feature allows you to alter current Windows
shortcuts or to create new ones for different sets of charts.
• Copy Configuration to Clipboard: Select to copy the startup configuration to the
clipboard, where it can be viewed in Notepad.

5.6.2 Chart Configuration Dialog Box

The Chart Configuration dialog box is used to create and/or modify chart groups.
Some of the tabs in this dialog box are chart-specific, while others are global and apply
to every chart in the group.
For the tabs that are chart-specific, you must select the desired chart from the black grid
on the right side of the dialog box prior to making changes. The selected chart is
highlighted in purple (Figure 16). Once the configuration is complete, select File > Save
and save the configuration to a text file. The contents of the text file can be used as a
parameter in a shortcut to start the Virtual Chart System with the same configuration.
For example:
C:\eterra\e_terracontrol\bin32\Charts.exe
C:\eterra\e_terracontrol\data\KirklandStationChart.txt

Proprietary – See Copyright Page 38 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
5.6.2.1 Layout Tab
The Layout tab (Figure 16) provides control over the visual appearance and
organization of the Virtual Chart System display. The settings on this tab apply to all
charts in the group.

Figure 16. Chart Configuration Dialog Box - Layout Tab

The following are included on the Layout tab:

• View Names: On a chart with multiple traces, this field controls whether each chart
displays the trace name and measurement value for all, none, or just the selected
trace.
• View Scales: On a chart with multiple traces, this field controls whether the scale for
all, none, or the selected trace is displayed. When grouping multiple traces together
on a single chart, it is a good idea to group together measurements with the same
scale. In this case, setting this parameter to Selected reduces clutter without
sacrificing any detail.
• Scale Text Position (not modifiable)
• Scale Text Style (not modifiable)
• Time Text Position (not modifiable)
• Time Text Style (not modifiable)
• Scale Text Justification (not modifiable)

Proprietary – See Copyright Page 39 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
• Name Text Position: Sets the placement of the trace name(s) to the top, bottom,
left, or right of the chart.
• Scroll Direction: Sets to scroll left, right, up, or down.
• Trace Box, Chart, Background, Time, Indicator, Minor Scale, Border, and Major
Scale: Clicking any of these buttons presents a color palette, from which you can
select the desired color for the selected item.
• Spacing: Adjusts the amount of gray spacing between the individual charts.
• Columns: When the columns and rows are set to zero, the Virtual Chart System
automatically arranges the charts in a fashion that best fits a monitor; however, you
can adjust these values to force a specific number of columns and/or rows. The
column value overrides the row value, meaning that (for example) if there are three
charts and columns set to 1, a row setting of 1 or 2 is ignored. The Reset button
returns the values of columns and rows to zero.
• Add Chart: Adds a chart in the selected location.
• Remove Chart: Removes the selected chart.
• Move Chart Up: Moves the selected chart one place to the left. If the chart is in the
left-most position, then it moves to the right-most position, one row up, until it is in
the first position.
• Move Chart Down: Moves the selected chart one place to the right. If the chart is in
the right-most position, then it moves to the left-most position, one row down, until it
is in the last position.

Proprietary – See Copyright Page 40 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
5.6.2.2 Colors Tab
The Colors tab (Figure 17) allows you to customize the colors for every feature of the
chart display.
The parameters on this tab are chart-specific. Each chart must be configured
separately, by selecting it in the chart grid on the right side of the dialog box prior to
making changes.

Figure 17. Chart Configuration Dialog Box - Colors Tab

The following are included on the Colors tab:

• Trace, Limit-1, Limit-2, Manual, NIS, Bad, and Old
• Clicking any Ellipsis button presents a color palette, from which you can select a
desired color for a trace or limit.

Proprietary – See Copyright Page 41 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
5.6.2.3 Points Tab
The Points tab (Figure 18) defines which measurements are displayed on each chart
and how they are labeled.
The parameters on this tab are chart-specific. Each chart must be configured
separately, by selecting it in the chart grid on the right side of the dialog box prior to
making changes.

Figure 18. Chart Configuration Dialog Box - Points Tab

The following are included on the Points tab:

• Point Name: Each measurement is denoted by a three-part key, which is entered in
the Point Name text box. This key is composed of the station name, equipment
name, and measurement name.
• Chart Label: This provides a means to identify each measurement in the Virtual
Chart System display. An easy approach to labeling the points is to cut and paste
the point name into the chart label, although you can enter any meaningful text as a
chart label.

Proprietary – See Copyright Page 42 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
5.6.2.4 Scales Tab
The Scales tab (Figure 19) allows you to set the scale/range in which the
measurements are charted.
The parameters on this tab are chart-specific. Each chart must be configured
separately, by selecting it in the chart grid on the right side of the dialog box prior to
making changes.

Note: To avoid confusion, note that no “scaling” is actually done in the Virtual Chart
System. The “Scale From” and “Scale To” values refer to the range of values over
which the trace appears. If the value of a particular measurement goes outside that
specified range, the numeric value is still displayed after its name, but the trace
indicator is off the edge of the chart.

It is a good idea to group measurements with the same scale on the same chart. This
prevents confusion and eliminates the need to display the scales for all the traces (see
section 5.6.2.1 Layout Tab). This tab also provides settings for the scale hash marks
(major and minor scale lines) and the scale text interval.
Good starting points for the Scale From and Scale To values are the engineering high
and low for the measurement. However, if a measurement spends 99.9% of its time
between 400 and 475, setting the Scale From and Scale To parameters to 400 and 475
increases the granularity of the chart and makes it more meaningful. The numeric
values are always displayed, even when the trace is off the chart.

Figure 19. Chart Configuration Dialog Box - Scales Tab

Proprietary – See Copyright Page 43 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
The following are included on the Scales tab:
• Scale From: Minimum value for which the trace is visible on the chart.
• Scale To: Maximum value for which the trace is visible on the chart.
• Line Interval: The interval at which minor scale lines are placed.
• Scale Offset: The offset (from Scale From) for the minor scale lines.

Note: The first minor scale line is placed at the Scale Offset. Therefore, if this
value is set to zero, a minor scale line is placed at the Scale From value on the
edge of the chart.

• Text Interval: The frequency with which the minor scale lines are enumerated:
– 0: Only the Scale From and Scale To values are listed.
– 1: Every minor scale line is labeled.
– 2: Every other minor scale line is labeled.
– 3, 4, etc.: Every third, fourth, etc., line is labeled.
• Major Interval: The interval at which major scale lines are placed.
• Major Offset: The offset of major scale lines with respect to minor scale lines.

Proprietary – See Copyright Page 44 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
5.6.2.5 Limits Tab
The Limits tab (Figure 20) allows you to specify one of six different visual effects for
portraying limits on a virtual chart.
Deselecting the Show Limit check box turns off these effects without changing or
removing the limit. The measurement names are automatically carried over from the
Points tab, to make configuring the limits easier.
The parameters on this tab are chart-specific. Each chart must be configured
separately, by selecting it in the chart grid on the right side of the dialog box prior to
making changes.

Figure 20. Chart Configuration Dialog Box - Limits Tab

The following are included on the Limits tab:

• Show Limit: Checking this box allows the limit violation effect(s) to be seen, and it
allows the limit itself to appear when its corresponding measurement is selected on
the chart.
• Limit: The analog value of the limit.
• Limit Style: Selects one of six limit violation visual representations:
– Shows a line representing the limit if the measurement is selected
– Shades from the limit to the trace, if the measurement falls below the limit
– Shades from the limit to the trace, if the measurement exceeds the limit
– Shades from the limit to the trace all the time

Proprietary – See Copyright Page 45 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
 – Changes the trace color if it falls below the limit (according to the Color tab)
– Changes the trace color if it exceeds the limit (according to the Color tab)

Note: Options 2 through 6 include the functionality of option number 1 as well.

Note that none of these are visible if the Show Limit box is not checked.

5.6.2.6 Time Range Tab

The Time Range tab (Figure 21) controls the range of time that is visible, and it toggles
between real-time and historical modes. The settings on this tab apply to all charts in
the group.

Figure 21. Chart Configuration Dialog Box - Time Range Tab

The following are included on the Time Range tab:

• Real Time: Select this radio button when real-time data trending is desired.
• Shift Interval: For real-time charts, the value of this field specifies in seconds how
often the chart scrolls (refreshes). This value should be set to 1 unless the
performance of the PC on which it is running becomes an issue.
• Historical: Select this radio button when historical data trending is desired.
• Stop Time: For historical charts, the value of this field specifies the end time of the
static chart. The Seconds Visible window counts back from this time.

Proprietary – See Copyright Page 46 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
• Browse: For historical charts, use this button to search for a history (.his) file. The
file is used to populate the History File Path and Database Name fields.
• History File Path: For historical charts, this field specifies the location of the .his
files. As seen in Figure 21, this field can be set to a shared drive on a separate
machine (the one receiving the .his files from the Copy History program).
• Database Name: For historical charts, the database name is the same as the name
of the SCADA database (.sdb) file. When using the Browse button, the database
name and a hexadecimal time stamp are combined to form the name of the .his file.
• Seconds Visible: Pertaining to both real-time and historical charts, this field
specifies how many seconds of chart are visible. The smaller the number, the faster
a real-time chart scrolls. This variable can affect real-time performance on a slow
PC.

5.6.2.7 Miscellaneous Tab

The Miscellaneous tab (Figure 22) contains global attributes, which further refine the
appearance of the Virtual Chart System display.

Figure 22. Chart Configuration Dialog Box - Miscellaneous Tab

The following are included on the Miscellaneous tab:

• Dash Interval: Sets the distance between the dashed lines. The smaller the
number, the closer the dashes.

Proprietary – See Copyright Page 47 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
• Dash Length: Sets the length of each individual dash. The larger the number, the
longer the dash.
• Dot Interval: Sets the distance between the individual dots within a dotted line. The
smaller the number, the closer the dots.
• Set Font: Select to change the font, font style, and size for all of the alphanumeric
text in the Virtual Chart System using a Font dialog box.
• Scale Font: When checked, the font grows and shrinks with the size of the chart.
• Step: When checked, significant changes are shown as step changes. For example,
if a measurement goes from 157 volts to 0 volts “instantaneously”, the Virtual Chart
System draws a horizontal line (if the scroll direction is down) from 157 volts to
0 volts. If unchecked, lines are plotted between each data value depicting something
of a transient, thus mimicking a real paper-and-pen chart during significant deltas.
• Show Indicators: When checked, the triangular “pen” appears at the current value
of the trace.
• Show Info Border
• Show Tool Tips
• Scale Line Style: Choose a solid, dashed, or dotted line to represent the scale hash
marks.
• Time Line Style: Choose a solid, dashed, or dotted line to represent the time hash
marks.
• Printing Defaults: Sets the colors of the chart to a printer-friendly white background
and dark foreground/text, which reduces toner usage.
• CRT Defaults: Sets the colors of the chart to an eye-friendly black background and
light foreground/text, which helps reduce eyestrain and provides a clearer picture on
a projection screen.

Proprietary – See Copyright Page 48 Virtual Chart System

e-terracontrol Reference Manual: User Interface Applications
6. Alarm Viewer Application
The Alarm Viewer is a Microsoft Windows application used for querying and viewing
event data from the e-terracontrol application.
The Alarm Viewer interacts with e-terracontrol, accessing event information from the
SCADA application and/or the SCADA-produced archive files.
The Alarm Viewer can run as a display within the e-terrabrowser Viewer. The Alarm
Viewer is a Microsoft ActiveX control that is installed and registered during the
e-terrabrowser client installation. The Alarm Viewer ActiveX control is labeled
“AlarmViewerOcx.ocx”.
The Alarm Viewer allows users to create queries based on fields contained in Alarm
events. The current release of e-terracontrol allows queries to be constructed using the
following fields:
• Event time
• Alarm text
• Priority
• Location
• Category
• Permission area
• Formatted log

Proprietary – See Copyright Page 49 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
6.1 Alarm Viewer User Interface Overview

Figure 23. Alarm Viewer Main Screen

The Alarm Viewer user interface has two primary views, as shown in Figure 23. The top
view is called the “Query view”, and it is used to construct and submit queries. The
bottom view is called the “Results view”, and it shows query results in a row/column
format.

6.1.1 Query View

Queries are constructed by providing values for fields that are part of an Alarm event. A
user can provide values for any of the fields listed below by using the provided check
boxes, edit controls, time controls, and buttons.
A query requires that a time range be specified; all other fields are optional. If a value is
not provided for a specific field, that field is not considered in resolving the query.
Two buttons are available to quickly set or clear values in the Query view:

Checks all the related filter values

Clears all the related checked filter values

Proprietary – See Copyright Page 50 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
To construct a query, the following fields can be used:
• Time: Standard time controls are used to select a time range. There are also time
preset buttons available, to automatically set the time to cover the full range of all
events stored in memory or to specify only those events that occurred within the last
x hours. A query must always have a time range specified.
• Manual End Time: The setting for this check box determines the manner in which a
query end time is specified. When the box is checked, a user must manually set an
end time. When the check box is cleared, the end time is automatically set to the
time of the most-recent Alarm event in the Alarm Viewer’s memory.
• Text: This edit control allows a user to specify a string to look for within the Alarm
text field (case-sensitivity is configurable). Simple wildcarding is allowed by using the
asterisk character. For example, entering a value of “*ack*” within the edit control
results in a match for any Alarm event that has the words “unacknowledged” or
“acknowledged” in it. Strings without the wildcard character require an exact match.
• Advanced Text: The Advanced Text button pops up a dialog box that allows more-
advanced text matching criteria. A user can specify a series of clauses that combine
the use of AND, OR, and NOT operations for text matching. A clause can contain up
to four text strings that are logically connected to one another. Any number of
clauses can be linked together using AND or OR.

• Area Permissions: This control allows the user to switch between filtering on user-
based Read permissions and showing all data. The OFF mode displays data
regardless of permission areas, and the ON mode filters on Read permissions.
When a user switches modes, the entire contents of the Alarm Viewer are emptied
and new data is requested from the e-terrabrowser server.

Proprietary – See Copyright Page 51 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
 This operation affects all viewports running in the e-terrabrowser client since they all
share the same data source. When switching area filtering from OFF to ON, it is
possible to have fewer categories and locations, as these lists are populated based
on data in the Alarm Viewer. Therefore, selecting a category or location and then
submitting the query may result in the Results view not being filtered on these
values, since they do not exist in the permission-filtered cache.
• Locations: A user can select one or more locations using the check box.
Additionally, the NOT, AND, and OR logical operators can be applied to the list of
locations.
• Categories: A user can select one or more categories using the check box.
Additionally, the NOT, AND, and OR logical operators can be applied to the list of
categories.
• Logs: A user can select none, some, or all of the logs using the provided check
boxes.
• Priorities: A user can select none, some, or all of the priorities using the provided
check boxes.
• Submit Query: When pressed, the entered query data is processed, and the
Results view is refreshed to display the filtered data.
• Reset Query: When pressed, all of the entered query data is cleared from the Query
view, and the begin and end time settings are set to the current range of data in the
Alarm Viewer cache.

6.1.2 Results View

The Results view shows the results of the most recently submitted query. You can
configure the order and width of columns shown (see section 6.4 Configuration). You
can also configure the number of rows shown on a page. If the query returns more than
a single page of data, you can page up or down using the Up or Down arrows in the
Query view.
To view the details for a given row, double-click an entry or right-click and select Details.
On the Event Details window (Figure 24) you can view adjacent events using the Up
and Down buttons.

Proprietary – See Copyright Page 52 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
Figure 24. Event Details Window

6.1.2.1 Pasting Events into Microsoft Excel

You can select events in the Results view, copy those events to the clipboard, and then
paste them into Excel.
There are various methods for selecting the events to copy; these methods adhere to
the Microsoft List Control standards. To select single events you can use the “Ctrl + left
click” method. To select a block of events you can use the “Shift + left click” method or
the rubber-band selection method.
To copy these events, right-click any event and select Copy Events. You can paste the
copied events into Excel using standard paste commands.
Using the Alarm Viewer command interface, you can specify the Select All and Copy
Events commands.

6.2 Alarm Viewer Startup

By default, the Alarm Viewer downloads Alarm events from the SCADA application at
startup (this process is configurable and discussed in section 6.4 Configuration).
Once the download is complete, a time-descending list of that data is presented in the
Results view.

Proprietary – See Copyright Page 53 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
6.3 Performance Considerations
Once the initial data is downloaded to Alarm Viewer, use the following guidelines to
optimize the performance of queries and data presentation:
• Time Ranges: The data within Alarm Viewer is organized into segments of time-
ordered collections. If you know that a query should consider events within a specific
time range, then that range should be specified as part of the query.
• Queries Using Text: Text searches are most efficient when using the single text
edit control (labeled “Text”). Within this text box, you can use simple wildcard
searches (using the “*” as a substitution character). Using the Advanced Text dialog
box is more powerful, but it is also slower.
• Records per Page: Restricting the number of records shown on a page has the
greatest effect on performance. Showing up to a few hundred records has minimal
impact on performance; showing a few thousand records has a severe impact on
performance.
• Time Ordering: Sorting the results in time-descending order (the default) is the
most efficient way to display results.

6.4 Configuration
Before you attempt to run the Alarm Viewer, several configuration parameters must first
be set.
The AlarmViewer_config.txt file has comments and examples for these parameters.
This file is in the Alarm Viewer directory under the WebFGCache for e-terrabrowser.
Some parameters are required, while others are optional. Where possible, if a property
is not defined in the configuration file, a default value is provided in the code.
When running the Alarm Viewer within the e-terrabrowser Viewer, e-terrabrowser tells
the Alarm Viewer which configuration file to use.
In e-terrabrowser, the configuration file to use is specified on the Configuration tab in
e-terrabrowser. The Alarm Viewer loads the specified file from the
eterra\webfg\webfgcache\alarmviewer directory on the client computer. If no file is
specified, the Alarm Viewer loads the AlarmViewer_config.txt file in that directory. This
allows each e-terrabrowser client connection to use a different configuration for the
Alarm Viewer.

6.4.1 Required Configuration

The Alarm Viewer does not run properly without setting the following properties in the
Alarm Viewer configuration file:

Proprietary – See Copyright Page 54 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
• DATA_SOURCE: Specifies the data source to obtain data from. Possible values
are:
– SMP: Gets data only from the e-terracontrol application
– SMP_ARCHIVE: Gets data only from archive files
– SMP_ALL: Gets data from either

6.4.2 Redundancy Configuration

For redundancy in the real-time link to work properly, there is a critical configuration
element.
Redundancy is dependent upon the Alarm Viewer TCP/IP link sharing the same socket
with the e-terrabrowser data provider interface. For this to happen properly, the
e-terrabrowser configuration file ADDR ID parameter names must exactly match the
Host1 and Host2 parameters in the Alarm Viewer configuration file.
There is a logical Ole DB Provider key string identification built up using these identifiers
that must match exactly to enable sharing of the sockets. This can be confirmed and
diagnosed using the webfg_client.log file that should be written to the “Start In” directory
for the WebFGViewer executable. When configured properly, the log file contains the
following two lines:
AlarmViewer: Attempting to connect using the ConnectionManager
AlarmViewer: Succeeded in obtaining a connection from the Connection Manager

6.4.3 Permission Configuration

The Alarm Viewer can be configured to show data for the entire system, or for only the
data the logged-on user has Read permissions for. These settings are only applied to
real-time data supplied by the e-terrabrowser server and not data obtained from archive
files.
• PERMISSION_AREA: Specifies the permission startup mode of the Alarm Viewer.
The OFF option displays data for the entire system, and the ON option filters on
permission areas.
• PERMISSION_SWITCH: Specifies if the user is allowed to switch between the two
permission modes during run time. When NO, the Area Permissions controls of the
Query view are inactive; when YES, these controls are active.

6.4.4 Optional Configuration

The following properties affect the behavior of the Alarm Viewer, but they are not strictly
required. They are:
• USE_SERVERS: Specifies whether the e-terrabrowser client top URL is used to
locate the archive files or if separate severs are used. Set to NO if the archive files

Proprietary – See Copyright Page 55 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
 are on the same server as the display files; set to YES if different servers will be
used for the archive files.
e-terrabrowser creates a file control that allows it to download the displays from the
Web server; it is possible to use the same control for the Alarm Viewer, or the Alarm
Viewer can create its own control. Setting this value to NO uses the e-terrabrowser
file control, and setting it to YES has the Alarm Viewer create its own file control.
• FILE_SERVER(n): Specifies the Uniform Resource Locator (URL) for archive files.
This is required if data is to be obtained from archive files. The values for
FILE_SERVER(n) must all be the complete URL to the directory where the archive
files are stored.
For example, assume that the archive files are located at http://server.domain.com/
test/archiveFiles.This requires the following values in the configuration file:
FILE_SERVER1 = http://server.domain.com/test/archiveFiles
In e-terrabrowser, this URL must be a branch off the display directories, in order to
use the e-terrabrowser file control. When the USE_SERVERS setting is NO, this
value must contain the same base URL as the top-level URL in e-terrabrowser.
• QUERY_DIR: Specifies the location on the local machine to save to and load
queries from.
• ARCHIVE_LIMIT: Specifies the threshold size, in bytes, of archive data to
download. When this value is exceeded, the user is notified and given the option to
cancel or continue the download.
• MAX_EVENTS_SHOWN: Specifies the maximum number of records to display on a
single “page”. This limits the size of the scrollable list showing query results. Leaving
this property undefined puts all results on a single page.
• MAX_EVENTS: Specifies the maximum number of events stored in Alarm Viewer’s
memory. When the number of records downloaded exceeds this value, events are
cleared from memory according to the value specified by EVENT_TRIM_AMOUNT.
The default value is 100000.
• EVENT_TRIM_AMOUNT: Specifies the percentage of MAX_EVENTS to release
(see above). Events with the oldest timestamps are released from memory when the
cache trimming occurs. The default value is 10.
• COLUMN_ORDER: Specifies the order and width of columns used for displaying
query results. The default value is shown in the configuration file.
• LIST_BACKGROUND_COLOR: Specifies the background color for the Results
view as an RGB triplet (in decimal). The default value is 212,212,212 (gray).
• CASE_SENSITIVE: Specifies whether text searches are case-sensitive or not. The
default value is OFF (not case-sensitive).
• REFRESH: Specifies whether the Results view and Query view are updated when
refresh events are received from the data server. The default value is ON.

Proprietary – See Copyright Page 56 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
• REFRESH_RATE: Specifies the refresh rate in seconds. The default value is
2 seconds.
• TIME_FORMAT_STRING: Specifies a formatting string for time values. This uses
standard codes for the C Runtime Library function strftime (except for “%R”, which is
used to indicate the repeated hour when Daylight Saving Time transitions to
Standard Time). The default formatting string is “%m/%d/%Y %H:%M:%S%R”.
• REPEATED_HOUR_INDICATOR: This indicator is used for formatting time strings
(if using the “%R” in TIME_FORMAT_STRING) when the repeated hour is
encountered. The default value is “*”.

6.4.5 Miscellaneous Configuration

The following properties are not likely to be used or changed, but they are documented
here for completeness:
• EVENT_GROUP_TIME_RANGE: This is a tuning parameter for Alarm Viewer
memory layout. The default value is 3600.
• TEST_DATA_EVENT_COUNT: Specifies the number of events to be generated
when STARTUP_MODE is set to TEST. The default value is 1000.
• CACHE_MENU: Specifies if the cache summary is available from the right mouse
pop-up menu on the List view.

6.5 Alarm Viewer Operations

There are functions available to the user through the use of pull-down and pop-up
menus. These menus provide the ability to save and load queries, save preferences, set
the font, and get details about the Alarm Viewer.
The Alarm Viewer Help System is also available from a menu; it opens to the Contents
section of Help.
There are also two query commands: one to clear and execute the query, and another
to execute the default query.

6.5.1 Save Query

To save a query, the query must first be applied by clicking the Submit Query button.
Then, when the Save Query menu option is selected, the following dialog box is
presented:

Proprietary – See Copyright Page 57 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
Figure 25. Save Query Dialog Box

The specified name of the query automatically has the extension .avquery appended,
unless the name itself contains the extension. The file is saved in the directory specified
by the QUERY_DIR value in the configuration file. The Include Time Filter check box
specifies whether to store the current time settings with the saved query.

6.5.2 Load Query

To load a query, select the Load Query menu option. The following dialog box is
displayed:

Figure 26. Load Query Dialog Box

When running within e-terrabrowser, the shared queries are loaded from the location
specified by the Alarm Viewer URL on the Configuration tab.
Select the query to load, and click OK. This only loads the query into the Alarm Viewer;
the Submit Query button must still be clicked to execute the query.

Proprietary – See Copyright Page 58 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
6.5.3 Save Preferences
Saves the current font, column settings, and background color to an .ini file that is read
when the Alarm Viewer is started. If this file is not found, the Alarm Viewer uses the
default font setting and column settings provided in the AlarmViewer_config.txt file. The
column settings preserve the column width and order.

6.5.4 Set Font

Provides a Font Settings dialog box to change the font of the Alarm Viewer. This affects
only the font of the column headers and data.

6.5.5 Clear Cache

Removes all of the contents in the Alarm Viewer cache. If real-time data is being used,
the latest data is automatically downloaded after the cache has been cleared.
This should be used when the cache limit has been reached by performing an archive
load and when, as a result, archive loading has been disabled. Clearing the cache
enables the loading of archive files again.

6.5.6 Command Interface (e-terrabrowser Only)

When running the Alarm Viewer within the e-terrabrowser Viewer, there is a set of
functions that can be accessed using the OLEAUTO interface. The required syntax for
these commands is:
OLEAUTO/USER=ALARMVIEWEROCX.ALARMVIEWEROCXCTRL= “command”
The following commands are available:
• LoadData: Creates a new Alarm Viewer window
• SaveQuery: See above
• LoadQuery: See above
• SetFont: See above
• SavePreferences: See above
• About: Provides information about the Alarm Viewer version
• Print: Prints the current contents of the Alarm Viewer
• PrintPageSetup: Issues a Print dialog box prior to printing the current contents of
the Alarm Viewer
• CopyEvents: Copies all the selected events in the Alarm Viewer to the clipboard,
with additional formatting to paste events into Excel
• SelectAll: Selects all the events currently visible in the Alarm Viewer

Proprietary – See Copyright Page 59 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
6.6 Alarm Viewer Printing
The Alarm Viewer has a built-in Print feature that prints the current contents of the
Results view. The printed output is formatted to include a header section that displays
the query settings that produced the results. Each page contains this header followed
by the Results view data.

6.7 e-terrabrowser Integration

When the Alarm Viewer is running in an e-terrabrowser Viewer, it is treated the same
as any other display. This allows the Alarm Viewer to be saved as part of a room and
then later called back up when the room is loaded. When the room is loaded, the Alarm
Viewer returns to the state the Alarm Viewer was in when the room was saved; this is
true for all query data, with the exception of the Time filter. Specifically, all the column,
font, and background color settings, as well as the current filter applied to the data, are
loaded.

6.8 Alarm Viewer Help System

The Alarm Viewer has a built-in Help System that makes use of the Microsoft WinHelp
functionality.
The Help System can be accessed by clicking the right mouse button and selecting the
Alarm Viewer Help option.

The Help mode can also be accessed by clicking the button. This changes the
cursor to a point with a question mark, and clicking any button, enterable field, or check
box provides help on that specific topic.
In addition, selecting a dialog box item and then pressing F1 brings up help for that
item.
The Help System requires that the AlarmViewer.hlp and AlarmViewer.cnt files be
located in the directory that the Alarm Viewer is running in.

6.9 Archive File Management

The SCADA server has the ability to generate archive files that log all events. These
archive files can later be read into the Alarm Viewer.
The alarm archive file functionality can be enabled directly through the SCADA server
(or through XML import). See the SCADA Server Configuration Dialog Box section in
the e-terracontrol Reference Manual: Applications. There is a check box to enable the
functionality and a field to enter the location of the alarm archive files.

Proprietary – See Copyright Page 60 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
6.9.1 Archive File Loading
When a query is executed from the Query view of the Alarm Viewer and the Begin Time
is older than any data that is currently loaded in the Alarm Viewer, archive files are
downloaded (if so configured). All of the necessary files are downloaded to meet the
entered Begin Time to the oldest time already in the Alarm Viewer. When an archive file
is loaded, the entire contents of the file are loaded, so the Begin Time becomes the
Begin Time of the oldest archive file loaded. Archive data does not take permission
areas into consideration when displaying data.

6.9.2 Archive File Publishing

The SCADA Server application places the archive files in the database directory. On an
hourly basis, one archive file is closed and a new archive file is opened. The name of
the archive file represents the beginning and end times of the data range in the file.
When an archive file is closed by SCADA, it must be moved to a Web server so the
Alarm Viewer has access to it. The Web server must contain an archive_list.txt file that
contains the directory reading of all the available archive files. The directory reading
needs to be performed with the following command:
dir /-c *.csv > archive_list.txt
This command is performed frequently, to ensure that the archive_list.txt file is accurate.
This can be done using various methods; the test configuration uses Windows Task
Manager to execute the command every x minutes.
When archive files are required to meet a query, the Alarm Viewer opens the
archive_list.txt file and determines which files to open based on the time values in its
title. The title of an archive file consists of a begin time and an end time, which
represent the time range of the events contained in the archive file. Therefore, an open
archive file (containing “_endtime_” in the title) must never be published on the Web
server.
Archive files from both the primary and standby Alarm applications need to be published
to the Web server in the event of a failover.

Proprietary – See Copyright Page 61 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
Figure 27. Archive Web Server Configuration

This figure demonstrates the recommended method for publishing archive files to a
Web server. Each Web server requests the archive files from both the primary and
standby e-terracontrol servers.
Since the archive files are named after their time values, there should never be a case
where two files have the same name on different machines.
There are third-party applications that perform this functionality, but they must have the
ability to exclude archive files that are still open.
The Rsync software was used to test this configuration. The Rsync software is
described in Appendix A Configuring Rsync for Use with Alarm Viewer.

Proprietary – See Copyright Page 62 Alarm Viewer Application

e-terracontrol Reference Manual: User Interface Applications
Appendix A. Configuring Rsync for Use with Alarm
Viewer
This appendix describes how to configure the Rsync software, to publish archive files
from the e-terracontrol server to a Web server.

Note: This appendix assumes that both the e-terracontrol and Web servers are
running on Windows Server 2008 R2 or Windows Server 2012 R2.

For more information about Rsync, visit:

http://rsync.samba.org

A.1 Rsync Scheduled Task

Using the Windows Task Manager, a batch file should be run every few minutes. This
batch file executes the Rsync command to retrieve the archive files from the
e-terracontrol servers. This batch file has one Rsync command for each e-terracontrol
server and another command to generate the archive_list.txt file.
Rsync uses various command-line arguments to determine the type of synchronization
to perform. The key feature of Rsync is the ability to detect only the differences between
the directories before moving any files.
Below are the commands from a sample batch file:
rsync -t -r -a --exclude="*endtime*" habXX@ems1::alarmarc
D:\WebFGServer\AlarmArchive

rsync -t -r -a --exclude="*endtime*" habXX@ems2::alarmarc

D:\WebFGServer\AlarmArchive

dir /-c D:\WebFGServer\AlarmArchive\*av* >

D:\WebFGServer\AlarmArchive\archive_list.txt
• The -exclude directive is to prevent the open archive files from being published on
the Web servers.
• The -t, -r, and -a arguments are required to set the correct archiving settings to only
transfer the new files over.
• habxx@ems1 directs Rsync to look for the Rsync application running on machine
“ems1” running as user “habXX”.
• alarmarc is an alias for the remote directory on “ems1” that is defined in the
rsync.conf file.
• The final parameter is the destination directory on the Web server.

Proprietary – See Copyright Page 63 Configuring Rsync for Use with Alarm Viewer
e-terracontrol Reference Manual: User Interface Applications
The directory reading uses the /-C option to remove commas from the listing of the file
size that the Alarm Viewer uses, to determine if the download threshold has been
violated.

Proprietary – See Copyright Page 64 Configuring Rsync for Use with Alarm Viewer
e-terracontrol Reference Manual: User Interface Applications
Index
A R
Alarm Viewer, 49, 51, 52, 53, 54, 55, 57, 59, 60
Rsync Configuration, 63
ActiveX Control, 49
archive files, 60
configuring, 54 S
e-terrabrowser, 49, 60
sequence of events. See SOE
Help, 60
Simulator, 22
operations, 57
configuring, 23
performance considerations, 54
user interface, 23
printing, 60
SMP Display Linker. See Display Linker
query view, 50
SOE Compiler, 5
results view, 52
command-line arguments, 5
running, 57
Process Starter, 10
startup, 53
starting, 5, 10
user interface, 50
tasks, 5
user interface, 11
C Windows shortcut, 5
work orders, 12
CFE Reader, 5, 13
SOE files, 5
Chart Configuration text file, 31
SOE Viewer, 5, 13
creating, 31
command-line argument, 13
configuring, 17
D Process Starter, 15
starting, 15
Display Linker, 28
user interface, 17
user interface, 29
Windows shortcut, 13
using, 29

H V
viewing event data, 49
historical data
Virtual Chart System, 31, See Virtual Chart System
export to file, 3
command-line arguments, 32
viewing, 2
Virtual Charts
history files
Chart Configuration text file, 31
configuring, 1
configuring, 35, 36
creating, 1
customizing, 31
viewing, 2
display window, 35
Process Starter, 32
M running, 31
Measurement History Application, 1 starting, 31, 32, 34
configuring, 3 user interface, 36
setting defaults, 3 Windows shortcut, 34
user interface, 1
W
Q work orders, 12
querying event data, 49

Proprietary – See Copyright Page 65 Index

e-terracontrol Reference Manual: User Interface Applications