User Guide

MN914006EN, Version 14

Visual T&D Excel®

Add-In
For use with Visual T&D software version 4.3 or later.
All brand and product names appearing in this document are the trademark or registered trademark
of their respective holders.

© 2020 Eaton – All rights reserved.

The information in this document is subject to change without notice.

Eaton’s Energy Automation Solutions

1990 5th Street
Suite 220
Levis, Quebec
Canada G6W 5M6
Phone: +1.418.830.5800
Fax: +1.514.227.5256
Email: [email protected]
Web: http://www.Eaton.com/smartgrid

Technical Support: [email protected]

MN914006EN, Version 14
 EAS-SA QF-MKT-02 Rev.02

Contents
1 Introduction 1
1.1 Related Documentation .........................................................................................1
1.2 Getting Assistance .................................................................................................2

2 Installing the Visual T&D Excel Add-In 3

2.1 Loading the Add-In into Microsoft Excel .............................................................3
2.2 Verify the Installation ............................................................................................4

3 Accessing the data 5

3.1 Setting up the Visual T&D Server Connection .....................................................5
3.1.1 Adding or Modifying a Connection ........................................................6
3.2 Microsoft Excel Basic Concepts............................................................................7
3.2.1 Formulas..................................................................................................7
3.2.2 Cell References .......................................................................................7
3.2.3 Worksheet Functions ...............................................................................8
3.2.4 Array .......................................................................................................8
3.2.5 Array Formulas .......................................................................................8
3.2.6 Date and Time .........................................................................................8
3.3 Inserting a Formula on a Worksheet......................................................................8
3.3.1 Manually Entering a Formula .................................................................9
3.3.2 Entering a Formula Using the Insert Function Command .......................9
3.3.3 Entering an Array Formula ...................................................................10
3.4 Using the Add-In Functions ................................................................................10
3.4.1 Elements Common to all Functions ......................................................11
3.4.2 Suspending the Execution of Visual T&D Functions ...........................11
3.4.3 Removing the Formulas ........................................................................12
3.4.4 The Data Point Browser ........................................................................12
3.4.5 The Event Type Browser.......................................................................16
3.4.6 VssPtProp: Accessing the Properties of a Data Point............................17
3.4.7 VssPtList: Displaying a List of Points that Meet a Specific
Property Criterion..................................................................................20
3.4.8 VssPtCurrVal: Accessing the Current Value of a Data Point................21
3.4.9 VssPtArchVal: Accessing the History of a Data Point..........................24

Visual T&D Excel® Add-In User Guide ●i

EAS-SA QF-MKT-02 Rev.02

3.4.10 VssPtCalcVal: Accessing Data Calculated from the History of the

Data Points ............................................................................................26
3.4.11 VssAlarmAndEvent: Accessing the Alarm and Event History .............33
3.4.12 Updating the Data .................................................................................35

4 Creating a Report Template 37

4.1 Creating a Report Template.................................................................................37
4.2 Generating a Report from a Template .................................................................37

5 Automating Report Generation 39

5.1 Creating the Report Generation Script ................................................................39
5.1.1 Using the Trigger Time in Scripts and Report Templates .....................39
5.1.2 Managing the Server Connection through Script ..................................41
5.1.3 Creating the Script.................................................................................43
5.1.4 Testing the Script ..................................................................................43
5.2 Scheduling a Periodic Report Generation............................................................44
5.3 Creating an Event-Triggered Task to Generate Reports ......................................46

6 Tips and Tricks 49

6.1 The TODAY Function .........................................................................................49
6.2 The NOW Function .............................................................................................49
6.3 Limitations and Known Problems .......................................................................49
6.3.1 Excel Worksheet Limitations ................................................................49
6.3.2 Merge & Center Function .....................................................................50
6.3.3 Loss of Selection after a Data Update ...................................................50

ii ● Contents
 EAS-SA QF-MKT-02 Rev.02

Tables
Table 3-1 Connections window controls....................................................................................... 6
Table 3-2 Visual T&D server connection properties .................................................................... 7
Table 3-3 Visual T&D Excel Add-In functions .......................................................................... 11
Table 3-4 Data Point Browser window controls ......................................................................... 13
Table 3-5 Display Options window: Group Settings tab controls............................................... 15
Table 3-6 Select event type window controls ............................................................................. 16
Table 3-7 VssPtProp function arguments ................................................................................... 19
Table 3-8 VssPtList function arguments ..................................................................................... 21
Table 3-9 VssPtCurrVal function arguments .............................................................................. 22
Table 3-10 VssCurrVal function arguments ................................................................................. 24
Table 3-11 VssPtArchVal function arguments ............................................................................. 25
Table 3-12 VssPtCalcVal function arguments .............................................................................. 30
Table 3-13 Bad quality attributes .................................................................................................. 31
Table 3-14 Uncertain quality attributes......................................................................................... 31
Table 3-15 Good quality attributes ............................................................................................... 32
Table 3-16 Additional quality attributes ....................................................................................... 32
Table 3-17 VssAlarmAndEvent function arguments .................................................................... 35
Table 5-1 VssSetTriggerTime VBA function arguments............................................................ 40
Table 5-2 VssGetTriggerTime function arguments .................................................................... 40
Table 5-3 VssIsConnected VBA function arguments ................................................................. 41
Table 5-4 VssIsConnected VBA return values ........................................................................... 42
Table 5-5 VssConnect VBA function arguments ........................................................................ 42
Table 5-6 VssConnect VBA return values .................................................................................. 42
Table 5-7 VssDisconnect VBA function arguments ................................................................... 43
Table 5-8 VssDisconnect VBA return values ............................................................................. 43

Visual T&D Excel® Add-In User Guide ● iii

 EAS-SA QF-MKT-02 Rev.02

1 Introduction

The Visual T&D family of products is specially designed to integrate a large number of diverse
data sources, thereby providing you with unified view of your electrical substation information.
With the Visual T&D Excel Add-In, you can easily:
 access the current and historical substation data in a Microsoft® Excel® workbook, either
locally or remotely;
 create custom reports from the current and historical substation data;
 perform advanced calculations on the substation data, using Visual T&D server calculation
functions as well as the tools provided by Excel;
 create report templates, and have reports generated automatically.

1.1 Related Documentation

The following Eaton documents contain additional information on other Visual T&D components:
 Visual T&D Installation Guide, MN914009EN.
This document contains all the information required to install, configure and perform the
maintenance of a Visual T&D server.
 Visual T&D Explorer User Manual, MN914001EN.
This document presents the Visual T&D Explorer, an application providing immediate access
to all Visual T&D data points in real time, in a variety of formats, with minimum
configuration effort. It also explains how to configure these data points and the various real-
time and historical views, but also how to set up alarms and events based on these data points'
values.
 Visual T&D Diagram Editor User Guide, MN914002EN.
This document presents the Diagram Editor, a Visual T&D application allowing the creation
of interactive diagrams used to monitor and operate a substation or an electric grid.
 Visual T&D Communication Server User Guide, MN914007EN.
This document explains how to set up the Visual T&D Communication Server, an optional
component of Visual T&D that allows you to connect substation devices to the Visual T&D
server without having to go through an SMP Gateway or an OPC server.

Visual T&D Excel® Add-In User Guide •1

EAS-SA QF-MKT-02 Rev.02

1.2 Getting Assistance

If you have any question regarding the performance, application or testing of any component of
this Eaton product, do not hesitate to contact us. Our staff will be pleased to assist you.
Technical Support
Eaton’s Energy Automation Solutions

Email: [email protected]
Phone: +1.877.834.0009
Toll Free: +1.800.815.2258

Business hours are from 8 a.m. and 5 p.m. CST, Monday to Friday.

2● Chapter 1: Introduction
 EAS-SA QF-MKT-02 Rev.02

2 Installing the Visual T&D

Excel Add-In

The Visual T&D Excel Add-In is an add-in specially designed to be under the control of Microsoft
Excel 2003 or a newer version. Therefore, make sure the software is installed before you begin.
The Visual T&D Excel Add-In belongs to the Visual T&D family of products and is available as
an option at installation time. If you are not sure whether you installed the option, launch the
installation process again.

2.1 Loading the Add-In into Microsoft Excel

The add-in file is named VSSADDIN.XLL. It is installed in the Client/Bin folder of the
Visual T&D installation directory.

Note: The installation process differs with Microsoft Excel 2007 and other newer
versions based on the Ribbon user interface.

