Trihedral Engineering Ltd.

Developer's Guide (part 1)

Copyright Trihedral Engineering Limited, 2013
All rights reserved.
10.2

PRINTED IN CANADA

Head Office Trihedral UK Limited Trihedral US Limited

Trihedral Engineering Limited Scotland Office Suite 160

1160 Bedford Highway, Suite 400 Glover Pavilion, Campus 3 7380 Sand Lake Road
Bedford, Nova Scotia Aberdeen Science Park Orlando, Florida
Canada Balgownie Drive, Aberdeen 32819
B4A 1C1 UK, AB22 8GW

Telephone: 902-835-1575 Phone: +44 (0) 1224 258910 Telephone: 407-888-8203

Toll Free: 800-463-2783 FAX: +44 (0) 1224 258911 FAX: 407-888-8213
FAX: 902-835-0369

Support: [email protected]
Sales: [email protected]
Contents
How to Build an Application 5
The Development Process ..................................................................................................... 5
Fundamentals: The Structure of VTS Applications ................................................................ 7
Application Types ................................................................................................... 7
Application Layers.................................................................................................. 8
Creating and Managing Your Applications.......................................................................... 12
Use the VTS Application Manager (VAM)............................................................ 13
Adding Applications ............................................................................................. 15
ScadaAce Applications ......................................................................................... 21
ChangeSets - An Application in One File .............................................................. 25
Remove an Application from the VAM ................................................................. 32
Make a Backup of Logged Data ............................................................................ 33
Open the Application Configuration Dialog........................................................... 34
Set Application Properties ..................................................................................... 35
The VTS Version Control System ......................................................................... 44
Import File Changes.............................................................................................. 57
Manage Files with the File Manifest ...................................................................... 58
Import/Export Files ............................................................................................... 59
Find Tools in the Configuration Toolbox ............................................................................ 63
Moving the Configuration Toolbox ....................................................................... 64
Pick Graphics and No Tool ................................................................................... 65
Libraries ............................................................................................................... 65
Application Configuration Button ......................................................................... 65
Deploy Changes Button ........................................................................................ 66
Cursor Coordinate Display .................................................................................... 66
Drawing Tools Library.......................................................................................... 66
The VTS Graphic Editor ................................................................................................... 101
Using the Graphic Editor’s Menu ........................................................................ 102
Multiple Levels of Control .................................................................................. 104
Control via Tags, Expressions and Parameters ..................................................... 105
Using the VTS Graphic Editor ............................................................................ 108
Clipboard Tools .................................................................................................. 123
Drawing Graphic Objects .................................................................................... 124
Alignment and Positioning Tools ........................................................................ 140
Working with Objects ......................................................................................... 146
Working with Colors........................................................................................... 150
Working with Parameters .................................................................................... 156
Pages - Adding and Editing .............................................................................................. 157
Quick Links: Common Tasks for Pages ............................................................... 158
Access the Page Configuration Dialogs ............................................................... 159
The Pages Context menu..................................................................................... 160
Working with Application Pages ......................................................................... 164
Properties of Application Pages........................................................................... 165
Link to Pages with the Page Hotbox .................................................................... 171
Link to Pages with the Page Button ..................................................................... 175
Close Pages with a Button ................................................................................... 177

Developer's Guide (part 1) Contents • iii

 Pages Included with VTS Applications................................................................ 178
The Menu Editor .............................................................................................................. 208
Add a Page to the Menu ...................................................................................... 209
Add a Divider to the Menu .................................................................................. 211
Add a Sub-Tree to the Menu ............................................................................... 212
Edit the Parameter Values of a Page .................................................................... 213
Open the Page Properties Dialog for a Selected Page from the Menu Editor ......... 214
Tags Properties Reference ................................................................................................ 215
Tag Browser ....................................................................................................... 216
Fundamental Tag Features .................................................................................. 222
Working With Tags ............................................................................................ 245
Parent-Child Tag Structures ................................................................................ 256
Import and Export Tags ...................................................................................... 267
Tag Types Referenced by Category ..................................................................... 272
Port Tags ............................................................................................................ 273
Communication Driver Tags ............................................................................... 283
Input Tags .......................................................................................................... 381
Output Tags ........................................................................................................ 418
Alarm System Tags............................................................................................. 455
Alarm Dialer System Tags .................................................................................. 464
Data Logging and Reporting Tags ....................................................................... 476
Calculation and Inquiry Tags .............................................................................. 497
Station and Site Tags .......................................................................................... 533
Configuration Tags ............................................................................................. 553
Tag Types Listed in Alphabetical Order .............................................................. 561
Tag Groups ......................................................................................................... 564
Customization of Tags ........................................................................................ 569

Index 571

iv • Contents Developer's Guide (part 1)

How to Build an Application

In this section of the Guide, VTS and VTScada developers will find all the information they need in order to build
monitoring and control systems.
The chapters follow the development process, beginning with VTS terms and definitions that you will need to know. The
final chapters include development examples that you can learn from or copy for your own applications.

Note: If your application runs on more than one computer, and you intend to do on-going development, then it is
extremely important that you understand the VTS Version Control system and how changes are deployed (or not)
between servers.

The Development Process

Most VTS development projects will follow a similar process. The steps presented here are meant to provide a set of
guidelines for this process, but are not intended to be taken as absolute rules. Every project will have its own
requirements and every developer will have a preferred system of work.
For each step of the following general development process, links are provided to relevant sections of this guide. The
following does not provide an exhaustive list of all the elements that might be included in a VTS application.

Step Relevant reference materials.

Preliminary design Completed system requirements, hardware reference documents,
etc. Before creating a monitoring and control interface for a
system, you must have a good technical knowledge of the I/O
hardware systems and at least a basic idea of what you want the
completed VTS application to do, including how the user interface
should look.
You should also understand the fundamental structure of VTS
applications. See the topics: Application Types and Application
Layers.
Start a new application While some sites start their applications from scratch, others
install applications that were built for them or else upgrade older
applications. The topic, Creating and Managing Your Applications
will describe how to build and work with applications.
Create the tag tables You must understand the addressing format for your chosen I/O
hardware, along with the communication driver(s) used before
creating an application to monitor and control it (see step 1).

Developer's Guide (part 1) How to Build an Application • 5

 Tags are the building blocks of a VTS application. The topic Tags
Properties Reference will tell you everything you need to know
about creating the tag tables.
Create display pages for the This step and the next two are generally taken together, one page
monitoring and control at a time.
elements
You can learn about creating application pages in Adding and
Editing Pages.
Links to those pages can be created through the menu, Editing the
Menu or with hotboxes: Linking to Pages with the Page Hotbox.
Lay out the page design The VTS Graphic Editor is the primary tool for creating design
with graphic elements and elements on an application page. Page design can be enhanced by
alignment tools Drawing Graphic Objects such as rectangles, circles and lines.
Alignment and Positioning Tools are available to help bring a tidy
look to your user interface design. The topics Working with
Objects and Working with Colors provide even more information
to help you create an effective user interface.
Draw the tags For every type of tag, there are several ways that it can be drawn.
Numeric displays, animated symbols such as tank levels, buttons,
text and colors can all be employed to create a dynamic user
interface. The topic Drawing Tags provides a description of each
tag drawing method. You can also create your own tag drawing
methods with User Draw Methods.
Add alarms Alarms notify operators when values move outside defined
tolerances. Some tags such as Analog Status Tags include built-in
alarms while others require that an Alarm tag be added. (Alarm
Tags)
The Alarm Page provides the primary operator interface for
viewing and acknowledging alarms, but you can also add alarm
monitoring elements to any application page using the Alarm
Tools Library.
Log data The Historian Tag is used to record a history of tag values and
then display that data in a report. The Reports Page and the
Historical Data Viewer Page are two tools provided to help you
review logged data.
Install a modem Modems are used to communicate with remote I/O hardware or
to phone off-site operators when alarms occur. The chapter
Working with Modems provides a complete overview of how to
install and configure a modem. Roster tags are used to control
who is phoned/paged/emailed for alarms in a particular area.
Secure the application Operator privileges are granted on a user-by-user basis. The
chapter, Activating and Configuring Security, describes how to
create and configure user accounts.
You can extend VTS’s security options by creating your own
Application Privileges that apply only to pages or tags within
your application.

6 • How to Build an Application Developer's Guide (part 1)

 Distribute the application For purposes of load distribution and redundancy, a VTS
between primary and application can be run on multiple servers and workstations. The
backup servers. chapter, Configuring for Multiple Workstations covers everything
that a developer needs to know about configuring servers.
Enable the VTS Internet A browser interface is provided that allows you to operate your
Server system from any workstation on your intranet or, (if connected to
the internet) anywhere in the world.
Review the topic Configuring for Internet and Mobile Access to
learn how to configure the VTS Internet Server.

Fundamentals: The Structure of VTS Applications

Before starting to build applications, it is helpful to know the terms used in VTS, the basic structure of all applications
and how applications are managed. The topics in this chapter will describe these fundamental features of VTS and more.

Application Types
There are two fundamental types of VTS application: Script and Standard.

Script applications are those that are written in a text editor using VTS script code. Script applications are not based
upon the VTS Library Layer and therefore do not have access to the Display Manager, Configuration Toolbox, Alarm
Dialer or any of the other tools and features provided in the VTS Layer.
Several useful script applications have been included with every copy of VTS. These include debugging and monitoring
tools such as the Source Debugger, the VTS Internet Monitor, etc.
To learn more about how to create script applications, please refer to the chapter, How to Program Customized Tools

Standard applications are those that are based on the VTS Library layer. As such, they inherit the entire set of features
and functionality built into the VTS layer, including:

• The display manager

• Page navigation including menu, page change buttons & page history buttons.
• The configuration toolbox
• Tag browser (add, copy, modify, delete and draw tags)
• Page libraries (add, copy, modify and delete pages)
• Menu editor for controlling the menu.
• VTS Graphic Editor (VGE – configures the appearance of all objects on a page)
• Geometric drawing tools (rectangle, ellipse, line, etc.)
• Alignment and spacing tools (align objects left, right, top or bottom. Space objects horizontally or vertically)
• Default Application Pages including:
• Alarm page (view different alarm categories, manage alarms and alarm sounds)
• Historical Data Viewer page (plot tag data on a graph)
• Reports page (generate a variety of report types in varying output formats from a selection of tag data)
• Operator Notes page (create and view time-stamped notes)

Fundamental to standard applications is the concept of layering. A standard application may be built directly upon the
VTS Library, or it may be built upon and inherit features from another application. That other application may in turn be
built upon yet another application. VTScada is an example of an application build on the VTS Library. When you select

Developer's Guide (part 1) How to Build an Application • 7

VTScada as the type for your new applications, you gain all the features in the VTS Library and all the features of the
VTScada layer.
See: Application Layers.

Local vs. Remote Applications

A further distinction between VTS application types is whether they are "local" or "remote". If local, the application runs
on only a single workstation. If remote, the application is designed to run simultaneously on multiple servers and
workstations, sharing data and tasks between them and automatically continuing without interruption should a server fail.
The application itself is the same whether local or remote – the difference is in the presence or absence of a server list.
See: Working with Remote Applications.

Application Layers
While the development tools provided in the VTS Library are useful for a wide variety of industries, you may also
require specialized tools. System integrators will often create custom tag types, drivers, wizards, graphics and other
specialized tools for a particular industry. These tools can be used in other applications through the VTS layering system.

A layer (or "OEM layer") is any VTS application. In practice, OEM layers are designed specifically to add custom
features for use in many other applications rather than being designed to run by themselves.
In a situation where you intend to simultaneously run more than one application based on a common OEM layer, you can
configure security for the OEM layer and share its security database with the applications that are based on it.

When creating a new VTS application, a required step is to select its type. This is how you choose the layer that the new
application will be built upon and inherit features from.

8 • How to Build an Application Developer's Guide (part 1)

Since every new application is based upon an existing application, it is possible to create a chain of many such layers,
each inheriting the features of all the layers below it.

Benefits of Application Inheritance

The twin benefits that you gain from the VTS layering system are reusability and extensibility:

Reusability: Inheritance from lower application layers to upper layers means that the custom tools that you
create for an OEM layer can be used in other applications. You do not need to re-create those tools or features
for every application.
Extensibility: New functions can be added to existing objects such as tags and drivers without changing the
structure of applications built on the OEM layer. For example, if you extend the feature set of a custom tag in an
OEM layer, applications built on that OEM layer will continue to work without interruption and, will have
access to the new feature set in your custom tag.

Application inheritance should be used when:

• More than one application may require access to a set of tools developed for your industry.
• You expect that an application will be part of a long-term development cycle.
• You are an OEM or system integrator who develops customized applications for a wide variety of clients, and you
wish to personalize the VTS interface to reflect your company's practices.

The VTScada Layer

VTScada is a specialized VTS application that has been designed specifically for users in the water and wastewater
industries. (Its features have been found useful by developers in a wide variety of other industries.)
The VTScada layer is based upon the VTS layer and therefore includes all of the features of a standard application. In
addition, the VTScada layer provides:
• station pages
• a communications data page
• a call-out list page
• extra tags
• extra reports
• enhanced support for WAP devices such as mobile phones.
If you select VTScada as the type for your new applications, you gain access to all of these features.

Developer's Guide (part 1) How to Build an Application • 9

Inheritance Across Layers
New applications inherit object definitions and application properties from the layers that they are based on. They
normally do not inherit instances of objects (except for tags). So, for example, if your OEM layer has a custom page,
your new application will be able to see those pages in the OEM layer, and can add them to the menu, but will not be
able to edit the page. The OEM page is visible from the application, but not a part of the application.
The same rule holds true for bitmap files, device drivers, wizards and any other custom code. All of these objects in the
OEM layer are visible from the new layer, but their files are not copied from the OEM layer to the new application. The
new application remains dependent upon its OEM layers to supply various objects rather than becoming a complete, self-
contained unit. The exception is tag instances - these are copied from the OEM layer to the new application when that
new application is created.
This becomes important when you are copying an application from one computer to another. You must copy the
application and all OEM layers upon which it is based in order to have all the objects and source code on the new

10 • How to Build an Application Developer's Guide (part 1)

workstation. Note: the exceptions to this rule are the VTS and VTScada layers, which are already present in every VTS
installation and therefore do not need to be copied.

Note: There is a way to cause instances of objects from the OEM layer to be copied to the new application. You can do
this by including a Template ChangeSet file with the OEM layer. See: OEM Template ChangeSet.

Propagation of Changes Through Layers

An application that is based on an OEM layer uses code and properties that remain in that OEM layer. Therefore,
changes to the code of the OEM layer will be seen in all of the applications that are built on it.
The following changes to an OEM layer will propagate through to dependant applications:
• Changes to any application properties that are not found locally in the dependant application’s copy of the Settings
files.
• New tag types added to the OEM layer.
(Be careful: new tag instances are not propagated. Tag types are.)
• New pages are not copied to the child application, but they can be seen.
If you add a new page to an OEM layer application, then open the child application, you will be able to add that
page to the child application’s menu and view it. You will not be able to edit the page within the child
application since the page file does not become a part of the child application.
Note that you will need to deploy changes in the OEM layer. A restart will only need to be done if changes have been
made to the Settings.Startup file. See: Local Changes versus Deployed Changes.

Changes to the OEM layer's tag database (that is, new instances of tags) will not be seen by child layers. Also, files and
other information specified in the OEM layer's Template.ChangeSet file will only be copied to a new application when
that new application is created. If the new application contains its own copy of a file or an application property, it will
ignore any changes made to those items in the OEM layer. See: OEM Template ChangeSet.

Application Files and Folders

Files within an application are divided between "user files" and "working files". This chapter discusses user files. The
working set of files must never be edited directly – attempting to do so will damage your application.
Most user files may be edited using a text editor, but be aware that edited files must be imported into an application's
working set before those changes will go into effect. The Import/Export Files dialog is not available in runtime-only
versions of VTS. Also, access to the Import/Export Files dialog is controlled by the Security Manager. Only users with
the Configure privilege may import an edited file. See: Import/Export Files.
As you work within VTS, it will automatically update the user files to reflect changes to the working set.

Warning: The working set of files and the change history repository are stored within the .sync folder. Never attempt to
directly edit any file in that folder structure. Any attempt to do so will damage your application.

Folders:
Pages Contains the source code for all of the application pages. You may edit these files and import
your changes to modify an application.
PlatformInfo Contains information about your VTS installation, the application and the computer you are
running the application on. These details may be viewed by opening the VTS Application
Manager (VAM), clicking on Properties, then on Information.
Any user changes to the files in the PlatformInfo folder will be ignored by VTS.
Resources Contains logo and button images used by VTS.

Developer's Guide (part 1) How to Build an Application • 11

Bitmaps Not created by default. If you are adding your own custom bitmaps for display in an
application page, you will create this folder and store the bitmaps here.
Tags If the setting, ExportTagFilesToUser is set, this folder will contain an up-to-date copy of all
the tag files. This copy cannot be imported, but serves as a reference and can be used in
recovery should the .sync folder be damaged.
Data Contains data output files generated by the application including log files, retained data files
and network values. Copy this folder to make backups of your application's data.

Files:
Accounts.Dynamic Created only after security has been enabled. Contains encrypted account information. User
edits to this file will be ignored.
Application.version Stores information about the current revision of the application. User edits to this file will be
ignored.
AppRoot.SRC The main source file for an application. Lists top-level variables and modules in use by the
application. Edits may be imported. This file was named "AppMod.SRC" in earlier versions
of VTS.
Default.ROS Contains the default call-out roster for the VTS Alarm Dialer.
GroupName.SRC The source code for any user-defined drawing methods (groups) in the application will be
stored in these files, where the name of the drawing method is used instead of "GroupName".
User edits to these files may be imported.
Lexicon.VLX If you customize the speech lexicon within an application, your edits will be stored in
Lexicon.VLX.
PageMenu.TXT Stores the application's page menu. This file replaces Menu.TXT and Menu2.TXT from
earlier versions of VTS. Edits may be imported.
Servers.RPC Contains the list of configuration servers. This text file is in XML format. User edits may be
imported, but must be made using correctly formed XML.
Settings.Dynamic Contains application properties (formerly, configuration variables) whose value may be
changed without re-starting the application. This file follows the same structure as the
obsolete Config.INI
Settings.Startup Contains application properties (formerly, configuration variables) whose value can only be
changed by re-starting the application. This file follows the same structure as the obsolete
Config.INI

Creating and Managing Your Applications

Application management involves many tasks. These may include:
• Adding new applications, whether creating, copying, or installing a new workstation or backup server in an existing
remote application.
• Moving or copying an application from one location to another.
• Updating the list of applications in the VTS Application Manager (VAM).
• Creating a backup.
• Setting overall properties.
• Controlling version changes, deploying, reverting or merging updates.
• Importing or exporting files (drivers, bitmap images, services, etc.)
• Managing the files that are part of the application.
These topics and more are covered in this chapter.

12 • How to Build an Application Developer's Guide (part 1)

Use the VTS Application Manager (VAM)
The primary tool for both creating and managing applications is the VTS Application Manager (VAM).

The VAM provides many functions. The following table will help guide you through its features. Note that the VAM is
organized such that the command buttons along the right edge apply to selected applications. Buttons along the bottom
edge apply to VTS itself, rather than to any specific application.
You can read the topics in this chapter from beginning to end in order to gain a complete understanding of how to create
and manage your applications, or you can use this table to skip ahead to topics of interest.

Create Applications The Add button provides access to several options for creating an application. You
can build applications from scratch, copy a remote application to this workstation,
add an existing application to the VAM, or use a ChangeSet to create a copy of an
application.
See: Adding Applications
Start and Stop Applications The Start and Stop buttons in the VAM are used for this purpose. You can also
configure an application to start automatically.
See: Starting and Stopping.
Configure Application Application properties (formerly known as configuration variables) control how
Properties your application looks and works. These values are set using the Application
Properties page, accessed through the Properties button of the VAM.
See: Set Application Properties

Developer's Guide (part 1) How to Build an Application • 13

Copy or Clone Applications You can use ChangeSets to create a copy of your application for backup or
distribution purposes. A clone is a special case of a copy, often used if you want a
duplicate to experiment with.
See: Copy an Application with ChangeSets
Version Management VTS uses a version control system to maintain a history of every change made to an
application. You can restore the application to an earlier stage of development at
any time.
Because of how the versioning system works, changes made outside of the VTS
user interface, such as file edits or modifications to the tag database, must be
imported before they are put into effect and under version control. Also, new files
such as bitmap images that are added to an application must be explicitly imported.
See:
The VTS Version Control System
Import/Export Files
Import and Export Tags
Manage Files with the File Manifest
Review Application Details Detailed information about your application, the version of VTS that you are
running and the workstation that you are running it on, are all available through the
VAM. This includes useful information about what features your VTS license
provides and can be helpful when debugging problems.
See: Learn About Your Copy of VTS
Secure Your Application VTS security uses a privilege system whereby users are assigned specific rights
controlling what they can do within the program.
See: Activating and Configuring Security
Manage Server Lists Many VTS applications are designed to run simultaneously on several servers and
workstations. This allows VTS to run more efficiently by sharing the resources of
several machines, and provides security in the form of automatic fail-over should a
server fail.
See: Working With Remote Applications
Backup Logged Data VTS provides powerful data logging abilities. You can configure your application
to VTS's own storage format, or you can configure for logging to be done using one
or more commercial database programs (even multiple different programs
simultaneously). See: Make a Backup of Logged Data.

Hide the VAM

In some installations, management may prefer to make the VAM inaccessible once an application is running. This might
be done for security purposes, to deny operators the ability to access the VAM's control features.
There are several options available to you to hide the VAM, configure applications to auto-start, etc. The chapter
Customizing VTS contains instructions for all of these options including Configuring the VAM to be Hidden.

Change the VAM's Color Theme

The VAM may be given any one of two dozen color themes. You can choose a theme that matches your corporate
colors, or choose one for the sake of aesthetics.
To change the theme, click on the Color Themes button on the lower taskbar of the VAM:

14 • How to Build an Application Developer's Guide (part 1)

The Color Themes dialog will open as shown:

Select a theme from the drop-down list. The VAM will be updated immediately to match your theme selection. Your
choice of theme for the VAM will also be applied to all applications except those that have been assigned a color theme
of their own. See: Select a Color Theme.

Adding Applications
When we refer to "adding an application" we may mean any of the following tasks:
• Create a new application, either from scratch or based on an OEM layer
• Add an existing application to the VAM's list of available applications.
• Install an application from a ChangeSet file, either to…
o Restore a backup
o Create a clone for testing and development
o Install an application on a new workstation
• Retrieve and install an application from a remote server
The first step for all of these tasks is to click on the Add button in the VAM.
The Add New Application opens as shown:

Instructions for each of the choices are provided in the following topics.

Create a New Application

Select the Create New option in the Add New Application dialog, and click OK. (illustration: Adding Applications) The
Add Application Properties dialog will open as shown:

Developer's Guide (part 1) How to Build an Application • 15

Every application must have a name, a path which is the folder it will be stored in, and a type which is the Layer that it
will be based upon.
The name should describe the application's purpose. Letters, numbers, spaces and certain punctuation characters are
permitted, but you will find it is easier to work with your application if you choose a straight-forward name, using just
one or two words. See: Valid Application Path Characters.

The path will automatically change to match the name after you press enter or tab to exit from the Name field. Spaces
and punctuation symbols will be removed. You are free to provide a different name for the path if you choose but, if the
path matches the name it will be easier for you to find the application on your workstation.

The Type is a drop-down list of all the standard applications currently available in the VAM. By choosing an existing
application, you build your new application on it as a layer, inheriting all of its features. The first two entries in the list
will always be "Standard Application" and "VTScada". See: Application Layers.

After providing the Name and Type, and optionally changing the path, click OK. The new application will be created and
added to the list of Available Applications in the VAM.

Note: Developers who are familiar with VTS prior to release 10 may expect a more complicated version of the New
Application Properties dialog. Options such as the initial graphics page and choices of configuration server are set after
the application has been created, using the Properties menu.

Valid Application Path Characters

Application path names may consist of alphanumeric characters, and can include the punctuation key symbols (i.e.
decimal (.), and comma (,)), and symbols created using the number keys (i.e. as the number hatch (#), and underscore
characters (_)).
If the application path name is based on the application's name, VTS automatically removes any invalid characters
and/or spaces from the application path name.
The characters indicated below are invalid, and may not be used in application path names. If you choose to enter a
custom application path, you cannot use these invalid characters or spaces.

Invalid Application Path Characters

Colon :
Less Than <
Greater Than >
Pipe |

16 • How to Build an Application Developer's Guide (part 1)

Valid Page Title Characters
Valid characters that may be used in page titles consist of any combination of:
• Alphanumeric characters (i.e. A through Z, and/or 0 through 9)
• Spaces
• The underscore character ( _ )
• The number hatch (#)
• The dollar sign ($)
• The caret (^)
• An asterisk (*)
• The decimal character ( . )
The page file name is based upon the page name with invalid characters and spaces removed. Valid page file name
characters are identified in the section that follows.

Valid Page File Name Characters

Valid characters that may be used in page file names consist of any combination of:
• Alphanumeric characters (i.e. A through Z, and/or 0 through 9)
• The underscore character ( _ )
• The decimal character ( . )
Page file names cannot include other symbols (i.e. dollar sign ($), number hatch (#), or equals (=) characters); spaces; or
strictly numeric characters. Because these symbols are acceptable in page titles, and the page file name is automatically
based on the page title, VTS strips any invalid characters and/or spaces when generating the page file name.

Find an Existing Application

Select the Find Existing option in the Add New Application dialog, and click OK. (illustration: Adding Applications)
The Found Applications dialog will open, as shown:

The VAM does not search your computer, automatically finding and adding all the applications that are present. You
must choose to add each application that you want to see in the list of available applications in the VAM.

Developer's Guide (part 1) How to Build an Application • 17

The Found Applications dialog offers a quick way to search for a given application. In the name field, type the first letter
of the name you are looking for and a *. Press enter and the dialog will search the VTS folder for all applications
beginning with that letter.

You can also use the Browse button in order to look through the hard drive for applications. When looking for an
application, you will select the application's folder rather than any particular file.

Since applications are found based on the path that they are stored in, the Show Path option allows you to see that path
rather than the name of the application.

Note: You can remove or hide applications from the VAM's list without deleting them from your computer. See:
Removing an Application from the VAM.

Get an Application from a ChangeSet

A ChangeSet is a condensed record of application development. Depending on how the ChangeSet was created, it may
contain either a complete record of all application development or only a snapshot of the final product at the time that the
ChangeSet was created. In either case, a ChangeSet file contains all the information required to create a new application
that is identical to the one that the ChangeSet was created from. (Note: ChangeSet files do not contain logged data.)
See: Copying an Application - ChangeSets

To create an application from a ChangeSet, select the Get From ChangeSet option in the Add New Application dialog
(illustration: Adding Applications), and click OK. The New Application Properties dialog will open, configured similar
to the following:

18 • How to Build an Application Developer's Guide (part 1)

You can use the Browse button to locate ChangeSet files, including those stored on FTP sites. (Note: the ability to access
FTP sites using the Browse button is not available if you are running VTS on the Windows Vista™ operating system.)
ChangeSet files will always have the extension, ".changeset".

The application name is defined by the ChangeSet and cannot be changed here.
The Path will default to the application name (minus spaces and punctuation symbols), but you may change it if you
want.
The Type is pre-determined by the application from which the ChangeSet was created.

Warning: If the application from which the ChangeSet was created is based on an OEM layer, you must first install that
OEM layer before adding the ChangeSet file. ChangeSets do not include OEM layers.

Three of the most common uses of ChangeSet files are, to create a backup of the application (excluding logged data), to
create a clone of an application on the current workstation, and to create a copy that can be installed on other computers
that are not networked.

Note: If you are running an application on multiple servers (a "remote" application) do not use ChangeSets to install the
application on each workstation. Install it on one, then use the instructions in the next topic, Get an Application from a
Server instead.

Clone an Application from a ChangeSet

Everything that was described in the previous topic, Get an Application from a ChangeSet is also true of a clone created
from a ChangeSet. The one difference is that a clone may co-exist on your network with the original application and no
configuration changes will be communicated between the two. This is not true of a simple copy, even if the copy is
made on another machine - if the two copies are able to communicate, they will.
By working in a cloned application, you can test, debug and experiment, all without risk of changing the original
application.

Get an Application from a Server

When an application is running on a workstation configured as the Primary Configuration Server(*), a client can connect
to that server and obtain a copy of the application. The primary configuration server ensures that all clients are
continually synchronized, so that every PC running the application has the same data and is running the same version of
the application.
Reasons to run an application on more than one server include load distribution and redundancy in case of server failure.
To get an application from a server:
1. Select the Get From Server option in the Add New Application dialog, and click OK. (illustration: Adding
Applications) The Choose Server dialog will open, as shown:

The drop-down list will be populated with the names of all the computers running VTS that your current
workstation is able to see.
2. Select the name of the computer running your application from the drop down list, or type in the machine name.

Developer's Guide (part 1) How to Build an Application • 19

3. Click the OK button.

The Find Servers dialog will open:

VTS will scan the workstation and report how many applications are present on it, including the number
currently running.
4. Click the Inquire button.
A list of the applications counted in the earlier dialog box is shown. Select the application that you want to copy
from that server and click the Acquire button.

The application will be copied to your workstation and added to your list of available applications in the VAM.

See: Configuring for Multiple Workstations.

20 • How to Build an Application Developer's Guide (part 1)

ScadaAce Applications
ScadaAce is a VTS OEM layer, designed for use with Motorola hardware. For those building Motorola Remote
Terminal Unit (RTU) systems, the ScadaAce layer simplifies the configuration process.
Upon first starting a new application that is based on the ScadaAce layer, you will be prompted to configure a Motorola
Gateway IP tag. Every ScadaAce application must have one (and only one) Gateway IP tag. By convention, its name
will always be "GW".

After providing the IP address of the gateway unit, and optionally choosing to enable the system time synchronization
feature, click OK. Immediately, you will be prompted to begin entering site information. Click the Add button.

Developer's Guide (part 1) How to Build an Application • 21

New sites may be added at any time using the Add New Site button at the bottom of the Sites page. This method will
always begin by asking you to place a pin on the map to show where the site is located.
Note also, the Manage Sites button at the bottom of the Sites page. This re-opens the Manage Sites dialog, allowing you
to add, edit or delete sites. This method does not prompt for a site location.

The Area field is automatically made the same as the name (RTU_1 in this example). This is very useful when viewing
the alarm list since it is the area value that allows you to distinguish alarms in one site from another.
The RTU ID value should match the ID value of the hardware.

Following the initial configuration of the new site, as shown, you will be able to configure the inputs and outputs of this
instance.

22 • How to Build an Application Developer's Guide (part 1)

Related Information:
ScadaAce Site Tags - provides a description of the configuration fields and guidelines for use.

View ScadaAce Sites

An overview of your ScadaAce sites is provided using a Sites page. This provides a list of configured sites (left side of
screen) and a map showing the location and current status of each.

Clicking on any RTU in the left column, or on its matching pin within the map (if a location has been configured) will
cause the site details page to open. These are created automatically for you, with each new site that you add.

ScadaAce Site Monitoring Pages - RTU Tab

Developer's Guide (part 1) How to Build an Application • 23

The RTU tab provides general information about the RTU at the site, including the list of faults, device statistics
(available via two buttons), and other information.
Along the base of this page (regardless of tab selected in the upper portion) are two tabs: one will show the list of alarms
at the site, the other may be used for adding operator notes, specific to this site.

ScadaAce Site Monitoring Pages - IO Tab

All analog and digital I/O tags that belong to the site will be listed on this tab. You can click the Manage I/O button,
which will be found at the bottom-center of the list, to re-open the site configuration dialog, where you can add, edit and
remove any of the I/O tags.

ScadaAce Site Monitoring Pages - Digital Statistics Tab and Analog Statistics Tab
Statistics are available only if configured when creating the input tags within the site.

24 • How to Build an Application Developer's Guide (part 1)

For each statistic tracked, values will be calculated for both "yesterday" and "last 24 hours". Other time ranges may
configured by adding History Statistics tags from the Tag Browser. See: History Statistics Tags.

When viewing the statistics, you may choose to view a table showing the values for all collected statistics over a time
period, or a table showing the specified statistic, over both time periods.

ChangeSets - An Application in One File

Notes: The information contained in this chapter applies only to the application code, tags, pages, etc. To save a copy of
the data collected by an application, see: Make a Backup of Logged Data.

Except for Template ChangeSets, do not store ChangeSet files in the application directory.

A ChangeSet file contains the instructions required to re-create an application. That is, the set of changes that went into
making the application. A ChangeSet is not the same thing as a copy of the application, compressed into one file
(although the Snapshot ChangeSet comes close).
There are four types of ChangeSets, each of which is intended for different purposes. A full description of each type is
provided in the sub-topics of this chapter.

Warning: ChangeSets do not include OEM layers. If your application uses an OEM layer, you must create and send a
ChangeSet for that as well.

ChangeSets are used in the following ways:

Developer's Guide (part 1) How to Build an Application • 25

• Initial installation of an application.
• Synchronizing an application where changes were made on a computer that is not visible from the network.
• Application recovery, using a very recently created ChangeSet.
• Obtaining a copy of an application for debugging.
• Creating a clone (identical copy) of an application in order to test changes without harming the running application
or accidentally distributing your test to other workstations.

ChangeSets should not be used to:

• Revert to an older version of an application. (Use the VTS Version Control system instead.)
• Install an application on more than one networked computer. (Install on one, then use Get-From-Server.)
• Serve as a backup unless up-to date ChangeSets are made on a frequent basis. (Restore from another server if the
application is running on more than one workstation. Use a recent ChangeSet otherwise.)

Given a ChangeSet file, there are two ways that you can use it, depending on your situation.
You could create a new application. The results will differ, depending on the type of ChangeSet file you have been
given, as described in the following topics.

If the ChangeSet was created from an application that already exists on your workstation, you can choose to create a
clone (copy). A clone is useful when you want to experiment with configuration changes, while being sure that nothing
you do will affect the primary version of the application.

You could apply the changes in the ChangeSet to an application.

Add-On ChangeSets can be applied to any application based on the same layer or a descendant of that layer. (An Add-
On ChangeSet of an application based on the VTScada layer could not be applied to an application that is based on the
VTS Library layer).
Full, Snapshot and Run-Only Snapshot ChangeSets can only be applied to the same application, presumably located on a
different computer. The purpose is to distribute updates between computers that do not have a network connection. The
changes in the ChangeSet are merged as if the computers were linked and the VTS Version Control system were able to
distribute those changes.

26 • How to Build an Application Developer's Guide (part 1)

Before using ChangeSets, it is important that you also understand the VTS Distributed Version Control system and how
changes are deployed. If Auto-Deploy has been disabled on your workstation while making(*) the changes that are
included in the ChangeSet, then two things are true:
• When applied to the destination computer, those changes will exist only in a local branch.
• The destination computer must have Version Control enabled as part of their VTS license key in order to access
those changes.
(*)Auto-Deploy relates to changes made to the application, not to the making of the ChangeSet. If you switch Auto-
Deploy off just before making the ChangeSet, the changes included in that set are still considered to have been deployed.
On the other hand, deployed changes within the ChangeSet will be deployed on the destination workstation, regardless of
whether Auto-Deploy is Off or On at that workstation.

The result of distributing a ChangeSet file is much the same as making a network connection between your computer and
the other workstations that are running the application.

Create a ChangeSet File

To Create a Full ChangeSet, requires only one step. Advanced ChangeSet options can be found in a sub-menu. Note that
significant preparation is required before creating an Add-On ChangeSet or an OEM Template ChangeSet.

Warning: ChangeSets do not include OEM layers. If your application uses an OEM layer, you must create and send a
ChangeSet for that as well.

1. Open the Application Configuration dialog.

(Instructions)
2. Select the Create ChangeSet File option from the menu.

Developer's Guide (part 1) How to Build an Application • 27

 3. Click the Create button.
A dialog box will open, prompting you for a file name. You can also select the directory where the ChangeSet
will be stored. The extension ".changeset" will automatically be added to whatever file name you provide.

Note: Do not store ChangeSet files in the application directory, with the exception of the OEM Template version.

4. Type a file name for the ChangeSet.

5. Click the OK button
The .changeset file will be created.

Advanced ChangeSet Options

The Advanced Mode option of the Create ChangeSet File page provides several options for creating ChangeSets
designed for special circumstances.

The first option, Create a Complete Backup, is identical to the single Basic Mode function. The other three types of
ChangeSet are described in the following topics.

Apply a ChangeSet File

Use the Apply ChangeSet page of the Application Configuration dialog when you want to:

• Update your application using a ChangeSet file from another workstation that is running the same application, and is
not visible via a network connection.

Note that you cannot apply a ChangeSet file from one application to another.

It is possible that the changes coming from the ChangeSet may conflict with changes that have been made to the
application on this machine. The Apply ChangeSet menu gives you a choice between two options for how to handle
conflicts:
• Use ChangeSet revision on conflict.
The version in the ChangeSet file is used.
• Discard changes from ChangeSet on conflict.
The version on the workstation is used in the case of a conflict. This is often the safest option when you
encounter a conflict while attempting to apply a ChangeSet file to a production system.

The steps to apply a ChangeSet file are as follows:

1. Open the Application Configuration dialog.

(Instructions)
2. Select the Apply ChangeSet File option from the menu.

28 • How to Build an Application Developer's Guide (part 1)

 3. Click on the Select button
A browse window will open, allowing you to find and select the .ChangeSet file.
4. Select the file and click Open
A dialog will prompt you to confirm that you wish to apply the changes.

5. Click "Yes"
The changes will be applied.
If there is a conflict between versions, an error message will tell you which version was used and which
ignored.

The Full ChangeSet

This is the type of ChangeSet you will create if you open the Create ChangeSet page of the Application Configuration
dialog and click "Create".
This type of ChangeSet contains a complete copy of an application's development history.

Note: The version history, stored in the ChangeSet, will not be visible unless you set the application property,
RepositoryShowCloneHistory to 1. This property must be part of the section, "Layer" rather than "System".

Use a Full ChangeSet if you want to send a complete copy of the application to a computer that is not on your network.
(That is, a computer that cannot do a "get from server" to obtain a copy of the application.)

Warning: ChangeSets do not include OEM layers. If your application uses an OEM layer, you must create and send a
ChangeSet for that as well.

You can also use a Full ChangeSet to restore an application that has been lost or damaged, but only if the ChangeSet was
created recently. If the application exists on another workstation, it is always better to restore or replace the damaged
workstation, then do a Get-From-Server to recreate it on the machine.
Note that, attempting to revert an application to an older version by applying a Full ChangeSet will not work. Changes
are merged. Since the changes you are trying to apply with the older ChangeSet already exist in the current application,
they will be ignored. Use the VTS Version Control system instead to switch to an earlier version.

Snapshot Copy ChangeSet

Creating an application from a Snapshot Copy creates a copy of the application that may be edited, but which will not
include any history of the development leading up to the current version. Development work leading up to the distributed
version will not be visible, but further development work can be done on the distributed application.

Warning: ChangeSets do not include OEM layers. If your application uses an OEM layer, you must create and send a
ChangeSet for that as well.

When installing an application using a Snapshot Copy, install it only on one server, then use Get-From-Server to install
the application on other computers in the network. If you use a Snapshot Copy ChangeSet on one workstation of a
networked application that is currently running, the empty version history of this most recently-modified workstation
will be applied to all other workstations that are running the application.

Developer's Guide (part 1) How to Build an Application • 29

Run-Only Snapshot Copy
This is the same as the Snapshot copy except that only .RUN files are included. None of the source files will be
distributed with the ChangeSet and therefore no changes can be made that would modify source files. Tags can still be
created and modified as these are not stored in source files.
Run-Only Snapshot Copy ChangeSets should be used for distributing OEM layer applications.

Warning: ChangeSets do not include OEM layers. If your application uses an OEM layer, you must create and send a
ChangeSet for that as well.

OEM Template ChangeSet

This replaces the template directory, used in earlier versions of VTS to specify instances of pages, etc. that should be
created in new applications based on your OEM layer. The Template ChangeSet must be stored in the application
directory and distributed with the OEM application.
A very specific process must be followed in order to create a Template ChangeSet.

As described elsewhere in this manual, VTS applications are often built on other (OEM) layers in order to inherit drivers,
tag types, reports or other objects from those layers. (See: Application Layers) While the new application will inherit
definitions of those objects, it does not inherit instances of the objects (other than tags) from the lower layers.
This is where the OEM Template type of ChangeSet can be useful. It allows new applications, based on the OEM layer
to be created with the desired configuration in place, including pages.

There are three requirements for a template ChangeSet file:

• The file must have the name "Template.ChangeSet"
• The file must be located in the OEM layer application's folder.
• The file must be added to the OEM layer. This is usually done either by compiling the OEM layer or by using the
File Manifest tool in the Application Configuration dialog. See: Manage Files with the File Manifest.

The steps for creating an OEM template ChangeSet involve creating a new application that contains only the tags, pages,
properties, etc. that are to be part of the template.

Preparation:
There are two, optional preparatory actions to take:
• The OEM layer's repository will contain the name of the machine where it was created. You may wish to substitute
your company name for the sake of creating a more professional appearance.
• If you are maintaining template ChangeSets for several applications, and if those applications have a parent-child
relationship to each other, then each distinct OEM layer that you create should be given a unique machine ID for its
repository history. Do this by creating a unique 12-digit hexadecimal code in the VTS Setup.INI file and changing it
between the creation of one OEM layer and another. The code may be any 12 hexadecimal digits.
To accomplish these actions:
1. Open the SETUP.INI file in the VTS folder, using a text editor.
2. Add the following two lines to the [SYSTEM] section. (Use your company or brand name for the repository
workstation name and invent your own 12-character ID).
RepoWorkstationName = ReliableOEMs

30 • How to Build an Application Developer's Guide (part 1)

 RepoMachineID = a1ab2bc3cd4d

3. Re-start VTS.

If using multiple RepoMachineID values, then it must be changed between the creation of one OEM layer and another.
You should always use the same RepoWorkstationName and RepoMachineID when making any changes to a given
template – keep a record of what values were used for each of your OEM layers.

Template Creation:
A space between steps indicates the completion of a sub-task.

1. Create and develop the OEM layer as completely as possible.

Be sure to deploy changes if the Automatically Deploy option is not checked.

2. Make sure you have no applications in your VAM called "New Application", and that there is no directory
under your VTS installation called "New Application".
If necessary, remove the application and/or directory.
3. In the VAM, click the Add button to create a new application.
4. Select the OEM application as the Type for the new application.
5. Do not change the application's name.
Leave the name as "New Application". If the dialog is initialized with a name like "New Application 1", then
you did not remove the application and/or directory that needed to be removed in step 2.
6. Do not start the new application.
Running an application creates a .platform file that must not be included in the template ChangeSet. All work
in this application will be done with the user files and the Application Configuration dialog.

7. Make your changes to the application's user copy files.

This is done by making your changes to another application, then copy and paste the source code changes you
require. You can also create tags in another application, export them to a file, then import that file into the new
application without actually running the application. See: Import and Export Tags.

8. Use the Import File Changes button in the VAM to import the user copy changes.
9. Open the Application Configuration dialog for New Application.
10. Select Create ChangeSet File in the menu.
11. Click on the Advanced Mode button.
12. Select the option, "Create a complete backup to be used as an OEM template".
13. Click on the Create button.
A dialog box will open, asking for a file name and location.
14. Navigate to the OEM layer's application folder.
15. Ensure that the filename is "Template.ChangeSet".
16. Click on OK.

17. Select the OEM layer application in the VAM

18. Click on the Import File Changes button

Developer's Guide (part 1) How to Build an Application • 31

 19. If the OEM layer doesn't yet have a Template.ChangeSet file, you will be prompted to add the file,
Template.ChangeSet. Click on "OK"

If you are updating an existing OEM layer ChangeSet, replace steps 3-5 above with the following:
1. Click Add New.
2. Select the option, Get From ChangeSet.
3. Select the OEM layer's Template.ChangeSet file as the source ChangeSet.

All applications created on the OEM layer will now include local copies of tags, application properties, pages, etc. that
were part of the temporary application. If you decide to update the OEM layer at a later date, remove the
Template.ChangeSet file from the OEM layer's file manifest and repeat these instructions. See: Manage Files with the
File Manifest.

Remove an Application from the VAM

You can remove an application from the VAM's list of available applications at any time. The choices you make while
doing so will determine whether this removes only the application's name from the list or if it deletes the application
entirely from your computer.

To remove an application:
1. In the VAM, select the application to remove.
2. Click on the Remove button.

A prompt will ask you to confirm that you want to remove the application.

32 • How to Build an Application Developer's Guide (part 1)

 3. Click "Yes"
You will be asked whether to keep the application's directory and files.

4. Click Yes to keep the directories and files or No to delete them.

Warning: This is no further confirmation dialog after this – choosing No will remove the application and all of
its files from your computer.

The application will be removed from the VAM.

OEM layers that have dependant applications may not be removed, but they can be hidden. The process is the same
except for the dialog that will be shown:

Make a Backup of Logged Data

If your application runs on two or more servers, where one is designated the primary and one or more others are
designated as backup servers, then your logged data is automatically stored on all servers continuously. If one server
were to fail, install a replacement, do a Get From Server to load the application on it, and let VTS synchronize the data
from running server. All of this can be done without interrupting the application.
In this configuration, DO NOT use a copy or backup of the data directory to restore data to one server. Doing so will
create a discontinuity between the computer that is being restored and the one(s) on which VTS has been continuing to
run.

If you are running VTS on a single computer only, then you will need to take a copy of the history files.

Unless otherwise configured(*), VTS stores logged data in a folder within your application. For example, if you have
installed VTS in the folder, C:\VTS and are running an application named MyApp, then the history would be found as
follows:
C:\VTS\MyApp\Data\

Developer's Guide (part 1) How to Build an Application • 33

To make a backup of your logged data, copy the Data folder and all of its sub-folders. History information can only be
viewed by VTS. You should also make a backup of the application as described in the topic, Copying an Application -
ChangeSets.

(*) If you have configured your system to use a 3rd party database program for your logged data instead of the VTS
history system, follow the instructions in that program for creating and restoring backups.

Open the Application Configuration Dialog

The Application Configuration Dialog contains a collection of tools for managing your application.

The pages within this dialog are described throughout this chapter. This topic provides instructions for the two methods
of opening the dialog.

Note: if security is enabled for an application, you must have at least the Configure privilege before you are allowed to
open this dialog.

Open the Application Configuration Dialog from the VAM

1. In the VTS Application Manager (VAM), select the application
2. Click on Properties

34 • How to Build an Application Developer's Guide (part 1)

Open the Application Configuration Dialog from Within an Application
1. While an application is running, click on the Configure button
The Configuration Toolbox opens.
2. Click on the Application Configuration button.

Set Application Properties

Application properties are used to control how VTS looks and operates. These were referred to as Configuration
Variables in earlier versions of VTS.
By changing properties for your application, you can:
• Choose to run the application in a window instead of in full screen.
• Change labels on the screen – perhaps to create an application for a language other than English.
• Control what is said by spoken alarms.

Developer's Guide (part 1) How to Build an Application • 35

• Decide whether alarm pop-up messages are to be enabled.
• And much more…
There are well over 1000 application properties that can be set. Fortunately for developers of VTS applications, the
majority of these properties can be set using VTS dialog boxes rather than by editing configuration files.
This chapter describes how to find and use the Application Configuration dialogs. A more technical reference is provided
in the chapter, Application Properties.

The steps to set a value for a property, using the Application Configuration dialog, are as follows. Links to detailed
instructions are provided where appropriate.

1. Open the Application Configuration dialog.

(Instructions)
2. Open the Edit Properties dialog.
(see: Opening the Edit Properties Dialog)
3. If the property has not yet been set in the current application, copy it from the underlying OEM layer.
(see: Copying a Property to the Current Application)
4. Change the property's value.
(see: Changing a Property's Value in an Application)
5. Apply the changes.
6. Deploy the changes.
(see: Local Changes versus Deployed Changes)

The following topics provide detailed instructions for each of these steps.

Open the Edit Properties Dialog

To view or change the properties of an application:

1. Open the Application Configuration dialog.

(Instructions)
2. Click on Edit Properties in the side menu.
The Properties page of the dialog will open.

36 • How to Build an Application Developer's Guide (part 1)

Properties shown in black are set within the application. Properties shown in a faint gray are inherited from an
underlying layer. You can change the value of only those properties found in the current application – for instructions on
how to copy a property, see the next topic: Copying a Property to the Current Application.

Sort and Filter the Application Property List

There are many application properties. Finding the one you need, or even trying to browse through similar properties
may take time. Three shortcuts have been provided to help you find properties faster.
Sorting: Click on the title of any column to sort the list by that column. You can click the title a second time to sort in
the opposite order.
Filtering: Enter a portion of the name you are searching for in the field provided, then either press enter or click on the
filter button. You should use the * wildcard for any portion of the name that you are not sure of. For example, to find
Display Manager properties that begin with the letters "Disp", enter "Disp*" in the field.

Developer's Guide (part 1) How to Build an Application • 37

Hide OEM Properties: Check the Hide OEM Properties option in order to limit the display to only those properties
that are set in the current application.

Copying a Property to the Current Application

This dialog shares many features with the one used to add a new property. See also: Adding a Property to the Current
Application.

In the Edit Properties dialog, you will notice that a few properties are shown using a bold font while most are displayed
using a faint text color. Those shown in a faint gray color are properties whose value has been set in one of the
application's underlying OEM layers. (If the Hide OEM Properties option is checked, only local properties are shown.)

38 • How to Build an Application Developer's Guide (part 1)

Note: If the property whose value you wish to change is already in a bold font, and if you do not intend to set a
workstation-specific value for that property, then the instructions in this topic do not apply. See either: Changing a
Property's Value in an Application or Set a Workstation-Specific Property Value.

In some cases, it will make sense to change a property's value in the OEM layer so that the value you want carries
through to all applications based on that layer. More commonly, you will want to change the property's value on an
application-by-application basis. To do this, you must make a copy of that property in your application as follows:

1. Open the Application Configuration dialog.

(Instructions)
2. Ensure that the Hide OEM Properties box is not selected.
3. Find and select the property whose value you want to change.
See: Sort and Filter the Application Property List for shortcuts.

4. Click on the Copy button.

The Copy Property dialog will open as shown at the beginning of this topic.

Note: The Copy Property dialog allows you to change all fields, including the Property Name and Section. Do not
change the contents of these two fields. Unknown property names are ignored. Properties attached to the wrong section
are also ignored by VTS.

5. Change the Value as required for your application.

6. [optional] If the copied property is meant to be in effect for only a particular workstation, type the name of that
workstation in the field provided.
7. [optional] Alter the comment field to provide a reminder note to yourself, explaining the reason for the new
value.
8. Click the OK button.
The dialog closes. Note that the new property will not be saved until you apply your changes.
9. Click the Apply button.
If the property is one that requires an application restart before it goes into effect, you will see the following
warning:

Developer's Guide (part 1) How to Build an Application • 39

 10. Click on OK unless you would like to make other configuration changes before proceeding with this one.
The Comment dialog will appear.

11. Type a comment into the Comments dialog and click the OK button.
If you later use the VTS controlled versioning system to review the changes made to your application, this
comment will help you remember what changes were made and why.

Adding a Property to the Current Application

Adding a property to an application is a rare event. For most applications, all the properties that you will require are
already defined in the VTS or VTScada layer and need only be copied to your application layer if you want to change
their values. (See: Copying a Property to the Current Application.)
One reason that you might want to add a property is if you have written your own module for VTS and wish to store
values such as labels in the Settings file. You can make your custom module more flexible if it is designed to use values
from the settings file without needing to re-write the module's code and re-compile it. Note that property names may not
include the characters []<>=;
Another reason that you might add a property is if you wish to override a configuration setting from the file Setup.INI.
Since these settings affect the appearance and function of VTS in general rather than one application in particular, very
few will be of use when added to your application's Settings file.
For a full description of the variables available in Setup.INI, see: Application Properties.

Steps to add a new property:

1. Open the Application Configuration dialog.
(Instructions)
2. Click on the Insert button
The Add Property dialog will open.

40 • How to Build an Application Developer's Guide (part 1)

 3. Enter the Property Name.
4. Select or Enter a section.
Properties may be ignored or misinterpreted if they are added to the wrong section of the Settings file.
5. Enter a value for the property
6. [optional] Select a workstation if this property is to be in effect on only that one.
7. Enter a comment, describing the new property.
Comments will be stored on the line below the property in the Settings.Dynamic file.
8. Click OK
The dialog closes. Note that the new property will not be saved until you apply your changes.
9. Click the Apply button.
The Comment dialog will appear.

10. Type a comment into the Comments dialog and click the OK button.
This comment is for the VTS version control system and should explain why the new property is being added,
unlike the earlier comment that explains what the property does.

Note: The new property will be saved to the Settings.Dynamic file. Do not use this system for properties that take effect
only on application start-up and should therefore be part of Settings.Startup.

Changing a Property's Value in an Application

You can use the Edit Properties dialog to change the value of an application property that is set locally within an
application:

Developer's Guide (part 1) How to Build an Application • 41

 1. Open the Application Configuration dialog.
(Instructions)
2. Find and select the property whose value you want to change. Only properties that are not flagged as OEM may
be edited.
See: Sort and Filter the Application Property List for shortcuts.
3. Click in the Value field.
An edit window will open within the field.

4. Type a new value for the property and press Enter.

5. Click on the Apply button.
If the property is one that requires an application restart before it goes into effect, you will see the following
warning:

6. Click on OK unless you would like to make other configuration changes before proceeding with this one.
The Comment dialog will appear.

7. Type a comment into the Comments dialog and click the OK button.
If you later use the VTS version control system to review the changes made to your application, this comment
will help you remember why the changes were made.

42 • How to Build an Application Developer's Guide (part 1)

 8. Choose whether to stop, restart now or later.

If you choose Not Now, the Restart Required symbol will be added to the application's title bar and further configuration
changes will not be allowed. The buttons for the configuration toolbox and for page notes will be disabled.

Set a Workstation-Specific Property Value

Any property can be assigned a value that will only apply to the instance of VTS running on a specific workstation. You
might use this feature to set display properties or security features that will be in effect only for a given workstation.

To set a workstation-specific property value:

1. Make a copy of that property in the current application. (see: Copying a Property to the Current Application)
Do this even if there is already a copy.
2. In the Workstation field of the property, type the machine name of the workstation where this property is to be
used.
3. Apply your changes.

If the property is flagged as requiring a restart, you will need to stop and restart the application before the new value goes
into effect and before you are able to make any further changes to the list of application properties.
For more information about workstation-specific properties, see: Workstation-Specific Properties.

Apply and Deploy Changes to Application Properties

None of the changes that you make to an application's properties, using the Edit Properties dialog will be saved or put
into effect until you click on the Apply Changes button.

Developer's Guide (part 1) How to Build an Application • 43

If you leave the page without clicking the Apply button, you will see the following warning.

If you click on the Yes button, the Edit Properties page will close and none of your edits will be saved. Clicking on No
closes the warning and leaves the Edit Properties dialog open so that you can use the Apply button.

All edits to the application properties are local to your workstation until Deployed. For most applications, changes are
automatically deployed as they are made, but if that feature has been disabled for your particular application, you will
need to use the Deploy Changes button. Deployed changes are shared with all networked workstations running the
applications and are stored in the repository of the controlled versioning system. See: Local Changes versus Deployed
Changes.

The VTS Version Control System

Every time that you make a set of changes to your application, VTS records the new configuration in a repository. You
can return to an earlier stage of development at any time by using the commands in the Version Log.

Note: Full access to the version control system is an optional feature that your company may or may not have purchased
with your VTS license. Check the list of features included with your VTS license in the About VTS dialog.

The version control system offers far greater flexibility than a simple Undo-Redo. Features include:
• The ability to return directly to any earlier stage of development.
• Since the act of switching to an earlier version is itself logged as a stage in the version control system, you have not
"undone" and lost changes to intermediate stages of development, but have added one more change to the log.
• You can merge (or then reverse) specific changes from a selected version.
For example, given an application with 20 versions recorded in the version control system, you decide to switch
to version 10. You can then choose to merge just the changes made in versions 12, 15 and 18 into version 10
and carry forward from there. (Note: later versions often depend on work done in earlier versions. If you merge
the work from a given version, be sure to include all related changes.)
• You can reverse or merge specific changes from a range of versions.
You can select a range of versions, and then select specific changes done across those versions to be reversed,
or merged.

44 • How to Build an Application Developer's Guide (part 1)

• VTS uses a distributed version control system. Version changes can be made by authorized users on any
workstation, regardless of whether the primary configuration server is available.
In the context of the VTS version control system, "reverse" means to undo a change. "Merge" means to blend a change
into the current revision. That change may be taken from another workstation that has not been configured to deploy its
changes automatically, or it may a change that was reversed.

Version Changes and Application Security

Warning: When you add, modify or delete user accounts, these actions count as changes to your application and
therefore become part of an application's version history.
If a switch to a different version of the application will affect user accounts, you will see a warning, asking if account
information should be retained. You can say "Yes" in response to this dialog to exclude all changes that would affect
account information.
If you select "No", thereby including changes that affect user accounts as you change from one version to another, you
can still recover those account changes. Do so by merging the version numbers in which the account changes were made.
See: Merge Version Changes.
When reversing or merging changes, you can choose to exclude the Accounts.Dynamic from the list of files included in
the action.
Security changes are always deployed immediately, regardless of the current setting of Auto-Deploy.

Commenting Changes
When you apply or deploy a change, VTS will prompt you for a comment:

Comments are extremely helpful. The version history for any application is likely to become large over time. By making
a note of why each change was made, you can create a clear history documenting your application's development.
Comments are not mandatory in the default configuration of VTS. If you prefer to make comments mandatory, you can
change the minimum length required. To do so, add the application property RepositoryCommentMinLen to the Layer
section of your Settings.Dynamic file.
See: Adding a Property to the Current Application.
After setting a value for the property RepositoryCommentMinLen, users will see a dialog similar to the following if they
do not provide the required number of characters.

Local Changes versus Deployed Changes

The most recent deployed change becomes the official version of the application. In a remote or networked application,
deployed changes are distributed by VTS to all the workstations running that application. Until a change is deployed, it is
said to be "local". Local changes are stored in a separate branch of the application's version history. They do not become

Developer's Guide (part 1) How to Build an Application • 45

active on other workstations (although they can be viewed there), and they can be erased using the Revert Changes page.
Local changes also have an effect on applications that run on a single computer: A ChangeSet is created from the most
recent deployed version. Modifications that have not been deployed are not included.

While there are local changes on a workstation, the Configuration Toolbox button will display a "Work-in-progress"
image.

All changes to an application are automatically and immediately deployed unless you choose otherwise. In most cases, it
is an advantage to have the Automatically Deploy Changes option in effect since it ensures that your edits are always
saved as the official version of the application in the repository. A situation where you might not want this feature is if
you are making changes to a networked application and do not want your edits to be installed on the other workstations
until you have finished and tested your work.

Notes: Changes related to security accounts are always deployed automatically and immediately.
Auto-Deploy cannot be deactivated on a Run-Time licensed workstation.

To switch off the Auto-Deploy feature, follow these steps:

1. Open the Application Configuration dialog.

(Instructions)
2. Click on "Information" from the menu.
3. Un-check the Automatically Deploy checkbox.

46 • How to Build an Application Developer's Guide (part 1)

 4. Click the Apply button.

All changes made to this application will now be local until you use the Deploy Changes option of the Application
Configuration dialog.
In a networked application, other servers will continue to run the deployed version, but will also obtain a copy of your
local changes. This will show up in the Workstations section of the Show Version Log screen, where your workstation
entry will be marked in Blue to indicate the presence of local changes in that branch.

Note: Changes to the Automatically Deploy option affect only the current workstation. You cannot remotely change this
value on other workstations.

Selecting Which Changes to Deploy

Note: Except for the header text, the same screen is used when merging or reversing a range of changes. See: Reverse
Version Range and Merge Version Range.

The Deploy Changes page is disabled while the Automatically Deploy Changes feature is in effect. See: Local Changes
versus Deployed Changes.

When you are ready to deploy local changes, making them the current version of the application, use the Deploy
Changes page of the Application Configuration dialog.
You can open this page as follows:

1. Open the Application Configuration dialog.

(Instructions)
2. Click on "Deploy Changes" from the menu.

Developer's Guide (part 1) How to Build an Application • 47

The Deploy Changes screen allows you to see exactly what was done to each source file and tag. For example, clicking
on the Analog Control tag (shown in the previous image) will open a display showing what was done to configure this
tag:

Changes made to source code such as a page, will show green lines for what is new, and yellow for the previous values.
(Circled numbers link to descriptions in the following text.)

48 • How to Build an Application Developer's Guide (part 1)

The following tools are available to help you work with this display:
(1) The number of changed files in each category is shown in parentheses.
(2) Before and after timestamp and file size.
(3) Columns can be sorted by type of change (addition + or removal -), line number, alphabetic.
(4) Move Next and Move Previous changes the focus box (5) from one change to the next.
(6) Changes throughout the file are shown in color bars on the side panel. The black rectangle shows how much of the
file is currently visible and can be dragged to show the next change.

When you first open the Deploy Changes page, all changed items will be selected. By selecting individual items in the
list and using the buttons at the bottom of the page, you can choose which changed items will be included when you
click the Deploy Changes button.

Warning: Development tasks often involve more than one file. Choosing to deploy only some of the code changes
required by a VTS object may cause serious errors in your application.

The Reload button allows you to refresh the display. If you have made local changes while the Deploy Changes page
was open, click this button to ensure that all changes are displayed before deploying.

Reverting Local Changes

Note: The Revert Changes page is disabled while the Automatically Deploy Changes feature is in effect. See: Local
Changes versus Deployed Changes.

Local changes to an application (that is, those changes that have not yet been deployed) can be reverted or undone. If you
need to undo local changes, use the Revert Changes page of the Application Configuration dialog.

Developer's Guide (part 1) How to Build an Application • 49

You can open this page as follows:

1. Open the Application Configuration dialog.

(Instructions)
2. Click on "Revert Changes" from the menu

You can revert all changes, returning to the last deployed stage of the application, or you can select particular changes to
revert.

When you first open the Revert Changes page, all changed items will be selected. By selecting individual items in the list
and using the buttons at the bottom of the page, you can choose which changed items will be included when you click
the Revert button.

Warning: Development tasks often involve more than one file. Choosing to revert only some of the code changes
required by a VTS object may cause serious errors in your application.

The Reload button will refresh the display. If you have made local changes while the Revert Changes page was open,
you should click this button to ensure that all changes are displayed before reverting.
Deployed changes are managed (and can be undone) using the Version Log.

50 • How to Build an Application Developer's Guide (part 1)

Review Versions - The Version Log
You can review stages of development by opening the Version Log:

1. Open the Application Configuration dialog.

(Instructions)
2. Click on "Show Version Log" in the menu.

Version numbering uses the following system:

First, the computer name where the change was made.
A hyphen or dash.
"D" indicates a deployed change.
"L" indicates a change that was local-only at the time it was made, whether or not it was later deployed.
The number following the "D" or "L" is a simple counter.
So, version "ANDREWH-D20" is the 20th deployed change made on the workstation, ANDREWH.
To prevent the possibility of a faulty system clock creating out-of-sequence entries, the version counter takes priority
over the "time applied" value.

The various features and tools in this page are shown in more detail in the following image. Numbers refer to notes in the
following text.

Developer's Guide (part 1) How to Build an Application • 51

1) List of workstations running the application
If this is a remote application, all the workstations that the application runs on will be listed in this table. Note that, if a
machine is isolated from the network, its version list will almost certainly be out of date. Color-coding is used so that
you can see at a glance whether each workstation is running the most recently deployed version of the application.
Black Text: The workstation is running the most recently deployed version
Blue Text: The workstation has local changes that have not yet been deployed.
Red Text: The workstation is running an out-of-date version. That is, the version on the workstation is
older than the most recently deployed version.

2) List of version changes for the selected workstation

Displays the list of version changes for the computer selected in the Workstations table. Information displayed includes:
Version number – The version numbering system is explained earlier in this topic (example: ANDREWH-D20).
Time applied – All version changes are logged using UTC time, however the display will show local time at the current
workstation.
User – The user currently logged in to the workstation when the change was made. If security has not yet been enabled,
the change will be attributed to the Logged Off user account.
Comment – When manually deploying a change, you will be prompted for a comment for the version. Automatically
deployed changes will often, but not always, be assigned a comment from a list of standard change descriptions.

3) Right-click on a version to open the options menu

52 • How to Build an Application Developer's Guide (part 1)

By right-clicking on an entry in the version table, you can open a menu that provides several options for learning more
about what went into a version, or to select changes to make current.
See the following topics for details and instructions:
Show Version Details
Switch to This Version
Reverse Version Changes
Merge Version Changes
Reverse Version Range
Merge Version Range

Miscellaneous buttons
The buttons, Next 100 and Show All are used to step through the list of version changes, which may become lengthy
over time. The Reload button will refresh the display to show any version changes that may have happened since the
page was opened.

Show Version Details

Detailed information about the changes that went into any version can be seen by right-clicking on an entry in the
Version Log and selecting Show Changes (See: Review Versions – The Version Log).
This is an extremely powerful feature of VTS that allows you to see exactly what changed in every altered file from one
version to the next. Note that each folder type (left window) displays a count of the number of files of that type that were
changed in this version (if any).

The details display is divided into two screens. On the left is a list of all files that were changed in this version. The right
side screen initially displays a guide to interpreting version changes, until you select a file from the left screen, as in the
following image. Each type of change is indicated by both a symbol and a color.

Developer's Guide (part 1) How to Build an Application • 53

Using the color and symbol codes, as listed in the first image, one can see that in version D14 (note the dialog box title),
the background color of the page Station1 was changed to color "<80BFFF>" (pale blue) and a minimum page height
and width were set.

Switch to This Version

Use this option to make any previous version current. Changes made in versions since the one you are switching to are
not lost. The act of switching versions becomes a version change itself. For example, your current version number is D12
and you switch to version D8. What will happen is that a new version will be added – D13 – which will be an identical
copy of D8. Changes made in versions D9 though D12 will no longer be in the current version, but if required, you could
easily switch to version D12 (thereby creating version D14, which is an identical copy of D12).

54 • How to Build an Application Developer's Guide (part 1)

Reverse Version Changes
By reversing the changes made within a selected version, you can remove just the edits made to the application in that
version.
For example, you have made the following changes to your application:
Version D10 Added a page
Version D11 Deleted a tag
Version D12 Created a new tag
You then decide that it was a mistake to have deleted the tag in version D11. You can select that row in the Version Log,
right-click and choose "Reverse Version Changes". All of the edits that separate version D11 from D10 are removed, but
the new tag created in version D12 remains.

Use extreme caution when reversing a version change. If later versions depend upon work that was done in the version
that you are reversing, your application will be damaged.

The act of reversing a version change does not remove those changes from the history. Instead, it adds a new version in
which the change is the undoing of whatever was done in the reversed version. You could later decide to re-incorporate
the changes from the reversed version by using the Merge Version Changes command.

Merge Version Changes

If you have used either the Switch Version or the Reverse Version Changes command, then you can use the Merge
Version Changes command to re-introduce the changes from a specific version. You can also use this tool to merge other
machine's local changes into a new deployed version.

For example, your version log includes the following changes:

Version 10 Added a page

Version 11 Added a tag
Version 12 Drew the tag on the page.

You decide that the creation of the page was a mistake, but that the creation of the tag was not. You can proceed as
follows:

1. Switch to version 9.
Changes made in versions 10, 11 and 12 vanish from the current version.
2. Merge the changes from version 11
The tag is again part of the current version.

Note: depending on the change you may need to re-start your application.

Reverse Version Range

Rather than reverse one version change at a time, you can select all the versions within a range. This feature includes the
ability to select file-by-file, which changes within that range you want to reverse, leaving some changes intact. For

Developer's Guide (part 1) How to Build an Application • 55

example, in versions 19 and 20 you may have created and configured tag A. In steps 21 and 22, you created and
configured tag B. In step 23 you made further changes to tag A.
You can reverse all the actions related to tag A without damaging tag B, by selecting items to reverse in a range that
spans steps 19 to 23.
To select a range:
1. Right-click on the version either beginning or ending the range.
2. Select Reverse-Version Range from the popup menu.

The currently selected version will be highlighted to help you keep track. Note that this version is also
highlighted in the workstation list – you can select a range across workstations as well as across the versions on
your workstation.
3. Right-click on the version marking the end of the range you wish to select.

4. Optionally, remove items from the list of changes to be reversed.

Note that some development items will depend on others – use care in your selection.

5. Click the Apply button and provide a comment in the dialog that appears.

Merge Version Range

If you have made an earlier version current, or have reversed version changes, you can merge selected changes from a
range of versions into your current version.

56 • How to Build an Application Developer's Guide (part 1)

The steps are identical to those when reversing a version range. The difference is only that selected changes are merged
into the current version rather than reversed from it. To review briefly:
1. Right-click on a version marking the start of the range and select "Merge version range" from the menu.
2. Right-click on the version marking the end of the range and select "Merge version range end".
3. Optionally remove files from the list of changes that will be merged.
4. Click the Apply button and provide a comment in the dialog that appears.

Import File Changes

Application code is automatically re-compiled every time you make a change to the application. This is an incremental
compile involving only those files that have changed in the repository.
There may be times when you have reason to use the Import File Changes button in the VAM to perform a full re-
compile of the application. The Import File Changes button performs all of the following tasks with a single click.
Actions include:
• Activate the application, if not already active.
• Find files that have been added to the application and confirm that you would like to import them (see following
comments).
• Find files that have been edited or altered using a file editor.
• Compile some or all of the application's code as required.
• Deploy changes, but only if the Automatically Deploy Changes option is set.

If files have been copied to or created in any of the application's folders, they will be found by the compilation process
and you will be asked whether you want to add those files to the working set.

By clicking OK, all the checked files will be added to the application's repository and VTS will consider them to be part
of the application.
If you un-check a file before clicking OK, VTS will remember your choice and will not prompt you to import it on any
future compile. You can still add the file later by using the File Manifest. If you change your mind after adding a file you
can also use the File Manifest to remove it from the list of working set files. See: Manage Files with the File Manifest.

The Import File Changes button may be useful in the following situations:
• You have made custom code changes in your application directory, and want to import those changes. Some
changes (like page code, drawing method, and tag code changes) can even be integrated into a running application.

Developer's Guide (part 1) How to Build an Application • 57

• You want to manually edit settings files instead of using the GUI. Whether those changes can be incorporated into a
running application depends on which files where edited.
• You would like to add a bitmap or similar file.
• You are unable to run the application. It generally is worthwhile to try the Import File Changes button to do a
compile-all.

Manage Files with the File Manifest

The File Manifest page of the Application Configuration dialog provides you with control over which files in the user-
accessible folders will also be included in the working set. When you deploy changes through a remote application, or
when you create a ChangeSet file, only those items that are checked in the File Manifest will be included.

Each folder name (left window) is followed by two numbers: the count of selected files followed by the total number of
files in that folder. File counts include those in sub-directories of each folder.
Files that are marked with red boxes (right window) are required by VTS and cannot be un-checked. Those with green
boxes are under your control.

Warning: Some of the files that you can choose to exclude from the manifest may be useful to your application. For
example, after un-checking PageMenu.txt, the page menu in the application will be empty. Use caution!

Un-selecting a file from the manifest does not delete it from the application directory. While unselected, it will be
ignored by the version management system and will not be synchronized across workstations. You may choose to select
it again at any time.

The following two examples may serve to illustrate the use of the File Manifest:
Custom Bitmaps:

58 • How to Build an Application Developer's Guide (part 1)

You may have added custom bitmap files to your application (see: Adding Custom Graphics to VTS). Although you
have copied the files to a Bitmaps sub-folder of your application, those images will not become part of the working set of
files until you have added them using the File Manifest.
Accidentally included files:
After writing custom code for your application, you accidentally include notes or other extra files when compiling. You
can un-check these files from the manifest before creating a ChangeSet file for distribution.

Import/Export Files
Much of VTS can be configured directly by application developers. Examples include:
• Application properties (configuration settings)
• Custom code such as tags, device drivers and user interface wizards
• The page menu
• Server lists
• Application pages
For all such files, VTS maintains two copies: a user copy that you can edit and a working copy that VTS maintains in its
repository.
If you edit one of the user copies, you must direct VTS to import that file before it will become part of the working set.
This provides two benefits: All changes are recorded in the VTS version control system, and security is maintained since
only users who have the Configure privilege are allowed to import file edits.

Warning: Edit only the user files. Never attempt to edit files in the application's repository directory (.sync). Altering
files in that location may cause irreparable damage to the application.

Developer's Guide (part 1) How to Build an Application • 59

The Import/Export Files page of the Application configuration dialog offers several functions. With it, you can:
• View a list of all files that have been changed in the user-accessible file set of the application.
• View line-by-line differences between a changed file and the version in the current working set.
• Import file edits to the current working set.
• Discard file edits, replacing the file(s) in the user set with the version in the current working set.
• Merge changes from the working set files into the user set files without overwriting user-changes.

Further information about these functions can be found in the following topics.

Review File Edits

The display area of the Import/Export Files page shows two windows: on the left is a list of the edited files, as detected
by VTS. Click on one of these files, and the right-side window will show the contents of the file, noting additions in
green, deletions in yellow and conflicts in red or orange.

This powerful tool allows you to see exactly how the user file differs from the current working version, allowing you to
decide whether or not you want to import it.
Configuration changes to tags will record who made the change, what fields were changed, when the change was made
(see footer bar) and what the previous value was.
Note the slider bar on the left of the file display area. The full vertical range of the slider matches the complete file
contents. Changes are marked in color coded bars along the slider's length. This provides a way to rapidly spot all the
changes in the file and navigate to them.
If image files are changed, this tool will show a before and after version of the image. Other binary files show only the
file name and the date of the change.

Instructions for Importing File Edits

To import one or more user-edited files into the application's working set:

1. Edit a file
Examples can be found in the chapter Customizing VTS.
2. Open the Application Configuration dialog.
(Instructions)
3. Click on "Import/Export Files" in the menu.

60 • How to Build an Application Developer's Guide (part 1)

 VTS is able to find edited files by comparing those in the user-accessible directories to their matching copies in
the working set. By default, all edited files will be selected.
4. [optional] Use the Unselect / Select buttons to limit the list of edited files to import.
5. Click the Import button.
The Comments dialog will open.
6. Type a note explaining the reason for the import. This will be recorded in the version log.
7. Click OK

Note: While changes to some files such as Settings.Dynamic will take effect immediately, changes to others such as
Settings.Startup will not take effect until the application is re-started.

Discard File Edits

If after reviewing the edits made to the user-copy of a file (see: Review File Edits), you decide to discard all of the
changes, you do not need to open the file and edit it. The Import/Export Files page offers a Discard button.
This button is typically used as follows:

1. Open the Application Configuration dialog.

(Instructions)
2. Click on "Import/Export Files" in the menu.
3. Select the changed file.
4. Click the Discard button
A prompt appears, asking for confirmation.

5. Click Yes to discard the manual changes.

The user copies will be over-written by the current version of the file(s) in the repository.

Warning: All selected files in the list will be affected by this command. Ensure that only those files are selected in
which you want to discard the manual changes.

Export Latest
Where Discard File Edits will over-write the user file set with the current copy of the user files, Export Latest will
attempt to merge recent changes from the working set into the user files without destroying changes found there.

Developer's Guide (part 1) How to Build an Application • 61

Find Tools in the Configuration Toolbox
All of the tools for application development can be found in the configuration toolbox. If you have configuration
privileges, you can open the toolbox by clicking on the Configure button in the upper right of the Display Manager title
bar.
(See notes: Moving the Configuration Toolbox.)

In total, the Configuration Toolbox provides a set of 40 tools, one of which (2C) opens a library, which provides access
to many more features.
Use the following reference array to learn more about any given button in the configuration toolbox:

A B C D
1 Pick Graphics No Tool Shape Deploy All
Polygon Changes
2 Tag Browser Menu Editor Libraries Application
Configuration
3 Cut Copy Paste Delete
4 Rectangle Line Polygon Pipe
5 Arc Ellipse Pie Chord
6 Text Bitmap Undo Redo
7 Bring to Front Send to Back Horizontal Vertical
Spacing Spacing
8 Align Left Align Bottom Align Top Align Right
9 Align Vertical Align Group Snap Grid
Center Horizontal

Developer's Guide (part 1) How to Build an Application • 63

 Center
10 Dialer Options Configure E-mail
Speech Options
Lexicon

Note: Only users with sufficient privileges may perform the tasks listed above. See: Working with Security.

Moving the Configuration Toolbox

The first time that the configuration toolbox opens for an application, it will always be located at the upper left corner of
the screen. It is very likely that you will want to move it closer to wherever you are working on the page. Here's how to
do that:
Click and drag. Some may find this challenging. There is only a very small target area where you can click in order to
drag the toolbox. You must click on the title bar, but not on any of the buttons.
Use the Move command. The steps follow the image. Note step three in particular.

1. Click once on the VTS logo of the toolbox.

2. In the menu that opens, click Move.
3. Use the keyboard arrows to begin the move.
Once you the toolbox has begun moving as directed by the keyboard arrows, you may use the mouse to finish
the move. But, you must start the move using the keyboard. This is an operating system feature rather than a
VTS tool, and is the same for any window.

64 • How to Build an Application Developer's Guide (part 1)

Pick Graphics and No Tool

Switch between configuration mode (pick tool) and operation mode (no tool).
The Pick Graphics button is one of the most frequently used buttons in the Configuration Toolbox. When selected, it
activates the Pick Graphics tool and places the application in design mode, enabling you to configure and develop the
application pages of your application.

Note: When an application is placed in design mode (i.e. the Pick Graphics button or any other button in the
Configuration Toolbox except the No Tool button is selected), certain operational tasks (such as alarm
acknowledgement) are disabled. To place the application in operation mode so that you can perform operational tasks,
either close the Configuration Toolbox or select the No Tool button.

Libraries

This button opens the Libraries menu, from which you can add and edit pages, or work with a variety of VTS
tools and libraries. (See image below.)

The key feature of this menu is that a right-click on any node will always open a context-sensitive menu showing what
can be done with that node.
Please refer to the Drawing Tools Library for more information on the various tools and libraries

The Pages node provides access to the tools used to create edit and delete pages. Detailed information is provided in the
chapter: Adding and Editing Pages.

Application Configuration Button

This button opens the Application Configuration dialog, a powerful toolset that allows you to view and control
development versions, application properties, security settings, line-by-line changes to source files and much more.
See the chapter Create and Manage Your Applications to learn more about the Application Configuration dialog.

Developer's Guide (part 1) How to Build an Application • 65

Deploy Changes Button

Note: The Deploy Changes button will be deactivated if Auto-Deploy is currently enabled (as it is by default).
In a remote applications, this button allows you to deploy your development changes to all the workstations that have
this application. For a full description of what happens when you deploy changes, see: Local Changes versus Deployed
Changes.

Cursor Coordinate Display

The bottom of the Configuration Toolbox includes an area that displays the X (horizontal) and Y (vertical) coordinates of
the mouse pointer as you move it across the screen to help you configure your operator interfaces as accurately as
possible.

Drawing Tools Library

The Libraries button in the configuration toolbox opens a dialog that provides specialized tool libraries,
development tools to help you create your own drawing methods and the entire set of application page development and
configuration tools.

The Libraries dialog is shown here with the Drawing Tools menu expanded to display the available libraries.

The following libraries of tools will be available by default. (Note that two of these libraries are only available to
VTScada-based applications.)

• Alarm Tools: Provides tools to build customized alarm displays for your application, either to supplement or
replace the existing default Alarm page. See: Create a Customized Alarm System Interface.
• Meter Parts: Provides tools to create your own photo-realistic meters to use in addition to the Meter 1 through
Meter 13 drawing methods. See: Meter Parts Library.
• Modem Tools: Provides tools to augment your application with event and statistic displays for configured modems.
The Modem Tools library is discussed in "Modem Tools Library".
• ODBC Manager: The OBDC manager includes one tool: A Show Stats button that when added to an application
will display ODBC statistics. See: ODBC Manager Library.
• Report Tools: Provides tools to build a custom reports page, either to supplement or replace the existing default
Reports page. See: Report Tools Library Reference.
• Site Tools Library (VTScada only): The Site Tools Library contains two extra tools (Legend and Program Spawn)
that are useful in the development of VTScada applications. See: Site Tools Library.

66 • How to Build an Application Developer's Guide (part 1)

• System Status Tools: This library contains tools that can help you monitor aspects of your application. See: System
Status Tools Library.
• Standard Library: Provides a variety of tools for displaying objects (clock, borders, grid, tool-tip, etc.), for
modifying application properties (Edit .INI checkbox and variable field) and for configuring hotboxes or buttons.
See: Standard Library Tools.
• System Status Tools: Provides one tool only – the Historian Status Display. When drawn on a page, this tool
displays current operating statistics for all Historians configured in an application. See: Monitor the Historian's
Connection.
• User Draw Methods: A repository for drawing methods that you have created using the grouping tool. See: User
Draw Methods.
You have a choice of two ways to access the tools included in each of these libraries:
• Left-Clicking on a plus sign beside any of the entries will expand that menu item to show the tools within it.
To use any of the tools, left-click on it and select Draw from the menu that will appear.

• Right-Clicking on a menu entry will open a dialog, from which you can choose the Draw option. This will cause a
dialog box to be displayed, showing all the tools available in that menu item.

Standard Library Tools

The Standard Library contains a set of tools that supplement those in the Configuration Toolbox. This is a miscellaneous
group of tools that share little in common other than that they can add useful features to a page.
The standard library tools include the following. Each is described briefly here with a reference provided in each to find
more detailed information.
• An Analog Clock. Allows a clock with animated hands to be placed on a page. Any time zone in the world can be
displayed.
• The Bitmap tool. Use this to insert an image on an application page. This is the same as the Bitmap button on the
main toolbox menu. See: Adding Bitmap Images.

Developer's Guide (part 1) How to Build an Application • 67

• The Border tool. Draws a highly-configurable rectangular border on a page.
• The Edit Property Checkbox Used to enable or disable a selected application property whose value may be either 1
(checked) or 0 (unchecked).
• The Edit Property Field Draws a text input box that can be linked to an application property, providing operators
with a way to adjust a value.
• The Folder. Places a tabbed folder on a page. Objects placed on a tab will be visible only when that tab is selected.
See Folder.
• The Frame. Similar to a Border, but with more configuration options. See: Frame.
• The Grid. Places a rectangular grid on a page. The grid can be any size you want, and have any number of rows and
columns. You can also define the color of both the grid lines and the background.
• The Open Historical Data Viewer (HDV) Button. Adds a Button that links to the HDV. This link may be pre-
configured to open with a particular pen group loaded. See: Open HDV Button.
• The Open Historical Data Viewer (HDV) Hotbox. Provides the same function as the HDV button in a hotbox
format. See: Open HDV Hotbox.
• Multi-Line Text. Add paragraphs to your display pages. See: Drawing Multi-Line Text.
• The Page Button. Provides the same function as the Page Hotbox except that it is always visible on a page. See:
Linking to Pages with the Page Button.
• The Page Close Button. Allows operators to close a windowed page without needing to provide a full Windows™
title bar with page close buttons. See: Closing Pages with a Button.
• The Page Hotbox. Draws a navigation link to another page. If the destination page is parameterized, the hotbox may
specify the tags to be used for those parameters. See: Linking to Pages with the Page Hotbox.
• Tag Icon Marker. Used in user-defined tag drawing methods. Draws the symbol that displays a question mark for
the questionable flag and an exclamation for manual data. See: Tag Icon Marker.
• Tag List. Displays some or all of the child tags of a selected parent using the drawing methods you chose. See: Tag
List Drawing Method.
• The Tool Tip. Allows operators and developers to add notes that will appear only when the cursor is over a defined
area.

68 • How to Build an Application Developer's Guide (part 1)

Border Tool
(See also: Frame)
A border may be any size and may look like any of the following examples:

Its purpose is to provide a frame around a set of other page components.

Developer's Guide (part 1) How to Build an Application • 69

A border’s appearance is changed by adjusting the component colors, the overall style and the edge width.
Component colors include:
• Fill – either system color, transparent or your selection
• Highlight – provides contrast to border shadows. System, transparent or user-specified.
• Shadow – the edge that is in shadow for a raised or beveled border. System, transparent or user-specified.
The overall style is set as one of the following attributes:
• Indented. The highlight and shadow combine to make the border area look as though it is set into the page.
• Raised. The highlight and shadow regions are switched so that the border appears to be raised above the page.
• Beveled. Similar to Raised, but with a more sharply defined border around all edges.
• Bordered. A double line surrounds the border region, creating the appearance of a frame.
Drawing a border:
Step 1: Locate the lower right corner of the border on the page
Upon clicking the Border button, you will be prompted to position a sample border on the page, using the lower
right corner as the base point.

Step 2: Define the appearance using the VTS Graphic Editor

Having set a location for the lower right corner of the border, the VTS Graphic Editor will open with the
options appropriate for Borders displayed. For more information on using this tool, please refer to the section Using the
VTS Graphic Editor and VTS Graphic Editor: Options Unique to Borders.

Press the OK button to create a border with the default settings as shown.

Step 3: After dismissing the Graphic Editor, you can adjust the size and location of the border by clicking once on it,
then dragging the square handles.

Edit Property Checkbox

Use the Edit Property Checkbox tool to draw a checkbox that can linked to a property in your Settings.Dynamic file. The
purpose is to allow an operator to enable or disable the action of the property. Only those properties that can be part of
the Settings.Dynamic file and whose value can be a 1 (enabled) or 0 (disabled) should be linked to this checkbox.

70 • How to Build an Application Developer's Guide (part 1)

Note: For further information about application properties and the Settings.Dynamic file, see: Set Application Properties.

The result of the above configuration is a checkbox labeled, "Alarm Popups" that can be checked to set the
AlarmPopupsEnable application property to 1, or can be unchecked to disable alarm pop-ups.
Each time an operator changes a property using this tool, a comment will be added to the version log as follows: "Edit
Property Checkbox: property name".

Note: Some application properties, such as ScaleDisplayContent, require that your application be restarted before their
value can be read. Review the list of properties in the Application Configuration dialog to find those that are not marked
"Restart". See: Opening the Edit Properties Dialog.

For each property whose value you wish to modify, you must create a new Edit Property Checkbox object.

Note: You may not want operators to have access to the application properties. It is therefore recommended that you
create an application page specifically for all your Edit Property Checkbox objects, and then protect it from operator
access using an application privilege (see: Protect a Page with an Application Privilege.

Section
Enter the name of the section under which the variable you wish this checkbox to modify appears. For example, if the
variable is part of the [System] section in the Settings.Dynamic file, enter "System" in the Section field.

Variable
Enter the name of the application property that will be changed by this checkbox.

Label
Enter the text label that you wish to be displayed for the completed checkbox.

Box on Left
Set the position of the checkbox in relation to its label.

Developer's Guide (part 1) How to Build an Application • 71

If the Box on Left checkbox is selected the checkbox will appear to the left of the accompanying label.
If the Box on Left checkbox is not selected, the checkbox will appear to the right of the accompanying label.

Alignment
Configure the alignment of the completed checkbox object and its accompanying label within its drawing area.

Focus ID
Select a number setting the order of the completed object in the overall tab order. (optional)

Edit Property Field

Use the Edit Property tool to draw a field that can be used to set the value of a specific application property in your
Settings.Dynamic file. Only those properties that can be part of the Settings.Dynamic file should be linked to this
checkbox.

Note: For further information about application properties and the Settings.Dynamic file, see: Set Application Properties.

The result of the above configuration is an edit field labeled, "Email Subject".

72 • How to Build an Application Developer's Guide (part 1)

Note: Some application properties, such as ScaleDisplayContent, require that your application be restarted before their
value can be read. Review the list of properties in the Application Configuration dialog to find those that are not marked
"Restart". See: Opening the Edit Properties Dialog.

For each property whose value you wish to modify, you must create a new Edit Property Field object. If you wish to set
an application property that accepts a value of either 0 or 1, use the Edit Property Checkbox tool.
Each time an operator changes a property using this tool, a comment will be added to the version log as follows: "Edit
Property: property name".

Note: You may not want operators to have access to the application properties. It is therefore recommended that you
create an application page specifically for all your Edit Property objects, and then protect it from operator access using
an application privilege (see: Protect a Page with an Application Privilege.

Section
Enter the name of the section in Settings.Dynamic under which the variable you wish this field to modify appears. For
example, if the variable appears under the [LABELS] section heading in Config.ini, enter "Labels" in the Section field.

Variable
Provide the name of the application property that this edit field will enable users to edit.

Title
Enter the text label that you wish to be displayed above the completed edit field.

Data Type
Select the data type accepted by the specified application property. A “data type” is a programming term referring to the
specific type of value that is permissible for a variable. Some variables require text settings, others require numeric
settings that might be small or large, while others require a specific value of "0" or "1".
The available data types are:
• Status: Status is a numeric data type that can have a value of 0 or 1 (i.e. off/on or false/true).
• Long: Long is a numeric data type that is a whole number 4 bytes in length (i.e. -2147483 to 2147483).
• Short: Short is a numeric data type that is a whole number 2 bytes in length (i.e. -32767 to 32767).
• Float: Float is a numeric data type that is a fractional or decimal point value (e.g. 327.983).
• Text: Text is a text data type that accepts alphanumeric characters (e.g. "My Application").

Minimum Value / Minimum Length

Enter the minimum value that the selected variable will accept based on its data type (see above). For text data types, this
parameter sets the minimum number of characters that the variable will accept.

Maximum Value / Maximum Length

Enter the maximum value that the selected variable will accept based on its data type (see Minimum Value). For text
data types, this parameter sets the maximum number of characters that the variable will accept.

View
Sets the appearance of the completed edit field. This can be one of:
• Invisible: The Edit .INI Var Field object will be invisible to users. You may choose this option if you wish to hide
the object from view, and set it to Force Normal whenever you wish to use it.
• Force Normal: The Edit .INI Var Field object will be enabled and visible.
• Gray If Appropriate: The Edit .INI Var Field object will be enabled when the associated application property
cannot be set.

Vertical Alignment

Developer's Guide (part 1) How to Build an Application • 73

Specifies the alignment to be applied to the edit field, and its title and bevel vertically within its drawing area. You may
select one of:
• Top: Aligns the upper-most part of the object (title, bevel or edit area depending on other selections) with the
vertical top of the drawing area.
• Centered: Aligns the vertical center of the object with the with the vertical center of the drawing area.
• Bottom: Aligns the lowest part of the object (bevel or edit field, depending on other selections) to the vertical
bottom of the drawing area.

Draw Bevel
Select this option to have a beveled border drawn around your edit field.

Align Title
Indicates whether or not you wish the height of the title to be factored into the vertical alignment calculations (see
Vertical Alignment above). If not selected, the vertical alignment will consider only the edit box and the beveled edge (if
present).

Focus ID
Use the Focus ID spin box to select a number representing the order of the completed object in the overall tab order.
(optional)

Folder
The Folder drawing object creates a user-interface object with multiple tabs; each tab contains a separate display of
system monitoring and control objects. The tabs are used to select which frame is to be displayed. See also: Frame.
A folder may have from one to fifteen tabs. You have extensive control over the appearance of the folder and the tabs
within it.

A folder with three tabs.

The content for each tab's frame must come from a pre-existing object in your application. These may be pages, tag
drawing methods, or library drawing methods (normally, User Draw methods). You do not draw objects on a folder as
you would on a page.

74 • How to Build an Application Developer's Guide (part 1)

There are two parts to a folder's configuration: The overall style of the folder and the content and appearance of the
individual tabs. Since both parts of the configuration provide a large number of options, they are described separately in
the following topics.

Define a Folder's Overall Appearance

The Style tab of the folder configuration:

Tab Style
The tabs may use any of the following three styles (shown here using default colors).

Font Style
Select a Font tag to define the appearance of the tab labels.

Selected Tab's Frame Setup

The shape of the tabs themselves and the area below the selected tab are controlled by the Frame Setup selection. If
either Frame Tabs or Frame Buttons are selected for the overall style, then you may further refine the shape by selecting
one of the six built-in frame designs. See Frame for details. The System Tabs style does not allow for further refinement
of the frame.

Selected Tab's Label Color

Developer's Guide (part 1) How to Build an Application • 75

Opens the Select Color dialog, from which you can choose the color, in which the selected tab's text will be displayed.
To emphasize that a tab is selected, it is best to choose a color with high contrast from the tab's color.

Unselected Tab's Frame Setup

Provides the same set of options as for the Selected Tab's Frame Setup. Use care with this selection: by choosing a raised
frame for the selected tab and a flat or sunken frame for the unselected tabs, you can provide a clear visual message to
the operator to help them see which tab is selected. Choosing a frame for the unselected tab that is a completely different
style from that of the selected tab may cause confusion.

Unselected Tab's Label Color

Sets the color of the text to use for the labels on the unselected tabs. This should have a low level of contrast against the
tab's background color in order to indicate that the tabs are not selected, yet still have enough contrast to be easily read.

Tab Label Margin

Sets the number of pixels above the tab labels. A large margin value may increase the height of the tabs, but will not
increase the width - if necessary, the label will be truncated to provide the required margin within a given tab width. The
overall folder width, divided by the number of configured tabs, controls the width available for each tab.

Unique key for saving selected tab

Variables such as dialog positions and sizes are normally retained per-user and per-module. What this means for the
folder is that the “Last viewed tab” would be saved, but shared across all folders.
By providing a unique key to this parameter, each folder drawn in an application can save its own last viewed tab. If
used, the key may be any phrase such as, “Main Station Display” or “Treatment Plant Panel”

Define a Folder's Tabs

The number of tabs, the label for each, and the content of each tab's frame are defined with the Tab Setup.
The table in the center of this panel displays a summary of each tab's configuration and can be used to re-order their
appearance in the folder. Use the controls above or below the table to modify the tabs.

76 • How to Build an Application Developer's Guide (part 1)

Note: While the VGE is open, you can switch tabs on the folder in order to see the effect of your changes to each
individual tab while you are configuring them. Note though, that Tab #1 will be re-selected after each configuration
change.

Number of Tabs
May be any value from one to fifteen. This only changes the number of tabs displayed; tabs are not added to or deleted
from the folder. Thus, if you configure four tabs, then drop the number to three, you will have hidden the fourth tab, not
deleted it.

Move Selected
Tabs may be re-ordered. They are displayed left-to-right across the folder in the order that they appear from top to
bottom in the table.

Tab Layout
Provides control over how the contents of the tab fit into the folder size.
The margin, measured in pixels, will ensure a set amount of blank space around the contents. If the area of the folder
plus the margin is smaller than the selected content, then the content will be scaled down to fit.
If Stretch to Fit is selected, the folder content will be expanded to fit the available size.
The Maintain Aspect Ratio option controls whether the content may be deformed when being stretched or shrunk.
Finally, the Horizontal Alignment and Vertical Alignment options control how content that is smaller than the folder will
be placed within the available space.

Developer's Guide (part 1) How to Build an Application • 77

Tab Contents
For the selected tab, you may provide the text for the label and the contents of the tab's frame.
Any one of three types of object may be used for the tab's contents: Tag Draw Method, Library Draw Method or Page.
The specification of the contents depends on the content type. See following examples.

Steps to use a Tag Draw Method:

1. Select Tag Draw Method as the Draw Method Type.
The Context field will be enabled.
2. Select the tag type in order to filter for its available drawing methods.
For example, if you select an Analog Status tag, you can then choose from any of the Analog Status drawing
methods.
3. Click the Select Draw Method button to choose from the available representations of this tag.
If this drawing method uses parameters, you will be prompted to set those parameters for this instance of the
DM.
You may later use the Set Parameters button to change those selections.
Related topics: User Draw Methods, Drawing a DM with Parameters.

Steps to use a Library Draw Method:

1. Select Library Draw Method as the Draw Method Type.
The Context field will be enabled.
2. Select the Library that will provide the drawing method.
You may use any library, but the User Draw Methods library is most likely to be used.
3. Select the DM that you want to show on the tab.
If this drawing method uses parameters, you will be prompted to provide set those parameters for this instance
of the DM.
You may later use the Set Parameters button to change those selections.
Related topics: User Draw Methods, Drawing a DM with Parameters.

Steps to use a Page:

1. Select Page as the Draw Method Type.
The Context field will be set to "Pages" and disabled.
4. Click the Select Page button to open a menu of all the pages in this application.
Any page may be used, but in general, it is best to use a page that was designed to fit the area of this folder.
5. Select the Page that you want to show on the tab.
If this page uses parameters, you will be prompted to set those parameters for this instance of the page.
You may later use the Set Parameters button to change those selections.
Note that, the page's background image will not carry through to display in the tabbed folder.
Related topics: Adding and Editing Pages, Page Properties Parameters Tab, Edit the Parameter Values of a Page.

Frame
A frame is similar to a border, but has a greater range of options for customizing its appearance.

78 • How to Build an Application Developer's Guide (part 1)

Every frame is a rectangular shape, with or without rounded edges, with or without a fill color, and with or without edge
enhancements such as a raised or beveled border.

Three frames on a gray background.

Besides having their own color, frames can be configured to follow the application's color theme. They can also be
partially transparent.
The VTS Graphic Editor for a frame will appear as follows:

The Color Options section of the configuration will not be enabled if the Use Theme Color is selected. However, since
all frames can have a measure of transparency, this control is repeated outside the Color Options section of the panel.
(See also: Color Options - Adjust Image Hue)
The following frame styles are available. Note that the Use Theme Color option will work only with the frames shown
here in blue.

Developer's Guide (part 1) How to Build an Application • 79

If these options are not sufficient, you can also define your own frame shapes, as described in the following topic.

Define Custom Frame Shapes

Frames are built of nine images, which define the appearance of each part of the overall frame.
To create your own customized frames, you must create a folder that contains your own versions of these nine images.
The image names must match the location of the image on the overall frame.

For example, here are the images for the Raised, Rounded Frame:

While this example shows .PNG format images, any of .PNG, .JPG or .BMP image formats may be used.

Corner images must match the size of their adjoining edges, and be no larger than the number of pixels required to create
the corner. For reference, the largest corner image for any of the frame styles included with VTS, is 20x20 pixels.
Side images (Top, Bottom, Left and Right) must be no wider than the corners they connect to. They need not be square -
for example the chrome frame uses side images that are much longer than they are wide, in order to create the chrome
reflection effect.
The center image is optional. It is commonly included as a square to provide the fill color.
The color serves only as a starting point - developers may modify the hue of any frame when they add it to a page.

80 • How to Build an Application Developer's Guide (part 1)

Tag Icon Marker
The Tag Icon Marker is the symbol that displays a question mark on tags with the questionable flag set, and an
exclamation mark on tags with manual data.
While in edit mode, this marker shows up as a yellow diamond:
While an application is running, it shows up as the more familiar question mark or exclamation mark.

Its purpose is to allow your user-defined tag drawing methods to display the question or exclamation mark as
appropriate. See: User Draw Methods.
This symbol will be added to and configured for your Tag Drawing Methods automatically. If you are adding a Tag Icon
Marker manually, then the VTS Graphic editor should be configured as shown here in order to link the symbol to the tag
being drawn.

Tool Tip Areas

The Tool Tip can be used to add notes to a page. The note will be displayed as a Tool Tip when the pointer hovers over
the defined area and will otherwise not be visible.

The defined area for the tool tip is invisible while the application is running. To help the operators find the area, it should
be placed over a bitmap or label. While in development mode, the tool tip button will be displayed as a simple black
rectangle.

The Graphic Editor dialog for the Tool Tip button is as shown:

Developer's Guide (part 1) How to Build an Application • 81

Referring to the example image above, the title will be displayed using a larger font, and the tool tip contents will be
displayed using a smaller font.
You may enter multiple lines of text for the Tool Tip contents, with an overall limit of 255 characters. Note that each line
break you add will count as two characters.

The display of the tool tip is controlled by configuration variables such as TipOff (sets the number of seconds for which
the message will be displayed), TipFore (sets the foreground color of the message) and ShowTip (enables or disables
tool tips).
Please refer to: Application Properties for Tooltips to see a complete list of the configuration variables that you can use.

Grid Drawing Object

Use this tool to add a rectangular grid to a page. Once placed, the grid can be adjusted to any size and color that you
want.

82 • How to Build an Application Developer's Guide (part 1)

When placing the grid on a page, the reference handle is the lower right corner. Once placed, the VGE will allow you to
adjust the number of rows and columns as well as the color and style of the lines and background. You can adjust the
size and location of the grid after closing the VGE.

Grid Columns and Rows

Use the spin controls or type a number to set how many columns and rows will be included in the grid. Minimum of 1,
maximum of 999.

Line Color
Click on the button to open the Select Color dialog. You can set the lines to be transparent if none should be shown.

Background Color
Click on the button to open the Select Color dialog. You can set the background to be transparent if none should be
shown.

Grid Line Style

Provides a drop-down list of line style options including: Invisible, Solid, Dashed, Dotted, Dot-Dash or Dot-Dot-Dash.

Analog Clock
Use this option to add the following animated clock to a page. The clock can be positioned and re-sized like any other
drawing object.

The Graphic Editor for the clock contains a single user-configurable option: the selected Time Zone. The time zone list
includes both GMT offsets and major cities around the world.

Developer's Guide (part 1) How to Build an Application • 83

Meter Parts Library
The Meter Parts library contains tools that allow you to build your own photorealistic meters. The drawing methods
Meter 4 through Meter 13 are ready-made examples of what you can do with the tools in this library.

Note: To create your own meter, you will need to combine parts from this library with images from the Meters group of
the bitmap images library. Those images include: backgrounds, bezels, glass, indicators and tick marks.

The meter parts library includes five meter components: scale markers (Draw Scale), linear indicator, linear legend,
radial indicator and radial legend.
Quick Link:
For a tutorial on the process of building a meter, see:
Build a Custom Meter

Compass Indicator
Draws a compass needle where the needle image is whatever you select from the Meter Parts, Radial Indicator group.
You can apply Hue, etc if you would like to change the colors to something other than the default. Note that most of the
images have an insertion point which is at the center, bottom of the image. For a needle such as the one shown, you will
need to apply a negative offset to bring the vertical center of the needle down to the rotation (i.e. insertion) point.

The graphic editor for the Compass Indicator will appear similar to the following:

84 • How to Build an Application Developer's Guide (part 1)

Data Source
The source of the value being indicated. This can be any of:
Tag – select an I/O tag whose value will be displayed by the meter.
Numeric Value – useful only for testing.
Parameter – choose a parameter from the page where this meter is being drawn. When the parameter option is selected,
the data source display will be replaced by a drop-down selector, showing all of the page parameters that are of type Tag.
Expression – create a meter that shows a value calculated from several I/O tags.

Select Bitmap
The image used for the indicator. The meter parts group of the graphic library includes several images of radial
indicators, including compass needle images.. The reference point will always be at the bottom center of the image. For
those that include a pivot, part way along the image (example following) you can add an offset from center.

Developer's Guide (part 1) How to Build an Application • 85

Offset from Center
Since all images are designed to pivot about the center, bottom of the image, you will need to add a negative offset of
half the image height before the compass needle pivots about a point that looks natural.

Counter-Clockwise
When checked, the needle will move in a counter-clockwise direction to indicate increasing values.

Reference Angle
May be either a positive or negative value. Sets the initial angle of the compass needle relative to North (0-degrees).

Dampen Movement
If set, the needle's motion will be animated to move smoothly to position rather than jumping directly to the new value.

Minimum Angle
Sets the starting angle of the needle display (left side). Measured in degrees, clockwise from vertical. Defaults to 225
degrees.

Maximum Angle
Sets the end angle of the needle display (right side). Measured in degrees, clockwise from vertical. Defaults to 135
degrees.

Color Options
Adjusts the hue, etc. of the indicator image. Color control is described in the chapter: Color Options - Adjust Image Hue.

Scaling
Whether to use the tag's scaling values or to set a range directly in the indicator using the minimum and the maximum
value fields.

Draw Scale
Draws a series of scale marks for the meter in either a linear or a radial format as shown:

86 • How to Build an Application Developer's Guide (part 1)

The scale marks are a static image. You can adjust the appearance, number, size and color of the markers through the
graphic editor, but once set, they do not change. There is no link between the appearance of the scale markers and any
tag or parameter value.
The Graphic Editor dialog for the Draw Scale is shown in the following image:

Select Major Tick

The image used for the long tick marks. A simple line works best. Don`t worry about finding or making a perfectly sized
image for the marks. The individual tick images can be scaled using the Relative Size slider.

Select Minor Tick

The images used for the short tick marks. Normally the same style of line as the major tick mark, but shorter.

Number of Major Divisions

One major division will give you two major tick marks – one at either end of the scale. Each major division will be filled
with the ticks set in the number of minor divisions, therefore it is wise to avoid setting this value too high.

Number of Minor Divisions

Developer's Guide (part 1) How to Build an Application • 87

The number of small tick marks drawn between each major division will be set by this number minus one.

Relative Size
This slider allows you to scale the tick mark images. Thanks to this control, you do not need to create a new set of tick
marks for every possible meter size.

Linear Scale
When checked, the tick marks will be drawn in a linear format:

The controls, Orientation and Reflect Image are available only to Linear Scales.

Orientation
Can be set to either horizontal or vertical. It is important that the tick mark images selected are appropriate to the
orientation: Select vertical marks for horizontal scales and horizontal marks for vertical scales.

Reflect Image
The normal orientation of the scale markers is as a row across the top (when oriented horizontally) of a relatively large
area. You can choose Reflect Image to flip the markers to the opposite side of the area.

Radial Scale (Minimum Angle & Maximum Angle)

Causes the scale to be drawn in an arc (example below) The Minimum Angle (start of the scale) and Maximum Angle
(end of the scale). These are measured in degrees, clockwise from North.
The radial scale shown here has two major divisions, starts at 300 degrees and ends at 60.

Color Options
Adjusts the hue, etc. of the indicator image. Color control is described in the chapter: Color Options - Adjust Image Hue.

88 • How to Build an Application Developer's Guide (part 1)

Linear Indicator
Draws an indicator for a linear meter, either as a moving marker, or a bar that changes in length. An example of each is
shown in the following image, where the marker is the top red line:

Meter 13 is an example of a moving marker:

You could use a bar that changes in length to build a thermometer draw method.

Data Source
The tag that provides the value being indicated. This can be any of:

Developer's Guide (part 1) How to Build an Application • 89

Tag – select an I/O tag whose value will be displayed by the meter.
Numeric Value – useful only for testing.
Parameter – choose a parameter from the page where this meter is being drawn. When the parameter option is selected,
the data source display will be replaced by a drop-down selector, showing all of the page parameters that are of type Tag.
Expression – create a meter that shows a value calculated from several I/O tags.

Select Bitmap
The image used for the line. Note that the same image is used for both the moving marker line and the expanding
indicator (either scale or crop draw mode). The expanding indicator works by stretching the bitmap in the direction
indicated by the linear indicator.
The meter parts group of the graphic library includes two indicators. It is important to select the vertical bar for an
indicator that moves horizontally and the horizontal bar for an indicator that moves vertically.

Orientation
Whether the meter should move horizontally or vertically. Please see the note under Select Bitmap regarding the proper
choice of indicator for each orientation.

Reverse Direction
When checked, horizontal indicators will increase to the left instead of right. Vertical meters will increase down instead
of up.

Draw Mode
This can be one of:
Moving – represented by a moving line:

Scale – represented by an expanding bar that fades slightly

towards the maximum range.

Crop – represented by an expanding bar, that stays sharp to

its maximum range, but blurs along the sides.

Dampen Movement
Applies to the moving draw mode: If set, the line's motion will be animated as it moves to position rather than jumping
directly to the new value.

Number of Steps
If set to 0, the indicator shows the exact value. If set to a larger value, the indicator is divided into the given number of
steps and the display will round to the nearest step. So, for example, a step of 1 would mean all on or all off. 20 steps on
an indicator that ranges from 0 to 100 would round the display to the nearest multiple of 5.

Color Options
Adjusts the hue, etc. of the indicator image. Color control is described in the chapter: Color Options - Adjust Image Hue.

Scaling

90 • How to Build an Application Developer's Guide (part 1)

Whether to use the tag's scaling values or to set a range directly in the indicator using the minimum and the maximum
value fields.

Linear Legend
Draws a numeric legend for a linear meter. An example, with three labels (0, 50, 100) is shown beneath a Linear
Indicator:

The following options are available for you to control the Linear Legend's appearance:

Tag
Selecting a tag or a page parameter is an optional step. If provided, the legend can take its minimum and maximum
values from this tag or parameter’s value. (Normally, this will be the same tag or parameter that is used for the linear
indicator).
Alternatively, you can ignore this field and specify minimum and maximum values for the display in the Scaling section.

Font
Select a font tag to control the font and other display parameters for the legend text.

Number of labels

Developer's Guide (part 1) How to Build an Application • 91

Sets the number of labels to display in the legend, where 3 is the minimum number possible. There will always be a label
at the beginning and at the end of the range with the remaining labels spaced evenly between them.

Scale Label Size

When checked, the text size of the label numbers will change in scale as the overall legend is resized.

Color
Opens the color selector where you can set the text color.

Direction and Rotation

The legend can be oriented horizontally or vertically. The numbers will increase in value from left to right or bottom to
top unless the direction is reversed.

Scaling
If a tag is specified, you can use that tag's scaling to set the beginning and end of the legend's range. Otherwise, you can
specify minimum and maximum values of your own.

Radial Indicator
A radial indicator is used to show values on a round meter. An example, created with the default values, is shown here:

As shown, the outer arc and vertical division line are visible only while in design mode. Their purpose is to help you
scale and place the indicator and will vanish when the application is put into run mode. The needle will remain and can
be any image you wish.

The following image shows the default Graphic Editor dialog for the radial indicator.

92 • How to Build an Application Developer's Guide (part 1)

Data Source
The source of the value being indicated. This can be any of:
Tag – select an I/O tag whose value will be displayed by the meter.
Numeric Value – useful only for testing.
Parameter – choose a parameter from the page where this meter is being drawn. When the parameter option is selected,
the data source display will be replaced by a drop-down selector, showing all of the page parameters that are of type Tag.
Expression – create a meter that shows a value calculated from several I/O tags.

Select Bitmap
The image used for the indicator. The meter parts group of the graphic library includes several images of radial
indicators. The reference point will always be at the bottom center of the image. For those that include a pivot, part way
along the image (example following) you can add an offset from center.

Developer's Guide (part 1) How to Build an Application • 93

Offset from Center
Some needle images are designed to look like they pivot on a mid-point. Since all needles actually pivot on the bottom,
center of the bitmap, you may need to add a negative offset before the image pivots about a point that looks natural.

Counter-Clockwise
When checked, the needle will move in a counter-clockwise direction to indicate increasing values.

Dampen Movement
If set, the needle's motion will be animated to move smoothly to position rather than jumping directly to the new value.

Minimum Angle
Sets the starting angle of the needle display (left side). Measured in degrees, clockwise from vertical. Defaults to 225
degrees.

Maximum Angle
Sets the end angle of the needle display (right side). Measured in degrees, clockwise from vertical. Defaults to 135
degrees.

Color Options
Adjusts the hue, etc. of the indicator image. Color control is described in the chapter: Color Options - Adjust Image Hue.

Scaling
Whether to use the tag's scaling values or to set a range directly in the indicator using the minimum and the maximum
value fields.

Radial Legend
Draws a numeric legend for a radial meter. An example, with 5 numbers drawn, is shown here inside a Radial Indicator:

94 • How to Build an Application Developer's Guide (part 1)

The black arc that runs from the minimum angle to the maximum angle and the vertical divider line based at the center of
the arc, are displayed only while the system is in design mode. They will vanish as soon as the application is put into run
mode.
The numbers will always be drawn horizontally.

The graphic editor dialog for a Radial Legend is shown in the following image:

Tag
Selecting a tag or a page parameter is an optional step. If provided, the legend can take its minimum and maximum
values from this tag or parameter’s value. (Normally, this will be the same tag or parameter that is used for the radial
indicator).
Alternatively, you can ignore this field and specify minimum and maximum values for the display in the Scaling section.

Font
Select a font tag to control the font and other display parameters for the legend text.

Minimum Angle

Developer's Guide (part 1) How to Build an Application • 95

Sets the starting angle of the legend display (left side). Measured in degrees, clockwise from vertical. Defaults to 225
degrees.

Maximum Angle
Sets the end angle of the legend display (right side). Measured in degrees, clockwise from vertical. Defaults to 135
degrees.

Number of Labels
Sets the number of labels to display in the legend. There is no minimum, but legends look best with at least 3.

Scale Label Size

When checked, the text size of the label numbers will change in scale as the overall legend is resized.

Color
Opens the color selector where you can set the text color.

Counter-Clockwise
When checked, the legend will increase in a counter-clockwise direction.

Scaling
If a tag is specified, you can use that tag's scaling to set the beginning and end of the legend's range. Otherwise, you can
use these fields to specify minimum and maximum values of your own.

ODBC Manager Library

The ODBC Manager library consists of a single tool: the Show Stats button. Clicking on the library entry immediately
opens the VTS Graphics Editor for drawing a Show Stats button on the screen.
The Show Status button is described in the chapter Drawing Tags, under the topic: Show Stats Drawing Method.
The OBDC Statistics screen is described in the next topic: Monitoring the ODBC Connection.

Monitoring the ODBC Connection

ODBC Connection statistics may be viewed by adding a Show Stats button to your application. This button can be added
from the ODBC manager library (see the Show Stats Drawing Method in the chapter Drawing Tags).
A Show Status button, when clicked on by the operator, will open the ODBC Statistics screen as shown in the following
image.

96 • How to Build an Application Developer's Guide (part 1)

 In the upper left corner, a selection list allows you to choose which of the ODBC data source to view of the ones
configured for this application.
Enabling the log causes all activity related to the driver to be stored in a file named ODBCManager.LOG. An example of
the information logged is as follows:
Date/Time : 2008-08-18 10:33:05
VTS Error : 0
VTS Message : No Error
Owner : LogLoop
DSN : august
Query : INSERT INTO VTS_TAGDATA
(TagID,LogTimeStamp,TagVariableValue,ManualFlag,QuestionableFlag,AlarmFlag)
VALUES (1,#2008/08/18 13:33:05#,0,0,0,0)
ODBC Error : 0
ODBC Message : N/A
SQL State : N/A

Note that it is possible to close the ODBC Statistics screen while the log is still enabled. Use this feature with caution: it
can result in an excessively large log file being created over time.

Site Tools Library

VTScada-based applications include a Site Tools library. The Site Tools library contains four tools that are useful in the
development of VTScada applications. These are:
• Program Spawn. When given the path to an executable file on your computer, allows you to launch (spawn) that
program from within VTScada. See: Program Spawn.
• Pulse Beacon. For use in creating a custom map icon. Provides the animated dot that marks the active site on a map.
See: Create Custom Map Icons.
• The Site Legend. A static image, providing a guide to the colors used in any of the site draw pins. See: Site Legend.
• The Site Map. See Site Map.

Developer's Guide (part 1) How to Build an Application • 97

• Sites. Replaces the VTScada Station list as of release 10.2 This can be used to draw a Site List as a component of
another page. In general, it is better to use the Site List page directly. See: Site List Page.

If you are looking for the Site Draw drawing method, please see: Site Draw Drawing Method.
If you are looking for the page opened by the Site Draw drawing method, see Site Details Page (VTScada).

Site Legend
Provides a legend that can be placed in a page to explain the colors used in the concentric rings of a site symbol.

The Site Legend can be accessed via the Site Tools Library. To do so:
1. Click the Configure button to open the Configuration Toolbox.
2. Click the Libraries button to open the Configure dialog.
3. Expand the Drawing Tools menu item.
4. Expand the Site Tools Library menu item.
5. Right-click on the Site Legend menu item.
6. Click the Draw button place a site legend on the screen. The Site Legend editor will open.
The Legend has no configurable parameters; therefore, you need only click the OK button to finish drawing the legend
on the currently open page. An example of the Site Legend follows:

Note: VTScada makes it easy for you to change the display colors used in the Legend and for site symbols on the
Overview page. The application properties responsible for the colors used in the legend and for site symbols can be
found in Application Properties for Colors.

Program Spawn
Links a button on an application page to a specified external application (e.g. Microsoft Excel). When the button is
clicked, the specified application will run.
The Program Spawn tool can be accessed via the Site Tools Library. To do so:
1. Click the Configure button to open the Configuration Toolbox.
2. Click the Libraries button to open the Select Library dialog.
3. Select the Site Tools Library in the Select Library dialog.
4. Click the Draw button to view the tools in the Site Tools Library.
5. Click the Program Spawn button to place a Program Spawn button on the current page.
6. The Program Spawn Editor graphic editor dialog opens. An example is displayed below.
7. Enter the full path and name of the .exe file you want to run when the button is clicked.
8. Provide a label for the button in the Button Text field
9. Click on OK to complete the process.
If the label is to include an ampersand (&), then the & character will need to be doubled in order to appear.

98 • How to Build an Application Developer's Guide (part 1)

The information below describes the elements of the Program Spawn Editor dialog.

Program Spawn Graphic Editor Dialog Elements

Program Path and Name
Enter the full path, name, and extension of the program you wish to launch when the
completed button is clicked (e.g. "C:\Program Files\Microsoft Office\Office\MSAccess.exe").
Note: If it is your intention to relocate this VTScada application to another PC, ensure that
you update the Program Path and Name field accordingly.
Button Text Enter the text you wish to be displayed as the label on the completed button (e.g. Run MS
Access). Labels should be kept short and precise, as the length of the label ultimately
determines the size of the button.

Station List (VTScada)

Obsolete as of VTS version 10.2
See: Site List Page for the replacement to this feature.

System Status Tools Library

Contains a collection of tools that help you monitor various aspects of your application.

Developer's Guide (part 1) How to Build an Application • 99

The Historian Status monitors each Historian tag's connection and I/O processes. For complete details, see: Monitor the
Historian's Connection.
The Modem Status tool is used to add a grid to any page, showing various metrics for the modems in your application.
See: Modem Status.

Custom Libraries
A right-click on the "Drawing Tools" node in the Configure dialog will open a context menu with a single entry: New.

You can create your own library entries, into which you can add your own User Drawing Methods. As you accumulate a
number of these methods, you may find it useful to organize them into new libraries.

The New command opens the following dialog, here showing a new library called "Monitoring Tools" about to be
created.

After clicking on OK, the tools library will have a new entry as shown in the following image. Note that the entries will
always be in alphabetical order.

Having created a new library, you can then:

• Add tools to the library
There are several ways to do this. See: User Draw Methods.
• Rename the library
To rename a library, right-click on its node and choose Rename from the context menu. The following dialog
box will appear, prompting you for a new name:

100 • How to Build an Application Developer's Guide (part 1)

• Delete the library
To delete a library, right-click on its node and choose Delete from the context menu. The following dialog box
will appear, prompting you to confirm that you wish to delete the library. Select OK to do so.

The VTS Graphic Editor

The VTS Graphic Editor provides a consistent user interface for the creation of every display element that you add to a
application. Every display element in VTS makes use of this tool. The graphic properties that can be edited will vary
according to the object being placed – rectangles have a fill color, arcs have only an outline color.
For every object property that can be controlled, including color, line weight, visibility, movement, scaling, etc., you can
set a constant value, or you can link the property to a tag or expression, thereby causing the object to change as the
monitored conditions change.
In general, the process to add a shape or object is:
1. Select the desired object from the configuration toolbox.
2. Indicate where the object is to be placed on the page using the left button of the mouse.
3. Use the Graphic Editor to define its appearance.
The same process is also used when drawing tags.

A sample of the Graphic Editor appears below. This is what you would see if drawing an arc:

Other shapes will have slightly different menu options. For example, rectangles and ellipses have a fill property;
therefore their version of the Graphic Editor will include that option. Pipes do not have outlines, but they do have color.

Developer's Guide (part 1) How to Build an Application • 101

In all cases, you can simply press the OK button at the bottom of the dialog box to accept the default values.
Note that changes are applied to the object as they are made in the editor – you do not have to wait until you press OK in
order to see the effect of your edits.

Pressing the Cancel button, or the X in the upper right corner, will close the dialog box and discard any of the changes
you have made.

Using the Graphic Editor’s Menu

On the left side of the graphic editor is a menu showing the options available for that shape.
Using a rectangle as an example, the menu would initially appear as shown below:

Indicator dots:
All the dots are initially grey. This indicates that none of the properties have been changed from their default values. For
each property you modify, the related dot will change to green.
In the example below, a fill color has been set. Note the green dot beside Fill as well as beside the word Ellipse. These
indicate properties that have had values set.

Expanding Menus:
Some menu items expand to display more options. In the next image, both Scaling and Movement have been expanded.
If one item within an expanding menu is set, both its dot and the dot at the top of that topic will also change color, as
shown below for Scaling.

102 • How to Build an Application Developer's Guide (part 1)

The panel display will also change, depending on whether you select the root of an expanding menu, or one of the
branches within it. When the root of the expanding menu is selected, all of the sub-menu items will be displayed in the
panel. When only one branch item is selected then the parameters for only that property will be displayed in the panel.
The following two images illustrate the difference:

Developer's Guide (part 1) How to Build an Application • 103

Changes to multiple properties
Selecting the name of the object (top of the menu, left panel) will cause the panel on the right of the dialog to display all
of the properties whose values have been set. For example, if both the fill and the top scaling of a rectangle have been
set, selecting the word “Rectangle” at the top of the menu would result in a dialog similar to the following:

Multiple Levels of Control

Most of the properties have more than one level of control. Note the button circled in the figure below. This opens a
selection, from which you can choose whether the selected property should be adjusted via a simple menu (color only),
an advanced menu (color, pattern and background) or should not appear (None).

Note: Not all the properties in the menu will have all three control levels. For example, scaling provides a choice of only
"None" or "Advanced".

• None - In the case of fill or outline, this is equivalent to "transparent". Otherwise it means "default value".
• Simple - You will be able to change one option - normally whatever is most common for that property such as the
color for fill. Note that several properties skip this control level, jumping directly from None to Advanced.
• Advanced - You will be able to control the property with several options. For example, with Fill this would include
setting a pattern and a background color as well as a base color.

104 • How to Build an Application Developer's Guide (part 1)

Control via Tags, Expressions and Parameters
VTS gives you a wide selection of methods for controlling each property of a graphic object. This range of control
allows you to create screens that can be static or that can respond dynamically to show changes in system conditions.

Referring to the following image, every graphic property has a drop-down menu of control methods. The first choice in
each list is always the native data type for the value. In the example shown here, it is Color. For other properties, it might
be Width, Line Style or Tag Type as matches the property being set.

The following topics describe how to use each of the available control methods.

Control by Native Value

Native Value may be any of Color, Line Width, Line Style, etc., depending on the property being set. Selecting this
option will result in the VGE providing an appropriate selection tool for setting the property value.

Three properties with control by native value selected.

Control by Tag Value

Choosing to control a property based on Tag Value will result in the property’s value changing as the selected tag’s value
changes. While this allows you to create dynamic displays, this method of control is not suitable for all properties.
Color, for example, needs to be an integer value between 0 and 255. A tag whose value ranges as an analog floating
point might not map well to color selections.
If the option “Use Tag Scaling” is selected, the tag’s value will be normalized between 0 and 1 across its output range. If
the minimum and maximum values are set instead, the value will be normalized such that, when the tag’s value
approaches the Minimum Value, 0 will be output. When the tag’s value approaches the Maximum Value, 1 will be
output. If the tag’s value is halfway between the minimum and maximum, the output will be 0.5 and if the tag’s value is
twice the maximum, the output will be 2. You could create a control output that ranges in value between 0 and 10 by
setting the Minimum Value to the tag’s minimum and the Maximum Value to 10% of the tag’s maximum.

Developer's Guide (part 1) How to Build an Application • 105

When you choose to control a property by tag value, the VGE will look similar to the following:

The tag selector button (shown circled) opens the tag browser, from which you can select any tag within the application.

Control by Expression
Choosing to control a property based on an expression will cause the following options to be displayed in the VGE.

In the example shown, the expression editor has been opened by clicking on the button shown circled. This expression is
examining the value of an Analog Input tag for a pressure monitor, named TankPressure. If its value goes above 80, then
the text will read “Pressure exceeds safe limits”. Otherwise, the text will read “Pressure within limits”. Note the tag
selector button within the expression editor window. It is often much easier to use this to select a tag than to type out the
name, which must be placed within [< >] brackets.

Above the button that opens the expression editor (circled in the preceding image) is a quick link to either the tag
browser (many expressions use tag values) or to an appropriate selector for the property being controlled. For example, if
the property is color, a quick link to the color selector will be provided for your convenience. The following image
shows where to find this link:

106 • How to Build an Application Developer's Guide (part 1)

For a guide to expressions, see: Creating Expressions.

Control by Normalized Expression

A normalized expression provides all the same features as an expression, but will also include scaling options with the
expression editor (shown in the following image). While control via a plain expression will use whatever value is
calculated by that expression, control via a normalized expression will be scaled such that, as the calculation approaches
the Minimum Value the result will be 0 and as the calculation approaches the Maximum Value the result will be 1.

Control by Parameter
Properties can be controlled by named page parameters. The parameters cannot be created on the fly in the VTS Graphic
Editor – they must already exist and be defined in the current page instance before they can be selected.

Control by parameter can be a very useful tool when creating new drawing methods (i.e. user-defined groups) and
parameterized pages. It is not meant to be used to control an individual object on a page that will not be copied. For such
cases, a tag value or an expression provides more direct control over an object's properties than a parameter.
Please see: Working with Parameters to gain an understanding of how to use this feature.

Developer's Guide (part 1) How to Build an Application • 107

Using the VTS Graphic Editor
Most of the graphic properties controlled by the editor apply to more than one type of object. For this reason, the details
for setting each of the properties, (e.g. fill, outline, etc.) will be described here in general, rather than within the
instructions for drawing each type of shape.
For most of the parameters, you can select the level of control that you want to have.

Some parameters will have two levels, None and Advanced, while others will have three as shown. Where the parameter
is Fill or Outline, the control level, "None" can be taken as equivalent to "Transparent". For all other parameters, the
control level, "None" can be taken as "No change applied".

VTS Graphic Editor: Fill

Applies to: Chord, Ellipse, Pie, Polygon, Rectangle, Text
Control Levels Available: None (*), Simple, Advanced
Defaults to: Simple
(*) The None option should be interpreted as "No fill", or "Invisible".
Color: The Color Selector window (shown superimposed on the Editor Dialog below) opens when you select the button
shown in the circle.
From the dialog, select whichever color you want to use for the fill. For more information on colors, see Working with
Colors.

Note: You can change the default colors displayed for the fill and outline of the geometric shape tools using the
DefGraphicBColor and DefGraphicPColor application properties (see: Application Properties for Colors).

108 • How to Build an Application Developer's Guide (part 1)

(Background image shows the Graphic Editor with the Advanced option selected.)

VTS Graphic Editor - Advanced Fill Options

The figure below shows the advanced fill options. Note that this provides access to all options of how a closed object's
fill can appear.
The Pattern Selection has been expanded in this figure to show some of the available patterns. Those who have used
early versions of VTS will note that the old system of stepping through all the patterns, one at a time, has been replaced
by a more direct selection tool.

25 patterns are available, a listing of which is available in Fill Patterns. Referring to the figure below, the dark section of
a pattern will take whatever color is selected in the Color choice.

The light areas of the pattern as shown in the selector, will take on the background color, which is chosen in the same
way as the foreground color.

Developer's Guide (part 1) How to Build an Application • 109

VTS Graphic Editor: Outline
Applies to: Arc, Chord, Ellipse, Line, Pie, Polygon, Rectangle
Control Levels Available: None(*), Simple, Advanced
(*) The None option should be interpreted as "No outline", or "Invisible".
Defaults to: None, except for Lines and Arcs which default to Simple
Color: When the Outline property is set using the Simple control level, you will have a choice of outline color.
The Color Selector window opens when you select the button shown in the circle (image below).
From the dialog, select whichever color you want to use for the outline. For more information on colors, see Working
with Colors.

Note: You can change the default colors displayed for the fill and outline of the geometric shape tools using the
DefGraphicBColor and DefGraphicPColor application properties (see: Application Properties for Colors).

(Background image shows the Graphic Editor with the Advanced option selected.)

110 • How to Build an Application Developer's Guide (part 1)

VTS Graphic Editor: Advanced Outline Properties
The 2 figures below show the advanced outline properties. In addition to Color, you can also set the outline style to any
of the 5 options shown, and the outline width to be any of 1 to 30 pixels wide.

Both Editor and width provide the option of control via tag or expression, in addition to selecting directly from the menu
shown above. This is controlled with the button shown circled in the figure below
Being able to adjust the outline width in response to a changing tag value may be useful if you are also setting the scaling
property to adjust with a tag's value. This will allow you to set a narrower outline when the scale values are small and a
wider line when the scale values are large.

Developer's Guide (part 1) How to Build an Application • 111

VTS Graphic Editor: Coordinates
Applies to: All objects
Control Levels Available: None(*), Advanced
(*) The None option should be interpreted as "No user-defined settings to change the current size" .
Defaults to: Advanced
Allows you accurately define the size and location of an object. You can numerically set the Left, Right, Top and Bottom
coordinates of the object, or you can set the Left and Top coordinates, then use the Width and Height values to define
object's size.

The following rules apply:

• If you provide a Width, the right edge will move to match the new value.
• If you provide a Height, the bottom edge will move to match the new value.
• Changes that you make to any of Left, Bottom, Right or Top will always change the Width and Height values.
• If you set a Right side value that is less than the Left side value, or any other similar combination, the values will
simply switch automatically. The smaller of Left or Right will always become left and the smaller of Top or Bottom
will always become the top.
• Left cannot be the same as Right and Top cannot be the same as Bottom. A minimum size of 1x1 is enforced.
• You cannot set a value outside the current page area.
The Left, Right, Top and Bottom coordinates refer to the object's bounding box. This may not be the same as the visible
portion of an object. Objects such as a Pie or a Chord have a bounding box that matches the overall elliptical shape that
the visible portion is built from.

VTS Graphic Editor: Color

Applies to: Text
Control Levels Available: n/a
Defaults to: None

112 • How to Build an Application Developer's Guide (part 1)

Allows you to set the foreground color of the selected text. Color may be set using any of the color selector, a tag value
or an expression value.

See also: Select Color Dialog.

VTS Graphic Editor: Scaling

Applies to: Arc, Bitmap, Border, Chord, Ellipse, Line, Pie, Pipe, Polygon, Rectangle, Text
Control Levels Available: None, Advanced
Defaults to: None
The default control level is "None". In this case, "None" means that no scale factor has been applied. This is equivalent
to saying that the object is scaled to 100% of the size it was drawn.

Note that the menu provides 5 ways that the object can be scaled: Left, Bottom, Right, Top and Overall. For the first four
options, each refers to which side of the object will be adjusted in response to a change in scale factor. In the case of
"Overall", the entire object will scale relative to its center point.

A change in scale does not affect the number of pixels used to draw an object's outline. The thickness used for the outline
will remain un-affected by a scale change unless the outline's width is also controlled by the same tag or expression. This
can result in outlines which look out of proportion to the rest of the object if there is a large variation in the object's size.
Refer to the section, VTS Graphic Editor: Advanced Outline Properties, for more information on adjusting the outline
width.

Developer's Guide (part 1) How to Build an Application • 113

If the tag's value changes over a larger range than you would like the object to change, you can apply your own scaling
factor to the tag's values with the Minimum Value and Maximum Value fields.

VTS Graphic Editor: Movement

Applies to: Arc, Bitmap, Border, Chord, Ellipse, Line, Pie, Pipe, Polygon, Rectangle, Text
Control Levels Available: None, Advanced
Defaults to: None
The default control level is "None". In this case, "None" means that no movement factor has been applied. This is
equivalent to saying that the object does not move.
Movement can be controlled by either a tag or an expression, as selected using the button shown in the figure below.
Note in the menu that you have a choice of Horizontal Movement and Vertical Movement. Defining both will result in
diagonal motion if the values for both are changing at the same time.

You have two options for limiting the motion of an object. First, you can override the tag's scaling by setting a Minimum
Value and a Maximum Value.
Setting a Minimum Value of 0 and a Maximum of 100 is equivalent to using the Tag Scaling.
Leaving the Minimum Value at 0 and adjusting the Maximum Value to 200 would be equivalent to scaling to 50%.
Setting the Maximum Value to 50 would be equivalent to scaling by double the distance.
You also have the option of setting a maximum number of pixels over which the object is permitted to move. A setting
of 0 means that the object cannot move.

114 • How to Build an Application Developer's Guide (part 1)

Note that the maximum number of pixels is relative to the scaling set with the Minimum and Maximum Values. For
example, if the maximum number of pixels is 10, the Minimum Value is set to 0 and the Maximum Value is set to 100,
then the object can potentially move over 10 pixels. If the Maximum Value is changed to 50, thus doubling the scaling,
then the object will move over 20 pixels.

VTS Graphic Editor: Visibility

Applies to: Arc, Bitmap, Border, Chord, Ellipse, Line, Pie, Pipe, Polygon, Rectangle, Text
Control Levels Available: None, Advanced
Defaults to: None
The default control level is "None". In this case, "None" means that no external factor has been applied to the visibility,
thus it is visible as drawn.
Note that, in the case of a shape such as a rectangle, if both the fill and the border are set to "None", the object will be
invisible regardless of how the Visibility is set. Having a visibility property in addition to being able to set color and fill
to "None" allows you to set those values to something meaningful and still have the object vanish when conditions
dictate that it should not be seen.

Visibility can be controlled by a tag, an expression or a parameter, as selected using the button shown circled in the
figure below.

The example shown in the above figure uses a tag named “AI_001” to control the visibility. The rectangle will be visible
whenever when AI_001’s value is greater than 0.

Select Bitmap
Many graphic objects rely on an image file to provide their appearance and size. Besides the Bitmap images button in the
toolbox, you may need to select an image in order to draw a custom meter, a selector switch, the arrows for input sliders
and the image for an Image Change object.
In all of these cases, the VTS Graphic Editor will include a button labeled, "Select Bitmap" or "Set Bitmap".

Developer's Guide (part 1) How to Build an Application • 115

Clicking this button opens the Select Bitmap library of images.

Each image button shown here is a group - click on the type of image you are interested in to see a selection of related
images.
When the images within a group are displayed, the dialog will include a "Previous" button. You may click this to back
out of the group, should you wish to view the contents of another.
There are over 4000 images in the various image groups and you can easily add your own images. New images can be
added to existing groups, or you can create new groups.

116 • How to Build an Application Developer's Guide (part 1)

Add New Bitmap Groups
Groups are used to organize images. If none of the 48 existing groups are appropriate for the images that you intend to
import, you can add new groups as required.
The following steps will create a folder in your application's Bitmaps directory, copy an image of your choice to use as
the thumbnail for that folder, and will register both with the application, thus avoiding the need to use the Import File
Changes button.

Note: If you duplicate an existing VTS group name and provide a local thumbnail image for it (which is not optional),
the Select Bitmap dialog will then show the same group twice. They may have different thumbnails, but will contain the
same set of images - both the VTS set and your own. If your intention is to add new images to an existing group,
navigate to that group and use the Import button.

1. Click the New Group button at the bottom of the Select Bitmap dialog.
The New Group dialog opens.

1. Provide a name for the new group.

If you have already created a group of this name, VTS will ask if you wish to overwrite it.

Note that this overwrites only the local thumbnail image being used to represent your custom group, not the
group folder or the collection of files within it.
2. Use the Browse button to select a thumbnail image.
The image will be re-sized to fit the Select Bitmap display.

You can also create image folders by working directly with the bitmap files and folders, then using the Import File
Changes button in the VAM. This older technique may still be useful if you wish to change a local folder name, or delete
a folder. See: Adding Custom Graphics to VTS.

Import Bitmap Images

Images are imported into the current group. Before proceeding, ensure that you have opened or created the appropriate
group for the image you intend to import.
1. From the Select Bitmap Dialog, click the Import button.
2. Locate and select the image you wish to import.
3. Click the "Open" button in the Import Image navigator.
The image is copied to the application's Bitmaps folder (or a matching group's sub-folder within Bitmaps) and is
now available in the Select Bitmaps dialog.

Developer's Guide (part 1) How to Build an Application • 117

Note that the VTS color rules apply to imported images. Pure black (RGB 0, 0, 0) is treated as transparent. Active
orange (RGB 255, 160, 0) is used with the Image Change drawing method. See: Special Colors.

Move, Rename or Delete Bitmap Images

These operations must be done at the file level. There are no user-interface tools for moving, renaming or deleting an
image.

Note: Before proceeding with the following instructions, ensure that the Select Bitmap dialog and the Configuration
Toolbox are both closed. This allows the version control system to finish recording any file changes made with the user
interface before you begin to work directly with those files.

All bitmaps are stored within a folder named Bitmaps.

In the case of bitmap groups, the Bitmaps folder will contain both a sub-folder named after the group, and an image (in
the Bitmaps folder, not the sub-folder), also having the name of the group. New entries in the Select Bitmap dialog, both
groups and images within groups, are created based on the presence of that bitmap file.
Bitmaps and bitmap groups that come with VTS are stored in the VTS installation directory. You should not change the
files in the installation directory as later updates to your VTS installation may overwrite your changes. Always work in
the application's folder structure, or the folder for your application's OEM layer.

To rename a bitmap image:

1. Using Windows Explorer™, navigate to your application's Bitmaps folder, or the group folder within Bitmaps.
2. Rename the image file.
3. In the VAM, click the Import File Changes button for your application.
4. Provide a comment, describing the fact that you have changed a bitmap name.

To move a bitmap image:

1. Using Windows Explorer™, navigate to your application's Bitmaps folder, or the group folder within Bitmaps.
2. Move the bitmap file from its present folder to the one where you would like it to be.
3. In the VAM, click the Import File Changes button for your application.
4. Provide a comment, describing the fact that you have changed a bitmap name.

To delete a bitmap image:

1. Using Windows Explorer™, navigate to your application's Bitmaps folder, or the group folder within Bitmaps.
2. Delete the file.
3. In the VAM, click the Import File Changes button for your application.
4. Provide a comment, describing the fact that you have changed a bitmap name.

118 • How to Build an Application Developer's Guide (part 1)

To rename, move or delete a bitmap group:
As above, except that there are two parts to a bitmap group: the folder and the thumbnail image. Both will need to be
modified.

VTS Graphic Editor: Options Unique to Images

The Panel menu option appears for both Bitmap images and Borders, but has very different features for each.
In the case of an Image, the Panel provides a place for you to select the image to be displayed and the colors to be
applied to it. The Color selector button allows you to select a color from the image that will be invisible – useful in the
case of an image that includes a solid background if you do not want the background to be visible on your page.
The Mirror Image checkbox allows you display the image mirrored left to right about its vertical center.
Images can be rotated to any angle from 0 to 359.9 degrees. You can specify the rotation angle numerically (using either
the slider or the data entry field). You can also choose any of a tag, an expression or a parameter as the source of the
rotation angle. For details on how these options work, see: Control via Tags, Expressions and Parameters.
Rotation is applied clock-wise.

You can add your own images to the list of those available. See: Select Bitmap for instructions.

This editor also includes the Color Options control to allow you to adjust the hue and other color properties of the image.
See: Color Options - Adjust Image Hue.

VTS Graphic Editor: Options Unique to Borders

In the case of a Border, the Panel provides a place for you to set the appearance of the border. Refer to the notes on the
Border Tool later in this section for details on how the attributes work.

Developer's Guide (part 1) How to Build an Application • 119

VTS Graphic Editor: Options Unique to Pipes
Pipes are drawn with a color range rather than a solid color. Therefore, the color selection is done with the Select Color
Range dialog box rather than the Select Color dialog used by Fill and Outline.

The Select Color Range dialog appears as shown in the figure below. Select the range you want for the pipe.

Width
Pipe width is set in pixels, with an available range of 1 to 30. The default value is 7. Like all other display properties, the
width can either be set directly, or controlled by a tag value or an expression.
The current value is always the one shown on top when the list of widths is opened. For example, in this case the pipe’s
current width is 7 pixels.

120 • How to Build an Application Developer's Guide (part 1)

VTS Graphic Editor: Options Unique to Text
(See also: Drawing Multi-Line Text)
The Text option within the Text object's menu provides a means for you to type the text that is to be displayed. You have
the option of setting either an un-changing text message, or of using an Expression. The figure below shows the default
text, set when you first open this dialog (“Sample Text”).

By using an expression, you can create text messages that change in response to changing values in the application. The
example below shows an expression that checks the value of an Analog Input tag named Pr_AI1. When the value is
below 80, the message will read "Pressure within limits", but when the pressure exceeds 80 the message will change to
"Pressure exceeds safe limit". Used in conjunction with a changing fill color, this can provide a warning which is both
informative and easily spotted.

Developer's Guide (part 1) How to Build an Application • 121

Horizontal Alignment
The horizontal alignment of any particular line of text may be set to Left, Center or Right as shown in the figure below.
The default will be Center.

Text Font

122 • How to Build an Application Developer's Guide (part 1)

Clipboard Tools
These tools work with the Windows™ clipboard to allow you to quickly duplicate or delete objects on a page.
The objects that you see and work with on a page are the visual representations of the code found in page source-files. If
you copy a tag drawing method, pipe or graphic object, what will actually be placed on the clipboard is the VTS script
code for that object rather than a bitmap image. This fact provides you with a powerful development tool. You can copy
objects from a page and paste them into a source file as code.
Note that in addition to the buttons described in the following topics, the standard Windows™ keyboard shortcuts will
work as well; Ctrl-C for copy, Ctrl-V for paste, Ctrl-X for copy & delete and the Del key to delete.

Copy Tool

For reproducing objects on the page.

Note: VTS also allows you to use keyboard shortcuts to select, copy, and paste multiple objects, as described in
"Working with Objects".

The Copy Tool enables you to perform rapid application development in applications where multiple pages have similar
layouts, as you can copy objects on one page, paste them to a new page, and then reassign the tags associated with any
tag drawing methods.
You can use the Copy Tool to reproduce one or more selected objects as many times as you require. Simply select the
object(s) you wish to copy using the Pick Graphics tool or keyboard shorts, and then click the Copy Tool button. A
preview of the objects you have copied will be attached to your mouse pointer. Position the preview objects on the
application page and click to drop a copy. You can continue to position the mouse pointer and click to make as many
copies of the selected object(s) as you wish. When you have finished, right click to drop the last copy and deactivate the
Copy Tool.

Cut Tool

For deleting objects from a page, while placing them on the clipboard so that they may be pasted in again
elsewhere.

Note: VTS also allows you to use keyboard shortcuts to select, copy, and paste multiple objects, as described in
"Working with Objects".

The Cut Tool works the in a similar way as the copy tool except that it also removes the original object selected. It
enables you to perform rapid application development in applications where multiple pages have similar layouts, as you
can cut objects on one page, paste them to a new page, and then reassign the tags associated with any tag drawing
methods.
The only visible result of using the cut tool by itself is to remove the selected object(s) from the page. To reproduce them
elsewhere in the application you will also need to use the paste too, described in the next section:

Paste Tool

For inserting objects onto a page, where the objects had previously been placed onto the clipboard using either the
copy tool or the cut tool.

Note: VTS also allows you to use keyboard shortcuts to select, copy, and paste multiple objects, as described in
"Working with Objects".

Developer's Guide (part 1) How to Build an Application • 123

The Paste Tool works the in a similar way as the copy tool except you must first select the items to be pasted by using
either the copy or the cut tool. It enables you to perform rapid application development in applications where multiple
pages have similar layouts, as you can cut or copy objects on one page, paste them to a new page, and then reassign the
tags associated with any tag drawing methods.

Delete Object Button

To delete an object, select it using the Pick Graphics tool, and then click the Delete Object button to remove the
object from your page. You can also delete selected objects from you pages using the Delete key on your keyboard.

Note: In the case of tag drawing methods, when you delete a drawing method from your application page, you are not
deleting the tag associated with that drawing method. The tag can be drawn again using the same drawing method or a
different drawing method.

Drawing Graphic Objects

The following sections provide detailed instructions for drawing each of the various graphic objects.

Drawing Arcs

To draw an arc, select the arc button from the configuration toolbox or from the page context menu.

Step 1: Set the size, location and type

You will be prompted to define the size, location and type of the arc by selecting two points on the page. As illustrated in
the following diagram, these two points define both the location and the size of the curve to use for the arc, based on an
imaginary bounding box with corners at the two pick locations.

The arc’s type may be either circular or elliptical depending on whether or not the imaginary bounding box is square or
not. To create a square bounding box, and therefore a circular arc, hold the shift key down on your keypad while
dragging the mouse between the first point and the second.

124 • How to Build an Application Developer's Guide (part 1)

Step 2: Set the start and end angles
After completing the first step, you will be prompted to indicate two points on the screen that will be used to define the
arc’s beginning and ending angles. Note that there is no user interface to allow you to type in the angles. The following
image illustrates the procedure:

Step 3: Define the appearance using the VTS Graphic Editor

The VTS Graphic Editor will open, providing you with options for defining the arc’s appearance. The menu of choices is
displayed in the following images. Note that you want to draw an arc with just the default coloring etc. you need not use
the graphic editor and can simply press the OK button to accept the defaults. For more information on using the Graphic
Editor, please refer to Using the VTS Graphic Editor.

Developer's Guide (part 1) How to Build an Application • 125

Drawing Chords

To draw a chord, select the chord button from the configuration toolbox or from the page context menu.

After selecting the Chord button, the arrow cursor will be replaced by a crosshair on the page. This is a prompt for you to
indicate where the chord is to be drawn. Do not spend time attempting to be precise in locating the chord, as it is much
easier to drop a chord of any size onto the screen, then adjust it later rather than attempt to locate it precisely when first
drawing it.

Referring to the illustration below, the process is to pick two points on screen, which will create a bounding rectangle,
within which the chord will be drawn. To create a circular chord segment, hold the shift key down while you pick the
two corner points. Otherwise, you can create an elliptical chord segment by picking the corners of any arbitrary
rectangle.

Step 1: Locate and size the chord

126 • How to Build an Application Developer's Guide (part 1)

As soon as the two corner points have been drawn, you will be prompted for a start and end angle for the chord 's end
points. Note that the chord will be drawn counter-clockwise from the start point you indicate, towards the end point.

Step 2: Set the chord’s start and end angles

Step 3: Define the appearance using the VTS Graphic Editor

As soon as the chord has been placed on the screen, the VTS Graphic Editor will be displayed as shown below. Simply
selecting the box labeled "OK" will result in a chord of default color, line style and line weight being created. Please
refer to Using the VTS Graphic Editor for instructions on using this dialog box.

Drawing an Ellipse

To draw an ellipse, select the ellipse button from the configuration toolbox or from the page context menu.

Step 1: Set the size, location and type

Developer's Guide (part 1) How to Build an Application • 127

You will be prompted to define the size and location of the arc by selecting two points on the page. As illustrated in the
following diagram, these two points define both the location and the size of the curve to use for the arc, based on an
imaginary bounding box with corners at the two pick locations.

The arc’s type may be either circular or elliptical depending on whether or not the imaginary bounding box is square or
not. To create a square bounding box, and therefore a circle, hold the shift key down on your keypad while dragging the
mouse between the first point and the second.

Step 2: Define the appearance using the VTS Graphic Editor

As soon as the ellipse has been placed on the screen, the dialog box shown below will be displayed. Simply selecting the
box labeled "OK" will result in an ellipse of default color, line style and line weight being created.
Please refer to Using the VTS Graphic Editor for instructions on using this dialog box.

Drawing a Pie Object

To draw a pie object, select the pie button from the configuration toolbox.

128 • How to Build an Application Developer's Guide (part 1)

When the Pie button is clicked, the arrow cursor will be replaced by a crosshair on the application page. This is a prompt
for you to indicate where the pie object is to be drawn. Do not spend time attempting to be precise in locating the object,
as it is much easier to drop a pie object of any size onto the screen and then adjust it rather than attempt to locate it
precisely when first drawing it.

Step 1: Set the size, location and type

Referring to the illustration below, the process is to pick two points on screen, which will create a bounding rectangle,
within which the pie object will be drawn. To create a circular pie section, hold the shift key down while you pick the
two corner points. Otherwise, you can create an elliptical pie section by picking the corners of any arbitrary rectangle.

Step2: Set the start and end angles of the pie

As soon as the two corner points have been drawn, you will be prompted for a start and end angle for the pie object's end
points. Note that the pie will be drawn counter-clockwise from the start point you indicate, towards the end point.

Step 3: Set the pie object’s style options

Developer's Guide (part 1) How to Build an Application • 129

As soon as the pie object has been placed on the screen, the dialog box shown below will be displayed. Simply selecting
the box labeled "OK" will result in a pie of default fill, line style and line weight being created.
Please refer to Using the VTS Graphic Editor for instructions on using this dialog box.

Adding Bitmap Images

To insert an image onto a page, select the Image button from the configuration toolbox:

VTS can display vector-based and bitmap images with the following extensions:
• *.APM
• *.BMP
• *.CUT
• *.EMF
• *.JPG
• *.PCX
• *.PNG
• *.TIF
• *.WMF

Note: Images placed on the pages of your application using the Image button are not associated with tags. In order to
place a visual representation of the value of a tag on a page, you must employ the Tag Browser's "Draw" button. See:
Drawing Tags.

Step 1: Set a location for the placeholder image.

You will be prompted to select a position on the page for the lower right corner of a placeholder image. Selecting the
image and its size will be done in a later step. The placeholder image will look like so:

Step 2: Select the bitmap image to insert

After completing step 1, the VTS Graphic Editor will open as shown in the following image:

130 • How to Build an Application Developer's Guide (part 1)

Complete instructions for using the dialog shown above can be found in the topic: VTS Graphic Editor: Options Unique
to Images
To choose an image, click the "Select Bitmap" button. The "Select Bitmap" dialog opens, similar to the example
displayed here:

Developer's Guide (part 1) How to Build an Application • 131

The "Select Image" dialog is composed of groups or categories to help you locate the images you need. To display
images belonging to a specific group, click on the associated button. The corresponding group of images will be
displayed in its own dialog, from which you may choose any that one that fits your design.

You may expand the range of choices by importing your own images. See: Import Bitmap Images.

Step 3: Choose a Color for the Status Display Area

Many images feature color indicator areas:

Color indicator areas are useful when combined with the Image Change tag drawing method (see "Image Change
Drawing Method") or when the bitmap itself is used as a tag drawing method. In both cases, color indicator will change
color with the tag to indicate equipment status.

132 • How to Build an Application Developer's Guide (part 1)

For the indicator to change color in response to an overlying image change drawing method, it must be Active Orange in
color (RGB: 255, 160, 0).
Only Active Orange responds to image change drawing methods.

Note: a change to the hue of the overall bitmap also affects the color indicator area, making it difficult to achieve (255,
160, 0) as the final color.

Drawing Lines

To draw a line, select the line button in the configuration toolbox.

When the Line button is clicked, the arrow cursor will be replaced by a crosshair on the application page. This is a
prompt for you to indicate where the start point of the line is to be drawn.

Step 1: Draw the line segment(s)

A line may include as many segments as you wish, but at a minimum it must have a start point and an end point to draw
one segment. Indicate the position of each vertex on the page by left-clicking.

Step 2: Stop drawing the line:

The line tool will continue prompting for points until you right-click. Thus, to draw a single line, the procedure is to left-
click at the start point of the line, move the cursor to the end point, left-click again, then right-click. To draw a multi-
segment line, left-click at the start point and at each vertex until you reach the position where you wish to end the line.
At that end point, right-click. No segment will be drawn to the location where you right-click.

Note: Drawing a line by doing a left-click followed immediately by a right-click will result in a line of zero length being
drawn on the application page. This will not be visible, but it may interfere with attempts to select nearby objects later.

Step 3: Set the line style options

As soon as the line has been placed on the screen, the VTS Graphic Editor will be displayed. Simply selecting the box
labeled "OK" will result in a line of default color, line style and line weight being created.
Please refer to Using the VTS Graphic Editor for instructions on using this dialog box.

Developer's Guide (part 1) How to Build an Application • 133

Drawing Pipes

To draw a pipe, select the pipe button from the configuration toolbox.

Step 1: Indicate the start point of the pipe.

When the Pipe button is clicked, the arrow cursor will be replaced by a crosshair on the application page. This is a
prompt for you to indicate where the start point of the pipe is to be drawn. A pipe object may include as many segments
as you wish, but at a minimum it must have a start point and an end point to draw one segment. Indicate the position of
each vertex on the screen by left-clicking.

Step 2: Stop drawing the pipe:

The pipe tool will continue prompting for points until you right-click. Thus, to draw a single pipe, the procedure is to
left-click at the start point of the pipe, move the cursor to the end point and left-click again. then immediately right-click.
To draw a multi-segment pipe, left-click at the start point and at each vertex until you have reached the position where
you wish to end the pipe, then right-click to stop the pipe command. No segment will be drawn to the location where you
right-click.

Note: Drawing a pipe by doing a left-click followed immediately by a right-click will result in a pipe of zero length
being drawn on the application page. This will not be visible, but it may interfere with attempts to select nearby objects
later.

Step 3: Set the pipe object’s style options

As soon as the pipe has been placed on the screen, the VTS Graphic Editor will be displayed as shown. Unless otherwise
defined, pipes will be grey in color and have a width of 7 units.
Please refer to Using the VTS Graphic Editor for instructions on using this dialog box.

Drawing a Polygon

To draw a polygon, select the polygon button from the configuration toolbox.

Step 1: Indicate the start point of the polygon.

When the Polygon button is clicked, the arrow cursor will be replaced by a crosshair on the application page. This is a
prompt for you to indicate where the start point of the polygon is to be drawn. A polygon object may include as many
vertices as you wish, but at a minimum it must have three in order to create a meaningful shape. Indicate the position of
each vertex on the screen by left-clicking.

134 • How to Build an Application Developer's Guide (part 1)

Note: VTS will allow you to create a polygon with only two vertices, but this is functionally equivalent to drawing a line.
Since the default outline for a polygon is "None", a two-vertex polygon will be invisible until you select a visible outline.

Step 2: Stop drawing the polygon:

The polygon tool will continue prompting for points until you right-click. No vertex will be drawn to the location where
you right-click, but a segment will be drawn to connect the first and last vertices.

Note: VTS will allow the segments of a polygon to cross. A sharp-edged hourglass is a perfectly valid polygon shape.

Step 3: Set the polygon object’s options

As soon as the polygon has been placed on the screen, the VTS Graphic Editor will be displayed. Simply selecting the
box labeled "OK" will result in a polygon of default fill color being created.
Please refer to Using the VTS Graphic Editor for instructions on using this dialog box.

Drawing a Rectangle

To draw a rectangle, select the rectangle button from the configuration toolbox.

Step 1: Place two corners of the rectangle on the page

When the Rectangle button is clicked, the arrow cursor will be replaced by a crosshair on the application page. This is a
prompt for you to indicate where the rectangle is to be drawn.
Referring to the illustration below, the process is to pick two points on screen, which will create a rectangle. To create a
square, hold the shift key down after indicating the first corner point. Otherwise, you can create a rectangle of arbitrary
dimensions by picking points freely on the application page.

Developer's Guide (part 1) How to Build an Application • 135

Step 2: Set the rectangle’s style options
As soon as the rectangle has been placed on the screen, the VTS Graphic Editor will be displayed. Simply selecting the
box labeled "OK" will result in a rectangle of default color, line style and fill being created.

Please refer to Using the VTS Graphic Editor for instructions on using this dialog box.

Drawing Text
(see also, Drawing Multi-Line Text)
To draw text on a page, select the text button from the configuration toolbox.

When the Text button is clicked, the arrow cursor will be replaced by the words "Sample Text" attached to an arrow
cursor, as shown in the figure below.

Step 1: Position the placeholder text on the page

136 • How to Build an Application Developer's Guide (part 1)

This is a prompt for you to indicate where the text is to be drawn. Do not spend time attempting to be precise in locating
the text, as it is much easier to drop the placeholder text onto the screen and then adjust it later rather than attempt to
locate it precisely when first drawing it.

Step 2: Set the text style options, including writing the desired text.
As soon as the sample text has been placed on the screen, the VTS Graphic Editor will be displayed. Selecting the box
labeled "OK" will result in the words "Sample Text" being created with the default font and color.
Please refer to VTS Graphic Editor: Options Unique to Text for instructions on using this dialog box.

Drawing Multi-Line Text

( See also: Drawing Text)
With Multi-Line Text, you can set line breaks where you would like them, but automatic line-wrapping will also occur if
a sentence is too long to fit within the object's bounding box.

Multi-Line Text is found in the Standard Library menu of the Drawing Tools library.

Developer's Guide (part 1) How to Build an Application • 137

Step 1
To draw Multi-Line Text, open the Libraries dialog, as shown in the preceding image. Expand the Standard Library by
clicking on the + sign, then right-click on Multi-Line Text to open its context menu. Click on Draw.
Step 2
A sample text image will appear, attached to the cursor. Click on the VTS page to set the initial location for the text.

Step 3
The VTS Graphic Editor will open for the Multi-Line Text Object, as shown in the following image.

138 • How to Build an Application Developer's Guide (part 1)

Click in the "Text To Display" area, then replace the words "Sample Text" with the words you want to display on your
page.
Step 4
Adjust the font, alignment, border and colors as desired, then click OK.
Step 5
The initial bounding box will remain the size of the 11 characters of "Sample Text". Click once to activate the boundary
grips, then re-size the bounding box to suit. Note that automatic line-wrapping will occur for every sentence that is
longer than the bounding box is wide.

Undo Tool

Provides a way for you to reverse any mistakes you've made by undoing your last action.
VTS keeps in memory an almost unlimited record of all the actions you've completed. It also handles undo actions page-
independently; therefore, if you've made changes to more than one page, the undo action will only undo the actions that
apply to the currently open page. The other pages will remain unaffected.
You can also apply a redo operation if you should change your mind about undoing an action. Instructions on the Redo
tool appear in the section that follows.

Developer's Guide (part 1) How to Build an Application • 139

Redo Tool

Because VTS keeps in memory an almost unlimited record of all the actions you've completed, it can also redo
actions in the event that you decide you didn't wish to undo an action.
It also handles redo actions page-independently; therefore, if you've made changes to more than one page, the redo
action will only redo the actions that apply to the currently open page. The other pages will remain unaffected.

Alignment and Positioning Tools

The alignment and positioning tools help you to create a clean and professional looking user interface.

Bringing Objects to Front

You can layer graphic objects to produce a multi-dimensional effect. The Bring To Front button that appears in the
configuration toolbox enables you to change the layering position of a selected object in relation to other objects by
bringing the object to the top of the stack.
To change an object's position, select the object and click the Bring To Front button. The object will appear on the top of
the stack.

In the example below, the blue square will be moved to the top layer using the Bring To Front button.

1. 2. 3. 4.

The blue square appears Select the blue square. Click the Bring To The blue square is moved to
in the bottom layer. Front button. the top layer.

The Bring To Front tool works with the Send To Back tool to assist you in layering objects efficiently. The Send To
Back tool is described in the next section.

Sending Objects to Back

In addition to the Bring To Front layering tool, VTS provides you with a Send To Back tool that you can use to send a
selected object to the bottom of the stack.
To change an object's position, select the object and click the Send To Back button. The object will appear on the bottom
of the stack.

In the example below, the red triangle will be moved to the bottom layer using the Send To Back button.

140 • How to Build an Application Developer's Guide (part 1)

1. 2. 3. 4.

The red triangle appears in Select the red triangle. Click the Send To The red triangle is moved to
the middle layer. Back button. the bottom layer.

Evenly Spacing Objects Horizontally

Use the Horizontal Spacing tool to organize selected objects in an even distribution. This operation works on 3 or more
selected objects. VTS treats the left-most and right-most objects as the anchors, and spaces the intermediate objects
evenly between them.
To space selected objects evenly across an application page, select the objects and click the Horizontal Spacing button.

In the example below, the yellow circle will change position so that it is evenly spaced between the blue square and the
red triangle.

1. 2. 3. 4.

The yellow circle appears Select the objects. Click the The yellow circle's position is
between the square and Horizontal Spacing adjusted. It now appears an
triangle. button. even distance from the square
and triangle.

You can also change the vertical spacing of selected objects using the Vertical Spacing tool. The Vertical Spacing tool is
described in the section that follows.

Evenly Spacing Objects Vertically

Use the Vertical Spacing tool to organize selected objects by giving them an even vertical distribution. This operation
works on 3 or more selected objects. VTS treats the top-most and bottom-most objects as the anchors, and spaces the
intermediate objects evenly between them.
To space selected objects evenly down an application page, select the objects and click the Vertical Spacing button.

In the example below, the yellow circle will change position so that it is evenly spaced between the blue square and the
red triangle.

Developer's Guide (part 1) How to Build an Application • 141

1. 2. 3. 4.

The yellow circle Select the objects. Click the Vertical The yellow circle's position is
appears between the Spacing button. adjusted. It now appears an even
square and triangle. distance from the square and
triangle.

Aligning Objects to their Left

Use the Align Left tool to move 2 or more selected objects so that they align to the left of the left-most object. VTS treats
the left-most object as the anchor and moves the other objects accordingly.
To align selected objects to the left, select the objects and click the Align Left button.

In the example below, the blue square and the red triangle will change position so as to align with the left side of the
yellow circle. The shapes are framed within a box to help demonstrate their position.

1. 2. 3. 4.

The yellow circle Select the objects. Click the Align Left The blue square and red
appears furthest to the button. triangle adjust themselves to
left of the page. align with the left side of the
yellow circle.

Aligning Objects to their Right

Use the Align Right tool to move 2 or more selected objects so that they align to the right side of right-most object. VTS
treats the right-most object as the anchor and moves the other objects accordingly.
To align selected objects along their right sides, select the objects and click the Align Right button.

142 • How to Build an Application Developer's Guide (part 1)

In the example below, the blue square and the red triangle will change position so as to align with the right side of the
yellow circle. The shapes are framed within a box to help demonstrate their position.

1. 2. 3. 4.

The yellow circle Select the objects. Click the Align The blue square and red
appears closest to the Right button. triangle adjust themselves to
right of the page. align with the right side of the
yellow circle.

Aligning Objects to their Bottom

Use the Align Bottom tool to move 2 or more selected objects so that they align to the bottom of bottom-most object.
VTS treats the bottom-most object as the anchor and moves the other objects accordingly.
To align selected objects along their bottom sides, select the objects and click the Align Bottom button.

In the example below, the blue square and the red triangle will change position so as to align with the bottom of the
yellow circle. The shapes are framed within a box to help demonstrate their position.

1. 2. 3. 4.

The yellow circle Select the objects. Click the Align The blue square and red
appears closest to the Bottom button. triangle adjust themselves to
bottom of the page. align with the bottom of the
yellow circle.

Aligning Objects on their Horizontal Center

Use the Align Horizontal Center tool you to move 2 or more selected objects so that they horizontally align through a
common center of the center-most object. VTS uses the limits of the initial vertical range of the selected objects to
calculate the new center.
To align selected objects along their horizontal centers, select the objects and click the Align Horizontal Center button.

Developer's Guide (part 1) How to Build an Application • 143

In the example below, the blue square and the red triangle will change position so as to align with the horizontal center
of the yellow circle. The shapes are framed within a box to help demonstrate their position.

1. 2. 3. 4.

The yellow circle is the Select the objects. Click the Align The blue square and red
most central object. Horizontal Center triangle adjust themselves to
button. align with the horizontal
center of the yellow circle.

Aligning Objects to their Top

Use the Align Top tool to move 2 or more selected objects so that they align to the top of top-most object. VTS treats the
top-most object as the anchor and moves the other objects accordingly.
To align selected objects along their top sides, select the objects and click the Align Top button.

In the example below, the blue square and the red triangle will change position so as to align with the top of the yellow
circle. The shapes are framed within a box to help demonstrate their position.

1. 2. 3. 4.

The yellow circle appears Select the objects. Click the Align Top The blue square and red
closest to the top of the button. triangle adjust themselves to
page. align with the top of the
yellow circle.

Aligning Objects on their Vertical Center

Use the Align Vertical Center tool to move 2 or more selected objects so that they align through a common vertical
center. VTS left and right limits of the initial selection set to calculate the new center.
To align selected objects along their vertical centers, select the objects and click the Align Vertical Center button.

144 • How to Build an Application Developer's Guide (part 1)

In the example below, the blue square and the red triangle will change position so as to align with the vertical center of
the yellow circle. The shapes are framed within a box to help demonstrate their position.

1. 2. 3. 4.

The yellow circle is the Select the objects. Click the Align The blue square and red
most central object. Vertical Center triangle adjust themselves to
button. align with the vertical center of
the yellow circle.

Group Tool

Combines a set of selected objects together into a named User Draw Method (DM). The original objects will be
replaced on the screen by an instance of the new object.
DMs make it easy to move, resize and copy multiple objects as one. The component parts of a DM can still be edited
individually, with the effect that every instance of the object will be updated to be displayed using the new configuration.
DMs that include tags use parameters to allow you to select a different set of tags for each instance of the object.
For example, the following image shows a DM that is made up of several components:
• an analog control, drawn as a slider
• a graphic image showing a scale
• an analog input displaying the feedback from the slider

As indicated by the selection highlight, all three objects are now treated as a single drawing object that can be moved and
re-sized like any other object.
For more information, see the topic: User Draw Methods. Objects that have been grouped can also be un-grouped. See:
Un-Grouping a Drawing Method.

Snap Grid

Developer's Guide (part 1) How to Build an Application • 145

Toggles the alignment grid and its associated snap spacing on and off. When you are using the snap grid, coordinates of
objects that are drawn, moved, or resized will automatically align to the nearest point on the grid.
When the button is latched in, the snap grid is on. (Note that visibility can be controlled independently of the snap grid
being on.) By default when you create a new application and begin to configure it, the grid is off.
Clicking the Snap Grid button when it is not latched in opens the Grid Options dialog where you can set the appearance
and behavior of the snap grid before turning it on. When you click the OK button, the snap grid will be turned on, and
the button will be highlighted in the Configuration Toolbox to indicate that it is latched on. Clicking the button while the
snap grid is on will turn it off, without opening the options dialog.
The Grid Options dialog with its default settings is as shown:

The Grid Options dialog allows you to:

• Set the horizontal and vertical spacing of the points on the grid (X spacing and Y spacing). Note that the lowest
possible value that will not result in a “Grid too dense to be displayed” message is 4.
• Set the grid to be visible or invisible;
• Set the grid color; and
• Specify the frequency of the dots of the visible grid relative to the snap spacing points.

Note: You can also customize the behavior of the Snap Grid tool application properties. For further information, see:
Application Properties for the Snap Grid.

Working with Objects

VTS provides you with a snap grid and several alignment, spacing, and layering tools (see "The Configuration Toolbox")
to help you manipulate the objects you draw on your pages. In addition to these tools, there are supplementary shortcut
keys that enable you to shift and place objects when you are building your operator interfaces. The table below identifies
these shortcut keys, while the sections that follow provide further instructions on working with them effectively.

Keyboard
Shortcut Command Result
Ctrl + A Select All Select all objects on the active page/window.
Ctrl + C Copy Copy the selected object(s) to the clipboard..
Ctrl + V Paste Paste the selected object(s) to the active page/window.
Ctrl + X Cut Cut the selected object(s) from the active page/window.

146 • How to Build an Application Developer's Guide (part 1)

 Ctrl + Z Undo Undo the last action.
Ctrl + Y Redo Redo the last action.
Ctrl + Print Screen Creates a screen capture of the currently displayed window that
Screen Capture can be pasted into a Microsoft Word document or into most
graphics software.
Note: This shortcut key combination is particularly useful when
you wish to print a trend window (see: Using the Historical Data
Viewer Page).

Selecting Multiple Objects on a Page

The sections that follow provide information on selecting multiple objects on a page using a variety of different methods,
such as the Ctrl key and the mouse, the Shift key and the mouse, or the Ctrl + A key combination.

Select Multiple Objects Using the Control (Ctrl) Key

You can select multiple objects on an application page using the Control (Ctrl) key and your mouse.
1. Press and hold the Ctrl key.
2. Click objects on the application page. Handles will appear around selected objects.
3. Release the Ctrl key.

You are now free to reposition the selected objects as a group.

Select Multiple Objects Using the Shift Key

You can select multiple objects on an application page using the Shift key and your mouse.
1. Press and hold the Shift key. A selection rectangle is attached to the mouse pointer.
2. Move the mouse until all the objects you wish to select appear within the rectangle.
3. Release the Shift key and the mouse button. Handles will appear around the selected objects.

Select All Objects on a Page

To select all the objects appearing on a page, press the Control (Ctrl) key and the "A" key.

Note: You can modify the properties of all selected objects by right-clicking one object and using the VTS Graphic
Editor. All the selected objects and their properties will be listed in the editor’s menu on the left side of the dialog box.
Further information on modifying the properties of a group of selected objects can be found in "Modify the Properties of
all Objects in a Selected Group".

Note: Once you've selected all objects on a page, you can copy and paste them to a new location using the other
keyboard shortcuts identified in "Working with Objects". Another option is to copy a page and its contents. For
instructions, please refer to "Duplicating a Page with Copy and Paste".

Copy and Paste Objects

As mentioned in "Working with Objects", you can copy and paste objects using the Copy Tool (see "Copy Tool"), or you
can copy objects using a keyboard shortcut.
First, select the objects you wish to copy, then press the Control (Ctrl) and "C" keys on your keyboard. Next, press the
Control (Ctrl) and "V" keys on your keyboard to paste the objects.

Developer's Guide (part 1) How to Build an Application • 147

Nudge Objects
You can nudge one selected object or a group of selected objects up, down, left or right a pixel at a time using the arrow
keys and your mouse.
1. Select the object (or objects) you wish to nudge.
3. Click and hold the mouse button.
4. Use the arrow keys to nudge the selected object (or objects) in the direction you choose.

Shape Polygon

Provides a way to edit selected pipes, lines, arcs and other graphic objects by moving their vertices.

The image displays the handles that appear when you select an object using the Shape Polygon tool. Click and drag a
handle to reposition the matching vertex.
This tool is of particular interest when editing a pipe object since it will not otherwise distort the pipe as changes to the
handles would.

Resizing Objects
VTS provides you with the ability to resize objects freely or proportionally. In both cases, you use the object's handles to
resize it. The difference is that, in order to maintain the height and width proportion, you will hold down the shift key
while resizing the object.

Resize an Object Freely

1. Select the object you wish to resize. The object's handles appear.

2. Click and hold the mouse button on one of the object's handles. In the example below, an object will be resized
horizontally to the right.

3. Resize the object by continuing to hold down the mouse button and moving the mouse in the direction you wish
to resize the object. An outline is displayed to help guide you.

4. Release the mouse button. The object adjusts to the size you've indicated.

148 • How to Build an Application Developer's Guide (part 1)

Resize an Object Proportionally
You can use resize objects proportionally, so that they grow or shrink in size with a proportional horizontal and vertical
ratio. In this example, circle is resized proportionally.
1. Select the object you wish to resize proportionally. The object's handles appear.

2. Click and hold the mouse button on one of the object's handles. In the example below, the circle will be resized
proportionally to be smaller.

3. Resize the object by continuing to hold in the mouse button and moving the mouse in the direction you wish to
resize the object. An outline is displayed to help guide you. The outline indicates that the object is NOT being
resized proportionally.

4. Press and hold the Shift key on your keyboard while continuing to resize the object. Do not release the mouse
button.
5. Move the mouse pointer out and in from the direction of the handle you've chosen while continuing to hold your
mouse button and the Shift key on your keyboard. The object's outline will indicate proportional resizing.
6. Resize the object according to your needs.
7. Release the mouse button. The object adjusts proportionally to the size you've indicated.

Modify the Properties of all Objects in a Selected Group

The VTS Graphic Editor provides a new way to modify the properties of all the objects in a selected group. Instead of
stepping through the selected objects one at a time, the properties of all the selected objects are displayed in the Graphic
Editor as shown in the following image.
This example shows the result of selecting to edit a rectangle, an ellipse and a Meter1 drawing object attached to a tag.
Each object and its properties are listed in the menu. Select any properties of any objects you want to edit. In addition,
note that in the menu, Rectangle is currently selected rather than one of its properties. In the main part of the editor
window, you can see that both Fill and Left Scaling – the two properties that have non-default values set – are displayed
for you to edit.

Developer's Guide (part 1) How to Build an Application • 149

Working with Colors
VTS supports true-color selection for most objects. A very few are limited to a 256-color palette. The color selection
dialog will vary accordingly, based on what type of object you are changing the color of.
Select Color Dialog: The Select Color Dialog is used by most objects that have an adjustable color. You may use
Hue Saturation and Luminosity values, RGB values, any existing color on the screen, or you
can use the dynamic color selection tool.
The Select Color dialog is described in detail in Select Color Dialog.
Select Pen Dialog: The Select Pen Dialog is used by a small number of objects. The Com Line drawing method,
used to represent a port tag is one such example.
The Select Pen dialog is described in detail in Select Pen Dialog.
Select Color Range: The Select Color Range dialog is used only by the Pipe graphic object. It allows you to select
color range that simulates shading along the curved surface of a pipe. See: Select Color Range
Dialog.

Note: When customizing VTS using the Settings file, properties that change the color of objects or other features require
numeric index values rather than the selection of colors from palettes. A color-coded list of the 255 possible values can
be found in the reference topic, VTS Color Palette.

Select Color Dialog

The Select Color dialog is available from many different VTS dialogs, enabling you to choose colors for page
backgrounds, graphic object outlines and fills, text foreground and background, bitmap annunciation areas, and tag
drawing methods.

Note: The option, "Transparent", will not be available in all instances. It is displayed only when "transparent" may be an
acceptable color choice.

150 • How to Build an Application Developer's Guide (part 1)

Select Color Dialog Elements
Recently Used Colors A history of the last few colors you have used, made available for easy re-use by clicking on
any of the swatches.
Basic Colors Seventy color samples covering a broad range of hues. Provides a set of color choices for
those who would rather not spend time setting HSL or RGB values.
The second color from the left, in the top line of the Basic Colors is Active Orange.
The black at the lower left corner has an RGB value of 10, 10, 10, providing you with a color
that is visibly black, but functionally different from Transparent Black (0, 0, 0).
Transparent Not available in all instances. If transparent is an option (such as the Changed Color of a
Color Fill) then this checkbox will be available.
Pick from screen Click on any object in any VTS window to select that color.
New/Old Shows the current color of the object below the color you will apply when the OK box is
clicked. RGB values are provided.
Hue/Sat/Lum Hue, Saturation and Luminosity. Use these boxes if you know the numeric value of the
desired color, as specified using this color system.

Note: If you change the luminosity, and then select another hue, the luminosity will remain unchanged, unless the
luminosity had been set to zero (black) or 255 (white). If the luminosity is currently zero or 255, the act of selecting a
new hue automatically resets the luminosity to 128.

Red/Green/Blue Use these boxes if you know the numeric value of the desired color, as specified using this
color system.
Dynamic selector Click within the rectangle to select a Hue and Saturation value. Use the vertical slider to the
right to adjust luminosity.

Developer's Guide (part 1) How to Build an Application • 151

Fill Patterns
The Select Brush dialog provides a spin box that you can use to select a number corresponding to a fill pattern that will
be applied to your completed geometric object. There are 25 distinct fill patterns from which you may choose. These are
identified in the reference section of this guide, VTS Fill Patterns.
The Set Foreground Color and Set Background Color radio buttons at the top of the Select Brush palette enable you to
set the foreground color for an object that will have a patterned fill, and the background color for an object that will have
a patterned fill.

Select Pen Dialog

The Select Pen dialog is used when drawing a Comm Line for a port tag. An example of the Select Pen dialog is
displayed here:

Color
Displays the currently selected color and provides a button for accessing the Select Color dialog.

Width
Use the Width checkbox to select a number from 1 to 10, setting the width of the outline in pixels.

Style
Select a number corresponding to a line style for your geometric object. A "1" corresponds to a solid line (no pattern).
Line styles and their corresponding index numbers are described in Line Styles.

Sample
The Sample area displays a preview of the currently selected color, outline width, and line style.

Line Styles
If using the advanced option when setting the outline for a line, rectangle or other geometric shape, you will see a style
option. This can be used to select a line style that will be applied to your completed geometric object. There are 5 distinct
line styles from which you may choose, as shown in the reference chapter: VTS Line Types.

Select Color Range Dialog

The Select Color Range dialog is related to the Pipe tool and to the Gradient Color Change tag drawing method (see:
Gradient Color Change Drawing Method). Use this to select a given color range to be applied to a selected object. An
example of the Select Color Range dialog is:

152 • How to Build an Application Developer's Guide (part 1)

The currently selected color range is highlighted with a rectangle.

Select Color Range Dialog Elements

Color Ranges There are 28 color ranges available in the Select Color Range dialog. The currently selected
color range is highlighted with a rectangle. To select a color range, simply click the one you
desire.

Color Options - Adjust Image Hue

The graphic editor will often provide the Color Options control, shown in the following image. This allows you to adjust
the display color of an object using a variety of tools.

The first is the Hue slider. This allows you to offset the color scale such that the original color of the object will
displayed as a color further along the scale:
The following three images illustrate the effect of the hue slider where the first in the series is the unmodified bitmap,
Equip20.bmp:

Developer's Guide (part 1) How to Build an Application • 153

Note: Areas of active orange are also affected by changes in the hue

Objects that are grey will not be affected by the hue slider unless you first use the Colorize Hue setting to give them a
color, and also adjust the Colorize Intensity slider to apply that color.
The other controls work as follows:

Saturation
Saturation is a measure of the purity of a color. An image with a saturation of 0 will be grey. If the saturation is increased
above 1, the colors in the image will appear more intense.

Brightness
Brightness is a measure of the strength of a color. An image with a brightness of 0 will be black.

Transparency
The slider for transparency is actually controlling the opacity of the object. The lower the setting, the less opaque and
therefore the more transparent the image will be.

Contrast
Contrast is a measure of the difference between colors used in the image. In a low contrast image, the colors will blend
together. In a high contrast image, the colors will stand out.

Colorize Hue
Grey-scale (and other) images can be colored by introducing a hue. Varying shades of grey will be tinged towards the
introduced hue in similarly varying amounts.

Colorize Intensity
Colorize Intensity defines how much color is introduced by the Colorize Hue. A setting of 0 means that no color will be
introduced.

Special Colors
VTS's color palette includes two special colors:
• Active Orange (241)
• Transparent Black (0)

154 • How to Build an Application Developer's Guide (part 1)

Both of these colors play unique roles in the development of your VTS applications. The sections that follow provide
details.

Active Orange
One special shade of orange has been designed to react to the Image Change drawing method for tags.
The RGB values that combine to create this specialized orange shade are R=255, G=160, and B=0. This shade of orange
has been specially configured to be combined with the Image Change tag drawing method (available to digital input,
digital output, alarm, function and Modem tags) to display in color the state of the related tag. When the Image Change
drawing method is employed without the use of a bitmap for one or more states, the resulting color indicator will react
when placed over any image or portion of an image drawn using the active orange color.
The following image illustrates this action:

In this example, four simple squares have been drawn (using the rectangle tool), each in a different shade of orange
chosen from the VTS palette. The square on the lower left has been drawn using the active orange shade. The Image
Change drawing method was then used to draw a Digital Input tag. The Image Change object was positioned in such a
way that it intersects all of the orange squares.
As shown, only the square drawn using active orange reacts with the Image Change object to change as the value of the
tag changes. (In this example: red.)
This feature can be employed in a variety of different ways. For example, you might wish to use an area map, plant map,
or other background image that has been drawn using patches of the active orange color in specific areas. Having
selected the image as the background for a page in your VTS application, you may then overlay its active orange sections
using Image Change objects. The result is that these areas will change in color according to the value of the tags related
to the Image Change objects.
Another use is to create your own equipment bitmaps that have areas highlighted using the active orange color. You can
then add these equipment bitmaps to your VTS application directory, place them on your application's pages, and layer
them with Image Change objects. The result is that the delineated portions of the equipment bitmaps will change color
when the related tags change color. An example follows:

These images demonstrate the reaction of a bitmap that includes the active orange when combined with the Image
Change drawing method for a Digital Input tag.
1. A valve bitmap whose base has been drawn using the active orange color from the VTS palette.
2. An Image Change object (red) has been placed over the active orange shaded area of the valve bitmap.
3. and 4. The area of the bitmap, drawn using the active orange shade, now changes color according to the
value of the tag.

Developer's Guide (part 1) How to Build an Application • 155

Transparent Black (Color Value 0)
Pure black has been designated to become invisible on your graphics pages.
The RGB colors that combine to create transparent black are R=0, G=0, B=0. Within the VTS scripting language,
transparent black has been configured to be invisible on application pages. What this means to you is that any parts of a
graphic object that are drawn using this color will be transparent when placed on a page.
To see an example of this at work, try opening any of the equipment graphics provided by VTS using a graphic software
program (such as Paint). You will notice that all equipment objects actually have black backgrounds, however, when
these images are placed on a VTS application page, the backgrounds appear to be transparent. An example follows:

1. 2.
To create your own custom graphics that include transparent areas, use the transparent black color wherever you want
background objects on the page to show through.

Working with Parameters

A parameter is a named object whose value can be supplied by a different source each time it is used. Its purpose is to
allow you to create re-usable components that can be adapted to a variety of situations.
For example, you might decide to create your own drawing method of equipment not found in the VTS graphic library –
perhaps a windmill.
If you were to select one or more specific tags to use in that drawing method, then each time you added it to a page, you
would always be monitoring and controlling the same windmill at the same I/O addresses.
However, if you create your windmill drawing method with parameters, then each time you add it to an application page,
you can select a different set of tags and hence a different set of I/O addresses to monitor.

156 • How to Build an Application Developer's Guide (part 1)

You can also create application pages with built-in page parameters. For example, each of the windmills will need its
own control and monitoring page. Rather than build a separate page for each, you can build just one page, and define a
parameter for every I/O tag that is to be displayed within the page. You could then add that same page to the menu three
times, (or create three hotboxes linking to the page), and select the tag set for a different windmill for each instance. To
an operator, it will look as though there are three distinct pages, but as a developer, you only needed to create a single
page.

Note: Never define parameters in an application’s default page. The default page opens independently of the menu and
the hotboxes, therefore there is no way to pre-define the tags to be used for its parameters.

Parameters can provide even greater efficiencies when used with custom drawing methods for parent-child tag structures.
These put all of the tags for equipment such as a pump controller, an engine or even a pumping station together in a
logical structure. Custom tag drawing methods can represent complete pieces of equipment with multiple I/O values
displayed and controls available.
By using parameters to link hierarchical tag structures to all of the elements of a custom drawing method, you can easily
add complete new units or stations without needing to configure and draw every separate tag that makes up that unit.

Quick Links: Common tasks for parameters

• To learn how to use parameters in user-defined drawing methods, see:
User Draw Methods Properties Parameters Tab.
• To see an example of a user draw methods with parameters, see:
Build a Custom Meter.
• To learn how to use parameters in pages, see:
Page Properties Parameters Tab.
• To see an example of a page with parameters, see:
Drawing One Page on Another.
• To learn how to link to parameterized pages from the menu, see:
Edit the Parameter Values of a Page.
• To learn how to use hotboxes with parameterized pages, see:
Parameterized Page Hotboxes.
• To control graphic object properties with page parameters, see:
Control by Parameter.

Pages - Adding and Editing

Pages are the screens that make up a VTS or VTScada application. VTS gives you extensive control over the size,
location, appearance and behavior of your application pages. See: Application Properties for Pages.
Notes for adjusting the display to monitors of varying sizes can be found in the Customization chapter: Scale the
Display.
There is no limit to the number of pages that can be added to an application, therefore you should add as many as are
required to create the best possible user interface. To help you get started, you are given one application page, (named
"Overview" by default,) as part of every new VTS application.

Developer's Guide (part 1) How to Build an Application • 157

Application pages can be displayed either full-screen, as a standard Windows page, or as a pop-up window. You can
even draw one application page on another, in effect displaying a page within a page. This last feature might be used to
display a common control screen as a part of several other application pages.

Pages can be given replaceable parameters that can then be used as a data source for the objects within the page. Each
added instance of the page can be given its own set of tags for those parameters. This allows you to create a page that can
be reused for a series of similar monitoring or control stations.

Note: If a page has parameters, and if tags have not been selected for those parameters, then any action that displays the
page will always result in a dialog box prompting for values.

There is no requirement that a tag or value be provided for every parameters, but any drawing objects that depend on
unspecified parameters, will not be shown.

Quick Links: Common Tasks for Pages

• To add a page, see: Adding a page with New.
• To import a page file, see: Import an Existing Page File.
• To create a series of similar pages, see: Duplicating a Page with Copy and Paste.
• To delete a page, see: Working with Application Pages (deleting a page).
• To edit a page, see: Working with Application Pages (editing a page).
• To change a page name and its appearance including the background and the window features, see: Page Properties.
• To make a page current, see: Make a Page Current.
• To display one page within another, see: Drawing One Page on Another.

158 • How to Build an Application Developer's Guide (part 1)

Access the Page Configuration Dialogs
The Libraries dialog, accessed via the Libraries button in the Configuration Toolbox, provides the tools you need to add
and work with application pages.

Notes:
• You can edit, copy and delete application pages (those that you create) but not system pages (those such as the
Historical Data Viewer that are created by VTS).
• Hovering over the Pages node of the menu will cause a tool-tip to appear that provides a count of the pages in the
application.
• Hovering over a page node in the menu will cause a tool-tip to appear that tells you the name of the source file
where that page is stored. Since pages can have the same name, there will be times that the only way to tell one page
from another is to compare the names of the source files.
• Right-clicking on any node in the menu will produce a context menu with tools appropriate to that node.

Viewing a List of Pages

You can view a list of application pages by opening the Configure dialog and expanding the Pages node. (In a new
application, this will be limited to Call-Out List and Overview – the two application pages that VTS creates for you.)

Note that you can also see a list of all the pages, including the system pages, with the Menu Editor (see: Editing the
Menu).

Make a Page Current

To open an application page and make it current, you can use any of the following techniques:
• Right-click on the page name from the Configure dialog and select Edit from the context menu.
• Double-click on the page name from the Configure dialog.

Developer's Guide (part 1) How to Build an Application • 159

• Use a hotbox in a page, the page menu, or the navigation tools in the task bar.

The Pages Context menu

Right-clicking on the Pages node opens the Pages context menu. This is your primary tool for adding and working with
application pages.

Each function found in the menu is described in the following sections:

Draw One Page within Another

The draw menu option is used to place one application page within another as a drawn object. In effect, it allows a page
to contain a window to another page. This can be useful if you have a page containing system control or monitoring tools
that should be available to operators while they are viewing other pages. Note that any background image will not carry
through to be displayed when one page is drawn within another.

To draw one page within another, start by opening the target page. That is, the page that will contain the smaller one.
Open the Libraries dialog and right-click on any page listed there.
Select Draw from the menu that opens. If you choose Draw from the "Pages" node at the top of the list of pages, a dialog
will open to allow you to select which page you want to draw.

After selecting a page to draw, indicate where, on the existing page, it is to be drawn. Only the portion of the drawing
area that is in use in the selected page will be drawn – no empty space will be included around the objects of the drawn
page.
Once drawn, the page is contained within a border that can be resized or moved like any other object.
Right-clicking on the drawn page will open a context menu. From here, if you select the Edit menu, you will open that
page inside a new window. Any changes you make will be reflected in all drawn instances of that page.

Add a Page with New

Use the New button to add a new application page.

160 • How to Build an Application Developer's Guide (part 1)

You will be prompted for a name to give this new page. Upon supplying a name and clicking OK, the new page will be
created.

You will be prompted for whether or not to add the new page to the menu. Select Yes or No as appropriate. If you
choose not to add the page now, you can always do so later using the Menu Editor.

The page will be added, but not immediately opened for editing. In general, the next steps will be to configure the page's
display properties (see: Page Properties), then open the page for editing.

Import an Existing Page File

The import button allows you to select any page's source file (*.SRC) and import it into your application.

VTS will attempt to compile the page before it is imported; if the source file does not contain valid script code for a VTS
application page, a Compiler Error message will be displayed.
The import command will always make a copy of the selected page source file. If the original is located in the current
application`s Pages directory, the import copy will be given a unique name by having a number appended to the original
file name. Otherwise, a copy will be made of the source file, having the same filename as the original.

Developer's Guide (part 1) How to Build an Application • 161

You can also import the source file from a user draw method (DM) to use as a page. A copy of the file will be made, then
modified to have the structure of a page source file rather than a DM source file.

Duplicate a Page with Copy and Paste

If you have recently used either the Cut or Copy functions on a page's menu entry, you can use the Paste function to
paste a copy of the page into your application as a new page.
Note the highlighted lines in the following images. The application page must be selected in order to copy it using the
context menu. The Pages menu header must be selected in order to paste.

After clicking on the Paste command, you will be prompted for the name to be given to the new page.

The new page will be an exact duplicate of the original, but no connection is maintained between the two. The two pages
will be stored in separate files.

Copying a Page from Source Code

Pages are stored in your application in a subdirectory named Pages. You can use the Windows clipboard to copy a source
file and then paste it directly into your application. This technique may be useful when duplicating pages or when
copying a page from one application to another. To do so, follow these steps:
1. Using Windows Explorer, locate the *.SRC file containing the page file, either in the current application's Pages
directory, or in another application's Pages directory.
2. Right-click on the file name to open its context menu
3. Select Copy
4. Return to your application and open the Configure dialog by clicking on the Libraries button in the
configuration toolbox.
5. Right-click on the Pages node to open the context menu
6. Select Paste.
7. You will be prompted for a name to give the new page. Supply any name that seems appropriate.
8. Click on OK to close the New Page Name dialog.

Adjusting Page Defaults

When you right-click on the Pages entry of the Configure menu, you can choose to adjust the default page properties.

162 • How to Build an Application Developer's Guide (part 1)

The properties option opens a dialog that controls the page defaults that can be set outside of the Application Properties
dialog. For more information about properties that control how pages appear, see: Application Properties for the Display
Manager.

Note: A restart of the application is not normally required after adjusting the page defaults, but in rare circumstances
(possibly on a workstation that is out of sync. with its configuration server) you may see the message, “Some of your
changes will not take effect until you restart the application”. If so, stop the application and restart it.

Use Last Displayed Page If this box is checked then, the last page shown when the application is shut down will be the
first page displayed when the application restarts.
Page If Use Last Displayed Page is not checked, then the page specified here will be the first page to be displayed
whenever the application starts. A select box allows you to pick the start page from a menu of all the pages in the
application. (Dialog box shown in the following image.)

Parameter String The field displays the parameters (if any) that will be passed to the first page, if that page
includes parameters. To change the parameters click the "Change Parameters" button to open the parameter editor.

Developer's Guide (part 1) How to Build an Application • 163

Working with Application Pages
Application pages are those that you can create, edit and delete. (As opposed to "System Pages", which are those created
by VTS.)

In the Configure dialog, clicking on the Pages node will cause all of the pages with the application to be shown. Right-
clicking on any application page will cause a context menu to be displayed, giving you access to all tools you need to
work with that page:

Draw
There are many situations where you might want to be able to see the information or controls that exist in one page while
looking at another. You can easily achieve this by drawing one page within another. An example showing how to use
this feature is provided in the topic, Use a Page as a Drawing Object.

Edit
Makes the selected page current so that you can draw and edit tags and other graphic objects on it.

Cut
Copies the current page to the clipboard and removes it from the application. To paste the page back into the application,
right click on the Pages node – you will find the paste function there. (See: Duplicate a Page with Copy and Paste.)

Copy
Copies the current page to the clipboard. As with the Cut function, you will find the paste function in the context menu
of the Pages node.

164 • How to Build an Application Developer's Guide (part 1)

Rename
Changes the name of the application page. Optionally, you can also change the title of the page in the page menu. You
would normally want the page menu to match the name of the page.

Delete
Removes the page from the application. If the page has been drawn on other pages, those instances will also be removed.

Properties
Opens the properties dialog. Please refer to the next topic, Properties of Application Pages for a discussion of what you
can accomplish with this dialog.

Properties of Application Pages

The page properties dialog is divided into three tabs: Properties, Parameters, and Advanced. The Properties tab will
always be the first to be displayed whenever the dialog is opened since it contains the most commonly used controls.
• The Properties tag is used to edit common page properties such as the background color.
• The Parameters tab is used to define the parameters for the current page. Note that defining a parameter can involve
changing its name and type, but does not involve setting a data source.
• The Advanced tab is used to control page size and position in the case there the application is not running in full
screen mode, or when the page is defined to be displayed in a window, similar to a dialog box.

Changes to these values are stored in the associated page's source code file (\Pages\PageName.SRC).

Page Properties

This is the tab you will use most often when working with pages. Properties that you can set include the following:

Page Name:

Developer's Guide (part 1) How to Build an Application • 165

Every object in VTS must have a name. This field allows you to change the name of the page. If you change the page
name you will be prompted for whether you also want to change the title used for this page in the page menu. In most
circumstances you should click Yes in response to that question.

Note: The page source file name will be taken from the initial page name, with all spaces and punctuation removed.
Changing the page name does not change the source file's name.

Page Title Expression: [optional]

The text that will be displayed in the title bar at the top of a windowed page. If not specified, the title is taken from the
page's name.
Advanced users can build an expression for this field that will concatenate static text with a name or value taken from
one of the page's parameters. This allows instances of parameterized pages to each have a unique title based on their
parameter values.
For example: given a page with a numeric parameter named “StationNumber”, the expression to display this number as
part of the title is
concat("Station # ", Variable("StationNumber"))

Page Tool Tip

This field is used if you have created a page change button in the task bar for this page. Holding the cursor over this page
change button will cause the page tool tip to appear.

Background
If Use Color is set, you can then click on the Set Color button to select a background color for the page. In general, it is
best to use a background color that is light and of a neutral shade. Since text and lines are black by default, they will not
show up well against a dark background. Garish color choices for the background will likely cause eye-strain among
operators of the application.
If Use Bitmap is set, you can use the Set Bitmap button to select a bitmap image to use as the background. This image is
selected from the VTS Select Bitmap dialog. You should first copy the image you want to use into the
Bitmaps\Backgrounds directory of your application before using this tool. Allowable file formats include *.APM,
*.BMP, *.CUT, *.EMF, *.JPG, *.PCX, *.PNG, *.TIF and *.WMF.

Page Window Flag

There are three possible modes in which a page can be displayed:
• No Restrictions May be opened either within the overall application window or as a separate window. You
can control how the page is opened by which mouse button is used to when clicking on the page's entry in the menu.
A left-click opens the page within the overall application while a right-click opens the page as a separate window.
• Always Display in Window The page always opens in a separate window.
• Never Display in Window The page will only open within the overall application – never as a separate window.

Bitmap Margin
Enabled only if Use Bitmap has been checked and a bitmap image chosen. This set of controls allows you to adjust the
size and position of the bitmap on the background by adjusting the margins (measured in pixels) around the bitmap. The
larger the margins, the smaller the bitmap image. Position is adjusted by making one of each pair of margins larger than
the other. For example, increasing the left margin while decreasing the right margin will move the image to the right.
An optional checkbox allows you to enable margins in windowed pages as well as in normal pages.

Scale Display Content – Not this page

166 • How to Build an Application Developer's Guide (part 1)

If Scale Display Content has been enabled for the application as a whole, you can use this checkbox to disable the
scaling feature for the current page.

Page Security Bit

Used with application-level security to link a security privilege to this page. See Protecting Objects Using Application
Privileges for more information.

New Thumbnail
VTS will attempt to create a thumbnail image of the page, to use as a visual reference when you are working with the
page later. If the page is large or complex, the thumbnail may not be very clear. For this reason, you can use the New
Thumbnail button to select any image from your Bitmaps directory to use instead. Like bitmap backgrounds, it is
recommended that you copy a graphic image to the \bitmaps\backgrounds directory of your application before using this
button.

Remove Thumbnail.
If you selected your own thumbnail image, you can use this button to remove it and allow VTS to again attempt to
provide its own image of the screen as a thumbnail.

Page Properties Parameters Tab

Use the parameters tab to work with the parameters attached to the current page. All the parameters attached to a page
are available to the drawing methods within that page and no other.
Parameters are designed to be used with pages that will be opened in multiple instances, where each instance displays its
own set of tags.
For example, a treatment center may have 10 nearly identical sub-stations, each of which will look like the others, but
each of which will have different labels and its own set of I/O tags. You can save time by creating one page as a template
for all the substations, using a parameter for each tag. The same page can be added to the menu 10 times, using a
different name and a different set of tags each time, thus saving hours of work.

Note: Never define parameters in the application’s default page. There is no way to select the tags that will be used for
these parameters when the default page opens. You would therefore see the Edit Parameters dialog every time the
application restarts

Developer's Guide (part 1) How to Build an Application • 167

The Append button opens the New Parameter dialog where you can define the name and the data type of page`s
parameters. See the next section: New Parameter Dialog.
The Edit button opens a dialog with the same features as that used for the New button. Only one parameter can be edited
at a time.
The up and down arrow buttons allow you to put the parameters into an order that seems logical for your application.

New Parameter Dialog

Note that this dialog does not provide a way to set the value of the parameter. Parameter values are supplied to an
instance of a page when it is drawn and can be set in one of two ways:
• When the page is first opened while in run mode, you will be prompted for values to supply to the parameters on
that page.
• In either the Menu Editor, the Page Hotbox configuration, or the Page Button configuration, you can set the values
that will be supplied to the parameters of the page for that instance. See: Edit the Parameter Values of a Page.

168 • How to Build an Application Developer's Guide (part 1)

Name: The name of the parameter

Note: Avoid using any name that might conflict with a VTS reserved word. To be safe, adopt a naming convention that
adds a distinct identifier to every name (for example "MA_Name" for My Application...)

Description: A description of the parameter. Optional, but highly recommended.

Type: The data type for the parameter. The data type of a parameter must match its intended use. For
example, if you plan to use a parameter for the scaling of a drawing object, only numeric parameters will be available to
select from.
Select Tag Type:Select Tag Type is used only when the parameter is a Tag Type. This list does not include tag groups,
but only specific tag types. If you use it to indicate that your parameter is a tag of type Analog Input, you cannot later
select an Analog Status to provide the data for an instance of that parameter.

Page Properties Advanced Tab

The Advanced Tab contains controls for the window size, location and appearance.

Developer's Guide (part 1) How to Build an Application • 169

Window Properties:
These apply only to pages that are opened as a window, separate from the main application.
• Position Sets the location of the upper left corner of the window, measured in pixels from the corner of the screen.
• Size Sets the initial size of the window, measured in pixels.
• Minimum Size If the page can be opened in a resizable window, this sets the minimum width and height to which
the operator is allowed to stretch the window.
• Maximum Size If the page can be opened in a resizable window, this sets the maximum width and height to
which the operator is allowed to stretch the window
Page Style:
These settings override the default page style. A page may be displayed either in the main window (normal) or as an
independent window similar to dialog box (windowed). You can control the appearance of both types of page through
the Change buttons in the page style area, each of which will open a Page Style dialog similar to that shown in the
following image.

170 • How to Build an Application Developer's Guide (part 1)

The page style dialog allows you to enable or disable the display of all the components that make up application's title
bar (top of the screen) and task bar (bottom of the screen). You can choose to display all the components of each (the
default state) or you can pick and choose individual components.

An example of a title bar with all decorations shown:

An example of a task bar with all decorations shown:

The checkbox "Hold Page Button Changes Target" is a function, not a decoration. When enabled and when you have
page buttons on the task bar as shown in the preceding example (Station Control and Overview) then you can replace one
button for another by the following steps:
1. Open a new page using the menu
5. Move the pointer over a button that you want to replace for a link to the current page.
6. Click-and-hold the mouse on that button for three seconds.
7. The link to the old page will be replaced with a link to the current page.

Background
Sets the default background color for pages in the application.

Bitmap Margins
When using a background bitmap on a page, you can use these values to set the top, bottom, left and right margins for
that bitmap.
By default, the margins apply only to full-screen pages. You also have a choice of using the margins for windowed
pages.

Link to Pages with the Page Hotbox

A page hotbox is a rectangular target, placed on an application page. This is a navigational tool that when clicked, opens
a new page as specified in its configuration.

Developer's Guide (part 1) How to Build an Application • 171

If the specified page has parameters (see: Page Properties Parameters Tab) then values for those parameters can be
provided in the page hotbox configuration. You might use this to create a series of page hotboxes, all pointing to the
same page, but each providing its own set of tags and values for the parameters.
Details on configuring the parameters of a page hotbox can be found in the next topic, Parameterized Page Hotboxes.
The Page Hotbox control is part of the Standard Library.

172 • How to Build an Application Developer's Guide (part 1)

The following image shows an example of the basic Page Hotbox graphic editor dialog.

The configuration shown will result in a yellow rectangle that users can click to open the page that has been associated
with it (Station1 in this example).

Note: As you place the hotbox on the screen during development, it will show as a simple rectangle. When the
application is running and an operator hovers over the area, the hotbox will appear as a shaded region.

Common implementations for page change hotboxes include:

• On the click of a page change hotbox surrounding an equipment bitmap, open a graphics page with controls and data
for the selected equipment. For example, a page change hotbox surrounding a pump might be clicked to enable
access to the pump's data and controls.

Developer's Guide (part 1) How to Build an Application • 173

• On the click of a page change hotbox surrounding a text label, open a related graphics page. For example, several
page change hotboxes might be drawn on a large map, with each configured to take the user to a more detailed view
of a section of the map.
Page hotboxes remain invisible until the mouse pointer is placed over the target area. Once the mouse pointer has been
placed over the target area, an outline of a page hotbox appears in a user defined color, thus identifying that a page
change will occur.

Note: The Page Hotbox drawing tool is much the same in appearance to the Set Value Hotbox drawing method for
Digital Output tags (see "Set Value Hotbox Drawing Method") ; however, its behavior is distinctly different. When the
Set Value Hotbox drawing method is clicked, it changes the value of the related Digital Output tag. Because the
appearance of the Set Value Hotbox tag drawing method and the Page Hotbox tool are similar, it would be prudent to
configure each with a distinct color to signify to operators that they are different tools.

Page Hotbox Editor Dialog Elements

Page Title Select the page you wish to open when this page change hotbox is clicked.
Page File Name Displays the file name of the page that will be opened when this page change hotbox is
clicked.
Note: The Page Title and Page File Name drop-down lists are directly associated. When a
page title is selected, the Page File Name drop-down list displays the corresponding page file
name, and when a page file name is selected, the Page Title drop-down list displays the
corresponding page title.

Parameterized Page Hotboxes

If the page hotbox links to a parameterized page, the configuration dialog will show a list of those parameters.

The input field will vary according to the type of parameter - text, checkbox, tag or number.

You can control where each field will look to find the value for the parameter. For example, a numeric parameter for the
page could be given a specific number, or you could choose a tag, a page parameter, a drawn tag property, etc. A
description of each choice follows:
• Tag (If the parameter is of type tag)

174 • How to Build an Application Developer's Guide (part 1)

 The first option in the list (see diagram) will always match the parameter’s defined type. This will often be a
tag, but it might be Numeric Value, Text Value…
You may only choose a data source whose type matches the defined parameter. Also, the scaling of the data
source cannot be changed here, as it can with the next option.
• Tag Value
You can select any tag whose value can be converted to a type that matches the parameter. If, for example, the
parameter is defined as text then nearly any tag can be selected and the value of that tag will be converted to
text.
For numeric values, you will also be given the opportunity to set the Minimum and Maximum output scaling.
• Expression
Opens the expression editor where you may enter VTS code that will produce a value that will be used for the
parameter. Requires knowledge of VTS programming.
• Parameters
Allows you to select any parameter in the current page to provide the data for the selected parameter in the
target page. See: Working with Parameters.

This feature is similar to, but more powerful than that of the menu editor (see: Edit the Parameter Values of a Page).
Both features allow you to create multiple links to one parameterized page, each link opening that page with its own set
of parameter values. The additional feature provided by the page hotbox is that, when a page hotbox is placed on a
parameterized page, parameters from that page may be specified for use as the values for the destination page’s
parameters. This powerful feature allows parameter values to be communicated across pages.

You may leave parameters un-assigned in the page hotbox dialog. The result will be that, each and every time an
operator uses this hotbox to open the page, they will need to set the data source for the parameters.

Link to Pages with the Page Button

The page button differs from the page hotbox only in appearance. Like the hotbox, it provides operators with a quick link
to another page.

Unlike the page hotbox, the Page Button will always be visible as a labeled button on the page.
If the label is to include an ampersand (&), then the & character will need to be doubled in order to appear.

You can find the Page Button in the Standard Library:

Developer's Guide (part 1) How to Build an Application • 175

The graphic editor for the Page Button will be similar to the following example. You have control over the text of the
label and the destination page that the button links to.

If the destination page has parameters (see: Working with Parameters.), you may configure the button to provide values
for those parameters.
Values for the parameters may be provided from any of: The native parameter type (tag, numeric, text, etc.), a tag value,
an expression, or a parameter from the page that the button is being added to.

176 • How to Build an Application Developer's Guide (part 1)

Close Pages with a Button
A Page Close button can be a useful addition to any page that is opened “windowed” rather than full screen. This
includes pages whose property is set to “Always display in window” and those set to “No Restrictions” which are opened
using a right mouse click from the menu, causing them to open as a window rather than in full screen mode.

(from the Page Properties dialog)

In a page that is displayed in full screen mode, the Page Close button will be visible, but disabled. An enabled Page
Close button is shown in the following example:

You can find this button in the Standard Library. To add one to a page, right-click on the Page Close button in the library
and select Draw from the context menu.

Drop the button on a page – the graphic editor will open to allow you to configure the labels.

Developer's Guide (part 1) How to Build an Application • 177

Note to VTS programmers: In general, it is not recommended that custom code be layered on top of existing page
objects. (For example, trying to make a Page Close button perform extra tasks before executing its own page-closing
code.) Create dedicated code instead

Pages Included with VTS Applications

Each new VTS application you create contains the following pre-configured system pages:
Alarm Page
Call-out List Page
Operator Notes Page
Reports Page
Historical Data Viewer Page
Internet Client Monitor Page
Lift Station Page
Site Details Page
Site List Page (SiteListWithMapPage)
Site Map Page
Applications based on the VTScada layer also include the following:
Communications Data Page (DataFlow RTU driver)

All of the pages listed above are referred to as “System Pages”. Excepting the Call-out List page, these are pages that
you cannot delete, rename or modify, and therefore they are not shown in the Pages list of the Libraries dialog. All are
available to be added or removed from the menu.

In addition to system pages, there are also “Application Pages”. These are the pages that you create as you build the user
interface for your application. You are free to add, edit and delete application pages as needed and without limit.
Overview Page: VTS provides one application page, named “Overview", in every new application. You can use
Overview as the starting page for your operator interface.

DataFlow Communications Data Page (VTScada)

If your application has been based on the VTScada layer, it includes a Communications Data page whose purpose is to
display data transmitted and received between the VTScada application and the DataFlow RTUs for your entire system.

178 • How to Build an Application Developer's Guide (part 1)

As shown, the Communications Data page displays packets of message code sent from the VTScada application to the
DFS RTUs (preceded by "Send" and colored blue), and from the DFS RTUs to the VTScada application (preceded by
"Reply" and colored green), along with the date and time at which each signal was transmitted or received.
Depending upon your application's configuration, the display of data on the Communications Data page may scroll quite
rapidly. The Freeze/Continue toggle button at the top of the Communications Data page allows you to freeze the display
so that you can have a closer look at the communications data. When you are finished reviewing the frozen display, you
can hit the button again to unfreeze the display.

Note: If you wish to view communications data for individual RTUs, click the Comm button appearing on the
appropriate RTU's station page. (To open a station page, click the appropriate station symbol on the Overview page.)

Understanding the Communications Data Display

The information in the Data Display follows the DFS protocol. For every blue Send message, there should be one or
more green Reply messages. A Send message without a matching Reply is a clear indication of a problem preventing the
station from answering.
The following figure shows an example of one Send/Reply transaction:

Developer's Guide (part 1) How to Build an Application • 179

As shown, each Send message will be bracketed by two non-printing characters (the square boxes). Each Reply ends
with a single box symbol. You should disregard these non-printing characters in the following guide to the codes.
The first two characters in each message are the address of the DFS RTU. (Again, disregard the boxes.) Looking at the
examples, you should see that for every Reply following a Send, these two leading characters match.
One exception to the above is the case of a “ZZ” command in the Send message. This indicates that a group poll is being
requested, starting at the address appearing in the 5th and 6th character places of the Send field. The following Replies can
be seen to include a series of RTU addresses.

A second exception to the above is the case of a station with a Digipeat path. In this case, the Send will start with the
address of the station it is repeating through, followed by ‘RD’ and then the station address of the RTU being polled.
The third character in the Send message is the module number. Here, “1” will indicate module A, “2” indicates module B
and so on, except for “R” which indicates a Radio module.
There is one exception to this pattern: A “0” in the third character position of the Send indicates that a Full Station Read
is being requested. All modules in the station should reply with their status, where an “x” will indicate “No Change” and
a “y” will indicate “Change”.
Normally if a reply indicates that there has been a change, a Send request will go to that module to request its new value.
The final character in either a Send or Reply is a check-bit. This may be any printing character, including punctuation.
This is the only character in either the Send or Reply that should ever have punctuation: a character other than a letter or
number in any other position is a sign of communication errors.

Freezing the Communications Data Display

To temporarily freeze the communications data displayed on the Communications Data page, simply click the Freeze
button. A hold will be placed on the data being displayed. This allows you to review the data closely. The Freeze button
will now be labeled, "Continue". Clicking the Continue button will remove the hold from the data and cause it to revert
to its regular display.

Note: Clicking the Freeze button does not stop data from being communicated; it merely freezes the display for closer
scrutiny. Data continues to be transmitted and received while the Freeze button is depressed.

Printing the Communications Data Page

You can print the Communications Data page by first freezing the communications display and then using one of the
following two methods:

VTS Print Screen Button

Click the Print Screen button appearing in the Display Manager’s title bar. A dialog will open and request confirmation
that you wish to print the page.
Click the OK button. The Communications Data page will be printed to the default printer configured under your
Windows operating system.

Shortcut Keys
Press the Ctrl + Print Screen shortcut keys to create a screen capture of the page.
Open a Microsoft Word document or a graphics software file.

180 • How to Build an Application Developer's Guide (part 1)

Press the Ctrl + V shortcut keys to paste the screen capture into the document or graphics file.
Print the image as directed by Microsoft Word or the graphics software.

Internet Client Monitor Page

This page enables you to view and administer VTS Internet Client (VIC) connections to your applications. The page
provides much the same functionality as is found in the VIC Monitor script application, but it brings those functions into
an application as a page. This provides a means for you to monitor and control VIC connections remotely.
For more information on the Internet Client Monitor, please refer to the Internet Client Monitor Application.

Site Map
A Site Map is a dynamically-loaded map, primarily used to show the location of any of the following site-related tags:
Polling drivers, DataFlow RTU drivers, MultiSmart™ stations, MPE™ Duplexer stations, or MPE™ SC stations. You
can also link a Context tag or a user-created type derived from a Context tag to a map by adding the properties "Latitude"
and "Longitude" to the parameter list. (See: Context Tags)
The map is sometimes referred to as a "slippy map" because of the way it can be moved within its frame. Operators can
pan and zoom to change the area displayed.
The map display is built of "tiles" - static images. At each higher magnification level, four times the number of tiles are
used for a given area. As the operator moves the display or changes magnification level, new tiles must be downloaded.
Once downloaded, they will be cached locally on your computer. These tiles are not distributed with VTS, therefore
your server must have an active Internet connection in order to be able to download tiles that have not been cached.
It is possible to switch from map view to satellite view, or to a different map provider. See Change the Map Type.
A Site Map is built into every automatically-generated lift station details page and into the Site Details page. (See: Site
Details Page and Station Pages). You can also add Site Maps to your application using the Site Tools Library, or the
Menu. Instructions are provided in the sub-topics of this article.

Any instance of the tag types listed above can be located on a Site Map as a pin. Operators can click on the pin to open
the associated Site Details Page.
The primary site associated with a map will be marked by an animated bubble. The head of the marker pin uses the same
color-indication system as the Site Draw Drawing Method, and described by the Site Legend.

Developer's Guide (part 1) How to Build an Application • 181

(c) OpenStreetMap Contributors http://www.openstreetmap.org/copyright
Tiles courtesy of MapQuest (Unless otherwise configured.)
Related information: Using Maps Without an Internet Connection.

Available controls for the map include: (*)

Control Action
Show All Sites A checkbox to enable or disable pin display for sites other than the root.
Update Site Location After clicking this button, the next click within the map area will re-locate the site.
Magnification Control A slider between (+) and (-) buttons. Provides a way to increase or decrease the
magnification (zoom level) one step at a time.
Click on any pin Opens the details page for that tag, as appropriate for the type.
Click and drag Relocate the focus of the map.
Mouse-wheel Zoom in or out.
Double-click Zoom in, one step, at the location clicked.
(*) Some controls will not be available, depending on how the map is viewed.

Note: Rather than use the default cache, you may set an independent source for the map tiles with
MobileSlippyMapTilesSource1 in your SETUP.INI file.
See: MobileSlippyMapTilesSource1.

182 • How to Build an Application Developer's Guide (part 1)

Draw as Site Map from the Site Tools Library
A site map can be added to any page as follows:
1. Open the Libraries dialog from the Configuration Toolbox.
2. Expand the Site Tools Library.
3. Right-click on Site Map and select Draw.
4. Place the map on a page.

Note that the map is drawn within its own window, which will have a higher z-order than the page it is being placed on.
The result can be loss of part of the VTS header or footer if the map is larger than the page.

The Graphic Editor options for a Site Map drawn this way, are as follows:

Parent
The station tag instance (and any child tags that also have valid latitude and longitude values) that is to be the primary
target of this site map. All sites shown will be marked by a pin, but the root site will be further indicated by an animated
dot.

Show All Sites

Choose whether this map instance should show only the root site, or if all sites visible in the map area should be shown.
In either case, the pin marking the root site for the map is the only one highlighted by an animated bubble.

Use Theme
Choose whether the borders of the map should follow the VTS color theme

Text Color
Specify the color to be used for the labels below the map.

Developer's Guide (part 1) How to Build an Application • 183

Add a Site Map Page to the VTS Menu
The Sites page and the Site Map page will be included in the menu in every new application. For applications that were
originally created in an older version of VTS, you will need to add these pages to your menu.
The Site Map page is a Site Map that fills an application page. The scale of the map will automatically adjust each time
that it opens in order to display all sites within the application. When the site map is opened as a page, you cannot
specify a root tag.
The parameter list for the Site Map page differs only slightly from the library option. By default, all child sites of the
selected parent will be shown.
Instructions for editing the menu can be found in Editing the Menu.
Instructions for adding a Hotbox or button can be found in Link to Pages with the Page Hotbox.

Change the Map Type

The default configuration of the Site Map page is a map. You can change this to a satellite view if you would prefer, or
you may substitute your own map provider.

Note that satellite tiles may not exist for all magnification levels.

1. Stop VTS
2. Using a text editor, open the file, Setup.INI
3. Change the property SlippyMapRemoteTileSource1 as follows:
SlippyMapRemoteTileSource1 = http://otile1.mqcdn.com/tiles/1.0.0/sat/

4. Save the file Setup.INI

5. Browse to Data folder under your VTS installation. (e.g. C:\VTS\DATA).
6. Rename the tile cache folder (SlippyMapTiles) so that the existing map tiles will not be used.
Alternately, you could delete the tile cache folder. By renaming the folder, you will avoid the necessity of
downloading tiles that have already been cached, should you decide to change back to the map view.
7. Restart VTS and run your application.
To use map tiles, the source URL is http://otile1.mqcdn.com/tiles/1.0.0/osm/

Create Custom Map Icons

You can create your own custom map icons (pins). For example, you may wish to provide visual clues to help operators
identify sites when more than one is displayed on a map.
The process is to create a Tag Drawing Method, provide a scaling parameter, then instruct your site tag to use that DM
instead of the built-in pin. It is recommended that you include a Pulse Beacon, which can be found in the Site Tools
library. The Pulse Beacon has no user-configurable parameters.

Key Details:
• Image Size: The image should be between 10x10 and 20x20 pixels in size.
• Transparent Edges: If using an image that is not already in the VTS library, set all parts that should be transparent to
pure black before importing. (RGB value, 000000.)
• Pin Center: The center of the new site pin's bounding box will be used as the pin location when shown on a map.
The center is calculated based on all graphics that make up the whole.
• Automatic Scaling: The drawing method should be given a numeric parameter named, ZoomLevel.
• Pulse Beacon: The animated spot that marks the active pin on a map is created by adding a Pulse Beacon from the
Site Tools Library. Ensure that the Pulse Beacon is sent to back so that it does not obscure the other parts of the pin
image.

184 • How to Build an Application Developer's Guide (part 1)

Using the Icon
There are four ways to use a custom map icon:
• To use the icon for a specific site, open the tag's configuration folder. Within the Display tab, choose the custom
map icon. Note: this assumes that, when creating the Tag Drawing Method, you configured it to be a drawing
method for the type of site you are now trying to configure.
• To use the icon for a group of sites that are the children or grandchildren of a specific Context tag, add a property
named, " CustomMapIconParm" to the Context, and set it equal to the name of the custom map icon's module.
• To use the icon for all instances of a given type of site, add a property to the [System] section of your
Settings.Dynamic file. This property must be named after the type you are configuring by putting the type name in
front of the keyword, "MapIconType". For example, "MultiSmartMapIconName = MyMapIcon".
• To use the icon for all sites of all types, give your custom map icon the name "CustomMapIcon".

Example:
1. Open the Libraries dialog, and expand the menu to show User Draw Methods.
2. Right-click to Add a new method.

3. Provide a name for the pin.

4. Ensure that the option, New Tag Draw Method is selected.
5. Select all the types of site that you might use the pin for (Polling driver, Station tag, Context, ...).

Developer's Guide (part 1) How to Build an Application • 185

 6. Right-click on the new DM and select Properties from the menu.
7. In the Parameters tab, click Append.

8. Set the name to "ZoomLevel", and the type to any of the numeric options. A description is recommended.
9. Save the new parameter and close the properties dialog.

10. Right-click on the new DM and select Edit from the menu.
11. When the tag browser opens, select any existing site tag to use during the editing session.
12. When prompted, set the ZoomLevel parameter to 18 (the maximum value). Ignore the other parameters.
13. In the Drawing Method Editor, remove the questionable data marker (yellow diamond).
14. Add the bitmap image(s) that you wish to use for the pin.
It is recommended that you add a Pulse Beacon from the Site Tools library. After adding this, select it and then
click the Send to Back tool in the configuration toolbox.

186 • How to Build an Application Developer's Guide (part 1)

 15. Adjust the position of all objects so that the center of the overall bounding box of all objects coincides with the
location that you wish to use as the pin-point. The location of the objects within the Drawing Method Editor
does not matter for site pins.

You may wish to add a Site Draw to the pin. This provides a visual indication to operators, showing the status
of the site and also allows them to click on the pin to open the related Site Page.
16. Do so by drawing any of your sites as a Site Draw within the Drawing Method Editor.
17. When the VTS Graphic Editor opens, select the Tag option from the menu.
18. Change the tag source from "Tag" to "Drawn Tag Property".
19. Select the relevant drawn tag type from the drop down menu. (Select only the parent, Drawn Tag, not any of the
properties or variables.)

Using Maps Without an Internet Connection

Trihedral cannot supply map tiles. The files must be downloaded from Open Street Maps or other source.
However, the tiles for each map you view are downloaded to, and cached on your computer. Each time you view the
same map again, the tiles in the cache will be used rather than pulling new copies from the Internet.
These files can be found in the folder, C:\VTS\Data\SlippyMapTiles (and sub-folders). By viewing all areas of interest
in a map region, and at all zoom factors, while your VTS workstation is attached to the internet, you will have all the
files you need in order to continue viewing those maps after the internet connection has been removed. The names of the
map tiles match the area and zoom factor viewed, and are not unique to your computer or VTS in any way.

Site Details Page

The Site Details Page replaces the older VTScada Station Page, which was associated with Polling drivers and DataFlow
RTU tags. The Site Details page can be used with either of those drivers, with a Station Tag (MultiSmart or MPE), and
with a Context tag that has latitude and longitude properties.

Developer's Guide (part 1) How to Build an Application • 187

The Site Details page is generated automatically for you by VTS. There are two methods that operators can use to open
this dialog:
• If you use the Site Draw drawing method to draw a polling tag (Types: Polling Driver, or DataFlow RTU) then
operators can click on the Site Draw to open this page.
• If you have drawn a Site Map on a page, and any tag listed below is located on the map (shown as pins), then
operators can open the Site Details page by clicking on the pin. Types include Polling Drivers, DataFlow RTU
drivers and Context tags that have valid latitude and longitude properties.
Every Site Details page has two tabs: I/O and Map. The map is simply a Site Map, showing the location of the station.
See: Site Map for further details.
The I/O page contains three sections: The window to the left shows a number of statistics associated with the driver, and
contains buttons that open the Comm Messages dialog or the Comm Statistics dialog for the driver.
The Alarms list will be populated with all current alarms associated with the driver. Operators may use the Ack button
here to acknowledge any given alarm.
The I/O tags associated with the site are shown at the bottom of the page. Red text indicates an unacknowledged alarm
on an Analog tag. A red dot indicates an unacknowledged alarm on a digital tag. Controls are provided for all output
tags associated with the station.

Sites Page
The Sites (or "Site List with Map") page is a system page that you may choose to add to your VTS menu or to a Page
Hotbox or Page Button.
A Site Map is built into the Site List page, but operators can choose to display it or not by clicking the checkbox, Show
Map.

A "site" is defined as any of the following tags: Polling Driver, MPE Duplexer, MPE SC Series, MultiSmart, DataFlow
RTU, and ScadaAce. Context tags can also be associated with a Sites Page by the addition of a property named
"StationPageName". To represent the Context tag as a pin on a Site Map, it must also have the properties "Latitude" and
"Longitude".

188 • How to Build an Application Developer's Guide (part 1)

If no site is specified in the page's parameters, then all sites in the application are shown in a list on the left side of the
page as Station Summary Drawing Methods. You may filter this list to show only the sites below a specified parent tag if
you wish. To do so, open the page's properties dialog and select the appropriate parent tag.
This list may be compressed by using the Compact View option, if there are more sites than will fit on one page.

Sites page: (illustration includes four example sites). As you move the mouse pointer over each site in the list, its marker
pin on the map will be highlighted with a dot.

Configuring the Site List Page

After adding the Site List page to the VTS Menu, or to a Page Hotbox, you may choose to configure its parameters. By
doing so, you can select a specific site for the page to display, and can control whether the application's theme color will
be used for the page. You can also specify the color that should be used for the labels. Note that any child sites of the
selected site tag will also be included in the Sites page.
The parameter list is as shown (menu editor):

Developer's Guide (part 1) How to Build an Application • 189

Station Pages
Note: The station page still exists, but is considered obsolete, having been replaced by the newer Site Details Page.
If you would prefer to continue using station pages, add the property UseOldSiteDialog to the System section of your
application's Settings.Dynamic file, and set the value of that property to "1".

Each time you create a new Polling Driver or a new Data Flow RTU driver tag for your application, VTScada
automatically creates a station page for the new station.

Station pages are launched when the station symbol for the Polling Driver or Data Flow RTU driver tag is clicked. You
may change the page that is launched when a station symbol is clicked (i.e. you may open a custom page you have
created for the station) by changing the station symbol's configuration.

Opening a Station Page

Note: The station page still exists, but is considered obsolete, having been replaced by the newer Site Details Page.
If you would prefer to continue using station pages, add the property UseOldSiteDialog to the System section of your
application's Settings.Dynamic file, and set the value of that property to "1".

190 • How to Build an Application Developer's Guide (part 1)

For a polling driver, the station number is the number that has been assigned to the Poll Sequence Number property on
the tag's I/O tab. (See: Polling Driver Tags)
For a Data Flow RTU driver tag, the station number is the number that has been assigned to the Station Number (RTU
Address), Digipeat Route property on the tag's ID tab.
The Station Navigator is activated when you press either the F11 or F12 function keys on your keyboard.
• When called by the F11 key, the Station Navigator will open the associated station dialog in a resizable window that
sits on top of any other page you were viewing previously.
• When called by the F12 key, the Station Navigator will open the associated station page as a regular, full-sized
window in the Display Manager's page display area.

To open the station dialog for a specific station, enter the station number in the Station Number field, and then press the
OK button.

Note: If you have entered an invalid station number (i.e. one that has not been assigned to the Poll Sequence Number
property of any Polling Driver or to the Station Number (RTU Address), Digipeat Route property of any Data Flow RTU
tag), you will receive an error message.

As discussed in the previous section, station pages display and provide access to information about the Polling Driver or
Data Flow RTU tag and its associated I/O tags. There are two ways in which you can open a station page:
• Click the station symbol associated with the station whose data you wish to view (while the application is in
operation mode); OR
• Press the F11 function key on your keyboard, and then enter into the Station Navigator the appropriate station
number.

Note: For a polling driver, the station number is the number that has been assigned to the Poll Sequence Number
property on the tag's I/O tab. For a Data Flow RTU driver tag, the station number is the number that has been assigned to
the Station Number (RTU Address), Digipeat Route property on the tag's ID tab.

Interpreting Data on a Station Page

Note: The station page still exists, but is considered obsolete, having been replaced by the newer Site Details Page.
If you would prefer to continue using station pages, add the property UseOldSiteDialog to the System section of your
application's Settings.Dynamic file, and set the value of that property to "1".

I/O Device Data

Each station page provides information about the polling driver or Data Flow RTU driver tag it represents, and about its
related I/O tags. When you initially configure a new Polling Driver or Data Flow RTU driver tag, but have not yet
configured or associated any I/O tags with it, the automatically generated station page appears like the one displayed
below.

Developer's Guide (part 1) How to Build an Application • 191

As you can see from this example, the top portion of the station page displays and provides access to information about
the corresponding RTU or PLC, including:
• Data Age The amount of time that has elapsed since the last time the RTU was polled (e.g. in the example above, it
has been 12 seconds since the last poll).
• Station Number The RTU address or number associated with this station (e.g. in the example above, the station
number for this RTU is "126").
• Total Number of Stations The total number of stations configured in this VTScada application (e.g. in the example
above, the total number of stations in this system is "299").
• Poll Mode Indicator The poll mode indicator appearing beneath the station number indicates whether this RTU is
in fast poll mode (blue), or normal poll mode (green). Normal poll mode polls all stations in the order of their station
numbers and continues this cycle (e.g. station 200, 201, 202, 203…). Fast poll mode polls for data as fast as the data
can flow. Typically the station currently in fast poll mode will be polled, followed by the station next in the queue
for normal polling, followed by the station currently in fast poll mode, and so forth (e.g. if station 200 is in fast poll
mode, the polling pattern will be: station 200, 201, 200, 202, 200, 203…).
• Show Stats The Show Stats button can be clicked to open the Driver Statistics dialog, which displays the details of
any errors encountered by the RTU.
• Normal/Fast The Normal/Fast poll button (labeled "Normal" in the image above) toggles the RTU between normal
and fast poll modes. Please note that this button is labeled with the action that will occur when it is next clicked.
When the button is labeled "Normal", the RTU is in fast poll mode (as indicated by the Poll Mode Indicator's color).
When the button is labeled "Fast", the RTU is in normal poll mode (again, as indicated by the Poll Mode Indicator's
color).
• Modules The Modules button can be clicked to open the Installed Modules dialog which displays the modules that
have been installed at this RTU (e.g. AMM, DMM, DCM, etc.)
• Comm The Comm button can be clicked to open the Driver Comm Messages dialog that displays the
communications transmitted and received by this RTU.
• Alarm List The Alarm List on a station page has two views – unacknowledged alarms, or current alarms (a mixture
of alarms that are either active, unacknowledged, or both). The list that is currently being viewed is displayed on the
label above the alarm list. Use the Unack./Current toggle button (described below) to toggle the list between these
two views.
• Silence The Silence button silences the alarm sound which has been triggered for the most recently triggered alarm.
• Ack Shown The Ack Shown button acknowledges all unacknowledged alarms related to this station/RTU.
• Unack./Current The Unack./Current button (labeled "Unack." in the image above) toggles the alarm list between
the unacknowledged list, and the current list ( a combination of alarms that are either active, unacknowledged, or
both).

I/O Data
Once you begin to configure input and output tags and associate them with your polling driver or Data Flow RTU tag,
VTScada will include them on the related station page.
The image below displays an example of a station page including I/O values.

192 • How to Build an Application Developer's Guide (part 1)

As you can see from the above example, four columns along the bottom of the station page contain I/O data being read
from an RTU. Note that there is a drawback to using long tag names.
• The first column on the left displays data for all Analog Status tags associated with this RTU driver tag at the top of
the column, and data for all Pulse Input tags associated with this RTU tag at the bottom of the column.
• The second column from the left displays data for all Digital Status tags associated with this RTU driver tag at the
top of the column, and data for all Pump Status tags associated with this RTU tag at the bottom of the column.
• The final two columns on the right represent the Digital Control tags associated with this RTU driver tag and enable
you to control the digital processes associated with the selected station. These digital control drawing methods are
drawn in corresponding pairs (e.g. an OFF button and an ON button).
The order in which the columns are arranged (as indicated above) is automatically configured by VTScada, and cannot
be manually modified, however, you may modify the order in which the tags appear within the designated section of the
designated column. For example, you may modify the order of the Analog Status tags in their designated portion of the
station page, but you may not modify the order of the columns on the station page.

I/O Display Order on a Station Page

Note: The station page still exists, but is considered obsolete, having been replaced by the newer Site Details Page.
If you would prefer to continue using station pages, add the property UseOldSiteDialog to the System section of your
application's Settings.Dynamic file, and set the value of that property to "1".

As indicated in the previous section, there is a pre-defined order in which the tag types appear on a station dialog. The
illustration below shows this order.

Developer's Guide (part 1) How to Build an Application • 193

The first column on the left is reserved for analog status and Pulse Input tags, with Analog Status tags appearing at the
top of the column, and Pulse Input tags appearing at the bottom.
The second column from the left is reserved for digital status and Pump Status tags, with the Digital Status tags
appearing at the top of the column, and the Pump Status tags appearing at the bottom.
The third and fourth columns are reserved for pairs of digital controls, with the "off" controls appearing on the inside
column, and the "on" controls appearing on the outside column.
You can not rearrange the order in which these columns appear, but you can change the order in which the tags appear in
the appropriate portion of their respective columns.

Setting the I/O Display Order Alphabetically on a Station Page

Note: The station page still exists, but is considered obsolete, having been replaced by the newer Site Details Page.
If you would prefer to continue using station pages, add the property UseOldSiteDialog to the System section of your
application's Settings.Dynamic file, and set the value of that property to "1".

The manner by which the I/O associated with a polling driver or Data Flow RTU are sorted on a station page (i.e.
alphabetically or numerically) is controlled by the configuration of the Site Draw drawing method used to draw station
symbols.
To set the order of the I/O associated with a polling driver or Data Flow RTU alphabetically on a station page (sorted
alphabetically by each tag's Description property), follow the instructions included below:

Note: The instructions below will guide you through the process of drawing a polling driver or Data Flow RTU driver
tag on a page using the Site Draw Drawing Method, as clicking the resulting station symbol is the means by which a
station page or custom page is accessed. If you have already drawn the polling driver or Data Flow RTU driver tag using
the Site Draw tag drawing method, you may modify its settings by clicking the Configure button, right-clicking the
station symbol, and proceeding to step 8 below.

1. Open the page upon which you wish to draw the polling driver or Data Flow RTU driver tag as a station symbol
(typically the Overview page).
2. Click the Configure button to open the Configuration Toolbox.
3. Click the Browser button to open the Tag Browser.
4. Select Drivers from the Types drop-down list (the Drivers tag group appears quite far down in the Types drop-
down list).
5. Select the Polling Driver or Data Flow RTU driver tag representing the station that you wish to draw, and for
which you wish to establish the order of the I/O on the associated station page.
6. Click the Draw button. The polling driver or Data Flow RTU driver tag drawing methods will be displayed.

194 • How to Build an Application Developer's Guide (part 1)

 7. Click the Site Draw button. The Site Draw dialog will open similar to the one displayed below.

8. Select the Alphabetical Sort Order radio button.

9. Click the OK button. The station symbol will be attached to your mouse pointer.
10. Position the station symbol on your page.
11. Click to drop the station symbol. The Tag Browser will reopen.

Developer's Guide (part 1) How to Build an Application • 195

 12. Close the Tag Browser.
13. Close the Configuration Toolbox.

You may now click the station symbol you just drew to view the associated station page. The I/O will be sorted
alphabetically in the appropriate portions of their respective columns (i.e. Analog status tags from a-z by Description,
and then Pulse Input tags from a-z by Description in the first column. Digital status tags from a-z by Description, and
then Pump Status tags from a-z by Description in the second column. Finally, Digital Control tags from a-z by
Description in the third and fourth columns).

Setting the I/O Display Order Numerically on a Station Page

Note: The station page still exists, but is considered obsolete, having been replaced by the newer Site Details Page.
If you would prefer to continue using station pages, add the property UseOldSiteDialog to the System section of your
application's Settings.Dynamic file, and set the value of that property to "1".

The manner by which the I/O associated with a Polling Driver or Data Flow RTU tag are sorted on a station page (i.e.
alphabetically or numerically) is controlled by the configuration of the Site Draw drawing method used to draw station
symbols.
To set the order of the I/O associated with a Polling Driver or Data Flow RTU tag numerically on a station page (by the
Display Order configured for each I/O tag), follow the instructions included below:

Note: The instructions below will guide you through the process of drawing a Polling Driver or Data Flow RTU driver
tag on a page using the Site Draw Drawing Method, as clicking the resulting station symbol is the means by which a
station page or custom page is accessed. If you have already drawn the Polling Driver or Data Flow RTU driver tag using
the Site Draw tag drawing method, you may modify its settings by clicking the Configure button, right-clicking the
station symbol, and proceeding to step 8 below.

1. Open the page upon which you wish to draw the Polling Driver or Data Flow RTU driver tag as a station
symbol (typically the Overview page).
2. Click the Configure button to open the Configuration Toolbox.
3. Click the Browser button to open the Tag Browser.
4. Select Drivers from the Types drop-down list (the Drivers tag group appears quite far down in the Types drop-
down list).
5. Select the Polling Driver or Data Flow RTU driver tag representing the station that you wish to draw, and for
which you wish to establish the order of the I/O on the associated station page.
6. Click the Draw button. The Polling Driver or Data Flow RTU driver tag drawing methods will be displayed.
7. Click the Site Draw button. The Site Draw dialog will open similar to the one displayed below.

196 • How to Build an Application Developer's Guide (part 1)

 8. Select the Numeric Sort Order radio button.
9. Click the OK button. The station symbol will be attached to your mouse pointer.
10. Position the station symbol on your page.
11. Click to drop the station symbol. The Tag Browser will reopen.
12. Select All in the Tag Browser's Types drop-down list.
13. Select the Area configured for the Polling Driver or Data Flow RTU driver tag you just drew in the Areas drop-
down list. The Tag Browser will then display all input and output tags associated with your station.
14. Select the first tag in the list.
15. Click the Properties button. The tag properties folder for the selected tag will open.
16. Click the Order tab.
17. Set the Display Order spin box according to the order in which you wish this tag to appear in its respective
column. (For example, Analog Status tags appear in the top half of the first column on a station page.)
18. Click the OK button.
19. Select the next I/O tag in the list and repeat steps 15 through to 18 until you have given each I/O tag associated
with this station a display order number.
20. Close the Tag Browser.
21. Close the Configuration Toolbox.
You may now click the station symbol to view the associated station page. The I/O will be sorted numerically by their
configured Display Order in the appropriate portions of their respective columns (i.e. Analog status tags numerically by
Display Order, and then Pulse Input tags numerically by Display Order in the first column; Digital Status tags
numerically by Display order and then Pump Status tags numerically by Display Order in the second column; and
finally, Digital Control tags numerically by Display Order in the third and fourth columns).

Responding to Alarms on a Station Page (VTScada)

Note: The station page still exists, but is considered obsolete, having been replaced by the newer Site Details Page.
If you would prefer to continue using station pages, add the property UseOldSiteDialog to the System section of your
application's Settings.Dynamic file, and set the value of that property to "1".

When an alarm has been triggered for a station, the centre of the associated station symbol will flash red to notify
operators of the alarm condition. Additionally, an alarm siren will sound.
To respond to alarms for a given station, follow the instructions below.
1. Ensure that your application is in operational mode (i.e. the Configuration Toolbox is closed, or its No Tool is
selected). You cannot respond to alarms while in development mode.
2. Open the station page of the station for which one or more alarms is being indicated (as indicated by a flashing
red station symbol). As you can see from the example below, three alarms associated with this station have been
triggered, are highlighted in the alarm list, and are indicated on the drawing methods for the associated tags
(these flash red to indicate unacknowledged alarms).

Developer's Guide (part 1) How to Build an Application • 197

 3. Click the Ack Shown button. All alarms for the selected station will be acknowledged, and the alarm siren will
cease.

198 • How to Build an Application Developer's Guide (part 1)

As shown in the example above, the alarms have been acknowledged; they are no longer highlighted in the alarm list,
and the drawing methods for the associated tags have ceased flashing in red, indicating that the alarms have been
acknowledged but are still active (i.e. the condition that caused them to trigger still exists).
In order to remove active alarms from the alarm list, you must remedy the situation that caused the alarms to trigger.
See also: Responding to Alarms.

Printing a Station Page

Note: The station page still exists, but is considered obsolete, having been replaced by the newer Site Details Page.
If you would prefer to continue using station pages, add the property UseOldSiteDialog to the System section of your
application's Settings.Dynamic file, and set the value of that property to "1".

Developer's Guide (part 1) How to Build an Application • 199

You can print a station page using the following method:
1. Press the Ctrl + Print Screen shortcut keys to create a screen capture of the page.
2. Open a Microsoft Word document or a graphics software file.
3. Press the Ctrl + V shortcut keys to paste the screen capture into the document or graphics file.

Station Details Page For MultiSmart, MPE SC and MPE Duplexer

Note: Available only in VTScada applications that include MultiSmart Station tags, MPE SC Station tags or MPE
Duplexer Station tags.

In the menu editor, this page is listed as "Lift Station Page". It is a parameterized page, for which you must select a
Station tag and other display parameters.

The Station pages use the information from a Station tag to create complete monitoring and control displays for your
pumping stations.

Each station tag can be drawn using a Station Icon drawing method or a Station Summary drawing method, both of
which provide a link to these automatically-generated pages. You could also create a menu entry, hotbox or hot button to
open one of these pages, providing the correct station tag as a page parameter.

The Station page is an assembly of various monitoring and control drawing methods for the associated station tag. Each
component is described in the following sub-topics. The specifics will vary according to whether the station is a
MultiSmart, MPE SC series or MPE Duplexer, but most components of the pages will be found for all types of station
tag.

200 • How to Build an Application Developer's Guide (part 1)

Well Details
Includes the Well Flow and Well Plot drawing methods.

The number of pumps displayed will match the configuration of the associated Station tag. When a pump is running, it
will be shown in green.
The current water level is represented by the shaded background and the numeric display. High and low alarm setpoints
for the pumps are shown by the red lines with matching numeric values.
The current flow, both in and out, is displayed as well as a trend of the past 24 hours, showing well level and alarm
levels.

Pump Control
Provides a Hand-Off-Auto control for each pump in the station.

Developer's Guide (part 1) How to Build an Application • 201

The label indicates whether the pump is running (displayed in green), stopped (gray) or if it will be the next to run
(yellow).

Station Summary
The Station Summary varies according to the type of station tag.

MultiSmart Station Summary:

For the MultiSmart Station, six operational profiles may be defined in the Setpoints tab. Profiles are used to store lead
and lag setpoints to be used under varying operating conditions such as storms, drought, etc. The profile selection in the
summary page shows which is active and allows you to select which to use.
If your station uses the Modbus protocol, only the profile number will be shown. If using the DNP3 protocol, you will
see the profile description displayed.

Operating notes may be added using the + button. This opens the standard VTS notebook dialog. Use these to create a
permanent record of operational and maintenance tasks.

For comparison, the station summary pages for the MPE Duplexer Station and the MPE SC Station are shown in the
following images. Note the lack of a Setpoints tab for the MPE Duplexer Station. The MPE SC Station has a Setpoints
tab, but only a single profile.

MPE Duplexer Station Summary:

202 • How to Build an Application Developer's Guide (part 1)

MPE SC Station Summary:

Developer's Guide (part 1) How to Build an Application • 203

Station Alarm List
Shows all current faults in the station. You may acknowledge or silence alarms with the buttons provided. A blinking
indicator shows that the alarm has not received a reset, sent from the Faults tab.

Station Statistics
An extensive collection of statistics is collected and displayed for each individual pump, the station as a whole, and the
well.

Tabs across the top of the display provide access to different sets of statistics. The number of tabs and the statistics
gathered will vary with the type of station controller.
Within any tab, statistics are grouped by item of equipment (pumps, well, station as a whole). The number of equipment
items shown will vary depending on your screen size. If there is not enough room to show all items, a scroll bar will be
provided so that you can select which set of statistics to view.

Station Faults and Fault Reset

There are two pages within the faults tab: a list of faults, grouped by component and a set of fault reset controls.

204 • How to Build an Application Developer's Guide (part 1)

Indicators will show red when a fault is present and green otherwise. After a fault has been reset, the corresponding
alarm must still be acknowledged in VTS.

Station Inputs
Provides a list of all input tags associated with the station. The list is divided into two pages - digitals and analogs
(digitals shown below). For the digitals, a color dot indicates the tag's value: green is used for zero, red for one and gray
indicates 'no data'. The analog tags are shown with their current value.

Developer's Guide (part 1) How to Build an Application • 205

Station Controls
The station controls page provides access to all output tags in the station, grouped by digitals and analogs.
To operate a digital control, click the corresponding button. To operate an analog control, click in the appropriate field as
shown, then type the new value that should be written to the station.

206 • How to Build an Application Developer's Guide (part 1)

Station Setpoints
For MPE SC Stations and MultiSmart Stations. Sample image shows the MultiSmart's Station Setpoints display.
Allows you to set the lead and lag setpoints for the pumps. One profile can be set for the MPE SC Station, while six
profiles may be created for the MultiSmart, each with a different configuration of setpoints. These are provided to allow
operators to quickly switch operating parameters in response to changing conditions such as an approaching rainstorm,
etc. The various profiles are used only for changing the pump lead and lag setpoints. Alarm setpoints are accessed only
through the Current tab of the display.
For reference, the display also shows the current depth of water in the well as a blue background.
You can adjust the setpoints using the sliders, or for greater accuracy, you may type values into the fields above each
setpoint slider.

Developer's Guide (part 1) How to Build an Application • 207

The Menu Editor
The contents and configuration of the page menu are set using the Menu Editor button in the Configuration Toolbox.

The Menu Editor consists of both a toolbar and a menu structure. When used together, both the toolbar and the menu
structure enable you to create menus and submenus for your applications.

Note: You can also create page navigation features using the Page Hotbox or the Page Button.

VTS automatically creates 3 pages when you configure a new application: a system page, the Historical Data Viewer
page, and the Alarm page. Although the application page you add using the New Application Properties dialog is added
by default to the application's menu, the Historical Data Viewer page and Alarm page are not. You can add them to the
menu structure using the Menu Editor.
Each time you create a new page, or copy or add an existing page using the Configure dialog, VTS queries you as to
whether you wish the page to be added to the menu.

If you choose to add the page to the menu, the page will be added to the menu's root. This function streamlines the
development of your menu structure.
The table below identifies and describes the tools available in the Menu Editor's tool bar.

Menu Menu Editor Tool

Editor Tool Name Description

208 • How to Build an Application Developer's Guide (part 1)

 Add The Menu Editor's Add button opens the Add Menu Item
dialog that displays the titles and page file names for all the
pages configured for this application. Selecting a page adds
it to the menu structure.
Note: The page will be added to the menu structure beneath
the currently selected menu item; however, you can move
menu items around in the Menu Editor by dragging them.
Add Divider The Menu Editor's Add Divider button inserts a divider in
the menu structure beneath the currently selected menu
item.
Add Sub-tree The Menu Editor's Add Sub-tree button inserts a sub-tree to
the right of the currently selected menu item and provides
space for you to enter a title for the sub-tree.
Cut The Menu Editor's Cut button deletes the currently selected
menu item from the menu structure.
Note: When an item is cut from the menu structure, it is
held in memory and may be pasted the same location or in
another location using the Paste button identified below.
Copy The Menu Editor's Copy button copies the currently
selected menu item in the menu structure.
Note: The Copy button works with the Paste button
identified below.
Paste The Menu Editor's Paste button pastes a cut or copied menu
item beneath the currently selected menu item.
Parameters Provides a means for viewing and editing the values of the
parameters associated with a selected page.

Note: You can add text that will be displayed along the left side of the menu when it is expanded. Use the application
property, MenuSystemTitle. See: Application Properties for details about setting a value.

Add a Page to the Menu

VTS can automatically add pages to the menu when they are created. When you use the Configure dialog to add a new
page, a dialog similar to the one shown below opens and requests confirmation as to whether you wish the new page
added to the application.

To add a page to the menu, click the Yes button. If you do not wish the page to be added, click the No button.
You can also add pages to the menu manually, using the Menu Editor's Add button. To do so, follow the instructions
below.
1. Open the Menu Editor using the Menu Editor button that appears in the configuration toolbox.
2. Select the menu item under which you wish the new menu item to be added.

Developer's Guide (part 1) How to Build an Application • 209

 3. Click the Add button (shown below). The Add Menu Item dialog opens and displays all the available pages for
your application.

4. Select the page you wish to add as a menu item.

5. Click the OK button. The selected page is added to the menu as a menu item.

210 • How to Build an Application Developer's Guide (part 1)

Add a Divider to the Menu
Menu dividers are useful in situations where you wish to separate pages of a specific type from other pages in the menu.
When you add a divider to the menu, a horizontal line is added to the menu.
1. Open the Menu Editor.
2. Select the menu item under which you wish the divider to be added.

3. Click the Divider button (shown below). A divider menu item is added to the Menu Editor under the selected
menu item.

Developer's Guide (part 1) How to Build an Application • 211

The menu will now display a horizontal line under the menu item you'd selected as shown below.

Add a Sub-Tree to the Menu

Like dividers, sub-trees are also useful in situations where you wish to separate pages of a specific type from other pages
in the menu; however, a sub-tree adds a fly-out menu panel to the menu, rather than a horizontal line. To add a sub-tree:
1. Open the Menu Editor.
2. Select the menu item under which you wish the sub-tree to be added.
3. Click the Add Sub-tree button (shown below). A Sub-tree header is added to the Menu Editor.

212 • How to Build an Application Developer's Guide (part 1)

 4. Enter a title for the sub-tree in the edit field.
5. Press the Enter key on your keyboard. The sub-tree is added to the Menu Editor.

You can now reposition menu items under the sub-tree by clicking and dragging, or you can use the Add button to add
new pages as menu items for the sub-tree.

Edit the Parameter Values of a Page

Parameter values are linked to the menu entry that calls a particular page. You can have multiple menu entries for the
same page, all with sources supplying the parameter values. The multiple menu entries can all have different text to
distinguish them.

Developer's Guide (part 1) How to Build an Application • 213

Thus, for example, if an application has ten identical stations, one page could be defined for a station, using parameters
for all of the I/O tags. That same page could be called 10 times from the menu for the 10 stations, each time with a
different set of I/O tags being used to supply the parameter values.

Note that changing the menu entry text causes a dialog to open, asking if you want to modify the title of the associated
page. If you do so, it will change the title of the page for all other menu entries that call that same page.
You can edit the values associated with a page's parameters by first selecting the page, then clicking the parameters

button:
If the selected page does not have parameters, you will see the following dialog:

Click the OK button to exit from the error message.

If the page does have parameters, the Edit Parameters dialog will open as shown:

For each parameter defined in the page, the following will appear:
• A bitmap graphic that indicates the parameter's type
• The name of the parameter
• The description of the parameter below that.
• Either an edit field where you can type the value, or a tag selector.
You must provide values of the right type. For example, providing text to a parameter that expects a number will cause
the following error message to be displayed:

Open the Page Properties Dialog for a Selected Page from the Menu
Editor
You can open the Page Properties dialog for a selected page from the Menu Editor. To do so, double-click the page's
entry in the editor. For further information about the Page Properties dialog, see the topic, Page Properties.

To close the menu item without adding a page as a menu item, click the Cancel button or the X in the upper right corner.

214 • How to Build an Application Developer's Guide (part 1)

Tags Properties Reference
The flexible nature of Visual Tag System (VTS) software is due to the custom building blocks upon which it is based.
These building blocks are called "tags". The term "tag" in the VTS name indicates the central role that they play in the
design and use of the VTS software.

Note: Tags were originally referred to as points. This term is antiquated but may still be found in some contexts.

A tag is a software component that can communicate with objects in the physical world. For flexibility, each tag type is a
specialized component that can be combined with other tag types to build diverse systems. For example:
• Port tags handle communication between the VTS server and the outside world, whether through a serial port or a
TCP/IP port.
• A specialized driver tag is available for nearly any brand of PLC hardware. Driver tags rely on port tags in order to
communicate with the hardware.
• Input and output tag types, both analog and digital, monitor and communicate with individual addresses on the
remote PLC. I/O tags rely on driver tags to ensure that communications are properly formatted for the remote
hardware.
• Alarm tags and Logger tags can be linked to any I/O tag to monitor and record values.
The term, “communications chain” describes the linkage of VTS with remote hardware through the I/O tag, to the driver
tag, to the port tag. By choosing appropriate tags for each link in the chain, you can build VTS applications for nearly
any situation.

Standard versus Custom Types.

All of the various types of tags that come with VTS & VTScada are described in this chapter. These are known as the
standard types.
VTS also gives you the ability to define your own types of tag. This can be done by creating groups of port, driver, I/O,
alarm and other tags that fully describe a type of equipment, such as a pumping station, motor, well, etc. You are also
able to use the VTS programming language to build completely new types of tag, designed specifically for your needs.

Developer's Guide (part 1) How to Build an Application • 215

The preceding figure illustrates the communication chain. The equipment that makes up the physical system is connected
to a PLC. This PLC is connected via a serial port to a PC running a VTS application.
Data collected from the equipment is transmitted from the PLC through the PC's serial port to a Serial Port tag. The
Serial Port tag passes the data to the driver tag representing the I/O device (in this example, a Modicon Driver tag). This
communication driver tag accepts the data and passes it to the analog and digital tags representing the equipment
processes within the physical system. Finally, each tag in the system has its own visual representation, showing the
system operators the status, mode and data of the associated equipment. The visual representations may include such
items as animated bitmaps and fluctuating numeric values.
Control is achieved by sending signals back through the chain. The user clicks a button or enters a numeric value in a
field, either of which is a visual representation of an output tag. The button click or numeric value is sent to the
communication driver for translation. The communication driver translates the signal to the correct format for the PLC in
use, and sends it to the Serial Port tag to transmit out to the PLC. The equipment process receives the new value and then
performs the required action (e.g. turns the pump off).

It is typical to begin each application you create by configuring a port tag to accept the data that is flowing through your
PC, and a device driver tag to provide an interface to physical I/O devices such as programmable logic controllers (PLC),
remote terminal units (RTU), I/O boards, or to Windows system features such as Dynamic Data Exchange (DDE). Once
you have these essential tags in place, you can create analog, digital and other tag other types to make your application
communicate with the outside world.
Each tag added to an application includes properties that uniquely identify it, and link it with the other tags in the system
to allow communication to occur. VTS stores all these attributes in a proprietary format that is under revision control.

Whenever you create a new tag, VTS generates a unique tag instance, based on the structure of the chosen type.

Tag Browser
The Browser button in the Configuration Toolbox, launches the Tag Browser dialog - one of the most frequently used
tools in VTS.

216 • How to Build an Application Developer's Guide (part 1)

The Tag Browser is used to create, view, draw and manage the tags that have been configured for your application.

Productivity Tip 1: To quickly review the I/O address and the value of all tags of a certain type (for example, Analog
Status tags in a named area), check Show Children and filter the Tag Browser's display. As of VTS 10.1.06, the display
grid includes columns for both I/O addresses and Values. See: Searching and Filtering the Tag List.

Tip 2: You can select more than one tag at a time from the list. Use the Shift and Control keys while selecting, just as
you would when selecting several files in Windows Explorer™. The following operations are available for a selection of
more than one tag: Cut/Copy (optionally followed by Paste), Enable/Disable, Delete.

The tag browser is designed to work much like Windows Explorer, where tag structures are similar to folders and files
on your workstation. See: Parent-Child Tag Structures.
Every VTS application comes pre-configured with several tags that are used for basic functionality. These include Font
Style tags, Alarm Priority tags, and Notebook tags. VTScada-based applications will have even more. Therefore, when
you launch the Tag Browser for the first time, you will see these tags in the list. An example is displayed below.

The top bar displays the context of the tag you are viewing, within a tag structure. It works in much the same way as the
address bar in Windows Explorer:

Developer's Guide (part 1) How to Build an Application • 217

Just as Windows Explorer shows only the files and directories within the folder that is named in the address bar, the Tag
Browser will show only parent and child tags within the structure shown in its address bar. The Home button will return
the display to the top level.
Below the address bar are various filters that can be applied to limit the display to tags of immediate interest.
The window down the left side ("tree view window") will display all of the parent tags in your application. This is
analogous to the folder view in Windows Explorer. You can close or open the tree view window by double clicking on
the vertical bar that separates it from the main tag window.

The window to the right displays parent and child tags that can be found within the currently selected parent. Parent tags
within this list are displayed using a green font. You can right-click on any tag to open a context menu of functions that
apply to a tag, such as Delete, Properties, Copy, etc.
Instructions for using the Tag Browser can be found in the following topics:
• Add a new tag.
• Copy an existing tag.
• Modify the properties of an existing tag.
• Delete a tag.
• Create a parent-child tag structure.
• Searching and Filtering the Tag List.
• See also, Import and Export Tags.

218 • How to Build an Application Developer's Guide (part 1)

Some users of earlier VTS versions may expect to be able to draw a tag by double-clicking on it. The double-click is
now associated with parent tags and opens that tag to view its child tags. A double-click on a child tag will open its
properties dialog.
To draw a tag, select it and then click the Draw button, or right-click the tag and select Draw from the context menu.

Icons That Describe Tags

Many of the tags shown in the browser will have symbols drawn in front of them. These tell you something about how
the tags were created. You can hover over each symbol in the browser to see a tool-tip definition.

Symbol Meaning
Has child tags. This is a parent tag.

Any tag instance that you have created. Not one of the built-in tags,
and not generated automatically like the child tags of a MultiSmart
Station.
An automatically-generated tag, in which you have over-ridden one
or more of the default parameter values.
Disabled. The start condition evaluates to False, or you have
explicitly disabled the tag. Visible only when the Show Disabled
option is checked.
Related Topic: Tag Field Colors.

Searching and Filtering the Tag List

In even the smallest application, the tag list will soon become long. For this reason, it is important to know how to filter
the list so that you can find the tags you are interested in.

Note: If you are using parent-child tag structures, only the immediate child tags of the currently selected parent will be
shown unless you check the Show Children option. Regardless of whether you have organized your tags into hierarchical
structures, the \ entry is considered the grandparent of all other tags.

The following filters are available. You may use any or all of these filters in combination.
If no tags match the filter parameters, or if you have used the address bar or tree window to browse to a tag that has no
child tags, then the main browser window will display the text, "There are no tags that match the current selection".

Developer's Guide (part 1) How to Build an Application • 219

When a filter is in use (except Show Children and Show Disabled), these controls are shown against an orange
background.

Ways to filter the display:

• Tag Structure. When a parent tag is selected, the list is automatically filtered to show only the child tags of that
parent. If Show Children is checked, all children and grand children are include, otherwise only the immediate
children of the current parent are shown.
• Text Filter. You may use wildcards (*) to limit the display to only those tags matching a given pattern. (ex:
Alarm*). Note that the text filter may be applied to names, or to any field within the tag's configuration. For
example, the following pattern will find all of the tags that use engineering units of RPM:
• Show Children. Includes all children and grand-children from the currently selected parent.
• Show Disabled. Includes inactive tags. These are tags whose start condition evaluates to false and tags that have
been explicitly disabled. (Disabling a tag sets the start condition explicitly to False.)
• Areas Filter. Select one area at a time to view tags that were configured with the matching area property.
• Types Filter. Select one type at a time to view only the tags of that type. This filter also affect the New Tag
selection by pre-selecting the same type from the list. Use care if you create a tag of a type other than the one being
filtered for - it will be created normally, but won't be visible in the browser until you change or remove the type
filter.

Note: You can direct VTS to restrict the loading of tags that belong to a certain area on specific workstations, and
therefore prevent them from appearing in the Tag Browser. See: Filtering Application Data.

Filter the List of Tags by Name or Value

The Tag Browser's Search field can be used to filter the tag list according to the search string you enter. This filter can
search for names, or it can search for matching text in any tag configuration field.

Note: All filters work together. Be sure that each is set correctly to ensure that you locate the tag(s) for which you are
searching.

By default, when you first run a VTS application, the Search field displays an asterisk (*) indicating that all tags should
be displayed. A search string can consist of the full name of the tag, or parts of the name of the tag combined with the
asterisk (*) wild card character. You can use the asterisk wild card to stand for any combination of characters (i.e. * = 0
or more of). For example:

A* Return all tag names that contain an "A" as their first character (e.g.
"AnalogFont" or "AlarmPriority0").

*A Return all tag names that contain an "A" as their last character (e.g.
"WellA" or "Soda").

*A* Return all tag names that contain one or more instances of the letter
"A" (e.g. "AnalogFont" or "LabelFont").

A Varies. If there is an exact match, then only that match is returned. If

there is no exact match, then wildcards are automatically added to
make this equivalent to *A*.

220 • How to Build an Application Developer's Guide (part 1)

* Return all tags, regardless as to their name.

Note: The Tag Browser's Search field is not case sensitive (i.e. entering "A*" is the same as entering "a*").

When you have finished searching for tags, you should reset the Search field by deleting all text or by entering an
asterisk (*), indicating that all tags should be displayed.

Filter the List of Tags by Type

The Tag Browser's Types drop-down list can be used to filter the tag list to display tags of a specific type.

Note: The Types drop-down list works with the Search field and Areas drop-down list to filter the tag list. Be sure that
each of these fields and drop-down lists are set correctly to ensure that you locate the tag(s) for which you are searching.

When you first run a VTS application, the Types drop-down list is set to "All", indicating that all types of tag should be
displayed. You may select a type or a tag group by which to filter the tag list. Types are listed in alphabetical order in the
Types drop-down list, followed by tag groups listed in alphabetical order (see Tag Groups).
In the example shown below, "Alarm Priority" has been selected in the Types drop-down list, and the tag list displays all
the Alarm Priority tags for this application.

Once you've finished searching for tags of a specific type, or belonging to a specific tag group, you should reset the
Types drop-down list by selecting "All", indicating that all tags should be displayed. The orange highlight warns you that
a filter is still in effect.

Filter the List of Tags by Area

The Tag Browser's Areas drop-down list can be used to filter the tag list to display tags that have been configured with a
specific area property.

Note: The Areas drop-down list works with the Search field and the Types drop-down list to filter the tag list. Be sure
that each of these fields and drop-down lists are set correctly to ensure that you locate the tag(s) for which you are
searching.

By default, when you first run a VTS application, the Areas drop-down list is set to "All", indicating that all types should
be displayed. You may select an area by which to filter the tag list.

Developer's Guide (part 1) How to Build an Application • 221

In the example shown below, "Larger Region" has been selected in the Areas drop-down list, and the tag list displays
only the tags that have been configured with "Larger Region" for their Area property.

Once you've finished searching for tags that have been configured with a specific area, you should reset the Areas drop-
down list by selecting "All", indicating that all tags should be displayed.
Further information may be found in: Filtering Application Data.

Fundamental Tag Features

This section describes the properties that are common to all tags. Detailed descriptions of the many different types, and
instructions for working with those tags, can be found in later sections of this chapter.

Tag Properties Folders

It is easy to add new tags and configure their attributes using tag properties folders. The term “tag properties folder”
refers to the set of dialog boxes that provide access to each tag instance’s properties. Each field found in a tag properties
folder matches a field in the corresponding type definition. By using a tag’s properties folder, you can add to or change
its configuration while your application continues to run.
You can also change tag properties by exporting the tag database for external editing, and then import the database back
into VTS.
All tag properties folders share a few common elements, regardless of the varying fields for each type of tag. The
following figure identifies some of these common elements and behaviors.

222 • How to Build an Application Developer's Guide (part 1)

Other common elements found on tag properties folders include radio buttons, checkboxes, and lists.
The tag properties folder for each type is described in the sections beginning with Tag Types Referenced by Category.
This information will assist you in correctly configuring your tags.

Tag Identification
Every tag has two forms of identification: A short, human-friendly name that you give it, and unique ID value that is
automatically generated. Throughout this help guide, the word "name" will be used, rather than "short name" or
"friendly name". In the places where the text refers to the unique ID, the term "unique ID" will be used. If you want to
see the unique ID value, hover the cursor over the name field in the tag browser:

Developer's Guide (part 1) How to Build an Application • 223

VTS uses the tag's unique ID for logging, and for animations on a page. The name is used for references between tags
and for anything in the user interface that needs to identify a tag.
A tag's unique ID value can never change, but you may change the name at any time. Since logging, alarms, page
animations, and more, are all tied to the unique ID value, they are not be affected by any change in the tag's name. This
includes moving a tag from one location in the tag hierarchy to another (which is, in effect, simply a change of name).

Note: Any expressions or relationships between tags will need to be updated after a change of tag name since these are
based on the name parameter rather than the unique ID. See: Move and Rename Tags.

When tags are organized into a hierarchy, the name includes the parent tags. For example, if Pump1 and Pump2 both use
an Analog Status tag to display the flow rate, you are free to call both of those Analog Status tags, "Flow". VTS will
know that they aren't the same tag because a) the unique ID values will be different and b) the full names will differ:
"Pump1\Flow" versus "Pump2\Flow".

Note1: If your application was originally created in a version of VTS prior to 10.2, the unique ID will be the same as the
original tag name.

Note 2: VTS Programmers should note that there is yet another name: the Tag ID. This does not appear in the graphical
interface, but may be used in code. For example, the Tag ID may be used as an equipment serial number. You can edit
the value in this field by exporting the tag database to Excel™ or Access™.

See also:
Move and Rename Tags.
Use a Tag’s Value in an Expression.

Licensing
The version of VTS that you are running has been purchased with certain licensing restrictions that limit the number of
tags that may run at the same time on one computer. The number of tags for which your VTS version is licensed can be
found in the About VTS dialog that is opened when you click the About VTS button on the VAM (see: Learn About
Your Copy of VTS).
The tag limit counts all tags in all running applications. Disabled tags don't count. For example, if your version of VTS is
licensed for 10,000 tags, the combined total number of tags in all applications running at the same time is limited to
10,000 tags. A quick way to discover the total number of tags currently used in your application is to open the Tag
Browser and read its title bar. The Tag Browser's title bar lists the number of tags being displayed (according to the Type

224 • How to Build an Application Developer's Guide (part 1)

and Area filtering), against the total number of tags in this and other running applications. For example, in the image
below, you are currently viewing 57 of 109 tags that are currently running in all open applications.

Constant, Expression or Tag

When configuring a tag, you will find many properties that offer three ways to set the associated value: Constant,
Expression or Tag. For example, when configuring an Alarm tag, you will have the option of setting a delay on the
alarm. Depending on your choice of constant, expression or tag, the configuration parameter will look like one of the
following examples:

The following is provided as a guide to help you choose the option best suited to your application.

Constant
Constant should be selected for any parameter whose value rarely, if ever, changes. A developer can return to the tag’s
configuration screen to edit the value, but otherwise ‘constant’ means ‘unchanging’. Select this option for all values that
should remain as you configured them.

Expression
Expressions are snippets of the VTS programming language that you can write to create values that change with
changing conditions. For example, you could create an expression that sets this parameter to the average of 3 or more
other tag values. Another expression might set a value of 0 when another tag’s value is below 50%, then set 100 when
the other tag’s value rises above 50%.
Select this option when you want the parameter’s value to be based on a formula, usually referencing other tag’s values.

The button opens the expression editor. The button clears the current expression. The word “: Invalid” means
either that no expression has been provided, or that the result of a calculation is meaningless, such as dividing by zero.
For a guide to the VTS expression language, see: Creating Expressions.
See also: Snapshot Expressions, which are used when configuring tag hierarchies.

Tag
Many parameters can take their value directly from another tag. That other tag might be an operator control for setting a
value, such as an alarm set point or delay. The selected tag need not be one for which you have provided an operator
input – any tag with a value can be used to set the parameter’s value.
Select this option when you want to have a parameter’s value match another tag’s value, such as when you want to
provide an operator with control over a value.

Developer's Guide (part 1) How to Build an Application • 225

The tag browser button will open the tag browser, from which you can select or create a tag whose value will be
used. The button clears the currently selected tag.

The link button is used with parent-child tag structures to control how the selected tag fits into the overall structure.
For more detail, see Parent-Child Tag Structures.

Tag Drawing Methods and Images

The data from your tags can be represented on-screen in many different ways. Animated gauges, level indicators,
numeric displays, etc. can be combined with static elements such as tanks and pipes to create an intuitive operator
interface.

Control elements that resemble those from physical control panels, such as dials, buttons and sliders can be used to make
an interface that operators will immediately recognize.
Complete coverage of the various tag drawing methods can be found beginning with the topic: Drawing Tags.

Confirmation Prompts for Output Tags

Many of the drawing methods for output tags include an option to require the operator to confirm that they intended to
write a value. For analog tags, the confirmation text will include the new value. For example, "Are you sure you want to
set the value to 1500?".
For some digital tags, the message displayed will be more or less meaningful depending on how you configure the tag.
For example, the Digital Control tag includes the fields "On Text" and "Off Text". Selector Switches provide a label for
each position. If you provide a descriptive word for the control action matching each output state ("On", "Open",
"Start"), then that word will appear in the confirmation prompt. For tags that do not have this option, and for those with
the option that you leave unconfigured, a generic message will be displayed.

226 • How to Build an Application Developer's Guide (part 1)

Tag Configuration Rules and Recommendations
The following are rules and recommendations that should be observed when you are creating tags for your applications.

Plan your tag structures carefully.

There are considerable advantages to be gained by grouping tags according to their usage in your application. Whether it
be by state, zone, station, mechanism or controller, there is always a logical way to organize your tags. Since you cannot
move tags into new parent groupings later, it is essential that the application be planned well before the tags are created.
See: Parent-Child Tag Structures.

Tag names need not be unique

The full name of a tag must be unique, but you may have many tags named "Flow" or "Well", so long as they are
children of different parents. ("Pump1\Flow" and "Pump2\Flow").
Each tag is fully identified by two mechanisms: its unique ID and by the combination of its name and its place in the tag
structure.

Tag names must be no longer than 64 characters in length

This rule refers only to the tag's immediate name, not its full name, which may include a lengthy list of parent tags.

Full tag names must be no longer than 253 characters in length

This rule refers to the tag's full name, which may include a lengthy list of parent tags.

Tag names must not duplicate other named items

A tag may not be named "Value" or "Area" since those are the names of tag properties.
Tags, pages, libraries and drawing methods may not share a name.
Tag names may not duplicate Type names - you cannot name a tag "Calculation" or "Analog Status".
Since it can be difficult to determine what names are used by VTS, and since new versions can be expected to introduce
more names that will be reserved for VTS, then the safest option is to adopt a naming convention that will always be
unique to your application. For example, start every name with "MA_" (for My Application).

Tag names must consist of valid characters

When configuring tag names, you must use valid characters.
Valid tag name characters include:
• Any combination of alphanumeric characters (i.e. A through Z, and/or 0 through 9)
• Spaces, except at the beginning or end of the name.
• Period (.)
• Symbols other than those listed below (e.g. you may use the number hatch (#), and underscore (_) characters in tag
names)

Invalid tag name characters consist of:

Tag names cannot include any of the following characters:

Developer's Guide (part 1) How to Build an Application • 227

 • Backslash (\ used to separate parent names) • Forward slash ( / )
• Colon ( : ) • Asterisk ( * )
• Question mark ( ? ) • Double quotes ( " )
• Less than ( < ) • Greater than ( > )
• Vertical bar ( | ) • Leading spaces
• Trailing spaces • Closing bracket ( ] )

Tag names cannot be purely numeric.

"57" is not a valid tag name but "Station57" is. An interesting side effect of this rule is that you cannot name a tag "E1"
or similar, since this is a valid numeric expression: ("E1" == "0E1" == "zero exponent one").
In the event that you have entered an invalid tag name, VTS will notify you with a warning dialog, and will clear the tag
properties folder's Name field for the entry of a valid tag name.

Tag names should follow a consistent and meaningful naming convention

The Description field is available to provide extra information about a tag, but it is helpful to always use names that are
meaningful in the context of the application.

Use the Area Property to Help You Sort Tags

The Area property, although not required, is highly recommended. Configuring your tags with areas will enable you to
filter your tags by area in the Tag Browser. This will help you to locate tags quickly, especially in larger applications
where there are hundreds of tags.
If you are using child tags, note that their area will automatically be the same as the nearest parent with an explicitly
configured area. You can override this if a child tag should have a different area value than its parent.

For customers whose VTS license includes the Alarm Dialer option: Roster tags, which control the list of operators to be
contacted in the event of an alarm, are linked to tag areas. That is, a given roster will be used for all the alarms having the
matching area property and for no other alarms.

Areas can be used to reduce the amount of memory required to run an application or to stay below licensing restrictions
by allowing you to exclude certain tags from being loaded into your application at startup, on the basis of the area
configured for their Area property. This is done using the [AREAS] section of the Settings.Startup configuration file for
your application. See: Tag Area Filtering.

Areas can also be associated with user groups to restrict configuration access to part of an application when users are
connecting over the internet from a VTS Internet Client (VIC).

Tags Should Include a Clear Description

In addition to a consistent and meaningful naming convention, tags should be given a clear description that will assist
you and your users in determining the purpose of the tag and the equipment process it represents. This is especially
important when tag names are abbreviated or follow a naming convention that is not easily interpreted.
In some places in VTS (such as the Alarm Page), the tag's description will be displayed instead of the name.

228 • How to Build an Application Developer's Guide (part 1)

Tag Change History
Every change to a tag's configuration is recorded. This allows you to determine exactly who changed a field, and when
the change was made. You can easily spot fields that have been changed during the current editing session, as the
background color of changed fields will turn green. The background highlight lasts only for as long as you are editing the
configuration folder – each time you open a tag's configuration folder, the fields will return to white – waiting for fresh
changes.

Before editing.

After editing.

If security has not yet been enabled, no user name will show in the history. Otherwise, the name of the user logged in at
the time the change was made, will be used.

Changes made to any field will show the latest modification date and the identity of the user logged in at the time (if
security is enabled).

Developer's Guide (part 1) How to Build an Application • 229

Useful hint: You can use the date of the last modification to look up other changes made at the same time in the version
history. (See: Review Versions – The Version Log) This will allow you to quickly find any other changes that the
operator may have made at or near the same time.

Changes to tag configuration that result from importing a tag file will be attributed to the user who imports that tag file,
and therefore assumes responsibility for ensuring that what is being imported is correct. (See: Import and Export Tags.)

The format of the displayed tooltip is controlled by application properties.

Tag Field Colors

Tag fields in the configuration panel will change color to provide more information about the type of change that has
occurred in them. The following colors are used:

Field Color Meaning

White Unchanged during current editing session. No over-ride or
snapshot expression.
Green Found in user-created tags. The parameter value has been
changed from its previous (or default) value.
A special case is if the parameter's original value came from
code built into the tag type's definition. In that case the
color orange will be used...
Orange A parameter value that was originally defined through
code has been overridden. This is most often seen when

230 • How to Build an Application Developer's Guide (part 1)

 overriding the area parameter of a child tag.
Pale Yellow Used in the Area field of a child tag if you have provided a
new value rather than use the Area inherited from the
parent tag.
Blue Blue indicates that the value is calculated from a snapshot
expression.
Red The field's current value is outside the allowed range of
values for this field.

Related Topics: Calculate Tag Configuration Values - Snapshot Expressions, Tag Configuration Overrides.

Tag Field Right-Click Menus

The context menu that appears when you right-click on a tag's configuration field will vary according to what the field is
and how it was created.

Name
Add Start Condition
Remove Start Condition

Options for the tag name field are limited to start conditions. See: Conditional Starts and Disabled Tags.

Other fields, no code to override.

Add (Edit) Snapshot Expression
Remove Snapshot Expression

If the field's value is not determined by code (that is, most fields) then the context menu allows you to add or remove a
snapshot expression. See: Calculate Tag Configuration Values - Snapshot Expressions.

Other fields with code to override

Add Override (Remove Override)
Add (Edit) Snapshot Expression
Remove Snapshot Expression

Area fields in child tags are coded to take their value from the nearest parent with a defined Area. Simply changing the
value overrides the code, but the Add Override option allows you to lock the current value in place, overriding the code
with the value currently calculated by that code.
If an Override has been added using this menu, the next right-click will show the option, Remove Override. You can
select this to allow the field to take its value from the code within the tag.
Calculated fields are used extensively in the children of Station Tags.

Developer's Guide (part 1) How to Build an Application • 231

See: Tag Configuration Overrides.

Tag Area Filtering and Alarm Area Filtering

Some of the applications you may create will consist of large numbers of tags. There may be circumstances under which
you may wish to prevent certain groups of tags from loading at startup to reduce the amount of memory required to run
the application, or you might require that only certain groups of tags are loaded on specific workstations. You can use
this functionality to ensure that you do not exceed the maximum number of tags permitted for your VTS application due
to licensing restrictions (please refer to Tag Licensing). In such situations, VTS makes it possible to disable some tags,
preventing them from loading and consuming unnecessary amounts of memory. This process is referred to as tag area
filtering.
See: Tag Area Filtering
You may wish to filter Alarm tags so that specific alarms load on specific workstations. The typical purpose for this
functionality is when you have a remote application installation that has one common configuration for all workstations,
but on some machines you wish to see a subset of the alarms (for example, if you wished to restrict alarms to specific
geographical areas). This process of alarm area filtering restricts the alarm displays and sounds to only those areas that
have been enabled for the relevant machine.
The area that is being filtered is the normal Area property of the tag.
See: Alarm Area Filtering.

VTScada Tags
Note that the following tags exist only in VTScada-based applications.

Data Flow RTU Driver Tags

MPE SC Series Station Tags
MPE Duplexer Station Tags
MultiSmart Station Tags
Polling Driver Tags
Pulse Input Tags

Common Tag Properties

Many of the standard VTS types have similar or identical tabs on their tag properties folders. For example, all tags have
an ID tab that contains properties that help to identify the tag and make it unique from all other tags in the system. All
input and output tags have an I/O tab where you can specify the parameters that associate the tag with an I/O device.
The following topics describe the properties that are commonly seen in VTS tag configuration folders.

The ID Tab
Nearly every tag’s configuration panel will have an ID tab that includes the same four elements. All tags of all types
must be identified and all will share the same identifying characteristics: name, area and description. The fourth element,
Help Search Key, is provided for those who have created their own compiled help files and wish to link specific tags to
topics within that file. (See: Integrating Custom Help Files into VTS.)

232 • How to Build an Application Developer's Guide (part 1)

Three types: Report tags, Context tags, and Data Flow RTU driver tags, will include an extra field in their ID tab. See the
descriptions of those tags for more information.

Name
Tag names are discussed at length in the topic Tag Configuration Rules and Recommendations. If the tag is a child of
another tag, the parent names will be displayed in a separate area before the name field. See: Parent-Child Tag
Structures.

You may right-click on the tag's name to add or remove a conditional start expression.

See: Conditional Starts.

Area
The area field is used to group similar tags together. By defining an area, you make it possible to:
• Filter for particular tag groups when searching in the tag browser
• Link dial-out alarm rosters to Alarm tags having a particular area
• Limit the number of tags loaded upon startup.
• Filter the alarm display to show only certain areas.
• Filter tag selection by area when building reports
When working with Parent-Child tag structures, the area property of all child tags will automatically match the
configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field
background will turn orange to indicate that you have applied an override.

Developer's Guide (part 1) How to Build an Application • 233

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags in
order to group all the tags representing the equipment processes installed at each I/O device. You might also consider
naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the
I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag,
such as System or Communications.

The area name may be up to 256 characters in length. You may define as many areas as you wish and you may leave the
area blank for some tags (note that for Modem tags that are to be used with the alarm dialer system, it is actually required
that the area field be left blank).
To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-
down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second
area being created.
There is no tool to remove an area name from VTS since such a tool is unnecessary. An area definition will exist as long
as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description
Tag names tend to be brief. The description field allows you to give each tag a human-friendly note describing its
purpose. While not mandatory, the description is highly recommended.
Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when
the operator holds the pointer over the tag’s drawing method.
The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed
on-screen.

Help Search Key

Used only by those who have developed their own Compiled Help Module (CHM) documentation (such as this guide).
To see this system in action, open the ID tab of any tag’s configuration panel and press the F1 key. This guide will
immediately open to display information about that screen because a link exists between the topic in this guide and that
screen.
When a user-defined help search key is defined for a tag, a Help button will appear between the tag properties folder's
OK and Cancel buttons the next time the tag properties folder is opened. Further, when any of the tag's drawing methods
is right-clicked, selecting the Help shortcut menu option will open the assigned help topic.
In addition to creating the help file, defining a numeric topic id and setting that id as the Help Search Key, you must also
tell your application how to find your .CHM file. See the topic, Integrating Custom Help Files into VTS for a description
of how to do this.

Alarm Tab and Alarm Setup Tab

There are three common versions of the alarm or alarm setup tab. In the Analog Input and Digital Input tags, the alarm
tab displays the list of Alarm tags that are attached, and provides a shortcut to add or remove Alarm tags. In Analog
Status and Digital Status tags, this same tab has the label "External Alarms" in order to distinguish the attached Alarm
tags from the built-in alarms.
Analog Status, Pump Status and Digital Status tags all have an alarm tab or alarm setup tab, which is used to configure
the built-in alarm for that type. These three example images show the differences between the versions:

234 • How to Build an Application Developer's Guide (part 1)

What the alarm tabs and the alarm setup tabs have in common is that, once fully configured, the value of the tag will be
monitored by the alarm manager, and an alarm will be triggered when values go past a given set point.
Note that, Alarm tags created using the Add button in another tag's alarm tab will be created as children of that tag.

Complete details on configuring the alarm tab for any type are provided with the description of that type in this guide.

I/O Tab
All of the input and output, status and control tags will have an I/O tab in their tag properties folder.
The I/O tab consists of properties used to identify and establish a connection to the communication driver tag being used
to communicate with your physical I/O device. This is accomplished by identifying the communication driver tag, the
address at which this basic I/O tag is to read or write data, and the rate at which the I/O device should be scanned for
data. A manual data option is provided to allow you to set a constant value for the tag, independent of any actual I/O, for
configuration and testing purposes.
Scan Interval. In general, it is desirable to limit the number of different scan intervals for a particular IODevice, to
optimize the reading to a minimal number of blocks and improve overall system update performance.
Typical I/O tabs for both Analog Input and Digital Input tags:

Digital Input tags (including Digital Status and Pump Status tags) can have single or double bit addresses. Status tags
(analog and digital) will include extra configuration options.

Developer's Guide (part 1) How to Build an Application • 235

Logger Tab
Input and output types will have a Logger tab on their tag properties folder. For tags that do not have a built-in
connection to a Historian, you must attached a Logger tag if you want to store a record of the tag's values.
Status and control tags have built-in connections to a Historian tag and therefore do not have a Logger tag since there are
no user-configurable settings.
If a Logger tag is being used, only one may be associated with any given tag. If that tag has a built-in connection to a
Historian, you should not also attach a Logger tag. If you require multiple loggers with different logging rates, please
see: Using Function Tags to Create Multiple Data Logs of an I/O Tag.
Typical Logger tab:

Historian Tab
Status, Logger and some other types will have a Historian tab on their tag properties folder. This is used to select the
particular Historian database that will be used to store data recorded from the current tag. See: Historian Tag for
information about the configuration and use of Historians.
Typical Historian tab:

Historians versus Loggers

Loggers control when data is recorded. Historians control where the recorded data is stored. Every Logger tag must use a
Historian tag in order to save logged data.
A single Historian tag can be used by all the Loggers in an application, but a unique logger must be used for every tag
whose value is to be recorded.

236 • How to Build an Application Developer's Guide (part 1)

Some tags, such as the Analog Input, do not have internal logging defined and therefore must have an external Logger
tag attached if the data is to be stored. Other tags, such as the Analog Status, do have internal logging and therefore need
only a Historian tag attached, to control which database the data is to be logged to.

Merit Tab and Quality Tab

Many types of tag include a Merit tab or Quality tab on their tag properties folder. “Merit” and “Quality” are two names
for what is essentially the same tab. For input and status types, the screen will look like the following examples:

For output and control types, there is no "Quality Based On" field.

Questionable Data
Questionable Data is a means of indicating that the data being reported by a tag might not be accurate. By default, the
Questionable Data checkbox is selected for every new tag you create. This field is available for your convenience when
commissioning a new system. Before you have verified the accuracy of an I/O tag, the questionable data flag will be set
and a question mark will appear on the tag’s drawing methods.
After you have verified the accuracy of each tag’s data, you can un-check its questionable data marker, thereby keeping
track of which tags you have verified and which you haven’t.

Developer's Guide (part 1) How to Build an Application • 237

Quality Based On
The Quality Based On field can be tied to a tag that monitors driver communication errors, a register in the PLC or RTU,
or other indication of system health. The tag you are configuring will use that value to set an internal variable named
QualityIssue. You may test this value in an expression: [TagName]\QualityIssue.
QualityIssue will be a 0 or 1. "Good Quality" is defined as a value of "0 or Invalid" and "Bad Quality" is defined as any
valid, non-zero value.
VTS programmers can create container tags that make use of the quality value of contributors, which are either Analog
Inputs or Digital Inputs.

Security Privilege
A Security Privilege may be applied to any tag that can write data. Using the drop-down list, you can select an existing
application-specific privilege that will restrict who is allowed to use this tag to write data. Once a value is set, users will
need to have that privilege granted to them before they can send a signal to an I/O device.
Application privileges are added using the Administrative Settings security dialog. Please see: Add Application
Privileges Using the Administrative Settings Dialog".

Order Tab
When you add a Status or Control tag (analog or digital) to your application, and associate this new tag with a Polling
driver, VTScada automatically adds a graphic representation of the tag to the I/O device's station dialog (that is, the
dialog that is displayed when the associated site symbol is clicked on the Overview page).
Station dialogs have four columns, with each column displaying I/O of a specific type. The first column on the left
displays graphics for the Analog Status tags associated with this I/O device at the top of the column, and graphics for the
Pulse Input tags associated with this I/O device at the bottom of the column. The second column displays Digital Status
tags at the top of the column, and Pump Status tags at the bottom of the column. The third and fourth columns display
output tags in corresponding pairs (e.g. On and Off). An example of a station dialog is displayed below.

Although you cannot change the order in which the columns appear, you can change the order in which the I/O appear
within their section of a given column using the Display Order property on the Order tab.
When you set the Display Order property for a tag, the number selected sets the tag's order in its column of the station
dialog in relationship to other tags of the same type (for example, the order of this Analog Status tag in relation to the
other Analog Status tags at the top of the first column).
If you do not specify a display order, tags will appear in their designated column in the order in which they were created.

238 • How to Build an Application Developer's Guide (part 1)

For further information, please see: "Station Pages (VTScada)".

Owner Tab
Input and Output tags, both analog and digital, have an Owner tab on their tag properties folder.
VTS supports the concept of owner/contributor (also referred to as container/contributor) relationships among tags,
where multiple contributor tags can supply their values to an owner or container tag. An owner tag's value is determined
by a mathematic function of the values of its contributor tags. An example of an owner/contributor relationship might be
at a power generation station, where the owner tag would calculate the overall power output for the entire station based
on the value of its many contributor tags. Within a contributor tag, you can select the owner tag and specify how the
contributor’s value should be used.

Note: You must write your own Owner tag. This requires a solid knowledge of VTS programming techniques. Reference
information can be found in Programming Custom Tag Types.

Owner
The Owner field can be used to specify a tag to which this contributor should supply its data. Establishing an
owner/contributor relationship also allows standard tags to monitor custom tags without prior knowledge of the number
of each type required.
The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual
data value, to questionable data, according to the configuration of the checkboxes appearing beneath the Owner field.
These checkboxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Record Data Quality

An owner tag may keep track of the quality of the data for each of its contributors. This requires the owner to have a
variable (an array) named DataQuality. The contributor will then pass it's quality value to an element of that array.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the
Record Tag Validity checkbox enables you (as the programmer of an owner tag) to increment the owner tag's count of
the number of tags that are contributing questionable data by 1, and decrement this count by 1 when this contributor is
not supplying questionable data.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values),
rather than reading data from their I/O device. When selected, the Record Use of Manual Data checkbox enables you to
increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been
provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack.
Priority checkbox causes the owner tag to keep track of the priority of the contributor's active alarm (or records an
Invalid if the contributor is not currently in an alarm state). Selecting the Set Active/Unack. Priority checkbox also
causes the owner tag to record whether or not the alarm has been acknowledged.

Set Owner\Data(n)[…] To Value

When selected, the Set Owner\Data0[…] To Value checkbox enables you to set the value of this contributor tag as the
first element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner
tag's array elements if required.

Developer's Guide (part 1) How to Build an Application • 239

Scaling Tab
All analog I/O tags include a Scaling tab on their tag properties folder.
Sensors and other hardware typically work with a range of discrete values that are much more finely divided than
standard engineering units such as degrees. For example, a temperature sensor might report values within a working
range of 0 to 4095. Depending on the sensor’s calibration, the low end of the scale, 0, might represent 32deg. At the high
end of the scale, 4095 might represent 200deg. Given these points, and assuming a linear relationship, one can then
calculate the actual temperature indicated by any value output from the sensor.
Working the other way, one can also calculate the equipment value required when an output tag is used as set point.

The Engineering Units property of the I/O tab is used to identify the unit value associated with the scaled value.

Script Tab
VTS includes a specialized standard type of tag called a Script tag. Script tags reference a script within a module, and
execute the code when the value of the associated tag changes. Script tags can be associated with this tag using the Script
tab. (Script tags and their properties are described in Script Tags).

Script Contributors
The Script Contributors list identifies the name(s) and description(s) of the existing Script tag(s) that will execute a script
based on the value of this tag (Script tags and their properties are described in Script Tags). The associated Add button
and Delete button may be used to modify the Script Contributors list.

Note: Any Script tags identified in the Script Contributors list are not properties in this tag; rather, this tag is a property
of the Script tag(s), as identified in the Script tag's "In Tag Scope" property (see Script Tag Properties: Execute Tab).

Add
Opens the Tag Browser so that you can select an existing, or create a new Script tag to monitor the value of this tag.
Information on the configuration of Script tags can be found in Script Tags.

Delete

240 • How to Build an Application Developer's Guide (part 1)

The Delete button enables you to disassociate a selected Script tag from this tag. The Script tag is not deleted by this
operation, and can be associated with another tag if you so choose.

Address Select
I/O tags that have been configured to use the SNMP driver or the OPC Client driver will have access to an Address
Select dialog through a button on the I/O tab of their configuration dialog.

Example of an Analog Control showing the MIB button, visible only after an SNMP driver has been selected as the I/O
device.

For a full discussion of how the MIB button can help you to build an SNMP address, please see the topic, SNMP
Addressing. OPC addresses are described in OPC Client Driver Addressing.

Table of Type Characteristics

Group Log-enabled
Name Name in exported tables Context type memberships variables
Port Tags
SerialPort SerialPort *Port Numeric, Ports, Value (integer)
Trenders
TCP/IP Port TCPIPPort *Port Numeric, Ports, Value (integer)
Trenders
UDP/IP Port UDPIPPort *Port Numeric, Ports, Value (integer)
Trenders
IP Network IPNetworkListener *Port Numeric Value (byte)
Listener
Driver Tags

Developer's Guide (part 1) How to Build an Application • 241

 Allen Bradley ABDriver *Driver Drivers, Numeric, *see note 1
Driver Trenders, Loggers
CalAmp DataRadioDriver *Driver Drivers, Numeric, *see note 1
Diagnostic Trenders, Loggers
Driver
CIP Driver CIPENIPDriver *Driver Drivers, Numeric, *see note 1
Trenders, Loggers
Data Flow DataFlow *Driver Numeric, Digitals, *see note 1
Driver VTScadaDriver,
Trenders, Loggers
DDE Driver DDEDriver *Driver Drivers, Numeric, *see note 1
Trenders, Loggers
DNP3 Driver DNP3Driver *Driver Drivers, Numeric, *see note 1
Trenders, Loggers
DriverMUX DriverMUX *Driver Drivers, Numeric, *see note 1
Trenders, Loggers
MDS MDSDriver *Driver Drivers, Numeric, *see note 1
Diagnostic Trenders, Loggers
Driver
Modicon ModiconDriver *Driver Drivers, Numeric, *see note 1
Driver Trenders, Loggers
Omron Host OmronDriver *Driver Drivers, Numeric, *see note 1
Link Driver Trenders, Loggers
OPC Client OPCClientDriver *Driver Drivers, Numeric, *see note 1
Driver Trenders, Loggers
OPC Server OPCServerSetup *Driver Drivers, Numeric, *see note 1
Setup Trenders, Loggers
Siemens S7 SiemensS7Driver *Driver Drivers, Numeric, *see note 1
Driver Trenders, Loggers
SNMP Driver SNMPDriver *Driver Drivers, Numeric, *see note 1
Trenders, Loggers
Polling Driver PollDriver *Driver Drivers, *see note 1
VTScadaDriver,
Numeric,
Trenders, Loggers
Workstation WorkstationStatusDriver *Driver Drivers, Numeric, *see note 1
Driver Trenders
Input and Input/Output Tags
Analog Input AnalogInput *Numeric Analogs, Numeric, Value (floating
Trenders point)
Analog Status AnalogStatus *Numeric Analogs, Numeric, Value (floating
Trenders point)

242 • How to Build an Application Developer's Guide (part 1)

 Digital Input DigitalInput *Numeric Digitals, Numeric, Value (byte)
Trenders
Digital Status DigitalStatus *Numeric Digitals, Numeric, Value (byte)
Trenders
Pulse Input PulseInput *Numeric Numeric, Analog Value (integer)
Pump Status Pump *Numeric Digitals, Numeric, Value (byte)
Trenders
Output Tags
Analog Control AnalogControl *Numeric Analogs, Numeric, Value (floating
Trenders, Outputs point)
Analog Output AnalogOutput *Numeric Analogs, Numeric, Value (floating
Trenders, Outputs point)
Deadband DeadbandControl *Numeric Numeric, Trenders Value (floating
Control point)
Digital Control DigitalControl *Numeric Digitals, Numeric, Value (byte)
Trenders, Outputs
Digital Output DigitalOutput *Numeric Digitals, Numeric, Value (byte)
Trenders, Outputs
MultiWrite MultiWrite *Numeric Outputs Value (floating
point)
Selector Switch SelectorSwitch *Numeric Numeric, Trenders Value (short)
Trigger TriggerTag *Trigger Digitals, Numeric, Value (byte)
Trenders
Alarm Tags
Alarm AlarmPoint *Alarm Digitals, Numeric Value (logged by
VTS)
Alarm Priority AlarmPriority *Alarm Digitals Value (do not log)
Priority
Alarm Status AlarmStatus *Alarm Status Numeric, Trenders Value (integer)
Modem Modem *Modem Numeric Value (integer)
Roster Roster *Roster Digitals, Numeric Value (Boolean)
SMS Appliance SMSAppliance (none) Numeric Value (integer)
Logging and Reporting Tags
Historian HistorianTag *Historian Numeric (none)
Logger LogPoint *Logger Numeric (none)
Notebook Notebook *Notebook Trender Value (text)
Report Report *Report (none) Value (0 or 1)
SQL Logger SQLLoggerGroup *SQL Logger (none) (none)
Group Group

Developer's Guide (part 1) How to Build an Application • 243

 SQL Logger SQLLogger *SQL Logger Numeric Value (matches
tag being logged)
Calculation and Inquiry Tags
Analog AnalogStatistics (none) (none) Do not log.
Statistics Selected child tags
may be logged.
Calculation Calculation *Numeric Numeric, Trenders Value (floating
point)
Counter CounterTag *Numeric Analogs, Numeric, Value (integer)
Trenders
Digital DigitalStatistics (none) (none) Do not log.
Statistics Selected child tags
may be logged.
Function Function *Numeric Numeric, Trenders Value (floating
point)
History HistoryStats *Numeric Numeric, Trenders Value (floating
Statistics point)
Network Status NetworkStatus *Numeric Numeric, Digitals, Value (byte)
Trenders, Loggers
Rate of Change RateOfChangeTag *Numeric Analog, Numeric, Value (floating
Trenders point)
Totalizer TotalizerTag *Numeric Analog, Numeric, Value (floating
Trenders point)
Script Script *Script Numeric, Trenders Value (floating
point)
Station Tags
Multismart Multismart *Station Stations Value (matches
Station the driver's value)
MPE SC MPESC *Station Stations Value (matches
Station the driver's value)
MPE Duplexer MPEDuplexer *Station Stations Value (matches
Station the driver's value)
Configuration Tags
Context ContextTag Defined by (none) (none)
configuration
Font Style FontValue *Font Style (none) (none)
Realm Display RealmDisplaySetup *Realm (none) (none)
Setup Display Setup

244 • How to Build an Application Developer's Guide (part 1)

*Notes:
1: See: Communication Driver Log-Enabled Variables

Working With Tags

Instructions for adding, copying, deleting and otherwise managing tags are provided in the following topics.

Add a New Tag

See also: Add a New Child Tag.
To add a new tag to your application, follow these steps:
1. Click the Browser button in the Configuration Toolbox.
The Tag Browser will open.
1. Check the Address bar at the top of the Tag Browser. Ensure that you are adding your tag to the correct branch
of the tag structure.
Just as new files are added to the current Windows folder, new tags will be added to the currently selected
parent tag.
2. Check the currently set filters.

A filter in the tag browser won’t stop you from adding a new tag, but it may interfere with your ability to see that tag in
the list after it has been added.

3. Click the New button.

You will be prompted to select the type of tag that you want to create. If you had set a tag type filter in the Tag
Browser, this selection list will start with that same tag type.

4. Select the type and click OK.

A new tag properties folder will open.
5. Configure the tag’s properties.
Notes for every type of tag are provided in "Tag Types Referenced by Category".
6. Click the OK button.
The new tag will be referenced by its Name and Description in the Tag Browser’s tag list.
If the Auto Deploy option is selected for the application, then this operation is complete. Otherwise, this will be
considered to be a local edit until you deploy your changes.

Add a New Child Tag

A child tag is a tag like any other. Its distinguishing characteristic is that it has a parent. This provides benefits of
organization, clarity in naming, ease of application scaling, and security management. See Parent-Child Tag Structures.

There are several ways to add a tag so that it becomes a child of another.
Method 1: Right click on the tag that is to be the parent, then select New Child from the context menu. This may be
done either of the Tag Browser's windows.

Developer's Guide (part 1) How to Build an Application • 245

The Select Tag Type dialog will open and you may proceed with the creation and configuration of the new tag as
described in Add a New Tag.

Method 2: Navigate to within a parent tag structure, then click the New button.

Method 3: Copy an existing tag, then Paste as Child to create an identical instance under another tag (which either is, or
will become, a parent). You will have an opportunity to provide the new tag with its own name, and in fact must do so if
the parent already has a child with the same name as that being copied.

246 • How to Build an Application Developer's Guide (part 1)

Move and Rename Tags
Moving a tag and renaming a tag are essentially the same operation. The result is that the tag's name is changed. The
difference between the two is that renaming changes only the immediate name while moving changes the full name
including the parentage. The full name describes the tag's place in the hierarchy. The unique ID stays the same,
therefore logging, alarms, reports, drawing methods, etc. will also not be affected. Relationships that will be affected are
any that are based on the name, including any expressions you may have created. (see: Calculate Tag Configuration
Values - Snapshot Expressions.)

Examples:

Developer's Guide (part 1) How to Build an Application • 247

To rename a tag:
1. Select the tag in the Tag Browser
2. Click Properties, or right-click on the tag and select Properties from the context menu.
3. Change the text in the name field.
4. Click OK.

To move a tag:
7. Select the tag to be moved, in the Tag Browser
8. Right-click on the tag and select Cut, or click the Cut button.

... or ...
9. Right-click on a tag elsewhere in the hierarchy, under which you want to place the original tag.
10. Select Paste as Child
You will be reminded that references may need to be updated - see following notes on the effects of changing
the name.

11. Click Yes to acknowledge the message and complete the move, or No to cancel the move.

Note: The display in the tag browser may not refresh until you change it from one branch to another.

248 • How to Build an Application Developer's Guide (part 1)

Effects of changing the name:
See also: Examples and Cautions.
• Expressions that referred to the tag may need to be updated.
Expressions are created by developers, not by VTS, and use the tag's name rather than the unique ID. Changing
the name of the tag will usually mean that the expression will need to be changed to use the new name. An
exception to this is if both the referencing tag and the referenced tag are moved together. In this case, the
reference is likely to survive, but it is wise to check.
• Potential for confusion
If operators are used to seeing the tag with one name, changing its name to something else is likely to cause
confusion.

Note: If you have created a new type (tag definition), the names and locations of the tags within that hierarchy are part
of its definition. You may still move and rename tags, but the definition (and therefore all instances of the tag) must be
updated immediately after each change. A dialog will remind you of this and ask you to confirm the action before it takes
place.

Examples and Cautions

Rule: Logged history, tags drawn on a page, reports, built-in alarms and network values are all associated with the tag's
unique ID, not the name.
Example 1:
You have an Analog Status tag named AAA, which has logged history and which is drawn on a page. You delete that
tag. You then create a new Analog Status tag and name it AAA.
The new tag has a new unique ID and therefore nothing that was associated with the old tag's unique ID will be
associated with the new tag's ID. This may surprise anyone who used older versions of VTS where tags were identified
only by their name.

Example 2:
You have created a new type of tag, ValveType. ValveType was created using two tags: a parent Context tag (Valve1 in
this example), and a child Analog Status tag named Flow.

You move Flow from Valve1 into WaterPipe by doing a cut and paste operation.
When asked whether you want to update type ValveType, you decide upon "No".

Developer's Guide (part 1) How to Build an Application • 249

By choosing "No", you cause the operation to be a cut (delete) and paste (create new tag) rather than a move. WaterPipe
gets an Analog Status tag named Flow that is identical to the original, but which is a new tag with a new unique ID.
Logged history, etc from the original Flow is unrecoverable.

Rule: When synchronizing changes version changes, a move trumps a modify.

Example:
You have installed the application on two, unconnected computers. On one computer, you move a tag to a new location
in the tag tree. On the other computer you leave the tag where it is, but change its properties.
You then connect the two computers (or take a ChangeSet from one to the other), thus allowing the version control
system to synchronize the application on both machines.
In the final synchronized version, the tag will have been moved. The property changes will not be included in the
running version.

Calculate Tag Configuration Values - Snapshot Expressions

A powerful feature of parent-child tag structures is that the field values in a child may be calculated when the tag starts.
For example, a child tag may use an I/O address that is calculated from a base value stored in a parent tag.
This is done by adding a Snapshot Expression to any of a child tag's configuration fields except the name. The term
"Snapshot" refers to the fact that the expression is calculated only when the tag starts. The calculated result will not
change until the tag re-starts, regardless of changes to the expression parameters.
The VTS expression language is described in the chapter Creating Expressions. Of special note will be the string
concatenation function described in Text Functions.

To start, right-click on any of a tag's configuration fields, then choose Add Snapshot Expression from the context menu.
(Note that you can also use this technique to remove the expression, thus allowing the field value to be directly
configured.)

250 • How to Build an Application Developer's Guide (part 1)

The expression editor will open as shown:

Any valid expression may be used. You can calculate using values stored in parent tags, application properties, etc.
To access a variable, preface it with a backslash. If there is no ambiguity about the variable's location (that is, the
variable name exists only in the current tag, or in an immediate ancestor) then only the backslash need be used. For a
variable such as "Area" that will exist in both the current tag and the parent, add two dots in front of the backslash to
force the expression to look upwards to at least the immediate parent. (ex: "..\Area". Note that child tags are programmed
to automatically use the parent tag's area, making this particular example uncommon.)

The name of any configuration field in a parent tag may be used as the source for the value. Use quotation marks only for
text that should be used literally, for example as part of a string concatenation function.
In the configuration panel, fields that contain a Snapshot Expressions will be shown in blue so that you can spot them
easily. Hover over the field to see the expression and the time that the it was last saved.

Developer's Guide (part 1) How to Build an Application • 251

VTS will search upwards through the Parent-Child tree to find the first instance of a matching field name.
You may specify a direct path to any given parent or sibling tag, using a ".." notation. Each successive ".." indicates a
starting point, one generation up from the current child. Thus, for a child tag to reference its sibling's area field, the
expression would be "..\SiblingTagName\Area".

Note: When specifying an absolute path from the top of the hierarchy, the path must start with "VTSDB\".

If the parent is a Context Tag with named properties, you can reference the value of any property using the same
backslash notation.
Related topics: Context Tags, Conditional Starts, Parent-Child Tag Structures.

Tag Configuration Overrides

The information in this topic applies only to Parent-Child Tag Structures. This includes Station Tags.
Child tags, especially children of a defined Type such as a Station Tag, may have their parameter values set by code
rather than being directly configured. The most commonly encountered example is the Area field of any child tag -
unless otherwise configured, it will use the Area value from the closest parent that has a defined area.
If you change the value of a tag parameter that is defined by code, then you are applying an override to that field.
The difference is most important in terms of what happens behind the scenes in the tag's configuration. For example, a
MultiSmart Station tag has some 38 or more child tags. If you export your application's tags to a spreadsheet, you will
see only the one entry for the MultiSmart - not for the child tags. This is because those tags can be re-created by code
and therefore do not need to exist as individually configured tags in the database.
However, if you override a parameter within one of the MultiSmart's child tags, and then export to a spreadsheet, you
will find an entry for that child. The override value is stored in the tag database rather than being calculated through
code.

When you override a parameter, the field will turn orange instead of green, signifying an override rather than a simple
configuration change.

Conditional Starts and Disabled Tags

It is possible that your application may contain tags that should not be started. A common example is an application with
several pumping stations: A Context tag parent may have been configured with four pump assembly children , but the
actual number of pumps may vary from one station to another. Rather than create separate station types, each with a
different number of pump assemblies, you can put a conditional start expression on each assembly. (The parent Context
tag will require a named variable to store the number of pumps for each station instance.)

Note: You can explicitly set a tag's start condition to False using the Tag Browser. Right-click on the tag select Disable
from the context menu.

252 • How to Build an Application Developer's Guide (part 1)

If a tag's start condition evaluates to false, then it (and all of its child tags) will not be drawn, will not be included in your
tag count. They will also not be available in the tag browser unless you check the option, Show Disabled.

To add a start condition to a tag:

1. Open the tag's properties dialog and right-click on the name field.

2. Select Edit Start Condition from the menu.

The Snapshot Expression dialog opens.
3. Create an expression that will evaluate to True or False according to starting condition that will affect this tag.

4. Click OK to save your work.

If the value of the station's NumPumps variable is 1 or less, then this pump (and all of its child tags) will not start.

In this example, it is assumed that the parent is a Context tag containing a variable named NumPumps, which can be set
for each instance of a station. This would be created in the Context tag's Settings dialog, as shown:

Developer's Guide (part 1) How to Build an Application • 253

Related topics: Parent-Child Tag Structures, Context Tags, Calculate Tag Configuration Values - Snapshot Expressions.

Disable Tags
You can disable any tag listed in the tag browser. The tag will stop running, and will be removed from view unless Show
Disabled is checked.
To disable a tag, right-click on it and click to remove the checkmark from the line, "Enabled".
You might choose to disable a tag if you do not intend to use it for a period of time, but you do expect to use it again and
therefore do not want to delete it.

Copy an Existing Tag

VTS applications commonly have a number of tags that are very similar in their configuration. For this reason, the Tag
Browser includes a Copy button that can help you to create large numbers of similar tags quickly.

The steps to create a new tag based on a copy of an existing one are as follows:
1. Click the Browser button in the Configuration Toolbox. The Tag Browser will open.
2. Use the Tag Browser’s searching and filtering capabilities to locate the tag whose properties you wish to copy.

254 • How to Build an Application Developer's Guide (part 1)

 3. Right-click on the tag and select "Copy" from the context menu, or select the tag and click the Copy button at
the top of the Tag Browser.
Every new tag must have a parent. This may be any other tag, or it may be the root level (\).
4. In the tag browser, locate the parent tag and right-click on it to open a menu.
5. Select "Paste as Child".
If the parent already has a child with the same name, you will be prompted to create a new name for the copy.
Do so now. Otherwise, the new tag will retain all the properties of the one being copied.
6. [Optional] Open the new tag's configuration folder to adjust properties as required.
If the Auto Deploy option is selected for the application, then this operation is complete. Otherwise, this will be
considered to be a local edit until you deploy your changes.

Modify the Properties of an Existing Tag

To modify the properties of an existing tag, follow the steps below.
1. Click the Browser button in the Configuration Toolbox. The Tag Browser will open.
2. Use the Tag Browser’s searching and filtering capabilities to locate and select the tag you wish to delete.
3. Right-Click on the tag and select "Properties" from the resulting context menu.
The tag properties folder will open and display the properties that have been configured for this tag.

4. Update the property fields as required.

(A description of every property field in every tab of every tag’s configuration folder can be found in this help
guide.)
5. Click the OK button to save your changes.
If the Auto Deploy option is selected for the application, then this operation is complete. Otherwise, this will be
considered to be a local edit until you deploy your changes.

Delete a Tag
Tags can be deleted using the tag browser.

Note: If you delete a parent tag, you will also delete all of its child tags.

1. Click the Browser button in the Configuration Toolbox. The Tag Browser will open.
2. Use the Tag Browser’s searching and filtering capabilities to locate and select the tag you wish to delete.
3. Right-click on the tag and select the Delete option from the context menu.
A confirmation dialog will open and request confirmation that you wish to delete the selected tag. If you delete
a parent tag, you will also delete all of its child tags.
4. Click the OK button.
If the Auto Deploy option is selected for the application, then this operation is complete. Otherwise, this will be
considered to be a local edit until you deploy your changes.

Developer's Guide (part 1) How to Build an Application • 255

If you delete a tag, everything that referred to that tag's unique ID value will become inaccessible. Drawing methods
will vanish from the page (but still exist in the page code) and there will be no way to retrieve logged data.
A new tag created with the same name as the one deleted will still have a new unique ID value, and therefore no
connection to anything that referred to the deleted tag.
If you later change your mind after deleting a tag, you may use the Version Log (provided that your VTS license
includes this option) in order to revert the change.

Parent-Child Tag Structures

When creating tags, you can define their relationship to each other by adding new tags as children to existing tags. This
allows you to organize your tags according to how they fit into the overall structure of the application.

As an example, VTScada station tags (MultiSmart, MPE SC series and MPE Duplexer tags) make extensive use of child
tags - when you add one station, many child tags are created to handle I/O, alarms, setpoints and more. See: Station Tags.

A logical system to make use of this feature is to create I/O tags as children of the driver they are using. I/O tags are
designed to automatically link to the nearest parent driver, thereby simplifying configuration.

Note: A tag's full name includes the name of all it's parent tags, separated by backslashes. This can sometimes become
too long to display in a field, in which case VTS will abbreviate the displayed name. Hover the pointer over the field in
order to see the full name, displayed within a tool tip.

This system provides a number of benefits:

• Organization.
If you are looking for Pump1 in Station 1, you can find it quickly by navigating through the parent-child
hierarchy.
• Clear naming.
It might make sense for the primary pump in each well to be named "Pump1". You can do this without creating
conflicts because internally, tag names include the sum of all the parents. ("Station1_drv\Well_1\Pump1",
"Station1_drv\Well_2\Pump1").

256 • How to Build an Application Developer's Guide (part 1)

• Ease of configuration.
New driver tags will automatically find the nearest parent port. (..\*Port)
New I/O tags will automatically find the nearest parent driver. (..\*Driver)
All tags will automatically inherit their parent's Area value.
• Management of Security Rules.
Security rules can be defined to grant privileges only in the scope of a parent tag. In this example, you might
create only one application privilege, "Station Control" and protect all of a station's control tags with it. This
privilege will be carried into every copy of the station. You can grant that privilege to all operators, but then
limit the scope of the rule so that Joe can operate only the equipment in Station 1, while Sally operates only the
equipment in Station 2. See: Security Rule Scope.
• Application Scaling 1.
When you copy a parent tag, you also create a copy of all its children. If a new station is added in this example,
all the tags for that station can be created in two steps: Copy and Paste.
• Application Scaling 2.
Using two related technologies, Snapshot Expressions, and Context Tags, tag fields can be calculated based on
the parent's configuration. In this example, if each station is assigned a set of base addresses for I/O, and all of
the child tags within the station use I/O addresses that are calculated from one of those base addresses, then
adding a new station with hundreds of child tags can be done with the following steps: 1) copy, 2) paste, 3) set
the new base addresses, 4) done. See: Calculate Tag Configuration Values - Snapshot Expressions and Context
Tags.
• Application Scaling 3.
Using another related technology, Start Conditions, you can create an expression that controls whether any tag
will start or not. (Note: this does not refer to starting equipment with an output tag - this means whether the tag
itself and all of its children are loaded into the running application.)
For example, perhaps a town's new station (Station3) has only one well instead of two. By setting a variable in
the station tag (Number_of_Wells) and a start condition on the tag, Well_2 (Number_of_Wells > 1), then you
can use the generic structure for the new station. You do not need to create one-well stations, two-well stations,
etc. See: Conditional Starts.
• Application Scaling 4.
You can create a custom drawing method for a parent tag that has graphical displays and controls for all of its
child tags. In this example, if you have created such a drawing method for stations, then you could draw each
new complete station in a single step. See: User Draw Methods.
• The ability to create your own tag types.
All of the preceding notes about application scaling can be combined into one concept. Having created a parent-
child tag structure, you can decide to turn it into a new type of tag. The VTScada station tags (MultiSmart
Station, MPE SC Station, etc.) are examples of this. See: Create New Types of Tags.

Relative Tag Paths

It is common for one tag to reference another; I/O tags require device drivers, text requires a choice of Font tag...
In parent-child tag structures, it is possible that more than one tag in a given structure will have the same name
(disregarding the parent path). It is also possible that overall structures (e.g. Cities) may be constructed from several sub-
structures (Pumping Stations with Pumps, Wells, etc.). It therefore becomes important to have control over how a
selected tag name will be identified within the scope of the overall structure.

Developer's Guide (part 1) How to Build an Application • 257

Key facts:
• The full name of any tag includes the list of parent tags: "Middletown\PumpStation1\Pump1"
• The ultimate parent of every tag is VTSDB. This is seen only when specifying an absolute path, which must start at
the very top level parent.
• You can use the notation ".." to indicate "up one generation". Use a backslash to separate each generation and to
separate a tag name from its parent or generation indicator. Thus "..\..\StationX" means "up two generations, find the
tag named StationX".
• The notation used for each path type can be used in expressions. This may be useful if your tag structures include
The available path types are described in the following topics.

Ancestor Relative Path

Note: this option will be disabled if the tag being created has not yet been given a name.
The type name is shown with a * prefix. The first ancestor matching this type will be selected.

In the example shown, "*Driver" indicates the type of ancestor. "..\" enforces the rule that only an ancestor tag can be
used. "Modbus driver with virtual IO" happens to be the description of the first matching tag found of type, Driver.
If this Analog Status is copied to another parent, it will look for the first parent that is a driver of any type..

Open Relative Path

All parents that are in common between the current tag and the selected tag are dropped from the path of the selected tag.
If the tag is copied to a new parent structure, VTS will search upwards through the scope of the structure until it finds a
matching name.
Open relative path is always the correct choice when selecting a built-in VTS tag such as a Font or AlarmPriority since
all tags ultimately have a common parent in \VTSDB.

258 • How to Build an Application Developer's Guide (part 1)

In the example shown, the I/O Device is a driver named "vMod" with description, "Virtual Modbus". If this Analog
Status tag is copied to another parent, it will look for the first ancestor named "vMod".

Fixed Depth Relative Path

Specifies an exact path through the generations where a given tag will be found. Two dots are used for each step up the
tree and a backslash is used for each step back down.

In the example shown, the calculation is referring to a sibling tag, AI_1. The fixed depth relative path in this example is
..\TagName

Absolute Path
Specifies the exact path to the selected tag, starting with the ultimate parent, VTSDB. All copies of the tag will refer to
exactly the same selected tag.

Developer's Guide (part 1) How to Build an Application • 259

In the example shown, the Analog Status looks for a tag named "VTSDB\LocalPort\vMOD".

Create New Types of Tags

Any Context tag can be turned into a new type of tag. The Type property on the ID tab of the Context tag will be used as
the name of the new tag type. Within that application, it will then appear in all tag lists (excepting filtered lists). This is
normally done only after adding one or more other tags as children of the Context tag, thus creating a useful tag
structure.
Having created a new type, you may then create new instances of your customized tag as if it were a standard VTS tag
type. The new tag type will include all of the child tags of the selected Parent tag, and new instances of these will be
created with each tag. You are also able to create tag drawing methods for this (or any other) tag. See: User Draw
Methods.

If you add child tags to any standard VTS or VTScada tag, you can also update that tag's type definition. For example,
you might add a Logger tag and an Alarm tag as children of an Analog Input type. All new and existing instances of that
type in the current application will include those child tags.

Note: The Context tag's type name must not duplicate any existing VTS tag type. An error message will be displayed if
the type name cannot be used.
To be safe, adopt a naming convention that adds a distinct identifier to every name (for example "MA_Type" for My
Application...)

The steps to create a tag type are as follows. A list of related topics is provided at the end of this page.
1. Create a Parent-Child Tag Structure and develop it fully.
• The Context tag's Type field must have a value, which will become the name of the new tag type. The name
must be valid for use as tag type name and must not match any existing tag type. If this condition is not met, an
error message will be displayed.
• The child tags should use snapshot expressions where possible in order to match field properties to each new
instance of the parent tag. Of particular note are the Area field and the Address field for I/O tags.
• It is recommended that the child tags do not have their Questionable Data flag set.
2. Right-click on the Context tag in the Tag Browser to open its context menu.
3. Select the option, Create Type.
A dialog will open to confirm that you wish to proceed with this action, and provide an opportunity to un-select
the default drawing method for new types, Tag List.
If the Context tag had been drawn using any user-created drawing methods, then those methods will be listed as
well. If you choose not to make those drawing methods available to the new type, then all instances drawn for
the original context tag will vanish from the pages.

260 • How to Build an Application Developer's Guide (part 1)

 4. Un-select any drawing methods that should not be available to the new type.
5. Click on OK.

A new tag type will have been added to your application, and the selected context tag will be converted to be an instance
of this type.

Creation of your own tag type definitions is an advanced operation, requiring knowledge of several VTS features. Please
refer to the following for further information:

Related Topics:
• Details about creating the structure for a new type can be found in Parent-Child Tag Structures.
• The Context tag was designed (in part) to be a template for new types. See: Context Tags.
• Maximum flexibility is achieved by configuring the child tags to use Snapshot Expressions and Conditional Starts.
• You can create your own custom drawing objects for the new tag type. This will allow you to draw the new tag type,
with all of its I/O, in a single step. See: User Draw Methods.
• Type definitions can be modified after being created. See: Update Type.
• Instances of your new tag structure can be broken apart into their individual tags. See: Disassemble Tag Structures.

Update Type
Any tag definition can be modified.
Besides updating a type definition that you have created, you could for example, add a Logger tag as a child of an
Analog Input, then update the Analog Input type. All Analog Inputs in the current application will follow the new
definition, gaining an attached Logger tag.
To update a type definition:
1. Create an instance of the tag in the tag browser.
2. Modify the child tags as desired.
Modifications to the parent's parameters have no effect on the type definition.
Allowed modifications include adding and deleting the child tags.
3. Right-click on the parent tag of the structure and select Update Type.
4. Confirm that you wish to proceed. The tag definition will be modified to include your changes, and all existing
instances of that type will follow the new definition.
If you need to add new properties to the settings tab of a Context parent, disassemble the structure between steps 1 and 2
of this process. (See: Disassemble Tag Structures)

Developer's Guide (part 1) How to Build an Application • 261

Instructions for deleting a type definition are found in Delete Tag Types.

Edit Type Properties

After a context tag has been turned into a new type, using the Create Type command, the properties tab of its
configuration dialog will change from one where you have full control over adding, changing, deleting properties to one
where you can only edit values that are stored as part of the type definition.
The configuration panel of a new Context tag:

The configuration panel of the same tag, after it has been turned into a new type:

262 • How to Build an Application Developer's Guide (part 1)

You can still edit the parameter list for the type (and therefore, of all instances of that type) by using the Edit Type
Properties page from the Application Configuration dialog.
1. Access this page as follows:
2. Open the Application Configuration dialog.
3. Click, Manage Types.
4. Find and select the type in the table.
5. Click, Edit.

This page allows you to work with the type's parameter definitions, rather than with values stored in those parameters for
a single instance of the type.

Disassemble Tag Structures

This feature existed in earlier versions of VTS, but is obsolete as of version 10.2.
There is no need to disassemble a tag structure. All of the following can be accomplished without disassembly:
• Add, edit or remove parameters - See: Edit Type Properties.
• Add or remove child tags - Do so in one instance of the type, then use the Update Type command to make those
changes part of the type definition. See: Update Type.
• All other tasks - Export the type to a spreadsheet or database, and make the required modifications there. Re-import
the file to make those changes part of the type definition. See: Manage Types Using a Spreadsheet or Database.

Manage Types Using a Spreadsheet or Database

(See also: Import and Export Tags)

Developer's Guide (part 1) How to Build an Application • 263

If you have created a new type of tag, you can export the type definition to a spreadsheet or database file. Some
developers find it easier to work with a type definition in a spreadsheet format. After modifying the tag structure in the
exported file, you can import those changes to update the type definition within the application.
Note that, type definitions may be built-up across OEM layers. Only what was added, changed or over-ridden in the
current layer will be exported.
In the following example, a new type named SpecialPurposeTag was created from a Context tag with four child tags.

Options:

Remove Allowed only for user-defined types, and only if there are no instances of that type in the
tag browser.
Edit Applies if the original parent was a Context tag before the type was created. You can use
this to add, remove and edit the properties of that tag, using a dialog similar to the
Settings tab of a Context tag's configuration panel.
Sync Requires an existing spreadsheet or database, created using the Export button.
Synchronize will import any changes that were made in that file, modifying the type
definition within the application. What it does next depends on your choice of Import
Clean Up Options. If Update is selected, a fresh copy of the structure will be sent to the
external file, including an updated version number. If Delete is selected, the external file
will be removed.
Export Sends the structure of the selected tag to a file of the selected type, Access, Excel or other
ODBC.

264 • How to Build an Application Developer's Guide (part 1)

Referring to the preceding image, since there is no checkmark in the Removable column of SpecialPurposeTag, we know
that there is at least one instance in the application. (Standard VTS types cannot be removed, regardless of whether there
are any instances.) Note that the Remove button and the Edit button can only be enabled while the application is
running.
The checkmark in the Editable column tells us that this type was based on a context tag. You can click the Edit button at
the lower left of the display to work with that tag's parameters. All instances will update to have the new or changed
parameters when you finish. See Edit Type Properties.

If you intend to work with the tags in a spreadsheet or database, start by clicking the Export button.
An operating system dialog will open, to prompt you for a file name. The suggested name for the export file will match
the type name, but this is not required. The VTS_Reserved worksheet or table in the file contains the name of the type
that will be modified when the file is re-imported.

Note: Each type must be exported to, or imported from its own file. You cannot put two type definitions into one file.

All the child tags of the current type are exported, no matter how many generations deep in the structure. But, if any of
those child tags are themselves user-defined types, then their structure will not be included, since there can be only one
type definition per export. The exception to this rule is that tags with values that have been over-ridden will always be
exported.

Each entry will be named according to its place in the tag structure. In this example, SpecialPurposeTag has the
following structure (shown with an instance named "MyStation1").

In the export file, child tags are named relative to the parent. So, in this example, the TCP/IP Port worksheet will have
the following entry for the TCP/IP Port child named IO_Port. Since this is the first child in the structure, its name does
not include the top-level parent.

The Modicon Driver tag is a child of the TCP/IP port. It's worksheet name will reflect its place in the structure:
Note the doubled backslashes. A single backslash indicates the division between parent and child tag names, but the
spreadsheet program forces us to use the doubled backslash. See also: Relative Tag References & Snapshot Expressions.

And, so on for the two Analog Input types that are children of the Modicon driver in this structure.

Developer's Guide (part 1) How to Build an Application • 265

Note the use of relative tag paths (*Driver) for the each I/O tag's driver field.

You can add new child tags of any type to the structure, by creating entries in the appropriate worksheet or table, being
careful to follow the naming example shown here. You can also remove or modify any child tag's definition in the
structure.

Note: Always leave column A blank for new tags.

Upon re-importing the file by using the Synchronize button, the file, the structure within the application will be modified
with your changes.

Version control applies to exporting and importing type definition files. The exported file contains a key that identifies
the application's current version number at the time of the export. VTS is able to compare the contents of the file being
imported to the definition of the type as it existed at that revision. Only differences between the file's current contents
and the type definition as it existed at the time of the export will be merged.

Delete Tag Types

Only type definitions that you have created can be deleted. There must be no instances of that type in the application, and
if the application is secured, you must possess sufficient configuration privileges. Also, you must be working in the layer
(application) where that tag was created.
To delete a type definition:
1. Ensure that there are no instances of that type in the application.
2. Open the Application Configuration dialog.
3. Open the Manage Types page.
4. Select the type in the list.
If there is no checkmark in the Removable column, the type is in use somewhere in the application (either as an
instance or as a child of another type) or else this is a standard VTS type, which cannot be removed.
5. Click the Remove button.
There is no confirmation dialog - the type definition will be removed from the application.

266 • How to Build an Application Developer's Guide (part 1)

Import and Export Tags
Tag configuration is stored within the VTS repository. Never attempt to edit any of the files in the .sync folders – damage
to, or destruction of your application is likely to result.

Some developers find that it is efficient to create or edit tags in a tabular format, such as a spreadsheet. This is
particularly true when there are a large number of similar changes to make. VTS makes it easy for you to export your tag
database to either a Microsoft Excel™ or Microsoft Access™ file, then synchronize the changes made in that file with
the running application. You may use other database formats via ODBC, but you will first need to configure a data type
conversion table for that database, to ensure that data is correctly copied in and out. See: Using an Unsupported Database
Format for Tag Storage.

Notes:
• If selecting the Excel format, the Microsoft Excel program must be installed on the computer. Microsoft COM
objects, provided only with a copy of Excel, must be present in order to create a spreadsheet that is fully compatible
with Excel.
• Tags that are created automatically as children of a complex type (those within a MultiSmart or MPE station, or
your own user-defined types) will be exported without configuration data that would be generated automatically
when the complex type is created. Override values will be exported for these values, and you may apply or remove
override values in the exported file.
• You cannot use the procedure described in this topic to modify the structure of a complex type by adding or
removing child tags. A separate tool exists for that purpose - See: Manage Types Using a Spreadsheet or Database.
• If you have custom tags with a large number of parameters, you should be aware of the following limits: If exporting
to Access, the maximum number of tag parameters is 256. If exporting to Excel, the maximum number of
parameters is 65,536. None of the tags built into VTS or VTScada approach these limits.

The export file will contain information that identifies both the application and its current version. This will be used by
the VTS configuration management system when synchronizing the modified database. Look for the table or worksheet,
VTS_Reserved. The synchronization process gives you the following option for what will happen to the spreadsheet or
table after you import it back to the application.

Developer's Guide (part 1) How to Build an Application • 267

• You may direct VTS to update the file by performing a fresh export, thereby ensuring that you can continue editing
the file and synchronizing those changes. Choose this option when you are making a series of consecutive edits and
synchronizations.
• You may direct VTS to delete the file, thereby ensuring that you must perform a fresh export before the next editing
session. Choose this option when you expect to work in the Tag Browser before going back to the external database.

In general, it is best to work on an exported file that matches the current tag database. Importing an older file that does
not include recent changes, which were made within the application, may lead to errors.

Tags can be imported (synchronized) without re-starting your application. Note that if there are a large number of tags to
import or export, the operation may take a few minutes. The operation will be faster if the application is not running.
When you request either operation, a dialog will remind you of this:

The steps to either import or export tags begin with the same page in the Application Configuration dialog:

To export:
1. Open the Application Configuration dialog.

268 • How to Build an Application Developer's Guide (part 1)

 (Instructions)
2. Select the output type.
If ODBC, you must have already defined a Data Source Name (DSN) for your database using the Microsoft
ODBC Data Source Administrator.
3. Choose whether to have the file open immediately after the export.
4. Click the Export button.
If exporting to Access or Excel, you will be prompted for a file name and path.
If exporting to an ODBC data source, you will be prompted for the DSN.
5. Provide the destination for the exported tags and click OK.

When exported to an external data file, each tag type will be stored in its own table or worksheet. Within a tag type table,
each instance of a tag will be stored on a separate row, with a field for each attribute of the tag. (See following example)
If a tag is part of a parent-child tag structure, the full name of the tag within the structure will be shown.

Note: If adding new tags, you must leave the field in column A blank.
Never change the value in column A for any existing tag (except when deleting an entire row).

To Import:
1. Open the Application Configuration dialog.
(Instructions_D2HLink_2006768)
2. Choose the database format to import from.
If ODBC, you must have already defined a Data Source Name (DSN) for your database using the Microsoft
ODBC Data Source Administrator.
3. Select the clean-up option.

Developer's Guide (part 1) How to Build an Application • 269

 As a guideline, use the update option when making a series of modifications. Use the delete option when there
will be significant changes to the internal tag database before the next round of external edits.
4. Click the Sync button.
If importing from Access or Excel, you will be prompted for a file name and path.
If importing from an ODBC data source, you will be prompted for the DSN.
5. Choose the source file or DSN and click OK.
A message will inform you of how many tags were imported.

Note: if you attempt to import tags that were exported from a different application, you will see an error message
warning you that the GUIDs do not match. The tags will not be imported. See: Importing Tags from One Application to
Another.

Relative Tag References & Snapshot Expressions

Tag names within parent-child tag structures and user-defined tag types are built as shown in the following example:

The name of each parent tag is part of the full tag name, where each parent name is separated from the next with a
backslash.
Relative tag references (common when defining a port or driver) will look similar to the following:

In Excel, Access and other programs, the backslash has its own meaning. Therefore, it is necessary to indicate that this
character should be treated as just a backslash and not use that other meaning. This is commonly done by doubling the
character:

A similar rule applies to snapshot expressions, except that here there can be both backslashes and equal signs to mark.
An extra leading backslash is used for both:

270 • How to Build an Application Developer's Guide (part 1)

When modifying tags in an exported spreadsheet or database, you must also add the leading backslash, as shown in these
examples.

Importing From Older Versions of VTS

Prior to the release of VTS 10, tags were stored in a database file named Points.MDB. For most applications, this was a
Microsoft Access database. (Microsoft SQL Server was used by a very small number of applications.) These Points
databases did not include any information to identify the application, or its version.

In any version 10 application, you can import the tags from an older application's Points.MDB file. The steps are the
same as those provided in the previous topic but, be aware of two potential problems:

• The file, Points.MDB stores tag instances, but not type definitions. If the source file used type definitions from an
OEM layer, then the destination application must also have access to that layer's code in order to use the tags.
• Conflicts between tag names in the older database and the current application may not be resolved the way you
would prefer. Since the older database has no version control information, VTS is not able to automatically
determine how to resolve a conflict between two tags of the same name.

Note that, after importing an older tag database, you must compile the current application (using the Import File Changes
button) before you be able to see all of the imported tags.

Importing Tags from One Application to Another

After exporting tags from an application, if you then attempt to import those tags to a different application you will see
an error message similar to the following:

This is meant to protect your application in the case that the imported database may include type definitions that are not
present in the destination, or possibly a name conflict between the current and imported set of tags.
If you are satisfied that these two problems will not occur, and you are sure that you want to import the database, then
you need only remove the identifying information from the external tags database. This is stored in a table (or worksheet)
named "VTS_Reserved". After the GUID entry in this table is removed or set to "00000000-0000-0000-0000-

Developer's Guide (part 1) How to Build an Application • 271

000000000000" (or more simply, the table has been removed from the saved database), the tags may be merged into any
VTS application just as the tags from an older VTS version may be imported.

Tag Types Referenced by Category

Below is a list of the standard VTS/VTScada tags, arranged into categories.

Port Tags Communication Driver Tags

Motorola IP Gateway Allen-Bradley Driver
Serial Port CIP Driver
TCP/IP Port Data Flow RTU Driver (VTScada)
UDP/IP Port CalAmp Diagnostic Driver
IP Network Listener Port DDE Driver
DNP3 Driver
Input Tags Driver MultiPlexer
Analog Input MDS Diagnostic Driver
Analog Status Modicon Driver
Digital Input Motorola ACE Driver
Digital Status Omron Host Link Driver
Pulse Input (VTScada) OPC Client Driver
Pump Status OPC Server Setup
Siemens S7 Driver
Output Tags SNMP Driver
Analog Control Polling driver (VTScada)
Analog Output Workstation Status Driver
Deadband Control
Digital Control Alarm tags
Digital Output Alarm tags
MultiWrite Alarm Priority
Selector Switch Alarm Status
Trigger
Alarm Dialer System Tags
Data Logging and Reporting Tags Roster tags
Historian Modem tags
Logger SMS Appliance tags
Notebook

272 • How to Build an Application Developer's Guide (part 1)

 Report Calculation and Function Tags
SQL Logger Group Calculation
SQL Logger Counter
History Statistics
Configuration Tags Function
Context Network Status
Font Style Rate of Change
Realm Display Setup Analog Statistics
Digital Statistics
Station Tags Script
MPE Duplexer Station Totalizer
MPE SC Station
MultiSmart Station

Port Tags
Driver tags need to know how they will communicate with hardware. Rather than build this information into the driver
tag, VTS provides Port tags, allowing your to define the communication details once, then use that information for
multiple drivers.

Port tags tell the VTS drivers about the nature of the physical connection (serial port, TCP/IP over Ethernet, or UDP) and
the required configuration details such as address, port number, transmission speed, whether a modem is attached, etc.

Motorola IP Gateway Tags

This type is used to create an interface to a Motorola MDLC network. They are intended for use with the Motorola ACE
driver tags.
In addition to adding an IP Gateway tag, you must also install a Motorola configuration file, named MDLC_TYP.CFG.
This lists the possible RTU table configurations. If there are errors in this file, you can expect "type mismatch" error
messages.

Note: MDLC_TYP.CFG is a Motorola product. It is not supplied by Trihedral.

The MDLC_TYP.CFG file must be placed in your application folder, and imported to the application using VTS
configuration management. (see: Import File Changes or Manage Files with the File Manifest.)

The Motorola IP Gateway API is made available via a Component Object Module (COM) object,
ACEIPGatewayAutomation.exe. This will be installed on your system when VTS is installed.
The gateway will support 20 concurrent polling requests.

Developer's Guide (part 1) How to Build an Application • 273

Motorola IP Gateway: ID Tab
The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Motorola IP Gateway: Settings Tab

Use the settings tab to configure the primary gateway and to control the time synchronization feature.

TCP/IP Address
Provide the gateway's primary address in this field. This must be in IPv4 format, rather than a named address.

System Time Sync

The enable box should be checked if you intend to use the system time synchronization broadcast, which sends the
current local time to all devices on the MDLC network.
Use the Broadcast Interval control to select the appropriate timing for your system.

Motorola IP Gateway: Sites Tab

Note: Available only in applications built on the optional ScadaAce layer.

If your application has been build on the ScadaAce layer, then the Motorola IP Gateway tag will include a Sites tab. This
should be used for adding all new ScadaAce sites. Note also, every application based on the ScadaAce layer will include
one Motorola IP Gateway tag, named GW.

274 • How to Build an Application Developer's Guide (part 1)

Use the buttons below the list to Add, Edit, or Delete ScadaAce Site tags.

Motorola IP Gateway Tag Drawing Methods

There are no drawing methods for the Motorola IP Gateway tag.

Serial Port Tags

The Serial Port type opens an RS-232 connector port for use by a driver. If you intend to use a modem, either for
communication to the remote telemetry unit, or for use by the alarm dialer, then you will need a Serial Port tag.
Technical details:
The transmit and receive buffer lengths are fixed at 16384 bytes.
The Data Transmit Ready (DTR) parameter of the serial port is fixed at 1

Note: Serial port tags may use the same port for different purposes on two different PCs. This is achieved by the re-use
of serial ports on backup machines in remote applications.

(Characteristics available in the Table of Type Characteristics.)

Serial Port Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Serial Port Properties: Settings Tab

Use the settings tab to configure the tag for the communication parameters required by your hardware. The default
settings for data bits, speed and parity are those which are most commonly in use.
When Use Modem is not checked, you must specify the COM port number in use. If Use Modem is checked, the Port
Number field will be disabled and the Phone Number field enabled.
The required values for all the configuration options should be available from the specification provided with the
hardware device connected to your serial port.

Developer's Guide (part 1) How to Build an Application • 275

Use Modem
Provides control over whether a modem or a serial port is to be used.
This checkbox must be selected, and a remote phone number phone number provided if the driver attached to this port is
to be a modem tag.
When the Use Modem checkbox is selected, the Phone Number and Modem Initialization fields will be enabled.

Port Number
Used to set the number of the serial port that is to be used. The corresponding serial port number must be configured in
the Ports dialog box of the Windows Control Panel. The value should match your port number and be between 1 and
4096.
If the Use Modem checkbox is selected, the Port Number field will be disabled and the Phone Number and Modem
Initialization fields will be enabled.

Phone Number
When a modem is to be used, fill in this field with the phone number that the modem must call in order to reach the
remote system. Supply all the digits including area code, etc. Do not include spaces.
If the Use Modem checkbox is not selected, the Phone Number field will be disabled.

Modem Initialization String

Used only if your modem requires a customized initialization string. In most situations, you will leave this field blank. If
configured, any initialization string must be prefixed by "AT". Note that the initialization string will be used only by the
Trihedral TSP driver. It will be ignored by the Unimodem driver.

Data Bits
Select a number (either 7, or 8) specifying the number of data bits to use for each character. The 8 bit setting, matching
the size of a byte, is used for almost all devices. The 7 bit setting might be needed for older devices that require ASCII
values.

Stop Bits

276 • How to Build an Application Developer's Guide (part 1)

Specify the number of stop bits for each data character. (In asynchronous communications, a stop bit is a bit that
indicates that a byte has just been transmitted).

Baud Rate
Set the baud rate (bits per second) at which data should be transmitted.

Parity
The Parity section enables data quality verification based on one of the following parity formats. It must be set to match
your device configuration.
• No Parity - select to suspend parity checking for this serial port. By default, the No Parity checkbox is selected.
• Odd Parity - select to use the odd parity mode of parity checking in which the number of mark bits (1's) in the data is
counted, and the parity bit is asserted or unasserted to obtain an odd number of mark bits.
• Even Parity - select to use the even parity mode of parity checking in which the number of mark bits in the data is
counted, and the parity bit is asserted or unasserted to obtain an even number of mark bits.
• Space Parity - select to use the mark parity mode of parity checking in which the parity bit is unasserted.
• Mark Parity - select to use the mark parity mode of parity checking in which the parity bit is asserted.

Echo
Select whether or not the transmitted data should be echoed in the received data.
If the Echo checkbox is selected, the driver should expect that the transmitted data will be echoed in the received data.
By default, the Echo checkbox is not selected.

RTS Keying
Check this box to select whether the driver should assert RTS (Request to Send) flow control while data is being
transmitted.
RTS/CTS (Request to Send/Clear to Send) flow control is typically used with all high-speed modems, or modems that
compress data.

Key Up Delay
The Key Up Delay property sets the delay in seconds prior to data transmission. The Key Up Delay field is only enabled
if the RTS Keying checkbox is selected.
The default value for the Key Up Delay property is 0.1 seconds.
For more information:
Please see Modem Tags for information on configuring Modem tags.
Port Sharing: Multiple drivers can share a Serial Port tag when it is in ‘serial’ mode. See:
SerPortDisconnectDelay.

Serial Port Tag Drawing Methods

The following drawing methods are available to display information about your application’s Serial Port tags:
Comm Indicator Drawing Method
Comm Line Drawing Method
Connection Status Indicator Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method

Developer's Guide (part 1) How to Build an Application • 277

Numeric Value Drawing Method
Plot Data Drawing Method

TCP/IP Port Tags

The TCP/IP port type is used to connect your VTS application to a series of hosts, allowing you to send and receive data
across a network or over the Internet. TCP/IP port tags can also open a TCP/IP socket to emulate a Serial Port tag for use
with serial-based I/O drivers using TCP/IP-based terminal servers.
A TCP/IP port tag may also be used to accept incoming TCP/IP socket connections if a port number is defined, but a
TCP/IP address is not defined (null or invalid), thus allowing drivers to act as slaves on network connections.
(Characteristics available in the Table of Type Characteristics.)

TCP/IP Port Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

TCP/IP Port Properties: Connection Tab

The Connection tab of the TCP/IP port tag properties folder contains properties that enable communications.

TCP/IP Name/Address
The TCP/IP Name/Address field provides a space for you to identify the name or IP address of the server to which to
connect (for example, MyRTU.com, or 198.255.32.1).

Connect Time Limit (sec)

Set the number of seconds that the system should wait for a connection response from the server that is specified in the
TCP/IP Name/Address field.

TCP/IP Port Number

278 • How to Build an Application Developer's Guide (part 1)

The TCP/IP Port Number field refers to the port number on the host address through which communications are enabled.
This information should be available from your hardware specification.
For example, Modicon TCP/IP drivers commonly use port 502.

Disconnect Delay
Specify in seconds or fractions of a second, the amount of idle time that should pass before the connection to the server
is terminated.

TCP/IP Port Tag Drawing Methods

The following drawing method is available to display information about your application’s TCP/IP port tags.
Comm Indicator Drawing Method,
Comm Line Drawing Method
Connection Status Indicator Drawing Method

UDP/IP Port Tags

The UDP/IP port type can be substituted for a TCP/IP port tag for a driver to use the User Datagram Protocol (UDP).
This protocol differs from TCP in that it does not provide for error checking, but does provide good support for packet
broadcasting and multi-casting.

Warnings:
All UDP/IP port tags use an internal listener port to receive datagram responses. The is what the Local Port Number
defines (it is also used as the transmit port number).
The engine will automatically route responses back to the UDP socket stream if the remote IP address matches that of the
stream. This means that multiple UDP/IP port tags can make use of the same local port number (internally they share the
UDP port listener). This UDP port listener requires that the port be free, thus any conflict for use of the port runs the risk
of disrupting UDP/IP communications.

Take note of the following possible errors. Some may not cause problems until the next re-start of the application.
1) UDP/IP Port and IP Network Listener tag sharing the same port number.
The IP Network Listener tag uses a socket server to function. This can interfere with the UPD listener port used by the
UDP/IP port tag.

2) UDP/IP address left blank

The UDP/IP port tag functions as a socket server when the Name/Address field is invalid. It will listen on the local port
number for any datagram messages and will bind to the first one received. In this way it is similar to an IP Network
Listener, only without the discrimination/filtering abilities. A UDP/IP port tag in this configuration can interfere with
other UDP/IP Port tags trying to use the same port. If you are unsure of the remote address then enter 0.0.0.0 rather than
leaving the field blank. If you truly want a UDP listener port, then it cannot currently use the same local port number as
other UDP port tags.

3) Disconnect Delay defined.

This option was included exclusively for use with IP Network Listener tags. There is one situation where the engine level
UDP handling is insufficient; when the remote device can respond with different IP addresses over time. Use the
Disconnect Delay to disassociate the remote IP after a period of inactively. The VTS engine is then able to establish new
remote IP address associations with the remote device via IP Network Listener tags.

Developer's Guide (part 1) How to Build an Application • 279

(Characteristics available in the Table of Type Characteristics.)

UDP/IP Port Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

UDP/IP Port Properties: Connection Tab

The Connection tab of the UDP/IP port tag properties folder contains properties that enable communications.

UDP/IP Name/Address
The UDP/IP Name/Address field provides a space for the name or IP address of the server to connect to (for example,
MyRTU.com, or 198.255.32.1).

Remote Port Number

The Remote Port Number field indicates the port number on the host address through which communications are
enabled.

Local Port Number

Disconnect Delay
Specify in seconds or fractions of a second, the amount of idle time that should pass before the connection to the server
is terminated.
Sets the port number on which the local PC should listen.

UDP/lP Port Tag Drawing Methods

The following drawing methods are available to display information about your application’s UDP/IP Port tags:

280 • How to Build an Application Developer's Guide (part 1)

Comm Indicator Drawing Method,
Comm Line Drawing Method
Connection Status Indicator Drawing Method

IP Network Listener Tags

Add IP Network Listener tags to your application if you want to be able to accept inbound TCP or UDP connections.
This tag is for use with the DNP3 and Modicon drivers, but may also be used by custom drivers.
While this tag will work with both protocols, it is intended primarily for TCP connections and is not recommended for
most UDP/IP communications. If a UDP port is in use, then VTS will listen for UDP/IP datagram packets and place
them into existing UDP streams if the remote IP address matches that of the UDP stream. Drivers using the UDP
protocol might only need a Network Listener if the RTU is connecting to VTS using a different IP address each time.

Warning: The IP Network Listener uses a socket server to accept incoming connections. Improper configuration can
result in communications failure for UDP/IP Port tags that make use of the same local port number. Refer to UDP/IP
Port Tags for more information and further warnings.

Multiple Modicon and DNP3 driver tags can share the same IP Network Listener.
See also:
Modicon Driver Properties: Serial Tab.
DNP3 Driver Properties: Serial Tab.
(Characteristics available in the Table of Type Characteristics.)

IP Network Listener Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

IP Network Listener Properties: Options Tab

Configuration of the IP Listener port is done in the options tab.

Developer's Guide (part 1) How to Build an Application • 281

Enable
Accepts a 1 to enable or a 0 to disable inbound connections. The options Expression or Tag allow you to enable or
disable connections based on user control of your choice, or based on current operating conditions. Set to 1 (online) by
default for all workstations.

Protocol
Select either TCP/IP and UDP/IP, as appropriate for the device your drivers will be communicating with.

Port Number
Define the port that be used for inbound connections. Ensure that your firewall has been configured to allow connections
to this port.

Remote Port Number

Enabled only for UDP/IP. UDP responses from VTS will be sent to this port number. Leave this option Invalid in order
to send responses back to the source port on the RTU.

IP Allow List
As a security measure, this listener will accept connections only from the IP addresses you add to this list. A range of
allowed addresses may be defined by leaving portions empty.

Discriminator Options - Idle Time and Sample Limit

These two values control how incoming data is sampled. Sample Limit specifies the number of bytes to be received
before the stream is sampled. In the event that the stream is not changing, the passage of Idle Time seconds will trigger a
sample. The default values were selected to work in most cases, but you may find that Sample Limit need only be set to
10 bytes when this tag is used by a DNP3 driver.

IP Network Listener Tag Drawing Methods

The following drawing methods are available to display information about your application’s IP Network Listener tags:

282 • How to Build an Application Developer's Guide (part 1)

Comm Indicator Drawing Method

Communication Driver Tags

Communication driver tags are designed to translate data being transmitted to and from specific types of I/O devices,
such as PLCs and RTUs. Each brand of I/O device generally requires its own communication driver, depending upon the
communication protocol used by the device.
The following communication driver tags are included with VTS:
Allen-Bradley Driver CIP Driver
Data Flow Module Data Flow RTU Driver
CalAmp Diagnostic Driver DDE Driver
MDS Diagnostic Driver Modbus – See Modicon
Modicon Driver Motorola ACE Driver
Omron Host Link Driver OPC Client Driver
Siemens S7 Driver Polling driver
SNMP Driver

Note: Please note that Trihedral Engineering Limited has many other communication driver tags available. Please refer
to the VTS driver library for further information (see VTS I/O Device Driver Library).

The basic driver types allow VTS to provide an interface to:

• Physical I/O devices, such as programmable logic controllers (PLCs), RTUs, and I/O boards; and
• Windows system features, such as Dynamic Data Exchange (DDE).
Most driver tags have 7 variables which can be logged. These are described in the following section.

Communication Driver Log-Enabled Variables

All of the standard drivers have 7 variables that may be logged. When recorded in a report, these allow you to monitor
driver communications over time to spot problems or ensure that response times are acceptable.

Logged Variable Description

1. ErrorValue An error value or code associated with a driver's
communication error.
2. FailedCount Incremented on each communication error.
3. FailedRetryCount Incremented if failure occurs on a retry. Drivers will
usually retry more than once before designating an
error to be an "error on retry". Thus, this count will
always be less than or equal to the FailedCount.
4. SuccessCount Count for successful reads and writes, incremented on
each successful operation.
5. Quality A mathematically derived indication of communication
error rates. Used to show the driver's overall "health".
(1)
6. ResponseTime The time it takes the PLC/RTU to receive a command,
process it and send a response. (2)

Developer's Guide (part 1) How to Build an Application • 283

 7. ErrorAddress If an address was associated with the error, it will be
recorded here.

A publicly accessible variable, CommStatsTimeStamp, holds the most recent timestamp that was used to update the
above 7 variables and write them to a DAT file.

Two reports are standard for all communications drivers. The Driver Communication Error Detail Report and the Driver
Communication Summary Report. Both are described in “Reports Page: Types of Reports”.

(1) Calculation of Quality:

Quality is an indication of a driver's ability to communicate without errors. The value ranges between 0 and 1 where the
closer the quality is to 1 (100%) the fewer communication errors are happening. You will need to determine what an
acceptable level of quality is for your situation. To put it simply, the closer the quality is to 1, the better the driver
communication.
On an initial, successful communication with a device, a quality of 1 (or 100%) is recorded. If subsequent
communications attempts end with errors, the level of quality drops according to the following formula. Successful
communications serve to then raise the level of quality back to a maximum of 100%.
You may find that the quality calculation changes through the day. This might indicate interference from a source that
can then be tracked down.
The quality calculation formula:
Q = Q * qF + (1 - qF) * (1 - !Error)

Where
Q = Quality
qF = Quality Factor
Error is a Boolean stating whether the driver reported an error state.
The default Quality Factor is .99 & all drivers start with a default Quality of 1.
Every time the driver completes an operation, the quality is recalculated.
Thus, when it first starts and does a successful operation:
Q = 1 *.99 + .01*1 = 1
When an error occurs, Q = 1*.99 = .99
If a subsequent error occurs, Q = .99*.99 = .9801
If a subsequent success occurs, Q = .9801 *.99 + .01*1 = .980299
The quality value over time will reflect the drivers overall health. It should always be a value between 0 & 1.
Quality includes all errors including any low level errors, retries, or addressing errors.

(2) Response Time

Response Time is calculated with the formula:
ResponseTime = EndTime - StartTime - XmitTime - RcvTime

Where
XmitTime is the time it took to transmit any data
RcvTime is the time it took to receive any data, based on

284 • How to Build an Application Developer's Guide (part 1)

• the number of bytes sent,
• the baud rate,
• parity,
• data bits and stop bits,
• whether there is an echo expected,
• whether RTS key delays are used.
The resulting Response Time is the time it took the PLC/RTU to receive a command, process it and send a response.

Communication Driver Alarms

Using the information in the preceding topic, Communication Driver Log-Enabled Variables, you can create Alarm tags
to warn operators of a loss in communication or a decrease in communication quality.
The alarm tag will use an expression as its trigger, where the expression refers to one of the log-enabled variables in the
communication driver. It is recommended that you create the alarm tag as a child of the driver tag.

Example. An alarm to warn of driver quality falling below 0.95.

Expression: [SomeDriverName]\Quality
This expression assumes that the Alarm tag was created as the child of a driver. If the alarm cannot refer to a parent
driver, provide the full path to the driver: [VTSDB\SomePortName\SomeDriverName]\Quality.
As configured in the alarm tag, with a two-second delay:

Allen-Bradley Driver Tags

The Allen-Bradley driver provides an interface to an Allen-Bradley PLC, allowing communication via:
• Serial port

Developer's Guide (part 1) How to Build an Application • 285

• KT/SD I/O board
• TCP/IP
Note: For CompactLogix and ControlLogix PLCs, which use tag based addressing such as Station1.Pump1.Running,
please refer to CIP Driver tags.
This driver has the ability to save the last value written to each output tag, and to rewrite those values, either
automatically when lost communications are restored, or manually by the press of a button. Carefully review the
information in the Type tab to decide whether this feature should be used in your application.
Log Enabled Variables: see Communication Driver Log-Enabled Variables
(Characteristics available in the Table of Type Characteristics.)

Allen-Bradley Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Allen-Bradley Driver Properties: Type Tab

The Type tab for an Allen-Bradley driver tag properties folder consists of attributes used to identify the type of Allen-
Bradley programmable logic controller that this driver will represent.

PLC Type
Select the type of Allen-Bradley PLC that this Allen-Bradley driver tag will represent. This may be one of:
• No Type Selected <default option>
• PLC-2
• PLC-3
• PLC-5
• PLC-5/250
• SLC-500
• ControlLogix

286 • How to Build an Application Developer's Guide (part 1)

Note: The ControlLogix driver is used in SLC-500 addressing. The TCP/IP port number to use for this driver is 44818.

Note also: it may be necessary to adjust the timeout interval on the TCP/IP tab if using ControlLogix.

PLC Address
This field should contain the address of the Allen-Bradley programmable logic controller. One of the following 3 formats
is permitted. (Note that this address must be provided in octal.)
• 012 (octal)
• 034 0357 (octal with a bridge address)
• 1.2.3.4 (IP address)
The PLC Address field and the TCP/IP Address fields are linked, and therefore are completed simultaneously. When you
enter an address in the PLC Address field, the same address is automatically entered in the TCP/IP Address field on the
TCP/IP tab for this tag. Conversely, when you enter an address in the TCP/IP Address field, the same address is
automatically entered in the PLC Address field.

Number of Virtual Words

Use this field to specify the number of registers that the virtual PLC will create. The virtual PLC will then emulate a
PLC-2 and respond to requests to read and write data.

Store Last Output Values

When checked, the driver will maintain a record of the last value written to each output address. This may be useful in at
least two situations:
• For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
• When failed hardware is replaced by a new device and you would like to start that device with the values last written
to the old one.
If the last output values are stored, they may be re-written by either of two methods:
• Automatically, when communication is restored to the device.
• Manually by way of a button press. See, Rewrite Outputs Drawing Method for details.
Changing this value from checked to un-checked will cause all currently stored values to be erased immediately.

Enable Auto Rewrite

If checked, the Store Last Output Values option will also be activated.
This option causes the driver to automatically rewrite the last value written to each output, in the event that
communications are lost, then restored.
Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in
driver communications.

Allen-Bradley Driver Properties: Serial Tab

The Serial tab for the Allen-Bradley driver tag properties folder consists of attributes used to identify and establish a
connection the Serial Port tag that the Allen-Bradley driver should use to transmit data to the I/O device. The Serial tab is
also used to select the communication protocol and error checking to be used in transmissions of data between the I/O
device and the Allen-Bradley driver.

Developer's Guide (part 1) How to Build an Application • 287

Port
Select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag. A Serial Port tag opens a serial
port to enable communications between VTS and your PLC or RTU. A TCP/IP tag is used to connect to a series of hosts,
allowing you to transmit data across a network or over the Internet.
The Port field can be used to associate this tag with a new or existing Serial Port tag or TCP/IP tag using the … button.
The … button opens the Tag Browser, which displays only the existing serial port and TCP/IP tags for your application,
and is used to create a new serial port or TCP/IP tag using its New button.
The Port field can be cleared using the X button that appears to its right.
Right-clicking the name of the serial port or TCP/IP tag that has been selected in the Port field opens the tag properties
folder for the selected tag.

Time-Out Limit
Sets the receiver time-out limit (i.e. the time in seconds or fractions of a second that this driver should wait for a reply
from the PLC or RTU).

VTS Station Address (Octal)

Specify the address (using the octal addressing format) of the VTS system on the serial link.

Retries
Select the number of attempts that will be made by this driver if there is no reply to a message, before an error is
declared.

ENQ Delay
Specify the amount of time (in seconds or in fractions of a second) that this Allen-Bradley driver should wait before
sending an ENQ in half duplex mode.

Note: Half duplex mode refers to the transmission of data in one direction at a time.

RTS Key Off Delay

288 • How to Build an Application Developer's Guide (part 1)

The RTS Key Off Delay field represents the amount of time (in seconds) that this Allen Bradley driver will wait before
dropping RTS at the end of a data transmission.

Hold
The Hold checkbox indicates whether this driver should hold data from the PLC or RTU in the event of a
communications failure.
If the Hold checkbox is selected, the last received value from the PLC or RTU will be held.
If the Hold checkbox is not selected, the data will be invalidated in the event of a communications error.
By default, the Hold checkbox is not selected.

BCC
Click this checkbox to select whether the BCC error checking method will be used on communication messages.
By default, the BCC checkbox is not selected (i.e. CRC error checking is used on all communication messages).

Note: The CRC acronym stands for Cyclic Redundancy Check, and the BCC acronym stands for Block Check Character.
Both are techniques used to detect data transmission errors. In general, CRC is a better error checking method, as it is a
16-bit error check, whereas BCC is an 8-bit error check

DF1 Mode
Enables you to choose between the following data transmission modes in communications from the driver to the PLC.

• Half Duplex: Half duplex mode refers to the transmission of data in one direction at a time. If the driver and the PLC
are communicating using the half duplex mode, either the driver or the PLC may transmit data at one time. The
device not communicating must wait until the device that is transmitting data is finished before it can transmit its
data.
• Full Duplex: Full duplex mode refers to the transmission of data by both parties simultaneously.
• Radio Modem: Certain Allen Bradley PLCs implement the Radio Modem Protocol (RMP) to optimize DF1
communication on radio modem links. The protocol is an enhancement of the Full Duplex Protocol and uses the
same message format with all the ACK and NAK responses removed.

Allen-Bradley Driver Properties: SD Tab

The SD tab for the Allen-Bradley driver tag properties folder consists of attributes used to identify and establish a
connection to the SD I/O board, if one has been configured for this I/O device.

Developer's Guide (part 1) How to Build an Application • 289

Board Type
The Board Type section enables you to specify the type of I/O board that has been installed. This can be one of:
• Disabled - When selected, indicates that the I/O board for this driver is disabled.
• S&S 5136-SD, Supplied Driver - When selected, indicates that a 5136-SD card is installed.

Device Name
The name of the device being monitored by this tag. This is a unique name that must be entered exactly as it appears in
the Windows Device Manager’s devices list.

Note: To launch the Device Manager in Windows, click Start, and then click Control Panel. Double-click System. On the
Hardware tab, click Device Manager

Time-Out Limit On SD
The Time-Out on SD field enables you to indicate the amount of time (in seconds or in fractions of a second) that the
driver will wait for a reply from the PLC's SD card.

Retries On SD
The Retries on SD spin box enables you to select the number of retry attempts you wish to be made by the driver if there
is no response to a message.

VTS Station Address On SD (Octal)

This field enables you to specify the address of the VTS system on the SD link. This value must be in Octal format.
The address may be set via a constant value, an expression or a numeric tag whose value is the octal address.

Allen-Bradley Driver Tag Type Properties: TCP/IP Tab

The TCP/IP tab of the Allen-Bradley driver tag properties folder can be used to configure the address, port, and time
limit to be used if communications are to be made using the TCP/IP communications protocol.

290 • How to Build an Application Developer's Guide (part 1)

TCP/IP Address
The TCP/IP Address field is used to specify the port number through which this Allen-Bradley driver tag will
communicate.

Note: The TCP/IP Address field and the PLC Address fields are linked, and therefore are completed simultaneously.
When you enter an address in the TCP/IP Address field, the same address is automatically entered in the PLC Address
field on the Type tab for this tag. Conversely, when you enter an address in the PLC Address field, the same address is
automatically entered in the TCP/IP Address field

TCP/IP Port
The TCP/IP Port Number field refers to the port number on the host address through which communications are enabled.
This information should be available from your hardware specification. The default value depends on the PLC Type
selected.

TCP/IP Time Limit

Use the TCP/IP Time Limit field to indicate the amount of time (in seconds or fractions of a second) that the driver will
await responses from the PLC. Defaults to 5 seconds unless otherwise specified.

Ethernet/IP Inactivity Timeout

Applies only if the PLC Type is set to ControlLogix. If the polling time is longer than this timeout value, then the driver
will disconnect between every poll. Values are pre-configured as multiples of 2.064 seconds. Select a value that is
greater than your polling interval.

Allen-Bradley Driver Properties: DLG Tab

Certain Allen Bradley PLCs (of PLC Type "ControlLogix") are able to log time-stamped data into files in PLC memory.
The Allen Bradley Driver tag can read records from these files (referred to here and in the PLC documentation as
queues). In order for the Allen Bradley Driver tag to make use of this feature, both the tag and the PLC must be

Developer's Guide (part 1) How to Build an Application • 291

configured properly. The DLG Read tab of the Allen Bradley Driver tag can be used to configure the tag for this feature.
Refer to the PLC's manual for instructions on how to configure the PLC (noting that up to 256 queues can be created and
data from different PLC memory addresses can be logged into different fields in different queues).

Data Logging Queue

Use to select a queue (configured according to the PLC’s manual) from which the driver will be retrieving logged data.

Length of Records from Queue

The Length of Records from Queue edit field allows you to enter the length of the records in the queue currently selected
in the Data Logging Queue drop list. This value is the length (in characters) of the records in the queue once they are
converted into a string by the PLC for communication.
The valid range is from 1 to 80. The value must be calculated according to how the data logging queue was configured in
the PLC itself:
• 11 characters for the date field,
• 9 characters for the time field,
• 12 characters for each long integer field
• 7 characters for each short integer field.

By default, the Allen Bradley Driver tag will assume a length of 80 chars (the maximum allowed by the PLC). While
default value will work, this may impose a penalty on the amount of communication between the driver and the PLC.
Entering the exact length is therefore recommended.

Note: entering an incorrect value will most likely result in failure to read any records from a particular queue, therefore
you should only change the default value if you know the exact value.

Important Notes
When configuring the data-logging feature on the PLC:
• Make sure that both date and time stamps are being logged into the relevant queues.

292 • How to Build an Application Developer's Guide (part 1)

• Failure to configure a queue in this manner will result in the Allen Bradley Driver tag simply ignoring all records
from that particular queue. This behavior is by design since a list of logged values without time stamps is of little
value.
• Make sure that a real-time clock is present and enabled in the PLC.
• For the same reason as above, if a real-time clock in not present in the PLC or if it is present but not enabled, the
driver tag will ignore all records from all data logging queues.
• Make sure the PLC’s real-time clock configuration (date, time, time-zone, daylight savings time) matches the
workstation’s clock configuration.
• Failure to do so will result in the Allen Bradley Driver tag setting the wrong timestamps to all logged values
read from the PLC.

Allen-Bradley Driver Tag Drawing Methods

The following drawing methods are available to display information about your Allen-Bradley driver tags:

Comm Indicator Drawing Method

Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method
Rewrite Outputs Drawing Method

Allen-Bradley Driver Addressing

The table below identifies the value ranges for Allen-Bradley PLCs. Bitwise addressing for binary and integer formats is
accomplished by following the element with "/bit-number".

Allen-Bradley Addressing Value Range

Output Image O:0 – O:30
Input Image I:0 – I:30
Status S:0 – S:n
Binary B3:0 – B3:255 (bitwise - B3:1/15 16th bit in
element number 1)
Timer T4:0 – T4:255
Counter C5:0 – C5:255
Control R6:0 – R6:255
Integer N7:0 – N7:255 (bitwise - N7:1/5 6th bit)
Floating Point F8:0 – F8:255

Developer's Guide (part 1) How to Build an Application • 293

 Network x9:0 – x9:255
User Defined x10:0 – x10:255

Note: The above addressing scheme is applicable for all Allen-Bradley PLC's, regardless as to the model. (Where
necessary (e.g. ControlLogix), the PLC's processor takes care of mapping addresses internally.)

An example of the addressing scheme for Allen-Bradley drivers of the PLC-500 type is described below:

Allen-Bradley PLC-500 Addressing: Allen-Bradley Driver Tag Properties

Allen-Bradley Driver Tag Properties
Folder Tab Property Value
Type tab PLC Type PLC-500
Type tab PLC Address 1
Serial tab Port COM1 or COM2
Serial tab Time-out Limit 1
Note: If you wish your scan interval to be 0.1, you may wish to decrement your Time-out Limit.
Serial tab ENQ Delay 0
Serial tab VTS Station Address 0 (your base address)
Serial tab Retries 1
Serial tab Hold deselected
Serial tab BCC selected
Serial tab Half-Duplex selected

Allen-Bradley PLC-500 Addressing: Serial Port Tag Properties

Serial Port Tag
Properties Folder Tab Property Value
Settings Tab Data Bits 8
Settings Tab Stop Bits 1
Settings Tab Baud Rate 19200
Settings Tab Echo deselected
Settings Tab TRS Keying deselected
Settings Tab Key Up Delay 0.1

Note: For a list of all available data type suffixes that can be used for tag I/O addresses, please refer to Data Type
Suffixes for Tag I/O Addresses.

CalAmp Diagnostic Driver Tags

The CalAmp diagnostic driver type enables users to read statistics from any given Integra-TR, Integra-H, Viper SC or
Phantom II radio.
This driver was known as the Dataradio Diagnostic driver in previous versions of VTS.

294 • How to Build an Application Developer's Guide (part 1)

These tags are only required in applications where you wish to gather data about a CalAmp unit.
For example, a common arrangement might be a CalAmp unit connected to your PC, and a secondary CalAmp unit
connected to an RTU or PLC at a remote location. In order to collect data from the RTU or PLC, your VTS application
can use an appropriate communication driver tag such as Allen-Bradley or Modicon. If you wish to gather data about
either CalAmp units in such a scenario (e.g. the temperature of the CalAmp unit), your application will require a CalAmp
diagnostic driver tag.
(Characteristics available in the Table of Type Characteristics.)

CalAmp Diagnostic Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

CalAmp Diagnostic Driver Properties: Type Tab

The Type tab of the CalAmp diagnostic driver tag properties folder is used to indicate the type of CalAmp unit that this
tag is to represent. The choices, as shown include:
• Integra-TR
• Integra-H
• Viper SC
• Phantom II

CalAmp Diagnostic Driver Properties: Serial Tab

The Serial tab of the CalAmp diagnostic driver tag properties folder is used to indicate the serial port to which the
CalAmp unit associated with this tag is connected.

Developer's Guide (part 1) How to Build an Application • 295

Port
The Port field enables you to select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag.
The port on the Data Radio unit, from which VTS collects diagnostic information, is a true RS-232 serial port. In order
to connect to this port with VTS, you can use one of several different hardware solutions:
• Serial port cable connected directly.
For this case, configure and select a Serial Port tag.
• Stand alone serial modem connected to the serial port on the radio.
VTS has its own modem that is used to dial up the modem connected to the radio. For this option, configure
and select a serial port that is using a modem.
• Ethernet terminal server connected to the serial port on the radio.
VTS is connected to the same network as the terminal server and can connect to it with either a TCP/IP or
UDP/IP port tag
• RJ-45 Ethernet port on the radio (Viper SC and Phantom II radios only).
Any VTS port tag may be used, but it must match the hardware connection to the radio.

CalAmp Diagnostic Driver Tag Drawing Methods

The following drawing methods are available to display information about your application’s CalAmp diagnostic driver
tags:
Comm Indicator Drawing Method
Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method

296 • How to Build an Application Developer's Guide (part 1)

Plot Data Drawing Method

CalAmp Addressing
Data can be obtained by reading from predefined addresses. The radios generate an ASCII string containing the
diagnostic information.

An analog or digital tag should be configured for each item of diagnostic information. The address structure depends on
the type of radio.
• For Integra-TR and Integra-H, the address format is <radio ID>:<parameter>.
For example, to read supply voltage on radio 3, the address is “3:VOLT”.
• For Viper SC and Phantom II radios, the address format depends on whether the radio is in ROUTER or BRIDGE
mode.
• ROUTER mode: [IP address]:<parameter>
• BRIDGE mode: [MAC address]:<parameter>
For example, with a radio in ROUTER mode, a valid address might be: “[192.168.6.254]:VOLT”.

For Viper SC radios only, the source and destination radio addresses must be specified for the RRSSI and LRSSI
parameters.
For example, a valid address could be “[192.168.1.205],[192.168.2.1]:RRSSI”
Where the source radio is 192.168.1.205 and the destination radio is 192.168.1.2

The following parameters are available:

All radios:
TEMP Internal radio temperature, measured in degrees C.
VOLT The radio supply voltage.
FPOW The forward power, measured in Watts.
RPOW The reverse power, measured in Watts.

Integra-TR and Integra-H radios:

RRSSI The remote received signal strength, measured in dBm.
LRSSI The local received signal strength, measured in dBm.
GRX The number of good data blocks received out of the last 15.
TRX The total number of data blocks detected, up to a maximum o f 15.
Viper SC radios:
RRSSI The remote received signal strength, measured in dBm.
LRSSI The local received signal strength, measured in dBm.
PER The packet error rate.

Phantom II radios:

Developer's Guide (part 1) How to Build an Application • 297

 BRSSI The background received signal strength, measured in dBm.
LRSSI The local received signal strength, measured in dBm.
PER The packet error rate.
THIN The packet thinning value

CIP Driver Tags

The CIP (Control and Information Protocol) driver type is included in VTS version 7.5 and later. These tags provide an
interface between VTS and hardware that uses the CIP and/or ENIP standards for communications.

Notes About Allen Bradley Control Logix Tags

The ControlLogix family of PLCs use tag names to identify data objects in the PLC. The type of data object must be
specified when writing to a particular tag. The ControlLogix family of PLCs supports the following atomic types:
• Boolean (BOOL)
• 8-bit Signed Integer (SINT)
• 8-bit Unsigned Integer (BYTE)
• 16-bit Signed Integer (INT)
• 132-bit Signed Integer (DINT)
• 32-bit Unsigned Integer (DWORD)
• 32-bit Float (REAL)

In addition, 2-dimensional arrays are supported, thus an array of any type listed above is possible:
• DINT[32] – a 32-element array of DINTs.

The ControlLogix family of PLCs also supports a structure. A structure is a collection of these atomic types. For
example, a Timer has the following fields:
• Timer.PRE – DINT
• Timer.ACC – DINT
• Timer.EN – BOOL
• Timer.TT – BOOL
• Timer.DN – BOOL
• Timer.FS – BOOL
• Timer.LS – BOOL
• Timer.OV – BOOL
• Timer.ER – BOOL

The VTS driver can read and write to all of the atomic data types within the structure. The VTS driver can also read a
stream representation of a structure; it does not have any knowledge of the contents of the structure. At present, the
driver cannot write an entire source.
It should be noted that even the atomic data types are themselves structures (of a special sort that can be read and
written). For example, an INT is actually an array of 16 BOOLS, 1 representing each bit in the INT. It is possible to read
and write a bit of an INT by addressing it correctly (i.e. INT_TAG1|INT will write to the least significant bit of
INT_TAG.).
This driver has the ability to save the last value written to each output tag, and to rewrite those values, either
automatically when lost communications are restored, or manually by the press of a button. Carefully review the
information in the Connection tab to decide whether this feature should be used in your application.

298 • How to Build an Application Developer's Guide (part 1)

(Characteristics available in the Table of Type Characteristics.)

CIP Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

CIP Driver Properties: Connection Tab

The Connection tab for a CIP driver enables you to configure the port through which communications with the hardware
will take place.

Note: The TCP/IP Port Tag should be usually be configured to communicate with the PLC on port 44818 (0xAF12). You
should confirm this against your PLC’s configuration.

Port
The Port field enables you to select the TCP/IP tag you wish to be associated with this driver (this will be the TCP/IP tag
that is representative of the physical TCP/IP socket to which the physical PLC or RTU is connected).
The Port field can be used to associate this tag with a new or existing TCP/IP tag using the button. This button opens the
Tag Browser, that displays only the existing TCP/IP tags for your application, and enables you to create a new TCP/IP
tag using its New button.
The Port field can be cleared using the X button that appears to its right.

Port Segment Path

[Port #, Link Address][Port,Addr]…
The Port Segment Path format is [Port ID, Link Address], and describes the path to access the data. The Port ID is a
number which describes the port to access the data. Port ID 1 is defined as the backplane of a PLC. The Link Address is
the address of the item with which to connect.
For example Link Address 0 is Slot 0 of the backplane. If simply connecting to an Ethernet port on a CPU card, this
value parameter should be set to [1,0].

Developer's Guide (part 1) How to Build an Application • 299

Note: You must be familiar with the hardware to which you are connecting in order to correctly establish the Port
Segment Path.

Hold
The Hold checkbox indicates whether this driver should hold data from the PLC or RTU in the event of a
communications failure.
If the Hold checkbox is selected, the last received value from the PLC or RTU will be held.
If the Hold checkbox is not selected, the data will be invalidated in the event of a communications error.
By default, the Hold checkbox is not selected.

Retries
The Retries spin box enables you to select the number of attempts that will be made by this driver if there is no reply to a
message. An error will be declared after this number has been reached.

Store Last Output Values

When checked, the driver will maintain a record of the last value written to each output address. This may be useful in at
least two situations:
• For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
• When failed hardware is replaced by a new device and you would like to start that device with the values last written
to the old one.
If the last output values are stored, they may be re-written by either of two methods:
• Automatically, when communication is restored to the device.
• Manually by way of a button press. See, Rewrite Outputs Drawing Method for details.
Changing this value from checked to un-checked will cause all currently stored values to be erased immediately.

Enable Auto Rewrite

If checked, the Store Last Output Values option will also be activated.
This option causes the driver to automatically rewrite the last value written to each output, in the event that
communications are lost, then restored.
Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in
driver communications.

CIP Driver Properties: Protocol Tab

The Protocol tab for a CIP driver enables you to configure settings related to operation timeouts.

Note: The properties are part of the communications protocol. You must be familiar with the CIP protocols in order to
properly configure them. If the default values for these properties are enabling communications, don't change them.

300 • How to Build an Application Developer's Guide (part 1)

Operation Timeout
Use to specify the time (in seconds) after which the target will abort a request. The default value for Operation Timeout
property is 10 (seconds).

Time Ticks
Use to specify the length of a time tick in milliseconds. (This value should be 2 to the power of n (where the user
supplies n)). The default value for the Time Ticks property is 6.

Number of Time Ticks per Timeout

The Number of Time Ticks per Timeout is the multiplier used by VTS with the Time Ticks value to automatically
calculate the Calculated Transaction Timeout(s) property. The default value for the Number of Time Ticks per Timeout
property is 154.

Calculated Transaction Timeout(s)

The Calculated Transaction Timeout(s) field displays the value that has automatically been calculated by VTS based on
the Time Ticks and Number of Time Ticks per Timeout values.

High Priority Message Flag

If the High Priority Message Flag checkbox is selected, the priority of messages is high and should take precedence over
all else. Otherwise, the priority of messages will be normal.

CIP Driver tag Drawing Methods

The following drawing methods are available to display information about your application’s CIP Driver tags:
Comm Indicator Drawing Method
Comm Statistics Button Drawing Method
CIP Control Drawing Method
CIP Information Drawing Method

Developer's Guide (part 1) How to Build an Application • 301

CIP Statistics Drawing Method
Rewrite Outputs Drawing Method

CIP Driver Addressing

The information provided below is intended to assist you in properly addressing a CIP Driver tag.

Note: When writing to an address in the PLC, a tag modifier must be specified in order to avoid Embedded Service
errors.

Address Description IOI String

Tag_Name Reads the Tag Tag_Name Tag_Name
Tag_Name[n] Reads element n from Array Tag_Name Tag_Name(n)
Tag_Name[n,m] or Reads element m from 2D Array Tag_Name Tag_Name(n)m
Tag_Name[n][m], etc.
Tag_Name.Attribute Reads Attribute from structure Tag_Name Tag_Name Attribute
Tag_Name[n].Attribute Reads Attribute from structure in Array Tag_Name(n) Attribute
Tag_Name, Element n

Examples:

Address Description
SetPoint Read the value of the tag SetPoint.
Analog_Data[4] Read the value of element 4 of the Analog Data Array.
Timers[6].PRE Read the value of the Preset Attribute of the 6th timer in the Timers
Array.
Inputs[5,9] Read the 9th Element of the Inputs 2 dimensional array.

CIP Driver tag Modifiers:

When writing to an address in the PLC, a Tag modifier must be specified. When reading a structure (e.g. a String) the tag
modifier instructs the driver on how to decode the structure. At present only two structure types are supported: string and
structure (which returns a stream representation of the structure, which can be decoded be a custom tag type).

Modifier Description
Address|BOOL Boolean
Address|SINT 8-bit signed integer
Address|INT 16-bit signed integer

302 • How to Build an Application Developer's Guide (part 1)

 Address|DINT 32-bit signed integer
Address|REAL 32-bit Real (float)
Address|DWORD 32-bit collection
Address|STRING String [structure] value
Address|STRUCT Returns a stream of a structure type Tag_Name

CIP Program addressing:

While VTS normally addresses CIP control tags, VTS I/O tags that will use programs in the PLC can access those
programs with the following address format:
PROGRAM:ProgramName.tagname
Where, "PROGRAM:" is a keyword, "ProgramName" is the name of the program in the PLC and "tagname" is the PLC
tag name.

CIP Driver tag Modifiers:

Arrays of BOOLs are addressed differently than other arrays. For example if there is a TestBOOL[200] array defined, it
can be read using TestBOOL.42 (i.e. read element 42).

Data Flow RTU Driver Tags

Available only in VTScada-based applications.
Data Flow RTU drivers are used to provide an interface to a Data Flow RTU. Each Data Flow RTU driver provides for
up to 18 installed Data Flow modules, each of which is represented by a single Data Flow module tag (see Data Flow
Module Tags).

Note: Data Flow RTU driver tags do not require Polling drivers since they have their own polling features.

Operators who do not have configuration privileges, but do have either “tag modify” or “manual data” security privileges
can toggle the active polling state on or off if this tag is drawn as a Comm Indicator on a page. When the operator right-
clicks on the Comm Indicator for the driver, a context menu will open, allowing the Active status to be changed.

When data is written to a Data Flow tag, it is immediately passed to the integrated polling feature and then on to the
associated communication driver tag. Following each write, all I/O addresses will be read immediately so that feedback
need not wait for the next polling cycle.
The Data Flow RTU driver can be represented on a Site Map.
(Characteristics available in the Table of Type Characteristics.)

Data Flow RTU Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.
The Data Flow RTU Driver type includes one extra field on the ID tab: The Station number, also known as the RTU
address.

Developer's Guide (part 1) How to Build an Application • 303

Data Flow RTU Driver Properties: I/O Tab
The I/O tab for a Data Flow RTU driver tag provides properties that can be used to establish a connection between this
tag and the physical Data Flow RTU.

304 • How to Build an Application Developer's Guide (part 1)

Serial Port Name
In order to connect to this port with VTS, you can use one of several different hardware solutions:
• Serial port cable connected directly.
For this case, configure and select a Serial Port tag.
• Stand alone serial modem connected to the serial port on the radio.
VTS has its own modem that is used to dial up the modem connected to the unit. For this option, configure and
select a serial port that is using a modem.
• Ethernet terminal server connected to the serial port on the unit.
VTS is connected to the same network as the terminal server and can connect to it with either a TCP/IP or
UDP/IP port tag
Any type of VTS port tag may be used, but it must match the hardware connection to the unit.

Poll Interval
Enables you to set the amount of time (in seconds or in fractions of a second) between polls of the physical Data Flow
RTU.

Note: If the Active checkbox is not selected, the associated Data Flow RTU will not be polled, regardless of the interval
assigned in the Poll Interval (Sec) field.

Active
Allows you to specify whether the designated poll interval is active or idle.
If the Active checkbox is selected, the associated Data Flow RTU will be polled according to the interval assigned in the
Poll Interval field.
If the Active checkbox is not selected, the associated Data Flow RTU will not be polled, regardless of the interval
assigned in the Poll Interval field.
The active status can also be toggled by the operator if the tag is drawn as a Comm Status indicator. Right-clicking on
that drawing method will open a menu with which the operator can change the active status. When drawn as a SiteDraw,
the outer ring will turn purple when the driver is not active.

No Response Time Limit

Enables you to set the amount of time (in seconds or in fractions of a second) that VTScada will wait when an attempt to
poll the Data Flow RTU has been made.
If no communication is made, the system will attempt to poll the station again, according to the setting in the Retries spin
box. If the system is unable to poll the Data Flow RTU, the next RTU in sequence will be polled.

Retries
The Retries spin box enables you to select a number indicating the amount of times that VTScada will attempt to poll an
unresponsive Data Flow RTU, after which the system will move on to the next Data Flow RTU in the polling sequence.

Full Refresh Time

Allows you to enter a number indicating the amount of time, measured in hours that the system should wait before doing
a full refresh of data values from the Data Flow RTU.

Hold Values on Error

Enables you to specify whether or not data should be held in the event of a communications error with the Data Flow
RTU.

Developer's Guide (part 1) How to Build an Application • 305

If the Hold Values on Error checkbox is selected, the last received value from the Data Flow RTU will be retained
otherwise, the data will be invalidated on error.

Group Poll Supported

Select this box to specify whether or not the Data Flow RTU represented by this tag belongs to a poll group (if group
polling is supported by the radio interface module).

Service Port Connection

If checked, The service port allows communication with the RTU via serial devices (such as Lantronix). It is an
alternative to using the Dataflow RIM card radio. The Dataflow protocol is slightly different through the service port.
Minor differences will be observed, such as all responses being marked as station '0' and the absence of CRCs on
messages that would otherwise have them.

Echo
Used if the Service Port Connection option has been selected. Enable or disable according to whether your device
transmits an echo for each transmit operation.

Data Flow RTU Driver Properties: Modules Tabs

The Modules tabs of the Data Flow RTU driver tag properties folder enables you to select existing (or create new) Data
Flow module tags to represent the Data Flow modules installed for this RTU (see Data Flow Module Tags). You may
associate up to 18 Data Flow module tags with one Data Flow RTU driver.
The modules are divided between the tabs, Modules A-F, Modules G-L and Modules M-0.

Module A, B, etc.
Use the Module fields to identify which module installed at a physical RTU by selecting a Data Flow module tags.
To associate this tag with a set of Data Flow module tags, click the drop-down field to select the appropriate Data Flow
module tag for each module.

306 • How to Build an Application Developer's Guide (part 1)

Data Flow RTU Driver Properties: Display Tab
The Location tab is used to define the placement (latitude and longitude) of the DataFlow station. Decimal values should
be used rather than degrees, minutes and seconds.
You may find it easier to set the location using the map interface than to enter the latitude and longitude values here. See:
Site Map.
You may also define a custom details page to use in the event that you have created one you would prefer over the built-
in Site Details page. Many of the drawing methods available to the DataFlow Driver have their own configuration for
which page is to be opened when clicked. The page selected in the drawing method will have priority over the page
selected in this tab. By selecting a details page here, you set the default to be used by those drawing methods, and for
drawing methods such as the map pin, which does not have any configurable options.
A custom details page should include a tag parameter, named SiteTag, of the same type as this tag. The built-in Site
Details page has two other parameters, which you may consider supporting in your custom page:
A parameter of type Status. This should be tied to the "Use Theme" parameter of any custom drawing methods in the
page.
A parameter of type text, which may be referenced by the TextColor parameter of certain drawing methods.

Related Information:
Site Details Page

Data Flow RTU Tag Drawing Methods (VTScada)

The following drawing methods are available to display information about your application’s Data Flow RTU tags
Active Indicator Drawing Method

Developer's Guide (part 1) How to Build an Application • 307

Comm Indicator Drawing Method
Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Data Age Drawing Method
Data Flow Station Draw Drawing Method
Duplexes Drawing Method
Fast Scan Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method
Polled Station Drawing Method
Site Draw Drawing Method

DDE Driver Tags

The DDE driver allows tags to read from and write to a local or network DDE server.
Specific instructions on configuring VTS as a DDE server and as a DDE client are provided elsewhere in this guide. See
also: Using DDE, and Dynamic Data Exchange.

The DDE acronym represents the term Dynamic Data Exchange; an inter-process communication system built into the
Windows operating systems. DDE enables two running applications to share the same data. For example, DDE makes it
possible to insert a spreadsheet chart into a document created with a word processor; whenever the spreadsheet data
changes, the chart in the document changes accordingly.

(Characteristics available in the Table of Type Characteristics.)

DDE Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

DDE Driver Properties: Local DDE Tab

The Local DDE tab of the DDE Driver tag properties folder is used to indicate the application name for and a topic
supported by the DDE server.

308 • How to Build an Application Developer's Guide (part 1)

DDE Application Name
The DDE Application Name field enables you to enter the DDE program name (i.e. Excel).

DDE Topic Name

The DDE Topic Name field enables you to enter the name of a topic supported by the DDE server.

DDE Driver Properties: Network DDE Tab

The Network DDE tab of the DDE Driver tag properties folder is used to indicate the name of the computer on which the
DDE server is running, and the share name that identifies the DDE server on the computer.

Note: Specific instructions on configuring VTS as a DDE server and as a DDE client are provided in.

Developer's Guide (part 1) How to Build an Application • 309

DDE Computer Name
The DDE Computer Name field enables you to enter the name of the server on which your DDE share (specified in the
DDE Share Name field) was created (e.g. Station9).

DDE Share Name

The DDE Share Name field enables you to enter the name of the DDE share you created on the server specified in the
DDE Computer Name field. You must add the .OLE extension to the name of the DDE share (e.g. DDEShare$.OLE).

Note: Unlike the Modicon, Allen-Bradley, and Omron Host Link drivers|tag=Omron Host Link Driver Tags, the
configuration folder and common routines for the DDE driver cannot be customized.

DDE Driver Tag Drawing Methods

The following drawing methods are available to display information about your application’s DDE Driver tags:
Comm Indicator Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method

DNP3 Driver Tags

This tag is a DNP3 Master, which implements all the objects defined in DNP subset level 3, except for the "Frozen
Counter" type. The driver does not generate "Freeze" requests, or class enable/disable messages. The driver also supports
a number of other objects as listed.
DNP3 Drivers may be configured to accept in-bound connections from an RTU via a configured IP Network Listener
tag. In DNP3 terms this is a 'dual-endpoint' where the IP network listener allows this to be a 'listening endpoint'.
This driver has the ability to save the last value written to each output tag, and to rewrite those values, either
automatically when lost communications are restored, or manually by the press of a button. Carefully review the
information in the Options tab to decide whether this feature should be used in your application.

(Characteristics available in the Table of Type Characteristics.)

DNP3 Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

DNP3 Driver Properties: Serial Tab

The Serial Tab of the DNP3 driver tag properties folder is used to set the parameters used to communicate with the
driver. If the configured port is using a modem for communications to a DNP3 outstation, this tag may be configured to
accept incoming phone calls.

310 • How to Build an Application Developer's Guide (part 1)

Port
Enables you to select the Serial Port tag, TCP/IP tag or UDP/IP Port tag that you wish to be associated with this driver
tag. A Serial Port tag opens a serial port to enable communications between VTS and your PLC or RTU. A TCP/IP or
UDP/IP tag enables you to connect to a series of hosts, allowing you to transmit data across a network or over the
Internet. A port must be configured regardless of whether an IP Network Listener is also configured.
The Port field can be cleared using the X button that appears to its right.

Enable Modem Dial-In

Should be configured only if you expect the RTU to dial in using the VTS Modem Manager. Do not use this option if an
IP Network Listener is configured.

IP Network Listener
Select the configured IP Network Listener tag that has been configured for this driver to accept TCP or UDP
connections. While a TCP connection is open, new connections will be rejected by the DNP3 driver.
If an IP Network Listener is configured, the Port tag must be TCP/IP or UDP/IP and be configured in client socket mode.

IP Allow
Used in connection with an IP Network Listener tag. General IP address filtering should be set on the IP Network
Listener, as this will be more efficient. The list of allowed IP addresses in the driver is intended to prevent misconfigured
devices from interfering with other devices.
Both filters (that in the Network Listener and this one) can be configured at the same time. The filter in the IP Network
Listener will be applied when the device first connects and the local filter will be applied after a specific driver instance
has been identified.

Master Address (VTS)

The station address for VTS. This is the "from" address in messages from VTS to the RTU, and the "to" address in
messages from the RTU to VTS. The range is 0 to 65535.

Developer's Guide (part 1) How to Build an Application • 311

Station Address
The station address for the RTU. The valid range is 0 to 65535.

Time Out Limit

Sets the time in seconds or fractions of a second that this driver should wait for a reply from the remote unit.

RTS Key Off Delay

Sets the amount of time (in seconds) that this driver will wait before dropping RTS at the end of a data transmission.

Retries
The Retries spin box enables you to select the number of attempts that will be made by this driver if there is no reply to a
message. An error will be declared after this number has been reached.

Hold
Select whether this driver should hold data from the PLC or RTU in the event of a communications failure.
If the Hold checkbox is selected, the last received value from the PLC or RTU will be held.
If the Hold checkbox is not selected, the data will be invalidated in the event of a communications error.
By default, the Hold checkbox is not selected.

Data Link Confirm

If set, every low level data link message will be confirmed by an acknowledgement. This option is generally used in an
environment where there are unreliable communications due to the extra non-data traffic sent.

Redundant Multiplexer Connection

Used only in the case that two DNP3 drivers will be subordinate to a Driver Multiplexer. If checked, this setting will
prevent activity if the driver is a DriverMUX inactive subordinate.
Note: This setting is incompatible with the DriverMUX's Parallel or Alternating modes.
When in this mode (option selected, current driver is the inactive subordinate driver) the DNP3 Driver will almost
completely shut down except for periodic checking of its communications link.

DNP3 Driver Properties: Options Tab

The options tab of the DNP3 driver tag properties folder allows you to fine-tune the driver behavior, adjusting it for your
particular hardware.

312 • How to Build an Application Developer's Guide (part 1)

Poll Options – Disable Class x Reads
Disable Class 1, 2 and 3 Reads. Any of these three DNP3 data classes may be disabled independently. A class marked as
disabled will never be read, even if the outstation indicates that class data is available.

Check RTU Interval

The interval (in seconds) at which VTS should check for class 1, 2 and 3 event data in the RTU. This function performs
two tasks: checks that the outstation is still functioning and checks to see if the outstation has an event pending, which
may be read. The outstation's configuration will determine which data changes are reported by events.
If your RTU is configured to spontaneously send values as they change (unsolicited data) you may choose to set the
Check RTU Interval value to a relatively large value, thus minimizing bandwidth while still ensuring that values have
been sent.

Enable Periodic Integrity Poll & Integrity Poll Interval

This option may not be required.
When checked, VTS will send a request for all values every Integrity Poll Interval seconds, even though these values
may not have changed.
An Integrity Poll will read all enabled Class 1, 2, and 3 events (changes) then all Class 0 (current) values. Note that Class
0 values may not include all data types – this depends entirely on the configuration of the DNP3 device.
Regardless of whether the Enable Periodic Integrity Poll option is set, there are three situations when an integrity poll
will always occur:
• When the driver becomes the I/O server.
• When an RTU signals that is has re-started.
• When an RTU signals that event buffers have overflowed.

Unsolicited Data Options – Enable Unsolicited Data

The Enable Unsolicited Data option must be checked for VTS to listen for unsolicited event messages (exceptions) from
the RTU.

Developer's Guide (part 1) How to Build an Application • 313

The configuration of the Allow Unsolicited Communications checkbox in the Serial tab has no effect on this behavior.

Disable Class x Responses

These options are available only when the Enable Unsolicited Data option has been set. Disable Class x Response to
prevent the RTU from spontaneously sending event messages for that class. This affects only unsolicited messages from
the RTU.

Reconnect Action
Allows you to choose what action to take when a connection to an RTU is re-established. The default action is "None"
since the connection is usually re-established by VTS making a Read request. No additional action is required in this
case.
In rare circumstances an RTU may make the connection, then send no data. The Poll For Events option exists so that you
can direct the DNP3 driver to send a request for changed data when this occurs.
In older (pre-10.0.12) versions of the driver, a reconnect would always cause an integrity poll to be done. The Integrity
Poll option exists for legacy application support.

Message Fail Time

The time interval for which VTS will delay a failed message to allow other messages on the same port to be transmitted.
This allows better performance when multiple RTUs share the same port and a message or messages to one RTU are
timing out, thus slowing down communications to all RTUs. Usually set to 0 when there is only one driver using the
port.

Store Last Output Values

When checked, the driver will maintain a record of the last value written to each output address. This may be useful in at
least two situations:
• For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
• When failed hardware is replaced by a new device and you would like to start that device with the values last written
to the old one.
If the last output values are stored, they may be re-written by either of two methods:
• Automatically, when communication is restored to the device.
• Manually by way of a button press. See, Rewrite Outputs Drawing Method for details.
Changing this value from checked to un-checked will cause all currently stored values to be erased immediately.

Enable Auto Rewrite

If checked, the Store Last Output Values option will also be activated.
This option causes the driver to automatically rewrite the last value written to each output, in the event that
communications are lost, then restored.
Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in
driver communications.

Timestamps are in Local Time

Controls how the driver will send and interpret received timestamps from the RTU. If checked, then timestamps are in
local time. If FALSE, then timestamps are in UTC. For most applications, UTC is the proper way to work with
timestamps. The local option exists for compatibility with legacy applications.
The default for the parameter is controlled by the application property, DNP3LocalTimestampsDefault. Existing
applications, upgraded to 10 will default to '1', but new applications will default to '0' (UTC).

314 • How to Build an Application Developer's Guide (part 1)

DNP3 Driver Tag Drawing Methods
The following drawing methods are available to display information about your application’s DNP3 driver tags:
Comm Indicator Drawing Method
Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Gradient Color Change Drawing Method
Numeric Value Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Plot Data Drawing Method
Rewrite Outputs Drawing Method

DNP3 I/O Addressing

See also: DNP object types supported.
Within VTS, DNP I/O addresses for all points except File Identifiers (object 70) are formatted in the following manner:

Obj/Var/Index[:NS | :LATCH | :PULSE]

Where:
• Obj is the DNP object to use. A table of supported object types can be found later in this topic.
• Var is the DNP variation of the object
• Index is the points index. For the Restart flag in the Internal Indications (object 80, var 1) use an index of 7.
• :NS is used to indicate that the point should not be scanned, as its value will be updated either by a DNP event, or
the background class 0 scan. If this option isn’t specified, then the point will be scanned at the rate specified in the
points scan rate field. You must use :NS when reading history data from the device.
• :LATCH is used to indicate the output type is a latched control. If this option isn’t specified the output type is a
trip/raise or close/lower control
• :PULSE is used to indicate the output type is a pulsed control. If this option isn’t specified the output type is a
trip/raise or close/lower control
VTS provides the DNP 3.0 Address Select dialog to help you build these addresses. In any tag that uses a DNP3 driver,
the I/O panel of the configuration dialog will provide a button beside the Address field:

Click this to open the Address Select dialog.

Developer's Guide (part 1) How to Build an Application • 315

To use this dialog, start by selecting the Group designation of the I/O device.
Available groups include:
• Binary Input
• Binary Output Status
• Counter
• Frozen Counter
• Analog Input
• Analog Output Status
• Time and Date
• Internal Indications
• Octet String
If the Direct Poll option is not checked, then (for the appropriate groups) the suffix :NS will be added to the address and
no variations may be applied.
Click the Direct Poll option to allow scanning and to enable the Variation selector, the content of which will vary
according to the selected Group.

Examples:
1) To read a digital input with status (obj 1, var 2) at address 4321 use
1/1/4321.

2) To read a 32 bit delta counter without status (obj 20, var 7) at address 876 use
20/7/876
3) To write a latching digital output to off, (also known as a control relay output block) (obj 12 ,var 1) at address 42 use
12/1/42:LATCH
… sending a value less than 0.

For File Identifiers, I/O addresses are formatted in one of the two following manners:

Outstation Directory Reads

Outstation directories may be read using an I/O address as follows:
70/5/DirectoryPath,READDIR

316 • How to Build an Application Developer's Guide (part 1)

Where:
• DirectoryPath is the path to the directory to be read. This will vary by outstation.
The normal use for this will be from script via a Read command.
Example:
ReadObj = [SomeDriverName]\DriverRead("70/5//data,READDIR", 1, &Result)

ReadObj will go invalid on completion.

Result will be set to an 2D array of directory entries, one row for each entry where the columns are as follows:

[0] Entry name Either filename or a sub-directory name

[1] Entry Type 1 for a file, 0 for a sub-directory
[2] Entry size File length for a file, number of entries for a sub-directory
[3] Timestamp UTC
[4] Permissions* The permissions for the entry
* DNP3 File permissions are a set of 9 bits, indicating read, write and execute permissions for the user, group and world.
Normally written in octal, the value 0777 is "all permissions for all classifications". The exact meaning of the bits is
outstation-dependant.

DNP3 File Writes

Files may be written to the outstation using an I/O address as follows:
70/5/PathToFile[,Timestamp[,Permissions[,Append]]]

Where:
• PathToFile includes the path for the file. This will include forward slashes for directories. The exact path will
depend on the outstation – see example.
• The optional parameter, Timestamp, is the timestamp for the file on the outstation in seconds since 1/1/1970, UTC.
The default is the current time of the I/O server (in UTC).
• The optional Permissions* are the permissions for the file. The default is 0777.
• Append is a flag indicating the behavior of the write if the indicated file already exists on the outstation. If TRUE,
the file will be appended to. If FALSE, the file will be overwritten by the new data. The default is false (no append)

* DNP3 File permissions are a set of 9 bits, indicating read, write and execute permissions for the user, group and world.
Normally written in octal, the value 0777 is "all permissions for all classifications". The exact meaning of the bits is
outstation-dependant.

The normal use for this will be from script via a Write command.
Example:
WriteObj = [SomeDriverName]\Driver\Write("70/5//data/newdata.txt", 1, &FileStrm, Invalid, "SomeText",
&Result)

Result will become valid once the file write has completed - TRUE for success, FALSE for failure. In addition, WriteObj
will become invalid on completion.

Developer's Guide (part 1) How to Build an Application • 317

FileStrm, the data to be written to the outstation file, can be a stream or a buffer. In the example given, the file to be
written to is "/data/newdata.txt". The paths used will depend on the outstation.

DNP3 File Deletions

Files may be deleted from the outstation using an I/O address as follows:
70/5/PathToFile,DELETE

Where:
• PathToFile includes the path for the file to be deleted.
The normal use for this will be from script via a Write command.
Example:
WriteObj = [SomeDriverName]\Driver\Write( "70/5//data/newdata.txt,DELETE", 1, &FileStrm, Invalid, "SomeText",
&Result)

Note that some valid data must be provided as the data parameter (FileStrm) but it's contents are ignored.

DNP object types supported

Please refer to the document, VTS-DNP3-DeviceProfile.pdf, which may be found in the Examples folder of your VTS
installation.

Object Object
Object Description Type Variation Read Write
Single bit binary input all variations 1 0

Single bit binary input 1 1

Single bit binary input with status 1 2

Single bit binary input event all 2 0

variations
Single bit binary input event without 2 1

time
Single bit binary input event with time 2 2

Single bit binary input event with 2 3

relative time
Single bit binary output all variations 10 0

Single bit binary output status 10 2

Control relay output block 12 1 

Binary counter all variations 20 0

32 bit binary counter 20 1

16 bit binary counter 20 2

32 bit delta counter 20 3

16 bit delta counter 20 4


318 • How to Build an Application Developer's Guide (part 1)

 32 bit binary counter without status 20 5

16 bit binary counter without status 20 6

32 bit delta counter without status 20 7

16 bit delta counter without status 20 8

Frozen binary counter all variations 21 0

Frozen 32 bit binary counter with 21 1

status
Frozen 16 bit binary counter with 21 2

status
Frozen 32 bit delta counter with status 21 3

Frozen 16 bit delta counter with status 21 4

Frozen 32 bit binary counter with time 21 5

Frozen 16 bit binary counter with time 21 6

Frozen 32 bit delta counter with time 21 7

Frozen 16 bit delta counter with time 21 8

Frozen 32 bit binary counter no status 21 9

Frozen 16 bit binary counter no status 21 10

Frozen 32 bit delta counter no status 21 11

Frozen 16 bit delta counter no status 21 12

Binary counter event all variations 22 0

32 bit binary counter event without 22 1

time
16 bit binary counter event without 22 2

time
32 bit delta counter event without time 22 3

16 bit delta counter event without time 22 4

32 bit binary counter event with time 22 5

16 bit binary counter event with time 22 6

32 bit delta counter event with time 22 7

16 bit delta counter event with time 22 8

Frozen binary counter event all 23 0

variations
Frozen 32 bit binary counter event 23 1

without time
Frozen 16 bit binary counter event 23 2

without time
Frozen 32 bit delta counter event 23 3


Developer's Guide (part 1) How to Build an Application • 319

 without time
Frozen 16 bit delta counter event 23 4

without time
Frozen 32 bit binary counter event with 23 5

time
Frozen 16 bit binary counter event with 23 6

time
Frozen 32 bit delta counter event with 23 7

time
Frozen 16 bit delta counter event with 23 8

time
Analogue input all variations 30 0

32 bit Analogue input 30 1

16 bit Analogue input 30 2

32 bit Analogue input without status 30 3

16 bit Analogue input without status 30 4

Float analogue input without status 30 5

Double Analogue input without status 30 6

Analogue input event all variations 32 0

32 bit Analogue input event without 32 1

time
16 bit Analogue input event without 32 2

time
32 bit Analogue input event with time 32 3

16 bit Analogue input event with time 32 4

Float Analogue input event without 32 5

time
Double Analogue input event without 32 6

time
Float Analogue input event with time 32 7

Double Analogue input event with 32 8

time
Analogue output all variations 40 0

32 bit Analogue output status 40 1

16 bit Analogue output status 40 2

32 bit Analogue output control block 41 1 

16 bit Analogue output control block 41 2 

Time and Date 50 1

320 • How to Build an Application Developer's Guide (part 1)

 Common Time Object 51 1

Common Time Object - 51 2

unsynchronized
Time delay coarse 52 1

Time delay fine 52 2

Class 0 Event data 60 1

Class 1 Event data 60 2

Class 2 Event data 60 3

Class 3 Event data 60 4

File Identifier (older systems) 70 1


File Identifier (preferred object for 70 5

newer systems)
Internal Indications object 80 1 

Octet String 110 *


Octet Change Object* 111 *

*Event\change objects would not normally be configured as I/O addresses. They are listed to indicate that processing
support is provided them. Upon receiving an event\change object, the value of the corresponding static object will be
updated. For example, if 110/255/6 is configured and an event is received for 111/13/6, then the tag reading the first
address will be updated with the value from the event\change as they share the same index.
Static\event object pairs that follow this rule include:

• g1 Binary Input and g2 Binary Input change

• g10 Binary Output and g11 Binary Output change
• g20 Counter and g22 Counter change
• g21 Frozen Counter and g23 Frozen Counter change
• g30 Analog Input and g32 Analog Input change
• g40 Analog Output and g42 Analog Output change
• g110 Octet Strings and g111 Octet String change

The data values returned for the objects that may be read are listed below:

Object Description Return Value

Single bit binary input 0 or 1.
Single bit binary input with status If status is OK, 0 or 1, else invalid.
Single bit binary input event without If status is OK, 0 or 1, else invalid. See also note below.
time
Single bit binary input event with time If status is OK, 0 or 1, else invalid. See also note below.

Developer's Guide (part 1) How to Build an Application • 321

 Single bit binary output status If status is OK, 0 or 1, else invalid.
32 bit binary counter If status is OK, 32 bit unsigned integer, else invalid.
16 bit binary counter If status is OK, 16 bit unsigned integer, else invalid.
32 bit delta counter If status is OK, 32 bit unsigned integer, else invalid.
16 bit delta counter If status is OK, 16 bit unsigned integer, else invalid.
32 bit binary counter without status 32 bit unsigned integer.
16 bit binary counter without status 16 bit unsigned integer.
32 bit delta counter without status 32 bit unsigned integer.
16 bit delta counter without status 16 bit unsigned integer.
32 bit binary counter event without If status is OK, 32 bit unsigned integer, else invalid. See also
time note below.
16 bit binary counter event without If status is OK, 16 bit unsigned integer, else invalid. See also
time note below.
32 bit delta counter event without time If status is OK, 32 bit unsigned integer, else invalid. See also
note below.
16 bit delta counter event without time If status is OK, 16 bit unsigned integer, else invalid. See also
note below.
32 bit binary counter event with time If status is OK, 32 bit unsigned integer, else invalid. See also
note below.
16 bit binary counter event with time If status is OK, 16 bit unsigned integer, else invalid. See also
note below.
32 bit delta counter event with time If status is OK, 32 bit unsigned integer, else invalid. See also
note below.
16 bit delta counter event with time If status is OK, 16 bit unsigned integer, else invalid. See also
note below.
32 bit Analogue input If status is OK, 32 bit signed integer, else invalid.
16 bit Analogue input If status is OK, 16 bit signed integer, else invalid.
32 bit Analogue input without status 32 bit signed integer.
16 bit Analogue input without status 16 bit signed integer.
32 bit Analogue input event with time If status is OK, 32 bit signed integer, else invalid. See also note
below.
16 bit Analogue input event with time If status is OK, 16 bit signed integer, else invalid. See also note
below.
32 bit Analogue input event without If status is OK, 32 bit signed integer, else invalid. See also note
time below.
16 bit Analogue input event without If status is OK, 16 bit signed integer, else invalid. See also note
time below.
32 bit Analogue output status If status is OK, 32 bit signed integer, else invalid.

322 • How to Build an Application Developer's Guide (part 1)

 16 bit Analogue output status If status is OK, 16 bit signed integer, else invalid.
Time and Date The current date and time in the outstation as a floating-point
number representing the number of milliseconds since Jan 1
1970.
File Identifier A buffer containing the records requested, or an individual
value of the specified type from the specified offset in a
specified record.
Octet String A buffer containing the string.

Note: For events, the return value is an array of five elements:

Index Element
0 The address of the point in the form Object/Variation/Address.
1 Value, after correction for any status flags. If the status is on-line, not
restart and not communication lost, the value will be as reported in the
event; else the value will be invalid.
2 The timestamp of the event.
3 The actual value before correction for status flags
4 The status flags.

For those events that return a time, the time will be as recorded in the device. For those events that do not return a time,
the time will be the local time when the driver received the message.

Time values are returned as a double, representing the time as the number of milliseconds since midnight, on 1/1/1970.

The data values that may be supplied for output objects are listed below:

Object Description Data Value

Control relay output block 32 bit signed integer. If > 0, then action will be a latch on,
close or raise. The time for the raise will be the value
supplied in units of milliseconds. If =< 0, then action will
be a latch off, open or lower. The time for the lower will
be the absolute value supplied in units of milliseconds.
The Latch flag, if TRUE, will cause the output to be a latch
type.
32 bit Analogue output control block 32 bit signed integer.
16 bit Analogue output control block 16 bit signed integer.
Time and Date The data value is ignored. The current date and time of
the VTS system will be sent to the outstation.

Developer's Guide (part 1) How to Build an Application • 323

 File Identifier A buffer containing the records to be written.
Internal Indications 16 bit unsigned integer. Note that only certain values are
allowed and will be detailed in the remote device's
profile.

Note to VTS programmers who are using the DNP3 driver in their code:
The following flags are available in the VTS layer of the driver and will be updated by every response from the remote
station:

Flag Meaning
IINTimeSync TRUE when Time sync is required by the Outstation.
IINLocalDO TRUE when some DO's in the Outstation are in local
control.
IINTrouble TRUE when an abnormal condition exists in the
Outstation.
IINRestart TRUE when an Outstation restart has occurred.
IINEventOverflow TRUE when Outstation event buffers have overflowed.
IINConfigCorrupt TRUE when Outstation configuration is corrupt.
(Characteristics available in the Table of Type Characteristics.)

Driver MultiPlexer Tags

Driver multiplexer (DriverMUX) tags allow you to set up redundant lines of communication between I/O tags and
equipment.
For I/O addressing options, particularly when configured for use with different driver types, see: DriverMUX
Addressing.
Possible uses for this tag include:
• Establishing a fail-over communications route in the event that one system is lost.
In its basic configuration, the DriverMUX tag will direct all communications to the primary driver. In the event
that the connection to the primary driver is lost, communication will switch to the secondary driver.
• Upgrading to new communications equipment/drivers with zero downtime.
In this scenario, you would install the new equipment and drivers while the existing system remains in place.
The new drivers would be connected to the DriverMUX tag instead of directly to your I/O devices. When you
are ready to test the new system, you can direct the DriverMUX to switch to the new, secondary system. If there
are problems, then communication will immediately and automatically switch back to the primary system with
no loss of data.
• Load sharing between two lines of communication.
The DriverMUX tag can be directed to use both communication drivers in either an alternating or an as-ready
basis. While one driver is busy with a large packet, the other can continue to send messages.
• To provide OPC Server redundancy.

324 • How to Build an Application Developer's Guide (part 1)

 A DriverMUX tag may be configured with OPC Client Drivers as subordinates. This will allow I/O tags to
exchange data with any number of OPC Servers.
(Characteristics available in the Table of Type Characteristics.)

Note: If a Polling driver has been configured under a DriverMUX, it will be disabled when it is not the current
subordinate. This has the following effects on your application:
• If there are two Polling drivers under the DriverMUX, only one will function at a time.
• An I/O tag will not read if it is configured to read only from the currently disabled polling driver. This includes both
the case of an I/O tag configured directly below the Polling driver, and an I/O address that is configured explicitly
for a particular driver using the format {}{addr}. (See: DriverMUX Addressing.)
• If one subordinate is a Polling driver, then both subordinates must be Polling drivers.
Allowing for the preceding list of considerations, Polling drivers that are subordinate to DriverMUX tags will work
normally, including those that are part of a polling group.

DriverMUX Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

DriverMUX Properties: Subordinate Drivers Tab

The Subordinate Drivers tab allows you to select the two drivers that the multiplexer will communicate with. Either of
these may be another DriverMUX tag, with its own primary and secondary device drivers.

Developer's Guide (part 1) How to Build an Application • 325

Note: A DriverMUX tag can use a Polling driver for both of its subordinate drivers. Use of a Polling driver for one
subordinate, but not the other, is an unsupported setup and is strongly discouraged.

Primary I/O Device.

One of two device drivers that the DriverMUX tag can switch between. Depending on the purpose you intend use the
DriverMUX tag for, this will normally be the device that will be used for the majority of I/O communications.

Secondary I/O Device.

The other of the two device drivers that the DriverMUX tag can switch between. This could be any of a backup route of
communication, a new system that you are switching to or even another DriverMUX tag, allowing you to configure three
or more redundant lines of communication.

DriverMUX Properties: Modes Tab

The modes tab allows you to define the operation (and thereby the purpose) of the DriverMUX tag. For each of the three
modes, you can select an option from a menu of choices, or you can use a tag or expression to provide external control
over the mode.
If defining a tag or expression to control a mode, note that numbering starts from 0, with the top mode in each list being
the 0 mode. For example, a tag or expression controlling the Selection Mode would need to set the values 0, 1 or 2 for
Automatic, Exclusive Primary and Exclusive Secondary, in that order. If the controlling tag or expression goes to
invalid, then the last known good value will be used.

Selection Mode
Automatic allows the DriverMUX to switch between the primary and secondary drivers, using rules defined in the other
modes. (May be a constant, expression or tag that evaluates to 0.)

326 • How to Build an Application Developer's Guide (part 1)

Exclusively Primary is used when only the driver defined as primary is to be used (May be a constant, expression or tag
that evaluates to 1.)
Exclusively Secondary is used when only the driver defined as secondary is to be used. (May be a constant, expression
or tag that evaluates to 2.)

Sequence Mode
Primary Preferred. In this mode, the primary driver is used for all communication unless it fails, at which point
communication is handled by the secondary driver. When the primary driver comes back online, communication is
transferred back to it. (May be a constant, expression or tag that evaluates to 0.)
Sticky Mode. Similar to Primary Preferred except that communication continues to be handled by whichever driver is
currently in use until that driver fails. Upon failure of the active driver, communication switches to the alternate, where it
remains regardless of whether communication is restored to the driver previously in use. (May be a constant, expression
or tag that evaluates to 1.)
Parallel mode. In this mode, both drivers are used for communication on an as-ready basis. If one driver is busy with a
larger communication packet, the other driver will be used for all packets until the first is ready for another packet. (May
be a constant, expression or tag that evaluates to 2.)
Alternating mode. Both drivers are used in a strictly alternating basis. If the next driver in turn is still busy with its last
communication packet, further communications will be queued until that driver is ready for another packet. (May be a
constant, expression or tag that evaluates to 3.)
Secondary Preferred. In this mode, the secondary driver is used for all communication unless it fails, at which point
communication is handled by the primary driver. When the secondary driver comes back online, communication is
transferred back to it. (May be a constant, expression or tag that evaluates to 4.)

Failover Mode
Failover mode is of use in a remote application where backup servers are configured to handle communications in the
event that a primary server fails.
Switch Drivers First. In the event that communication is lost with the driver currently in use, switch to the alternate
driver. (May be a constant, expression or tag that evaluates to 0.)
Switch Servers First. In the event that communication is lost with the driver currently in use, attempt to switch to a
backup server to re-establish communication with that driver before switching to the alternate driver. (May be a constant,
expression or tag that evaluates to 1.)
Write Mode
By default, the driver multiplexer writes to only the currently active driver. If the drivers are connected to different
hardware devices, then it is possible that one device might not be synchronized with regards to registers that are used as
set points or other controls. This could cause unpredictable results in the case of a hardware fail over.
You have the option of forcing the DriverMUX to write to both devices.
Single Device. The DriverMUX tag writes to the currently active driver only
Both Devices. The DriverMUX tag sends all write requests to both the primary and secondary drivers.

DriverMUX Properties: Settings Tab

In the event of a communication failure, the DriverMUX tag will poll the failed driver at a decreasing frequency,
watching for communication to be restored. This is done to allow communication to be re-established as quickly as
possible in the event of a momentary outage, but to also reduce network load devoted to polling in the event of a longer
outage.

Developer's Guide (part 1) How to Build an Application • 327

Minimum Test Rate (seconds)
The initial frequency at which checks are made to determine a failed driver's state.

Maximum Test Rate (seconds)

The longest period to wait between checks of a failed driver.

Backoff Rate (multiplier)

The time between tests is multiplied by this rate to obtain a progressively slowing frequency between tests until the Max
Test time is reached.

Health Check Rate (seconds)

When the mode is set to Primary Preferred and the primary driver is in use, the secondary driver is tested at this rate to
ensure its availability.

Alternate Failure Triggers

It is possible for a driver to report that it is still working, even though no data is being transferred. An example is a radio
link: All devices may be in perfect working order, but if the antenna is obscured, no data will be transferred. You can use
the Alternate Failure Trigger to monitor some indicator other than the driver itself to determine when the DriverMUX
should switch drivers.
A separate alternate trigger is provided for each driver. Use a tag or an expression that will evaluate to TRUE (1) to
determine when a failure condition can be considered to have happened. An additional field, "Trigger Delay" is used to
set the length of time that the alternate trigger must be true before the DriverMUX will switch drivers. For example, if
monitoring for no data being received, it is necessary to wait several seconds in order to distinguish between a loss of
communications and a pause between messages.

Store Last Output Values

328 • How to Build an Application Developer's Guide (part 1)

When checked, the driver will maintain a record of the last value written to each output address.
If the last output values are stored, they may be re-written by either of two methods:
• Automatically, when communication is restored to the device. Auto-Rewrite must be set on the subordinate drivers
that are to participate in automatic re-writing.
• Manually by way of a button press. Store Last Outputs must also be must also be set on both of the subordinate
drivers. See, Rewrite Outputs Drawing Method for details.
Changing this value from checked to un-checked will cause all currently stored values to be erased immediately.

Ignore Data from Inactive Subordinate

Select this option to discard any data that is being received by the driver that is not the currently active one. The default
behavior when the box is unchecked and the DriverMUX is in "Automatic" mode, is to pass all unsolicited data from
both drivers to input tags.

DriverMUX Tag Drawing Methods

The following drawing methods are available to display information about your application’s DriverMUX tags. Note
that, when the DriverMUX tag is in alternating mode, communication statistics shows only a count of switches.

DriverSelect Drawing Method

Comm Indicator Drawing Method
Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Gradient Color Change Drawing Method
Numeric Value Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Plot Data Drawing Method

DriverMUX Addressing
The address used by an I/O tag may or may not need to change when the DriverMUX tag switches between drivers. The
following three scenarios are provided to help you with I/O addressing.

Scenario 1: Two lines of communication are set up between a PLC in the field and VTS: one
uses radio and the other uses a modem.
In this case, tag addressing is simple: The address is defined by the PLC device and does not change with the
communication driver.

Developer's Guide (part 1) How to Build an Application • 329

Scenario 2: Connecting to different RTUs.
For this scenario, the tag addressing used by the primary driver will be different from that used by the secondary. By way
of example, perhaps one used Allen Bradley equipment and the other uses Modicon.
In this case, an I/O Tag will have to reference its intended data location by two completely different addresses. The
address parameter of the I/O tag must therefore contain both addresses where each address is given inside curly braces
and are given in the order of the Primary and Secondary subordinate drivers.
If (and only if) the DriverMUX is in Parallel or Alternating mode, you can make use of this address format to force an
I/O tag to read from only one of the two drivers. Include both sets of braces, but leave the address blank for the driver
that you do not want to read from.
Ex. {Primary Address}{Secondary Address}

330 • How to Build an Application Developer's Guide (part 1)

Scenario 3: A subordinate driver is also a DriverMUX tag, and each driver requires a different
address for the I/O devices.
In this scenario, the addresses in each I/O tag will be nested in curly braces where the left to right order matches the
primary to secondary configuration of the DriverMUX configuration:

Ex. {Primary Address}{{Secondary Address}{Tertiary Address}}

Developer's Guide (part 1) How to Build an Application • 331

MDS Diagnostic Driver Tags
The MDS diagnostic driver tags enable users to read statistics from any given MDS radio.

Note: MDS diagnostic driver tags are only required in applications where you wish to gather data about an MDS radio.
For example, a common arrangement might be an MDS radio connected to your PC, and a secondary MDS radio
connected to an RTU or PLC at a remote location. In order to collect data from the RTU or PLC, your VTS application
could use an appropriate communication driver tag (e.g. Allen-Bradley or Modicon), however, if you wish to gather data
about either MDS radios in such a scenario (e.g. the temperature of an MDS radio), your application will require an
MDS diagnostic driver tag.

(Characteristics available in the Table of Type Characteristics.)

MDS Diagnostic Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

332 • How to Build an Application Developer's Guide (part 1)

MDS Diagnostic Driver Properties: Serial Tab
The Serial tab of the MDS diagnostic driver tag properties folder is used to indicate the serial port to which the MDS
radio associated with this tag is connected.

Port
The Port field enables you to select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag.
In order to connect to MDS radio port with VTS, you can use one of several different hardware solutions:
• Serial port cable connected directly.
For this case, configure and select a Serial Port tag.
• Stand alone serial modem connected to the serial port on the radio.
VTS has its own modem that is used to dial up the modem connected to the radio. For this option, configure
and select a serial port that is using a modem.
• Ethernet terminal server connected to the serial port on the radio.
VTS is connected to the same network as the terminal server and can connect to it with either a TCP/IP or
UDP/IP port tag
Any type of VTS port tag may be used, but it must match the hardware connection to the radio.

Time-Out Limit
Set the time in seconds or fractions of a second that this driver should wait for a reply from the remote unit.

Retries
Select the number of attempts that will be made by this driver if there is no reply to a message. An error will be declared
after this number has been reached.

Actively Retrieve Values

Indicates that messages should be sent out in active mode, rather than passive mode.
If the Actively Retrieve Values checkbox is selected, messages will be sent out in active mode (i.e. a request for data
from the MDS radio will be immediately sent).

Developer's Guide (part 1) How to Build an Application • 333

If the Actively Retrieve Values checkbox is not selected (default), the data will be sent out in passive mode (i.e. a request
for data from the MDS radio will be held until another request for data from the associated RTU or PLC is made).

MDS Diagnostic Driver Tag Drawing Methods

The following drawing methods are available to display information about your application’s MDS diagnostic driver
tags:
Comm Indicator Drawing Method
Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method

MDS Diagnostic Driver Addressing

MDS radio diagnostic data can be obtained by reading from predefined addresses. Supported models are: TransNET,
x790, x710, and SD series radios.
An analog or digital tag should be configured for each item of diagnostic information of interest. Note that not all radio
models support all diagnostic data. Please refer to the manufacturer’s manuals to find the available diagnostic data for
individual models and the proper radio configuration to enable diagnostics.

The following predefined addresses are available for analog tags:

RSSI.VAL Received signal strength, in dBm. Analog tags with this address should use the following
scaling:

Unscaled Min 136

Unscaled Max 206
Scaled Min -120
Scaled Max -50

SNR.VAL Signal to noise radio, in dBm.

TEMP.VAL Internal radio temperature, in degrees C.
VOLT.VAL Primary supply voltage in mV.
CUR.VAL Primary supply current in mA.
SVOLT.VAL Secondary power supply #1 voltage, in mV.
SVOLT2.VAL Secondary power supply #2 voltage, in mV.
SVOLT3.VAL Secondary power supply #3 voltage, in mV.

334 • How to Build an Application Developer's Guide (part 1)

TXFPOW.VAL Transmit forward power, in dBm.
TXRPOW.VAL Transmit reverse power, in dBm.
LNACUR.VAL Low Noise Amplifier current, in mA.

The following predefined addresses are available for digital tags (0 = OK, 1 = BAD):
RSSI.ERR RSSI status
SNR.ERR SNR status
TEMP.ERR Temperature status
CUR.ERR Primary supply current status
SVOLT.ERR Secondary power supply #1 voltage status
SVOLT2.ERR Secondary power supply #2 voltage status
SVOLT3.ERR Secondary power supply #3 voltage status
TXFPOW.ERR Transmit forward power status
TXRPOW.ERR Transmit reverse power status
LNACUR.ERR Low Noise Amplifier current status

The address structure is <radio unit #>:<address>.

For example, to read supply voltage on radio 3258, the address is “3258:VOLT.VAL”.

Modbus Driver Tags

See: Modicon Driver Tags

Modicon Driver Tags

The Modicon driver provides an interface to a Modicon PLC, allowing communication via:
• Serial RTU
• Serial ASCII
• SA-85 I/O card for ModBus Plus communications
• Embedded TCP/IP
• Open Modbus TCP
This driver has the ability to save the last value written to each output tag, and to rewrite those values, either
automatically when lost communications are restored, or manually by the press of a button. Carefully review the
information in the Options tab to decide whether this feature should be used in your application.
The number of bytes in a Modbus message may be limited by adding the following application property:
ModiconVTSMaxBlock. By default, this is 125. See: Set Application Properties.

(Characteristics available in the Table of Type Characteristics.)

Modicon Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.

Developer's Guide (part 1) How to Build an Application • 335

The properties of the ID tab are described in the topic: The ID Tab.

Modicon Driver Properties: Options Tab

The Options tab of the Modicon Driver tag properties folder can be used to set byte swapping for long integer, IEEE
single or IEEE double bytes. If this driver is communicating over a modem, then the Options tab is also used to indicate
that squelch noise should be suppressed, if present.

Comm Channel
The Comm Channel section enables you to select a radio button indicating the communication channel and protocol to
use for this Modicon driver. The default communications protocol is Serial RTU. This will be one of:
• Serial RTU Select to use the RTU mode of the Modbus serial communications standard.
• Serial ASCII Select to use the ASCII mode of the Modbus serial communications standard.
• SA-85 (MB+) Select to use the Modbus Plus communications protocol via a Modicon SA-85 card.
• Embedded TCP/IP Select to use the Embedded TCP/IP protocol.
• Open Modbus TCP Select to use the Modicon Open Modbus/TCP specification to receive Modbus protocol over
Ethernet TCP/IP.

Squelch Noise Present

Applies when communicating over a modem. Check this box to enable the squelching of background noise. By default,
the Squelch Noise Present checkbox is not selected.

Reverse Long Integer Byte

Allows you to select whether or not byte swapping should occur for long integer values.
By default, the Reverse Long Integer Byte checkbox is not selected.

Reverse IEEE Single Byte

Allows you to select whether or not byte swapping should occur for IEEE single byte values.
By default, the Reverse IEEE Single Byte checkbox is not selected.

336 • How to Build an Application Developer's Guide (part 1)

Reverse IEEE Double Byte
Allows you to select whether or not byte swapping should occur for IEEE double byte values.
By default, the Reverse IEEE Double Byte checkbox is not selected.

Force Multi Element Write OpCodes

Certain hardware requires data to be written using multi-element OpCodes (15 and 16) even though the actual data is
single-element (OpCodes 5 & 6). By checking this box, you can ensure that this driver instance is able to communicate
with devices that require the multi-element codes.

Store Last Output Values

When checked, the driver will maintain a record of the last value written to each output address. This may be useful in at
least two situations:
• For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
• When failed hardware is replaced by a new device and you would like to start that device with the values last written
to the old one.
If the last output values are stored, they may be re-written by either of two methods:
• Automatically, when communication is restored to the device.
• Manually by way of a button press. See, Rewrite Outputs Drawing Method for details.
Changing this value from checked to un-checked will cause all currently stored values to be erased immediately.

Enable Auto Rewrite

If checked, the Store Last Output Values option will also be activated.
This option causes the driver to automatically rewrite the last value written to each output, in the event that
communications are lost, then restored.
Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in
driver communications.

Modicon Driver Properties: Serial Tab

The Serial tab for the Modicon Driver tag properties folder consists of attributes used to identify and establish a
connection to the Modicon I/O device.

Developer's Guide (part 1) How to Build an Application • 337

Port
Enables you to select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag. A Serial Port tag
opens a serial port to enable communications between VTS and your PLC or RTU. A TCP/IP tag enables you to connect
to a series of hosts, allowing you to transmit data across a network or over the Internet.
The Port field can be cleared using the X button that appears to its right.

IP Network Listener
Select the configured IP Network Listener tag that has been configured for this driver to accept TCP or UDP
connections. If the IP Network Listener is configured, this driver must use Open Modbus TCP, configured on the
Options tab.

IP Allow
Used in connection with an IP Network Listener tag. General IP address filtering should be set on the IP Network
Listener, as this will be more efficient. The list of allowed IP addresses in the driver is intended to prevent misconfigured
devices from interfering with other devices.
Both filters (that in the Network Listener and this one) can be configured at the same time. The filter in the IP Network
Listener will be applied when the device first connects and the local filter will be applied after a specific driver instance
has been identified.

PLC Address
The station address of the Modicon programmable logic controller. By default, the PLC Address field is set to 1.
An expression may be used to provide the address if needed. This may be required on a network where the address varies
depending on the workstation where the tag is running.
Note that, to create a valid expression for an address that contains non-numeric characters, you must enclose the address
in quotation marks. e.g. “31.0.0.0” See: Modbus Plus PLC Addressing.

Time-Out Limit

338 • How to Build an Application Developer's Guide (part 1)

Allows you to set the receiver time-out limit in seconds or fractions of a second. This is the length of time that this driver
should wait for a reply from the PLC or RTU.

Port
Enables you to select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag. A Serial Port tag
opens a serial port to enable communications between VTS and your PLC or RTU. A TCP/IP tag enables you to connect
to a series of hosts, allowing you to transmit data across a network or over the Internet.
The Port field can be cleared using the X button that appears to its right.

Squelch Time
Sets the amount of time (in seconds or in fractions of a second) to wait before clearing noise. Enabled only when Squelch
Noise Present has been selected on the Options tab.

Retries
The Retries spin box enables you to select the number of attempts that will be made by this driver if there is no reply to a
message. An error will be declared after this number has been reached.

Hold
The Hold checkbox selects whether this driver should hold data from the PLC or RTU in the event of a communications
failure.
If the Hold checkbox is selected, the last received value from the PLC or RTU will be held.
If the Hold checkbox is not selected, the data will be invalidated in the event of a communications error.
By default, the Hold checkbox is not selected.

Retry Delay
The Retry Delay field enables you to specify the amount of time (in seconds or fractions of a second) that the driver will
wait between attempts to repeat a transmission of data if the previous attempt(s) have failed.
By default, the Retry Delay field is set to 0 (indicating that there should be no delay between retry attempts).

RTS Key Off Delay

The RTS Key Off Delay field represents the amount of time (in seconds) that this Modicon driver will wait before
dropping RTS at the end of a data transmission.

Modicon Driver Properties: Modbus Plus Tab

The Modbus Plus tab of the Modicon Driver tag properties folder is used when an SA-85 I/O card for ModBus Plus
communications has been configured.

Developer's Guide (part 1) How to Build an Application • 339

SA-85 Adapter Number
The SA-85 Adapter Number section enables you to specify the number of the adapter if you have installed an SA-85
network adapter card for Modbus Plus communications networks. You can specify adapter 0, adapter 1, or none by
selecting the associated radio button. The default setting for the SA-85 Adapter Number section is None.

SA-85 Polling Rate

The SA-85 Polling Rate section enables you to indicate the rate in seconds or fractions of a second at which you wish the
SA-85 network adapter card to be polled. The default SA-85 Polling Rate setting is 0.025.

Retries
The Retries spin box enables you to select the number of attempts that will be made by this driver if there is no reply to a
message. An error will be declared after this number has been reached.

Time Out (x500mS)

The Time Out (x500mS) spin box enables you to specify the message response time limit that the driver will wait for a
reply from the PLC. This time limit may be set from 1 to 20 increments. The default setting for the spin box is 2 (i.e. two
500 millisecond increments, or 1 second).

Maximum Paths Open

The Maximum Paths Open spin box enables you to indicate the maximum number of Modbus Plus sessions that can be
opened simultaneously by the installed SA-85 network adapter. The Maximum Paths Open spin box may be set from 1
to 8. The default setting for the Maximum Paths Open spin box is 8.

Modicon Driver Properties: Virtual I/O Tab

The properties of the Virtual I/O tab of the Modicon Driver tag properties folder are used to configure a virtual PLC in
the memory of your PC.

340 • How to Build an Application Developer's Guide (part 1)

Modicon Virtual PLC Input Coils can be written to, on a local machine.

Holding Coils 0xxxx (0-999)

The Holding Coils 0xxxx (0-9999) field sets the number of 00000-series holding coils in the virtual PLC.

Input Coils 1xxxx (0-9999)

The Input Coils 1xxxx (0-9999) field sets the number of 10000-series input coils in the virtual PLC.

Input Registers 3xxxx (0-9999)

The Input Registers 3xxxx (0-9999) field sets the number of 30000-series input registers in the virtual PLC.

Holding Registers 4xxxx (0-9999)

The Holding Coils 4xxxx (0-9999) field sets the number of 40000-series holding registers in the virtual PLC.

Listen on Channel x
The Listen On Channel 1 through 8 checkboxes allow you to select the channels of the Modbus Plus network to which
the virtual PLC should listen. Please note that these do not apply to serial or TCP/IP connections.

Note: Please refer to Modicon Driver Addressing for information on Modicon addressing formats.

Modicon Driver Tag Drawing Methods

The following drawing methods are available to display information about your application’s Modicon Driver tags:
Comm Indicator Drawing Method
Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method

Developer's Guide (part 1) How to Build an Application • 341

Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method
Rewrite Outputs Drawing Method

Modicon Driver Addressing

The allowable range of addresses is dependent upon the device with which you are communicating. For example, a PLC
may only have 500 holding registers, and thus it can only address either 40001 through 40501, OR 400001 through
400501 (whichever you prefer), even though the protocol allows for addresses much higher than this.
The table below identifies the value ranges for Modicon outputs, inputs, input registers, and holding registers.

I/O Type Text Prefix 5 digit address 6 digit address

Holding Coil HC1 - HC65536 00001 – 09999 000001 – 065535
Input Coil IC1 - IC56636 10001 – 19999 100001 – 165535
Input Registers IR1 - IR65536 30001 – 39999 300001 – 365535
Holding HR1 - HR65536 40001 – 49999 400001 – 465535
Registers
Data Logger DL1:1 – DL16:8

Note: when using numeric addressing, the leading digit is significant as it determines the I/O type. Any 4 digit numeric
address will be used as a Holding Coil address.

Older applications may have been configured using the text prefix addresses such that they were 0-based, i.e. the first
holding coil was at HC0. To permit old applications to work correctly, an application property flag
(ModiconTypedAddr1Offset) is used to set the base for text prefix addresses. The flag will default to 1-based (flag is
FALSE).

Bit Addressing
An individual bit in a register (either an Input Register or a Holding Coil) may be read or written (for Holding Coils) by
appending the address with "/x" where x has a value from 0 to 15 and indicates which bit is to be used. For writes, a
read\modify\write cycle is used on the register as the Modicon protocol does not have a bit operation function.
If you are working with long integers, append the text "/sdword" after the bit number. For example: "40050/1/sdword".

Float Addressing
If required, you can use floating point addressing with VTS. The process will require an adjustment to the way the
address is provided in order to reach the correct register.
Modicon registers are 16 bits wide. In order to get a float address you will need to read 2 sequential registers to get 32
bits. To do this, you will need to know the lowest register address of the pair. Note that this may be odd or even and
differs by device.
The address will be formed by entering the lowest address of the pair with the suffix of /FLOAT. e.g. IR9/FLOAT will
read the register pair at IR9 and 10, and return the combined value as a float.
Note that driver options determine how the 4 bytes in the combined register pair are ordered to form the float as this will
differ by device.

342 • How to Build an Application Developer's Guide (part 1)

Modicon Driver Addressing: Modicon Driver Tag Properties
Modicon Driver Tag
Properties Folder Tab Property Value
Options Tab Comm Serial RTU
Channel
Serial Tab PLC Address 1
Serial Tab Time-Out 0.5 (Make it shorter if Scan Interval
Limit is going to be very short)
Serial Tab Port COM2 (name of Serial Port tag)
Serial Tab Retry Delay 0
Serial Tab Hold deselected
Serial Tab Retries 2
Serial Tab RTS Key Off 0
Delay

Modicon Driver Addressing: Serial Port Tag Properties

Serial Port Tag Properties
Folder Tab Property Value
Settings Tab Port Number 2
Settings Tab Data Bits 8
Settings Tab Stop Bits 1
Settings Tab Baud Rate 9600
Settings Tab Parity No Parity
Settings Tab Echo deselected
Settings Tab RTS Keying deselected
Settings Tab Key Up Delay 0.1

Note: For a list of all available data type suffixes that can be used for tag I/O addresses, please refer to Data Type
Suffixes for Tag I/O Addresses.

Modbus Plus PLC Addressing

When communicating using Modbus Plus, request packets may have to be routed across various BP85 Bridge Plus
devices in order to reach the intended PLC. The routing information is stored as part of the PLC address.

Developer's Guide (part 1) How to Build an Application • 343

Since VTS workstations that are located on different subnets will have to be routed through intervening BP85 Bridge
Plus devices, it is therefore necessary that the PLC address of the Modicon Driver tag to be resolved based on the
workstation the tag is running on.

The expression to use for the PLC address of PLC (x) in the above example might be as follows:

ToUpper(\Code\RPCManager\WkStnName) == "SERVER_B" ? “20.10” : “10”

This code says that, if the address is being resolved from server B, then use “20.10”, otherwise use “10”. The following
illustration shows how this would look in your tag configuration panel.

SCADAPack History Read

The VTS Modbus supports the reading of data from data loggers created by Control Microsystems RTU's that have been
configured to store data using DLOG functions.

344 • How to Build an Application Developer's Guide (part 1)

For example, you may have a Control Microsystems driver which is saving data once per minute using DLOG functions.
To configure VTS to read the data once per hour, you can use the SCADAPack History Read as described in the
following notes.

Configuring the Control MicroSystems RTU

Note: the following provides minimal information required to use Control Microsystems devices with VTScada. For
more information on the RTU's, please refer to the TelePACE Ladder Logic manual

A necessary first step is to program the RTU driver to use the DLOG functions. The DLOG functions can log 8 fields
from any of 16 loggers.
For each set of 8 fields, VTScada requires one to be configured as a "Date and Time" field. It does not matter which field
is used for this purpose or even whether more than one is configured as "Data and Time". VTScada will simply use the
first one found in numerical order.

For the other fields, VTScada supports any of the data types that Control MicroSystems uses.

Configuring VTScada

To retrieve data from history, you must use either the Analog Status tag or the Digital Status tag. These two tags are able
to read both current data and historical data.

Using Analog Status tags

The format for the history address must be in the format "DLx:y” where x is the number of the logger and y is the field
within that logger.
Thus, to read from field 3 of logger 1 the address would look like "DL1:3".

The history scan interval is measured in seconds and can be any integer value you wish. For example, to read every hour
you would enter 3600.

Developer's Guide (part 1) How to Build an Application • 345

Note: While it would be unusual, you are also able to enter an address for direct analog input, reading at a different
interval frequency.

Tag Value:
If an address has been defined (standard address - not history address), the value coming from this address will always be
used to set the tag value, regardless of whether or not a history address is also defined.
If only a history address has been defined, and if the value read from the data logger has a newer timestamp than the tag's
current timestamp, then the value read from history will be used as the tag's value.

Varying History Scan Intervals

Should you attempt to set different history scan intervals for the different fields within one logger, VTS will force all the
tags associated with that logger to read at the same time. This time will be the smallest of the varying history scan
intervals.

Scaling
A useful technique for maximizing the data being stored by the RTU is to not scale it at the logger level, leaving it as a
two byte integer. Scaling will be done in VTS after reading from the logger, using the tag's scaling properties.

Note: The tag performs a destructive read. Once the data has been read and saved, a log purge will be performed.

Using Digital Status tags

Digital Status tags are configured the same way as Analog Status tags with the exception of the format used in the
history address field. For Digital Status tags this takes the form: DLx:y/b where the /b indicates the bit number within the
address. Thus, bit 0 of field 3 of logger 1 would be addressed as DL1:3/0.
By using individual bits, each field in the logger can store as many as 32 digital values, thus maximizing storage in the
RTU.

346 • How to Build an Application Developer's Guide (part 1)

You must check the Read History box in the I/O tab in order to see where to put the address.
Note that the appearance of the Digital Status tag's I/O tab will change when the Read History box is checked as shown:

Motorola ACE Driver Tags

The Motorola ACE driver should be used for all Motorola ACE / Moscad RTUs in your system.
Requires a Motorola IP Gateway tag, and the Motorola table configuration file, MDLC_TYP.CFG, which lists the
possible RTU table configurations. See: Motorola IP Gateway Tags.

Motorola ACE Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Motorola ACE Driver Properties: Settings Tab

The settings tab is used to define the communication parameters to your Motorola ACE RTU. The IP Gateway device
will handle retries and timeouts. No field exists in this driver to allow a retry specification. Time limit values are
provided only as a fall-back in the case that the IP Gateway does not handle the time limit.

Developer's Guide (part 1) How to Build an Application • 347

Motorola IP Gateway
The name of a configured Motorola IP Gateway tag. The first such parent found will be used automatically.

RTU ID
The identifier of the MDLC network that the RTU device was configured with.

RTU Type
Should match the RTU type, as specified in the API configuration file. This name will be found immediately after the
keyword, "Type", and just before the table definitions.

RTU Status Interval

The period between RTU status polls.

Burst Refresh Interval

The burst refresh poll interval. Used to cause a read poll to occur at a regular interval while the driver is using burst
mode and polling would otherwise be disabled.

Read Time Limit

The IP Gateway device configuration provides the time-outs to be used. The value in this field is only to provide a fail-
safe in the event that the usual time-out limit fails to work for read operations.

Write Time Limit

The IP Gateway device configuration provides the time-outs to be used. The value in this field is only to provide a fail-
safe in the event that the usual time-out limit fails to work for write operations

Hold

348 • How to Build an Application Developer's Guide (part 1)

Controls whether this driver should hold data from the RTU in the event of a communications failure.
If the Hold checkbox is selected, the last received value from the RTU will be held.
If the Hold checkbox is not selected, the data will be invalidated in the event of a communications error.
By default, the Hold checkbox is not selected

Motorola ACE Tag Drawing Methods

The following drawing methods are available to display information about your application’s Motorola ACE driver tags:
Comm Indicator Drawing Method
Comm Stats Button Drawing Method
Numeric Value Drawing Method

Motorola ACE Driver Addressing

Addressing uses the following form, where T, R and C are zero-based integers, and B is the letter B.
[B]T:R:C
Where...
• The letter B is optional, as indicated by the square brackets. (Do not type the brackets in an address.) If present, this
indicates that the driver should wait for unsolicited data to be pushed out from the RTU, rather than the driver
polling the RTU.
• T is the table number to use in the MDLC_TYP.CFG file.
• R is the row number to use in the MDLC_TYP.CFG file.
• C is the column number to use in the MDLC_TYP.CFG file.
Examples:
0:1:2
Designates Table 0, Row 1, Column 2 in polling mode, since the B is not present.

B3:2:1
Designates Table 3, Row 2, Column1 in Burst mode.
Burst mode may only be used if the RTU was programmed to communicate this way. Simply adding the B to the address
will not cause the RTU to push updates.
Burst mode applies only to data reads. After an initial poll the driver will wait for the RTU to report a change. The burst
option is ignored for data writes. A burst refresh interval is provided in order to periodically perform an explicit poll of
the RTU.

Omron Host Link Driver Tags

The Omron Host Link driver provides an interface to an Omron PLC via a serial port.

Note: The Omron driver requires that the PLC be in Monitor mode in order for writes to work.

This driver has the ability to save the last value written to each output tag, and to rewrite those values, either
automatically when lost communications are restored, or manually by the press of a button. Carefully review the
information in the Serial tab to decide whether this feature should be used in your application.
(Characteristics available in the Table of Type Characteristics.)

Developer's Guide (part 1) How to Build an Application • 349

Omron Host Link Driver Properties: ID Tab
The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Omron Host Link Driver Properties: Serial Tab

The Serial tab for the Omron Host Link driver tag properties folder consists of attributes used to identify and establish a
connection the Serial Port tag that the Omron Host Link driver should use to transmit data to the I/O device. The Serial
tab is also used to select the communication protocol to be used in transmissions of data between the I/O device and the
driver.

Port
Enables you to select the Serial Port tag or TCP/IP tag you wish to be associated with this driver tag. A Serial Port tag
opens a serial port to enable communications between VTS and your PLC or RTU. A TCP/IP tag enables you to connect
to a series of hosts, allowing you to transmit data across a network or over the Internet.
The Port field can be cleared using the X button that appears to its right.

Time-Out Limit
Sets the receiver time-out limit (i.e. the time in seconds or fractions of a second that this driver should wait for a reply
from the PLC or RTU).

Hold
Controls whether this driver should hold data from the PLC or RTU in the event of a communications failure.
If the Hold checkbox is selected, the last received value from the PLC or RTU will be held.
If the Hold checkbox is not selected, the data will be invalidated in the event of a communications error.
By default, the Hold checkbox is not selected.

Point To Point
Select whether the Point To Point protocol to be used by the Omron Host Link driver in communications with the PLC.
If selected, the driver will use point-to-point protocol (PPP) to communicate with the PLC.

350 • How to Build an Application Developer's Guide (part 1)

If the Point To Point checkbox is not selected, the driver will use multi-drop protocol.
By default, the Point To Point checkbox is not selected.

Station
Enter the PLC station address in this field.

Retries
Select the number of attempts that will be made by this driver if there is no reply to a message. An error will be declared
after this number has been reached.

Store Last Output Values

When checked, the driver will maintain a record of the last value written to each output address. This may be useful in at
least two situations:
• For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
• When failed hardware is replaced by a new device and you would like to start that device with the values last written
to the old one.
If the last output values are stored, they may be re-written by either of two methods:
• Automatically, when communication is restored to the device.
• Manually by way of a button press. See, Rewrite Outputs Drawing Method for details.
Changing this value from checked to un-checked will cause all currently stored values to be erased immediately.

Enable Auto Rewrite

If checked, the Store Last Output Values option will also be activated.
This option causes the driver to automatically rewrite the last value written to each output, in the event that
communications are lost, then restored.
Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in
driver communications.

Omron Host Link Driver Tag Drawing Methods

The following drawing methods are available to display information about your application’s Omron Host Link driver
tags:
Comm Indicator Drawing Method
Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method
Rewrite Outputs Drawing Method

Omron Addressing
The addressing for Omron C-Series PLCs in VTS is made up of two parts, the memory area and the address. The address
string is made up of a two-letter memory designator and an unsigned integer value as outlined in the table below.

Developer's Guide (part 1) How to Build an Application • 351

Although the Host Link protocol does not support bit reads or writes, VTS does support bit addressing when writing or
reading the word registers. Caution should be exercised when writing bits because all bits in the affected register will be
written.
The addressing for Omron Host Link driver bits supports the period ( . ) separator, as well as the backslash character ( / ),
enabling the use of the standard addressing format utilized by Omron.
The bit address is an optional part of the address string. A complete address for an Omron C-Series PLC would be in the
following format:
MMdddd[/BN]

Where MM is taken from the first column in the table below, dddd is the register number, and BN is the optional bit
number.
The table below identifies the addressing values for Omron C-Series PLCs.

Channel
Prefix Description Digits Channel Bit
AR Auxiliary Relay 2 Yes Yes
TC Timer/Counter 3 Present Value Status (don't add digits)
T Timer 3 Present Value Status (don't add digits)
C Counter 3 Present Value Status (don't add digits)
DM Data Memory 4 Yes No
HR Holding Relay 2 Yes Yes
IR Internal Relay 3 Yes Yes
LR Link Relay 2 Yes Yes
SR Special Relay 3 Yes Yes
TR Temporary Relay 0 No Yes
EM Extended Memory 4 Yes No

Examples of Omron Addressing:

DM120
HR98/2
AR120/15

The data types of the Omron registers are set by appending one of the strings listed below to the end of the address
string:
"/UWORD"
"/UDWORD"
"/SWORD"
"/SDWORD"
"/BCD4"

The default data type is unsigned word integer.

Note: For a list of all available data type suffixes that can be used for tag I/O addresses, please refer to Data Type
Suffixes for Tag I/O Addresses.

352 • How to Build an Application Developer's Guide (part 1)

OPC Client Driver Tags
By adding OPC Client Driver tags to your application, you are able to communicate with OPC servers on your network,
whether those are other VTS applications, control equipment or other programs. The OPC interface allows for two-way
communication, thus you can go on to add both input and output tag types that exchange information with the OPC
server through the OPC client drivers you configure.
Please review the information provided in the chapter, OPC Configuration in VTS.

Note: If you have used the OPC client driver in versions of VTS prior to 8.1, you may expect to see a field for the
Automation ProgID. With the introduction of Trihedral's own OPC Automation DLL, which is used by default, you no
longer need to provide this information.

If updating an older application that did include Automation ProgID information, the existing id will still be
used, but will not be visible in the tag's configuration dialog.

(Characteristics available in the Table of Type Characteristics.)

OPC Client Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

OPC Client Driver Properties: OPC Tab

The OPC tab for the OPC Client driver tag properties folder consists of attributes used to identify and establish a
connection to the control device to be associated with this driver. The OPC tab for an OPC Client driver is also used to
identify the remote server node that the driver should use to transmit data.
Please review the information provided in the chapter, OPC Configuration in VTS.

Server Prog ID
The Server Prog ID field enables you to specify the program identifier (ProgID) for the OPC server to which you wish to
connect. This will be a string of the form Manufacturer.OPC.ServerType.

Developer's Guide (part 1) How to Build an Application • 353

Examples of a Server Prog ID are: Trihedral.VTSOPC.DA or Matrikon.OPC.Modbus.

Note: The OPC Server vendor generally supplies the Server Prog ID; please refer to your OPC Server manufacturer's
documentation for the correct details.

Remote Server Node

Use this field to specify the name of the workstation that is acting as the OPC server. The Remote Server Node field can
be left blank in the event that the local workstation is the OPC server.

Analog Deadband (% of full scale)

The Analog Deadband spin box enables you to indicate a percentage by which analog values must change before a
change in value is reported. If the percentage is 0, the updates will be event driven, occurring on each value change.

Hold
In the event of an interruption in communication, this option will cause the last good value to be held. You should use
this option with caution since, unless there is another means to alert you to interruptions in communication, it will appear
that a valid value is still being received.

OPC Client Driver Tag Drawing Methods

The following drawing methods are available to display information about your application’s OPC Client Driver tags:
Comm Indicator Drawing Method
Comm Statistics Button Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method

OPC Client Driver Addressing

The VTS OPC Address Select tool, found in every I/O tag that uses an OPC Client driver, will help you build addresses
for your I/O tags.

Clicking the OPC button opens the OPC Address Select tool. (Example shows a client connected to the Trihedral OPC
Server – your display will vary depending on the server that your OPC Client is using. )

354 • How to Build an Application Developer's Guide (part 1)

Using the Address Select tool, you can quickly navigate through the nodes to the OPC item that you wish to use.

Note that for the VTS OPC Server, there is no leaf for the "Value" of a tag. The tag node itself has the value attached.

The following is a basic example (not using the OPC Address Select tool) of using an OPC Client driver tag to read data
from an Omron C200H PLC via an OPC Server (in this example, an INGEAR Omron OPC Server version 2.25.0.1).

Note: There is no standard for OPC driver addressing. The following example covers only one possible configuration.
For your application, the definitive guide to OPC addressing will always be the documentation for the OPC Server in
use.

On the OPC Server (using the user interface provided by the manufacturer of the OPC
Server):
1. Create a device named Omron.
4. Create a group named MyGroup.
5. Create two items, Tag1 and Tag2.
6. Configure the tags with the correct addressing information for connecting to the Omron PLC.

VTS OPC Client Driver Tag Properties:

OPC Client Driver Tag

Properties Folder Tab Property Value
OPC tab Server Prog ID CimQuest.IGOMOPC.1

VTS Input Tag Properties (Analog Input or Digital Input)

Enter the address Omron.Group.Tag1 in the Address field for the VTS input tag that will read data from the Tag1 item
on the OPC Server.

Developer's Guide (part 1) How to Build an Application • 355

Enter the address Omron.Group.Tag2 in the Address field for the VTS input tag that will read data from the Tag2 item
on the OPC Server.
Note that the addresses entered for the above VTS input tags are based on the syntax:
DeviceName.GroupName.ItemName

Note: For a list of all available data type suffixes that can be used for tag I/O addresses, please refer to Data Type
Suffixes for Tag I/O Addresses.

OPC Server Setup Tags

Note: Use of the OPC Server Setup tag is restricted to VTS installations that include this feature as part of the license
key. You can confirm whether this feature is enabled by opening the About VTS dialog from the VTS Application
Manager.

Server Name: Trihedral.VTSOPC.DA

The VTS OPC Server supports the OPC DA (Data Access) Standard.
The OPC Server Setup tag is used to turn your application into an OPC Server. Minimal VTS configuration is required
on your part to do this.

Note: OPC security is handled by Windows via user and group security permissions set using the Microsoft Component
Services dialog and the COM Security tag of the My Computer dialog. Please refer to Securing an OPC Server for more
information on OPC security.

Only one OPC server may be defined per application. Attempting to define a second server in the same application will
result in an error dialog stating "An application can have at most one OPC Server Setup tag".

Note: Use of the same namespace for more than one application is strongly discouraged as it will cause significant
problems.

There are no drawing methods for this tag. When the OPC Server Setup tag has been created, the application’s OPC-
supporting tags become available on the VTS OPC server.
Please review the information provided in the chapter, OPC Configuration in VTS.
(Characteristics available in the Table of Type Characteristics.)

OPC Server Setup Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

OPC Server Setup Properties: Settings Tab

An OPC Server has two configurable properties in addition to its ID information:
• The name space for this application on the Trihedral OPC Server. This is a required field.
• The Disallow Writes checkbox is there as a security feature. If checked, clients can query data from the server, but
cannot write to it.
As a convenience, the server’s Prog ID will also be shown in this screen.
You may find it easiest to reuse the application's name for the server namespace. You should never use the same name
space for two applications.

356 • How to Build an Application Developer's Guide (part 1)

Please review the information provided in the chapter, OPC Configuration in VTS.

Siemens S7 Driver Tags

The Siemens S7 driver provides an interface to Siemens PLCs of the following types:
• S7-200
• S7-300
• S7-400
Communication with the PLC is via ISO over TCP.
Future versions of VTS may also include communication via
• Serial (RS-485)
• Serial (RS-232) with adapter

This driver has the ability to save the last value written to each output tag, and to rewrite those values, either
automatically when lost communications are restored, or manually by the press of a button. Carefully review the
information in the Options tab to decide whether this feature should be used in your application.

(Characteristics available in the Table of Type Characteristics.)

Siemens S7 Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Siemens S7 Driver Properties: Options Tab

The Options tab for the Siemens S7 driver tag properties folder consists of attributes used to identify and establish a
connection to the control device to be associated with this driver.

Developer's Guide (part 1) How to Build an Application • 357

PLC Type
The S7 Driver is able to communicate with 3 Siemens devices: the S7-200, S7-300 and S7-400.

Protocol Type
ISO over TCP is the only protocol currently available.

Priority
Two priority levels are available: OP Mode (low priority) and PG Mode (high priority). Note that there may be a limit on
the number of PG mode connections which are available.

Rack and Slot

Specify the CPU position. These can be determined from the hardware configuration. Note that these fields do not apply
to the S7-200 CPU.

CP Type
If you are connecting to a Siemens PLC through a communications processor, select it here, otherwise select None.
Options include: CP-243, CP-343 and CP-443.

Store Last Output Values

When checked, the driver will maintain a record of the last value written to each output address. This may be useful in at
least two situations:
• For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
• When failed hardware is replaced by a new device and you would like to start that device with the values last written
to the old one.
If the last output values are stored, they may be re-written by either of two methods:
• Automatically, when communication is restored to the device.
• Manually by way of a button press. See, Rewrite Outputs Drawing Method for details.
Changing this value from checked to un-checked will cause all currently stored values to be erased immediately.

Enable Auto Rewrite

358 • How to Build an Application Developer's Guide (part 1)

If checked, the Store Last Output Values option will also be activated.
This option causes the driver to automatically rewrite the last value written to each output, in the event that
communications are lost, then restored.
Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in
driver communications.

Siemens S7 Driver Properties: Serial Tab

The Serial tab for the Siemens S7 driver tag properties folder consists of attributes used to identify and establish a
connection to the control device to be associated with this driver.

Port
Since the only protocol currently available is ISO over TCP, you should configure and select a TCP Port.

Time-Out Limit and Retries

A half second time out limit with one retry is recommended as a reasonable value for a Siemens PLC.

Hold
In the event of an interruption in communication, this option will cause the last good value to be held. You should use
this option with caution since, unless there is another means to alert you to interruptions in communication, it will appear
that a valid value is still being received.

Protocol Timeout
Timeout period, after which a lack of protocol traffic is considered an error. Default: 30 seconds.

Initial Max Packet Length

Maximum PG/OP packet length used for initial communication with the PLC. This value will not be used after length
negotiation with the PLC is complete. Default: 240.

Max. Outstanding Requests

Developer's Guide (part 1) How to Build an Application • 359

Defines the maximum number of PG/OP packets that may be outstanding. Default: 1 outstanding request.

Max Items Per Request

Defines the maximum number of item addresses to include in a request. Default: 18 items.

Max Requests per Semaphore

Defines the maximum number of requests that can be sent in one semaphore acquisition. Default: 100 requests.

Max Time per Semaphore

Defines the maximum amount of time to hold the semaphore. Default: 1 second.

Siemens S7 Driver Tag Drawing Methods

The following drawing methods are available to display information about your application’s Siemens S7 driver tags:
Comm Indicator Drawing Method
Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method
Rewrite Outputs Drawing Method

Siemens S7 Driver Addressing

The syntax of the S7 memory addresses and the legal ranges for each of the supported PLCs are as follows:

The syntax for memory addresses takes one of 3 forms:

[Area][Byte Address].[Bit Index]
[Area][Data Size: B, W or D][Starting Byte Address]
[Data Block Number DBx].DB[Data Size: B, W, X, or D][Starting Byte Address]

Memory Area Area Prefix S7-200 Bytes S7-300 Bytes S7-400 Bytes
Input E(I) 16 (128 bits) 8K (64Kbits) 16K (128Kbits)
Output A(Q) 5 (40 bits) 8K (64Kbits) 16K (128Kbits)
Memory M 32 4K 16K
Special Memory S(SM)
Variable Storage V
Timer T 512 1K 4K

360 • How to Build an Application Developer's Guide (part 1)

 Counter Z(C) 512 1K 4K
Data Blocks DBx DBy 2048, 64K each 8192, 64K each
Peripheral Input PE(I)
Peripheral Output PA(Q)
Analog Input AE(I) (n/a) (n/a)
Analog Output AA(Q) (n/a) (n/a)
Local L

SNMP Driver Tags

The SNMP driver can be used to communicate with any device that uses the Simple Network Management Protocol
(versions 1, 2c or 3).

When using version 3, authentication may be done using either MHAC-SHA-96 or the MD5 protocol. Encryption uses
either DES or 128-bit AES(1). Choice of protocol is done using the following application properties, found in
Settings.Dynamic:
• SNMPv3DefaultUserAuthProtocol (Set "0" for MD5 and "1" for SHA-1)
• SNMPv3DefaultUserPrivProtocol (Set "0" for DES and 1 for AES128)

(1)
If circumstances require that multiple users or security levels be configured, then multiple SNMP drivers can be
instantiated.
The following security levels are supported: NoAuthNoPriv, AuthNoPriv, and AuthPriv. There can be only one level per
driver instance. When SNMP version 3 is selected, the contents of the Agent tab of the configuration folder change to
allow selection of the security level and parameters for the User name and Context Name. The following application
privileges are used to store the configuration: SNMPv3DefaultUserAuthKey, SNMPv3DefaultUserAuthProtocol,
SNMPv3DefaultUserPrivKey, SNMPv3DefaultUserPrivProtocol.

VTS is considered a Network Management Station (NMS) only and cannot be managed by SNMP. The security level
must be less than or equal to the level configured for the user.
I/O tags that are configured to use an SNMP driver will have an address selection feature. A button labeled "MIB"
(management information base) will be added beside the Address field of the I/O tab. Clicking this will open an SNMP
Address Select window, from which you can choose the correct Object Identifier (OID) address.

Note: The SNMP driver requires more configuration than other drivers. You will need to obtain the MIB library for your
device from the manufacturer and you will need to tell VTS where to find this information. See SNMP Addressing for
details and configuration steps.

(Characteristics available in the Table of Type Characteristics.)

Developer's Guide (part 1) How to Build an Application • 361

SNMP Driver Properties: ID Tab
The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

SNMP Driver Properties: Communications Tab

Use the Communications tab to select the port through which this driver will communicate as well as options for
handling communication errors. In addition to the port parameters, this tab provides a location for you to specify the
name of the SNMP group to which this driver instance will belong.

Port
Use the tag browser button to select the TCP/IP or UDP port tag to which the remote equipment is attached. The X
button can use used to clear the current selection.

Retries
In the event that a connection cannot be made to the remote equipment on the first attempt, this field sets the number of
communication retries that are to be attempted before the driver gives up with an error message.

Retry Delay
Sets the delay, measured in seconds, between retry attempts.

Maximum PDU Length (Bytes)

Use to specify the maximum length, as measured in bytes, of the Protocol Data Unit. This value need only be changed
from the default if a different value is required by the equipment with which you will be communicating.

SNMP Group
The name of a VTS RPC service to which this driver instance will belong. Alternate RPC services need only be created
if your application uses multiple servers on separate sub-nets. In most applications you should leave the default value for
this field.

362 • How to Build an Application Developer's Guide (part 1)

Hold
In the event of an interruption in communication, this option will cause the last good value to be held. You should use
this option with caution since, unless there is another means to alert you to interruptions in communication, it will appear
that a valid value is still being received.

Store Last Output Values

When checked, the driver will maintain a record of the last value written to each output address. This may be useful in at
least two situations:
• For hardware that does not maintain its state during a power loss and must be restored to that state when re-started.
• When failed hardware is replaced by a new device and you would like to start that device with the values last written
to the old one.
If the last output values are stored, they may be re-written by either of two methods:
• Automatically, when communication is restored to the device.
• Manually by way of a button press. See, Rewrite Outputs Drawing Method for details.
Changing this value from checked to un-checked will cause all currently stored values to be erased immediately.

Enable Auto Rewrite

If checked, the Store Last Output Values option will also be activated.
This option causes the driver to automatically rewrite the last value written to each output, in the event that
communications are lost, then restored.
Use this option only if you are certain that you want the last values to be rewritten automatically after an interruption in
driver communications.

SNMP Driver Properties: Agent Tab

Provides configuration options related to the SNMP device with which this driver will communicate.

Format for SNMP 1 and 2c.

Developer's Guide (part 1) How to Build an Application • 363

Format for SNMP 3

SNMP Version
Select the simple network messaging protocol version that the agent is using. Supported versions include 1, 2c and 3.
Defaults to 1. Selecting version 3 will cause the available configuration parameters to change as shown.

Read Community String (Versions 1 and 2c)

Used for authentication of the device. The default value of "public" should have been changed on the device in the
interest of improved security.

Read/Write Community String (Versions 1 and 2c)

Similar to the Read Community String, this value is used to authenticate an SNMP device that will be used to both read
and write information. Like the former, this value should be changed on the device from the default of "public".

User Name (Version 3 only)

The name required for authentication.

Context Name (Version 3 only)

A context is a collection of information accessible by an SNMP entity. A SNMP Engine may contain one or more
contexts, where the default context has an empty name. Information is not constrained to a single SNMP Engine ID or
context; the same information can be available via different means. A context is used to define information subsets. For
example, an SNMP Engine exposed to this driver might contain multiple components, each of which implements MIB
items that may have conflicting OID info. The concept of a context was introduced to avoid this ambiguity. For simple
devices the default context is sufficient.

SNMP Driver Properties: Traps Tab

Used to specify the port on which the driver will listen for unsolicited (Trap) messages. The intended purpose of traps in
SNMP is to notify the network management service so that it can investigate as required. Traps typically contain
messages such as a timestamp and an event OID such as a device restart.
Defaults to 162. Should not match the local or the remote port number.

364 • How to Build an Application Developer's Guide (part 1)

The following notes are for SNMP version 3 only:
Additional configuration options, within the Trap Data block will be enabled when SNMP v3 is in use. In general, it is
recommended that Allow Traps be disabled unless explicitly required.
When filtering for specific SNMP user, check that the minimum security level is set as required. Note that the
user/security-level/context setup on the Agent tab is for commands (Get/Set/GetBulk) and has no effect on traps.

Security levels available include:

• Accept traps with no security
• Only accept authenticated traps.
• Only accept authenticated and encrypted traps.

SNMP Driver Tag Drawing Methods

The following drawing methods are available to display information about your application’s SNMP driver tags:
Comm Indicator Drawing Method
Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method
Rewrite Outputs Drawing Method

Developer's Guide (part 1) How to Build an Application • 365

SNMP Addressing
MIB : management information base. A hierarchy of the information available to an SNMP device, organized by
numbered Object Identifiers (OIDs).

SNMP addresses are built using a hierarchy of OID values. These can be long. The VTS SNMP Address Select tool,
found in every I/O tag that uses an SNMP driver, will help you build addresses for your I/O tags.

Before using the Address Select tool, you must first tell VTS where to find the MIB file for your device. You will need
to obtain a .MIB file from your equipment manufacturer.

SNMP Address Configuration

There are two parts to address configuration. The first is to obtain the required .MIB file(s) and import them into your
application. The second is to build the address using the built-in SNMP Address Select dialog (shown below).

Note: One MIB file may depend on another. Check that you have all that you need.

Importing a .MIB
1. Obtain a .MIB file from your equipment manufacturer.
7. Save this file to a folder on your VTS server computer.

Note: All .MIB files that will be used by an application will be stored a folder named "MIB" within your application
directory. You can create this folder yourself and copy the files to it. If using the Import MIB button as described in step
3e, VTS will create the folder and copy the selected files to it.

8. Import the file into the application's version control system.

There are two ways to do this:
1. Click on the application's Import File Changes button in the VAM.
Or:
a) Create and configure an SNMP driver tag in your application.
b) Select that driver in an I/O tag, such as an Analog Input.
c) The address field of the I/O tag will now have a MIB button.
d) Click the MIB button – the SNMP Address Select dialog will open.
e) Click the Import MIB… button.
f) Select the file.

Warning: If the .MIB file depends on other .MIB or .MY files, you will get an error message in the Address Select tool
after clicking the MIB button. Hovering over the error will open a tool-tip window, display the name of the missing file.
Locate and copy this file to the MIB folder, then use the Import File Changes button in the VAM.

Building an address.
The following instructions assume that you are configuring an I/O tag that uses an SNMP driver and have
reached the stage of building the address.

366 • How to Build an Application Developer's Guide (part 1)

 A MIB button can be found beside the address field when an SNMP driver has been selected as the I/O Device.

1. Click on the MIB button.

9. Navigate through the tree to select the device you wish to address.
Note that you can hover over a node to see extra information.
10. If required, enter the Table Index number, specifying the row in the SNMP table.
The Table Index is the last number in the SNMP address string.
11. Click OK.

Developer's Guide (part 1) How to Build an Application • 367

Note: The Disable Polling option allows you to turn off regular polls for this OID. Use this when you want to receive
data from traps only. Adding the :NS (no scan) suffix after the SNMP OID will cause the same result.

The result will be similar to that shown here:

368 • How to Build an Application Developer's Guide (part 1)

Polling Driver Tags
Available only in VTScada-based applications.
Polling driver tags are designed for use in telemetry applications where communication links may be costly, either in
terms of time or money.
The Polling driver tag provides the following features:
• The ability to poll multiple stations or I/O devices in a pre-determined order and at a fixed time interval.
• The ability to switch to fast-polling mode of selected sites on demand. See Fast Scan Drawing Method.
• Provides a tidy grouping of associated I/O tags on a single display.

Note 1: Polling driver tags are not required for Data Flow RTU driver tags since those have a polling feature built-in.

Note 2: Polling driver tags used in combination with DriverMUX (driver multiplexer) tags may fail to work properly.
Refer to the chapter, Driver Multiplexer Tags for instructions and warnings.

Polling drivers should be configured to stand between a communications driver tag and the I/O tags. Their function is to
control the order and the frequency of data transfer between the I/O tags and the remote equipment via the
communication driver tag.
All input tags associated with a Polling driver will use the scan interval configured for the Polling driver rather than their
configured scan rate.
When data is written from an output tag, it is immediately passed to the Polling driver tag and then on to the associated
communication driver tag. Following each write, all I/O addresses will be read immediately so that feedback need not
wait for the next polling cycle.

Multiple Polling drivers may be attached to a single communication driver tag, each with a separate poll rate, however
the result will be that all will poll at the fastest configured rate.

Note: If Modbus drivers are used in conjunction with a Polling driver in a networked application, then the application
property, ModiconSharedRPC should be set to 1. This will prevent the operation of the Polling drivers being distributed
between the primary and backup servers.

Developer's Guide (part 1) How to Build an Application • 369

(Characteristics available in the Table of Type Characteristics.)

Polling Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Polling Driver Properties: I/O Tab

The I/O tab for the Polling driver tag consists of properties used to identify the communication driver tag to be associated
with this Polling driver, and to establish the poll group, the I/O device's sequence in the poll, and the interval at which
the equipment associated with the communication driver tag should be polled for data.

I/O Device
The I/O Device field enables you to specify the communication driver tag for which this Polling driver will set the scan
rate.
The I/O Device field can be used to associate this tag with a new or existing communication driver tag using the tag
browser button. The button opens the Tag Browser, which displays only the existing communication driver tags for
your application, and enables you to create a new communication driver tag using its New button.

Poll Group Name

The Poll Group Name field enables you to enter a name by which this poll group will be known (or the name of the
existing poll group to which this Polling driver should belong).

370 • How to Build an Application Developer's Guide (part 1)

Note: Multiple Polling drivers can associate multiple communication drivers with a single poll group.

For example, you can create 5 Polling drivers, each of which is associated with a different communication driver, and
enter the same polling group name for each of the Polling drivers (e.g. "Poll Group 1", or "East Side Stations Poll
Group"). The result is that the 5 communication drivers associated with the 5 Polling drivers will be polled as a single
group. Instructions on configuring a poll group can be found in Setting Up a Poll Group.

Poll Sequence Number

The Poll Sequence Number field enables you to specify a number that identifies this Polling driver's place in the polling
sequence for the identified poll group.
For example, if you have created 5 Polling drivers, each of which is associated with a different communication driver
(e.g. Modbus1, Modbus2, etc.), and all 5 Polling drivers have the same poll group identified (in their Poll Group Name
property), you must enter a number from 1 to 5 for each of the Polling drivers to determine the order in which the 5
communication drivers belonging to the poll group will be polled.

Scan Interval (Seconds)

The Scan Interval field enables you to enter a number representing the amount of time (in seconds or in fractions of a
second) between requests for data from this Polling driver tag to the I/O device with which it is associated. The Delay
After Scan Interval (Seconds) property enables you to specify the amount of time that the Polling driver should wait
before polling the I/O device (see below).
If Scan Interval is set to 0, the I/O device is scanned for data as fast as is possible.

Note: All data that is set to the same Scan Interval is read in the same poll of the I/O device. For this reason, it is
recommended that you limit the number of different scan intervals for a single I/O device to optimize the reading to a
minimal number of blocks, and improve overall system update performance. For example, if you have 12 analog inputs
connected to one I/O device, it is recommended that the scan intervals for these tags be set to the same value (e.g. 1
(second)).

Delay After Scan Interval (Seconds)

The Delay After Scan Interval (Seconds) property indicates the amount of time that this Polling driver should wait before
polling the communication driver identified in the I/O Device field.
The system works on a 12-hour clock, starting at midnight. The value entered in the Delay After Scan Interval field
therefore indicates the amount of time after 12:00 am before the system begins to scan according to the time schedule
identified for the Scan Interval property.
For example, if you wish the system to begin polling at 1:00 am, and continue to poll every 2 hours (i.e. 1:00 am, 3:00
am, 5:00 am, 7:00 am, etc.), you should set the Delay After Scan Interval property to 3600 seconds (1 hour), and then set
the Scan Interval to 7200 seconds (2 hours).
Configuration examples are provided in Polling Driver Scan Interval and Delay After Scan Interval Examples.

Note: The Delay After Scan Interval must always be less than the Scan Interval value.

External Poll Trigger

May be linked to any tag or expression that transitions from a 0 or invalid state to a 1-state to trigger a poll. A Trigger
Tag should be used here, if you want to schedule polling to occur on a given schedule or in response to an operator’s
command. Note that an external poll signal will not cause a poll to occur if polling is disabled, or if fast scan mode is
currently enabled.

Disable Polling

Developer's Guide (part 1) How to Build an Application • 371

Allows you to disable and enable the polling cycle for this poll driver. Note that this does not mean that reads or writes
are disabled; only the polling cycle is affected.

Polling Driver Properties: Display Tab

The Display tab is used to define the placement (latitude and longitude) of the Polling station. Decimal values should be
used rather than degrees, minutes and seconds.
You may also define a custom details page to use in the event that you have created one you would prefer over the built-
in Site Details page. Many of the drawing methods available to the Polling Driver have their own configuration for
which page is to be opened when clicked. The page selected in the drawing method will have priority over the page
selected in this tab. By selecting a details page here, you set the default to be used by those drawing methods, and for
drawing methods such as the map pin, which does not have any configurable options.
A custom details page should include a tag parameter, named SiteTag, of the same type as this tag. The built-in Site
Details page has two other parameters, which you may consider supporting in your custom page:
A parameter of type Status. This should be tied to the "Use Theme" parameter of any custom drawing methods in the
page.
A parameter of type text, which may be referenced by the TextColor parameter of certain drawing methods.
Related Information:
Site Details Page

You may find it easier to set the location using the map interface than to enter the latitude and longitude values here. See:
Site Map.

Polling Driver Scan Interval and Delay After Scan Interval Examples
A Polling driver tag can be configured to scan a communication driver tag on a regular schedule. The key to doing so is
proper configuration of the Scan Interval and Delay After Scan Interval properties.
The Scan Interval property specifies the number of seconds between polls, where the polling cycle starts at midnight.
The Delay After Scan Interval property specifies the number of seconds after the Scan Interval to trigger the poll.

372 • How to Build an Application Developer's Guide (part 1)

Note: The Delay After Scan Interval property should never be greater than the Scan Interval property.

The following 3 examples have been provided to help guide you.

Poll at 2-hour Intervals Starting at 1:00 am

If you want the poll to happen at 1:00 am, 3:00 am, 5:00 am, 7:00 am (and so forth), the Scan Interval property should be
set to 7200 seconds (2 hours), and the Delay After Scan Interval property should be set to 3600 seconds (1 hour after
midnight).

Poll Every 10 Minutes Starting at Midnight

If you want the poll to happen at 12:10 am, 12:20 am, 12:30 am (and so forth), the Scan Interval property should be set
to 600 seconds (10 minutes), and the Delay After Scan Interval property should be set to 0 seconds (midnight).

Poll At 3:00 am and 3:00 pm Daily

If you want the poll to happen at 3:00 am and 3:00 pm every day, the Scan Interval property should be set to 43200
seconds (12 hours), and the Delay After Scan Interval property should be set to 10800 seconds (3 hours).

Polling Driver Tag Drawing Methods

Polling driver tags enable users to establish groups of PLCs or RTUs that will be polled together. The drawing methods
for a Polling driver tag enable users to display pertinent data about the RTU or PLC with which they are associated.
The following drawing methods are available to Polling driver tags:
Active Indicator Drawing Method
Comm Indicator Drawing Method
Comm Messages Button Drawing Method
Comm Statistics Button Drawing Method
Data Age Drawing Method
Fast Scan Drawing Method
Gradient Color Change Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method
Polled Station Drawing Method
Site Draw Drawing Method

Setting Up a Poll Group

A poll group can be configured by associating a Polling driver with each communication driver tag that you wish to
belong to the group. For example, if you wish to configure 3 communication driver tags to belong to the same poll
group:
Create a new Polling driver tag for each communication driver tag, and configure each as follows.
Select the communication driver tag's name in the I/O Device field on the I/O tab of the Polling driver. There should be
one Polling driver associated with each communication driver tag.
Enter the same text in the Poll Group Name field on the I/O tab of each Polling driver (e.g. Eastern Poll Group).

Developer's Guide (part 1) How to Build an Application • 373

Enter an appropriate sequential number in the Poll Sequence Number field for each of the Polling driver tags. This will
identify each Polling driver tag's place in the poll sequence for the identified poll group. (For example, enter 1 for the
first Polling driver tag in the Eastern Poll Group, 2 for the second Polling driver tag in the Eastern Poll Group, and 3 for
the final Polling driver tag in the Eastern Poll Group.

Workstation Status Tags

Workstation status driver tags can be associated with one or more Analog Input tags to access data that the driver obtains
from the Windows Management Instrumentation (an API in the Windows operating system that enables devices and
systems in a network to be managed and controlled).

Windows Vista requires additional security configuration before you will be able to access performance counter
information (i.e. workstation status information). By default, an application will run using the same privileges as the
person who started it. You can add the user account that the application runs as to the Performance Log Users group and
then assign that group the right to "Log on as a Batch Job User".
For further information, refer to http://technet2.microsoft.com/windowsserver2008/en/library/8620ccc5-b054-48b4-
b276-9f6c716954a71033.mspx?mfr=true
To add a user to the Performance Log Users group:
1. Click Start, click in the Start Search box, type compmgmt.msc, and then press ENTER.
12. Expand System Tools, expand Local Users and Groups, and click Groups.
13. In the list of groups, right-click Performance Log Users, and then click Add to Group.
14. On the General tab, click Add.
15. Type the name of the user you want to add, or click Advanced to search the directory for a user.
16. When you have finished adding users, click OK, and click OK again to close the Performance Log Users property
page.
To assign the Log on as a batch job user right to the Performance Log Users group:

1. Click Start, click in the Start Search box, type secpol.msc, and then press ENTER. The Local Security Policy
snap-in will open in Microsoft Management Console.
17. In the navigation pane, expand Local Policies and click User Rights Assignment.
18. In the console pane, right-click Log on as a batch job and then click Properties.
19. In the Properties page, click Add User or Group.
20. In the Select Users or Groups dialog box, click Object Types. Select Groups, and then click OK.
21. Type Performance Log Users in the Select Users or Groups dialog box, and then click OK.
22. Click OK again to close the property page.

Note: Workstation status driver tags have been configured in such a way that they do not conform to the same
server/backup server fail over process like other VTS drivers (see "Remote Applications"). In essence, the PC being
monitored by a workstation status driver tag is its own server. If the PC being monitored drops off the network, the
workstation status driver tag will be unable to report data about it to the application.

Note: Information on the correct configuration of a workstation status driver tag and its associated Analog Input tags is
provided in Workstation Status Driver Tag Addressing.

(Characteristics available in the Table of Type Characteristics.)

Workstation Status Driver Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.

374 • How to Build an Application Developer's Guide (part 1)

The properties of the ID tab are described in the topic: The ID Tab.

Workstation Status Driver Properties: Workstation Tab

The Workstation tab enables you to specify the workstation for which this tag should report data.

Workstation Name
The Workstation Name drop-down list enables you to select the name of the workstation that you wish to monitor (you
may alternatively enter a Net BIOS name in this field). The Workstation Name field defaults to the local machine name
when new workstation status driver tags are initially created.

Note: Please refer to Workstation Status Driver Tag Addressing for instructions on the correct configuration of a
workstation status tag and its associated Analog Input tags.

Workstation Status Driver Tag Addressing

A workstation status driver tag monitors a workstation and allows associated Analog Input tags to report and display data
about the workstation.
In order to access information about the workstation being monitored by a workstation status driver tag, follow these
steps:
Create a workstation status driver tag. Set the Workstation Name drop-down list to the name of the workstation you wish
to monitor. (You can create one workstation status driver tag for each workstation you wish to monitor.)
Create one Analog Input tag for each piece of data you wish to obtain from the workstation being monitored. (You can
create multiple Analog Input tags and associate them with a single workstation status driver tag.)
Use the I/O Device field for each Analog Input tag to associate the analog input with the workstation status driver tag.

Set the Address field of each Analog Input tag to one of the following text strings:

Address Field Value Information Returned from Workstation

AverageCPU Running average of total system CPU
BatteryLevel The percentage of the battery level remaining
BatteryLifetime An estimation of the remaining battery life, in minutes.
PowerStatus 0 == on battery
1 == on A/C
2 == on back-up power
BatteryState:High Set to 1 if the battery's power state is high
BatteryState:Low Set to 1 if the battery's power state is low
BatteryState:Critical Set to 1 if the battery's power state is critical
BatteryState:Charging Set to 1 if the battery is charging
BatteryState:NoBattery Set to 1 if no battery is found
FreeDiskSpace Free disk spaces (bytes) for a logical disk (anything that is addressable
with a drive letter).
GDIObjects GDI objects used by VTS

Developer's Guide (part 1) How to Build an Application • 375

 Handles Handles in use by VTS
IOBPS I/O bytes per second, including all disk reads/writes, as well as
network traffic
Memory Real memory used by VTS (in bytes)
SystemCPU System CPU – all processes
Threads Threads being used by VTS
Virtual Memory Virtual memory used by VTS (in bytes)
VTSCPU CPU used by VTS only

Note: You must append the letter for the drive to be monitored to FreeDiskSpace (e.g. FreeDiskSpaceC for drive C, or
FreeDiskSpaceD for drive D.

Workstation Status Driver Tag Drawing Methods

The following drawing methods are available to display information about your application’s workstation status driver
tags:
Comm Indicator Drawing Method
Numeric Value Drawing Method

Data Type Suffixes for Tag I/O Addresses

The data type to read from or write to is usually implied by the address. If it is not, the strings below may be appended to
the address (without spaces) to force the data to be interpreted as a specific type:

Suffix Meaning
/ABFloat Allen-Bradley PLC/3 Floating Point (4 bytes) (Used for Allen-Bradley exclusively)
/AB5Float Allen-Bradley PLC/5 Floating Point (4 bytes) (Used for Allen-Bradley exclusively)
/BCD2 2-digit (1 byte) Binary Coded Decimal
/BCD3 3-digit (2 bytes – lowest 12 bits) Binary Coded Decimal
/BCD4 4-digit (2 bytes) Binary Coded Decimal
/Bit Attempts to convert the value to a single bit. The bit number used is always 0. (ex:
40001/Bit)
/Double IEEE Double Precision Floating Point (8 bytes)
/Float IEEE Single Precision Floating Point (4 bytes)
/SByte Signed Byte
/SDWord Signed 32-bit Integer
/SWord Signed 16-bit Integer

376 • How to Build an Application Developer's Guide (part 1)

 /UByte Unsigned Byte
/UDWord Unsigned 32-bit Integer
/UWord Unsigned 16-bit Integer

For example:
40001/UDWord

Each I/O device uses a different addressing scheme. These addressing schemes are referenced below.
• Allen-Bradley Driver Addressing;
• Modicon Driver Addressing;
• Omron Addressing; and
• OPC Client Driver Addressing.
The sections that follow identify the VTS driver types and their properties.

VTS I/O Device Driver Library

The following communication driver tags are standard to VTS:
Allen-Bradley Driver Tags
CIP Driver Tags
CalAmp Diagnostic Driver Tags
DDE Driver Tags
DNP3 Driver Tags
MDS Diagnostic Driver Tags
Modicon Driver Tags
Omron Host Link Driver Tags
OPC Client Driver Tags
Siemens S7 Driver Tags
SNMP Driver Tags
Workstation Status Tags

Additional
Company Device Medium Protocol
Components

Allen-Bradley Ethernet Direct

PLC-2 Serial DF1 Allen-Bradley Serial

Interface Module

PLC-3 DH+ DF1 Woodhead 5136-SD

(ISA or PCI)

Serial DF1

PLC-5 Serial DF1

Developer's Guide (part 1) How to Build an Application • 377

 DH+ DF1 Woodhead 5136-SD
(ISA or PCI)

Ethernet DF1 PLC-5E only

SLC500 (all Serial DF1

processors)
DH+ DF1 Woodhead 5136-SD
(ISA or PCI)

Ethernet DF1

Micrologix Serial DF1

RS-485/RS-232 Modbus RTU

Serial

Ethernet DF1, CIP

Compact Logix Serial DF1

Ethernet DF1, CIP

Control Logix Serial DF1

Ethernet DF1, CIP

Aquatrol 1300 RTU Serial Aquatrol Special

communication
hardware

1500 RTU Serial Aquatrol

Bailey Network 90 DCS Serial Bailey Bailey CIU

Campbell 10X Data Logger Serial Array Based

Scientific
510 Data Logger Serial Array Based

Logger Various API

Control Telesafe Micro 16 Serial Modbus RTU, DF1 & DNP are
Microsystems RTU Modbus ASCII, DF1, Telesafe options
DNP

SCADAPack RTU Serial/Ethernet Modbus RTU, Modbus

Family ASCII, Modbus TCP/IP
& UDP/IP, Open
Modbus TCP, DNP3
Datalogging and Store
& Forward Supported

DAQ Serial DNP 3.0 Level 1

Data Flow RTU Serial, Ethernet Data Flow Systems Includes TACII,
Systems (TCP /IP& HyperTAC,
UDP/IP) HyperServer
Database

378 • How to Build an Application Developer's Guide (part 1)

 Conversions

DDE (Dynamic DDE Compliant DDE Client DDE Server

Data Exchange) Devices

DNP 3.0 DNP 3.0 Compliant Serial, Ethernet DNP 3.0 Level 1
Devices

Federal Pioneer DSM-2P Power Serial Federal Pioneer

Meters

Foxboro 731C Loop Serial Foxboro

Controller

743C Loop Serial Foxboro

Controller

761C Loop Serial Foxboro

Controller

C50 RTU Serial DNP 3.0 level 1

General Electric Series 1 PLC Serial General Electric

Series 5 PLC Serial General Electric

Series 6 PLC Serial General Electric

Series 90 PLC Serial SNP, SNPX

Granville 307 Vacuum Serial Granville Phillips

Phillips Controller

Hewlett-Packard HP48000 RTU Serial Subset, HEX-ASCII

IDEC Micro CP12 Serial IDEC

Micro CP13 Serial IDEC

Micro FA2 Serial IDEC

Micro FA3 Serial IDEC

IEC IEC 60870 Serial, Ethernet IEC 60870-5-101

Compliant Devices

Koyo DL Family of PLCs Serial Direct Net

(205, 305, 405)

Landis & Gyr Telegyr 8979 Serial Landis & Gyr

Lantronix UDS-10, UDS-100 Serial/Ethernet N/A

Serial to Ethernet
Converters

Mitsubishi A Series Serial Mitsubishi

Modbus Modbus Compliant Serial, Ethernet, Modbus ASCII, Modbus PLUS

Devices TCP, Ethernet Modbus TCP/IP, requires additional

Developer's Guide (part 1) How to Build an Application • 379

 UDP, Modbus Modbus UDP/IP, hardware
Plus Open Modbus TCP,
Modbus PLUS,
Modbus RTU

Modicon Premium, Serial, Ethernet, Modbus ASCII, Modbus PLUS

Quantum, TCP, Ethernet Modbus TCP/IP, requires additional
Momentum, UDP, Modbus Modbus UDP/IP, hardware
Compact, Ultra- Plus Open Modbus TCP,
Compact, TSX Modbus PLUS,
Micro Modbus RTU

Moore APACS ACM 040- Moore Moore Requires Moore

4M interface card for PC

Motorola Moscad Serial, Ethernet DDE, Modbus

OSI Soft PI Database (Read API API Requires PI Client

Only) Software

Omron C-series Serial Hostlink

Programmable
Controllers

CS Series PLCs Serial FINS

CJ Series PLCs Serial FINS

OPC (OLE for OPC Servers for Serial, Ethernet OPC Client
Process Control) various Products

Opto 22 Optomux Serial Optomux

Power ION Series Meters Serial, Ethernet ModbusDNP 3.0 level

Measurement 1
Ltd

Powers Process 330, 350, 512, 535, Serial Powers

Controllers 545

Quindar SCADA Master Serial, Ethernet QNet

(TCP/IP &
DECNet)

Schlumberger Q1000 meter Serial DNP 3.0 level 1

Siemens S5 Series PLC

Ethernet Profinet or PG
S71200
Serial Modbus RTU

SIMATIC TI 305, Serial Direct Net

405, 505 Series
PLCs

S7-200 Series PLC Ethernet OP/PG Requires Siemens

Ethernet
Communications

380 • How to Build an Application Developer's Guide (part 1)

 Processor

OPC over Serial, OPC Client Requires OPC

OPC over Ethernet Server

S7-300 Series PLC Ethernet OP/PG May Require

Siemens Ethernet
Communications
Processor

OPC over Serial, OPC Client Requires OPC

OPC over Ethernet Server

S7-400 Series PLC Ethernet OP/PG Requires Siemens

Ethernet
Communications
Processor

OPC over Serial, OPC Client Requires OPC

OPC over Ethernet Server

Sierra Misco see Stevens Water

Square D Sy/Max PLCs Serial Square D

Stevens Water SM0850 Serial Stevens

Surfline 9009, 9015 Series Serial Surfline Requires Surfline

CP Module

Texas TI 305, 405, 505 Serial Direct Net

Instruments Series PLCs

Toshiba T2, T2E PLCs Serial Toshiba

Input Tags
Input tags are used to read data from an I/O device, such as a programmable logic controller (PLC), remote terminal unit
(RTU), or an I/O board. These tags permit the handling of either digital (discrete), or analog (continuous floating point)
values.
The following input tags are included with VTS:
Analog Input tags
Analog Status tags
Digital Input tags
Digital Status tags
Pulse Input Tags
Pump Status Tags

The sections that follow describe each of these input tags and define their properties.

Developer's Guide (part 1) How to Build an Application • 381

Analog Input Tags
The role of Analog Input tags is to represent incoming analog data values from equipment processes, and provide
drawing methods to display the data in numeric or graphic form as a bar, gauge, or number.

Note: Analogs can have text values if the driver returns a text value. For this to happen, the Unscaled Min and Unscaled
Max values within the Scaling tab must be set equal.

(Characteristics available in the Table of Type Characteristics.)

Analog Input Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Analog Input Properties: I/O Tab

The I/O Tab contains the properties used to identify and establish a connection to the communication driver tag being
used to exchange data with your physical I/O device (e.g. PLC or RTU). This is accomplished by specifying the driver
tag that communicates with the physical I/O device, the address at the physical I/O device from which this tag is to read
its data, and the rate at which the I/O device should be scanned for data.
If supported by the communication driver, the Analog Input tag may also be used to write data.

I/O Device
Select the communication driver tag from which data will be read.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Address

382 • How to Build an Application Developer's Guide (part 1)

Provide the address within the I/O device from which this tag is to read data. This value must match the configuration
of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.
For some drivers (SNMP and the OPC Client) an address browser is provided to assist you.

Scan Interval
Provide the frequency, measured in seconds, that the I/O device should be scanned for new data. If the I/O Device is a
Polling driver, which provides its own scan interval, then this field will not accept data.

Engineering Units
Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc.

Manual Data
This optional field allows you to provide a constant value that will be used instead of input read by the communication
driver. It is commonly used when testing a new Analog Input tag when application is not attached to a live data source.
Tags that are using manual data are marked on screen by a flashing exclamation mark.

Enable Output
If checked, this input tag may also be used to write data to the specified address of the communication driver. A Security
Privilege may be set in the Merit tab to restrict access to this feature.

Analog Input Properties: Scaling Tab

The Scaling Tab requires values that will be used to convert unscaled, raw data from the I/O device associated with this
tag into scaled data that will be reported to operators. VTS uses an algorithm to calculate this tag's value internally, based
on the known unscaled and scaled values you supply.

Developer's Guide (part 1) How to Build an Application • 383

 Assuming a linear relationship between the values, by
providing a known minimum scaled value for a given
minimum unscaled value, and a known maximum scaled
value for a given maximum unscaled value, VTS can
provide a scaled value for any given unscaled input value.

Analog Input Properties: Owner Tab

The Analog Input tag can be used in an owner/contributor structure where multiple contributor tags can supply their
values to an owner tag. The Owner Tab allows you to specify the owner tag to which this tag should contribute its data.

Note: There is no specific "owner" tag type, rather an owner tag is typically a custom-designed tag that is created using
VTS scripting code for special projects.

Owner
The Owner field enables you to specify a tag to which this contributor should supply its data. An owner tag is one which
you must design and then create, using the VTS scripting language.
The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual
data value, to questionable data, according to the configuration of the checkboxes appearing beneath the Owner field.
These checkboxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

384 • How to Build an Application Developer's Guide (part 1)

When selected, the Set Owner\DataX[…] To Value checkbox enables you to set the value of this contributor tag as the
nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner
tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack.
Priority checkbox causes the owner tag to keep track of the priority of the contributor's active alarm (or records an
Invalid if the contributor is not currently in an alarm state). Selecting the Set Active/Unack. Priority checkbox also
causes the owner tag to record whether or not the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values),
rather than reading data from their I/O device. When selected, the Record Use of Manual Data checkbox enables you to
increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been
provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag
Quality checkbox enables you to increment the owner tag's count of the number of tags that are contributing quality data
by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the
Record Tag Validity checkbox enables you to increment the owner tag's count of the number of tags that are contributing
questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Analog Input Properties: Merit Tab

The Merit tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you suspect
the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its
data is marked for extra monitoring.
The Quality Based On field is for use when this tag is to be a contributor to a custom-built container tag. Please see the
topic Merit Tab and Quality Tab for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

Developer's Guide (part 1) How to Build an Application • 385

Analog Input Properties: Alarm Tab
The Alarm tab allows you to create new Alarm tags that will be triggered by this tag. The new alarm tags will be created
as children of the current tag.
Use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will
automatically be linked to this tag’s value.

Analog Input Properties: Script Tab

The Script Tab allows you to create one or more Script tags to be associated with this tag.
A Script tag provides a means of creating a procedure, using VTS’s programming language, that will run whenever this
tag’s value changes.

386 • How to Build an Application Developer's Guide (part 1)

Analog Input Properties: Logger Tab
The logger tab enables you to associate a single Logger tag with this tag. The Logger tag works with an attached
Historian to record this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag
will be created as a child of the current tag.

Note: Only one Logger tag can be directly associated with a single input or output tag. If you need to have multiple
loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O Tag

Analog Input Tag Drawing Methods

The following drawing methods are available to display information about your application’s Analog Input tags:
Animated Bitmap Drawing Method Bottom Bar Drawing Method
Color Blink Drawing Method Color Box Drawing Method
Color Fill Drawing Method Color Line Drawing Method

Developer's Guide (part 1) How to Build an Application • 387

 Compass 1 Drawing Method Compass 2 Drawing Method
Draw Text Drawing Method Droplist Control Drawing Method
Gradient Color Change Drawing Method Image Change Drawing Method
Left Bar Drawing Method Meter 1 Drawing Method
Meter 2 Drawing Method Meter 3 Drawing Method
Meter 4 Drawing Method Meter 5 Drawing Method
Meter 6 Drawing Method Meter 7 Drawing Method
Meter 8 Drawing Method Meter 9 Drawing Method
Meter 10 Drawing Method Meter 11 Drawing Method
Meter 12 Drawing Method Meter 13 Drawing Method
Momentary Button Drawing Method Multi-color Drawing Method
Multi-text Drawing Method Numeric Entry Drawing Method
Numeric Value Drawing Method Plot Data Drawing Method
Right Bar Drawing Method Set Analog Value Drawing Method
Set Value Button Drawing Method Set Value Hotbox Drawing Method
Slider Drawing Method Text Change Drawing Method
Top Bar Drawing Method Two Color Bar Drawing Method

Analog Status Tags

Analog Status tags were originally unique to VTScada, but have long since been included in the core VTS software. It is
the role of Analog Status tags to take analog data such as well level or a motor speed from an I/O device.

Note: Analogs can have text values if the driver returns a text value and if the Unscaled Max value is set equal to the
Unscaled Min value in the tag configuration.

Note: Never attempt to attach a Logger tag to an Analog Status tag. Analog Status tags have a built in Historian.

(Characteristics available in the Table of Type Characteristics.)

Analog Status Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Analog Status Properties: I/O Tab

The I/O Tab includes properties used to identify and establish a connection to the communication driver tag being used
to exchange data with your physical I/O device (e.g. PLC or RTU), or to the Polling driver responsible for determining
the order and rate at which data polls will occur.

388 • How to Build an Application Developer's Guide (part 1)

I/O Device
Select the communication driver tag from which data will be read.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Address
Provide the address within the I/O device from which this tag is to read data. This value must match the configuration
of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.
For some drivers (SNMP and the OPC Client) an address browser is provided to assist you.

Scan Interval
Provide the frequency, measured in seconds, that the I/O device should be scanned for new data. If the I/O Device is a
Polling driver, which provides its own scan interval, then this field will not accept data.

History Address
If set, then the address field becomes optional. This field provides a means of reading values as recorded by a data
logger.
If both the address and the history address are provided, then the address will be polled for data at the interval set by the
Scan Rate, but the values read from the data logger will overwrite the values logged by this tag when it is updated.
The form for the history address will depend on the RTU. Please refer to the addressing reference chapter for your driver.
Further information on reading history information can be found in the topic SCADAPack History Read

History Scan Interval

Sets the time between polls of the history data logger. If a History address has been set, but this field is left blank, then it
will default to the value set in the Scan Rate field. The recommended value for this field is 60 seconds. Lesser values
may cause communications to slow down.

Developer's Guide (part 1) How to Build an Application • 389

Engineering Units
Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc.

Deadband (Engineering Units)

The value of an Analog Status tag is automatically logged on change. The deadband range, specified in the defined
engineering units, allows you to set a minimum amount by which the input data must change before a new value is
written to the log file.
This allows you to dampen out minor value fluctuations, reducing the size of the log file by excluding system noise.

Manual Data
This optional field allows you to provide a constant value that will be used instead of input read by the communication
driver. It is commonly used when testing a new Analog Input tag when application is not attached to a live data source.
Tags that are using manual data are marked on screen by a flashing exclamation mark.

Enable Output
If checked, this input tag may also be used to write data to the specified address of the communication driver. A Security
Privilege may be set in the Quality tab to restrict access to this feature.

Analog Status Properties: Scaling Tab

The Scaling Tab requires values that will be used to convert unscaled, raw data from the I/O device associated with this
tag into scaled data that will be reported to operators. VTS uses an algorithm to calculate this tag's value internally, based
on the known unscaled and scaled values you supply.

390 • How to Build an Application Developer's Guide (part 1)

 Assuming a linear relationship between the values, by
providing a known minimum scaled value for a given
minimum unscaled value, and a known maximum scaled
value for a given maximum unscaled value, VTS can
provide a scaled value for any given unscaled input value.

Analog Status Properties: Alarm Tab

The Alarm Tab allows you to configure two alarms (typically for a high set point and a low set point) based on the value
of this tag. The initial priority for each is "None". This prevents un-configured alarms from being counted as disabled
alarms.
Note that while the priority is set to "None", all other controls are disabled.

Note: If you wish to override the built-in low and or high alarms for an Analog Status tag, please refer to "Overriding
Built-in Alarms".

Developer's Guide (part 1) How to Build an Application • 391

Low Alarm Priority
The Low Alarm Priority drop-down list enables you to select the priority of the low alarm that will be triggered for this
tag if its value drops below the value defined for the Low Alarm Setpoint. The available priorities are:
• None
• 0 – Event
• 1 – Critical Alarm
• 2 – High Alarm
• 3 – Warning Alarm
• 4 – Notice Alarm
If you have defined your own Alarm Priority tags, those will also be available for selection.

Low Alarm Setpoint

The Low Alarm Setpoint field enables you to enter the lowest value that this tag's value will be permitted to attain, after
which a low alarm will be triggered. The source for this field may be either a constant, the result of an expression, or the
value of a tag.
Please see the topic: Constant, Expression or Tag for more information on selecting between these three choices.

Low Alarm Deadband

392 • How to Build an Application Developer's Guide (part 1)

If noise in the system causes a value to fluctuate above and below the set point, the alarm will repeatedly switch between
active and inactive status. By using the deadband, you can dampen out these fluctuations by setting an amount by which
the tag’s value must rise above the low alarm set point before it is considered to no longer be active. The deadband is
used only for changing a current alarm’s active status. It does not affect the set point.

Low Alarm Delay

Spikes in the value being monitored may cause transient alarms. By setting an alarm delay, you can specify that the
trigger condition must remain true for a given length of time before the alarm is considered to have occurred.
If required, refer to the topic: Constant, Expression or Tag for more information on selecting between these three
choices.

Disable Low Alarm

The Disable Low Alarm field enables you to specify whether the low alarm for this tag is disabled or enabled. Disabling
of alarms is typically used in situations where you wish to avoid false alarms. For example, in the event that routine
maintenance is being performed on the equipment represented by this tag, or when you are aware that another
interruption in communications will occur for a period of time; in such situations, the alarm can be disabled until the
maintenance is complete and communications are reestablished.
A value of 0 (or any tag or expression that returns 0) means that the alarm has not been disabled. Any value other than 0
in this field indicates that the alarm has been disabled.
The value accepted by the Disable Low Alarm field can be provided via any of a constant, an expression, or a tag. Please
see the topic: Constant, Expression or Tag for help selecting which to use.

Alarm Rearm Time

Applies only if Alarm Rearm Enable is checked for this alarm. If the alarm has been acknowledged, but remains active
for the time shown in this field, the alarm will return to the un-acknowledged state. Audible and visible warnings
configured for this alarm’s priority level, will again be displayed. The Alarm Rearm Time is measured in seconds, and
defaults to 3600 (1 hour). The value in this field must be greater than 0.

Alarm Rearm Enable

Controls whether this alarm will revert back to an un-acknowledged state if it remains active for the length of time set in
Alarm Rearm Time, after having been acknowledged by the operator.

High Alarm Setpoint, High Alarm Priority and Disable High Alarm
These work in exactly the same way as the low alarm set point, low alarm priority and disable low alarm fields, except
that they are used to create an alarm that will be triggered when the tag's value goes above a given set point.

Low Alarm Popup Enable & High Alarm Popup Enable

If the configuration variable AlarmPopupsEnable is set to 1, then setting either the Low Alarm Popup Enable or the High
Alarm Popup Enable, will result in a pop-up dialog being displayed whenever the respective alarm is triggered. It is
strongly suggested that this feature be used sparingly.

Sound
The Sound field enables you to identify what sound will be played when this alarm is triggered. The Sound field can be
set to blank, 0, 1, or to the name of a .WAV sound file to be played.
If the Sound field is set to 0, no sound will be played when this alarm is triggered.
If the Sound field is set to blank or 1, an alarm sound whose properties are configured on the associated Alarm Priority
tag will be played.
If the Sound field identifies the name of a .WAV sound file, it will override any alarm sound configured for the
associated Alarm Priority tag. When specifying a sound file, you must enter its name and extension (e.g. MySound.wav).

Developer's Guide (part 1) How to Build an Application • 393

The specified sound file must be a .WAV file, and must be stored in the application directory. If the specified sound file
is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

Analog Status Properties: External Alarms Tab

The External Alarms tab is used to display, add or remove separate Alarm tags that are triggered by this Analog Status
tag. Use the Add button to create new external Alarm tags and the Delete button to remove them. The new alarm tags
will be created as children of the current tag.

Analog Status Properties: Quality Tab

The Quality tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you
suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure
that its data is marked for extra monitoring.
The Quality Based On field is for use when this tag is to be a contributor to a custom-built container tag. Please see the
topic Merit Tab and Quality Tab, for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

394 • How to Build an Application Developer's Guide (part 1)

Analog Status Properties: Order Tab
(For use with VTScada-based applications only)
The control found on this tab enables you to specify the placement of this tag when viewed in an associated station
dialog. See Order Tab for further details.

Analog Status Properties: Historian Tab

If you select a Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer.
Historians are described in the topic, Historian Tag. You may log to more than one Historian by duplicating this tag's
value in a Calculation tag and attaching to it a Logger that is configured with a different Historian or a different
logging rate.

Note: There are consequences if you change the selected Historian tag after you have begun
collecting data. If you switch to a new Historian (perhaps for organizational or load sharing
purposes), the data collected for this tag by the previous Historian will become inaccessible.

Analog Status Tag Drawing Methods

The following drawing methods are available to display information about your application’s Analog Status tags:
Animated Bitmap Drawing Method Bottom Bar Drawing Method

Developer's Guide (part 1) How to Build an Application • 395

 Color Blink Drawing Method Color Box Drawing Method
Color Fill Drawing Method Color Line Drawing Method
Set Value Button Drawing Method Set Value Hotbox Drawing Method
Compass 1 Drawing Method Compass 2 Drawing Method
Draw Drawing Method Draw Text Drawing Method
DropList Control Drawing Method Gradient Color Change Drawing Method
Image Change Drawing Method Left Bar Drawing Method
Meter 1 Drawing Method Meter 10 Drawing Method
Meter 11 Drawing Method Meter 12 Drawing Method
Meter 13 Drawing Method Meter 2 Drawing Method
Meter 3 Drawing Method Meter 4 Drawing Method
Meter 5 Drawing Method Meter 6 Drawing Method
Meter 7 Drawing Method Meter 8 Drawing Method
Meter 9 Drawing Method Momentary Button Drawing Method
Multi-Color Drawing Method Multi-Text Drawing Method
Numeric Entry Drawing Method Numeric Value Drawing Method
Plot Data Drawing Method Right Bar Drawing Method
Set Analog Value Drawing Method Slider Drawing Method
Text Change Drawing Method Top Bar Drawing Method
Two Color Bar Drawing Method

Analog Status Tag: Context Menu

Given an Analog Status tag, drawn on a page using any of the available drawing methods (see: Analog Status tag
Drawing Methods), an operator may right-click on that drawing method to open the following context menu:

This menu includes the following features by which the tag can be controlled:

Help
Opens this help guide.

Disable Low Alarm

When checked, the low alarm is disabled.

Disable High Alarm

396 • How to Build an Application Developer's Guide (part 1)

When checked, the high alarm is disabled.

Alarm Settings
Opens just the alarm tab from the tag’s configuration panel, allowing the alarms to be re-configured.

Manual Data
Opens just the I/O tab from the tag’s configuration panel, allowing manual data (and other I/O values) to be re-
configured.

Logging Deadband
Opens just the I/O tab from the tag’s configuration panel, allowing manual data (and other I/O values) to be re-
configured.

Questionable Data
Toggles the Questionable Data flag on this tag from its current setting to the opposite.

Properties
Opens the tag’s configuration panel, providing access to all tabs.

Comparison of Analog Input and Analog Status Tags

Analog Status and Analog Input tags are used for similar purposes. Both are used to monitor analog values and, with
only one exception, the same drawing methods are available to each. Either could be used for the same PLC I/O address
and when drawn on the screen, there is nothing to indicate which tag has been used.

A common question then is, “which tag should I use?”. The following comparison of features should help you choose.
Any tag attribute not listed below is the same for both.

Analog Input Analog Status

No built-in logger Logger built in, logging on change
No deadband option Deadband option - used to set a minimum change
required before logging a new value.
High and low alarms built-in.
No built-in alarm
Does not support history reads Supports history reads when used with drivers that have
this feature.
Not drawn on VTScada Station Pages Drawn on VTScada Station Pages
Does not include the “Draw” drawing method Includes the “Draw” drawing method

The feature comparison shows that Analog Status tags have several advantages. There are more built-in features,
reducing the need to use extra tags to provide logging and alarms. Analog Status tags also support history reads and are
displayed on Station Pages. If you plan to use any of these features, then an Analog Status tag is probably your best
choice.

Why then might you ever use an Analog Input tag? First, the dedicated Logging or Alarm tags that you add to an analog
input will have more features and therefore more control than the built in logging and alarms of the analog status. The
other reason has to do with the overhead that comes with the Analog Status tag. For many inputs, you might not want
logging or alarms. In order to support these and other features, the Analog Status tag has more overhead. In most
applications, the difference in performance will never be noticed, but in larger applications, you may find that that there

Developer's Guide (part 1) How to Build an Application • 397

is a performance price to be paid when using a large number of Analog Status tags for inputs that do not require the
additional features.

When you do add Analog Status tags to your application, there is one extremely important configuration option to
remember: You should always set a value for the deadband. The automatic logging feature of these tags will add a new
record each time the value changes, regardless of how small that change is. To avoid filling the log file with system
noise, you should set the deadband to a small value, thus causing the tag to ignore any change less than this amount. For
example, on a input that changes from 0 to 100, you might set the deadband between 0.1 and 1.

Digital Input Tags

Digital inputs represent incoming digital data values from equipment, and provide drawing methods that change color,
appearance, or text to impart the value of the digital input and associated equipment.
A Digital Input tag can be a single bit digital input or a double bit digital input. For single bit digital inputs, there are two
possible states. For digital inputs that use two address bits, there are four possible states.

Note: Digital inputs clamp raw data values to either zero or one on each input pin (yielding a result of 0, 1, 2, or 3 for
pump status and Digital Status tags). Analog zero yields zero, while all other values yield 1. This is effective for analog
values that have discrete states (e.g. line voltage can be read for on/off), but pure analog data (e.g. velocity) will only
become false when the value drops below the sensitivity of the measuring device.

(Characteristics available in the Table of Type Characteristics.)

Digital Input Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Digital Input Properties: I/O Tab

The I/O Tab holds the properties used to identify and establish a connection to the communication driver tag being used
to exchange data with your physical I/O device (e.g. PLC or RTU). This is accomplished by identifying the
communication driver tag that communicates with the physical I/O device, the address at the physical I/O device from
which this tag is to read its data, and the rate at which the I/O device should be scanned for data.

Note: Digital Input tags can have single or double bit addresses. Information on single and double bit digital inputs can
be found in Single Bit and Double Bit Digital Inputs.

398 • How to Build an Application Developer's Guide (part 1)

I/O Device
Select the communication driver tag from which data will be read.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Bit 0 Address
The Bit 0 Address property is the address of the low order bit for this tag in the I/O device. If this is a single bit digital
tag, this is the field that specifies the address of that bit.

Bit 1 Address
The Bit 1 Address property is the address of the high order bit for the digital input in the I/O device. If this is a single bit
digital input, this field should be left blank.

Scan Interval
Provide the frequency, measured in seconds, that the I/O device should be scanned for new data. If the I/O Device is a
Polling driver, which provides its own scan interval, then this field will not accept data.

Manual Data
This optional field allows you to provide a constant value that will be used instead of input read by the communication
driver. It is commonly used when testing a new Analog Input tag when application is not attached to a live data source.
Tags that are using manual data are marked on screen by a flashing exclamation mark.

Invert Input
The Invert Input checkbox enables you to specify whether or not the value of this tag should be reversed. If selected, the
value for this tag will be inverted (i.e. 0 and 1 are swapped).
The typical use for input inversion is in projects where 1 indicates false or off, and 0 indicates true or on. By default, the
Invert Input checkbox is not selected.

Enable Output

Developer's Guide (part 1) How to Build an Application • 399

If checked, this input tag may also be used to write data to the specified Bit 0 address of the communication driver.
Pulsed writes are not available. A Security Privilege may be set in the Merit tab to restrict access to this feature.

Digital Input Properties: Owner Tab

Some VTS tags can be used in an owner/contributor structure where multiple contributor tags can supply their values to
an owner tag. The Owner Tab allows you to specify the owner tag to which this tag should contribute its data.

Note: There is no specific "owner" type, rather an owner tag is typically a custom designed tag that is created using VTS
scripting code for special projects.

Owner
The Owner field enables you to specify a tag to which this contributor should supply its data. An owner tag is one which
you must design and then create, using the VTS scripting language.
The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual
data value, to questionable data, according to the configuration of the checkboxes appearing beneath the Owner field.
These checkboxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value checkbox enables you to set the value of this contributor tag as the
nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner
tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack.
Priority checkbox causes the owner tag to keep track of the priority of the contributor's active alarm (or records an
Invalid if the contributor is not currently in an alarm state). Selecting the Set Active/Unack. Priority checkbox also
causes the owner tag to record whether or not the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values),
rather than reading data from their I/O device. When selected, the Record Use of Manual Data checkbox enables you to

400 • How to Build an Application Developer's Guide (part 1)

increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been
provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag
Quality checkbox enables you to increment the owner tag's count of the number of tags that are contributing quality data
by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the
Record Tag Validity checkbox enables you to increment the owner tag's count of the number of tags that are contributing
questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Digital Input Properties: Merit Tab

The Merit tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you suspect
the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its
data is marked for extra monitoring.
The Quality Based On field is for use when this tag is to be a contributor to a custom-built container tag. Please see the
topic Merit Tab and Quality Tab, for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

Digital Input Properties: Alarm Tab

The Alarm tab allows you to create new Alarm tags that will be triggered by this tag.
Use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will
automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Developer's Guide (part 1) How to Build an Application • 401

Digital Input Properties: Script Tab
The Script Tab allows you to create one or more Script tags to be associated with this tag.
A Script tag provides a means of creating a procedure, using VTS’s programming language, that will run whenever this
tag’s value changes.

Digital Input Properties: Logger Tab

The logger tab enables you to associate a single Logger tag with this tag. The Logger tag and the attached Historian will
record this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag will be
created as a child of the current tag.

Note: Only one Logger tag can be directly associated with a single input or output tag. If you need to have multiple
loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O Tag

Single Bit and Double Bit Digital Inputs

A single bit digital status reads a value of 0 or a 1 from one address on an I/O device. An example of a single bit digital
status would be a pump's status, where the pump is either off (0), or on (1).
A double bit digital status reads a value of 0 or 1 from two addresses on an I/O device. An example of an equipment
process requiring a double bit digital status might be a valve with 4 states: open, closed, open or close action in progress,
or error. The table below shows the possible values for a double bit digital status according to the values at each bit.

State Bit 1 Open Bit 0 Close Description Tag Value

State 0 0 0 A process is in action (either 0
the valve is opening, or is
closing)
State 1 0 1 The valve is closed. 1
State 2 1 0 The valve is open. 2
State 3 1 1 There is an error. 3

402 • How to Build an Application Developer's Guide (part 1)

 Invalid Invalid Invalid No data. Invalid

Digital Input Tag Drawing Methods

The following drawing methods are available to display information about your application’s Digital Input tags:
Animated Bitmap Drawing Method
Color Blink Drawing Method
Color Box Drawing Method
Color Line Drawing Method
Gradient Color Change Drawing Method
Image Change Drawing Method
Momentary Button Drawing Method
Plot Data Drawing Method
Set Value Button Drawing Method
Set Value Hotbox Drawing Method
Text Change Drawing Method

Digital Status Tags

Digital Status tags were originally unique to VTScada, but have long since been included in the core VTS software.
Digital Status tags accept incoming digital data from an I/O device. A Digital Status tag might be used to read the status
(e.g. off or on), or the mode (e.g. running or stopped) of a motor.

Note: VTS also includes Pump Status tags that are to be used for digital equipment processes related to pumps. For
information on Pump Status tags and their properties, please refer to Pump Status Tags.

A digital status can be a single bit digital input or a double bit digital input. For single bit digital inputs, there are two
possible states (e.g. off or on, or running or stopped), whereas for digital inputs that use two address bits, there are four
possible states (e.g. opened, closed, process in action (either opening or closing), or error).

Note: Digital inputs clamp raw data values to either zero or one on each input pin (yielding a result of 0, 1, 2, or 3 for
pump status and Digital Status tags). Analog zero yields zero, while all other values yield 1. This is effective for analog
values that have discrete states (e.g. line voltage can be read for on/off), but pure analog data (e.g. velocity) will only
become false when the value drops below the sensitivity of the measuring device.

Note: Never attempt to attach a Logger tag to a Digital Status tag. Digital Status tags have a built in logger.

(Characteristics available in the Table of Type Characteristics.)

Digital Status Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Developer's Guide (part 1) How to Build an Application • 403

Digital Status Properties: I/O Tab
The I/O Tab holds the properties used to identify and establish a connection to the communication driver tag being used
to exchange data with your physical I/O device (e.g. PLC or RTU), or to the Polling driver responsible for determining
the order and rate at which data polls will occur.

Note: Digital Status tags can have single or double bit addresses. Information on single and double bit digital inputs can
be found in Single Bit and Double Bit Digital Inputs.

I/O Device
Select the communication driver tag from which data will be read.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Bit 0 Address
The Bit 0 Address property is the address of the low order bit for this tag in the I/O device. If this is a single bit digital
tag, this is the field that specifies the address of that bit. The reported value of this digital tag is the data at this address
plus two times the data at the Bit 1.

Note: If a data logger is being used on a tag, it can only be for a single bit address.

Bit 1 Address
The Bit 1 Address property is the address of the high order bit for the digital input in the I/O device. If this is a single bit
digital input, this field should be left blank.

Scan Rate
Provide the frequency, measured in seconds, that the I/O device should be scanned for new data. If the I/O Device is a
Polling driver, which provides its own scan interval, then this field will not accept data.

404 • How to Build an Application Developer's Guide (part 1)

Read History
If checked, the field Bit 0 Address becomes History Address and the field History Scan Interval is enabled.

History Address
If set, then the Bit 0 address becomes optional. This field provides a means of reading values as recorded by a data
logger.
If both the Bit 0 address and the history address are provided, then the bit 0 address will be polled for data at the interval
set by the Scan Rate, but the values read from the data logger will overwrite the values logged by this tag when it is
updated.
The form for the history address will depend on the RTU. Please refer to the addressing reference chapter for your driver.

History Scan Interval

Sets the time between polls of the history data logger. If a History address has been set, but this field is left blank, then it
will default to the value set in the Scan Rate field. The recommended value for this field is 60 seconds. Lesser values
may cause communications to slow down.

Manual Data
This optional field allows you to provide a constant value that will be used instead of input read by the communication
driver. It is commonly used when testing a new Analog Input tag when application is not attached to a live data source.
Tags that are using manual data are marked on screen by a flashing exclamation mark.

Off Text
The Off Text property enables you to configure text that will be displayed in some of the tag's drawing methods when
the value of this tag is 0 or false/off.

On Text
The On Text property enables you to configure text that will be displayed in some of the tag's drawing methods when the
value of the tag is 1 or true/on.

Invert Input
If the Invert Input checkbox is selected, the value of the tag being used as the data source is reversed (i.e. a 1 becomes a
0 or a 0 becomes a 1) before it is written to the I/O device.

Enable Output
If checked, this input tag may also be used to write data to the specified Bit 0 address of the communication driver.
Pulsed writes are not available. A Security Privilege may be set in the Quality tab to restrict access to this feature.

Digital Status Properties: Alarm Setup Tab

The Alarm Setup Tab allows you to configure one alarm based on the status of this tag. Note that while the priority is set
to "None", all other controls are disabled.

Developer's Guide (part 1) How to Build an Application • 405

Alarm Priority
The Alarm Priority drop-down list enables you to select the priority of the alarm that will be triggered for this tag. The
available priorities are:
• None (all other controls will be disabled)
• 0 – Event
• 1 – Critical Alarm
• 2 – High Alarm
• 3 – Warning Alarm
• 4 – Notice Alarm
If you have defined your own Alarm Priority tags, those will also be available for selection.

Alarm State
The Alarm State spin box enables you to select the trigger for the alarm. The alarm will be triggered when the tag's state
becomes one of the following:
0 The alarm is triggered when Bit 0 goes low. The Bit 1 address either has not been provided or is low.
1 The alarm is triggered when Bit 0 goes high. The Bit 1 address either has not been provided or is low.
2 Two addresses provided. Bit 0 goes low and Bit 1 goes high.
3 Two addresses provided. Both Bit 0 and Bit 1 go high.
Upon Change - any change of state triggers an alarm. Note that when the Upon Change option is selected, the
trip alarm option will be set and cannot be un-selected by the developer.

Alarm Delay
Transient changes in state can result in multiple alarms being triggered. By setting an alarm delay, you can specify that if
the tag’s state changes back one which does not constitute an alarm situation, it must remain in that state for a given
length of time before the alarm is deemed to be inactive.

Alarm Rearm Time

406 • How to Build an Application Developer's Guide (part 1)

Applies only if Alarm Rearm Enable is checked for this alarm. If the alarm has been acknowledged, but remains active
for the time shown in this field, the alarm will return to the un-acknowledged state. Audible and visible warnings
configured for this alarm’s priority level, will again be displayed. The Alarm Rearm Time is measured in seconds, and
defaults to 3600 (1 hour). The value in this field must be greater than 0.

Alarm Rearm Enable

Controls whether this alarm will revert back to an un-acknowledged state if it remains active for the length of time set in
Alarm Rearm Time, after having been acknowledged by the operator.

Disable Alarm
The Disable Alarm checkbox enables you to specify whether the alarm for this tag is disabled or enabled. Disabling of
alarms is typically used in situations where you wish to avoid false alarms. For example, in the event that routine
maintenance is being performed on the equipment represented by this tag, or when you are aware that another
interruption in communications will occur for a period of time. In such situations, the alarm can be disabled until the
maintenance is complete and communications are re-established.

Trip Alarm
The Trip Alarm checkbox enables you to indicate whether you wish this alarm to be a trip alarm.
Trip alarms do not have the attribute of being Active or Inactive based on the value of the Trigger tag. Once triggered,
the alarm must be acknowledged by an operator, but the underlying cause of the alarm need not be cleared.

Append State to Alarm Message

When the Append State to Alarm Message checkbox is selected, VTS will append the text used for the state of the tag, as
taken from the Off Text and On Text fields in the tag’s I/O tab, to the alarm message.

Popup Enable
If the configuration variable AlarmPopupsEnable is set to 1, then setting either the Low Alarm Popup Enable or the High
Alarm Popup Enable, will result in a pop-up dialog being displayed whenever the respective alarm is triggered. It is
strongly suggested that this feature be used sparingly.

Note: If you wish to override the built-in alarm for a Digital Status tag, please refer to "Overriding Built-in Alarms".

Digital Status Properties: External Alarms Tab

The External Alarms tab is used to display, add or remove separate Alarm tags that are triggered by this Digital Status
tag. Use the Add button to create new external Alarm tags and the Delete button to remove them. The new alarm tags
will be created as children of the current tag.

Developer's Guide (part 1) How to Build an Application • 407

Digital Status Properties: Quality Tab
The Quality tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you
suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure
that its data is marked for extra monitoring.
The Quality Based On field is for use when this tag is to be a contributor to a custom-built container tag. Please see the
topic Merit Tab and Quality Tab, for details.

Digital Status Properties: Order Tab

(For use with VTScada-based applications only)
The control found on this tab enables you to specify the placement of this tag when viewed in an associated station
dialog. See Order Tab for further details.

408 • How to Build an Application Developer's Guide (part 1)

Digital Status Properties: Historian Tab
If you select a Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer.
Historians are described in the topic, Historian Tag. You may log to more than one Historian by duplicating this tag's
value in a Calculation tag and attaching to it a Logger that is configured with a different Historian or a different
logging rate.

Note: There are consequences if you change the selected Historian tag after you have begun
collecting data. If you switch to a new Historian (perhaps for organizational or load sharing
purposes), the data collected for this tag by the previous Historian will become inaccessible.

Digital Status Tag Drawing Methods

The following drawing methods are available to display information about your application’s Digital Status tags:
Animated Bitmap Drawing Method
Color Blink Drawing Method
Color Box Drawing Method
Color Line Drawing Method
Draw Drawing Method
Gradient Color Change Drawing Method
Image Change Drawing Method
Momentary Button Drawing Method
Plot Data Drawing Method
Set Value Button Drawing Method
Set Value Hotbox Drawing Method
Text Change Drawing Method
Two Color Bar Drawing Method

Pulse Input Tags

Pulse input tags accept incoming analog data from a pulse input device (such as a rain gauge, transducer, or a gas, water,
or electric meter). In a DFS RTU, every time the count is read, it will be reset by the RTU. Note that if you are unable
to read the response due to a communication error, the count will be reset regardless and you will lose that information.

Developer's Guide (part 1) How to Build an Application • 409

Note that the Pulse Input Tag was designed to work with the Data Flow driver and will not permit the selection of any
other driver type.

(Characteristics available in the Table of Type Characteristics.)

Pulse Input Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Pulse Input Properties: I/O Tab

The I/O Tab holds the properties used to identify and establish a connection to the communication driver tag being used
to exchange data with your physical I/O device.

I/O Device
A Data Flow Driver is required for this tag to function. Select the communication driver tag from which data will be
read.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Address
Provide the address within the I/O device from which this tag is to read data. This value must match the configuration
of your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.
For some drivers (SNMP and the OPC Client) an address browser is provided to assist you.

Scan Interval

410 • How to Build an Application Developer's Guide (part 1)

Provide the frequency, measured in seconds, that the I/O device should be scanned for new data. If the I/O Device is a
Polling driver, which provides its own scan interval, then this field will not accept data.

Engineering Units
Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc.

Manual Data
This optional field allows you to provide a constant value that will be used instead of input read by the communication
driver. It is commonly used when testing a new Analog Input tag when application is not attached to a live data source.
Tags that are using manual data are marked on screen by a flashing exclamation mark.

Pulse Input Properties: Scaling Tab

The Scaling Tab requires a scaled value that will be counted per incoming pulse.

Pulse Input Properties: Quality Tab

The Quality tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you
suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure
that its data is marked for extra monitoring.
This tab also contains the Quality Based On field, for use when this tag is to be a contributor to a custom-built container
tag. Please see the topic Merit Tab and Quality Tab, for details.

Developer's Guide (part 1) How to Build an Application • 411

Pulse Input Properties: Order Tab
The Order Tab for a Pump Status tag enables you to specify the placement of this tag when viewed in an associated
station dialog.

Pulse Input Properties: Historian Tab

If you select a Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer.
Historians are described in the topic, Historian Tag. You may log to more than one Historian by duplicating this tag's
value in a Calculation tag and attaching to it a Logger that is configured with a different Historian or a different
logging rate.

Note: There are consequences if you change the selected Historian tag after you have begun
collecting data. If you switch to a new Historian (perhaps for organizational or load sharing
purposes), the data collected for this tag by the previous Historian will become inaccessible.

Pulse Input Tag Drawing Methods (VTScada)

The following drawing methods are available to display information about your application’s Pulse Input tags:
Draw Drawing Method

412 • How to Build an Application Developer's Guide (part 1)

Totalizer Drawing Method

Pump Status Tags

Pump status tags accept incoming digital data from pumps.
VTS also includes Digital Status tags that are to be used for equipment processes related to digital equipment other than
pumps. For information on Digital Status tags and their properties, please refer to Digital Status tags.

Note: Digital inputs clamp raw data values to either zero or one on each input pin (yielding a result of 0, 1, 2, or 3 for
pump status and Digital Status tags). Analog zero yields zero, while all other values yield 1. This is effective for analog
values that have discrete states (e.g. line voltage can be read for on/off), but pure analog data (e.g. velocity) will only
become false when the value drops below the sensitivity of the measuring device.

Note: Never attempt to attach a Logger tag to a Pump Status tag. Pump Status tags have a built in logger.

(Characteristics available in the Table of Type Characteristics.)

Pump Status Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Pump Status Properties: I/O Tab

The I/O Tab holds the properties used to identify and establish a connection to the communication driver tag being used
to exchange data with your physical I/O device (e.g. PLC or RTU), or to the Polling driver responsible for determining
the order and rate at which data polls will occur.

Developer's Guide (part 1) How to Build an Application • 413

Pump status tags can have single or double bit addresses. For further information on single and double bit digital inputs,
see: Single Bit and Double Bit Digital Inputs.

I/O Device
Select the communication driver tag from which data will be read.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Bit 0 Address
The Bit 0 Address property is the address of the low order bit for this tag in the I/O device. If this is a single bit digital
tag, this is the field that specifies the address of that bit. The reported value of this digital tag is the data at this address
plus two times the data at the Bit 1.

Note: If a data logger is being used on a tag, it can only be for a single bit address.

Bit 1 Address
The Bit 1 Address property is the address of the high order bit for the digital input in the I/O device. If this is a single bit
digital input, this field should be left blank.

Scan Rate
Provide the frequency, measured in seconds, that the I/O device should be scanned for new data. If the I/O Device is a
Polling driver, which provides its own scan interval, then this field will not accept data.

Read History
If checked, the field Bit 0 Address becomes History Address and the field History Scan Interval is enabled.

History Address
If set, then the Bit 0 address becomes optional. This field provides a means of reading values as recorded by a data
logger.
If both the Bit 0 address and the history address are provided, then the Bit 0 address will be polled for data at the interval
set by the Scan Rate, but the values read from the data logger will overwrite the values logged by this tag when it is
updated.
The form for the history address will depend on the RTU. Please refer to the addressing reference chapter for your driver.

History Scan Interval

Sets the time between polls of the history data logger. If a History address has been set, but this field is left blank, then it
will default to the value set in the Scan Rate field. The recommended value for this field is 60 seconds. Lesser values
may cause communications to slow down.

Off Text
The Off Text property enables you to configure text that will be displayed in some of the tag's drawing methods when
the value of this tag is 0 or false/off.

On Text
The On Text property enables you to configure text that will be displayed in some of the tag's drawing methods when the
value of the tag is 1 or true/on.

Manual Data

414 • How to Build an Application Developer's Guide (part 1)

This optional field allows you to provide a constant value that will be used instead of input read by the communication
driver. It is commonly used when testing a new Analog Input tag when application is not attached to a live data source.
Tags that are using manual data are marked on screen by a flashing exclamation mark.

Invert Input
If the Invert Input checkbox is selected, the value of the tag being used as the data source is reversed (i.e. a 1 becomes a
0 or a 0 becomes a 1) before it is written to the I/O device.

Enable Output
If checked, this input tag may also be used to write data to the specified Bit 0 address of the communication driver. A
Security Privilege may be set in the Quality tab to restrict access to this feature.

Pump Status Properties: Alarm Setup Tab

The Alarm Setup Tab allows you to configure one alarm based on the status of this tag. Note that, while the priority is set
to "None", all other controls are disabled.

Alarm Priority
The Alarm Priority drop-down list enables you to select the priority of the alarm that will be triggered for this tag. The
available priorities are:
• None
• 0 – Event
• 1 – Critical Alarm
• 2 – High Alarm
• 3 – Warning Alarm
• 4 – Notice Alarm
If you have defined your own Alarm Priority tags, those will also be available for selection.

Alarm State

Developer's Guide (part 1) How to Build an Application • 415

The Alarm State spin box enables you to select the trigger for the alarm. The alarm will be triggered when the tag's state
becomes one of the following:
0 The alarm is triggered when Bit 0 goes low. The Bit 1 address either has not been provided or is low.
1 The alarm is triggered when Bit 0 goes high. The Bit 1 address either has not been provided or is low.
2 Two addresses provided. Bit 0 goes low and Bit 1 goes high.
3 Two addresses provided. Both Bit 0 and Bit 1 go high.
Upon Change - any change of state triggers an alarm. Note that when the Upon Change option is selected, the
trip alarm option will be set and cannot be un-selected by the developer.

Alarm Delay
Transient changes in state can result in multiple alarms being triggered. By setting an alarm delay, you can specify that if
the tag’s state changes back one which does not constitute an alarm situation, it must remain in that state for a given
length of time before the alarm is deemed to be inactive.

Alarm Rearm Time

Applies only if Alarm Rearm Enable is checked for this alarm. If the alarm has been acknowledged, but remains active
for the time shown in this field, the alarm will return to the un-acknowledged state. Audible and visible warnings
configured for this alarm’s priority level, will again be displayed. The Alarm Rearm Time is measured in seconds, and
defaults to 3600 (1 hour). The value in this field must be greater than 0.

Alarm Rearm Enable

Controls whether this alarm will revert back to an un-acknowledged state if it remains active for the length of time set in
Alarm Rearm Time, after having been acknowledged by the operator.

Disable Alarm
The Disable Alarm checkbox enables you to specify whether the low alarm for this tag is disabled or enabled. Disabling
of alarms is typically used in situations where you wish to avoid false alarms. For example, in the event that routine
maintenance is being performed on the equipment represented by this tag, or when you are aware that another
interruption in communications will occur for a period of time; in such situations, the alarm can be disabled until the
maintenance is complete and communications are reestablished.

Trip Alarm
The Trip Alarm checkbox enables you to indicate whether you wish this alarm to be a trip alarm.
Trip alarms differ from level alarms in that they are not active or inactive based on the value of the Trigger tag. Once
triggered, they must be acknowledged, but there is no requirement that the cause of the alarm condition be cleared.

Append State to Alarm Message

When the Append State to Alarm Message checkbox is selected, VTS will append the text used for the state of the tag, as
taken from the Off Text and On Text fields in the tag’s I/O tab, to the alarm message.

Popup Enable
If the configuration variable AlarmPopupsEnable is set to 1, then setting either the Low Alarm Popup Enable or the High
Alarm Popup Enable, will result in a pop-up dialog being displayed whenever the respective alarm is triggered. It is
strongly suggested that this feature be used sparingly.

Note: If you wish to override the built-in alarm for a Pump Status tag, please refer to "Overriding Built-in Alarms".

416 • How to Build an Application Developer's Guide (part 1)

Pump Status Properties: External Alarms Tab
The External Alarms tab is used to display, add or remove separate Alarm tags that are triggered by this Pump Status tag.
Use the Add button to create new external Alarm tags and the Delete button to remove them. The new alarm tags will be
created as children of the current tag.

Pump Status Properties: Quality Tab

The Quality tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you
suspect the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure
that its data is marked for extra monitoring.
The Quality Based On field is for use when this tag is to be a contributor to a custom-built container tag. Please see the
topic Merit Tab and Quality Tab, for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

Pump Status Properties: Order Tab

The Order Tab for a Pump Status tag enables you to specify the placement of this tag when viewed in an associated
station dialog.

Pump Status Properties: Historian Tab

If you select a Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer.
Historians are described in the topic, Historian Tag. You may log to more than one Historian by duplicating this tag's
value in a Calculation tag and attaching to it a Logger that is configured with a different Historian or a different
logging rate.

Note: There are consequences if you change the selected Historian tag after you have begun
collecting data. If you switch to a new Historian (perhaps for organizational or load sharing
purposes), the data collected for this tag by the previous Historian will become inaccessible.

Developer's Guide (part 1) How to Build an Application • 417

Pump Status Tag Drawing Methods
The following drawing methods are available to display information about your application’s Pump Status tags:
Animated Bitmap Drawing Method
Color Blink Drawing Method
Color Box Drawing Method
Color Line Drawing Method
Draw Drawing Method
Gradient Color Change Drawing Method
Image Change Drawing Method
Momentary Button Drawing Method
Plot Data Drawing Method
Set Value Button Drawing Method
Set Value Hotbox Drawing Method
Text Change Drawing Method
Two Color Bar Drawing Method

Output Tags
Output tags are used to write data to an I/O device, such as a programmable logic controller (PLC), remote terminal unit
(RTU), or an I/O board. These tags permit the handling of either digital (discrete), or analog (continuous floating point)
values.

Note: Output tags will not write INVALID data. (INVALID is a specific VTS data type, roughly meaning, "no valid
value available"). Also, with the exception of the MultiWrite tag, no output type will write an unchanged value twice
unless directed by the driver performing a "re-write outputs".

The following output tags are included with VTS:

Analog Control tags Analog Output tags
Deadband Control Tags Digital Control tags
Digital Output tags Multi-Write tags

418 • How to Build an Application Developer's Guide (part 1)

 Selector Switch tags Trigger tags

(Characteristics available in the Table of Type Characteristics.)

Analog Control Tags

It is the role of Analog Control tags to transmit analog data entered by the user to an I/O device. An Analog Control tag
might be used to change the speed of a motor, or to specify a feed time for chemicals to be added to a well or tank.
In most cases, an operator will use the control tag to write information out to the system. You also have the option of
configuring an automatic data source such as a Calculation tag to provide the information that is to be written.

Analog Control Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Analog Control Properties: I/O Tab

In the I/O Tab, you will find the properties used to identify and establish a connection to the communication driver tag
being used to exchange data with your physical I/O device (e.g. PLC or RTU), or to the Polling driver responsible for
determining the order and rate at which data polls will occur.

I/O Device
Select the communication driver tag to which data will be written.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Developer's Guide (part 1) How to Build an Application • 419

Address
Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of
your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.
For some drivers (SNMP and the OPC Client) an address browser is provided to assist you.

Engineering Units
Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc.

Data Source
[Optional] While Analog Control tags usually take their value from an operator-controlled drawing object, the Data
Source field provides the option of configuring this tag to accept a value from another tag or expression instead.
The value from the Data Source can be written to the I/O device, or it can be used to simply update the drawing method
display. See the following topics: Write output when Data Source Changes and Use Data Source for display only.
If you have selected a data source that is configured to write output, and have also drawn the tag as an object that
operators can use to set values, then both can write to the I/O device. The value written will be whichever was most
recently changed.

Write output when Data Source changes

When selected, the value supplied by the data source tag or expression will be written to the I/O device and will also be
used to set this tag’s value. Selecting this option automatically de-selects the “Use Data Source for display only” option.

Use Data Source for display only

When selected, the value supplied by the data source tag or expression will not be written to the I/O device, but will be
used to set this tag’s value. Selecting this option automatically de-selects the “Write output when Data Source changes”
option.

Analog Control Properties: Scaling Tab

The Scaling Tab requires values that will be used to convert unscaled, raw data from the I/O device associated with this
tag into scaled data that will be reported to operators. VTS uses an algorithm to calculate this tag's value internally, based
on the known unscaled and scaled values you supply.

420 • How to Build an Application Developer's Guide (part 1)

 Assuming a linear relationship between the values, by
providing a known minimum scaled value for a given
minimum unscaled value, and a known maximum scaled
value for a given maximum unscaled value, VTS can
provide a scaled value for any given unscaled input value.

Analog Control Properties: Merit Tab

The Merit tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you suspect
the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its
data is marked for extra monitoring. Please see the topic Merit Tab and Quality Tab, for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

Developer's Guide (part 1) How to Build an Application • 421

Analog Control Properties: Order Tab
The Order Tab for a Analog Control tag enables you to specify the placement of this tag when viewed in an associated
station dialog.

Analog Control Tag Drawing Methods

The following drawing methods are available to Analog Control tags:
Animated Bitmap Drawing Method Bottom Bar Drawing Method
Color Blink Drawing Method Color Box Drawing Method
Color Fill Drawing Method Color Line Drawing Method
Compass 1 Drawing Method Compass 2 Drawing Method
Draw Text Drawing Method Droplist Control Drawing Method
Gradient Color Change Drawing Method Image Change Drawing Method
Left Bar Drawing Method Meter 1 Drawing Method
Meter 2 Drawing Method Meter 3 Drawing Method
Momentary Button Drawing Method Multi-color Drawing Method
Multi-text Drawing Method Numeric Entry Drawing Method
Numeric Value Drawing Method Plot Data Drawing Method
Right Bar Drawing Method Set Analog Value Drawing Method
Set Value Button Drawing Method Set Value Hotbox Drawing Method
Slider Drawing Method Text Change Drawing Method
Top Bar Drawing Method Two Color Bar Drawing Method

Note: The Numeric Entry, Slider, Set Analog Value, Set Value Button, Set Value Hotbox, and Droplist Control drawing
methods allow users to actually output data to the equipment process associated with the tag being drawn. All other
drawing methods simply display the value that has been output.

422 • How to Build an Application Developer's Guide (part 1)

Analog Output Tags
It is the role of analog outputs to take analog data from the user or from another tag, and write it to an I/O device. Analog
data can be transmitted by an operator via a slider or a numeric entry field.

(Characteristics available in the Table of Type Characteristics.)

Analog Output Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Analog Output Properties: I/O Tab

The I/O Tab holds the properties used to identify and establish a connection to the communication driver tag being used
to exchange data with your physical I/O device (e.g. PLC or RTU). This is accomplished by identifying the
communication driver tag that communicates with the physical I/O device, the address at the physical I/O device from
which this tag is to read its data, and the rate at which the I/O device should be scanned for data.

I/O Device
Select the communication driver tag to which data will be written.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Address
Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of
your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.

Developer's Guide (part 1) How to Build an Application • 423

For some drivers (SNMP and the OPC Client) an address browser is provided to assist you.

Engineering Units
Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc.

Data Source
The value output by an analog control can be supplied by an operator via a drawing method on the screen, it can be
supplied by a data source, or both can be used.
Normally, the data source would be another tag or an expression. If both a data source and an operator control are
provided, then the value of the control tag will be whichever value was most recently set.

Use Data Source for display only

The data source can be used either as the value of the tag, updating the tag's value whenever the data source changes, or
it can be used for display purposes only, leaving the value output by the tag unchanged. This checkbox allows you to
select one mode or the other.

Analog Output Properties: Scaling Tab

The Scaling Tab requires values that will be used to convert unscaled, raw data from the I/O device associated with this
tag into scaled data that will be reported to operators. VTS uses an algorithm to calculate this tag's value internally, based
on the known unscaled and scaled values you supply.

424 • How to Build an Application Developer's Guide (part 1)

 Assuming a linear relationship between the values, by
providing a known minimum scaled value for a given
minimum unscaled value, and a known maximum scaled
value for a given maximum unscaled value, VTS can
provide a scaled value for any given unscaled input value.

Analog Output Properties: Owner Tab

Some VTS tags can be used in an owner/contributor structure where multiple contributor tags can supply their values to
an owner tag. The Owner Tab allows you to specify the owner tag to which this tag should contribute its data.

Note: There is no specific "owner" type, rather an owner tag is typically a custom designed tag that is created using VTS
scripting code for special projects.

Owner
The Owner field enables you to specify a tag to which this contributor should supply its data. An owner tag is one which
you must design and then create, using the VTS scripting language.
The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual
data value, to questionable data, according to the configuration of the checkboxes appearing beneath the Owner field.
These checkboxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

Developer's Guide (part 1) How to Build an Application • 425

When selected, the Set Owner\DataX[…] To Value checkbox enables you to set the value of this contributor tag as the
nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner
tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack.
Priority checkbox causes the owner tag to keep track of the priority of the contributor's active alarm (or records an
Invalid if the contributor is not currently in an alarm state). Selecting the Set Active/Unack. Priority checkbox also
causes the owner tag to record whether or not the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values),
rather than reading data from their I/O device. When selected, the Record Use of Manual Data checkbox enables you to
increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been
provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag
Quality checkbox enables you to increment the owner tag's count of the number of tags that are contributing quality data
by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the
Record Tag Validity checkbox enables you to increment the owner tag's count of the number of tags that are contributing
questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Analog Output Properties: Merit Tab

The Merit tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you suspect
the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its
data is marked for extra monitoring. Please see the topic Merit Tab and Quality Tab, for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

426 • How to Build an Application Developer's Guide (part 1)

Analog Output Properties: Alarm Tab
The Alarm tab allows you to create new Alarm tags that will be triggered by this tag.
Use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will
automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Analog Output Properties: Script Tab

The Script Tab allows you to create one or more Script tags to be associated with this tag.
A Script tag provides a means of creating a procedure, using VTS’s programming language, that will run whenever this
tag’s value changes.

Analog Output Properties: Logger Tab

The logger tab enables you to associate a single Logger tag with this tag. The Logger tag will work with the attached
Historian to record this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag
will be created as a child of the current tag.

Note: It is recommended that only one Logger tag be directly associated with a single input or output tag. If you require
multiple loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O
Tag

Analog Output Tag Drawing Methods

The following drawing methods are available to Analog Output tags:
Animated Bitmap Drawing Method Bottom Bar Drawing Method
Color Blink Drawing Method Color Box Drawing Method
Color Fill Drawing Method Color Line Drawing Method
Compass 1 Drawing Method Compass 2 Drawing Method
Draw Text Drawing Method Droplist Control Drawing Method
Gradient Color Change Drawing Method Image Change Drawing Method

Developer's Guide (part 1) How to Build an Application • 427

Left Bar Drawing Method Meter 1 Drawing Method
Meter 2 Drawing Method Meter 3 Drawing Method
Momentary Button Drawing Method Multi-color Drawing Method
Multi-text Drawing Method Numeric Entry Drawing Method
Numeric Value Drawing Method Plot Data Drawing Method
Right Bar Drawing Method Set Analog Value Drawing Method
Set Value Button Drawing Method Set Value Hotbox Drawing Method
Slider Drawing Method Text Change Drawing Method
Top Bar Drawing Method Two Color Bar Drawing Method

Note: Of the above tag drawing methods, only the Numeric Entry, Slider, Set Analog Value, Droplist Control,
SetValueBtn, SetValueHotbox, and Momentary Button methods enable users to output values to the associated tags; the
remaining drawing methods display the value that has been output.

Deadband Control Tags

Deadband control tags monitor the value of any tag with a numeric value and compare the monitored tag's value to a low
set point and a high set point. If the value of the monitored tag falls below the low set point, the value of the Deadband
Control tag is set to 1. If the value of the monitored tag rises above the high set point, the value of the Deadband Control
tag is set to 0.
A checkbox allows this action to be reversed.
(Characteristics available in the Table of Type Characteristics.)

Deadband Control Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Deadband Control Properties: Options Tab

The Options tab of a Deadband Control tag's properties folder enables you to select the tag whose value will be
monitored, and to configure details such as whether the control is enabled and whether it will send a start signal when the
monitored value goes above or goes below the set point.

428 • How to Build an Application Developer's Guide (part 1)

Monitored Value
This should be either a tag, or an expression based on one or more tag values. While Constant is available as an option
due to the nature of this field selector, it will not be useful as a monitored value.
The deadband control compares the Monitored Value with its low and high set points to determine its own value. If the
Monitored Value is less than the value of the Low Setpoint, then the value of this Deadband Control tag will be 1. If the
Monitored Value is greater than the value of the High Setpoint, the value of this Deadband Control tag will be 0.

Note: The behavior of this Deadband Control tag can be reversed such that if the Monitored Value is greater than the
value of the High Setpoint, the value of this Deadband Control tag will be 1 using the Operation radio buttons (see
below).

Inhibit
The effect of setting the inhibit flag is to force the tag’s value to be 0, regardless of other settings.
A valid value for the Inhibit field can be provided via any of a constant, an expression, or a tag. Please see Constant,
Expression or Tag for help selecting which to use.

Operation
The Operation section contains two radio buttons that enable you to set the behavior of this tag.
Start On High: If the Start On High radio button is selected, the value of this tag will be reversed from its default. When
the Monitored Value is greater than the High Setpoint (see Deadband Control Properties: Setpoints Tab), the value of
this Deadband Control tag will be 1 (rather than 0, which is the default).
Start On Low: If the Start On Low radio button is selected, if the Monitored Value is less than the Low Setpoint (see
Deadband Control Properties: Setpoints Tab), the value of this Deadband Control tag will be 1.

Manual Data
The Manual Data property enables you to set a user-defined value for this tag. If the value of the Manual Data field is left
Invalid, or is not a valid number, then the value for this tag is read.

Developer's Guide (part 1) How to Build an Application • 429

Note: If the value entered into the Manual Data field is a 0, the actual value of this tag is also overridden, as 0 is
considered a valid value. Therefore, you must clear the Manual Data field entirely if you wish the actual value of this tag
to be read, rather than a manually-entered value.

Questionable Data
Questionable data is a means of indicating that the data being reported by a tag might not be accurate. Use this field to
flag the tag’s data in the event that you suspect the values it is reporting might not be accurate, or when this tag has
initially been created and you wish to ensure that its data is marked for extra monitoring.

Deadband Control Properties: Setpoints Tab

In this tab, you can configure the low and high set points that will be compared to the monitored value.

High Setpoint and Low Setpoint

The Deadband Control tag will compare the values in the Setpoint fields with the Monitored Value to determine its own
value.
If the Monitored Value exceeds the value of the High Setpoint, the value of this Deadband Control tag will be 0. The
result of this comparison is referred to as the stop condition.
If the Monitored Value is less than the value of the Low Setpoint, the value of this Deadband Control tag will be 1. The
result of this comparison is referred to as the start condition.

Note: The behavior of this Deadband Control tag can be reversed such that if the Monitored Value is greater than the
value of the High Setpoint, the value of this Deadband Control tag will be 1.

A valid value for the High Setpoint field and the Low Setpoint field can be provided via any of a constant, an expression,
or a tag. Please see Constant, Expression or Tag for help selecting which to use.

Start Delay and Stop Delay

You can enter a value (measured in seconds) in the Start Delay field to set a length of time that to wait after the start
condition before setting the value of this Deadband Control tag to 1.

430 • How to Build an Application Developer's Guide (part 1)

The Stop Delay field works in the same way: Enter the number of seconds that the tag should wait after the stop
condition before setting the value of this Deadband Control tag to 0.

Deadband Control Properties: Owner Tab

Some VTS tags can be used in an owner/contributor structure where multiple contributor tags can supply their values to
an owner tag. The Owner Tab allows you to specify the owner tag to which this tag should contribute its data.

Note: There is no specific "owner" type, rather an owner tag is typically a custom designed tag that is created using VTS
scripting code for special projects.

Owner
The Owner field enables you to specify a tag to which this contributor should supply its data. An owner tag is one which
you must design and then create, using the VTS scripting language.
The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual
data value, to questionable data, according to the configuration of the checkboxes appearing beneath the Owner field.
These checkboxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value checkbox enables you to set the value of this contributor tag as the
nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner
tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack.
Priority checkbox causes the owner tag to keep track of the priority of the contributor's active alarm (or records an
Invalid if the contributor is not currently in an alarm state). Selecting the Set Active/Unack. Priority checkbox also
causes the owner tag to record whether or not the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values),
rather than reading data from their I/O device. When selected, the Record Use of Manual Data checkbox enables you to

Developer's Guide (part 1) How to Build an Application • 431

increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been
provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag
Quality checkbox enables you to increment the owner tag's count of the number of tags that are contributing quality data
by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the
Record Tag Validity checkbox enables you to increment the owner tag's count of the number of tags that are contributing
questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Deadband Control Properties: Alarm Tab

The Alarm tab allows you to create new Alarm tags that will be triggered by this tag.
Use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will
automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Deadband Control Properties: Logger Tab

The logger tab enables you to associate a single Logger tag with this tag. The Logger tag will work with the attached
Historian to record this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag
will be created as a child of the current tag.

Note: Only one Logger tag can be directly associated with a single input or output tag. If you need to have multiple
loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O Tag

Deadband Control Tag Drawing Methods

Deadband control tags monitor the value of any tag with a numeric value and compare the monitored tag's value to a low
set point and a high set point. If the value of the monitored tag falls below the low set point, the value of the Deadband
Control tag is set to 1. If the value of the monitored tag rises above the high set point, the value of the Deadband Control

432 • How to Build an Application Developer's Guide (part 1)

tag is set to 0. The drawing methods for Deadband Control tags enable the operator to set the value if it falls between the
low and high set points.
The following drawing methods are available to Deadband Control tags:
Animated Bitmap Drawing Method Bottom Bar Drawing Method
Color Blink Drawing Method Color Box Drawing Method
Color Fill Drawing Method Draw Text Drawing Method
Gradient Color Change Drawing Method Image Change Drawing Method
Left Bar Drawing Method Meter 1 Drawing Method
Meter 2 Drawing Method Meter 3 Drawing Method
Multi-color Drawing Method Multi-text Drawing Method
Numeric Value Drawing Method Plot Data Drawing Method
Right Bar Drawing Method Text Change Drawing Method
Top Bar Drawing Method Two Color Bar Drawing Method

Digital Control Tags

Digital Control tags were originally unique to VTScada, but are now available to all VTS applications. These tags
transmit digital data that is entered by the user or from another tag and write it to an I/O device.
A Digital Control tag might be used to turn a pump off or on, open a valve, or change the mode of a piece of equipment
from manual to auto.
(Characteristics available in the Table of Type Characteristics.)

Digital Control Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Digital Control Properties: I/O Tab

The I/O Tab contains properties used to identify and establish a connection to the communication driver tag being used
to exchange data with your physical I/O device (e.g. PLC or RTU), or to the Polling driver responsible for determining
the order and rate at which data polls will occur.

Developer's Guide (part 1) How to Build an Application • 433

I/O Device
Select the communication driver tag to which data will be written.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Address
Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of
your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.
For some drivers (SNMP and the OPC Client) an address browser is provided to assist you.

Pulse Duration
If you are using a pulsed signal, enter the duration of the pulse here in seconds or decimal parts of a second. In the case
of pulsed outputs, the value of this tag is 1 while the attempted control is in progress (i.e. for the length of the pulse).

If the value of Pulse Duration is 0 or blank (Invalid), then a constant value will be written to the I/O device.

Data Source
The value output by the control can be supplied by a data source. For a digital control, the values supplied by the data
source should be limited to 1 or 0 (true or false).

Off Text and On Text

Some drawing methods used by Station tags are able to display the text you provide here. Note that the value of Digital
Control itself is used to indicate "currently writing" or "not currently writing", rather than the value being written. See
also: Confirmation Prompts for Output Tags.

Invert Output

434 • How to Build an Application Developer's Guide (part 1)

Reverse the value of the output before writing.

Invert Data Source

Reverse the value coming from the data source before using.

Digital Control Properties: Feedback Tab

The Feedback tab can be used to select an alarm, alarm priority, digital status, or Digital Control tag that will provide
feedback when this tag's control action has successfully been completed.

Note: Remember, the existence of an output tag is not enough to output a value to the I/O device; you must draw the tag
using a control drawing method (such as a Set Value Button) to enable users to send a value to the I/O device and related
equipment.

Feedback
The Feedback field enables you to specify an existing alarm, alarm priority, digital status, or Digital Control tag whose
value can be used to determine whether the control action for this tag was successful. When a value is output by this tag,
the feedback tag reads its value from the I/O device at the same address, and compares this value with the expected
value(s) configured in the Feedback At State 0 and Feedback At State 1 spin boxes (see below).
If the Pulse Duration property for this tag (as set on the I/O tab) is set to a valid value greater than 0 (i.e. a pulsed signal),
then the Feedback At State 0 property is ignored, as the logic assumes that the control attempt is always to drive the
value of the feedback tag to the Feedback At State 1 value.

Note: The 0 state may be inverted to a 1 before writing to the I/O device if this tag's Invert Output property (I/O tab) is
set to 1 (true).

Feedback At State 0
If the Pulse Duration property for this tag, as set on the I/O tab, is set to any of: 0 (the default), invalid, or blank (i.e. a
non-pulsed signal) then...
The Feedback At State 0 spin box should be set to the value you expect for the selected Feedback tag when this tag has
successfully gone to the 0 state. For example, if you've configured this tag to stop a motor by issuing a value of 0 to the
I/O device, you would expect the feedback tag (e.g. a Digital Status tag) to read a 0 back from the I/O device, indicating
that your output was received.

Feedback At State 1

Developer's Guide (part 1) How to Build an Application • 435

If the Pulse Duration property for this tag, as set on the I/O tab, is set to any of: 0 (the default), invalid, or blank (i.e. a
non-pulsed signal), then...
The Feedback At State 1 spin box can be used to set the value you expect for the feedback tag when this tag has
successfully gone to the 1 state. For example, if you've configured this tag to stop a motor by issuing a value of 1 to the
I/O device, you would expect that the feedback tag (e.g. a Digital Status tag) would read 1 back from the I/O device,
indicating that the value was received.
This value can be used as the source for an Alarm tag with a time delay to alert the operator that the requested output
change has not had the desired effect within a reasonable period of time.

Digital Control Properties: Merit Tab

The Merit tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you suspect
the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its
data is marked for extra monitoring. Please see the topic Merit Tab and Quality Tab, for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

Digital Control Properties: Order Tab

(For use with VTScada-based applications only)
The Order Tab for a Digital Control tag enables you to specify the placement of this tag when viewed in an associated
station dialog.

Digital Control Tag Drawing Methods

Digital Control tags enable users to write digital data to a PLC or RTU, which transmits the entered value to the
equipment process associated with the tag. The drawing methods for Digital Control tags enable users to set values to be
written to the equipment process associated with the tag, and display these set values.
The following drawing methods are available to Digital Control tags:
Animated Bitmap Drawing Method
Color Blink Drawing Method
Color Box Drawing Method

436 • How to Build an Application Developer's Guide (part 1)

Color Line Drawing Method
Gradient Color Change Drawing Method
Image Change Drawing Method
Momentary Button Drawing Method
Set Value Button Drawing Method
Set Value Hotbox Drawing Method
Text Change Drawing Method
Two Color Bar Drawing Method

Note: Of the drawing methods displayed above, only the Momentary Button, Set Value Button, and Set Value Hotbox
drawing methods allow users to actually output data to the equipment process associated with the tag being drawn. All
other drawing methods simply display the value that has been output.

Digital Output Tags

Digital Output tags take digital information from the user or from another tag and write it to the I/O device. Digital
Output tags provide drawing methods to change the state of the output via button controls.
The value of a digital output can be:
• 1 when there is an attempt to set the output that has not yet been confirmed by a change in the feedback value;
• 0 if neither case is met. i.e. when not performing a write, or after confirmation is received that a write has occurred.
• Of interest to programmers: A transient value of 2 will occur when the feedback value changes without any
prompting from the digital output. This value is extremely transitory and will not be caught by an alarm.

Note: Remember, the existence of an output tag is not enough to output a value to the I/O device; you must draw the tag
using a control drawing method (such as a Set Value Button) to enable users to send a value to the I/O device and related
equipment.

(Characteristics available in the Table of Type Characteristics.)

Digital Output Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Digital Output Properties: I/O Tab

The I/O Tab contains the properties used to identify and establish a connection to the communication driver tags being
used to exchange data with your physical I/O device (e.g. PLC or RTU). This is accomplished by identifying the
communication driver tag that communicates with the physical I/O device, and the address at the physical I/O device to
which this tag is to write its data.

Developer's Guide (part 1) How to Build an Application • 437

I/O Device
Select the communication driver tag to which data will be written.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Address
Provide the address within the I/O device to which this tag is to write data. This value must match the configuration of
your PLC or RTU hardware. Refer to the Addressing topic for your particular device driver for guidance.
For some drivers (SNMP and the OPC Client) an address browser is provided to assist you.

Pulse Duration
If you are using a pulsed signal, enter the duration of the pulse here in seconds or decimal parts of a second.
If the value of Pulse Duration is 0 or blank (Invalid), then a constant value will be written to the I/O device.

Data Source
The value output by the control can be supplied by a data source. For a digital control, the values supplied by the data
source should be limited to 1 or 0 (true or false).

Invert Output
Reverse the value of the output before writing.

Invert Data Source

Reverse the value coming from the data source before using.

438 • How to Build an Application Developer's Guide (part 1)

Digital Output Properties: Feedback Tab
The Feedback tab can be used to select an existing tag, or create a new tag belonging to the Digitals Group, that will
provide feedback indicating the current status of this tag's control action.
When the feedback tag’s value changes to what was expected as a result of the digital output, then the Digital Output
tag’s value will go to 0, indicating that no output is in progress (i.e. the write has finished)
Until the feedback tag changes to the value expected as a result of the digital output (perhaps because a communication
error is preventing the output from occurring) then the Digital Output tag’s value will remain at 1, indicating that the
output is still in progress.
If the feedback tag’s value changes independently of a write occurring from the digital output, the tag’s value will
undergo a transitory change to a 2. This signal is designed for the use of VTS programmers – it does not last long enough
to be displayed and cannot be captured by an alarm.

Feedback
Select or create a tag from the digitals group that will provide the source of the feedback.

Feedback At State 0
The Feedback At State 0 spin box can be used to set the value you expect back from the feedback tag when the digital
output has successfully written a 0 (State 0).

Feedback At State 1
The Feedback At State 1 spin box can be used to set the value you expect back from the feedback tag when the digital
output has successfully written a 1, 2 or 3 (State 1).

Digital Output Properties: Owner Tab

Some VTS tags can be used in an owner/contributor structure where multiple contributor tags can supply their values to
an owner tag. The Owner Tab allows you to specify the owner tag to which this tag should contribute its data.

Developer's Guide (part 1) How to Build an Application • 439

Note: There is no specific "owner" type, rather an owner tag is typically a custom designed tag that is created using VTS
scripting code for special projects.

Owner
The Owner field enables you to specify a tag to which this contributor should supply its data. An owner tag is one which
you must design and then create, using the VTS scripting language.
The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual
data value, to questionable data, according to the configuration of the checkboxes appearing beneath the Owner field.
These checkboxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value checkbox enables you to set the value of this contributor tag as the
nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner
tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack.
Priority checkbox causes the owner tag to keep track of the priority of the contributor's active alarm (or records an
Invalid if the contributor is not currently in an alarm state). Selecting the Set Active/Unack. Priority checkbox also
causes the owner tag to record whether or not the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values),
rather than reading data from their I/O device. When selected, the Record Use of Manual Data checkbox enables you to
increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been
provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag
Quality checkbox enables you to increment the owner tag's count of the number of tags that are contributing quality data
by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

440 • How to Build an Application Developer's Guide (part 1)

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the
Record Tag Validity checkbox enables you to increment the owner tag's count of the number of tags that are contributing
questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Digital Output Properties: Merit Tab

The Merit tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you suspect
the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its
data is marked for extra monitoring. Please see the topic Merit Tab and Quality Tab, for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

Digital Output Properties: Alarm Tab

The Alarm tab allows you to create new Alarm tags that will be triggered by this tag.
Use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will
automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Developer's Guide (part 1) How to Build an Application • 441

Digital Output Properties: Script Tab
The Script Tab allows you to create one or more Script tags to be associated with this tag.
A Script tag provides a means of creating a procedure, using VTS’s programming language, that will run whenever this
tag’s value changes.

Digital Output Properties: Logger Tab

The logger tab enables you to associate a single Logger tag with this tag. The Logger tag will work with the attached
Historian to record this tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag
will be created as a child of the current tag.

Note: Only one Logger tag can be directly associated with a single input or output tag. If you need to have multiple
loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O Tag

Digital Output Tag Drawing Methods

Digital Output tags write digital equipment process data to a PLC or RTU. The drawing methods for Digital Output tags
enable users to write this data and view the data being written.
The following drawing methods are available to Digital Output tags:
Animated Bitmap Drawing Method
Color Blink Drawing Method
Color Box Drawing Method
Color Line Drawing Method
Gradient Color Change Drawing Method
Image Change Drawing Method
Momentary Button Drawing Method
Plot Data Drawing Method
Set Value Button Drawing Method
Set Value Hotbox Drawing Method
Text Change Drawing Method

Note: Of these drawing methods, only the Set Value Button, Set Value Hotbox, and Momentary Button methods enable
users to output values to the associated tag; the remaining drawing methods display the value of the tag.

Multiple Write Tags

The MultiWrite tag allows you to configure a set of values that will be written to a list of registers when triggered. This
can be used to place a plant into a state of operation or to quickly shut a plant down in one step.
Up to 100 output tags can be controlled by a single MultiWrite tag, with a defined value set to be written to each. The
trigger for the write may be any of a manual button press, a tag that changes state from false to true, or an expression that
evaluates to true.
Each value to be written will be checked to ensure that it is valid before it is written. Invalid writes will be ignored. All
valid values will be written, regardless of whether or not they have changed since the last write.
Should 100 tags not be enough, it is possible for one MultiWrite tag to trigger another upon finishing its write sequence.
An event will be recorded in the alarm history whenever a MultiWrite is triggered.

442 • How to Build an Application Developer's Guide (part 1)

_D2HLink_2008446(Characteristics available in the Table of Type Characteristics.)

MultiWrite Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

MultiWrite Properties: Activation Tab

The Activation tab provides a way for MultiWrite tags to be controlled automatically. Any tag or expression that will
change from a false to a true value can be used to trigger the write.
If you intend to provide a button for operators to manually trigger the write, then you can also define an application
Security Privilege that will restrict access to that button to authorized operators.

MultiWrite Properties: Write List Tab

The Write List displays the output tags that will be written to, and controls what value will be written to each. The
outputs will be written in the order in which they are displayed.

Developer's Guide (part 1) How to Build an Application • 443

You can add or edit any tag in the list by clicking on a row. The Tag and Value input fields will be activated when a row
is selected, except that rows must be filled from 1 in order. You cannot add a tag to row 3 before row 2 has been
completed.
The grid displays the name and description of each tag selected to be written to. The Value column shows what will be
written to each tag when the MultiWrite is triggered. The value may be any of a constant, an expression or another tag’s
value. In the case where another tag’s value is to be written, that tag’s name will be display in the Value column.

To add a tag to the list, select the next available row, then click on the Tag Browser button. Select or create an output tag.
After you have specified the tag to write to, you can provide a value to write using the Value field.

To remove a tag from the list, select its row, then click on the X button beside the tag field

The buttons below the grid provide the following functions:

444 • How to Build an Application Developer's Guide (part 1)

Move Up Moves the selected tag up the list so that its value will be written sooner. Enabled only when
the currently selected tag is not the first in the list.

Move Down Moves the selected tag down the list so that its value will be written later. Enabled only when
the currently selected tag is not the last in the list.

MultiWrite Tag Drawing Methods

MultiWrite tags write defined values to a group of PLC or RTU addresses, as defined by the associated tags. The
drawing methods for these tags enable users to trigger the writing of this data.

Multi-Write Button Drawing Method

Multi-Write Hotbox Drawing Method

Selector Switch Tags

Selector Switch tags provide the means to create multi-position switches that can be used to create on-off toggles, mode
selectors, Hand-Off-Auto (H-O-A) switches, etc.

A selector switch can accept two types of feedback: Equipment feedback indicates the current status or state of the
equipment. When configuring the Selector, you may can specify what the expected value will be for each switch
position.
Switch Position feedback (an optional parameter that should be used when a second device is also controlling the
equipment) drives the position of the Selector Switch tag. This value must match the numeric switch position (0, 1, or 2).
In both cases, feedback must be provided by a tag or an expression.

Selector Switch Mismatch Conditions

The selector switch is designed to alert the operator to a mismatch condition by providing visual feedback through its
native drawing methods.
There are two possible causes for a mismatch condition:

• Position mismatch. The switch position as requested by the operator does not match the actual position as driven by
the switch position feedback value. This can occur when there is a lag in response time from the equipment.
• Value mismatch. The equipment feedback does not match the expected value for the requested or current position.
This type of mismatch can also be used to trigger an alarm. The alarm must be enabled and the mismatch must exist
for a set length of time before an alarm will become active.

The native drawing methods for the selector switch will use the following conventions to notify the operator of a
mismatch or an alarm condition:

• Alarm indicators take precedence. While an alarm indicator is active, no other mismatch indicator will be displayed.
• Alarms are normally indicated with red, and (if possible) will be shown on the requested or current position of the
switch.
• Alarm indicators are displayed until the alarm condition is cleared, regardless of whether the alarm has been
acknowledged.

Developer's Guide (part 1) How to Build an Application • 445

• When a position mismatch occurs and no alarm state is active, then (if possible) the requested position will be
indicated by the drawing method – often by blinking.
• When a value mismatch occurs and the alarm is either disabled or has not yet triggered, an indication similar to a
position mismatch will be displayed, if possible.

(Characteristics available in the Table of Type Characteristics.)

Selector Switch Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Selector Switch Properties: I/O Tab

The I/O Tab includes properties used to identify and establish a connection to the communication driver tags being used
to exchange data with your physical I/O device (e.g. PLC or RTU). This is accomplished by identifying the
communication driver tag that is linked with the physical I/O device.
In addition, the I/O tab also provides a means of selecting tags or expressions that are to provide feedback for the state of
the equipment or external control over the switch position.

Feedback versus Switch Position Feedback

The Feedback field is used to ensure that the correct value was written to the remote device. This is normally configured
as an input tag or status tag, monitoring the equipment. On the Positions tab, you can specify what value is expected for
each selector position. If the value of the selected input tag does not match the expected value for the current position,
then this will trigger an alarm, assuming that the alarm option of the selector has been enabled.
Switch Position Feedback is used to synchronize the selector with physical control of the switch. The input or status tag
used for this field must be able to provide a value of 0, 1 or 2 corresponding to possible positions of the selector. The
VTS selector switch position will follow the switch position feedback value. If the selector switch is changed in the
application, but the switch position feedback indicates that the physical position has not changed, the drawing method
will blink to indicate a mismatch.
No alarm will be triggered by a mismatch in switch position feedback, only by a mismatch between the Feedback field
and the expected value for the current position. It is often likely though, that a mismatch in switch position will lead
immediately to a mismatch between the feedback value and the expected value.

In the case where each position of the switch writes to a different output address, you can deselect the "Use Single
Output Address" box, and provide a value that will be written to each address not matching the current switch position.
Note that values will be written in a "make before break" order. In other words, the value for a new switch position will
always be written before the value-when-off is written to the addresses matching the unselected switch positions.

446 • How to Build an Application Developer's Guide (part 1)

I/O Device
Select the communication driver tag to which data will be written.
By default, the tag will look for a parent tag that is a device driver (..\*Driver). If none is found, the text "--Missing--"
will be displayed. The tag button to the right of the field opens the tag browser, from which you can either select an
existing communication driver tag or add a new one. The X button will clear the field. Right-clicking on a tag in the
field will open a dialog with which you can add or remove a Snapshot Expression, or open a selected driver`s
properties dialog.

Feedback (equipment feedback)

[Optional] Select the tag or expression that has been configured to provide feedback indicating whether the control
action of this switch has been successful. “Success” means that the state of the equipment matches what is expected (as
configured on the Positions tab) for each possible switch position. A mismatch in values here will trigger an alarm, if one
is configured on the Alarm Setup tab.

Switch Position Feedback

[Optional] Select the tag or expression that has been configured to provide an indication of the current position of the
equipment. (0, 1 or 2 according to switch positions) The selector switch will change positions to follow this feedback
value. If the selector switch is changed, but the feedback value does not follow, the drawing method will blink, but this
will not by itself cause an alarm. See Feedback (equipment feedback).

Value When Off

Available only when the Use Single Output Address option has been un-checked. The value provided here will be
written to the addresses of the unselected switch positions after the current position's value has been written.

Use Single Output Address

This checkbox provides an option to use a single output address for all switch positions, or to allow a separate address
for each position. NOTE: Addresses are specified on the next tab, Positions.

Developer's Guide (part 1) How to Build an Application • 447

Selector Switch Properties: Positions Tab
In the Positions tab you can configure the expected feedback values, the values to write and the address(es)
corresponding to each of the possible switch positions. (Whether a single or multiple output addresses are used, depends
on the checkbox in the I/O panel.)

Select Position to Configure

Select each of the available switch positions to configure the output and expected values for that position. The label over
each parameter will change to indicate which position is currently being configured. The list is controlled by the
parameter, Number of Positions.

Number of Positions
May be either "2" or "3". Limits the number of configurable positions in the switch. Always select "2" for a toggle
switch. (This differs from earlier versions where it was common practice to create toggle switches by configuring
positions "0" and "2", leaving position "1" blank.)

Expected Value (Position x)

Specify the value that is expected to be returned in the feedback field of the I/O panel, to indicate that the tag's switching
operation caused a successful change in the system in that the state of the equipment matches what we expect. This value
can be a constant, an expression, or it may come from a tag.

Output Value (Position x)

This field is where you to specify the constant, expression or tag value that will be written to the output address when the
corresponding position is selected. If a tag or expression is used here, then changing output values will trigger a write to
the device as long as the position has not changed.
Label (Position x)
If the switch requires operator confirmation (configured when drawing the switch as a toggle) then this label will appear
as part of the confirmation prompt for the matching switch position.

Address

448 • How to Build an Application Developer's Guide (part 1)

The I/O address to write the output value to when position x is selected.
If the Use Single Address option was checked in the I/O panel, then this will field will be labeled simply "Address" since
the same address is used for all positions. Otherwise, the label will be "Address (Position x)" to indicate which switch
position you are providing the address for.

Selector Switch Properties: Alarm Setup Tab

The Alarm Setup tab allows you to specify the parameters of the alarm that will be triggered when the equipment
feedback for the tag does not match expected value.
Since physical equipment can sometimes take a few moments to respond, a delay can be specified to prevent the alarm
from being triggered while waiting for the expected feedback value.
By design, this alarm cannot be configured as a trip alarm.

Note: Invalid data, whether on the I/O Device or a feedback tag, will neither cause nor clear an alarm condition.

Alarm Priority
Select the priority level of this alarm. All other controls are disabled while the priority level is set to "None".

Delay
Specify a delay in seconds to wait when the feedback value from the PLC does not match the expected value for the
requested switch position before triggering an alarm.

Sound
[optional] Enter the name of a .wav file in your application directory in order to use that as the alarm sound.

Alarm Disable
Un-select in order to enable alarms on this switch.

Popup Enable
Available only when alarm pop-ups are enabled in the application properties (see: AlarmPopupsEnable)

Developer's Guide (part 1) How to Build an Application • 449

Selector Switch Properties: Merit Tab
The Merit tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you suspect
the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its
data is marked for extra monitoring. Please see the topic Merit Tab and Quality Tab, for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

Selector Switch Tag Drawing Methods

Selector switch tags allow you to add multi-position drawing methods such as Toggle buttons, mode selectors and Hand-
Off-Auto switches to your applications.
The following drawing methods are available to Selector Switch tags:

Animated Bitmap Drawing Method Bottom Bar Drawing Method

Checkbox Switch Drawing Method Color Blink Drawing Method
Color Box Drawing Method Color Fill Drawing Method
Color Line Drawing Method Compass 1 Drawing Method
Compass 2 Drawing Method Draw Text Drawing Method
Droplist Control Drawing Method Gradient Color Change Drawing Method
Horizontal Button Drawing Method Image Change Drawing Method
Left Bar Drawing Method Meter 1 Drawing Method
Meter 2 Drawing Method Meter 3 Drawing Method
Momentary Button Drawing Method Multi-color Drawing Method
Multi-text Drawing Method Numeric Entry Drawing Method
Numeric Value Drawing Method Plot Data Drawing Method
Right Bar Drawing Method Selector Switch Drawing Method
Set Analog Value Drawing Method Set Value Button Drawing Method
Set Value Hotbox Drawing Method Slider Drawing Method

450 • How to Build an Application Developer's Guide (part 1)

Text Change Drawing Method Top Bar Drawing Method
Toggle Switch Drawing Method Two Color Bar Drawing Method
Vertical Button Drawing Method

Trigger Tags
Trigger tags can be used to activate a process at a set time and date. They may be configured to repeat at regular
intervals, or they can be configured to trigger based on an expression or another tag’s value. By drawing the Trigger tag
on a page, you can also provide a way for operators to manually trigger an event.

As well as defining a schedule or event that will set the trigger to 1 (On), you can should also define a schedule for when
it will be reset to 0 in preparation for the next trigger event. This may be configured as a delay measured in seconds after
the On trigger event, it may be set to a regular schedule or it may be tied to an expression or tag value.

Note: the trigger depends on the under-lying Windows operating system and your computer system clock. It should not
be relied upon for precise to-the-second starts or stops.

An “Enable” parameter is provide to allow you to control whether the Trigger tag is activated or not. If the tag is drawn
on a page, this can be toggled by right-clicking on the drawing method. Disabling a Trigger tag will also force its value
to be 0 (OFF).

Note: in VTS applications created prior to version 10, the scheduling option of both the On Condition and Off Condition
could be disabled by setting the "Every" field to 0. This has been replaced by an "Enable" checkbox, but applications
created in earlier versions will continue to work without modification.

(Characteristics available in the Table of Type Characteristics.)

Trigger Tag Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Trigger Tag Properties: On Conditions Tab

This tab is used to set the condition that will switch the tag’s value to 1. The tag may be switched to an ON state based
on a schedule or based on an expression (which may include a tag).
Both options may be configured, resulting in a tag that will be triggered both on a regular schedule and also in response
to an event.
Note the field labeled “Enable”. When not checked, this means that no schedule is in effect. All other time-related fields
will be disabled.
Note also the Starting Time. This serves as both an initial trigger time and the base date for repeating trigger events. For
example, to trigger a report to be created at midnight on the first day of each month, you would set the following values:

Developer's Guide (part 1) How to Build an Application • 451

• "Enable" field checked.
• "Starting Time" set to 12:00 a.m. on the first day of this month.
(Setting the first day of next month would achieve the same result, but putting the base date of repeating events
in the past ensures that you do not miss the first iteration.)
• "Every" value set to 1.
• "Months" option selected.
• "Same Day as Starting Day" selected. ("Same Day" refers to date in the month, not day of the week)
You must also configure the Off Conditions tab to set the schedule or condition that will reset the tag’s value to 0. Once
the trigger has occurred and the tag’s value set to 1, it remains at a value of 1. If you need a 0 to non-zero transition to
trigger an event, you must reset the value to Off (0) before the next desired On-time.

Enable
Must be checked in order for the trigger to activate based on a time and date schedule.

Starting Time
Sets the base date and time for the schedule configuration options. Subsequent configuration options will be counted
from this start time. If set to the future, no trigger will occur until that date.

Every [N] Seconds / Minutes / Hours / Days

The field beside “Every” controls the frequency of the following units.
For example, if the Every value is set to 1 and the Hours checkbox is selected, then beginning with the time configured
in the Start Time, the trigger will be set to true every hour.
If the Every value is set to 7 and the Days checkbox is selected, then beginning with the configured Start Time date, the
trigger will be set to true every week at the time given in Start Time.

Day Checkboxes
Allow you to control which days the Trigger tag will operate on. For example, you may choose to disable the trigger’s
action on weekends by unselecting Saturday and Sunday.

452 • How to Build an Application Developer's Guide (part 1)

These checkboxes will not be enabled when the Months option is selected.

Months
Selecting the Months option is similar to configuring to Trigger tag to switch on every N Hours. If this option is chosen,
then further refinements include “On The” or “Same Day as Starting Day”.
For example, you may wish to configure the trigger to run “on the 1st Wednesday” or “on the 2nd Monday” of the
month. Alternatively, of you have selected “Same Day as Starting Day” then the trigger will run on the given numeric
day of the month, at the selected time.
When the Months option is selected, the Day checkboxes will not be enabled.

Expression
Select a tag, or enter an expression that will be used to activate the Trigger tag. The On condition will be set when the
selected tag or expression’s value becomes non-zero.

Trigger Tag Properties: Off Conditions Tab

This tab is used to set the condition that will switch the tag’s value to 0, resetting the Trigger tag for the next scheduled
event. The tag may be switched to an OFF state based on a delay in seconds after switching ON, a schedule, or based on
an expression (which may include a tag).
A combination of options may be configured, resulting in a trigger that will reset either based on time, or in response to
an event.
Note the field labeled “Every”. When set to 0 this means that no schedule is in effect. All other time-related fields will be
disabled.

Developer's Guide (part 1) How to Build an Application • 453

Delay
When set to a value greater than 0, the Trigger tag’s value will be set to 0 (OFF) this many seconds after being triggered
by the On Condition.

Enable
Must be checked in order for the trigger to de-activate based on a time and date schedule.

Starting Time
Used to set the base date and time for the reset (Off-condition) schedule. The other configuration options on this tab will
be counted from the given Starting Time.

Every [N] Seconds / Minutes / Hours / Days

The field beside “Every” controls the frequency of the following units.
For example, if the Every value is set to 1 and the Hours checkbox is selected, then beginning with the time configured
in the Start Time, the trigger will be reset to 0 every hour.
If the Every value is set to 7 and the Days checkbox is selected, then beginning on the configured Start Time date, the tag
will be reset to 0 every week.

Day Checkboxes
Allow you to control which days the reset schedule will operate on. For example, you may choose to not reset the tag to
0 on weekends by unselecting Saturday and Sunday.
These checkboxes will not be enabled when the Months option is selected.

Months
Configures the tag to reset to 0 every month. If this option is chosen, then further refinements include “On The” or
“Same Day as Starting Day”.
For example, you may wish to configure the trigger to reset “on the 1st Wednesday” or “on the 2nd Monday” of the
month. If you have selected “Same Day as Starting Day” then the trigger will be reset on the given numeric day of the
month, at the selected time.
When the Months option is selected, the Day checkboxes will not be enabled.

Expression
Select a tag, or enter an expression that will be used to reset the Trigger tag’s value to 0. The Trigger tag’s value will be
set to 0 when the value of the selected tag or expression becomes non-zero.

Trigger Tag Properties: Options Tab

With the options tab, you can restrict access to this tag’s operation to authorized users only by setting an application
Security Privilege.
The Disable checkbox allows you to deactivate the Trigger tag. Disabling a Trigger tag forces its value to 0.

454 • How to Build an Application Developer's Guide (part 1)

Trigger Tag Drawing Methods
The following drawing methods are available to Trigger tags:
Animated Bitmap Drawing Method
Color Blink Drawing Method
Color Box Drawing Method
Color Line Drawing Method
Gradient Color Change Drawing Method
Image Change Drawing Method
Momentary Button Drawing Method
Plot Data Drawing Method
Set Value Button Drawing Method
Set Value Hotbox Drawing Method
Text Change Drawing Method

Note: Of these drawing methods, only the Set Value Button, Set Value Hotbox, and Momentary Button methods enable
users to output values to the associated tag; the remaining drawing methods display the value of the tag.

Alarm System Tags

Alarm Tags
Alarm tags are used to establish rules for when an alarm should be triggered, and what behavior should occur. An Alarm
tag monitors the value of another tag and triggers an alarm when that tag’s value reaches or passes a given set point.
The Setpoint property can be a user-defined number or it can be supplied by another tag’s value. The two values are
compared using an operation such as greater than, equal to, or less than. If the result of this comparison is determined to
be true, then the Alarm tag will be triggered.
When the Alarm tag is triggered and while the trigger condition remains true, the value of the Alarm tag itself becomes
1; otherwise, the value of the Alarm tag is 0.
The Alarm tag itself can also serve as a set point object since its value is 1 when the alarm condition exists or 0 when an
alarm condition does not exist.

Developer's Guide (part 1) How to Build an Application • 455

The urgency of the alarm (from Event to Critical) is defined by the Alarm Priority tag selected in the Alarm tag’s
properties.

Alarms can be configured such that, if they are acknowledged by an operator, but remain active for a set length of time
(that is, the triggering condition for the alarm remains in effect), the alarm will go back to an un-acknowledged
condition, thereby re-activating any audible and visible warning indicators that are attached to that alarm.

Trip Alarms Versus Level Alarms

Alarm tags can be configured as either “Trip” or “Level”.
A level alarm will show up in the Active List as long as the underlying trigger condition remains true. The underlying
condition must be cleared before the alarm is removed from the list of Active alarms.
Trip alarms do not have an Active or Inactive status that is based on the value of the Trigger tag. Once triggered, the trip
alarm is simply in an alarm condition, waiting for operator acknowledgement. There is no need to also clear the alarm
state by adjusting the Trigger tag’s value.

A trip alarm will never be displayed in the list of Active alarms. They are primarily used in situations where the
momentary existence of an alarm condition should “trip” the alarm, after which the state of the Trigger tag is irrelevant.
As an example, consider an intrusion detection system: When an unauthorized person opens a door, the alarm is
triggered. When then happens to the door is irrelevant to the alarm.

Both trip and level alarms must be acknowledged by an operator before their audible and visual warnings will stop.
(Characteristics available in the Table of Type Characteristics.)

Alarm Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Alarm Properties: Trigger Tab

The Trigger tab for the Alarm tag properties folder consists of the attributes used to identify the conditions that the
Alarm tag will evaluate to determine whether an alarm should be triggered.
The Triggered By field is used to select the tag that is being monitored by this Alarm tag. The Setpoint property displays
a value (or a tag) that will be compared to the value of the tag being monitored (as identified in the Triggered By tab).
The Function property selects the operation that is to be performed to compare the monitored tag's value with the
Setpoint value.

456 • How to Build an Application Developer's Guide (part 1)

Triggered By
The Triggered By field enables you to specify the name of the tag whose value will be monitored and compared to the
value of this Alarm tag's Setpoint value to determine if this alarm should be triggered.
The Triggered By field can be used to associate this Alarm tag with a new or existing numeric tag using the tag browser
button to its right. The Triggered By field can be cleared of its current value using the X button to its right.
Right-clicking the name of the I/O tag that has been selected in the Triggered By field opens the tag properties folder for
the selected communication driver tag.

Function
The Function drop-down list enables you to select one of 11 operators to use to compare the value of the Triggered By
tag with the Setpoint value configured for the Setpoint field to determine if there is an alarm state.

Setpoint
The Setpoint field enables you to specify the value you wish to be compared to the value of the tag being monitored by
this Alarm tag.
The valid value for the Setpoint field can be provided via any of a constant, an expression, or a tag. Please see Constant,
Expression or Tag for help selecting which to use.

Deadband
The Deadband field enables you to enter a value indicating how much far the Trigger tag’s value must return into the
safe zone before the alarm is no longer considered active. Deadband values are used in systems where some analog
values fluctuate frequently, sometimes providing a false data reading. For example, the level of fluid in a tank aboard a
vessel might shift frequently in high seas, a circumstance that may be perceived as the level of the tank changing, when it
is actually not.

Delay

Developer's Guide (part 1) How to Build an Application • 457

The Delay field enables you to enter an amount of time (in seconds or in fractions of a second) that the system will wait
before triggering an alarm for this tag. This allows you to disregard transient spikes in value as the tag must remain in an
alarm state for the amount of time specified in the Delay field before an alarm will be indicated.

Alarm Properties: Actions Tab

The Actions tab for the Alarm tag properties folder enables you to select an Alarm Priority tag whose of properties will
be used to indicate the category of alarm to be triggered by this Alarm tag (see Alarm Priorities). Other properties
available on the Actions tab allow you to disable the alarm in the event that alarm conditions could be triggered due to
routine equipment maintenance or another interruption in communications of which you are aware. The sound to be used
for the alarm siren for this alarm can also be indicated here.

Disable Alarm
The Disable Alarm field enables you to disable or enable this Alarm tag, using a 0 (not disabled) or 1 (disabled), an
expression or, the value of a second tag. This feature is typically used in situations such as when routine maintenance is
being performed. In such a situation, an alarm can be disabled until the maintenance is complete and communications are
reestablished, thus avoiding false alarms.

Alarm Rearm Time

Applies only if Alarm Rearm Enable is checked for this alarm. If the alarm has been acknowledged, but remains active
for the time shown in this field, the alarm will return to the un-acknowledged state. Audible and visible warnings
configured for this alarm’s priority level, will again be displayed. The Alarm Rearm Time is measured in seconds, and
defaults to 3600 (1 hour). The value in this field must be greater than 0.

Alarm Rearm Enable

Controls whether this alarm will revert back to an un-acknowledged state if it remains active for the length of time set in
Alarm Rearm Time, after having been acknowledged by the operator.

Trip

458 • How to Build an Application Developer's Guide (part 1)

The Trip checkbox enables you to indicate whether this alarm is to function as a trip alarm or a level alarm, as described
in the introduction to this tag.

Priority
The Priority field enables you to indicate the priority of this alarm by selecting an Alarm Priority tag. The built-in Alarm
Priority tags have numbers from 0 to 4 with the following meanings:
• None.
• 0 (event) - the alarm will not occur, but its value may still be used as a set point by other tags;
• 1 (critical) - the highest priority alarm;
• 2 (high) - a regular priority alarm;
• 3 (warning) - warning
• 4 (notice) - a notice or informational event. Logged in the event history, but otherwise silent.
You may also create your own Alarm Priority tags.

Sound
The Sound field enables you to identify what audible warning will be played when this alarm is triggered. The Sound
field can be set to a 0, a 1, or to the name of a .WAV sound file to be played.
If the Sound field is set to 0, no sound will be played when this alarm is triggered.
If the Sound field is set to 1, the sound configured in the associated Alarm Priority tag will be played.
If the Sound field identifies the name of a .WAV sound file, it will override any alarm sound configured for the
associated Alarm Priority tag. When specifying a sound file, you must enter its name and extension (e.g. MySound.wav).
The specified sound file must be a .WAV file, and must be stored in the application directory. If the specified sound file
is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

Popup Enable
If the configuration variable AlarmPopupsEnable is set to 1, then Popup Enable will result in a popup dialog being
displayed whenever the alarm is triggered. It is strongly suggested that this feature be used sparingly.
The popup will display the names of all active alarms for which Popup Enable has been set. As alarms are
acknowledged, they will be removed from the popup. Should all the alarms be acknowledged or go inactive while the
popup is displayed, it will close. You may close the popup at any time by selecting the Close button. The popup will not
be displayed again until a fresh alarm event occurs.
The popup does not provide a way to acknowledge the alarm – its purpose is solely to provide extra notification to the
operator of current, un-acknowledged alarms.

Alarm Tag Drawing Methods

Alarm tags monitor the value of another tag, and trigger an alarm based on that value, notifying users with sound and
color when certain conditions exist within your system.
The following drawing methods are available to Alarm tags:
Animated Bitmap Drawing Method
Color Blink Drawing Method
Color Box Drawing Method
Color Line Drawing Method
Gradient Color Change Drawing Method
Image Change Drawing Method

Developer's Guide (part 1) How to Build an Application • 459

Text Change Drawing Method

Alarm Priority Tags

The Alarm Priority tag type is used to specify different alarm indicators (such as the frequency of the alarm tones, the
tone cycle, alarm priority, and alarm highlight color) for alarms of different priorities and categories. An Alarm Priority
tag is associated with an Alarm tag so that when the Alarm tag is triggered, the sound and color indictors configured for
the Alarm Priority tag with which the alarm is associated will be activated.
By default, every standard VTS application you create includes 5 Alarm Priority tags. These tags and their properties are
described in the following table:

Name AlarmPriority0 AlarmPriority1 AlarmPriority2 AlarmPriority3 AlarmPriority4

Area System System System System System
Description No Alarm Critical Alarm High Alarm Warning Alarm Notice
Priority 0 1 2 3 4
Priority White Red Orange Yellow White
Color
Tone 1 Freq 0 2000 1800 1600 1400
in Hz
Tone 2 Freq 0 1000 1000 1000 1000
in Hz
Priority No Alarm Critical High Warning Notice
Descriptor
Tone Cycles -1 -1 -1 -1 0
Tone 1 0.5 0.5 0.5 0.5 0.5
Period in
Secs
Tone 2 0.5 0.5 0.5 0.5 0.5
Period in
Secs
(Characteristics available in the Table of Type Characteristics.)

Alarm Priority Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Alarm Priority Properties: Alarm Configuration Tab

The Alarm Configuration tab for the Alarm Priority tag properties folder consists of the properties used to identify the
types of alarm signals that will occur when an alarm is triggered by an associated Alarm tag.
For the audible warning sound, you may either configure a two-tone alarm by setting the frequency and duration of each
tone, or you may select a .WAV file from disk.

460 • How to Build an Application Developer's Guide (part 1)

Priority
The Priority field sets the priority of this alarm as a number from 0 to 4, where:
• 0 indicates that the alarm will not occur, but its value may still be used as a set point by other tags
• 1 indicates the highest priority alarm
• 2 indicates a regular priority alarm
• 3 indicates a warning
• 4 indicates a notice or informational event
You may also set the Priority property to values higher than 4 for user-defined alarm priorities.

Priority Color
When clicked, the Priority Color button opens the Select Color dialog from which you can select the color you wish to
be used to highlight alarms of this priority in the alarm list (thereby helping operators to identify the priority of the alarm
visually

Tone 1 Frequency in Hz
The Tone 1 Freq in Hz field enables you to specify the first of two audio tones that will be used to signal alarms
associated with this Alarm Priority tag. Typically, an alarm sound consists of two tones alternating within a specific time
period (the second of these two audio tones is specified in the Tone 2 Freq in Hz field).
The default value for this property is 2000Hz.

The Tone 1 Period in Secs

This field sets the length of time that the tone 1 frequency will sound. The default value is 0.5 seconds.

Tone 2 Frequency in Hz
The Tone 2 Freq in Hz field enables you to specify the second of two audio tones that will be used to signal alarms
associated with this Alarm Priority tag. Typically, an alarm sound consists of two tones alternating within a specific time
period (the first of these two audio tones is specified in the Tone 1 Freq in Hz field).

Developer's Guide (part 1) How to Build an Application • 461

The default value for this property is 1000Hz.

The Tone 2 Period in Secs

This field sets the length of time that the tone 2 frequency will sound. The default value is 0.5 seconds

.WAV File Name

The .WAV File Name field enables you to specify the name and extension of a .WAV sound file to be used in place of
the typical alarm tones to signal to operators that an alarm has been triggered.
If a .WAV file is specified, the Tone 1 Period in Secs and the Tone Cycles fields enable you to set the duration of play
and the number of times the .WAV file is to be played (respectively) once an alarm has been triggered.
When specifying a sound file, you must enter its full name and extension (e.g. MyAlarmSound.WAV) . VTS searches
for the specified .WAV file in your application directory. If the .WAV file is not found, the alarm will revert back to
using the tones as specified in the Tone 1 Frequency in Hz and Tone 2 Frequency in Hz fields.

Priority Descriptor
The Priority Descriptor field enables you to enter a short text description (no more than 81 characters in length) that will
be used to identify the priority of those alarms associated with this Alarm Priority tag. This description will appear in
filtering drop-down lists, and in the alarm list, wherever alarm priority is referenced.

Tone Cycles
The Tone Cycles field enables you to specify the number of times an alarm sound (either tones or a specified .WAV file)
is played once an alarm has been triggered.
If you are configuring this Alarm Priority tag to play tones, the Tone Cycles field enables you to indicate the number of
times the alarm tones specified by Tone 1 Freq in Hz and Tone 2 Freq in Hz will cycle (where one cycle is one instance
of the first tone sounding for the amount of time specified in Tone 1 Period in seconds, followed by one instance of the
second tone for the amount of time specified in Tone 2 Period in seconds).
If you are configuring this Alarm Priority tag to play a .WAV file rather than alarm tones, the Tone Cycles field enables
you to specify the number of times the .WAV file is played (whereas the Tone 1 Period in seconds field below enables
you to indicate the duration of play.)
The Tone Cycles field can be set to one of the following values:
• -1 if you wish the tones or the specified .WAV file to cycle infinitely (default)
• 0 if you do not require any alarm sound
• A number representing the number of times you wish the first and second tone or the .WAV file to cycle

Note that, if alarm speech is enabled, the first option (-1 to play the tone indefinitely) will not be available. If this is the
current value when alarm speech is enabled, the tone cycles field will automatically be set to 0.

Enable Alarm Speech

A checkbox to enable or disable spoken alarms. Please refer to Configuring Spoken Alarms for the instructions to make
this feature work on your system.

Alarm Annunciation Cycles

Similar to Tone Cycles, but applies only to spoken alarms. If both the tone cycles and the alarm annunciation cycles are
set to non-zero values, then the alarm tone will sound first for the set number of cycles, followed by the spoken alarm.

462 • How to Build an Application Developer's Guide (part 1)

Alarm Status Tags
This tag looks for active or unacknowledged alarms matching a given set of characteristics. It can be used to build a
trigger for an output or another alarm. For example, you might use it to trigger a warning system when any alarm with a
given priority in a given area is active.
The value of the Alarm Status tag will be either 1 or 0 depending on whether its trigger condition is met.
(Characteristics available in the Table of Type Characteristics.)

Alarm Status Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Alarm Status Properties: Alarm Tab

The alarm tab is used to define which alarms will be counted an instance of the Alarm Status tag. Use the fields to select
the characteristics that must be found in an alarm in order to be included in the count.

Low Alarm Priority

Select the lower end of the range of alarm priorities to be filtered for. Any alarm with a priority between the Low Alarm
Priority and the High Alarm Priority, and matching the remaining conditions will be included in the filter. The minimum
priority cannot be set above the maximum priority.
To filter for alarms of only a given priority, set both the Low Alarm Priority and the High Alarm Priority to that value.

High Alarm Priority

Select the upper end of the range of alarm priorities to be filtered for. Any alarm with a priority between the Low Alarm
Priority and the High Alarm Priority, and matching the remaining conditions will be included in the filter. The maximum
priority cannot be set below the minimum priority.
To filter for alarms of only a given priority, set both the Low Alarm Priority and the High Alarm Priority to that value.

Area Filter

Developer's Guide (part 1) How to Build an Application • 463

Select the area that the alarm must be configured within in order to be included in the filter. Areas shown in the list
include all system alarm areas as well as developer-created areas.

Name Filter
Use this field to restrict the list of filtered alarms to only those matching a given name. The * wildcard may be used to
permit selection on a set of similar names. For example, "East*" will match "East Pump Alarm", "East Tank Alarm", etc.

Alarm List
Options include “Active”, “Unacknowledged” and “Current”. Only one option may be chosen. Restricts the filter to only
those matching a particular list type.

Alarm Status Tag Drawing Method

The following drawing method is available to display information about your application’s Alarm Status tags:
Numeric Value Drawing Method

Alarm Dialer System Tags

The VTS Alarm Dialer System (see: Alarm Dialer System) contacts designated operators by phone, pager, or e-mail
when alarms have gone unacknowledged for a user-defined period of time.
Tags in this category include: Modem, Roster, SMS Appliance.

Modem Tags
Modem tags enable outgoing and incoming calls by providing a link between your VTS application and a modem
configured on your system. This is not the same as configuring a Serial Port that uses a modem for communication.
Your computer must have a voice modem in order to use this feature. Data modems, such as those included with many
laptops, will not function with VTS.
The value of the modem tag can be used to monitor the call status, according to the following table. (These values are
reflected in the Modem Indicator drawing method.)

Value Meaning
0 Modem idle
1 Modem calling
2 Modem answering
3 Modem failed

464 • How to Build an Application Developer's Guide (part 1)

(Characteristics available in the Table of Type Characteristics.)

Modem Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.
The Area property for a Modem tag will normally be left blank.
If the Modem tag has an area defined for it then only alarms that have the same tag area will be able to use that modem
to dial out.

Modem Properties: Settings Tab

The Settings tab of the Modem tag properties folder contains properties that allow you to configure the network and
security settings for the Modem tag. A message is provided to the right of the workstation name, provides extra
information about the station's availability, as follows:
If the Workstation field is left blank, the modem tag is for a so-called, local modem, and the text “Local” will be
displayed in the workstation message field. This configuration is not recommended - it is much better to specify the
workstation name even if VTS is running only on a single workstation where the modem also resides. (The term "Local
Modem" does not mean simply that the modem is on the same machine.) The “Index” parameter (the modem name) for
the modem tag is ignored if this modem tag is for a local modem. Local modems are specified by a configuration setting
in the <workstation>.Startup file for each workstation as follows:
<Modem tag name>Device = <Modem friendly name>

For example:
Modem1Device = MultiTech Systems MT9234ZPX-UPCI [Trihedral]

If this setting is not provided, the modem manager will select a modem from the list of modems not already associated
with a modem tag. (Results may be unexpected.)

Local modems are typically used only if PPP is being used by VTS, or in a system with custom software designed to use
local modems. Under typical operating conditions, Trihedral recommends that local modems NOT be used.

The text, “Available”, or "Unavailable" in the workstation message field refers to the workstation's availability. It is
displayed even if no modem has been selected.

Developer's Guide (part 1) How to Build an Application • 465

Workstation Name
The Workstation Name field enables you to specify the name of the computer to which the modem is connected. If you
do not specify a workstation in the Workstation Name field, VTS will use a local modem on a machine that is running
that tag within the application, selecting the first modem that is available.

Note: Once the workstation name has been specified, the Line Name and Name Or Index On Workstation drop-down
lists will automatically update to display the names of the Serial Port tags and modems available on this workstation.

Line Name
The Line Name drop-down list enables you to select the name of an existing phone line to which this modem is attached,
or enter a new and unique line name to which this modem is attached. This name must be unique, and cannot be
identified anywhere else in the system.
The same line name must be used by modems sharing the same physical phone line, even if they are on different
workstations.

Name Or Index On Workstation

The Name Or Index On Workstation drop-down list enables you to select a modem on the workstation specified in the
Workstation Name field, provided that the workstation is available. If the specified workstation is not currently available,
you may enter the name of the modem you wish to use, or can enter a number or text value as follows:
If this value is numeric, it is the index into the list of modems shown in the Modems Properties dialog box in the
Windows Control Panel, starting from 1.
If the value of Index is a text string, it is the name of the modem exactly as it appears in the Modems Properties dialog
that is accessed using the Windows Control Panel.

Note: Because the index of available modems can change over time, it is recommended that you refer to the modem by
name rather than by its index in the Modem Properties dialog box.

Ring Count
The Ring Count spin box enables you to select the number of rings you wish to occur before the selected modem
answers an incoming call.
If the value of Ring Count is 0, the modem will not answer any calls.

466 • How to Build an Application Developer's Guide (part 1)

Note: Regardless of this setting, the modem will not be answered if the application property, AnswerCalls is set to 0.
Information on the configuration variables pertaining to the Modem Manager can be found Application Properties for the
Modem Manager.)

Security Privilege
Select an application security privilege from this drop down if you wish to limit the operation of this control to only
those operators who have been granted the matching security privilege.
In this case, "operation" refers to the ability to disable or enable the tag via the context menu. It does not affect whether
or not the modem will operate while a user without the privilege is logged on.
Application privileges are added using the Administrative Settings security dialog. Information on creating application
privileges can be found in "Add Application Privileges Using the Administrative Settings Dialog".

Modem Properties: Historian Tab

If you select a Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer.
Historians are described in the topic, Historian Tag. You may log to more than one Historian by duplicating this tag's
value in a Calculation tag and attaching to it a Logger that is configured with a different Historian or a different
logging rate.

Note: There are consequences if you change the selected Historian tag after you have begun
collecting data. If you switch to a new Historian (perhaps for organizational or load sharing
purposes), the data collected for this tag by the previous Historian will become inaccessible.

Modem Tag Drawing Methods

The following drawing methods are available to display information about your application’s Modem tags:
Animated Bitmap Drawing Method
Color Box Drawing Method
Gradient Color Change Drawing Method

Developer's Guide (part 1) How to Build an Application • 467

Image Change Drawing Method
Modem Indicator Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method
Text Change Drawing Method

Note: VTS also includes a Modem Tools library that contains modem diagnostics tools that may be added to a page.

Roster Tags
Roster tags are designed to work with the Alarm Dialer call-out system. Using a Roster tag, you may configure contact
information for up to 30 operators. When a Roster tag has been enabled, the call-out system will contact the operators in
order in the event that an alarm has been triggered and has gone unacknowledged for a user-defined period of time. The
call-out system will continue to contact the operators on the active Roster tag until the alarm has been acknowledged.
The Area field, selected during configuration, is especially important for Roster tags. The Area field is used by VTS to
tie the Roster to those alarms that have this same area. If more than one Roster shares the same area, only one of them
can be active at a time. The active Roster Tag in an area is always the one most recently activated – all other Roster tags
with the same area property are automatically de-activated when one is activated.
One Roster Tag, the Default Call-Out Roster, is configured by default in every VTScada system. No names should be
added to this roster. Its purpose is to provide a means of telling VTS to not call anyone. Since only one roster in an area
can be active at a time, if the roster which is active has no names attached, no-one will be called.

Roster tags work with Modem tags, and the Dialer Options and Speech Lexicon tools to form the VTS Alarm Dialer
system. See: Alarm Dialer System.

Note: if your system includes more than one modem, and those modems are attached to servers located in regions with
different area codes, then you must use the Canonical Address Format for each phone number and you must configure
the server's location within the Windows™ Phone and Modem Settings dialog.

(Characteristics available in the Table of Type Characteristics.)

Roster Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Roster Properties: Contacts

The Contacts tab for a Roster tag is used to create the list of people who will be notified, and to define how to reach each
of them. The available methods include voice (a phone call) e-mail or pager.

468 • How to Build an Application Developer's Guide (part 1)

Note that the choice of contact mode controls the meaning of the next three fields, as shown:

The contact fields for the SMS Text option are identical to those for the Voice option. To use the SMS Text option, the
application must have a configured SMS Appliance Tag. See: SMS Appliance Tags.

Contact List (Contact Order | Username | Mode | Enabled)

Developer's Guide (part 1) How to Build an Application • 469

The list displays the operators who will be contacted in this roster, how they will be contacted and whether that entry is
enabled. Up to 30 names may be added. The list is not interactive . You cannot change the contact mode or enabled
status by clicking on in the list. Instructions for adding, changing and removing entries are provided below.
Blank lines are permitted, but too many will make the list more difficult to work with. We recommend that you keep all
the contact names together, starting with the first row.
The list may be reorganized using the Move Selected buttons.

Communication Method
The Communication Method radio buttons enable you to select the method of contact for this operator record. Options
include phone/voice, pager, or e-mail.

Continue Roster Sequence

The Continue Roster Sequence checkbox enables you to command the system to continue to contact operators in the
order they appear on the roster, even if the delivery of the pager or e-mail message has occurred successfully. This option
applies only to pager or e-mail contact modes, not to entries that are contacted by phone.
The roster will continue contacting entries flagged as “continue roster sequence” until the alarm is acknowledged. The
frequency which the list is contacted is controlled by the application property, RosterDelay
After calling a Voice contact, the roster will automatically call the next contact if last was not successfully contacted and
the alarm has not yet been acknowledged.
Once the alarm is acknowledged (by either the person on the phone or by an operator at the workstation) the roster
sequence will terminate until the next alarm goes active.

Do Not Contact
The Do Not Contact checkbox enables you to temporarily disable an operator's record in the roster. In the event that an
alarm is triggered and goes unacknowledged, this operator will be skipped by the roster/dial-out system until the
operator's contact information has been enabled.

Contact Description
Used to identify each contact in the list. This is an optional field. If left blank, the Phone Number or E-mail address of
the contact will be shown.

Contact User Name

Used if alarm acknowledgement by e-mail or SMS text is configured and if the Communication Method is set to e-mail
or SMS text for this contact. If left blank, a notification will be sent, but but that message will not include an
acknowledgement code.
If set, the field must match an existing security account username.

Phone Number / E-Mail addresses

Voice lines: Enter the contact’s phone number, using only the digits. If your phone systems requires a 9 to access an
outside line, you will need to configure your modem options using the Windows™ control panel.

Note: if your system includes more than one modem, and those modems are attached to servers located in regions with
different area codes, then you must use the Canonical Address Format for each phone number and you must configure
the server's location within the Windows™ Phone and Modem Settings dialog.

Pagers: The Phone Number field requires the paging company’s T.A.P. Modem Number (TAP = Telocator
Alphanumeric Protocol). This number allows access to the alphanumeric paging network, enabling VTS to send a
message to the pager phone/PIN (see PIN Number below). The correct number for the Phone Number field can be
obtained from your paging company’s technical support team.

470 • How to Build an Application Developer's Guide (part 1)

E-mail addresses: If the selected contact mode is e-mail, this field will be used for e-mail addresses rather than phone
numbers. You may enter several addresses, using a semi-colon between each.
While there is no limit on the number of e-mail addresses you may have, the combined total number of characters may
not exceed 255.

Pager PIN
This field is used only with the pager communication method. A PIN is a required part of the pager contact information.

Time Zone
If one or more of the contacts are located in a time zone other than that of the alarm server, they may find it inconvenient
or confusing to translate the time stated in the alarm notification to their local time. If the contact's time zone is provided,
using this drop-down list, then they will recieve a message that has been adjusted to their location for them.
The list uses the names built into the Microsft Windows' Multilingual User Interface Pack.

To add contact to the list:

1. Click on a blank row in the list.
To keep the list tidy, you should select the first blank row from the top. The row will be displayed with blue
highlighting.
23. Select the communication method.
Voice, Pager or E-mail
24. Enter the name of the operator in the Name field.
As soon as you press enter or exit from the field, the name you typed will be added to the list.
25. Enter the phone number or e-mail address (as per the communication method) for the contact.
26. [Only if the contact mode is “Pager”] Enter the PIN number for the pager.

To update a contact in the list:

1. Click on the contact entry that you want to modify in the list.
27. Change any of the fields that need to be updated.
Changes to the row take effect immediately on pressing <enter> in each field, or upon leaving the field.

To delete a contact from the list

1. Click on the contact entry that you want to delete from the list.
28. Clear the Name field
29. Clear the Phone Number/E-mail address field.
When both the name and the phone number fields have been made blank, the entry will be removed from the
list.

Roster Properties: Activation Tab

The activation tab of the Roster tag allows you to define an external trigger that will activate a roster. A roster can also
be activated manually by adding a roster button to the CallOut List page of your application. (See: Roster Tag Drawing
Methods.)
Note that, given several Roster tags that share a common area, only one can be active at a time. Activating one Roster tag
will automatically cause all other rosters that share the same area to be de-activated. There is no such thing as telling a
roster tag to de-activate. This happens automatically when another roster tag in the same area activates. A roster tag
remains active until another in the same area activates.

Developer's Guide (part 1) How to Build an Application • 471

If you accidentally use the same trigger for two Roster tags that share an area, that trigger will be ignored since it would
violate the "only one active roster at a time in an area" rule.

Manual activation of the roster will over-ride its current status.

Roster Tag Message Dialogs

If an operator’s contact mode has been set to E-mail and a badly formatted e-mail address has been entered, then the
following warning dialog will be displayed:

Click on the Close button and correct the e-mail address before proceeding. The Roster tag will not permit you to save a
badly formatted e-mail address.

Roster Tag Drawing Methods

The following drawing methods are available to display information about your application’s Roster tags:
Color Box Drawing Method
Image Change Drawing Method
Make Active Drawing Method
Roster Alarm Test
Text Change Drawing Method

SMS Appliance Tags

The SMS Appliance tag works in conjunction with the Alarm Dialer option to allow alarm notifications to be sent as text
messages to a mobile cellular device, and to allow alarm acknowledgement via SMS.
SMS messages are sent and received using an "SMS appliance", which is a cell phone (or "cell modem") tethered to a
VTS workstation via RS-232, Bluetooth, or USB. Any such "cell modem" should conform to ETSI TS 100 585.

472 • How to Build an Application Developer's Guide (part 1)

The SMS Appliance tag handles communications through the SMS appliance. The tag registers with the SMS Manager
service as an SMS agent.
Since SMS appliances are usually installed as "modems" under MS Windows™, the configuration of the SMS Appliance
tag allows the specification of this modem and the workstation to which the modem is attached. You may also set a
security privilege, and if necessary, can mark the modem as disabled.
The SMS Manager takes care of forwarding message requests to any registered SMS agents in a round-robin sequence. It
also provides a publisher for received SMS text messages. Code that subscribes to received messages will get
notification of all received text messages. Subscribers are responsible for any filtering of received text messages.

The SMS Appliance tag will re-initialize the appliance once per minute to verify that it is still attached and functioning.
Any error will result in a complete reset, which is repeated at a regular interval until the tag is disabled or a functioning
device is available.
The SMS Appliance tag will queue messages to send, so long as it is operating normally. Received messages are
published immediately. If these should be queued, it is the responsibility of the subscriber to do so.

The value of the SMS Appliance tag can be used to monitor the device status, according to the following table. (These
values are reflected in the SMS Indicator drawing method.)

Value Meaning
1 Connected to cell modem
2 Sending an SMS Message
3 Receiving an SMS message
4 Checking the connection to the cell
modem
5 Disabled
6 Workstation with modem is not
available
7 Modem unavailable

Related topic: Roster Tags.

(Characteristics available in the Table of Type Characteristics.)

SMS Appliance Properties: ID tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

SMS Appliance Properties: Settings tab

The Settings tab is used to identify the SMS appliance (SMS "modem") that will be used to send and receive messages.

Developer's Guide (part 1) How to Build an Application • 473

Workstation Name
The name of the computer, running the VTS application, to which the SMS appliance is attached.

Name or Index on Workstation

The named workstation will be checked for devices. If more than one is found, you may select between them using this
drop-down list.

Privilege
Select an application security privilege from this drop down if you wish to limit the operation of this control to only
those operators who have been granted the matching security privilege.
In this case, "operation" refers to the ability to disable or enable the tag via the context menu. It does not affect whether
or not SMS messages are sent while a user without the privilege is logged on.
Application privileges are added using the Administrative Settings security dialog. Information on creating application
privileges can be found in "Add Application Privileges Using the Administrative Settings Dialog".

Disable
Check this box to disable the device without removing it or deleting its configuration.

SMS Appliance Properties: Advanced tab

The fields in the Advanced tab are optional. These need not be set for most configurations and should only be configured
by developers who are familiar with the configuration of SMS devices.

474 • How to Build an Application Developer's Guide (part 1)

Modem Initialization String
You may provide an initialization string, as specified in the user manual for your cell modem. This will be sent to the cell
modem at the beginning of each initialization cycle.
In most cases, you do not need to provide this string to the tag.

PIN for SIM Card

If required, this will value will be assigned to you by your cellular provider. The password is pre-configured in most SIM
cards.

SMS Gateway Number

If required, this number will be provided by your cellular provider. This number is pre-configured in most SIM cards.

SMS Appliance Tag Drawing Methods

SMS Appliance Tags have a numeric value indicating their current state. The following drawing methods may be used to
display this information:
Animated Bitmap Drawing Method
Color Box Drawing Method
Gradient Color Change Drawing Method
Image Change Drawing Method
SMS Indicator Drawing Method
Multi-color Drawing Method
Multi-text Drawing Method
Numeric Value Drawing Method
Plot Data Drawing Method
Text Change Drawing Method

Developer's Guide (part 1) How to Build an Application • 475

Data Logging and Reporting Tags
Data logging tags are used to record the values of input and output tags to disk, and facilitate the trending of data on the
Historical Data Viewer page. Reporting tags are used to specify groups of tags upon which to generate timely reports.
Notebook tags enable users to add notes on the new Historical Data Viewer page.
The relationship between Historian tags and Logger tags is that Logger tags define when data is to be stored, while
Historian tags define where the data is to be stored. Each tag for which data is to be stored must have a unique Logger
tag. A single Historian tag is often enough for an application.

Historian Tag
The Historian Tag is used to write data that is to be logged to storage. (The Logger tag controls only how often the
Historian tag writes.)
Every VTS application will have a default instance of a Historian tag named "SystemHistorian". In many cases, this will
be the only Historian tag that you use in an application. The data it saves will be written to a VTS proprietary database
format.

The Historian tag's configuration panels provide access to only some of the available options. With a combination of
Historian tags and related application properties, you can also configure the following:
• Save data to a proprietary database such as Oracle, Microsoft SQL Server, MySQL or SQLite instead of the VTS
database.
• Ensure that a redundant backup exists by writing to separate storage locations on two or more servers.
• Configure load sharing between servers.
See also: Data Logging.
The status of the Historian's connection to its data store can be viewed. See: Monitor the Historian's Connection.

(Characteristics available in the Table of Type Characteristics.)

Historian Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Historian Properties: Settings Tab

Choose how and where data will be stored.

476 • How to Build an Application Developer's Guide (part 1)

Represent system downtime as missing data
If checked, then system downtime will be represented as a gap in the data. If not checked, then the last recorded value
will be taken as if it were in effect for the duration of the time that VTS was not logging.

Storage Name
Advanced Use Only. Allows a user-specified name to be used, rather than the tag's Unique ID. This provides control
over the folder name that will be used in the data store.
If configuring an ODBC-based database, the use of this field is recommended, as the tag's Unique ID may not remain
unique after being modified to a form that can be used by the ODBC driver.

Storage Type
Advanced Use Only. May be "File" if using the VTS data store. May be "ODBC" if configuring an ODBC-based
database. Defaults to "File" if not otherwise specified and therefore need not be set if using the VTS data store.

Storage Location
Advanced Use Only. If using the VTS data store, you may use this field to specify the path to a storage location other
than the default. (C:\VTS\AppName\Data)
If using an ODBC-based database, this should be set to either the configured DSN (Data Source Name) of the database,
or the connection string.

Developer's Guide (part 1) How to Build an Application • 477

Storage Type and Storage Location are recommended for use in place of the matching application properties for
configuring an alternate data store. See: Historian Properties for Data Store Selection.

Historian Properties: Storage Limiting Settings Tab

Choose whether to limit the data saved. If the data is to be limited, you can also choose whether to limit it by date, or by
a maximum number of records.

By default, no limit is set on the amount of data to be stored.

If you choose to delete data older than a given number of days, you will have the option of setting how many days that
will be. The default is 365.

The sweep interval sets how frequently older data is deleted. When deleting data older than a set number of days, the
sweep interval will always be exactly ¼ of the number of days specified. So, if deleting data older than 1 year, the actual
removal of the older records will happen only 4 times per year. Between sweeps, data older than the set limit will
accumulate.

If you choose a maximum number of records to keep, you can set the sweep interval to any number of days that you
would like. Records beyond the set maximum number may accumulate between sweep intervals.

478 • How to Build an Application Developer's Guide (part 1)

Historian Tag Drawing Methods
None.

Logger Tags
Logger tags are used to control when data is to be logged. They are required only for tags such as the Analog Input,
Digital Input and Calculation that do not have logging built-in.
The Logger tag must be linked to a Historian tag, which will perform the actual recording of the data. The Logger's only
job is to define when the value from the source tag is to be recorded.
It is recommended that only one Logger & Historian be directly configured to record values per standard tag. A tag's
name is used to identify the database table to which the Historian writes. If you need to log a tag's value at multiple rates,
see: Using Function Tags to Create Multiple Data Logs of an I/O Tag.
Logger tags themselves have no values and cannot be drawn on a page

(Characteristics available in the Table of Type Characteristics.)

Logger Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Logger Properties: Conditions Tab

The Conditions tab for the Logger tag properties folder consists of the attributes used to identify the tag whose value
should be recorded and the logging mode to use when logging the tag's data. The logging mode can be a time period or
for whenever the monitored tag's value changes.

Developer's Guide (part 1) How to Build an Application • 479

Log Data From
Select the tag whose values will be passed to a Historian by this Logger tag.
The Log Data From field can be used to associate this tag with a new or existing tag using the … button. The … button
opens the Tag Browser, which displays only the existing tags for your application, and enables you to create a new tag
using its New button. (Information on using the Tag Browser can be found in "Tag Browser").
The Log Data From field can be cleared using the X button to its right.
Right-clicking the name of the tag that has been selected in the Log Data From field opens the tag properties folder for
the selected tag.

Log On Change As Well As Time

The Log On Change As Well As Time checkbox enables you to specify whether the data for the specified tag will be
recorded to the logger's .DAT file according to a specified time period alone, or also when the value of the tag being
monitored changes.
If the Log On Change As Well As Time checkbox is selected, data will be logged to the .DAT file every time period as
defined in the Interval property on this logger's Log Rate tab (see Logger Properties: Log Rate Tab), as well as when the
value of the tag being monitored changes.

Enable
The Enable field allows you to enable or disable the logging of tag data by this logger using a constant value (either a 0,
or a 1), an expression, or the value of a second tag.
If the Constant checkbox beneath the Enable field is selected:
• Enter a 1 to enable the logging of the data for the tag being monitored.
• Enter a 0 to disable the logging of the data for the tag being monitored.
Any expression or tag that returns either a 0 or 1 (or non-zero) can also be used. Please see Constant, Expression or Tag
for help selecting which option to use.

Note: In an Excel spreadsheet, this value must always be entered as a text value to avoid ODBC problems mixing
numbers and text in the same column. To do this, type the apostrophe character (') before typing the number.

480 • How to Build an Application Developer's Guide (part 1)

Logger Properties: Log Rate Tab
The Log Rate tab of the Logger tag properties folder is used to identify the rate at which the data is recorded for the
monitored tag.

Note: Those familiar with versions of VTS prior to 10 may have expected to see a number of other fields in this tab.
Those functions have been either taken over or made obsolete by the Historian.

Interval (Seconds)
The Interval field enables you to specify a period of time (in seconds or in fractions of a second) between logs of the
value of the tag being monitored.

Logger Properties: Historian Tab

If you select a Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer.
Historians are described in the topic, Historian Tag. You may log to more than one Historian by duplicating this tag's
value in a Calculation tag and attaching to it a Logger that is configured with a different Historian or a different
logging rate.

Note: There are consequences if you change the selected Historian tag after you have begun
collecting data. If you switch to a new Historian (perhaps for organizational or load sharing
purposes), the data collected for this tag by the previous Historian will become inaccessible.

Developer's Guide (part 1) How to Build an Application • 481

Notebook Tags
Notebook tags are used to add notes on the Historical Data Viewer page. In essence, they provide a named link to an
encrypted data file where operator notes are stored.
VTS comes with one Notebook tag pre-configured: SystemNotes. If you have a larger application you may wish to
create multiple Notebook tags in order to better organize your information, whether by equipment type or geographical
region.
(Characteristics available in the Table of Type Characteristics.)

Notebook Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Notebook Properties: Historian Tab

If you select a Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer.
Historians are described in the topic, Historian Tag. You may log to more than one Historian by duplicating this tag's
value in a Calculation tag and attaching to it a Logger that is configured with a different Historian or a different
logging rate.

Note: There are consequences if you change the selected Historian tag after you have begun
collecting data. If you switch to a new Historian (perhaps for organizational or load sharing
purposes), the data collected for this tag by the previous Historian will become inaccessible.

Notebook Tag Drawing Methods

The following drawing methods are available for your application’s Notebook tags:
Add Note Drawing Method
Note List Drawing Method

Report Tags
The Report tag type is used to track the data of a user-defined group of tags to a user-defined output format at regular
intervals.
VTS also includes a built-in Reports page that enables the generation of reports, along with a set of report tools that
enable you to build your own custom reports page (see "Report Tools Library Reference"). The difference between the

482 • How to Build an Application Developer's Guide (part 1)

default Reports page and Report tags is that the Reports page enables a one-time generation of a report, while Report
tags enable you to configure a report to be generated on a regular basis (daily, weekly, or monthly), or whenever a
related tag changes it value from 'false' to 'true'. An example of how to configure a Report tag can be found in "Use
Report Tags to Generate Reports ".
A record will be added to the Events History each time a report is generated using the Report Tag. This allows operators
to ensure that automated reports were created on schedule.
The value of the Report tag will be 1 when writing a report and 0 otherwise.
(Characteristics available in the Table of Type Characteristics.)

Report Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

The Report tag’s ID tab differs from the standard in that it includes an extra field: Report Type.

Report Type
The Report Type drop-down list enables you to select the type of report that you wish this tag to generate. This may be
one of:
Daily Snapshot Report
Daily Total Report
Driver Communication Error Detail Report
Driver Communication Summary Report
Hourly Snapshot Report
Hourly Total Report
Standard Report

Developer's Guide (part 1) How to Build an Application • 483

Report Properties: Tag Tab
The Tag tab of the Report tag properties folder enables you to select tags whose data will be included in the report you
wish to generate. The Tag tab enables you to filter the available tags by tag type or by area; so that you may more easily
locate the tags you wish to incorporate in the report.

Load Group
The Load Group button enables you to load a set of tags that has previously been saved. A loaded tag group can then be
used to generate a new report based on your application's requirements. Step-by-step instructions can be found in Saving
and Loading Tag Groups for Reports.

Save Group
The Save Group button enables you to save the tags that have been configured for this report as a group that can later be
reused for report generation. Step-by-step instructions can be found in Saving and Loading Tag Groups for Reports.

Types
Use this drop-down list to select the type of tags you wish to include in this report.

Note: The Types drop-down list is set automatically according to the setting of the Report Type drop-down list on the
Report tag's ID tab. You will rarely need to change it.

Areas
The Areas drop-down list enables you to filter the tags to be included in this report by their Area property.

Tags Available
The Tags Available list displays the names and descriptions of those tags that are available for inclusion in the reports to
be generated by this tag. The < button enables you to move a selected tag (or tags) between the Tags Available list and
the Tags In Report list. The << button enables you to move all tags in the Tags Available list to the Tags In Report list.

484 • How to Build an Application Developer's Guide (part 1)

Tags In Report
The Tags In Report list displays the names and descriptions of those tags you have selected to be included in this report.
The > button enables you to move a selected tag (or tags) between the Tags In Report list and the Tags Available list.
The >> button enables you to move all tags in the Tags In Report list to the Tags Available list.

Report Properties: Period Tab

Use the Period tab of the Report Tag properties folder to select a preset time period or configure a custom time period for
the report to be generated by this tag. Note: the Report Button drawing method provides an option for an operator to re-
run the last scheduled report in the event that a system interruption prevented that report from being generated.
Last versus Previous:
The terms “Last” and “Previous” mean different things in the context of a report. “Last” refers to a time period ending at
present (or at a defined end time if defining a custom period). “Previous” refers to the most recent full period where
weeks end on Sunday night, days end at one second before midnight, and hours end one second before the top of the
hour.
For example, suppose that the current time is 3:25 p.m. on a Tuesday. “Last 24 hours before trigger time” refers to the
period from 3:25 p.m. Monday until 3:25 p.m. Tuesday.
“Previous calendar day” refers to the period from 12:00 a.m. Monday until 11:59 p.m. Monday.
"Current" refers to the time frames such as "so far today" or "so far this week".

Presets
The Presets drop-down list can be used to select a pre-configured period of time for the data to be included in this report.

If Custom is selected, further options will be available, as shown:

Developer's Guide (part 1) How to Build an Application • 485

Period Type
The selection offers a choice between Previous Time Period or Duration and End Time.
Previous Time Period:
Select a time period (Days, Weeks, etc.) from the drop down list and enter a number in the field provided. “Previous”,
refers to the most recent time period, ending at a standard boundary such as the midnight, etc.
Duration and End Time:
Sets the length of time that should be included in the report, ending at a set length of time prior to the trigger event.

Report Properties: Trigger Tab

The Trigger tab of the Report tag properties folder enables you to select a trigger that will prompt the report to be
generated. This trigger can be a daily, weekly, or monthly time, or any tag belonging to the numeric group.

486 • How to Build an Application Developer's Guide (part 1)

Trigger
The Trigger radio buttons enable you to select an event that will prompt the generation of this report. This can be one of:
• No Trigger
• Hourly at. (repeats every X hours, beginning at the specified time)
If X is 3, a specified time of 12:00, 3:00, 6:00 or 9:00 would all produce exactly the same result. You do not
need to provide the earliest interval in the day.
If the system is offline when a report interval is due, that interval will simply be missed.
• Daily Trigger (at a user-defined time)
• Weekly Trigger (on a user-defined day at a user-defined time)
• Monthly Trigger (on a user-defined date at a user-defined time)
• By Tag (when the value of a specified tag changes from false to true). The Trigger Tag field is not enabled unless
the By Tag radio button has been selected.

Trigger Tag
The Trigger Tag field enables you to select any tag with a numeric value whose value will be used to generate this report
(when the value of the selected tag changes, the report will be generated). The Trigger Tag field only becomes enabled
when the By Tag radio button is selected.
Right-clicking the name of the tag that has been selected in the Trigger Tag field opens the tag properties folder for the
selected tag.

Workstation
The Workstation field enables you to enter the name of the workstation upon which this report will be generated. By
default, the Workstation field is set to the name of the local workstation.

Developer's Guide (part 1) How to Build an Application • 487

Report Properties: Destination Tab
The Destination tab of the Report tag's properties folder enables you to configure an output format and destination for the
report to be generated by this tag.

Output Type
The Output Type drop-down list enables you to select the format to be used to display this report. This can be one of:
• Default Printer: Prints the report to the printer configured for your PC under the Windows operating system.
• Printer: Enables you to specify the path to a printer other than the default printer configured for your PC under the
Windows operating system.
• Text File: Generates the report as a plain, unformatted text file with the extension .TXT. This option enables the
transmission of report data in the body of an e-mail message (please see "E-mail Report" below).
• Screen Display: Generates the report in a window on your screen. This format enables the use of a Microsoft Excel
template file to modify the way your report appears. Please refer to "Using a Microsoft Excel Template File to
Generate Reports".

Note: A report that has had its Output Type configured as ‘Screen Display’, and for which the ‘Use Excel to Display
Screen Reports’ checkbox has been selected will open as a regular screen display over VIC connections. The ‘Screen
Display Using Microsoft Excel’ feature is not available for VIC connections at the present time.

• CSV File: Generates the report as a comma-separated value file with the extension .CSV. Such files are easily
imported by a variety of different database software packages. This report output option enables the transmission of
report data as an attachment to an e-mail message (please see "E-mail Report As Attachment" below).
• Formatted Excel XLS File: Generates the report as a formatted Microsoft Excel spreadsheet with the extension
.XLS. (The report will feature a bold title and column headings.) This report output option enables the transmission
of report data as an attachment to an e-mail message (please see "E-mail Report As Attachment" below).
• Plain Excel XLS File: Generates the report as a plain, unformatted Microsoft Excel spreadsheet with the extension
.XLS. (Unlike the Formatted Excel XLS File option, the report will not feature a bold title and column headings.)
This report output option enables the transmission of report data as an attachment to an e-mail message (please see
"E-mail Report as Attachment" below).
• Access MDB File: Generates the report as a Microsoft Access database file with the extension .MDB. This report
output option enables the transmission of report data as an attachment to an e-mail message (please see "E-mail
Report As Attachment" below).
• ODBC Data Source: Enables you to specify an existing ODBC data source associated with an existing ODBC-
compatible database file into which you wish the report data to be saved.

E-mail Report

488 • How to Build an Application Developer's Guide (part 1)

When selected, the E-mail Report checkbox causes the report generator to e-mail a copy of the report data to a specified
address or set of addresses within the body of the e-mail message. The E-mail Report option is only available when you
select Text File as your report output type. See: Send Report Data by E-Mail.

E-mail Report as Attachment

When selected, the E-mail Report as Attachment checkbox causes the report generator to e-mail a copy of the report data
to a specified address or set of addresses as an attachment to an e-mail message. The E-mail Report as Attachment option
is only available when you select the Text File, CSV File, Formatted Excel XLS File, Plain Excel XLS File, or Access
MDB File output option. See: Send Report Data by E-Mail.

E-Mail Settings
The E-Mail Settings button can be clicked to launch the E-Mail Settings dialog where the recipients, subject, and
message for the e-mail can be configured. See: Send Report Data by E-Mail.

Destination
The destination field's label changes according to the selected report output type|tag=Report Type Drawing Method.
You may enter a path, printer, or ODBC data source for the report. (A path is not required for Default Printer or Screen
Display output types). You may specify a path or printer using either the Browse button to navigate to the desired
location, or by manually typing the path into the destination field.

Browse
The Browse button opens a dialog that allows you to explore your hard drive to locate a printer (when Printer is selected
in the Output Type drop-down list) or path to a Microsoft Excel template to be used to generate this report (when Screen
Display is selected in the Output Type drop-down list). Instructions on utilizing Microsoft Excel templates to generate
reports can be found in "Using a Microsoft Excel Template File to Generate Reports ".

Report Properties: Options Tab

The Options tab of the Report tag's properties folder enables you to configure an output format and destination for the
report to be generated by this tag.

Use Excel to display screen reports

The Use Excel to display screen reports checkbox can be selected if you wish Microsoft Excel to launch your report
when the Screen Display report output type is selected.

Developer's Guide (part 1) How to Build an Application • 489

If you do not select the Use Excel to display screen reports checkbox, then a simple window will be launched and the
report data will be displayed within it.

Note: A report that has had its Output Type configured as ‘Screen Display’, and for which the ‘Use Excel to Display
Screen Reports’ checkbox has been selected will open as a regular screen display over VIC connections. The ‘Screen
Display Using Microsoft Excel’ feature is not available for VIC connections at the present time.

Use separate sheets/tables

Useful only if your report was custom coded to allow tag iterations across separate worksheets (Excel output) or tables
(Access output). The report tag does not support time-based iterations.

Rename sheets/tables
Used in conjunction with the previous option, this checkbox can be selected if you wish the report spreadsheet(s) or
table(s) to be renamed corresponding to the tag used in each iteration.

Generate an event
When checked, an event will be added to the application's history. Events can be viewed in the Alarm Page by selecting
the History display option.

Log the event using the Report Area

The Generate an event option must also be selected. Causes the event to be associated with the system area, "Report".
Otherwise, the event will be associated with the report tag's area.

Report Tag Drawing Methods

The following drawing methods are available to display information about your application’s Report tags:
Report Button Drawing Method
Report Options Drawing Method
Report Destination Drawing Method
Report Tag List Drawing Method
Reporting Period Drawing Method
Reporting Period (Enhanced) Drawing Method
Report Type Drawing Method

SQL Logger Group Tags

SQL Logging allows you to record in an ODBC compatible database, the values from any tag that could normally be
logged.
The SQL Logger Group tag type works in combination with the SQL Logger tag. You use the SQL Logger Group tag to
define a database and the frequency of data logging for all the SQL Logger tags associated with it. The SQL Logger tag
is used to indicate which values are to be logged to that database. You may link one or more SQL Logger tags to one
SQL Logger Group, recording one or more values into a single database.

490 • How to Build an Application Developer's Guide (part 1)

SQL Logger Group Tag: Before you begin
Before you can log values to a database, you will need to have 1) a database containing two tables as described below
and 2) an ODBC DSN configured for your database.

Setting up a database
You can use any ODBC compatible database such as MS-Access, Microsoft SQL Server, MySQL, Oracle, etc.
Instructions on how to install and configure a database program are beyond the scope of this documentation.
Once you have a database created, you will need two tables within it to hold the data that VTS will export. In the
Example directory under VTS (normally found as C:\VTS\Example) there are four files to help you with this task.
• SQLLoggerAccess.mdb
• SQLLoggerMySQL.sql
• SQLLoggerOracle.SQL
• SQLLoggerSQLServer.SQL
The three files which end with the extension ".sql", contain SQL commands to create the tables you will need in your
database.
If you do not have a database and do not own a database program, you can still use this feature of VTS/VTScada by
following these steps:
From the template directory of VTS, copy the file named SQLLoggerAccess.mdb to your application directory.
Rename it to match the data you plan to collect, being sure to keep the .mdb extension on the name.
You are now ready to proceed.

Configuring an ODBC DSN

This is created using the Windows™ Open Data Base Connectivity (ODBC) tool found in the Administrative Tools
section the Windows™ configuration menu. The example below shows the screens you would see if configuring a
System DSN for a Microsoft Access database. As shown, the name can be anything you like. the Database Select button
allows you to select a .MDB file on your computer or network.

Note: This must be done on all potential servers for a networked VTS application. The DSN must be identical on each
machine.

Developer's Guide (part 1) How to Build an Application • 491

(Characteristics available in the Table of Type Characteristics.)

SQL Logger Group Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

SQL Logger Group Properties: Settings Tab

The Settings tab holds the properties required to connect this tag to a database.

492 • How to Build an Application Developer's Guide (part 1)

Database DSN
As described in SQL Logger Group Tag: Before you begin, you must create and configure a database before using the
SQL Logger Group tag.
The DSN (Data Source Name) must already exist on your system and be pointing to the database you created for this tag.

Database Type
Tell VTS what type of database you are writing to.

CAUTION: The Database Type selection MUST match your database. Choosing an incompatible type will result in the
tag failing to write values to your database due to differences in data format.

Auto Delete Records Older Than (Days)

Allows you to limit the size of the database by automatically deleting records older than (n) days.
You may choose to set this value to 0 to turn off the auto-delete feature.

Username, Password
The Username and Password fields should match whatever is required to connect to your database. If you are using MS
Access and did not configure a user name and password, then you may leave these fields blank.

Tag ID Table Name, Tag Data Table Name

The two table name fields should not be changed under ordinary circumstances. The database configuration utility
supplied with VTS/VTScada created these table names for you by default. (see SQL Logger Group Tag: Before you
begin)

SQL Logger Group Properties: Log Settings Tab

The Log Settings tab allows you to configure the timing for when data will be written to the database.
There are three choices of Log Type: Interval, Triggered and On Data Change. Note that all the tags attached to a
particular SQL Logger Group through the associated SQL Logger tags will use these settings.

Developer's Guide (part 1) How to Build an Application • 493

Log Type
• Interval Selecting "Interval" allows you to record values every (n) seconds. Use this when you want continuous
monitoring of the system, setting the interval to the number of seconds you want between each data output.
• Triggered "Triggered" allows you to write values only when some condition changes. The write could be triggered
by a tag changing value, or you can create an expression to define precise conditions that will cause a value to be
written. Note that the trigger does not need to be activated by the same tag whose value you are recording. You
could potentially record the level of a holding tank every time a pump switches on and/or off.
When logging is to be triggered, you must also choose what the trigger will be. For testing purposes you can choose
Constant. This allows you to set a value of 1 for "On" or 0 for "Off".
Selecting "Expression" as the Log Trigger allows you to enter an expression using VTS's scripting language.
Selecting a Tag as the Log Trigger allows you to select any tag in your project to indicate when to write log values. The
following section, "Trigger On" applies directly to using a tag as the trigger as you must also indicating what change in
condition of that tag is to indicate when to write data.
The space where you see a 0 in the dialogue box above will be replaced with a selection of the tags in your project.
In almost all cases, if you are using the Triggered option for the Log Type, you will choose a tag as the trigger.

Trigger On
If you have chosen Triggered as the Log Type, you also have the choice of whether the trigger happens on a Value
Change, a Rising Edge (from False to True) or a Falling Edge (from True to False. This applies to Constants,
Expressions and Tags.

Log Type: On Data Change

This option for log triggering passes more control over to the Logger tags attached to this Logger Group. Essentially, you
are indicating that log values are to be written when the value of the tag you are monitoring changes. See the section on
the SQL Logger tags for more information.
If using this log type, please read the following section: Log Invalids for an important note.

Log Invalids
You have the option of whether or not to record "invalids" as part of the data being written. An invalid data value is
essentially a NULL.

494 • How to Build an Application Developer's Guide (part 1)

Note that if you select On Data Change as your trigger and you have not chosen to log invalids, then if the data changes
from a valid value to invalid (or vice versa), no value will be written. You must enable Log Invalids in order to capture
these data changes.

Enable
Where triggering controls the timing of data output, Enable sets whether or not data is to be output at all. Where the two
controls offer the same options of "Constant", "Expression" and "Tag", the difference may seem subtle, but it is
fundamentally different. Enabling the logger group means that logging is switched on or off. Triggering means that (if
logging is enabled) data values are written when the trigger signals them to be.

Note: if a SQL Logger Group is disabled, then all the SQL Logger tags attached to that group are automatically disabled.

Use Coordinated Universal Time (UTC)

A switch giving you the option to record the time stamp using either local time or UTC.

SQL Logger Group Properties: SQL Logger tab

Each Logger Group Tag must have one or more SQL Logger tags contributing data to it before it will be useful. As
noted, the SQL Logger Group Tag creates a link to a database and sets a frequency of logging - it does not actually select
what data is being logged. That job is assigned to the SQL Logger tag as described in the following section.

SQL Logger Group Tag Drawing Methods

Only one drawing method is available to SQL Logger Group tags:
Show Stats Drawing Method

Developer's Guide (part 1) How to Build an Application • 495

SQL Logger Tags
The SQL Logger tag type allows you to select where data to be logged is to come from. Before using an SQL Logger tag
you should create a SQL Logger Group tag as described in the preceding section. SQL Logger tags contribute values to
SQL Logger Group tags.
Each record added to the database will include:
• An index value indicating which tag's value is being recorded
• A time stamp
• The value of the tag being logged at that moment
• A flag to indicate whether the value is 'manual data'
• A flag to indicate whether the value is 'questionable data'
• An alarm flag
• (Characteristics available in the Table of Type Characteristics.)

SQL Logger Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

SQL Logger Properties: Log Settings Tab

The Log Settings tab is where you select and control which tag's values you wish to log.

Tag to log, Variable to log

In the "Tag to log" selection area, simply choose any existing tag from your project. If that tag has multiple values which
could be logged, you will have a choice in the "Variable to log" selection. In most cases, the variable will simply be
"value".

Enable
The "Enable" window allows you to enable or disable logging of the selected value by entering a 1 for Enable and a 0 for
disable. You also have the ability to toggle whether logging is enabled based on a script expression, or by selecting a tag:

496 • How to Build an Application Developer's Guide (part 1)

either the same tag you are logging the data values for, or any other. This provides you with the option of either logging
continuously or logging only when a condition is met such as when an Alarm tag is activated.

SQL Logger Group

An SQL Logger Group must be selected. SQL Logger tags contribute their values to SQL Logger Group tags which then
manage the actual output of the data to a database.

Deadband (Engineering Units)

If (and only if) the associated SQL Logger Group was set to trigger on data changes, it has essentially passed control to
this tag to cause data writes to occur. If this is the case, then the Deadband field will be enabled and you will have the
option of indicating how much the value must change by before another value will be written to the database.

SQL Logger Tag Drawing Methods

The following drawing methods are available to display information about your application’s SQL Logger tags:
Animated Bitmap Drawing Method Bottom Bar Drawing Method
Color Blink Drawing Method Color Box Drawing Method
Color Fill Drawing Method Color Line Drawing Method
Draw Text Drawing Method Gradient Color Change Drawing Method
Image Change Drawing Method Left Bar Drawing Method
Meter 1 Drawing Method Meter 2 Drawing Method
Meter 3 Drawing Method Multi-color Drawing Method
Multi-text Drawing Method Numeric Value Drawing Method
Plot Data Drawing Method Right Bar Drawing Method
Text Change Drawing Method Top Bar Drawing Method
Two Color Bar Drawing Method

Calculation and Inquiry Tags

These are tags whose value depends on some function of other tag values. Calculation tags and Function tags allow you
to create your own expressions. The other tags in this group encapsulate common functions that you may wish to use
such as Counters, Totalizers, Alarm Status counts, etc.

Analog Statistics Tags

Analog Statistics tags are used to monitor any tag having a numeric value. While they can use digital tags, they are more
commonly used to collect statistics on Analog Input, Analog Status and other similar tags.
Three statistics are gathered are gathered: minimum value during selected time frames, maximum value and average
value, again during selected time frames.
The Analog Statistics tag works by launching a child tag for each statistic to be gathered. Each child tag may be included
separately in a report or Historical Data Viewer plot.

Use these tags sparingly. Since each selected statistic is gathered using a child tag, the count of tags in use in your
application will correspondingly increase by the number of statistics being gathered. There is also an increased load on
the CPU. Select only the time frames required.

Developer's Guide (part 1) How to Build an Application • 497

(Characteristics available in the Table of Type Characteristics.)

Analog Statistics Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Analog Statistics Properties: Source Tab

Used to select the source tag for which statistics are to be calculated.

Source
The Source tab is used to select which tag is to be monitored. Any tag with a numeric value may be selected as the
source.

Analog Statistics Properties: Minimum Values Tab

Select the time frames, during which you wish to record the minimum value of the source tag. By default, all will be
selected, which will result in 15 child tags being created in order to generate those statistics. Un-check all that you do not
need.

498 • How to Build an Application Developer's Guide (part 1)

Note: Statistics for the time periods "this week" and "last week" are affected by the application property, StartOfWeek.
You may use that property to set the beginning of a week to any day of your choice.
"Today" means since the time 00:00 this day.
"This Week" means since 00:00 of the first morning of the week.
"This Month" means since 00:00 on the morning of the first day of the month.
"Yesterday" means the 24 day, prior to today.
"Last week" means the full week prior to the current week.
"Last Month" means the calendar month prior to the current one.
"Last 24 Hours" covers the 24 hours prior to "right now".

Analog Statistics Properties: Maximum Values Tab

Select the time frames, during which you wish to record the maximum value of the source tag. By default, all will be
selected, which will result in 15 child tags being created in order to generate those statistics. Un-check all that you do not
need.

Available time frames are the same as for the Minimum Values tab.

Analog Statistics Properties: Average Values Tab

Select the time frames, over which you wish to record the average value of the source tag. By default, all will be
selected, which will result in 15 child tags being created in order to generate those statistics. Un-check all that you do not
need.

Available time frames are the same as for the Minimum Values tab.

Developer's Guide (part 1) How to Build an Application • 499

Analog Statistics Tag Drawing Methods
The following drawing methods are available to display information about your application’s Analog Statistics tags:
Tag List drawing method

Calculation Tags
The Calculation tag type is used to wrap an expression, with the resulting value of the Calculation tag being the result of
the expression. This tag type replaces the Function tag.
For a guide to the VTS expression language, see: Creating Expressions.
The characteristics of the Calculation tag are identified in the table below.
(Characteristics available in the Table of Type Characteristics.)

Calculation Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Calculation Properties: Calc Tab

The Calc tab allows you to construct the calculation to be performed by this tag. While a choice of Constant, Expression
or Tag is provided, you would normally use only Expression.

Calculation
The Calculation field enables you to specify a constant numeric value, an expression, or reference another tag that will
be the calculation run by this tag. The Calculation field corresponds to the selected associated checkbox. Select
Expression and click on the button to open the expression editor.

500 • How to Build an Application Developer's Guide (part 1)

Manual Data
This optional field allows you to provide a constant value that will be used instead of input read by the communication
driver. It is commonly used when testing a new Analog Input tag when application is not attached to a live data source.
Tags that are using manual data are marked on screen by a flashing exclamation mark.

Engineering Units
Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc.

Questionable Data
Use this field to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when
this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Calculation Properties: Owner Tab

Some VTS tags can be used in an owner/contributor structure where multiple contributor tags can supply their values to
an owner tag. The Owner Tab allows you to specify the owner tag to which this tag should contribute its data.

Note: There is no specific "owner" tag type, rather an owner tag is typically a custom designed tag that is created using
VTS scripting code for special projects.

Owner
The Owner field enables you to specify a tag to which this contributor should supply its data. An owner tag is one which
you must design and then create, using the VTS scripting language.
The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual
data value, to questionable data, according to the configuration of the checkboxes appearing beneath the Owner field.
These checkboxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value checkbox enables you to set the value of this contributor tag as the
nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner
tag's array elements if required.

Set Active/Unack. Priority

Developer's Guide (part 1) How to Build an Application • 501

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack.
Priority checkbox causes the owner tag to keep track of the priority of the contributor's active alarm (or records an
Invalid if the contributor is not currently in an alarm state). Selecting the Set Active/Unack. Priority checkbox also
causes the owner tag to record whether or not the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values),
rather than reading data from their I/O device. When selected, the Record Use of Manual Data checkbox enables you to
increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been
provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag
Quality checkbox enables you to increment the owner tag's count of the number of tags that are contributing quality data
by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the
Record Tag Validity checkbox enables you to increment the owner tag's count of the number of tags that are contributing
questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Calculation Properties: Alarm Tab

The Alarm tab allows you to create new Alarm tags that will be triggered by this tag.
Use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will
automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Calculation Properties: Logger Tab

The logger tab enables you to associate a single Logger tag with this tag. The Logger tag will record this tag’s data to
disk so that it can be plotted on the Historical Data Viewer page. The new logger tag will be created as a child of the
current tag.

502 • How to Build an Application Developer's Guide (part 1)

Note: Only one Logger tag can be directly associated with a single input or output tag. If you need to have multiple
loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O Tag

Calculation Tag Drawing Methods

The following drawing methods are available to display information about your application’s Calculation tags:
Animated Bitmap Drawing Method Bottom Bar Drawing Method
Color Blink Drawing Method Color Box Drawing Method
Color Fill Drawing Method Color Line Drawing Method
Compass 1 Drawing Method Compass 2 Drawing Method
Draw Text Drawing Method Gradient Color Change Drawing Method
Image Change Drawing Method Left Bar Drawing Method
Meter 1 Drawing Method Meter 2 Drawing Method
Meter 3 Drawing Method Meter 4 Drawing Method
Meter 5 Drawing Method Meter 6 Drawing Method
Meter 7 Drawing Method Meter 8 Drawing Method
Meter 9 Drawing Method Meter 10 Drawing Method
Meter 11 Drawing Method Meter 12 Drawing Method
Meter 13 Drawing Method Multi-color Drawing Method
Multi-text Drawing Method Numeric Value Drawing Method
Plot Data Drawing Method Right Bar Drawing Method
Text Change Drawing Method Top Bar Drawing Method
Two Color Bar Drawing Method

Counter Tags
Counter tags provide a means to count events such as pump starts or equipment cycles. A count is recorded each time the
source changes from 0 to non-zero.

Note: an invalid value for the source is not assumed to mean a 0 or off state. A transition from invalid to 1 will not be
counted.

The Counter tag retains its value between application restarts and uses the last known valid source value when counting.
For example, if the data source was 1 (i.e. running) when VTS stopped and is 1 when VTS restarts, it is assumed that the
equipment continued to run while VTS was offline and the counter is not incremented. Similarly, if the source was 0 (i.e.
off) when VTS stopped and is 1 when VTS restarts, it is assumed that the equipment started at least once while VTS was
offline and the counter is incremented by 1.

Note: Never attempt to attach a Logger tag to a Counter tag. Counter tags have a built in logger.

Also: Note that right-clicking on a Counter tag will not cause the Historical Data Viewer window to open.

(Characteristics available in the Table of Type Characteristics.)

Developer's Guide (part 1) How to Build an Application • 503

Counter Properties: ID Tab
The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Counter Properties: Settings Tab

All options to configure the counting behavior of the Counter tag can be found in the settings tab.

Source
The source can be any tag or calculation whose value will change between 0 and a non-zero value. The count will be
increased each time the source changes from 0 to a non-zero.
Constants are not useful here, but are a standard part of this type of selector.

Log Interval
The Counter tag will log its value at the end of each interval specified. This interval goes by the clock, not by running
time. If, for example, the log interval is set to "Day", the tag's value will be logged at midnight, not at the end of 24 hours
of operation. If the log interval is set to "Hour", the tag's value will be logged each hour on the hour. "Weekly" means
midnight Sunday night and "Monthly" means at midnight before the first day of the month.

Reset After Log

You can select whether or not the counter should be reset to 0 after its value is logged.

Engineering Units
Text that states what the Counter tag is counting (e.g. Starts).

External Reset
Allows you to specify a tag or calculation to force a reset of the counter. Note that the current value of the tag will
always be logged before a reset. The reset will occur when this source changes from a 0 or false value to a non-zero or
true value. A change from invalid to true does not cause a reset.

504 • How to Build an Application Developer's Guide (part 1)

Counter Properties: Merit Tab
The Merit tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you suspect
the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its
data is marked for extra monitoring. Please see the topic Merit Tab and Quality Tab, for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

Counter Properties: Historian Tab

If you select a Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer.
Historians are described in the topic, Historian Tag. You may log to more than one Historian by duplicating this tag's
value in a Calculation tag and attaching to it a Logger that is configured with a different Historian or a different
logging rate.

Note: There are consequences if you change the selected Historian tag after you have begun
collecting data. If you switch to a new Historian (perhaps for organizational or load sharing
purposes), the data collected for this tag by the previous Historian will become inaccessible.

Counter Tag Drawing Methods

The following drawing methods are available to display information about your application’s Counter tags:

Developer's Guide (part 1) How to Build an Application • 505

Reset Button drawing method Reset Target drawing method
Last Logged Value drawing method Numeric Value drawing method
Draw Text drawing method Meter 1 drawing method
Meter 2 drawing method Meter 3 drawing method
Animated Bitmap drawing method Two Color Bar drawing method
Color Fill drawing method Multi-Color drawing method
Multi-Text drawing method Plot Data drawing method
Text Change drawing method Image Change drawing method
Color Box drawing method Color Blink drawing method
Gradient Color Change drawing method Color Line drawing method
Numeric Entry drawing method Set Analog Value drawing method

Digital Statistics Tags

Digital Statistics tags are used to monitor digital tags including Digital Input, Digital Status, Pump Status, Alarm, Roster,
etc.
Statistics gathered are user-configurable and include number of starts (zero to non-zero transitions) during selected time
frames and total run time (non-zero time) during selected time frames.
The Digital Statistics tag works by launching a child tag for each statistic to be gathered. (Counter tags and History
Statistics tags) Each child tag may be included separately in a report or Historical Data Viewer plot.

Use these tags sparingly. Since each selected statistic is gathered using a child tag, the count of tags in use will
correspondingly increase by the number of statistics being gathered by each Digital Statistics tag. There is also an
increased load on the CPU. Select only the time frames required.

(Characteristics available in the Table of Type Characteristics.)

Digital Statistics Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Digital Statistics Properties: Source Tab

Used to select the source tag for which statistics are to be calculated.

506 • How to Build an Application Developer's Guide (part 1)

Source
The Source tab is used to select which digital tag is to be monitored. Selection is limited to tags with numeric values, but
only tags whose values have a clear zero to non-zero transition should be selected. Examples include Digital Input,
Digital Status and Alarm tags.

Elapsed Time Meter

Your controller may be capable of recording the running time of the equipment being monitored. This is often called the
Elapsed Time Meter. If your equipment supports this feature then an analog input (or analog status) tag can be created to
read the value from the Elapsed Time Meter. You may then list this value beside the other statistics in your page graphics
or reports.

On-Count Units
Similar to the Engineering Units field of analog tags, this value is used for display purposes only. Use it to describe what
is being counted.

Digital Statistics Properties: On-Count Statistics Tab

The On-Count Statistics tab is used to select the time frames for which you want to gather zero to non-zero transitions of
the source tag. By default, all will be selected, which will result in 15 child tags being created in order to generate those
statistics. Un-check all that you do not need.

Developer's Guide (part 1) How to Build an Application • 507

Note: Statistics for the time periods "this week" and "last week" are affected by the application property, StartOfWeek.
You may use that property to set the beginning of a week to any day of your choice.
"Today" means since the time 00:00 this day.
"This Week" means since 00:00 of the first morning of the week.
"This Month" means since 00:00 on the morning of the first day of the month.
"Yesterday" means the 24 day, prior to today.
"Last week" means the full week prior to the current week.
"Last Month" means the calendar month prior to the current one.
"Last 24 Hours" covers the 24 hours prior to "right now".

Digital Statistics Properties: On-Time Statistics Tab

The On-Time Statistics tab is used to select the time frames for which you want to gather the non-zero (running) time of
the source tag. By default, all will be selected, which will result in 15 child tags being created in order to generate those
statistics. Un-check all that you do not need.

508 • How to Build an Application Developer's Guide (part 1)

Note: Statistics for the time periods "this week" and "last week" are affected by the application property, StartOfWeek.
You may use that property to set the beginning of a week to any day of your choice.
"Today" means since the time 00:00 this day.
"This Week" means since 00:00 of the first morning of the week.
"This Month" means since 00:00 on the morning of the first day of the month.
"Yesterday" means the 24 day, prior to today.
"Last week" means the full week prior to the current week.
"Last Month" means the calendar month prior to the current one.
"Last 24 Hours" covers the 24 hours prior to "right now".

Digital Statistics Tag Drawing Methods

The following drawing methods are available to display information about your application’s Digital Statistics tags:
Tag List drawing method

Function Tags
The Function tag type is used to perform mathematical and logical calculations using numeric values and/or the values of
other tags. A Function tag can accept up to four tag values or numeric values as properties, and the result of the
calculation becomes the value of the Function tag. Other tags can use the value of a Function tag.
A Function tag will return a value of 1 when the specified input tags are Invalid and the AND operation is used.
Similarly, a Function tag will return a value of 0 when the specified input tags are Invalid.

Function tags are an older technology. They have been replaced by Calculation tags for most applications.
(Characteristics available in the Table of Type Characteristics.)

Developer's Guide (part 1) How to Build an Application • 509

Function Properties: ID Tab
The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Function Properties: Operator Tab

The Operator tab identifies the operation that will be performed on the inputs for this tag.

OpCode
The OpCode drop-down list enables you to specify the type of operation to be performed on the values associated with
this Function tag.
For supported calculations that accept multiple values, any Invalid values are ignored (Invalid values include any
Function Parameter X fields that have No Tag Selected chosen, have a value of 0, or are left blank).
The supported operations are:
+ Function Parameter 1 + Function Parameter 2 + Function Parameter 3 + Function Parameter 4
(excluding any Invalid values).
- Function Parameter 1 - Function Parameter 2 - Function Parameter 3 - Function Parameter 4
(excluding any Invalid values).
* Function Parameter 1 * Function Parameter 2 * Function Parameter 3 * Function Parameter 4
(excluding any Invalid values).
/ Function Parameter 1 / Function Parameter 2 / Function Parameter 3 / Function Parameter 4
(excluding any Invalid values).
& Function Parameter 1 & Function Parameter 2 & Function Parameter 3 & Function Parameter
4 (excluding any Invalid values).
| Function Parameter 1 || Function Parameter 2 || Function Parameter 3 || Function Parameter 4
(excluding any Invalid values).
Average Average of Function Parameters 1 through 4 (excluding any Invalid values).

510 • How to Build an Application Developer's Guide (part 1)

Max Maximum of Function Parameters 1 through 4 (excluding any Invalid values).
Min Minimum of Function Parameters 1 through 4 (excluding any Invalid values).
Integrate Performs time integral of Function Parameter 1 * Function Parameter 2 every Function
Parameter 3 seconds.
If Function Parameter 2 is not defined, it defaults to a value of 1.
If Function Parameter 3 is not defined, it defaults to a value of 1 second. For example, if
Function Parameter 2 and Function Parameter 3 were not defined, the calculation would
be Function Parameter 1 * 1 every 1 second).

Note: A Function tag will return a value of 1 when the specified input tags are invalid and the AND operation is used.
Similarly, a Function tag will return a value of 0 when the specified input tags are invalid.

Function Properties: Inputs Tab

The Inputs tab identifies the numeric values or tag values that will be factors in the calculation.

Function Parameter X
The Function Parameter 1 through to Function Parameter 4 fields enable you to specify up to four factors in the
calculation performed by this tag.
The Function Parameter X fields toggle between a numeric entry field and a tag selection field, according to the setting
of their related Constant checkbox (described below).
If the Constant checkbox beneath a Function Parameter X field is selected, you may enter a numeric value to be used in
this tag's calculation.
If the Constant checkbox beneath a Function Parameter X field in not selected, a … button and a X button appear to the
right of the Function Parameter X field. You may click the … to open the Tag Browser, which enables you to select an

Developer's Guide (part 1) How to Build an Application • 511

existing tag whose value will be used as the first factor in the calculation, or create a new tag whose value will be used as
the first factor in the calculation. The Function Parameter 1 field can be cleared using the X button that appears to its
right.
Right-clicking a tag that has been selected in the Function Parameter X field opens the associated tag properties folder.

Note: For supported calculations that accept multiple values, any Invalid values are ignored. Invalid values include
Function Parameter X fields (where X is 1 through 4) that have No Tag Selected chosen, have a value of 0, or have been
left blank. For example, if the Function tag is configured to perform an addition operation on three factors, and the fourth
factor is left Invalid, the resulting calculation would be Function Parameter 1 + Function Parameter 2 + Function
Parameter 3. Because no Function Parameter 4 was Invalid, the field is ignored.

Constant
Constant checkboxes toggle the field with which they are associated between a numeric entry field, and a tag selection
field.
If the Constant checkbox is selected, the associated field will accept the entry of a number.
If the Constant checkbox is not selected, the associated field contains a … button and a X button. The … button opens
the Tag Browser, which enables you to select an existing tag to associate with this tag, or create a new tag to associate
with this tag. (Information on using the Tag Browser can be found in "Tag Browser"). The X button clears a selected tag
from the field.

Note: You cannot select a Function tag as one of its own function parameters.

Note: A Function tag will return a value of 1 when the specified input tags are invalid and the AND operation is used.
Similarly, a Function tag will return a value of 0 when the specified input tags are invalid.

Function Properties: Manual Tab

The Manual tab contains the Manual Data and Questionable Data properties. The Manual Data field can be used to enter
a user-defined value for this tag that will override the value of its calculation. The Questionable Data checkbox allows
you to flag this tag’s data as being questionable in the event that you feel the values it is reporting might not be accurate,
or when this tag has initially been created and you wish to ensure that its data is monitored for validity.

Manual Data
Enables you to set a user-defined value for this tag, rather than reading the value from the associated I/O device (i.e. this
user-defined value overrides the data incoming from the equipment).
If this field is anything other than a blank, or an invalid number, then the value from the I/O device is ignored and this
value will be used instead.
The drawing method used by any tag with Manual Data will include an exclamation mark.

Note: If the value entered into the Manual Data field is a 0, the actual value reported by the equipment is also overridden,
as 0 is considered a valid value. Therefore, if it is your intention to resume reading data from the I/O device, you must
clear the Manual Data field entirely.

Questionable Data
Use this field to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when
this tag has initially been created and you wish to ensure that its data is marked for extra monitoring. Please see the topic
Merit Tab and Quality Tab, for details.

512 • How to Build an Application Developer's Guide (part 1)

Function Properties: Owner Tab
Some VTS tags can be used in an owner/contributor structure where multiple contributor tags can supply their values to
an owner tag. The Owner Tab allows you to specify the owner tag to which this tag should contribute its data.

Note: There is no specific "owner" tag type, rather an owner tag is typically a custom designed tag that is created using
VTS scripting code for special projects.

Owner
The Owner field enables you to specify a tag to which this contributor should supply its data. An owner tag is one which
you must design and then create, using the VTS scripting language.
The owner tag may keep track of different aspects of each contributor's data, from the presence of a user-defined manual
data value, to questionable data, according to the configuration of the checkboxes appearing beneath the Owner field.
These checkboxes also determine the way that this contributor tag's value should be used in the owner tag's calculations.

Set Owner\DataX(…) to Value

When selected, the Set Owner\DataX[…] To Value checkbox enables you to set the value of this contributor tag as the
nth element in the owner tag's array. You may choose to set this contributor tag's value in more than one of the owner
tag's array elements if required.

Set Active/Unack. Priority

An owner tag may keep track of the alarm priority and status of its contributors. When selected, the Set Active/Unack.
Priority checkbox causes the owner tag to keep track of the priority of the contributor's active alarm (or records an
Invalid if the contributor is not currently in an alarm state). Selecting the Set Active/Unack. Priority checkbox also
causes the owner tag to record whether or not the alarm has been acknowledged.

Record Use of Manual Data

An owner tag may keep track of the number of contributor tags that are providing manual data (user-defined values),
rather than reading data from their I/O device. When selected, the Record Use of Manual Data checkbox enables you to
increment the owner's count of the number of tags that are contributing manual data by 1 when manual data has been
provided for this contributor, and decrement this count by 1 when no manual data value has been specified.

Record Data Quality

Developer's Guide (part 1) How to Build an Application • 513

An owner tag may keep track of the quality of the data for each of its contributors. When selected, the Record Tag
Quality checkbox enables you to increment the owner tag's count of the number of tags that are contributing quality data
by 1, and decrement this count by 1 when this contributor is not supplying quality data.

Record Tag Validity

An owner tag may keep track of the questionable status of the data for each of its contributors. When selected, the
Record Tag Validity checkbox enables you to increment the owner tag's count of the number of tags that are contributing
questionable data by 1, and decrement this count by 1 when this contributor is not supplying questionable data.

Function Properties: Alarm Tab

The Alarm tab allows you to create new Alarm tags that will be triggered by this tag.
Use the Add button to open a configuration panel for a new Alarm tag. The triggered-by field for the new alarm will
automatically be linked to this tag’s value. The new alarm tags will be created as children of the current tag.

Function Properties: Script Tab

The Script Tab allows you to create one or more Script tags to be associated with this tag.
A Script tag provides a means of creating a procedure, using VTS’s programming language, that will run whenever this
tag’s value changes.

Function Properties: Logger Tab

The logger tab enables you to associate a single Logger tag with this tag. The Logger tag works with a Historian to this
tag’s data to disk so that it can be plotted on the Historical Data Viewer page. The new logger tag will be created as a
child of the current tag.

Note: Only one Logger tag can be directly associated with a single input or output tag. If you need to have multiple
loggers with different logging rates, please refer to Using Function Tags to Create Multiple Data Logs of an I/O Tag

Using Function Tags to Create Multiple Data Logs of an I/O Tag

It is a requirement that only one Logger tag be directly associated with an input or output tag.
If you attempt to create multiple loggers to save data for the same tag, it is possible that errors will occur. This does not
mean that you cannot record data at different log rates for the same tag; it simply means that you must use a different
approach.
In addition to performing mathematical and logical calculations, one or more Function or Calculation tags can be used to
read the values of a single input or output tag. Therefore, the solution to logging tag data at different log rates for the
same input or output tag is to create as many Function tags as you require log rates, and then configure the Logger tags to
record data for each of the Function tags, rather than for the single input or output tag.
The instructions below will guide you through this process.

Configure a Function or Calculation Tag to Mirror an Input or Output Tag's Value

1. Open the Tag Browser.
30. Select Function or Calculation from the Types drop-down list. The list of tags filters to display tags of the Function
tag type.
31. Click the New button. A new Function tag properties folder opens.
32. Enter a name for the Function tag in the Name field.
33. Select an appropriate area from the Area drop-down list.
34. Enter a description for the Function tag in the Description field.

514 • How to Build an Application Developer's Guide (part 1)

35. Click the Inputs tab.
36. Select the input or output tag whose data you wish this Function tag to mirror from the Function Parameter 1 drop-
down list.
37. Click the OK button.
The Function tag will now have the same value as the input or output tag you've associated with it. You can configure as
many Function tags as you require, and associate them with a single input or output tag.
You may now configure two Logger tags to log the data at different rates. Assign one to the input or output tag, and one
to the Function tag. VTS will save the data from each.
Also, calculation and Function tags being what they are, you can use them to log a function of one or more tag values
rather than simply a single tag’s value.

Function Tag Drawing Methods

The following drawing methods are available to display information about your application’s Function tags:
Animated Bitmap Drawing Method Bottom Bar Drawing Method
Color Box Drawing Method Color Fill Drawing Method
Color Line Drawing Method Gradient Color Change Drawing Method
Image Change Drawing Method Left Bar Drawing Method
Meter 1 Drawing Method Meter 2 Drawing Method
Meter 3 Drawing Method Multi-color Drawing Method
Multi-text Drawing Method Numeric Value Drawing Method
Plot Data Drawing Method Right Bar Drawing Method
Text Change Drawing Method Top Bar Drawing Method
Two Color Bar Drawing Method

History Statistics Tag

Each instance of a History Statistics tag will perform 7 statistical calculations, using the data collected from a numeric
tag's value over a defined time period. History Statistics tags complement, rather than replace, Totalizer tags and Counter
tags. The result of only 1 calculation will be shown, but you may display other calculations by linking other History
Statistics tags to the first – these will simply take the result of the requested calculation from the first tag rather than
performing calculations of their own.
The available calculations include:
• Time-weighted average – average value over a specified length of time.
• Minimum value during period
• Maximum value during period
• Value at start
• Count of zero to non-zero transitions (e.g. equipment starts)
• Non-zero time (example: total time that a pump was running during the period)
• Totalizer, calculated as the sum of the values logged during the time period. Note that this calculation differs
substantially from that used by Totalizer tags.

Any numeric tag may be used as the data source, so long as its value is logged. The exception is if the data source is
another History Statistics tag. A warning will appear if you attempt to use a data source that is not being logged.

Developer's Guide (part 1) How to Build an Application • 515

Statistics are collected over a given duration of time (the Manual Data Period option in the tag's configuration). You
provide the length of the time period and the frequency at which the display is to be updated. Time durations fall on
regular clock intervals. For example, a manual data period set for the latest 1 hour, updated every 15 minutes, will use
logged data for the 60 minutes prior to the most recent quarter-hour mark.

Note: Use care if attempting to use a Digital Output tag as a data source for counting 0 to 1 transitions (equipment starts).
While the output tag may be writing a 1 to the equipment, the value of the Digital Output tag itself will only be 1 if it is
configured for a pulse duration, or if it has a feedback configured and there is a delay between when the output writes
and the feedback shows that the value has been written. If neither of these is true, then the Digital Output tag's value will
remain 0 and you will not get the number of times that it wrote a start value to the equipment.

The calculated value of the History Statistics tag can be displayed on a page using any of the Analog drawing methods.
While a History Statistics tag can be selected for inclusion in the Historical Data Viewer (HDV), clicking on one that is
drawn on a page will not cause the HDV to open. Note that if you want to save the values calculated by the History
Statistics tag, you will need to configure a Logger tag for it.

(Characteristics available in the Table of Type Characteristics.)

History Statistics Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

History Statistics Properties: Source Settings Tab

Use this tab to select the logged tag whose value is to be used for the calculation, and the particular calculation to be
performed by this instance of the History Statistics tag.
Every standard VTS tag has only one source variable that can be used for the calculation: its value. Custom tag types
may expose other variables that can be used in the calculation.

Source

516 • How to Build an Application Developer's Guide (part 1)

Select the tag whose value (or other source variable) is to be used in the calculation. All numeric tag types are available.
By default, the nearest Numeric parent tag will be selected. You can select another History Statistics tag here if you wish
to display a different one of its 7 calculations. Selecting another History Statistics tag as the data source will disable the
Data Period options for this tag instance.

Source Variable
For all standard VTS tags, the only source variable is the tag's value. Custom tags, written specifically for your
application, may make other variables available. If so, the drop-down list will be populated with the available choices.

Statistic
Select the calculation to be performed from the following list:
• Average – time weighted average over the data period.
• Minimum value during the data period.
• Maximum value during the data period.
• Value at start of the data period.
• Zero to non-zero transitions during the data period.
• Non-zero time. Example: total time that a pump was running during the period.
• Totalizer – the value of the source added to itself each second during the data period.

Scaling Factor
The calculated value will be multiplied by the factor you specify in this field. Use for applying a scaling factor to the
value, for example if correcting for raw values that are measured in terms of minutes or hours instead of seconds.
Defaults to 1.

Engineering Units
Provide units of measure that the input data represents. Possible values for this field include "rpm" "degrees C", "%", etc.

Questionable Data
Use this field to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when
this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

History Statistics Properties: Data Period Tab

This panel is used to set the length of the calculation period, and the rate at which the calculation is updated.
If another History Statistics tag has been selected as the data source, all fields in this panel will be disabled. The source
History Statistics tag will control the data period.

Developer's Guide (part 1) How to Build an Application • 517

Latest
Use the text field to set a number of time units. The statistic calculation will use data from this length of time, measured
to the nearest clock interval as controlled by the update rate.

Update Rate
Sets the frequency at which the statistic is recalculated. The calculation will always use data from the full length of time
specified by the Latest field, ending on the clock interval specified by this update rate. For example, if the update rate is
5 minutes, the update will occur at the 5 minute mark, 10 minute mark, etc.
The update rate must not be greater than the duration of time over which the statistic is being calculated, and can be no
smaller than 0.1% of that time period.

History Statistics Properties: Historian Tab

Allows you to link a Historian tag to this History Statistics tag in order to save a record of the summary data calculated
by the History Statistics tag. Logging is done at the interval configured in the data period tab. In a remote application,
logging is broadcast to all machines running the application.

History Statistics Tag Drawing Methods

The following drawing methods are available to display information about your application’s History Statistics tags:

518 • How to Build an Application Developer's Guide (part 1)

Animated Bitmap Drawing Method Bottom Bar Drawing Method
Color Blink Drawing Method Color Box Drawing Method
Color Fill Drawing Method Color Line Drawing Method
Draw Text Drawing Method Gradient Color Change Drawing Method
Image Change Drawing Method Left Bar Drawing Method
Meter 1 Drawing Method Meter 2 Drawing Method
Meter 3 Drawing Method Meter 4 Drawing Method
Meter 5 Drawing Method Meter 6 Drawing Method
Meter 7 Drawing Method Meter 8 Drawing Method
Meter 9 Drawing Method Meter 10 Drawing Method
Meter 11 Drawing Method Meter 12 Drawing Method
Meter 13 Drawing Method Multi-color Drawing Method
Multi-text Drawing Method Numeric Value Drawing Method
Plot Data Drawing Method Right Bar Drawing Method
Text Change Drawing Method Top Bar Drawing Method
Two Color Bar Drawing Method

Network Status Tags

These are used to inquire about the connection status between two computers (usually a server and a workstation). A 1 is
returned for a good connection, 0 for no connection and Invalid if no information can be determined.
(Characteristics available in the Table of Type Characteristics.)

Network Status Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Network Status Properties: Settings Tab

The Settings tab for a Network Status tag is used to specify which workstations you want to monitor. You must provide
the names of the machines to monitor. IP and Subnet are required only if separate connections between the computers are
possible. In this case, you must tell VTS which connection to monitor.

Developer's Guide (part 1) How to Build an Application • 519

Machine 1 Name
Specify the name of one of the two workstations, the connection between which is to be monitored. You may enter the
name of the workstation in this field, or select the name of the workstation from the drop-down list.

Machine 1 IP
The Machine 1 IP field enables you to enter the IP address of the first workstation to be monitored by this tag.

Machine 1 Subnet
The Machine 1 Subnet field enables you to enter the subnet for the first workstation to be monitored by this tag.

Machine 2 Name, IP and Subnet

These three fields match those of Machine 1. They enable you to specify the name, IP address and subnet of the second
workstation to be monitored by this tag.

Manual Data
The Manual Data property enables you to enter a value for this tag, rather than reading the value from the monitored
workstations. In this instance, the Manual Data property may be set to 0, indicating that the workstation is not connected;
or 1, indicating that the workstation is connected.

Questionable Data
Use this field to flag this tag’s data in the event that you suspect the values it is reporting might not be accurate, or when
this tag has initially been created and you wish to ensure that its data is marked for extra monitoring. Please see the topic
Merit Tab and Quality Tab, for details.

Network Status Properties: Alarm Setup Tab

The Alarm Setup tab for a Network Status tag (shown below) enables you to configure alarm conditions for this tag.

520 • How to Build an Application Developer's Guide (part 1)

Alarm Priority
The Alarm Priority drop-down list enables you to select the priority of the alarm for this tag, should it enter an alarm
state. The available priorities are:
None (alarm not configured)
0 – Event
1 – Critical
2 – High
3 – Warning
4 – Notice

Delay
The Delay field enables you to enter the amount of time (in seconds or fractions of a second) that the system
will wait before triggering an alarm for this tag. This tag must therefore be in an alarm state for the amount of
time specified in the Delay field before an alarm will be indicated.

Sound
The Sound field enables you to identify what sound will be played when this alarm is triggered. The Sound field can be
set to a 0, 1, or to the name of a .WAV sound file to be played.
If the Sound field is set to 0, no sound will be played when this alarm is triggered.
If the Sound field is set to 1, an alarm sound whose properties are configured on the associated Alarm Priority tag will be
played.
If the Sound field identifies the name of a .WAV sound file, it will override any alarm sound configured for the
associated Alarm Priority tag. When specifying a sound file, you must enter its name and extension (e.g. MySound.wav).
The specified sound file must be a .WAV file, and must be stored in the application directory. If the specified sound file
is not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

Alarm Disable
The Alarm Disable checkbox enables you to disable and enable the alarm for this tag. Alarm disabling is typically used
in situations where routine maintenance is being performed, or when you are aware that another interruption in
communications will occur for a period of time. In such a situation, an alarm can be disabled until the maintenance is
complete and communications are reestablished.

Developer's Guide (part 1) How to Build an Application • 521

Popup Enable
If the application property AlarmPopupsEnable is set to 1, then checking Popup Enable will result in a popup dialog
being displayed whenever the alarm is triggered. It is strongly suggested that this feature be used sparingly.

Network Status Properties: Historian Tab

If you select a Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer.
Historians are described in the topic, Historian Tag. You may log to more than one Historian by duplicating this tag's
value in a Calculation tag and attaching to it a Logger that is configured with a different Historian or a different
logging rate.

Note: There are consequences if you change the selected Historian tag after you have begun
collecting data. If you switch to a new Historian (perhaps for organizational or load sharing
purposes), the data collected for this tag by the previous Historian will become inaccessible.

Network Status Tag Drawing Methods

The following drawing methods are available to display information about your application’s Network Status tags:
Animated Bitmap Drawing Method
Color Blink Drawing Method
Color Box Drawing Method
Gradient Color Change Drawing Method
Image Change Drawing Method
Network Link Drawing Method
Plot Data Drawing Method
Text Change Drawing Method
Two Color Bar Drawing Method

Rate of Change Tags

Rate of Change tags are used to display how quickly another tag’s value is changing. They can be used to watch for
system problems such as leaks and blockages.

522 • How to Build an Application Developer's Guide (part 1)

The Rate of Change tag calculates the first derivative of another tag’s value. In general terms, this is defined as the
change in value divided by the change in time. A steady flow has a rate of change of zero.

Note: The source tag's value must be logged in order for the Rate of Change tag to work properly.

The rate of change will be positive if the source is increasing in value, and negative if the source tag’s value is
decreasing. The tag can be configured to report the absolute value instead, thus showing a positive value for any rate of
change.

For example, the water level in a large holding tank would normally change slowly unless it started to leak. A tank
feeding a process would be expected to have a level decreasing at a minimum rate unless the outlet became blocked. A
Rate of Change tag can be configured for either situation in order to detect departures from an expected rate of change.
Alarms built into the tag can be triggered when the rate is too fast or too slow.

Note that in remote applications, the Rate of Change tag information is distributed from the server to workstations on a
regular interval (default: 60 seconds) or when the value changes by a given percentage (default: 5%). These values are
controlled by variables in your configuration file. See: RateOfChangeTagRPCThreshold and
RateOfChangeTagRPCInterval for details.
(Characteristics available in the Table of Type Characteristics.)

Rate of Change Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Rate of Change Properties: Settings Tab

The Settings tab is used to select which tag is to be watched and how frequently it is to be checked.

Developer's Guide (part 1) How to Build an Application • 523

Source
Use this option to select the tag to be monitored for changes in value.
If you would like to monitor the rate of change of some combination of tags or a calculated value, you should create a
Calculation tag with the expression you need and use it as the source.

Source Time Scale

If the data source is a rate (e.g. flow rate) rather than an amount (e.g. tank level) then you should use this field to match
the data source’s measurement rate. Available options include: per Second, per Minute and per Hour.

Positive Rate
When checked, the absolute value of the rate of change will be shown. Otherwise, a decreasing value in the source tag
will be displayed as a negative rate of change.

Refresh Interval and Period

• The Refresh Interval sets how frequently the rate of change is calculated. This value is always measured in seconds.
• The Period defines the length of time over which the change is to be measured. It is also measured in seconds.
The rate of change is roughly defined as the amount by which the value has changed during a given period, divided by
the length of time in the period. To state it more accurately, the rate of change is the calculated derivative (dy/dx) of the
plotted value.

Note: The rate of change calculation is affected by data noise and transient spikes. The period should always be set to a
value larger than the frequency of data noise. To avoid alarms due to transient noise, set a delay on the alarm. (see: Rate
of Change Properties: Alarms Tab.)

Engineering Units
Used by various drawing methods. Set this field to display the units of the rate of change.

Questionable Data
Use this field to flag the tag’s data in the event that you suspect the values it is reporting might not be accurate, or when
this tag has initially been created and you wish to ensure that its data is marked for extra monitoring.

Manual Data
This optional field allows you to provide a constant value that will be used instead of input read by the communication
driver. It is commonly used when testing a new Analog Input tag when application is not attached to a live data source.
Tags that are using manual data are marked on screen by a flashing exclamation mark.

524 • How to Build an Application Developer's Guide (part 1)

Rate of Change Properties: Display Tab
The controls in the display tab are used only in connection with the Historical Data Viewer (HDV). The Displayed Value
Minimum and Maximum set the initial limits of the y-axis for this tag when it is viewed in the HDV.
These fields do not scale the data.

Rate of Change Properties: Alarms Tab

You can set alarms to notify operators when the rate of change is either too slow or too fast.
High alarms are triggered when the rate matches or exceeds a set point. Depending on whether the Positive Rate option
is checked on the Settings tab, the Low Alarm can be used either to warn on large negative changes, or to warn when the
rate of change falls below a desired minimum.

Developer's Guide (part 1) How to Build an Application • 525

Low and High Alarm Priority
The Low and High Alarm Priority drop-down lists are used to select the priority of the alarms that will be triggered for
this tag. The default priority is None, indicating that neither alarm has been configured. The available priorities are:
• None
• 0 – Event
• 1 – Critical Alarm
• 2 – High Alarm
• 3 – Warning Alarm
• 4 – Notice Alarm
If you have defined your own Alarm Priority tags, those will also be available for selection.

Low and High Alarm Setpoints

Use the Low Alarm Setpoint field to enter the lowest value that this rate of change value will be permitted to attain, after
which a low alarm will be triggered. Correspondingly, the High Alarm Setpoint is used to set a value at which the high
alarm should be triggered.
If the Positive Rate option is selected on the Settings tab, all rates of change will be positive. In this situation, the high
alarm is used to warn of excessively high rates of change (whether the changing value is rising or falling). The low alarm
could be used to warn of change rates that are too slow.
If the Positive Rate option is not selected, the high alarm will warn only of excessive change rates for values that are
rising. The low alarm set point should be set to a negative value to warn of excessive change rates for values that are
falling.

526 • How to Build an Application Developer's Guide (part 1)

The source for these fields may be either a constant, the result of an expression, or the value of a tag. Please see the
topic: Constant, Expression or Tag for more information on selecting between these three choices.

Low and High Alarm Deadbands

If noise in the system causes a value to fluctuate above and below the set point, the alarm will repeatedly switch between
active and inactive status. By using the deadband, you can dampen out these fluctuations by setting an amount by which
the tag’s value must retreat back past the set point before the alarm state is considered to no longer be active.
For the low alarm, this means that the value must rise <deadband> units above the set point. For the high alarm, the
value must fall by <deadband> units below the set point.
The deadband is used only for changing a current alarm’s active status. It does not affect the set point.

Low and High Alarm Delays

Noise in the value being monitored may cause transient spikes or drops in the reported rate of change. To avoid having
alarms triggered by system noise, you can set a delay in seconds. The value must meet or exceed the alarm set point for
the length of the delay time before an alarm will be activated.

Low and High Alarm Priorities

The Alarm Priority drop-down lists enable you to set the priority of the alarm(s) that will be triggered. It is not
uncommon to have a different priority for low versus high alarms. See: Alarm Priorities for more information about the
following standard options:
• 0 – Event
• 1 – Critical Alarm
• 2 – High Alarm
• 3 – Warning Alarm
• 4 – Notice Alarm
If you have defined your own Alarm Priority tags, those will also be available for selection.

Disable Low or High Alarm

The Disable … Alarm field enables you to specify whether either the low alarm or high alarm for this tag is enabled.
Disabling of alarms is typically used in situations where you wish to avoid false alarms. For example, in the event that
routine maintenance is being performed on the equipment represented by this tag, the alarm can be disabled until the
maintenance is complete and communications are re-established.
A value of 0 (or any tag or expression that returns 0) means that the alarm has not been disabled. Any value other than 0
in this field indicates that the alarm has been disabled.
The value can be provided via any of a constant, an expression, or a tag. Please see the topic: Constant, Expression or
Tag for help selecting which to use.

Low Alarm Popup Enable & High Alarm Popup Enable

If the configuration variable AlarmPopupsEnable is set to 1, then setting either the Low Alarm Popup Enable or the High
Alarm Popup Enable, will result in a pop-up dialog being displayed whenever the respective alarm is triggered. It is
strongly suggested that this feature be used sparingly.

Sound
The Sound fields can be used to set the sound that will be played when either the low alarm or the high alarm is
triggered. These fields can be set to blank, 0, 1, or to the name of a .WAV sound file to be played.
If a Sound field is set to 0, no sound will be played when this alarm is triggered.
If a Sound field is set to blank or 1, an alarm sound whose properties are configured on the associated Alarm Priority tag
will be played.

Developer's Guide (part 1) How to Build an Application • 527

If a Sound field contains the name of a .WAV sound file, it will override any alarm sound configured for the associated
Alarm Priority tag. When specifying a sound file, you must enter its name and extension (e.g. MySound.wav). The
specified sound file must be a .WAV file, and must be stored in the application directory. If the specified sound file is
not found, the alarm will revert to using tones as specified in the associated Alarm Priority tag.

Rate of Change Error Dialogs

The period must be set to a value that is larger than the refresh interval for the Rate of Change tag to work properly.
Attempting to set either value such that this is no longer the case will result in the following error dialog:

Acknowledge the dialog by clicking on the Close button, then adjust the complementary value (either a larger period or a
smaller refresh interval) before continuing to set the value you were first attempting to set.

Rate of Change Tag Drawing Methods

The following drawing methods are available to display information about your application’s Rate of Change tags:
Numeric Value drawing method Draw Text drawing method
Meter 1 drawing method Meter 2 drawing method
Meter 3 drawing method Animated Bitmap drawing method
Two Color Bar drawing method Color Fill drawing method
Multi-Color drawing method Multi-Text drawing method
Plot Data drawing method Text Change drawing method
Image Change drawing method Color Box drawing method
Color Blink drawing method Gradient Color Change drawing method
Color Line drawing method

Totalizer Tags
The Totalizer tag provides a means of accumulating the sum of another tag's (or calculation's) value over time. To put it
more precisely, the totalizer integrates a value over a time period.
The totalizer looks for its source to represent values "per second", "per minute" or "per hour". It is important to select a
source time scale that matches the source values. For example, when recording total flow from a meter that is measuring
flow rate per second, selecting the "per minute" source time scale is guaranteed to produce results that are incorrect.
You can also use the totalizer to record running time. For this, the source value must be a 1 when the equipment is
running and a 0 when stopped. Given a source time scale of "per second" this will add 1 second, per second while the
equipment is running and 0 seconds per second while stopped.
An invalid is not taken to mean that the value (or running state) of the tag is 0. If the source's value goes to invalid, it will
be assumed that the last known value remains in effect and that value will continue to be used for the integration.
Values are added to the Totalizer tag at the end of each elapsed source time scale. This will not necessarily be "on the
second" or "on the minute".

528 • How to Build an Application Developer's Guide (part 1)

A Logger tag should never be attached to the totalizer since this is done for you. At the end of each log interval, values
are automatically logged. You have the option of performing a reset of the Totalizer tag's value after each write to the log
file.
You can cause a reset to be done at times other than the set logging interval, either by providing a reset button for the
operator to use, or by configuring a tag to use an external reset. The current value is always logged before a reset is done.

Note: If the totalizer is drawn with a Set Analog Value tag or a Numeric Entry tag, two things will happen when the
operator uses either drawing method: the totalizer will log its current value and it will reset to whatever value is set by
the drawing method instead of 0.

It should be noted that a plot of the Totalizer tag on the Historical Data Viewer will show a constant value from one log
interval to the next, with an instant change between values at each log interval.
The current value of the Totalizer tag is saved between VTS restarts.

Note: Never attempt to attach a Logger tag to a Totalizer tag. Totalizer tags have a built in logger.

(Characteristics available in the Table of Type Characteristics.)

Totalizer Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Totalizer Properties: Settings Tab

All options relevant to the main purpose of the Totalizer tag can be found in the settings tab.

Developer's Guide (part 1) How to Build an Application • 529

Source
The source can be any tag, calculation or even a constant. Whatever value is provided here will be the value that is
totaled. In most cases, this will be an analog status or Analog Input tag, but there are no restrictions on the source. You
might use a digital input to collect a total of equipment running time. If, for example, you specify a constant value of 1,
the totalizer will record the total time that the application is running.

Source Time Scale

While there is no limitation on what can be used for the source, a Totalizer tag will commonly be used with equipment
such as a flow meter. Flow meters may provide their values in units of flow per second, flow per minute or flow per
hour. Selecting the correct time scale is of critical importance to collecting an accurate total.

Log Interval
The Totalizer tag will record its current total to a log file at the end of each interval specified. This interval goes by the
clock, not by running time. If, for example, the log interval is set to "Day", the tag's value will be logged at midnight, not
at the end of 24 hours of operation. If the log interval is set to "Hour", the tag's value will be logged each hour on the
hour. Weekly means midnight on Sunday night and Monthly means midnight starting the first day of the month.

Reset After Log

You can select whether or not the totalizer should be reset to 0 after its value is logged.

Zero Cut-off Limit

To allow for a source that does not output an exact 0 when there should be no value to record, you can set a zero cut-off
limit. This value is taken as a range, above and below zero, within which the totalizer takes 0 to be the source's value.
Note that this is a range above and below zero, not a low value cut-off. Negative input values are possible from the
source tag and are totaled as such.

Engineering Units
Text stating what the Totalizer tag is totaling (e.g. Gallons, Liters…).

External Reset
Allows you to specify a tag or calculation to force a reset of the totalizer. Note that the current value of the tag will
always be logged before a reset. The reset will occur when this input changes from a 0 or false value to a non-zero value.
A change from invalid to non-zero does not cause a reset.

Totalizer Properties: Merit Tab

The Merit tab contains the Questionable Data checkbox. Use this field to flag this tag’s data in the event that you suspect
the values it is reporting might not be accurate, or when this tag has initially been created and you wish to ensure that its
data is marked for extra monitoring. Please see the topic Merit Tab and Quality Tab, for details.
This tab also contains the Security Privilege field. Select an application security privilege from this drop down if you
wish to limit the operation of this control to only those operators who have been granted the matching security privilege.

530 • How to Build an Application Developer's Guide (part 1)

Totalizer Properties: Historian Tab
If you select a Historian tag, this tag's run-time values will be saved for use in reports and the Historical Data Viewer.
Historians are described in the topic, Historian Tag. You may log to more than one Historian by duplicating this tag's
value in a Calculation tag and attaching to it a Logger that is configured with a different Historian or a different
logging rate.

Note: There are consequences if you change the selected Historian tag after you have begun
collecting data. If you switch to a new Historian (perhaps for organizational or load sharing
purposes), the data collected for this tag by the previous Historian will become inaccessible.

Totalizer Tag Drawing Methods

The following drawing methods are available to display information about your application’s Totalizer tags:
Elapsed Time drawing method Reset Button drawing method
Reset Target drawing method Last Logged Value drawing method
Numeric Value drawing method Draw Text drawing method
Meter 1 drawing method Meter 2 drawing method
Meter 3 drawing method Animated Bitmap drawing method
Two Color Bar drawing method Color Fill drawing method
Multi-Color drawing method Multi-Text drawing method

Developer's Guide (part 1) How to Build an Application • 531

Plot Data drawing method Text Change drawing method
Image Change drawing method Color Box drawing method
Color Blink drawing method Gradient Color Change drawing method
Color Line drawing method Numeric Entry drawing method
Set Analog Value drawing method

Script Tags
Script tags monitor the value of another tag and enable the execution of a piece of script code upon a change in the
monitored tag's value. The sections that follow discuss Script tags in detail.
(Characteristics available in the Table of Type Characteristics.)

Script Tag Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Script Tag Properties: Execute Tab

The Execute tab of the Script tag properties folder contains the properties required to identify the tag in which the script
is to be executed, and the name of the script to be used.

In Tag Scope
The In Tag Scope field enables you to specify a tag to associate with this tag. The tag identified will be the tag within
which the scripting code defined by this Script tag will run.
The In Tag Scope field can be used to associate this tag with a new or existing tag using the … button. The … button
opens the Tag Browser, which displays the existing tags for your application, and enables you to create a new tag using
its New button. (Information on using the Tag Browser can be found in "Tag Browser").
The In Tag Scope field can be cleared using the X button to its right.
Right-clicking the name of the tag that has been selected in the In Tag Scope field opens the tag properties folder for the
selected tag.

Launched Module

532 • How to Build an Application Developer's Guide (part 1)

The Launched Module field enables you to specify the name of the module to be run within the tag identified in the In
Tag Scope field.

Script Tag Drawing Methods

Script tags monitor the value of another tag and allow the execution of a script when the monitored tag's value changes.
The drawing methods associated with Script tags enable you to display the value of the completed script.
The following drawing methods are available to Script tags:
Animated Bitmap Drawing Method Bottom Bar Drawing Method
Color Fill Drawing Method Gradient Color Change Drawing Method
Left Bar Drawing Method Meter 1 Drawing Method
Meter 2 Drawing Method Meter 3 Drawing Method
Multi-color Drawing Method Multi-text Drawing Method
Numeric Value Drawing Method Plot Data Drawing Method
Right Bar Drawing Method Top Bar Drawing Method
Two Color Bar Drawing Method

Station and Site Tags

Tags in this category create multi-I/O structures, designed for specific types of stations.

MPE Duplexer Station Tags

Available only in VTScada-based applications.
"MPE" stands for Motor Protection Equipment. A single MPE Duplexer Station tag includes all of the I/O required to
monitor and operate a MPE Duplexer station.
(Characteristics available in the Table of Type Characteristics.)

MPE Duplexer Station Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Developer's Guide (part 1) How to Build an Application • 533

MPE Duplexer Station Properties: Settings Tab

Controller Model
The options are, Duplexer or Intrinsically Safe Duplexer. Defaults to Intrinsically Safe.

Number of Pumps
Set the number of pumps in the station, thereby controlling how many associated child tags will be created. Ranges from
one to two.

Well Depth
Provide the depth of the well, as measured in the units specified in the next field. Setpoints must be with the range of the
well depth provided.

Depth Units
Provide the system of units to be used for the depth of the well. This value is used only as a label on the display.

High Level (Ft)

Provide a number

Lag Level (Ft)

Provide a number

Well Volume
Provide the volume capacity of the well, as measured in the volume units specified in the next field.

Volume Units
Provide the system of units to be used for measuring the volume of fluid in the well. This value is used only as a label on
the display.

Lead Level (Ft)

Provide a number

534 • How to Build an Application Developer's Guide (part 1)

Off Level (Ft)
Provide a number

Low Level (Ft)

Provide a number. Used only if the Intrinsically Safe model has been selected.

Privilege
If you wish to restrict access to the controls of this station, select the application privilege to be associated with it. Only
the operators who have been assigned a security rule that includes this privilege will be able to control the station.

MPE Duplexer Station Properties: Communications Tab

Port
Select the communications port to use for this station. By default, the nearest parent will be selected.

Modbus Configuration
The driver created for this station will be based on the Modicon Driver. Use the fields in this section to configure the
details of the Modbus protocol that will be used. For detail, see: Modicon Driver Tags.

Station Number
Poll Sequence if this tag is using a PollDriver. Also used for sorting the data in a Pump Activity or Derived Flow report.

I/O Driver Override (optional)

Developer's Guide (part 1) How to Build an Application • 535

Provides a way for you to select an existing driver tag to be used instead of the driver built-into the station.

MPE Duplexer Station Properties: Display Tab

The Location tab is used to define the placement (latitude and longitude) of the MPE Duplexer station. Decimal values
should be used rather than degrees, minutes and seconds.
You may also define a custom details page to use in the event that you have created one you would prefer over the built-
in Site Details page. Many of the drawing methods available to the MPE Duplexer have their own configuration for
which page is to be opened when clicked. The page selected in the drawing method will have priority over the page
selected in this tab. By selecting a details page here, you set the default to be used by those drawing methods, and for
drawing methods such as the map pin, which does not have any configurable options.
A custom details page should include a tag parameter, named SiteTag, of the same type as this tag. The built-in Site
Details page has two other parameters, which you may consider supporting in your custom page:
A parameter of type Status. This should be tied to the "Use Theme" parameter of any custom drawing methods in the
page.
A parameter of type text, which may be referenced by the TextColor parameter of certain drawing methods.

You may find it easier to set the location using the map interface than to enter the latitude and longitude values here. See:
Site Map.

MPE Duplexer Station Tag Drawing Methods

The following drawing method are available:
Site Icon Site Summary

536 • How to Build an Application Developer's Guide (part 1)

 Site Details Pump Control
Well Details Well Flow
Well Plot Well Setpoints
Controller Status Station Summary
Alarm List Station All Inputs
Station All Outputs Station Comms
Station Faults Station Stats
Pump List Tag List
Analog Control List Analog Input List
Digital Input List Digital Output List

MPE Duplexer Child Tags

A single MPE Duplexer Station tag includes all of the I/O required to monitor and operate a MPE Duplexer pumping
station. The I/O tags, alarms and more are implemented as child tags of the MPE Duplexer Station.
(See: Parent-Child Tag Structures)
It is recommended that you do not create instances of these independently of a MPE Duplexer station.
(Characteristics available in the Table of Type Characteristics.)

MPE Duplexer Child Tag Drawing Methods

These drawing methods are components of the overall MPE Duplexer Station displays. While they can be drawn
independently, it is recommended that you use the MPE Duplexer Station drawing methods in order to create these
components in the correct context.

MPE SC Series Station Tags

Available only in VTScada-based applications.
MPE stands for Motor Protection Equipment. This tag will support either of the SC1000 or the SC2000 controllers.

(Characteristics available in the Table of Type Characteristics.)

MPE SC Series Station Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Developer's Guide (part 1) How to Build an Application • 537

MPE SC Series Station Properties: Settings Tab

Controller Model
Specify whether this tag is to be used with the MPE SC1000 or the SC2000 controller.

Number of Pumps
Select the number of pumps that are installed at this station. Possible values range from one to four.

Well Depth
Provide the depth of the well, as measured in the units specified in the next field.

Depth Units
Provide the system of units to be used for the depth of the well. This value is used only as a label on the display.

Flow Units
Provide the system of units to be used for flow. This is required only if flow calculations are supported by the controller.

Well Volume
Provide the volume capacity of the well, as measured in the volume units specified in the next field.

Volume Units
Provide the system of units to be used for measuring the volume of fluid in the well. This value is used only as a label on
the display.

Total Daily Flow Units

Provide the system of units to be used for total flow. This is required only if flow calculations are supported by the
controller.

538 • How to Build an Application Developer's Guide (part 1)

Depth Probe Present
Check to box to indicate that your well has a depth probe.

Station Backup Generator Present

Check to box to indicate that your station has a backup generator.

Flow Calculations Supported

Check to box to indicate that your controller supports flow calculations.

Pump VDF Control Supported

Check to box to indicate that your controller provides VDF control.

Privilege
If you wish to restrict access to the controls of this station, select the application privilege to be associated with it. Only
the operators who have been assigned a security rule that includes this privilege will be able to control the station.

MPE SC Series Station Properties: Communications Tab

In this tab, you define the parameters for the Communications Port and the Modbus Driver that will be created
automatically as part of this station.

Port
Select the communications port to use. By default, the nearest parent will be selected.

Modbus Configuration

Developer's Guide (part 1) How to Build an Application • 539

The driver created for this station will be based on the Modicon Driver. Use the fields in this section to configure the
details of the Modbus protocol that will be used. For detail, see: Modicon Driver Tags.

Station Number
Poll Sequence if this tag is using a PollDriver. Also used for sorting the data in a Pump Activity or Derived Flow report.

I/O Driver Override (optional)

Provides a way for you to select an existing driver tag to be used instead of the driver built-into the station.

MPE SC Series Station Properties: Auxiliary DI Tab

Provides an Enabled / Disabled option for each of the auxiliary input addresses of the station. The actual value being
monitored by each input, N, can be configured using the drop-down list in the "Input N" section of the panel.

540 • How to Build an Application Developer's Guide (part 1)

MPE SC Series Station Properties: Auxiliary DO Tab
You may define up to six auxiliary digital outputs for an SC2000 controller and up to five auxiliary digital inputs for the
SC1000.

MPE SC Series Station Properties: Auxiliary AI Tab

You may define up to four auxiliary analog inputs for the SC2000 controller. The SC1000 does not support auxiliary
analog inputs.

Developer's Guide (part 1) How to Build an Application • 541

MPE SC Series Station Properties: Display Tab
The Location tab is used to define the placement (latitude and longitude) of the MPE SC Series station. Decimal values
should be used rather than degrees, minutes and seconds.
You may also define a custom details page to use in the event that you have created one you would prefer over the built-
in Site Details page. Many of the drawing methods available to the MPE SC Series have their own configuration for
which page is to be opened when clicked. The page selected in the drawing method will have priority over the page
selected in this tab. By selecting a details page here, you set the default to be used by those drawing methods, and for
drawing methods such as the map pin, which does not have any configurable options.
A custom details page should include a tag parameter, named SiteTag, of the same type as this tag. The built-in Site
Details page has two other parameters, which you may consider supporting in your custom page:
A parameter of type Status. This should be tied to the "Use Theme" parameter of any custom drawing methods in the
page.
A parameter of type text, which may be referenced by the TextColor parameter of certain drawing methods.

542 • How to Build an Application Developer's Guide (part 1)

You may find it easier to set the location using the map interface than to enter the latitude and longitude values here. See:
Site Map.

MPE SC Series Station Tag Drawing Methods

The following drawing methods are available to display information about your application’s MPE SC Series Station
tags:
Site Icon Site Summary
Site Details Pump Control
Well Details Well Flow
Well Plot Well Setpoints
Controller Status Pump Alternation Control
Station Summary Station Power
Alarm List Station All Inputs
Station All Outputs Station Comms
Station Faults Station Stats
Pump List Tag List
Analog Control List Analog Input List
Digital Input List Digital Output List

MPE SC Child Tags

A single MPE SC Station tag includes all of the I/O required to monitor and operate a MPE SC Series pumping station.
The I/O tags, alarms and more are implemented as child tags of the MPE SC Station.
(See: Parent-Child Tag Structures)

Developer's Guide (part 1) How to Build an Application • 543

It is recommended that you do not create instances of these independently of a MPE SC station.
(Characteristics available in the Table of Type Characteristics.)

MPE SC Child Tag Drawing Methods

These drawing methods are components of the overall MPE SC Station displays. While they can be drawn
independently, it is recommended that you use the MPE SC Station drawing methods in order to create these components
in the correct context.

MultiSmart Station Tags

Available only in VTScada-based applications.
A single MultiSmart Station tag includes all of the I/O required to monitor and operate a MultiSmart pumping station.
Configuration is done in part through the standard set of VTS tag configuration panels and in part through a MultiTrode-
supplied XML file that describes your equipment.
(Characteristics available in the Table of Type Characteristics.)

MultiSmart Station Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

MultiSmart Station Properties: Settings Tab

Number of Pumps
Lift stations may have from one to six pumps.

544 • How to Build an Application Developer's Guide (part 1)

Well Depth
Provide the depth of the well as measured in the Units value specified (meters, feet or inches). This value is used for the
visual representation of the well and as a limit on the possible setpoint values.

Well Volume
Provide the volume capacity of the well, measured in the Units value specified (US gallons or Liters). This value is used
by related reports.

Units
Select the system of measurement to be used. Choices are Metric (base unit: meters), Imperial A (base unit: feet) or
Imperial B (base unit: inches).

Negative Offset
An offset to the level measurement, used to account for the distance from the bottom of the probe to the bottom of the
well. Since the zero level in VTS is relative to the bottom of the probe, failing to add the value of this offset can result in
false alarms and incorrectly displayed values.

XML Configuration File and Import XML File

Click the Import XML File button to locate and import the configuration file for this station. A copy is made of the file
that you import - no link is maintained to the original file. If the original is edited, you will need to import again in order
to bring those changes into your application.
The selection list shows the files that have previously been imported.

Privilege
If you wish to restrict access to the controls of this station, select the application privilege to be associated with it. Only
the operators who have been assigned a security rule that includes this privilege will be able to control the station.

Developer's Guide (part 1) How to Build an Application • 545

MultiSmart Station Properties: Communications Tab

Port
Select the TCP/IP or Serial Port tag that is to be used for communication with the equipment. If the station is being
created as a child tag of a port, the ancestor port tag will be selected automatically.

Protocol
Selection determines what type of communications driver will be created for use in this station. Choices are DNP3 or
Modbus

Protocol Configuration
Configuration options vary according to the selected protocol type. For detail, see: DNP3 Driver Tags or Modicon Driver
Tags.

Station Number
Poll Sequence if this tag is using a PollDriver. Also used for sorting the data in a Pump Activity or Derived Flow report.

I/O Driver Override (optional)

Provides a way for you to specify a specific, existing driver tag to be used instead of the driver built-into the station. In
most cases this need not be selected.

MultiSmart Station Properties: Display Tab

The Location tab is used to define the placement (latitude and longitude) of the MultiSmart station. Decimal values
should be used rather than degrees, minutes and seconds.

546 • How to Build an Application Developer's Guide (part 1)

You may also define a custom details page to use in the event that you have created one you would prefer over the built-
in Site Details page. Many of the drawing methods available to the MultiSmart Station have their own configuration for
which page is to be opened when clicked. The page selected in the drawing method will have priority over the page
selected in this tab. By selecting a details page here, you set the default to be used by those drawing methods, and for
drawing methods such as the map pin, which does not have any configurable options.
Your custom details page should include a tag parameter, named SiteTag, of the same type as this tag.

You may find it easier to set the location using the map interface than to enter the latitude and longitude values here. See:
Site Map.

MultiSmart Station Tag Drawing Methods

The following drawing methods are available to display information about your application’s MultiSmart Station tags. In
most cases, you need only use the Station Icon or the Station Summary. The remaining methods are components of the
station page that will be created for you. Both the Station Icon the Station Summary link to this page. See: Station
Pages... for a description of this page and the various components.
If your application includes more than one station tag, you may prefer to draw a Station List, which is an automatically
created display of Station Summary drawing methods, one for each station.

Site Icon Site Summary

Site Details Pump Control
Well Details Well Flow
Well Plot All Well Setpoints
Well Setpoints Controller Profile
Controller Maintenance Alarm List
Custom Alarms Station Summary

Developer's Guide (part 1) How to Build an Application • 547

 Station Power Pump List
Station All Inputs Station All Outputs
Station Comms Station Faults
Station Stats Tag List
Analog Control List Analog Input List
Digital Input List Digital Output List

MultiSmart Station Child Tags

A single MultiSmart Station tag includes all of the I/O required to monitor and operate a MultiSmart pumping station.
The I/O tags, alarms and more are implemented as child tags of the MultiSmart Station.
(See: Parent-Child Tag Structures)
It is recommended that you do not create instances of these independently of a MultiSmart station.

MultiSmart Station Child Tag Drawing Methods

These drawing methods are components of the overall MultiSmart displays. While they can be drawn independently, it is
recommended that you use the MultiSmart drawing methods in order to create these components in the correct context.

ScadaAce Site Tags

Available only in applications that are built on the ScadaAce layer.
A ScadaAce Site tag should be created using either the Add Site button or Manage Sites button in the Sites page of a
ScadaAce application.
Note that, the first time you start a ScadaAce application, you will be prompted to create a gateway.

ScadaAce Site Properties: ID tab

When created using the Add button in a Motorola IP Gateway tag, the ID tab will not look like other ID tabs. The row of
tabs, found across the top of most tag configuration panels, will be shown only after the ID tab fields have been filled in
and you click the OK button.
Note that, clicking the OK button will cause two actions: The site tag will be created, and the configuration panel for this
tag will be re-opened, this time showing all the tabs. After that point, clicking the Cancel button will discard
configuration changes, but will not abort the tag creation process.
Note that upon clicking OK, a series of other configuration tabs will be enabled. Of those, the Analog Inputs tab will be
opened first.

548 • How to Build an Application Developer's Guide (part 1)

Name
Add a name, appropriate for the site being created.

Area
After pressing Tab or Enter to finish entering the name, the Area field will automatically configure itself to match the
name that you provided. This is done so that, when viewing alarms on the Alarm Page, any alarms from different sites
that happen to have the same description (a very likely scenario) can be told apart by looking at the Area column. You
are free to change the Area field if you wish.

Description
A description should be provided for every site.

RTU ID and RTU Type

The RTU ID value should match the identifier for the device at this site.

ScadaAce Site Properties: Settings tab

The Settings tab repeats two parameters from the ID tab: RTU ID and RTU Type. In most cases, you will have
configured these values before creating the tag, but they may be created, or changed in this tab.

Developer's Guide (part 1) How to Build an Application • 549

Two application privileges may be applied to a ScadaAce site: Operators with the View privilege may see the details of
this site in a site list. Operators with the Control privilege may write values with this site's output tags.
You must create your own application privileges to use. See: Application Privileges.
The location fields, Latitude and Longitude are most easily filled in by placing this site on a map. This can be done when
creating the site, if you use the Add Site button in the Sites page. Or, you may locate the site after you have saved the
configuration. Close all development dialogs and click on the site - a Site Details map will open, including a map. There,
you may click the Update Location button to place or move the location pin.
Alternatively, you are free to type in the latitude and longitude coordinates for the site.
Selecting a Custom Details page is an advanced operation, requiring that developer create a customized page for this site.
If so, it may be selected using this menu item.

ScadaAce Site Properties: Analog Inputs tab

Up to 25 Analog Input points may be configured for each site. Matching child tags of type, Analog Status, will be
created for each that you configuring using the spread-sheet format. The format allows for rapid configuration of tags
without needing to create each independently in the Tag Browser. Unscaled values need not be provided since these
values are known for the ScadaAce RTU. I/O addresses for each input are pre-defined by the ScadaAce system.
The I/O address of each tag is configured for you, following the format, B2:n-1:0 where n matches the number in the
tag's name.
Click on the label <add>, in the description column to begin configuring each input. Note that you may tab between
fields, and use the Enter key to finish an input and move on to the next row.
Related Information:
Analog Status Tags Provides a full description of the configuration fields in an analog input.

550 • How to Build an Application Developer's Guide (part 1)

Description Since the names are pre-defined, you must provide a description for each tag in order for operators to
know what the value represents.
Scaled Min The minimum value for this input, in terms of the engineering units being measured.
Scaled Max The minimum value for this input, in terms of the engineering units being measured.
Units Engineering units that the input represents.
Low Alarm Upon first clicking in the Low Alarm field, the space will resolve into two inputs: The value, below
which a low level alarm should be activated, and the priority of that alarm, presented as a drop-down list.

High Alarm Configured in the same way as the Low Alarm. When the input's value goes above this setpoint, an
alarm of the specified priority will be activated.

Developer's Guide (part 1) How to Build an Application • 551

Statistics Tracking Check in order to enable tracking of Minimum, Maximum and Average values of this input,
over time. Two History Statistics tags will be created for each option you choose. Statistics over the past 24 hours and
statistics for the time period, "yesterday".

The Delete button will clear an I/O tag's configuration, effectively removing the matching child tag. It does not destroy
the matching tag number, which may be used again later.

ScadaAce Site Properties: Analog Outputs tab

Up to four analog output tags (created using the Analog Control type) can be configured. Operators will be able to use
these tags to write values to the RTU.
The I/O address of each tag is configured for you, following the format, 6:n-1:0 where n matches the number in the tag's
name.
Click on the label <add>, in the description column to begin configuring each output. Note that you may tab between
fields, and use the Enter key to finish an input and move on to the next row.
Related Information:
Analog Control Tags Provides a full description of the configuration fields in an analog output.

Description Since the names are pre-defined, you must provide a description for each tag in order for operators to
know what the value represents.
Scaled Min The minimum value for this input, in human terms.
Scaled Max The minimum value for this input, in human terms.
Units Engineering units that the input represents.

ScadaAce Site Properties: Digital Inputs tab

Up to 96 digital input tags (created using the Digital Status type) can be configured. The are used to monitor whether
points on the RTU are in state 0 or state 1.
The I/O address of each tag is configured for you, following the format, B1:n-1:0 where n matches the number in the
tag's name.
Click on the label <add>, in the description column to begin configuring each input. Note that you may tab between
fields, and use the Enter key to finish an input and move on to the next row.
Related Information:
Digital Status Tags Provides a full description of the configuration fields in a digital input.

Description Since the names are pre-defined, you must provide a description for each tag in order for operators to
know what the value represents.
OFF text / ON text These columns match input states zero and one, respectively. You may change the text
accordingly if state zero is defined as "ON" and state one is defined as "OFF" at your operation.

552 • How to Build an Application Developer's Guide (part 1)

Alarm Click in the alarm field to begin configuration. Use the first drop-down list to configure the state or
state-transition that will activate an alarm. Using the second column, select the priority of this alarm.

Alarm Delay Configure a time period, measured in seconds, for which the tag must remain in its activation state
before an alarm is considered to have occurred.
Statistics Tracking Check in order to enable tracking of On Time, or On Counts of this input, over time. Two
History Statistics tags will be created for each option you choose. Statistics over the past 24 hours and statistics for the
time period, "yesterday".

ScadaAce Site Properties: Digital Outputs tab

Up to 48 digital output tags (created using the Digital Control type) can be configured. These allow operators to issue
control actions to the equipment.
The I/O address of each tag is configured for you, following the format, 5:n-1:0 where n matches the number in the tag's
name.
Click on the label <add>, in the description column to begin configuring each output.
Related Information:
Digital Control Tags Provides a full description of the configuration fields in a digital output.

Description: Since the names are pre-defined, you must provide a description for each tag in order for operators to
know what the value represents.
OFF text / ON text. These columns match input states zero and one, respectively. You may change the text
accordingly if state zero is defined as "ON" and state one is defined as "OFF" at your operation.

ScadaAce Site Properties: Drawing Methods

Three drawing methods are available for the ScadaAce tag, Site Icon, Site Details, and Manage I/O.
In practice, it is not expected that you will need to use any of these. The Sites page, built into every ScadaAce-based
application, will automatically add each site you configure.

Configuration Tags
Tags in this category relate to the appearance or structure of your application. This list includes Context tags, Font tags
and the Realm Display Setup tag.

Context Tags
Context tags are used as parents in parent-child tag structures. They provide a generic and customizable template that
you can use to define any natural grouping in your application (region, station, city, sub-assembly, etc.). The parameter

Developer's Guide (part 1) How to Build an Application • 553

list for a context tag is left for you to configure. You may add whatever properties you wish. For example, you might
add properties named Latitude and Longitude in order to be able to draw the Context tag on a Site Map, or you might
create I/O address fields that can be used by child tags that you add to the Context tag.
Your context tags may be given their own tag-type names (as opposed to instance names), and may be given a user-
defined list of properties and matching values. The type name will be used if you chose to turn the Context tag into a new
tag type definition. See: Create New Types of Tags.

A Context can be displayed on a Site Map if it is given settings named "Latitude" and "Longitude".
By adding a setting named, "StationPageName", you can configure a Context to show a custom details page when its
drawing method is clicked on a Site List or Site Map page.
Your custom details page should include a tag parameter, named SiteTag, of the same type as this tag.

Related topics: Parent-Child Tag Structures, User Draw Methods.

(Characteristics available in the Table of Type Characteristics.)

Context Properties: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.
The Context Tag's ID tab contains an extra field named, "Type". If, after creating the context tag, you right-click on it in
the tag browser and select "Create Type", you will create a new tag type, named after the contents of the Type field.
The name you provide for the type must be a single word and must not duplicate the name of any existing type of tag. An
error dialog box will warn you if invalid characters are used, or if the name supplied cannot be used as the name of a new
tag type.

Context Properties: Settings Tab

554 • How to Build an Application Developer's Guide (part 1)

Context tags may be given a list of named properties. Each copy of the tag may then be given its own unique values for
those properties. There is no limit on the number of named properties that you may create.

Note: Property names may not duplicate VTS reserved words. To be safe, adopt a naming convention that adds a distinct
identifier to every name (for example "MA_Name" for My Application...)

By defining properties in a context tag, you provide a method for children of that tag to adapt their configuration values
to the parent instance via Snapshot Expressions. For example, I/O addresses may be calculated from a BaseAddress
value stored in the Context tag instance.
If you want to display the context tag on a map, you must add properties named "Latitude" and "Longitude".
See: Parent-Child Tag Structures, and Calculate Tag Configuration Values - Snapshot Expressions.

To create a new property click the Add button, which opens the Add Property dialog:

Property names must be unique, not just in the list of properties, but in the tag itself. VTS properties such as Name, Area
and Description may not be used. Attempting to do so will cause the "Name in Use" dialog to open.
Property names must include letters ("Property2" is valid, but "2" is not). The property name may not include a space or
any of the following characters: ! , @ % ^ & * ( ) - ` ~ : ; " ' < > ? / { } [ ] | \

You can change any property name, value or comment by clicking on the field in the settings list. Editing is done in-
place.

If you turn the context tag and its children into a new type using the Update Type command in the tag browser, you can
still edit the list of properties for the type definition as a whole. See: Manage Types Using a Spreadsheet or Database.

Developer's Guide (part 1) How to Build an Application • 555

Context Tag Drawing Methods
The following drawing methods are available to display information about your application’s Context tags. Some may
not be useful unless your Context tag has been configure to have Latitude and Longitude parameters, or to be a parent to
a Polling driver or station tag.

Site Icon Site Summary

Site Details Tag List

Font Tags
Font tags contain font settings that are used throughout your application to display different types of data with different
font attributes.
Several font tags are standard on every installation of VTS, or you may create your own. The standard fonts are
illustrated here:

Font Style Tags

The Font Style tag type is used to specify fonts for the drawing tools that employ text. It is the only standard tag type that
does not have a numeric value; instead, its value is a VTS font type.
By default, every standard VTS application you create consists of 3 Font Style tags. These tags should not be modified
as they are used extensively throughout VTS applications. (Changing the default Font Style tags might adversely affect
the appearance of the VTS interface.) For example, the NoteFont tag is used by VTS for the tool tip notes that appear
when you place the mouse pointer over a tool or graphic object on an application page; changing the NoteFont tag's
properties so that it displays in a 20 point font size will adversely affect the display of tool tips in your application.
The 3 default Font Style tags are described in the table below.

Font Style Tag Property

Name Settings Use
AnalogFont System, 10 pt, Used for numeric graphic objects of analog
Bold tags.
LabelFont MS Sans Serif, 6 Used for normal text labels on application
pt, Bold pages.
NoteFont Arial, 9 pt, Used for tool tips that appear when the mouse
Regular pointer is placed over tools or graphic objects
in your application.
Although it is not recommended that you change the attributes of the existing Font Style tags, you can use them
whenever a tag drawing method or application development tool employs text in its display. Typically these tools
provide you with a drop-down list from which you can select any of the 3 default Font Style tags to be used for the tool's
text.
Additionally, you are welcome to create your own Font Style tags and employ them as you require.
(Characteristics available in the Table of Type Characteristics.)

556 • How to Build an Application Developer's Guide (part 1)

Font Style Properties: ID Tab
The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Font Style Properties: Settings Tab

The Settings tab of the Font Style tag properties folder displays the current settings of the properties for the Font Style
tag, and enables you to change these settings using the Change button to open the Font dialog box.

Fixed Pitch
The Fixed Pitch checkbox enables you to indicate whether or not constant character spacing will be employed for this
Font Style tag (i.e. if the width and height of the font configured for this tag should be fixed.
By default, the Fixed Pitch checkbox is not selected.

Change
The Change button opens a Font dialog that enables you to configure the property settings (font, style, and size) for the
selected Font Style tag.

Realm Display Setup Tags

The usage of the Realm Display Setup tag is described in the VTS Internet Server chapter. It exists only to hold
configuration settings that set the level of control granted to operators connecting to an application from a VTS Internet
Client. There are no drawing methods, no log enabled variables and no group memberships.

Developer's Guide (part 1) How to Build an Application • 557

For context information, please see the topics: Realms and Realm Display Setup.

(Characteristics available in the Table of Type Characteristics.)

Realm Display Setup: ID Tab

The ID tab includes the properties required to identify this tag. The Name, Area, Description, and Help Search Key
properties always appear on the ID tab for all standard tag types.
The properties of the ID tab are described in the topic: The ID Tab.

Realm Display Setup Tag: Settings Tab

The settings tab controls the overall display options. The first drop-down selector is where you choose which realm the
settings will apply to. Only realms that include the current application will be available in the list.
You also have the option of making the settings apply to all realms that include this application, rather than just one at a
time. To decide whether to use that option, you must choose whether you want to provide different settings to different
VIC stations - which would be done via different realms. Changes to this tag take effect immediately. There is no need to
restart the application after adding or changing a Realm Display Setup tag.

You can add exactly one Realm Display Setup tag for each realm that includes the application.

Fixed Size Window, Resizable Window or Full Screen

If the Full Screen option is selected, you will not have access to the other options on this page. Running full screen
implies that the window width and height will be whatever the full (maximum) screen size is. NOTE: When a VIC is
running in full screen, the Windows title bar and other window borders will not be displayed.
If Fixed Size Window is selected, you gain more control over the VIC window at the server side, while not allowing
size control at the VIC. You will be able to set the VIC window size and page style options at the server with this option
selected.

558 • How to Build an Application Developer's Guide (part 1)

The operator will still be able to move the window around on his screen, and will be able to minimize and restore it,
provided that the Disable Min/Max Buttons option has not been selected.
Note that if the specified Fixed Size is larger than the resolution of the computer running the VIC session, scroll bars will
appear on the display.
By selecting Resizable Window, you provide the VIC with the greatest level of control. Operators will be able to re-size
their screen at will, limited only by the optional minimum width and height that you may set in this dialog box.
Your choice of display option will affect which of the remaining controls on the screen are available. The description of
each of those controls will tell you which window options it is relevant for.
Note that leaving the initial Window Width and Height blank (if available) will result in the VIC taking the maximum
screen area as its initial size upon opening.

Initial Window Width and Height Fields

Always available if Full Screen is NOT selected. If you have selected Fixed Size Window above, these controls set the
window width and height for the VIC. If you have selected Resizable Window, then these controls set only the initial
window size for the first time the application is opened on the VIC. On subsequent startups, the resizable VIC window
will remain at whatever dimensions the operator set.
If Full Screen has not been selected and these two values are also not set, the following configuration options (if set) will
be used to determine a default size:
• If BrowserWidth and BrowserHeight are defined in the application properties, these values will be used.
• Otherwise, if DispMgrWidth and DispMgrHeight are set in the application properties, those values will be used.
• Otherwise, the default width and height will simply fill the screen.
These settings are maintained by the VIC and so (for a re-sizable VIC application) apply only for the first time the VIC is
opened. If the operator resizes the screen, the VIC will re-open to the last width and height used.

Minimum Window Width and Height Fields

Available only if the Resizable Window option is selected. Sets the minimum width and height that the VIC is able to
resize to. Defaults to 25 pixels.
If these values are not set for a resizable VIC, then the application will check the configuration file to see whether
DispMgrMinWidth and DispMgrMinHeight have been set and if so, will use those. Otherwise, no minimum values will
be set.

Disable Min/Max Buttons

This option is not available if Full Screen option is selected. Does exactly what it says to the Min/Max buttons at the top
right of the client's screen.

Constrain Aspect Ratio

Available only if the Resizable Window option is selected. Forces the VIC screen to maintain a constant aspect ratio
(width to height) while it is being re-sized.

Realm Display Setup Tag: Page Style Tab

The Page Style tab includes settings that apply to VIC sessions that display in Full Screen Mode (as set on the Settings
Tab). This is a list of which elements of both the Title Bar and the Task Bar you wish to make visible.

Developer's Guide (part 1) How to Build an Application • 559

Elements of the Title Bar and Task Bar:

Title Bar Style:

Provides a series of yes-or-no checkboxes controlling which parts of the title bar should be displayed on the VIC
including whether the title bar should be displayed at all. See below for an example showing a title bar and task bar in a
VIC.

Task Bar Style:

Provides a series of yes-or-no checkboxes controlling which parts of the task bar should be displayed on the VIC
including whether the task bar should be displayed at all.

560 • How to Build an Application Developer's Guide (part 1)

Realm Display Setup Tag: Windowed Page Style Tab
The Windowed Page Style tab includes settings that apply to pages that display as windows – whether Fixed Size or
Resizable, as selected in the Settings Tab.

Title Bar Style:

Provides a series of yes-or-no checkboxes controlling which parts of the title bar should be displayed on the VIC
including whether the title bar should be displayed at all. An image to refresh your memory of the various parts of the
screen is included with the previous topic, Page Style Tab.

Task Bar Style:

Provides a series of yes-or-no checkboxes controlling which parts of the task bar should be displayed on the VIC
including whether the task bar should be displayed at all.

Tag Types Listed in Alphabetical Order

All of the VTS tag types are listed here. For each, a reference is provided to the full description of the type.
Alarm Alarm tags are used to establish rules as to when an alarm should be triggered, and
what behavior should occur.
Alarm Priority The Alarm Priority tag type enables you to specify different alarm indications
(such as the frequency of the alarm tones, the tone cycle, alarm priority, and alarm
highlight color) for alarms of different priorities and categories.
Alarm Status This tag looks for active or unacknowledged alarms matching a given set of
characteristics.
Allen-Bradley Driver The Allen-Bradley driver provides an interface to an Allen-Bradley PLC, allowing
communication via:
• Serial port
• KT/SD I/O board
• TCP/IP
Note: Please refer to CIP Driver tags for information on Allen Bradley

Developer's Guide (part 1) How to Build an Application • 561

 ControlLogix tags.
Analog Control It is the role of Analog Control tags to transmit analog data entered by the user to
an I/O device.
Analog Input The role of Analog Input tags is to represent incoming analog data values from
equipment processes
Analog Output It is the role of analog outputs to take analog data from the user or from another
tag, and write it to an I/O device.
Analog Status It is the role of Analog Status tags to take analog data from an I/O device.
Calculation The Calculation tag type is used to wrap an expression, with the resulting value of
the Calculation tag being the result of the expression. This new tag type replaces
the older Function tag type.
CIP Driver These tags provide an interface between VTS and hardware that uses the CIP
and/or ENIP standards for communications.
Context Context tags are used as parents in parent-child tag structures.
Counter Counter tags provide a means to count events such as pump starts or equipment
cycles.
Data Flow Module Data Flow module tags enable you to represent the installed modules for a Data
Flow RTU.
Data Flow RTU Driver Data Flow RTU drivers are used to provide an interface to a Data Flow RTU.
CalAmp Diagnostic Driver These tags enable users to read statistics from any given Integra-TR or Integra-H
CalAmp unit.
DDE Driver The DDE driver allows tags to read from and write to a local or network DDE
server.
Deadband Control Deadband control tags monitor the value of any tag with a numeric value and
compare the monitored tag's value to a low set point and a high set point.
Digital Control Digital Control tags transmit digital data entered by the user or from another tag
and write it to an I/O device.
Digital Input Digital inputs represent incoming digital data values from equipment, and provide
drawing methods that change color, appearance, or text to impart the value of the
digital input and associated equipment.
Digital Output Digital Output tags take digital information from the user or from another tag and
write it to the I/O device.
Digital Status Digital Status tags accept incoming digital data from an I/O device.
DNP3 Driver The DNP driver is a DNP 3.0 Master that implements all the objects defined in
DNP subset level 3, except for the "Frozen Counter" type.
Driver Multiplexer Driver multiplexer (DriverMUX) tags allow you to set up redundant lines of
communication between I/O tags and equipment.
Font Style The Font Style tag type is used to specify fonts for the drawing tools that employ
text.
Function The Function tag type is used to perform mathematical and logical calculations
using numeric values and/or the values of other tags.
Historian The Historian Tag is used to write data that is to be logged to storage.
History Statistics Each instance of a History Statistics tag will perform 7 statistical calculations,
using the data collected from a numeric tag's value over a defined time period.

562 • How to Build an Application Developer's Guide (part 1)

 Logger The Logger tag type monitors the value of another tag and on a set interval, sends
the values to a Historian for recording.
MDS Diagnostic Driver These tags enable users to read statistics from any given MDS radio.
Modem Modem tags represent a physical modem for your system, and enable outgoing
and incoming calls.
Modicon Driver The Modicon driver provides an interface to a Modicon PLC, allowing
communication via:
• Serial RTU
• Serial ASCII
• SA-85 I/O card for ModBus Plus communications

MultiWrite The MultiWrite tag allows you to configure a set of values that will be written to a
list of registers when triggered.
Network Status Network status tags enable you to view the connectivity of up to two workstations,
allow you to trigger an alarm should a monitored workstation become
disconnected, and enable you to log this data to file.
Notebook The Notebook tag type enables users to add notes on the Historical Data Viewer
page.
Omron Host Link Driver The Omron Host Link driver provides an interface to an Omron PLC via a serial
port.
OPC Client Driver The OPC Client driver allows VTS to act as an OPC Client to an OPC Server,
enabling the exchange of data from a VTS application to an OPC Server.
OPC Server The OPC Server Setup tag is used to turn your application into an OPC Server.
Polling Driver Polling driver tags provide controlled communication between drivers and ports.
Pulse Input Pulse input tags accept incoming analog data from a pulse input device (such as a
rain gauge, transducer, or a gas, water, or electric meter).
Pump Status Pump status tags accept incoming digital data from pumps.
Rate of Change Rate of Change tags are used to display how quickly another tag’s value is
changing.
Realm Display Setup The Realm Display Setup tag is used to control what options are available to a
VTS Internet Client for managing its own screen parameters and appearance.
Report The Report tag type is used to track the data of a user-defined group of tags to a
user-defined output format at regular intervals.
Roster Roster tags are designed to work with the VTScada call-out system. Using a
Roster tag, you may configure contact information for up to 8 operators
Script A Script tag monitors the value of another tag and allows the execution of a script
when the monitored tag's value changes.
Selector Switch Selector Switch tags provide the means to create three-position switches that can
be used (among other things) for implementing Hand-Off-Auto (H-O-A) switches.
Serial Port The Serial Port tag type opens a serial port for use by a driver.

Developer's Guide (part 1) How to Build an Application • 563

 Siemens S7 Driver The Siemens S7 driver provides an interface to Siemens PLCs of the following
types:
• S7-200
• S7-300
• S7-400

SNMP Driver The SNMP driver can be used to communicate with any device that uses the
Simple Network Management Protocol (versions 1 or 2c).
SQL Logger Group SQL Logging allows you to record in an ODBC compatible database, the values
from any tag that could normally be logged.
SQL Logger The SQL Logger tag type allows you to select where data that is to be logged is to
come from.
TCP/IP Port The TCP/IP port tag type enables you to connect your VTS application to a series
of hosts, allowing you to transmit data across a network or over the Internet.
Totalizer The totalizer collects the integral of another tag's value over a time period.
Trigger Trigger tags can be used to activate a process at a set time and date.
UDP/IP Port This tag type can be substituted for a TCP/IP port tag for a driver to allow serial
drivers to transparently use UDP/IP.
Workstation Status Workstation status driver tags can be associated with one or more Analog Input
tags to access data that the driver obtains from the Windows Management
Instrumentation (an API in the Windows operating system that enables devices
and systems in a network to be managed and controlled)

Tag Groups
VTS has tag groups that are used to organize the standard tag types into collections based on their value, capabilities, or
other characteristics. Some of the tag types belong to multiple groups based on shared characteristics. The tag groups are:

Analogs Group Container Group (VTScada)

Digitals Group Drivers Group
Loggers Group Numeric Group
Ports Group Trenders Group
VTScada Drivers Group Stations Group
(VTScada)
The tag groups enable selection of a specific tag type in a tag-associated drop-down list. For example, when creating a
new driver tag type to be associated with an Analog Input or Digital Input tag, clicking the tag browser button to the
right of the I/O Device field opens a group dialog that allows you to select the type of driver tag you wish to create.

Analogs Group
The analogs group assembles those tags that read or write analog (continuous floating point) values to an I/O device.
The group is composed of the following members:

Analog Control tags Analog Input tags

564 • How to Build an Application Developer's Guide (part 1)

 Analog Output tags Analog Status tags
Counter Pulse input (VTScada)
Rate of Change Totalizer

Container Group (VTScada)

The container group is unique to VTScada, and is composed of those tags that can have contributors. (An example of a
container/contributor relationship might be at a power generation station, where the container tag (also referred to as an
owner tag) would calculate the overall power output for the entire station based on the value of its many contributor
tags.)
The container group is composed of the following members:

Analog Statistics Context

Data Flow RTU (VTScada) Digital Statistics
MPE Duplexer Station MPE SC Station
MultiSmart Polling

Digitals Group
The digitals group assembles those tags that read or write digital (discrete) values to an I/O device.
The group is composed of the following members:

Alarm Alarm priority

Data Flow RTU (VTScada) Digital control
Digital input Digital output
Digital status Network status
Polling driver (VTScada) Pump status
Roster Trigger

Drivers Group
The drivers group consists of tags that are used to provide an interface to physical I/O devices or to Windows system
features, such as Dynamic Data Exchange.
The group is composed of the following members:

Allen-Bradley driver Control & information/Ethernet I/P driver

Data Flow RTU (VTScada) CalAmp diagnostic driver
DDE driver DNP3 driver

Developer's Guide (part 1) How to Build an Application • 565

 Driver Multiplexer MDS diagnostic driver
Modicon driver Motorola ACE driver
Omron host link driver OPC client driver
Siemens S7 driver Polling driver (VTScada)
SNMP driver Workstation driver

Loggers Group
The VTS loggers group consists of tags that have a numeric value, and that can have their data logged to disk for data
examination and analysis, and plotting on the Historical Data Viewer page by having a Logger tag associated with them.
The group is composed of the following members:

Allen-Bradley driver
Analog status Data Flow RTU (VTScada)
CalAmp diagnostic driver DDE driver
Digital status DNP3 driver
Driver Multiplexer MDS diagnostic driver
Modicon driver Network status
Notebook Omron host link driver
OPC client driver Pump status
Siemens S7 driver SNMP driver

Numeric Group
The numeric group is composed of tags that have a numeric value:

Allen-Bradley driver Alarm

Alarm Status Analog Control
Analog Input Analog Output
Analog Status Analog Statistics
Calculation CIP driver
Counter Data Flow RTU (VTScada)
DDE driver Deadband Control
Digital Control Digital Input
Digital Output Digital Status
Digital Statistics DNP 3.0 driver

566 • How to Build an Application Developer's Guide (part 1)

 Driver Multiplexer Function
Historian History Statistics
IP Network Listener MDS Driver
Modem Modicon driver
Motorola ACE driver
Network Status Omron Host Link driver
OPC client driver Polling driver (VTScada)
Pulse input (VTScada) Pump Status
Rate of Change Roster
Script Selector Switch
Serial Port Siemens S7 driver
SNMP driver SMS Appliance
SQL Logger TCP/IP Port
Totalizer Trigger
UDP/IP Port Workstation driver

Outputs Group
The outputs group is composed of tags that have can be used to write values:
• Analog Control
• Analog Output
• Digital Control
• Digital Output
• MultiWrite
• Selector Switch

Ports Group
The ports group consists of tags that enable communications between a VTS application and a physical system. The
ports group is composed of the following members:
• Motorola Gateway IP
• Serial port
• TCP/IP port
• UDP/IP port

Stations Group
The ports group consists of tags that enable communications between a VTS application and a physical system. The
ports group is composed of the following members:
• MPE SC Series Station
• MPE Duplexer Station
• MultiSmart Station

Developer's Guide (part 1) How to Build an Application • 567

Trenders Group
The Trenders group consists of tags whose value can be plotted on the Historical Data Viewer page. The tags composing
the Trenders group are:

Allen-Bradley driver Alarm Status

Analog Control Analog Input
Analog Output Analog Status
Calculation Counter
Data Flow RTU (VTScada) CalAmp diagnostic driver
DDE driver Deadband control
Digital control Digital input
Digital output Digital status
DNP3 driver Driver Multiplexer
Function History Statistics
MDS diagnostic driver Modicon driver
Network status Notebook
Omron host link driver OPC client driver
Pump status Rate of Change
Serial port Script
Selector Switch Siemens S7 driver
SNMP driver UDP/IP port
TCP/IP port Totalizer
Trigger Workstation driver
When Trenders is selected in the Tag Browser's Types drop-down list, and the New button is clicked, the Trenders
Group dialog will open, enabling you to select the type of tag you wish to create.
To create a new tag, select the radio button corresponding to the type of tag you wish to create, and then click the OK
button. A new tag properties folder associated with the selected tag type will open for configuration.
A list showing many more device drivers available in VTS can be seen in the topic, VTS I/O Device Driver Library.

VTScada Drivers Group (VTScada)

The VTScada drivers group is unique to VTScada, and is composed of those driver tags that are unique to VTScada:
• Control & Information/Ethernet I/P Driver
• Data Flow RTU
• Polling driver

568 • How to Build an Application Developer's Guide (part 1)

Customization of Tags
VTS provides Application Properties that enable you to make changes to the appearance and/or behavior of VTS
applications.
To learn how to customize the appearance and behavior of your tags, see: Application Properties for Tags

Developer's Guide (part 1) How to Build an Application • 569

 copying 164
deleting 165
drawing 164
editing 164
renaming 165

Index application properties 35

application type 8
application.version 12
apply changes 43
apply ChangeSets 28
apply file changes 57
appmod.src 12
approot.src 12
arc 124
are you sure - confirmation prompts 226
A aspect ratio contraint (realm display setup) 559
accounts.dynamic 12 automatically deploy 45
ACE 273 AVC 44
active orange 155 AverageCPU 375
add new application 15
add override 231 B
add property dialog 40
add snapshot expression 231 backup data 33
add start condition 231 bitmap margin (page background) 166
alarm dialer system tags 464 bitmaps - drawing 130
alarm priority tag type 460 bitmaps - importing 117
alarm setup tab 234 bitmaps folder 12
alarm status tags 463 border 69
alarm tab 234 brightness 154
alarm tag drawing methods 459 bring to front 140
alarm tags 455
align on horizontal center 143 C
align on vertical center 144
align to bottom 143 CalAmp Diagnostic Driver 294
align to left 142 calculation tags 500
align to right 142 change history 60
align to top 144 ChangeSet 18
alignment 140 choose server 19
Allen-Bradley driver addressing 293 chord 126
Allen-Bradley driver tag drawing methods 293 CIP driver addressing 302
Allen-Bradley driver tags 285 CIP driver tags 298
analog clock object 83 clipboard 123
analog control tag drawing methods 422 clock 83
analog control tags 419 color 150
analog input tags 382 color range 152
analog output tags 423 color theme - VAM 14
analog statistics tags 497 colorize hue 154
analog status tag drawing methods 395 colorize intensity 154
analog status tags 388 comments and version control 45
analogs group 564 communication driver alarms 285
application configuration 34 communication driver tags 283
application configuration button 65 communications chain 215
application management 12 compass indicator 84
application pages compile 57
(see also conditional starts (tags) 252
pages configuration toolbox 63

Full Reference VTS Help Reference Index • 571

configuration variables 35 draw scale 86
confirmation 226 drawing tools library 66
container group 565 driver alarms 285
context tags 553, 562 driver list 377
contrast 154 DriverMUX 324
Control Logix tags 298 DriverMUX addressing 329
coordinates 112 drivers group 565
copy property dialog 38 DSN 491
copy tool 123
counter tags 503 E
create new application 15
create new type 260 Edit Properties page 36
cursor coordinate display 66 edit property checkbox 70
custom details page 307, 372, 536, 542, 547, 554 edit property field 72
custom libraries 100 editable 265
custom map icons 184 ellipse 127
CustomMapIcon 185 ErrorAddress 284
CustomSiteIconParm 185 ErrorValue 283
cut tool 123 evenly space horizontally 141
evenly space vertically 141
export file edits 61
D
export tags 267
Data Flow RTU driver tags 303
data folder 12 F
data type suffixes for tag I/O addresses 376
database 490 FailedCount 283
DataFlow communications data page 178 FailedRetryCount 283
Dataradio Diagnostic driver 294 file manifest 58
DDE 216 fill patterns 152
DDE driver tags 308 filtering application properties 37
deadband control tag drawing methods 432 find existing 17
deadband control tags 428 find servers 19
default page 162 folder - drawing tabbed folders 74
default.ros 12 font tags 556
delete object button 124 found applications 17
deploy changes 47 frame 78
deploy changes button 66 FreeDiskSpace 375
development process 5 Full ChangeSet 29
device driver library 377 function tags 509
dialogs
grid options 146 G
digital control tag drawing methods 436
digital control tags 433 gateway 273
digital input tags 398 GDIObjects 375
digital output tag drawing methods 442 get from server 19
digital output tags 437 gradient 152
digital statistics tags 506 graphic editor 101
digital status tags 403 graphic objects 124
digitals group 565 grid 146
disable min/max (realm display setup) 559 grid drawing object 82
disable tags 252 group tool 145
discard file edits 61 groupname.src 12
DNP object types supported 318 groups - bitmaps 117
DNP3 Driver Tag Drawing Methods 315
DNP3 driver tags 310
DNP3 I/O addresses in VTS 315

572 • Index Developer's Guide (part 1)

H M
Handles 376 manage types 264
hide OEM properties 38 manifest 58
hide the VAM 14 map 181
historian tab 236 map icons 184
Historian Tag 476 MapQuest 182
history statistics tag 515 MDS diagnostic driver tags 332
hotbox 171 Memory 376
how to build an application 5 menu editor 208
hue 153 add page 209
divider 211
I sub-tree 212
merge changes 55
I/O tab 235 merit tab 237
ID tab 232 meter parts library 84
image formats supported 130 MIB 366
images - drawing 130 minimum window height (realm display setup) 559
import bitmap images 117 minimum window width (realm display setup) 559
import file edits 60 Modbus 335
import tags 267 modem tags 464
import/export files 59 Modicon driver addressing 342
inheritance 10 Modicon driver tags 335
input tags 381 Motor Protection Equipment controllers 537
Integra 294 Motorola 273
internet client monitor page 181 Motorola ACE 273
IOBPS 376 Motorola ACE driver tags 347
IP Network Listener 281 Motorola IP Gateway tags 273
MPE Duplexer Child Tags 537
K MPE Duplexer Station Tags 533
MPE SC Child Tags 543
keyboard shortcuts 146 MPE SC Series tags 537
multi-line text 137
L MultiPlexer 324
MultiSmart Child Tags 548
layers 8 MultiSmart Station Tags 544
lexicon.vlx 12 Multitrode 544
libraries 66 multiwrite tag 442
libraries button 65 multiwrite tag drawing methods 445
Libraries dialog 159
library
delete 101 N
new 100 network status tag 519
rename 100 new application properties 8
licensing - tags 224 new group - bitmaps 117
lift station page 200 no tool 65
line 133 notebook tags 482
line styles 152 nudge 148
linear indicator 89 numeric group 566, 567
linear legend 91
listener 281
O
local changes 45
logger tab 236 ODBC manager library 96
logger tags 479 OEM layers 8
loggers group 566 OEM Template ChangeSet 30
Omron addressing 351

Full Reference VTS Help Reference Index • 573

Omron Host Link driver tags 349 pulse beacon 184
OPC client driver addressing 354, 355 pulse input tags 409
OPC client driver tags 353, 356 pump status tags 413
OpenStreetMap 182
orange 241 155 Q
order tab 238
output tags 418 quality calculation - drivers 284
owner tab 239 quality tab 237

P R
page background 166 radial indicator 92
page button 175 radial legend 94
page close button 177 rate of change tags 522
page hotbox 171 realm display setup tags 557
page name 166 rectangle 135
page properties 165 redo 140
page security 167 removable 265
page style 170 remove application 32
Page Title 166 report tags 482
Page Tool Tip 166 resizing objects 148
page window flag 166 resources folder 11
page window properties 169 response time calculation 284
pagemenu.txt 12 ResponseTime 283
pages restart required 43
adding and editing 157 reverse changes 55
background 171 revert changes 49
bitmap margins 171 roster tags 468
configuration 159 RTU 216
context menu 160 Run-Only Snapshot Copy ChangeSet 30
copy and paste 162
drawing 160 S
import 161
new 160 saturation 154
parameter string 163 SC1000 controller 537
use last displayed 163 ScadaAce 548
viewing 159 SCADAPack history read 344
viewing a list of 159 scaling tab 240
pages folder 11 scan interval 235
parameters 156, 167, 213 screens 157
paste tool 123 script applications 7
Phantom radio 294 script tab 240
pick graphics 65 script tag drawing methods 533
pick graphics button 65 script tags 532
pie 128 security and version control 45
pins 184 select bitmap 115
pipe 134, 152 select color dialog 150
pipes - editing 148 select multiple objects 147
platforminfo folder 11 selector switch tag drawing methods 450
PLC 216 selector switch tags 445
points 215 send to back 140
polling driver tags 369 serial port 216
polygon 134 serial port tags 275
ports group 567 servers.rpc 12
positioning 140 settings.dynamic 12
program spawn 98 settings.startup 12

574 • Index Developer's Guide (part 1)

shape polygon 148 description 228
short name 223 filter by area 221
show stats button 96 filter by name 220
show version details 53 filter by type 221
Siemens S7 driver tags 357 modifying 255
site details page 187 sorting 228
site legend 98 tags folder 12
site list with map page 188 task bar style (realm display setup) 560
site map 181 TCP/IP port tags 278
site tag 548 template ChangeSet 30
site tools library 97 text 136
sites page 188 theme 14
slippy map 181 Threads 376
SMS appliance tags 472 thumbnail (for pages) 167
snap 146 title bar style (realm display setup) 560
Snapshot Copy ChangeSet 29 tool tip (adding your own) 81
snapshot expression 250 toolbox 63
SNMP driver tags 361 totalizer tags 528
SQL logger group tags 490 transparency 154
SQL logger tags 496 transparent black 156
SQLLoggerAccess 491 trenders group 568
SQLLoggerMySQL 491 trigger tags 451
SQLLoggerOracle 491 Type - definition 260
SQLLoggerSQLServer 491
standard applications 7 U
standard library 67
start condition (tags) 252 UDP/IP port tags 279
station details page 200 undo 139
station pages 190 unique ID 223
I/O data 192 update tag type definitions 261
I/O Device Data 191 UPS monitoring 375
I/O display order 193 user files 11
responding to alarms 197
station tags 533 V
StationPageName 554
stations group 567 valid application path characters 16
statistics 516 valid name characters 227
SuccessCount 283 valid page file name characters 17
switch versions 54 valid page title characters 17
system status tools library 99 VAM 13
SystemCPU 376 version control system 44
version log 51
version numbering 51
T Viper SC 294
tabbed folder 74 ViPR 294
tag browser 216 Virtual Memory 376
tag categories 272 VTS application manager 13
tag groups 564 VTS Application Version Control 44
tag import/export 267 VTS ChangeSet Files 25
tag naming rules 227 VTS Driver Multiplexer 324
tag properties 232 VTS graphic editor 101
tag properties folders 222 borders 119
tags 215 changing multiple properties 104
adding 245 color 112
copying 254 control by expression 106
deleting 255 control by parameter 107

Full Reference VTS Help Reference Index • 575

 control by tag 105
control levels 104
fill 108
images 119
indicator dots 102
menus 102
movement 114
outline 110
pipes 120
scaling 113
visibility 115
VTS graphic editortext 121
VTS Historian 476
VTS Tag Browser 216
VTScada 9
VTSCPU 376

W
window height (realm display setup) 559
window properties 170
window width (realm display setup) 559
working files 11
workstation status tags 374
workstation-specific properties 43

576 • Index Developer's Guide (part 1)