Moreover, the Visual T&D Excel Add-In does not work with the 64-bit version of
Microsoft Excel 2010; you must install the 32-bit version of Excel to use the
Add­In.

To load the Add-In file into Microsoft Excel 2003:

 Start Microsoft Excel.
 From the Tools menu, choose Add-Ins.
 In the Add-Ins window, click Browse and select the VSSADDIN.XLL file you found above.

At this point, the list of available add-ins should contain the Visual T&D Excel Add-In.
 Make sure the add-in is selected.
 Click OK, and then close the Add-Ins window.

The Visual T&D menu appears in the Excel menu bar.

To load the Add-In file into Microsoft Excel 2007 or later:

 Start Microsoft Excel.

Visual T&D Excel® Add-In User Guide •3

EAS-SA QF-MKT-02 Rev.02

 Click the Office button, and then click Excel Options. (Excel 2007)

OR

Select the File tab, and then click Options. (Excel 2010)
 Select the Add-Ins tab.
 In the Manage box, select Excel Add-ins, and then click Go.
 In the Add-Ins window, click Browse and select the VSSADDIN.XLL file you found above.

At this point, the list of available add-ins should contain the Visual T&D Excel Add-In.
 Make sure the add-in is selected.
 Click OK to close the Add-Ins window.

The Visual T&D menu command appears in the Add-Ins ribbon.

2.2 Verify the Installation

You can validate if the Visual T&D Excel Add-In was properly installed in very few steps.

To verify the installation in Microsoft Excel 2003:

 Make sure the Visual T&D menu is present on the Excel menu bar.
 From the Visual T&D menu, choose About to verify that correct product version is installed.

To verify the installation in Microsoft Excel 2007 or later:

 Make sure the Visual T&D menu command is present on the Add-Ins ribbon.
 On the Add-Ins ribbon, click Visual T&D, and then click About to verify that the correct
product version is installed.

4● Chapter 2: Installing the Visual T&D Excel Add-In

 EAS-SA QF-MKT-02 Rev.02

3 Accessing the data

The Visual T&D Excel Add-In allows you to include your substation real-time and historical data
in various Excel calculation and report-formatting functions.
In this chapter, you will learn how to set up the Visual T&D server connection. You will then
familiarize yourself with the various data access functions provided by Visual T&D.

3.1 Setting up the Visual T&D Server Connection

To ensure that Excel can access the Visual T&D data, you must first set up a connection to the
Visual T&D server. If you want to access the data for more than one Visual T&D server, simply
repeat the configuration steps for each server.

Note: Remember that the Visual T&D Excel Add-In and the server program may be
installed on different computers. All functions are available, regardless of whether
the server is installed locally or remotely.

To modify the list of available connections, you will use the Connections window. This window
displays the list of connections that have been configured, as well as their respective connection
statuses.

To display the Connections window:

 From the Visual T&D menu, choose Connections.

Control Description
Available Displays the list of connections to Visual T&D servers.
connections

Visual T&D Excel® Add-In User Guide •5

EAS-SA QF-MKT-02 Rev.02

Control Description
Disabled When selected, indicates that the connection is not currently active.

Name Displays the symbolic name of the connection.

Address Displays the name or IP address of the computer on which the server resides.

Status Displays the connection current status.

Add Displays a window through which you can add a new connection.

Edit Displays a window through which you can modify the properties of the selected
connection.

Delete Deletes the selected connection from the list.

Table 3-1 Connections window controls

3.1.1 Adding or Modifying a Connection

When you click Add or Edit in the Connections window, Excel displays the Connection
Properties window that you can use to enter or modify the information required in order to
establish a connection with the server.

Property Description
Name Specifies the symbolic name of the connection.

Address Specifies the name or IP address of the computer on which the server resides.

Port Specifies the TCP port to use.

The Visual T&D server uses port 16102 by default. You can have it use another
port, however, in order to meet network security constraints.
If you do need to modify the port number to be used by the Visual T&D server,
contact our technical support group.

User Name Specifies the name of the user account to be used in establishing a connection to
the server.

Password Specifies the password for the specified user account.

6● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

Property Description
Remember my If selected, the password is saved for the next time you start Excel.
password
Otherwise, you will have to enter your password every time you start Excel for
the purpose of opening a connection with the Visual T&D server.
Note: If you select this option, remember to update the password when you change it on
the Visual T&D server.

Table 3-2 Visual T&D server connection properties

Note: You can use several instances of Excel to simultaneously edit or consult different
documents. Remember that each instance of the application loads into memory,
a copy of the Visual T&D Excel Add-In, which uses its own connections, and that
the server can accept a limited number of connections (4) on a given computer.

To avoid using several connections, you can open all your documents with the
same instance of Excel, using the File menu’s Open command.

3.2 Microsoft Excel Basic Concepts

The Visual T&D Excel Add-In adds advanced functions to the list of functions already available
in Microsoft Excel. Before proceeding, you must be aware of a few basic concepts so that you can
use the functions correctly.

Note: This document is mostly based on Microsoft Excel 2007/2010. Some

clarifications may be specified for Microsoft Excel 2003 when significant changes
were made between those two versions.

3.2.1 Formulas
A formula is an equation that analyzes the data on a worksheet. Formulas perform mathematical
operations such as additions, multiplications or value comparisons. They can refer to cells on the
same worksheet, to cells on other worksheets within the same workbook, or to cells in other
workbooks.
Formulas calculate the values in a specific order. In Excel, a formula always begins with the equal
(=) sign. This sign tells Excel that the characters that follow represent a formula. Next come the
items to be calculated (operands), separated by the calculation operators. Excel calculates the
formula from left to right, based on a specific order for each operator in the formula. You can
modify the order of the operations by using parentheses.

3.2.2 Cell References

A formula can refer to constants and to other cells.
When a cell contains a formula that refers to another cell, it is called a dependent cell. For
example, cell B2 is a dependent cell if it contains the following formula:

=C2
By default, each time there is a change to the cell referred to in a formula, the dependent cell
changes as well.
If you only use constants in a formula, rather than references to other cells, the result changes only
if you modify the formula (ex. the result of =30+70+110 formula, will always be 210).

Visual T&D Excel® Add-In User Guide •7

EAS-SA QF-MKT-02 Rev.02

Formulas can also refer to cell ranges, or to names or labels representing cells or cell ranges.

3.2.3 Worksheet Functions

Functions are predefined formulas that perform calculations using specific values (called
arguments), in a certain order (or structure). For example, the SUM function adds values or cell
ranges, while the PMT function calculates loan payments as a function of interest rate, term and
principal.

3.2.3.1 Arguments
Arguments can be numbers, text, or logical values such as TRUE or FALSE, arrays, error values
such as #N/A, or cell references. The selected argument must result in a valid value. Arguments
can also be constants, formulas or other functions.

3.2.3.2 Structure
The structure of a function begins with the name of the function, followed by a left parenthesis,
followed by the arguments separated by commas, and lastly, by a right parenthesis.
If the function starts a formula, type an equal sign (=) before the name of the function. You can
also use the Insert Function command (see “Entering a Formula Using the Insert Function
Command”, page 9).

3.2.4 Array
An array is used to create unique formulas that generate several results and that act on a group of
arguments spread out across various rows and columns.
Excel supports two types of arrays: formula arrays and constant arrays. A formula array is a
rectangular area of cells that share a common formula. A constant array is a group of constants
that are laid out in a particular manner and that act as an argument in a formula.
Visual T&D functions can all be inserted in a formula array, in order to simultaneously display
several pieces of information for several data points.

3.2.5 Array Formulas

Array formulas perform several calculations and return either a single result or multiple results.
For example, in a list of sales figures for various regions, you can use an array formula to calculate
the average sales figures for a particular region.

3.2.6 Date and Time

Excel stores dates as serial numbers used for calculations. January 1, 1900 is serial number 1 if the
workbook has been using the calendar since 1900. If the workbook has been using the calendar
since 1904, Excel stores January 1, 1904 as serial number 1 (January 2, 1904 as serial number 2).
Using the 1900 example, Excel would store January 1, 1998 as serial number 35796 since 35,795
days would have elapsed since January 1, 1900.

3.3 Inserting a Formula on a Worksheet

There are several ways to insert a formula in a cell on a worksheet. This section provides a
detailed explanation of the mechanisms available in Excel to accomplish the task, along with
Visual T&D Excel Add-In-specific details.

8● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

3.3.1 Manually Entering a Formula

You can enter a formula by simply typing it.

To manually enter a formula:

 Click on the cell in which you want to enter the formula.
 Type an equal sign (=).
 Enter the formula.
 Press Enter.

Important Notes
 You can enter a formula in an array of cells by selecting the cells, typing the formula, and
then pressing Ctrl-Shift-Enter.
 With Visual T&D functions, even if you are requesting numerous pieces of information that
will be displayed in an array of cells, you do not need to select the array of cells. Simply enter
the formula in the first cell of the array, and then press Enter. This can be very useful for
those functions where there is no way of knowing how much space will be occupied by the
results.

In the example below, a formula is typed in cell B2, requesting the units and description for
the 3 points listed cells A2 through A4. Once the Enter key is pressed, the results appeared
in the array of cells B2 through C4. If you were to click on any cell within the array, you
would see that the formula was automatically propagated to each of the cells.

 With Visual T&D functions, if you need to edit a formula that is repeated in an array of cells,
simply select the first cell in the array and make the required modifications. Then make sure
to press Ctrl-Shift-Enter, or Excel will not allow you to continue.
 You can also enter a formula in a range of cells by copying the formula located in another
cell.

3.3.2 Entering a Formula Using the Insert Function Command

The Insert Function command can guide you through the function insertion process.

To enter a formula using the Insert Function command:

 Click on the cell in which you want to enter the formula.

 Click the Insert Function ( or ) button.

Visual T&D Excel® Add-In User Guide •9

EAS-SA QF-MKT-02 Rev.02

 In the Insert Function window, select the desired function, and click OK.

The Function Arguments window appears, displaying the function-specific parameters that
must be specified.
 Enter the required function arguments, and then click OK.

3.3.3 Entering an Array Formula

You create an array formula in the same way you create other formulas, but you select the array of
cells before entering the formula, and you press Ctrl-Shift-Enter after having typed the
formula.

3.4 Using the Add-In Functions

The various functions added to Excel are designed to help you construct requests to access
Visual T&D server data.

Function Description
VssPtProp Function used to access data point properties.

VssPtList Function used to display a list of data points that meet a specific property
criterion.

VssPtCurrVal Function used to access the current values (real-time) of the data points.
Note: This function replaces the VssCurrVal function, which is still supported for
backward compatibility purposes.

VssPtArchVal Function used to access the archived values of the data points in the historical
database.

VssPtCalcVal Function used to access the values that are calculated from archived values in the
historical database.

10 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

Function Description
VssGetTriggerTime Function used to retrieve the trigger time as set by the last VssSetTriggerTime
VBA function call in a script.
This function is intended to be used in report models for event-triggered report
generation (see page 40).

VssAlarmAndEvent This function is used to retrieve the list of alarms and events.

Table 3-3 Visual T&D Excel Add-In functions

Each function requires a group of arguments in order to be able to send a request to the server for
data. The arguments define the nature of the data to be displayed, the list of data points for which
the data is to be extracted, and the manner in which the data is to be displayed in the Excel
workbook.
Thus, each function requires 2 categories of arguments, which are the same for all functions:
 The list of data point names for which the data is being requested. The list must contain at
least one data point, but cannot exceed 500 data points.
 The information to be displayed. This list specifies which information related to the data
(value, timestamp, quality, etc.) is to be displayed, and in what order. Each function has its
own display parameters, in addition to the parameters that are common to all functions.
Each function is described in detail later on in this chapter.

3.4.1 Elements Common to all Functions

The following rules apply to all functions:
 You can use all types of data points (analog and binary, input and output) with all functions.
 Data point names are case-sensitive. It is therefore preferable to use the data point browser
(see “The Data Point Browser”, page 12) to insert data point names as function arguments.
 You can have up to 500 data points per function. However, certain functions may not be able
to return all the data for such a large number of data points, since the Visual T&D server
imposes its own limit on the amount of data it can return per request.
 The cell format is not automatically adjusted by the Visual T&D Excel Add-In. You therefore
have to adjust the format of any cells containing timestamps, as the time in Excel is displayed
as a number of days.
 You can specify the same display parameter more than once. For example, you can display
the value of a data point twice with a single function call.
 Display parameters are not case-sensitive.

3.4.2 Suspending the Execution of Visual T&D Functions

To make it easier to create reports and report models, you can suspend the execution of the
Visual T&D functions that you use in your workbooks. This allows you to avoid sending requests
to the server unnecessarily, the results of which could break the page layout of your model.
When function execution is suspended, the cells containing Visual T&D formulas display the
following text:

(Function is suspended)

Visual T&D Excel® Add-In User Guide • 11

EAS-SA QF-MKT-02 Rev.02

To suspend the execution of the Visual T&D functions:

 From the Visual T&D menu, click Suspend the execution of the functions.

A checkmark is added beside the menu command to indicate that function execution is, in
fact, suspended.

Note: The standard Excel worksheet update procedures do not update the Visual T&D
data. You have to use the commands described below.

3.4.3 Removing the Formulas

You can remove all the formulas you inserted in an Excel workbook. This operation allows you to
create a static copy of a report, while keeping the data obtained through the data access functions.

Note: Make sure you have a copy of the document before you remove the formulas, as
you will not be able to re-insert the formulas with Excel’s Undo command.

To remove all the formulas from a workbook:

 From the Visual T&D menu, click Remove All Formulas.

3.4.4 The Data Point Browser

To simplify the task of entering the function arguments, the Visual T&D Excel Add-In provides a
Data Point Browser, which allows you to browse through the list of available data points for each
configured connection, and to select the data point names to insert in the Excel workbook. You
can then refer to cells containing data points as arguments for the various functions.

To display the Data Point Browser window:

 From the Visual T&D menu, choose Data Point Browser.

12 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

Control Description
Available Displays the list of data points that are available on the selected connection.
connections

Insert top to bottom Inserts the list of Selected points in a column, from top to bottom, starting at
the selected cell in the active workbook. Each data point name is placed in a
cell, based on its order of appearance in the list of selected points.

Insert left to right Inserts the list of Selected points in a row, from left to right, starting at the
selected cell in the active workbook. Each data point name is placed in a cell,
based on its order of appearance in the list of selected points.

Available points Displays the list of all the data points that are available on the selected
connection. Binary data points are displayed in blue and analog data points, in
green.

Filter Filters the Available points by name. All points containing the text entered in
the box will be displayed.

Group Settings Displays the Group Settings tab of the Display Options window, which you
can use to group the points differently so that you can change their order of
appearance in the Available points list.
See “Grouping Data Points”, page 13.

Selected points Contains the list of data points that will be displayed on the worksheet.

Add Adds the selected point to the list.

Remove Deletes the selected point from the list.

Remove All Deletes the entire list of selected points.

Table 3-4 Data Point Browser window controls

3.4.4.1 Grouping Data Points

For display purposes, you can have the Data Point Browser group together all the data points that
start or end with the same characters. You can also specify that there is a delimiter in a specific
position within the data point name.
Let us suppose, for example, that the components of the data point names are delimited by
underscores.
If you ask Visual T&D to group the points together by the beginning of their names, you will
obtain a result that looks like this:

If you open one of the folders, the data points will be displayed as follows:

Visual T&D Excel® Add-In User Guide • 13

EAS-SA QF-MKT-02 Rev.02

Impossible d’afficher l’image.

If you repeat the exercise, but ask that Visual T&D group the points together by the ending of their
names, you will obtain a result that looks like this:

If you open one of the folders, the data points will be displayed as follows:

To specify how you want the data points to be grouped:

 In the Data Point Browser window, click Group Settings.

14 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

Control Description
Include binary points Specifies whether binary points are to be included in the list of data points to
be grouped together.

Group data points Specifies whether or not the data points are to be grouped together.
If you do not put a checkmark, the remaining boxes will not be available.

with a common Specifies that the data points with the same characters at the beginning of
beginning their names are to be grouped together.

with a common ending Specifies that the data points with the same characters at the end of their
names are to be grouped together.

are delimited by Specifies that all the data point names have the same delimiter and that you
occurrence ... of are interested in the nth occurrence of the delimiter. For example, if the
character ... delimiter is an underscore and the data point names contain 3 underscores
separated by other characters, and you specify occurrence 2, you are referring
to the second underscore within the data point name. Visual T&D will group
together all the data points with identical characters preceding or following
the second underscore, depending on whether you requested that the data
points be grouped together by the common beginning or common ending of
their names.

have a fixed length Specifies that Visual T&D is to search for all data point names with n
of ... characters identical characters. For example, if you specify a value of 7, Visual T&D
will group together all the data point names for which the first or last 7
characters are identical, depending on whether you requested that the data
points be grouped together by the common beginning or common ending of
their names.

Preview This section of the window displays a list of folders that Visual T&D created
based on your grouping criteria. When you open the different folders, you
will note that the binary points are displayed in blue and the analog points, in
green.

Table 3-5 Display Options window: Group Settings tab controls

Visual T&D Excel® Add-In User Guide • 15

EAS-SA QF-MKT-02 Rev.02

3.4.5 The Event Type Browser

To simplify the task of entering the function arguments, the Visual T&D Excel Add-In also
provides an Event Type Browser, which allows you to browse through the list of available event
types for each configured connection, and to select the event types to be inserted in the Excel
workbook. You can then refer to cells containing the event types as arguments for the various
functions.

To display the data point browser:

 From the Visual T&D menu, choose Event Type Browser.

Control Description
Available Displays the list of event types that are available on the selected connection.
connections

Insert top to bottom Inserts the list of Selected event types in a column, from top to bottom, starting
at the selected cell in the active workbook. Each event type name is placed in a
cell, based on its order of appearance in the list of selected points.

Insert left to right Inserts the list of Selected event types in a row, from left to right, starting at the
selected cell in the active workbook. Each event type name is placed in a cell,
based on its order of appearance in the list of selected points.

Filter All the names of the different event types that can be selected. If a group is
selected, Visual T&D Events for example, all event types of that group will be
selected.

Table 3-6 Select event type window controls

16 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

3.4.6 VssPtProp: Accessing the Properties of a Data Point

The VssPtProp function allows you to access the various data point properties. These properties
correspond to the different configuration settings (columns) in Visual T&D Explorer.
This function has the following arguments:

Argument Description
Data points The list of data point names for which the properties are being requested.
This argument is mandatory.

Display The display parameters, including the properties to be displayed.

This argument is mandatory.
The following parameters are supported in the current version:
Note: Refer to the Visual T&D Explorer User Manual for additional information about the
data point settings that correspond to these properties.

Supported for All Data Point Types

Name The data point name.

Source The name of the data source that provides the data point.

Description The data point description.

IsLogged Indicates if the value of the data point is to be logged.

Published Indicates if the Visual T&D server makes the point

available through a slave protocol component.

OPCPublished Indicates if the data point is available for OPC clients

through the Visual T&D OPC Data Access interface.

Event Indicates if transitions on the data point are to be recorded

as events by the Visual T&D server.

Alarm Indicates if transitions on the data point are to be handled

as alarms by the Visual T&D server.

Latched Indicates whether or not alarms related to the data point

remain in the alarm list when the value returns to normal,

ChimeBehavior Indicates the chime behavior for alarms related to the data
point.

ChimeDuration Indicates if the alarm chime is Temporary or Permanent

for alarms related to the data point.

BadQualityAlarm Indicates if a quality change is handled, or not, as an

alarm by the Visual T&D server for the data point.

AlarmDescription The description specified in the data point settings for

related alarms.

Priority The priority of alarms related to the data point.

Visual T&D Excel® Add-In User Guide • 17

EAS-SA QF-MKT-02 Rev.02

Argument Description
IOType The type of input or output.
Note: This property is used either for the Input Type or
Output Type settings, depending on the type of point.

AppearanceFilter The time that must elapse before an alarm is triggered.

DisappearanceFilter The time that must elapse before an alarm returns to

normal.

DetailFile The name of the corresponding detail file or a URL to

such file.

Zone The zone in which the data point is located, per the site
layout.

Addr-1 The value of the Addr-1 optional address setting.

Addr-2 The value of the Addr-2 optional address setting.

Addr-3 The value of the Addr-3 optional address setting.

IED The IED the data point is assigned to.

Region The Region the data point is assigned to.

Substation The Substation the data point is assigned to.

Function The Function the data point is assigned to.

Subfunction The Subfunction the data point is assigned to.

VoltageLevel The Voltage Level the data point is assigned to.

Bay The Bay the data point is assigned to.

Equipment The Equipment the data point is assigned to.

Column Requests that the data be displayed by column.

If you do not include this parameter, the data will be
displayed by row. This display parameter can be inserted
anywhere in the list of properties to be displayed.

Analog Specific

Type The type and size of the data point (ex. 16-bit signed).

Scale The multiplier used to convert a raw reading value to a

scaled value.

Offset The offset used to convert a raw reading value to a scaled

value.

Unit The units associated with the data point.

LowEGU The minimum value the analog data point can attain, in
engineering units.

18 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

Argument Description
HighEGU The maximum value the analog data point can attain, in
engineering units.

Deadband The minimum change, in engineering units, that must

occur on the data point for the change to be considered
significant.

LowerThreshold The value the analog data point must fall under to trigger
an alarm or event.

UpperThreshold The value the analog data point must exceed to trigger an
alarm or event.

Binary Specific

AlarmState Indicates which state of the binary data point is

considered to be an alarm condition.

BinaryType The type of binary point, between those defined in the

category settings of the site configuration, in Visual T&D
Explorer.

Binary Input Specific

InvertedPolarity Indicates if the binary input point state is inverted at the

Visual T&D server level.

Output Specific

ControlType The type of control operation that can be performed on

this output point.

MonitoringPoint The name of the input point which value is displayed in

control operation windows for this output point.

Connection The name of the connection to which the data points belong.
You can specify the name of the server computer or its IP address.
This argument is optional, unless the requested data points belong to 2 different
connections.

Table 3-7 VssPtProp function arguments

The following sections present some VssPtProp function usage examples.

3.4.6.1 Example 1: Displaying the Properties of a Data Point

In the following formula, the VssPtProp function is used to display the name, the unit and the
description of data point L225.AB:

=VssPtProp(A2, "Name, Description, Unit")

Visual T&D Excel® Add-In User Guide • 19

EAS-SA QF-MKT-02 Rev.02

The formula is typed in cell B2 and is automatically propagated to cells C2 and D2, since 3 fields
of information are requested.
The order of the display parameters determines the order in which the information is put into the
cells.

3.4.6.2 Example 2: Displaying the Properties of Multiple Data Points

In the following formula, the VssPtProp function is used to display the unit and description of
data points L226.AA, L226.AB and L226.AC.

=VssPtProp("L226.AA,L226.AB, L226.AC", "Unit, Description")

Data point names are entered directly in the formula.

The formula is typed in cell B2 and it was automatically propagated to array B2 through C4, since
2 fields of information are requested for 3 different data points.

3.4.6.3 Example 3: Displaying the Properties of Multiple Data Points by

Column
In the following formula, the VssPtProp function is used to display the same information as in
the previous example, but by column. References to cells B1 to D1 are made, rather than
specifying data point names directly in the formula:

=VssPtProp(B1:D1, "Column, Unit, Description")

3.4.7 VssPtList: Displaying a List of Points that Meet a Specific

Property Criterion
The VssPtList function allows you to display a list of data points that meet a specific property
criterion. The property corresponds to a data point setting (column) in Visual T&D Explorer.
This function has the following arguments:

20 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

Argument Description
Property The data point property to be used as the list filter criterion.
Supported properties are the same than for the VssPtProp function (see
“VssPtProp: Accessing the Properties of a Data Point”, page 17, for the
complete list of properties and the corresponding descriptions).
This argument is mandatory.

Value The value the specified property must take for a data point to be included in the
displayed list.
This argument is mandatory.

Connection The name of the connection to which the data points belong.
You can specify the name of the server computer or its IP address.
This argument is optional, unless the requested data points belong to 2 different
connections.

Table 3-8 VssPtList function arguments

The following section presents a VssPtList function usage example.

3.4.7.1 Example 1: Displaying the Name of Each Data Point that is Recorded
in the Data Log
In the following formula, the VssPtList function is used to display the name of each data point
that is recorded in the data log:

=VssPtList("IsLogged", 1)

The formula is typed in cell A2 and is automatically propagated to the cells under.

3.4.8 VssPtCurrVal: Accessing the Current Value of a Data Point

The VssPtCurrVal function allows you to access the information related to the current
(real­time) value of the data points.
This function has the following arguments:

Visual T&D Excel® Add-In User Guide • 21

EAS-SA QF-MKT-02 Rev.02

Argument Description
Data points The list of data point names for which the current values are being requested.
This argument is mandatory.

Display The display parameters, including the information to be displayed.

This argument is mandatory.
The following parameters are supported in the current version:

Name The data point name.

Value The engineering value for an analog point, or the state for a
binary point.

Quality The quality of the current value or state of the data point. If the
quality is good, a value of 1 is displayed. If the value is bad or
unsure, a value of 0 is displayed.

Time The timestamp of the current value or state of the data point.
The value is in local time and represents the time of the last
transition received for the data point.
You can specify the parameter twice, in order to display the
date in one cell and the time in another.

Ms The milliseconds of the timestamp.

Column Requests that the data be displayed by column.

If you do not include this optional parameter, the data will be
displayed by row.
The parameter can be inserted anywhere in the list.

Connection The name of the connection to which the data points belong.
You can specify the name of the server computer or its IP address.
This argument is optional, unless the requested data points belong to 2 different
connections.

Table 3-9 VssPtCurrVal function arguments

The following sections present some VssPtCurrVal function usage examples.

3.4.8.1 Example 1: Displaying the Current Value of a Data Point

In the following formula, the VssPtCurrVal function is used to display the name or a data
points, with its current quality and value, and the complete timestamp of this quality and value
including the date, the time (up to the seconds), and the milliseconds:

=VssPtCurrVal("L225.AA", "Name, Quality, Value, Time, Time, Ms")

22 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

The formula is typed in cell A2 and it was automatically propagated to cells B2 through F2, since
6 fields of information are requested.
The order of the display parameters determines the order in which the information is put into the
cells.
The Time parameter was entered twice in the formula, in order to put the date and time in 2
consecutive cells. Please note that cells D2 and E2 are formatted, since Excel had generated the
date and time in numerical format.

3.4.8.2 Example 2: Displaying the Current Value of Multiple Data Points

In the following formula, function VssPtCurrVal is used to display the quality, value and
timestamp of data points L225.AA, L225.AB and L225.AC.

=VssPtCurrVal(A2:A4, "Quality, Value, Time")

The formula is typed in cell B2 and it was automatically put into to cells B2 through D4, since 3
fields of information are requested for each of the 3 data points.

3.4.8.3 Example 3: Displaying the Current Value of Multiple Data Points by

Column
In the following formula, the VssPtCurrVal function is used to display the quality and value of
3 data points, by column.

=VssPtCurrVal(B1:D1, "Column, Quality, Value")

3.4.8.4 The VssCurrVal Function

This function is made available to provide compatibility with some old versions of the
Visual T&D Excel Add-In. You should use the VssPtCurrVal function unless you have an old
version of the add-in.
The arguments for this function are the same as those for the VssPtCurrVal function. The
Display parameter can take on the following values, in addition to those described for the
VssPtCurrVal function:

Argument Description
Display 0 Equivalent to entering "Value" as an argument.

1 Equivalent to entering "Value, Time" as arguments.

Visual T&D Excel® Add-In User Guide • 23

EAS-SA QF-MKT-02 Rev.02

Argument Description
2 Equivalent to entering "Value, Quality" as arguments.

3 Equivalent to entering "Value, Quality, Time" as arguments.

Table 3-10 VssCurrVal function arguments

3.4.9 VssPtArchVal: Accessing the History of a Data Point

The VssPtArchVal function allows you to obtain the list of transitions for one or more data
points over a given period of time.
The function can be inserted in a single cell or in a range of cells. The Visual T&D Excel Add-In
selects the range of cells required to display the requested information.
If you request data for a point that has no historical data, the cells that display the information for
the data point will show #NULL!.
This VssPtArchVal function has the following arguments:

Argument Description
Data points The list of data point names for which the transitions are being requested.
This argument is mandatory.
If the list contains multiple data points, the data for each point is grouped
together for the display.

Start Time Start time of the period for which the data is being requested.
This argument is mandatory.

End Time End time of the period for which the data is being requested.
This argument is mandatory.

Display The display parameters, including the information to be displayed.

This argument is mandatory.
The following parameters are supported in the current version:

Name The data point name.

Value The engineering value for an analog point, or the state for a
binary point.

Quality The quality of the current value or state of the data point.

Time The timestamp of the current value or state of the data point.

Ms The milliseconds of the timestamp.

Column Requests that the data be displayed by column.

If you do not include this parameter, the data will be displayed
by row. The parameter can be inserted anywhere in the list.

24 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

Argument Description
Bound Specifies whether the data at the beginning and end of the time range is to be
included (1) or excluded (0).
If no data exists at the bounding times, the next data outside of the range is
shown.
This argument is optional and has a default value of 0.

Maximum The maximum number of transitions requested for each data point.
A value of 0 specifies that the maximum number of transitions returned for each
data point is the limit imposed by the server.
This argument is optional and has a default value of 0.

Connection The name of the connection to which the data points belong.
You can specify the name of the server computer or its IP address.
This argument is optional, unless the requested data points belong to 2 different
connections.

Table 3-11 VssPtArchVal function arguments

The following sections present some VssPtArchVal function us5-01-age examples.

3.4.9.1 Example 1: Displaying the First 5 Transitions on a Data Point, for a

Particular Period
In the following formula, the VssPtArchVal function is used to display the first 5 transitions on
data point L228.PT:

=VssPtArchVal("L228.PT", A2, B2,"Name, Time, Ms, Value, Quality",

C2, D2)
The name, timestamp, timestamp milliseconds, value and quality fields are requested.

The order of the display parameters determines the order in which the information is put into the
cells.

3.4.9.2 Example 2: Displaying the First 3 Transitions on 3 Data Points, for a

Given Period
In the following formula, the VssPtArchVal function is used to display the first 3 transitions on
the L225.AA, L225.AB and L225.AC data points:

Visual T&D Excel® Add-In User Guide • 25

EAS-SA QF-MKT-02 Rev.02

=VssPtArchVal(A2:A4, B2, C2,"Name, Time, Ms, Value, Quality", D2,

E2)
The name, timestamp, timestamp milliseconds, value and quality fields are requested.

The order of the display parameters determines the order in which the information is put into the
cells.

3.4.10 VssPtCalcVal: Accessing Data Calculated from the History

of the Data Points
The VssPtCalcVal function allows you to obtain data that is calculated based on the history of
the transitions on one or more data points, for a given period of time and a specific sampling
interval.
This function can be inserted in a single cell or in a range of cells. The Visual T&D Excel Add-In
selects the range of cells required to display the requested information.
If you request data for a point that has no historical data, the cells that display the information for
the data point will show a value of 0.
The VssPtCalcVal function has the following arguments:

Argument Description
Data points The list of data point names for which the transitions are being requested.
This argument is mandatory.

Start Time Start time of the period for which the data is being requested.
This argument is mandatory.

End Time End time of the period for which the data is being requested.
This argument is optional.
If you do not specify an end time, the function returns all the available historical
data from the beginning of the period until the maximum number of transitions
is reached.

Display The display parameters, including the calculated values to be displayed.

This argument is mandatory.
The following parameters are supported in the current version:

26 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

Argument Description
Time The timestamp of the start of the sampling period.
If you include this parameter in the list, it is always put into the
first column/row of the display.

Name The data point name.

If you include this parameter in the list, it is always put to the
right of/under the timestamp (if included).

Column Requests that the data be displayed by column.

If you do not include this optional parameter, the data will be
displayed by row.

Average The average value of the data for each sampling interval. The
average is calculated based on the values interpolated at the
beginning and end of each interval.
This calculation is the mean column of the temporary database
used to create Crystal Reports reports.

Average The numeric representation of the quality of the average data

Quality for the sampling interval.
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Average The text associated with the quality of the average data for the
Quality sampling interval.
String

Integral The integral value of the data for each sampling interval.
This calculation is the integ column of the temporary
database used to create Crystal Reports reports.

Integral The numeric representation of the quality of the integral data

Quality for the sampling interval.
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Integral The text associated with the quality of the integral data for the
Quality sampling interval.
String

Interpolative The value interpolated at the beginning of each sampling

interval.

Interpolative The numeric representation of the quality of the interpolative

Quality data for the sampling interval.
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Interpolative The text associated with the quality of the interpolative data
Quality for the sampling interval.
String

Visual T&D Excel® Add-In User Guide • 27

EAS-SA QF-MKT-02 Rev.02

Argument Description
Maximum The maximum value for each sampling interval.
This calculation is the max column of the temporary database
used to create Crystal Reports reports.

Maximum The numeric representation of the quality of the maximum

Quality good raw data for the sampling interval.
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Maximum The text associated with the quality of the maximum good raw
Quality data for the sampling interval.
String

Maximum The time of the data item that has the maximum value for each
Actual Time sampling interval.
This calculation is the tMax column of the temporary database
used to create Crystal Reports reports.

Maximum The numeric representation of the quality of the time of the

Actual Time data that has the maximum value for the sampling interval.
Quality
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Maximum The text associated with the quality of the time of the data that
Actual Time has the maximum value for the sampling interval.
Quality
String

Maximum The milliseconds of the time of the data item that has the
Actual Time maximum value for each sampling interval.
Ms

Minimum The minimum value for each sampling interval.

This calculation is the min column of the temporary database
used to create Crystal Reports reports.

Minimum The numeric representation of the quality of the minimum

Quality good raw data for the sampling interval.
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Minimum The text associated with the quality of the minimum good raw
Quality data for the sampling interval.
String

Minimum The time of the data item that has the minimum value for each
Actual Time sampling interval.
This calculation is the tMin column of the temporary database
used to create Crystal Reports reports.

28 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

Argument Description
Minimum The numeric representation of the quality of the time of the
Actual Time data that has the minimum value for the sampling interval.
Quality
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Minimum The text associated with the quality of the time of the data that
Actual Time has the minimum value for the sampling interval.
Quality
String

Minimum The milliseconds of the time of the data item that has the
Actual Time minimum value for each sampling interval.
Ms

Standard The standard deviation for all the data included in each
Deviation sampling interval.
This calculation is the std column of the temporary database
used to create Crystal Reports reports.

Standard The numeric representation of the quality of the standard

Deviation deviation data for the sampling interval.
Quality
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Standard The text associated with the quality of the standard deviation
Deviation data for the sampling interval.
Quality
String

Sum of The sum of the decrements for all the data included in each
decrements sampling interval.
This calculation is the decr column of the temporary database
used to create Crystal Reports reports.

Sum of The numeric representation of the quality of the sum of

decrements decrements for all the data for the sampling interval.
Quality
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Sum of The text associated with the quality of the sum of decrements
decrements for all the data for the sampling interval.
Quality
String

Sum of The sum of the increments for all the data included in each
increments sampling interval.
This calculation is the incr column of the temporary database
used to create Crystal Reports reports.

Sum of The numeric representation of the quality of the sum of

increments increments for all the data for the sampling interval.
Quality
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Visual T&D Excel® Add-In User Guide • 29

EAS-SA QF-MKT-02 Rev.02

Argument Description
Sum of The text associated with the quality of the sum of increments
increments for all the data for the sampling interval.
Quality
String

Transitions The number of transitions that occurred on this point for the
Quantity specified period.

Transitions The numeric representation of the quality of each transition.

Quantity
Quality For additional information about quality values, see
“Displayed Quality Values”, page 31.

Transitions The text associated with the quality of the transitions.

Quantity
Quality
String

Variance The variance of the values included in each sampling interval.

Variance The numeric representation of the quality of the variance for

Quality the sampling interval.
For additional information about quality values, see
“Displayed Quality Values”, page 31.

Variance The text associated with the quality of the variance for the
Quality sampling interval.
String

End The last valid value in each sampling interval.

End Quality The text associated with the quality of the last value for the
String sampling interval.

Interval: Count The number of units of the sampling interval.

This argument is mandatory.

Interval: Units The units of the sampling interval.

This argument is mandatory and can take the following values:

Seconds The interval is specified in seconds.

Minutes The interval is specified in minutes.

Hours The interval is specified in hours.

Days The interval is specified in days.

Connection The name of the connection to which the data points belong.
You can specify the name of the server computer or its IP address.
This argument is optional, unless the requested data points belong to 2 different
connections.

Table 3-12 VssPtCalcVal function arguments

30 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

3.4.10.1 Displayed Quality Values

The VssPtCalcVal function includes, as parameters of its Display argument, quality value
fields that give additional information about the values that are displayed using this function. For
example, if this function is used to retrieve the minimum value, it can also provide the quality of
this minimum value.
A Visual T&D quality value is a 32-bit hexadecimal number that results from the combination of
multiple quality attribute values added together. For example, a quality value of 0x00020040,
which is the sum of 0x00020000 and 0x00000040, means that the corresponding value is
respectively “interpolated” and “uncertain”.

Note: Quality values are expressed as decimal numbers in Excel. However, working
with hexadecimal numbers makes it easier to decode the quality attributes that
compose the value.

To transform a decimal value into a hexadecimal value in Excel, use the

DEC2HEX formula.

The following tables presents the quality attributes that can appear in a quality value:

Bad Quality Attributes Description

0x00000000 Bad Quality

0x00000004 Configuration Error

0x00000008 Not Connected

0x0000000C Device Failure

0x00000010 Sensor Failure

0x00000014 Last Known

0x00000018 Communication Failure

0x0000001C Out of Service

0x00000020 Waiting for initial data

Table 3-13 Bad quality attributes

Uncertain Quality Description

Attributes
0x00000040 Uncertain

0x00000044 Last Usable

0x00000050 Sensor Cal

0x00000054 EGU Exceeded

0x00000058 Subnormal

Table 3-14 Uncertain quality attributes

Visual T&D Excel® Add-In User Guide • 31

EAS-SA QF-MKT-02 Rev.02

Good Quality Attributes Description

0x000000C0 Good

0x000000D8 Local Override

Table 3-15 Good quality attributes

Additional Quality Description

Attributes
0x00010000 Extra Data

0x00020000 Interpolated

0x00040000 Raw

0x00080000 Calculated

0x00100000 No Bound

0x00200000 No Data

0x00400000 Data Lost

0x00800000 Conversion

0x01000000 Partial

Table 3-16 Additional quality attributes

3.4.10.2 Example 1: Displaying Calculated Values for a Data Point over a

Given Period, with a One-Hour Sampling Interval
In the following formula, the VssPtCalcVal function is used to display the average, minimum
and maximum (including the timestamps) values stored in the historical database of data point
L225.AA, for each one-hour interval from midnight through 6 pm:

=VssPtCalcVal("L225.AA", A2, B2, "Time, Name, Average, Minimum,

Minimum Actual Time, Maximum, Maximum Actual Time", C2, D2)

32 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

3.4.10.3 Example 2: Displaying Calculated Values for 2 Data Points over a 5-

Minute Period, with a 1-Minute Sampling Interval
In the following formula, the VssPtCalcVal function is used to display the integral, the sum of
the increments, and the variance of the values stored in the historical database for points L226.AA
and L226.AB, for each one-minute interval over a 5-minute period:

=VssPtCalcVal("L225.AA, L225.AB", A2, B2,"Time, Name, Integral,

Sum of Increments, Variance", C2, D2)

3.4.11 VssAlarmAndEvent: Accessing the Alarm and Event

History
The VssAlarmAndEvent function allows you to obtain the list of alarms and events for one or
more type of events and one or more data points, for a given period of time and a specific
sampling interval.
This function can be inserted in a single cell or in a range of cells. The Visual T&D Excel Add-In
selects the range of cells required to display the requested information.
If you request data for an event types or a point that has no historical event log, the cells that
display the information for the event will show a value of #NULL!.

Visual T&D Excel® Add-In User Guide • 33

EAS-SA QF-MKT-02 Rev.02

The VssAlarmAndEvent function has the following arguments:

Argument Description
Start Time Start time of the period for which the data is being requested.
This argument is mandatory.

End Time End time of the period for which the data is being requested.
This argument is mandatory.

Display The display parameters, including the calculated values to be displayed.

This argument is mandatory.
The following parameters are supported in the current version:

Name The data point name.

Description The description of the event.

Value The engineering value for an analog point, or the state for a
binary point.

Time The timestamp of the current value or state of the data point.

Ms The milliseconds of the timestamp.

Note The note associated to the event or the point of the event.

Reference The reference associated to the event when it is a user log

event.

Column Requests that the data be displayed by column.

If you do not include this optional parameter, the data will be
displayed by row.
The parameter can be inserted anywhere in the list.

Maximum The maximum number of events returned from the server.

A value of 0 specifies that all events are returned.
This argument is optional and has a default value of 0.

Alarms only Indicates if only alarms (1) are returned or if all events are (0).
This flag is effective only for event of the Process-related events type.
This argument is optional and has a default value of 0.

All event types Indicates if all events types must be included (1) or only those specified (0).
This argument is optional and has a default value of 0.

Event types List of the events type to be returned by the request.

This argument is not considered if All event types is set to 1.
Otherwise, this argument is mandatory.

All data points Indicates if all data points (1) are returned or only those specified (0).

34 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

Argument Description
This argument is optional and has a default value of 0.

Data points List of the data points to be considered in the request. Events not related to a
point will ignore this argument.
This argument is not considered if All data points is set to 1.
Otherwise, this argument is mandatory.

Connection The name of the connection to which the request will be sent.
You can specify the name of the server computer or its IP address.
This argument is optional, unless the application is connected to 2 or more
server.

Table 3-17 VssAlarmAndEvent function arguments

3.4.11.1 Example: Displaying the First 5 Events that Occurred at a Given Date
In the following formula, the VssAlarmAndEvent function is used to display the 5 first events
that occurred at a given date:

=VssAlarmAndEvent(B1, B2, "Name, Description, Value, Time,

Ms",5,,1,,1)
All event types and data points will be considered. The following fields are returned: name,
description, timestamp, timestamp milliseconds and value.

The order of the display parameters determines the order in which the information is put into the
cells.

3.4.12 Updating the Data

To avoid overloading the Visual T&D servers with numerous requests for access to cyclical data,
the standard Excel worksheet update mechanisms do not allow you to update the Visual T&D
data. However, if you modify some cells that are used as references for Visual T&D functions,
data is updated automatically.
The Visual T&D Excel Add-In provides 3 commands for updating the Visual T&D function data.

Visual T&D Excel® Add-In User Guide • 35

EAS-SA QF-MKT-02 Rev.02

3.4.12.1 Updating all the Data

The Update All Data command launches an update of all the cells in the workbook that refer to a
Visual T&D function.

To update all the data:

 In the Visual T&D menu, click Update All Data.

3.4.12.2 Updating the Real-Time Data

The Update Real-Time Data command launches an update of all the cells in the workbook that
refer to a function that accesses real-time Visual T&D data.

To update the real-time data:

 In the Visual T&D menu, click Update Real-Time Data.

3.4.12.3 Updating the Historical Data

The Update Historical Data command launches an update of all the cells in the workbook that
refer to a function that accesses historical Visual T&D data.

To update the historical data:

 In the Visual T&D menu, click Update Historical Data.

36 ● Chapter 3: Accessing the data

 EAS-SA QF-MKT-02 Rev.02

4 Creating a Report Template

Microsoft Excel allows you to create report templates that you can use to generate periodic
reports, without altering the template. Report templates are stored in files with an XLTX (or XLT)
extension.
The Visual T&D Excel Add-In provides additional functions to help you create your report
models.

4.1 Creating a Report Template

Creating an Excel report model simply entails saving a workbook to the Excel Template format
(XLTX or XLT).
For information regarding the use of Excel templates, consult the Microsoft Excel online help.

4.2 Generating a Report from a Template

To generate a report based on a model, you must simply update the report data and save the report.

To generate a report from a template:

 In Windows Explorer, double-click on the template file (XLTX or XLT).

Excel automatically creates a new workbook based on the template.

 Make sure the Suspend the execution of the functions command of the Visual T&D menu
does not show a checkmark (see “Suspending the Execution of Visual T&D Functions”,
page 11).
 From the Visual T&D menu, choose Update All Data.
 When the update is done, save the document by choosing the Save from the File menu.

Excel will ask you to assign a name to the workbook (you cannot modify the model this way).
 From the Visual T&D menu, choose Remove All Formulas, and save the document again.

This will ensure that when someone subsequently opens the file, the report data will remain as
it was when you saved it, rather than being updated with new information from the server.

Visual T&D Excel® Add-In User Guide • 37

 EAS-SA QF-MKT-02 Rev.02

5 Automating Report
Generation

You can easily automate the generation of your reports, based on the templates you create.
Reports can be generated on a periodic basis, or when a specific event occurs. In both cases, a
Visual Basic for Applications (VBA) script must be used specifically for the generation. The
difference between both methods is how and when the script will be executed.
The periodic execution of a script can be planned using Windows’ scheduled tasks or Visual T&D
Explorer’s Task Manager. Event-triggered report generation should be automated using
Visual T&D Explorer’s Task Manager.
The most interesting feature of event-triggered report generation is the possibility to use the trigger
time to specify the range of data to include in the report. For example, an operator may be
interested to know the sequence of events that occurred 15 minutes prior to a breaker trip event,
and 5 minutes after. This is feasible using event-triggered report generation.
This chapter outlines the steps required to automate the generation of a report.

5.1 Creating the Report Generation Script

The first step consists in creating a VBA script (.VBS file) that interacts with Microsoft Excel to:
 open the report model;
 update the worksheet and the Visual T&D data;
 and save a static copy of the report in a location of your choice.

5.1.1 Using the Trigger Time in Scripts and Report Templates

When the script execution is triggered by an event, you can pass the trigger time to the script as an
argument, and thus refer to the trigger time in your report model to include data preceding and
following the triggering-event occurrence.
The script has the responsibility to set the trigger time using the VssSetTriggerTime function
for further uses by Excel Add-In function calls found in the report template. The trigger time is
obtained via a call to VssGetTriggerTime function.
Both trigger time functions are described in details below.

Visual T&D Excel® Add-In User Guide • 39

EAS-SA QF-MKT-02 Rev.02

5.1.1.1 VssSetTriggerTime VBA Function

Note: This is a Visual T&D-specific VBA function. It is not available in Excel, but it can
be used in scripts.

The VssSetTriggerTime function is used to set the trigger date and time in a script prior to
calls to the VssGetTriggerTime function. Your script should take the trigger time as an
argument, or should know how to retrieve the trigger time by itself.
The VssSetTriggerTime function has the following arguments:

Argument Description
Trigger Time The date and time at which the event triggered the report generation.
This argument is mandatory.

Is Local Indicates if the trigger time should be interpreted by Excel as UTC time (0) or
local time (1).
This argument is mandatory.

Table 5-1 VssSetTriggerTime VBA function arguments

5.1.1.2 VssGetTriggerTime Function

The VssGetTriggerTime function is used to retrieve the trigger date and time as set by the
VssSetTriggerTime function.
The VssGetTriggerTime function should be used as an argument for other Excel Add-In
functions, such as VssPtArchVal and VssPtCalcVal, in a report template. The report
template can then be used in a script as the template for the generated report.
The VssGetTriggerTime function has the following arguments:

Argument Description
Display The display parameters, including the information to be displayed.
This argument is optional.
The following parameters are supported in the current version:

Date and Get the trigger date and time as set by VssSetTriggerTime.
Time
Milliseconds must be obtained via a second call, using the Ms
argument (see below).

Ms Get the trigger time milliseconds.

Table 5-2 VssGetTriggerTime function arguments

5.1.1.3 Example
In a report model, to display L226.AA point transitions that were recorded 3 hours (0.125 of a
day) prior to the event, you should type the following formula in a cell:

=VssPtArchVal(B1, VssGetTriggerTime()-0.125, VssGetTriggerTime(),

"Time, Value, Quality", 0)

40 ● Chapter 5: Automating Report Generation

 EAS-SA QF-MKT-02 Rev.02

As requested, the timestamp, value and quality of each transition are displayed in separate
columns. Please note that column A is formatted since Excel generates the date and time in
numerical format.

5.1.2 Managing the Server Connection through Script

By default, scripting requires that the Excel Add-In connection to the Visual T&D server be
always active in Excel, even if the user works with Excel for other purposes.
The Visual T&D Excel Add-In provides a set of VBA functions that may be invoked in scripts to
establish a connection, verify if one is already established, or to terminate it.

5.1.2.1 VssIsConnected VBA Function

Note: This is a Visual T&D-specific VBA function. It is not available in Excel, but it can
be used in scripts.

The VssIsConnected function is used to verify if a connection between the Visual T&D Excel
Add-In and the Visual T&D server is currently active, or not, through script execution.
The VssIsConnected function has the following arguments and return values:

Argument Description
Name The name of the connection, as specified in the Excel Add-In Connections
window.
This argument is mandatory.

Table 5-3 VssIsConnected VBA function arguments

Return Value Description

1 The connection is currently active.

Visual T&D Excel® Add-In User Guide • 41

EAS-SA QF-MKT-02 Rev.02

Return Value Description

-1 The connection is deactivated (disabled).

Table 5-4 VssIsConnected VBA return values

5.1.2.2 VssConnect VBA Function

Note: This is a Visual T&D-specific VBA function. It is not available in Excel, but it can
be used in scripts.

The VssConnect function is used to establish a connection between the Visual T&D Excel
Add-In and the Visual T&D server through script execution, even if this connection is deactivated
in the Visual T&D Excel Add-In.
The VssConnect function has the following arguments and return values:

Argument Description
Name The name of the connection, as specified in the Excel Add-In Connections
window.
This argument is mandatory.

Table 5-5 VssConnect VBA function arguments

Return Value Description

1 The connection was successfully established.

-1 The connection could not be established for an unknown reason.

-2 No connection of this name is currently configured in the Visual T&D Excel

Add-In.

-3 The connection could not be established because the maximum number of users
allowed by the Visual T&D license was reached.

-4 The connection could not be established because the server cannot be reached.

-5 The connection could not be established before the expiration of the connection
timer.

-6 The connection could not be established because the password provided at

configuration time for this connection is no longer valid.

-7 The connection could not be established because the current license of the
Visual T&D server to connect is not valid.

Table 5-6 VssConnect VBA return values

5.1.2.3 VssDisconnect VBA Function

Note: This is a Visual T&D-specific VBA function. It is not available in Excel, but it can
be used in scripts.

42 ● Chapter 5: Automating Report Generation

 EAS-SA QF-MKT-02 Rev.02

The VssDisconnect function is used to terminate a connection between the Visual T&D Excel
Add-In and the Visual T&D server through script execution.
The VssDisconnect function has the following arguments and return values:

Argument Description
Name The name of the connection, as specified in the Excel Add-In Connections
window.
This argument is mandatory.

Table 5-7 VssDisconnect VBA function arguments

Return Value Description

1 The connection was successfully terminated.

-1 The connection could not be terminated, or no configuration of this name is

currently configured in the Visual T&D Excel Add-In.

Table 5-8 VssDisconnect VBA return values

5.1.3 Creating the Script

You can use the example file installed with Excel Add-In to create a custom script file to generate
your reports. The file is provided with the Visual T&D product documentation and is called
Excel Report - Automatic Generator.vbs.
The script it contains requires up to 4 parameters to generate a report from a template:
 The name and path of the template to be used.
 The path of the folder in which the report is to be stored.
 The name of the output file.
 The trigger time. This parameter is optional and used for event-triggered report generation
(see “Using the Trigger Time in Scripts and Report Templates”, page 39 for more details).

Note: The script shown adds the date and time of the report generation to the output
file name, in order to avoid overwriting the same file each time the report is
generated.

To create the report generation script:

 Save the example file under a name of your choice with a VBS extension.

5.1.4 Testing the Script

To verify that your script is working:
 Open a command prompt window.
 Run the script by typing the following command:

wscript <script name> <template name> <destination path> <output file name>

Visual T&D Excel® Add-In User Guide • 43

EAS-SA QF-MKT-02 Rev.02

Example:

wscript "D:\Reports\my script.vbs" "D:\Reports\Template 1.xlt"

"D:\Reports\Output\" "Report 1.xls"
 Make sure the report was indeed generated in the destination folder.

Note: If you experience any problems with script files, feel free to contact our technical
support (see page 2). However, the script should work if you follow the preceding
instructions carefully.

5.2 Scheduling a Periodic Report Generation

Once your script file is ready, you can have Windows request a periodic generation of your report,
using Windows’ scheduled tasks.

To schedule the generation of a report:

 Click start, then Control Panel, then System and Security; under Administrative Tools,
click Schedule tasks.
 In the Actions pane of the Task Scheduler window, click Create Task.

 In the General tab, type a Name for the task to schedule and enter a short Description for it.
 Under Security Options:
 Select Run whether user is logged or not.
 By default, the user account that creates the task is assigned to it; you can change the
account using the Change User or Group button.
 Select the Triggers tab, and then click New.

44 ● Chapter 5: Automating Report Generation

 EAS-SA QF-MKT-02 Rev.02

 Specify when the task should be executed, and then click OK.
 Select the Actions tab, and then click New.

 In the Action box, select Start a program.

Visual T&D Excel® Add-In User Guide • 45

EAS-SA QF-MKT-02 Rev.02

 Under Settings:
 Click Browse, and locate wscript.exe, which normally resides in the
.\WINDOWS\system32\ folder of your hard disk; click Open once the file is
selected.
 In the Add arguments (optional) box, type the following arguments:

<script name> <template name> <destination path> <output file name>

Ex. "C:\Reports\my script.vbs" "C:\Reports\Template 1.xlt"

"C:\Reports\Output\" "Report 1.xls"
 In the Start in (optional) box, enter the name of the folder where the wscript.exe
file is located.
 Click OK.
 Select the Settings tab.

 Adjust the additional task behavioral settings as required.

For example, you can stop the task if it runs longer than a certain time.
 Click OK.

The task appears in the Task Scheduler list and should now be performed as scheduled.

5.3 Creating an Event-Triggered Task to Generate

Reports
Visual T&D Explorer’s Task Manager allows a user to create event-triggered tasks. These tasks
can create simple reports, but can also launch application or scripts.

46 ● Chapter 5: Automating Report Generation

 EAS-SA QF-MKT-02 Rev.02

For example, a user may want to automate the generation of a report when a breaker opens. The
report would contain all transitions and the sequence of events prior, and after, the breaker event.
This is made possible using the Task Manager, by creating a task that executes a report-
generation VBA script. This task must then be configured to be triggered by the breaker’s opening
event.
Task management is explained more in details in the Visual T&D Explorer User Manual.

Visual T&D Excel® Add-In User Guide • 47

 EAS-SA QF-MKT-02 Rev.02

6 Tips and Tricks

This chapter presents a few tricks and tips to make it easier for you to use the Visual T&D Excel
Add-In, and to create reports and templates.

6.1 The TODAY Function

This Microsoft Excel function, which is part of the broader Date and Time function, displays
today's date and time. You can use the function to create a daily report template. Simply refer to
the cell in which you have placed the TODAY function call, in order to specify the interval for
which you want to obtain the data.
You can add or subtract a number of days to or from the result of the function, in order to obtain
the interval for today, yesterday, and so on.

6.2 The NOW Function

This Microsoft Excel function, which is part of the broader Date and Time function, displays the
current date and time. You can use the function to create a report template in which you refer to
the function to indicate the report generation date.
However, you should avoid using the result of this function as an argument for Visual T&D
functions. Each time Excel updates a worksheet, all formulas that refer to cells containing the
NOW function call are transmitted as requests to the Visual T&D server. Furthermore, the
Visual T&D Excel Add-In forces an update of the worksheet whenever the results are ready for
display. This situation could potentially lead to an avalanche of updates.

6.3 Limitations and Known Problems

This section presents the limitations and known problems of the Visual T&D Excel Add-In.

6.3.1 Excel Worksheet Limitations

Worksheets are limited to 65,535 rows and 256 columns. If a data access function needs to exceed
these limits in order to display all the results, the cell in which you entered the function will show
#Cannot display.

Visual T&D Excel® Add-In User Guide • 49

EAS-SA QF-MKT-02 Rev.02

6.3.2 Merge & Center Function

Using Excel’s Merge & Center function, which you access via the Formatting toolbar ( , in
Excel 2003) or the Home ribbon’s Alignment group ( , in Excel 2007/2010 or
later), can cause problems with Visual T&D functions.
To avoid problems using this function, make sure you do not merge two cells containing
Visual T&D functions. Furthermore, do not use more than one Visual T&D function in a given
formula, except for the VssGetTriggerTime function that may be used as an argument to
another function (see “VssGetTriggerTime”, page 40).

6.3.3 Loss of Selection after a Data Update

The data update mechanisms of the Visual T&D Excel Add-In can sometimes cause the current
cell to be deselected. This problem is an irritant but does not cause any damage or loss of data.

50 ● Chapter 6: Tips and Tricks