Quindar SCADA
Interface to the PI System
Version 2.0.2.0
Revision C
How to Contact Us
OSIsoft, Inc.
Worldwide Offices
777 Davis St., Suite 250
OSIsoft Australia
San Leandro, CA 94577 USA
Perth, Australia
Auckland, New Zealand
Telephone
(01) 510-297-5800 (main phone)
OSI Software GmbH
Altenstadt, Germany
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
OSI Software Asia Pte Ltd.
Singapore
techsupport@osisoft.com
OSIsoft Canada ULC
Montreal, Canada
Houston, TX
Johnson City, TN
Mayfield Heights, OH
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
Phoenix, AZ
OSIsoft Japan KK
Savannah, GA
Tokyo, Japan
Seattle, WA
OSIsoft Mexico S. De R.L. De C.V.
Yardley, PA
Mexico City, Mexico
Sales Outlets and Distributors
 Brazil
 South America/Caribbean
 Middle East/North Africa
 Southeast Asia
 Republic of South Africa
 South Korea
 Russia/Central Asia
 Taiwan
WWW.OSISOFT.COM
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI
ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book
that are known to be trademarks or service marks have been appropriately capitalized. Any trademark
that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein
in no way indicates an endorsement, recommendation, or warranty of such party’s products or any
affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in
subparagraph I(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS
252.227-7013
Unpublished – rights reserved under the copyright laws of the United States.
© 2001-2008 OSIsoft, Inc.
ii
PI_Quindar.doc
Table of Contents
Terminology ................................................................................................................ vii
Introduction ................................................................................................................... 1
Reference Manuals ..................................................................................................... 1
Supported Features ..................................................................................................... 1
Diagram of Hardware Connection ............................................................................... 5
QUICS IV and Windows SCADA Differences .............................................................. 5
DLL Names .............................................................................................................. 5
SCADA Station and Tag Names .............................................................................. 5
Maximum Point Counts ............................................................................................ 6
Starting Point Numbers ............................................................................................ 6
Analog Value Format ............................................................................................... 6
Principles of Operation ................................................................................................ 7
Installation Checklist .................................................................................................. 11
Interface Installation ................................................................................................... 13
Naming Conventions and Requirements ................................................................... 13
Interface Directories .................................................................................................. 14
PIHOME Directory Tree ......................................................................................... 14
Interface Installation Directory. .............................................................................. 14
Interface Installation Procedure ................................................................................. 14
Installing Interface as a Windows Service ................................................................. 14
Installing Interface Service with PI ICU .................................................................. 15
Installing Interface Service Manually ...................................................................... 17
PICheckNda Connection Test Utility ......................................................................... 19
Define OMS Record Tags ........................................................................................... 21
Digital States ............................................................................................................... 23
PointSource ................................................................................................................. 25
Quindar SCADA Interface to the PI System
iii
iii
Table of Content
PI Point Configuration ................................................................................................ 27
Point Attributes .......................................................................................................... 27
Tag ........................................................................................................................ 27
PointSource ........................................................................................................... 27
PointType .............................................................................................................. 27
Location1 ............................................................................................................... 28
Location2 ............................................................................................................... 28
Location3 ............................................................................................................... 28
Location4 ............................................................................................................... 28
Location5 ............................................................................................................... 28
InstrumentTag ....................................................................................................... 28
ExDesc .................................................................................................................. 29
Scan ...................................................................................................................... 30
Shutdown ............................................................................................................... 31
Output Points............................................................................................................. 31
Trigger Method 1 (Recommended) ........................................................................ 31
Trigger Method 2 ................................................................................................... 32
Performance Point Configuration .............................................................................. 33
Configuring Performance Points with PI ICU (Windows) ........................................... 33
Configuring Performance Points Manually ................................................................. 34
I/O Rate Tag Configuration......................................................................................... 37
Monitoring I/O Rates on the Interface Node .............................................................. 37
Configuring I/O Rate Tags with PI ICU (Windows) .................................................... 37
Configuring I/O Rate Tags Manually .......................................................................... 39
Configuring PI Point on the PI Server .................................................................... 39
Configuration on the Interface Node ...................................................................... 39
Startup Command File ................................................................................................ 41
Configuring the Interface with PI ICU ........................................................................ 41
General Parameters Tab ........................................................................................... 43
Quindar Hosts Tab .................................................................................................... 45
Command-line Parameters ........................................................................................ 46
Sample PIQuindar.bat File......................................................................................... 50
UniInt Failover Configuration ..................................................................................... 51
Introduction ............................................................................................................... 51
iv
Failover Installation Checklist .................................................................................... 51
Startup Command File Configuration......................................................................... 54
Sample Interface Startup Files ............................................................................... 56
Data Source Failover Control Point Configuration ..................................................... 56
Active ID ................................................................................................................ 57
Heartbeat ............................................................................................................... 57
Control Point Data Flow ......................................................................................... 58
Procedure for Configuring Failover Points on SCADA Hosts ................................. 58
PI Failover Control Tag Configuration........................................................................ 66
Active ID ................................................................................................................ 67
Heartbeat ............................................................................................................... 67
Interface State Tag .................................................................................................... 68
Interface State Tag Configuration .......................................................................... 69
Digital State Configuration ..................................................................................... 69
Failover Configuration Using the PI ICU .................................................................... 70
Create the Interface Instance with the ICU ............................................................ 70
Configure the Failover Startup Parameters ............................................................ 70
Create the Failover State Digital State Set ............................................................. 71
Create the Failover Control and Failover State Tags ............................................. 72
Importing Failover Digital Set to PI via PI SMT 3 ................................................... 73
Messages .................................................................................................................. 75
Informational .......................................................................................................... 75
Errors ..................................................................................................................... 76
Interface Node Clock .................................................................................................. 79
Windows.................................................................................................................... 79
Security ..................................................................................................................... 81
Windows.................................................................................................................... 81
Starting / Stopping the Interface on Windows .......................................................... 83
Starting Interface as a Service .................................................................................. 83
Stopping Interface Running as a Service ................................................................... 83
Buffering ...................................................................................................................... 85
Which Buffering Application to Use ........................................................................... 85
How Buffering Works ................................................................................................ 86
Buffering and PI Server Security ............................................................................... 86
Quindar SCADA Interface to the PI System
v
Table of Content
Enabling Buffering on an Interface Node with the ICU ............................................... 87
Choose Buffer Type ............................................................................................... 87
Buffering Settings .................................................................................................. 88
Buffered Servers .................................................................................................... 91
Installing Buffering as a Service ............................................................................. 93
Appendix A: Error and Informational Messages ....................................................... 97
Message Logs ........................................................................................................... 97
Messages .................................................................................................................. 97
System Errors and PI Errors .................................................................................... 102
Revision History........................................................................................................ 103
vi
Terminology
In order to understand this interface manual, you should be familiar with the terminology
used in this document.
Buffering
Buffering refers to an Interface Node’s ability to store temporarily the data that
interfaces collect and to forward these data to the appropriate PI Servers.
N-Way Buffering
If you have PI Servers that are part of a PI Collective, PIBufss supports n-way
buffering. N-way buffering refers to the ability of a buffering application to send
the same data to each of the PI Servers in a PI Collective. (Bufserv also supports
n-way buffering to multiple PI Server however it does not guarantee identical
archive records since point compressions specs could be different between PI
Servers. With this in mind, OSIsoft recommends that you run PIBufss instead.)
ICU
ICU refers to the PI Interface Configuration Utility. The ICU is the primary application
that you use in order to configure and run PI interface programs. You must install the
ICU on the same computer on which an interface runs. A single copy of the ICU
manages all of the interfaces on a particular computer.
You can configure and run an interface by editing a startup command file. However,
OSIsoft discourages this approach. Instead, OSIsoft strongly recommends that you use
the ICU for interface management tasks.
ICU Control
An ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common
to all interfaces, an ICU Control implements interface-specific behavior. Most PI
interfaces have an associated ICU Control.
Interface Node
An Interface Node is a computer on which

the PI API and/or PI SDK are installed, and

PI Server programs are not installed.
PI API
The PI API is a library of functions that allow applications to communicate and exchange
data with the PI Server. All PI interfaces use the PI API.
PI Collective
A PI Collective is two or more replicated PI Servers that collect data concurrently.
Collectives are part of the High Availability environment. When the primary PI Server in
Quindar SCADA Interface to the PI System
vii
vii
Terminology
a collective becomes unavailable, a secondary collective member node seamlessly
continues to collect and provide data access to your PI clients.
PIHOME
PIHOME refers to the directory that is the common location for PI client applications. A
typical PIHOME is C:\Program Files\PIPC. PI interfaces reside in a subdirectory of
the Interfaces directory under PIHOME. For example, files for the Modbus Ethernet
Interface are in C:\Program Files\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME directory.
For example, ICU files in [PIHOME]\ICU.
PI SDK
The PI SDK is a library of functions that allow applications to communicate and
exchange data with the PI Server. Some PI interfaces, in addition to using the PI API,
require the use of the PI SDK.
PI Server Node
A PI Server Node is a computer on which PI Server programs are installed. The PI Server
runs on the PI Server Node.
PI SMT
PI SMT refers to PI System Management Tools. PI SMT is the program that you use for
configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT
runs on either a PI Server Node or a PI Interface Node.
Pipc.log
The pipc.log file is the file to which OSIsoft applications write informational and error
messages. While a PI interface runs, it writes to the pipc.log file. The ICU allows easy
access to the pipc.log.
Point
The PI point is the basic building block for controlling data flow to and from the PI
Server. For a given timestamp, a PI point holds a single value.
A PI point does not necessarily correspond to a “point” on the foreign device. For
example, a single “point” on the foreign device can consist of a set point, a process
value, an alarm limit, and a discrete value. These four pieces of information require four
separate PI points.
Service
A Service is a Windows program that runs without user interaction. A Service continues
to run after you have logged off from Windows. It has the ability to start up when the
computer itself starts up.
The ICU allows you to configure a PI interface to run as a Service.
viii
Tag (Input Tag and Output Tag)
The tag attribute of a PI point is the name of the PI point. There is a one-to-one
correspondence between the name of a point and the point itself. Because of this
relationship, PI System documentation uses the terms “tag” and “point” interchangeably.
Interfaces read values from a device and write these values to an Input Tag. Interfaces
use an Output Tag to write a value to the device.
Quindar SCADA Interface to the PI System
ix
Introduction
This document describes OSIsoft’s Quindar Interface to the Plant Information (PI)
System (PI Quindar). The PI Quindar Interface provides connectivity to Survalent
Technology’s (previously Quindar Products Ltd) SCADA System.
The PI Quindar Interface is distributed in two versions. The first interfaces with the
Survalent QUICS IV VMS-based SCADA system and the second interfaces to the
Windows-based SCADA Server. The operation of each of these is virtually identical.
Differences between the two versions are spelled out in the section titled QUICS IV and
Windows SCADA Differences later in the manual. Additionally, any references herein to
SCADA System can be assumed to apply to both. The terms VMS SCADA and
Windows SCADA will be used herein when something is specific to a particular version
of the interface.
The PI Quindar Interface provides bi-directional transfer of Analog Status data between
the SCADA System and the PI Server via the Quindar Network Database Access (Nda)
API Library. The interface also supports input of Operator Message
Reference Manuals
OSIsoft

PI Server manuals

PI API Installation manual

UniInt Interface User Manual
Vendor

Network Database Access API User’s Guide
Supported Features
Feature
Support
Part Number
PI-IN-QD-QIV-NT
Platforms
NTI (2000, XP, 2003)
APS Connector
No
Point builder
Yes
ICU Control
Yes
PI Point Types
Float (16, 32 & 64), Discrete, Strings
(operator messages only)
Sub-second Timestamps
Yes
Sub-second Scan Classes
Yes
Quindar SCADA Interface to the PI System
1
1
Introduction
Feature
Support
Automatically Incorporates PI Point
Attribute Changes
Yes
Exception Reporting
Yes
Outputs from PI
Yes
Inputs to PI: Scan-based / Unsolicited /
Event Tags
Scanned or Unsolicited / Event
Supports Questionable Bit
No
Supports Multi-character PointSource
Yes
Maximum Point Count
25,000 analog, 25,000 status tags (VMS
SCADA)
100,000 analog, 200,000 status tags
(Windows SCADA)
* Uses PI SDK
Yes
PINet String Support
n/a
* Source of Timestamps
PI or SCADA
History Recovery
No
* UniInt-Based
* Disconnected Startup
* SetDeviceStatus
Yes
Yes
Yes
* Failover
UniInt Failover (Phase 1)
* Vendor Software Required on PI Interface
Node
Yes
* Vendor Software Required on Foreign
Device
Yes
Vendor Hardware Required
No
Additional PI Software Included with
Interface
No
* Device Point Types
Analog, Status and OMS
See paragraphs below for further explanation.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating
systems. Because it is dependent on vendor software, newer platforms may not yet be
supported.
Please contact OSIsoft Technical Support for more information.
Uses PI SDK
The PI SDK and the PI API are bundled together and must be installed on each PI
Interface node. The Windows SCADA version of the interface is compiled to use the PI
SDK. This is done so that the interface can handle the longer SCADA station and tag
names available with the Windows SCADA System.
2
Source of Timestamps
When the interface is running in scan mode, it always uses PI time for the data
timestamps.
When the interface runs in exception mode, the interface can use either the timestamps
returned from the SCADA System or adjust those timestamps to the current PI time. The
default mode of operation is to use the timestamps directly from the SCADA System. If
the /at command line parameter is passed in the start up command file, then the
SCADA System timestamps will be adjusted to PI time. A detailed discussion of the
time adjustment is given in the Principles of Operation section.
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an
OSIsoft-developed template used by developers, and is integrated into many interfaces,
including this interface. The purpose of UniInt is to keep a consistent feature set and
behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very
rapid development of new interfaces. In any UniInt-based interface, the interface uses
some of the UniInt-supplied configuration parameters and some interface-specific
parameters. UniInt is constantly being upgraded with new options and features.
The UniInt End User Document is a supplement to this manual.
Disconnected Start-Up
The PI Quindar interface is built with a version of UniInt that supports disconnected
start-up. Disconnected start-up is the ability to start the interface without a connection to
the PI server. This functionality is enabled by adding /cachemode to the list of start-up
parameters or by enabling disconnected startup using the ICU. Refer to the UniInt
Interface User Manual for more details on UniInt Disconnect startup.
SetDeviceStatus
The interface supports UniInt device status tags. The device status Health tag has the
string “[UI_DEVSTAT]” in the extended descriptor (Exdesc) PI Point Attribute. Please
refer to the UniInt Interface User Manual.doc file for more information on how to
configure health points. Alternatively, Health tags can be configured with the PI
Interface Configuration Utility.
Device status tags can be configured to monitor the status of the devices to which the
interface connects. Strings of the following form can be written to the device status tag.
Note that the “# |” at the beginning of each error string is for internal use for an
application that parses this string.

“Good” – This means that the interface is able to connect to all devices for the
given tag configuration of the interface. A value of “Good” does not mean that
all tags are receiving good values, but it is a good indication that there are no
hardware or network problems.

“1 | Starting” – The interface will remain in this status until it has successfully
collected data from its first scan. Interfaces that collect data infrequently may
stay in this status for a long time.

“3 | 1 device(s) in error” – This means that communication has been lost to all
SCADA hosts.
Quindar SCADA Interface to the PI System
3
Introduction

“4 | Intf Shutdown”. The interface is shutdown.
Failover
Nda SCADA Failover
The Nda library provides failover between the SCADA system Hosts. Up to four
SCADA System hosts can be configured and the interface will fail from one to another
as needed. If no hosts are available the interface will return I/O Timeout status for all
scanned points.
UniInt Failover Support
UniInt provides support for a hot failover configuration which results in a no data loss
solution for bi-directional data transfer between the PI Server and the Data Source given
a single point of failure in the system architecture. This failover solution requires that
two copies of the interface be installed on different interface nodes collecting data
simultaneously from a single data source. Failover operation is automatic and operates
with no user interaction. Each interface participating in failover has the ability to monitor
and determine liveliness and failover status. To assist in administering system
operations, the ability to manually trigger failover to a desired interface is also supported
by the failover scheme.
The failover scheme is described in detail in the UniInt End User Document, which is a
supplement to this manual. Details for configuring this Interface to use failover are
described in the UniInt Failover Configuration section of this manual.
Vendor Software Required
The Survalent Network Database Access Library appropriate for the specific SCADA
System must be installed on the interface node.
Version 1.7.711.0 or higher of Windows version of Nda Client API is required for the
Windows version of the interface.
Version 1.7.116.0 or higher of VMS version of Nda Client API is required for the VMS
version of the interface. Check with Survalent to verify the version of the Nda Client
API and that the version of the Nda Server on the VMS side is 2.34.
Note: There have been intermittent problems with floating-point values when earlier
versions of the Nda Client API were used, sometimes even crashing the interface.
Device Point Types
The PI Quindar Interface supports Analog and Status points, as well as Operator
Message String Records (OMSRecords).
4
Diagram of Hardware Connection
The following diagram illustrates the connectivity between the SCADA System and the
PI Data Archive.
Nda Server API
SCADA System
QUICS IV or Windows
NdaClient
API
PI Network Sub-System
PI API/SDK
PIQuindar Interface
SCADA
Database
SCADA Node
PI Data Server
Buffering
Interface Node
PI Database
PI Server Node
QUICS IV and Windows SCADA Differences
From the PI user’s perspective, the QUICS IV SCADA (VMS) and Windows SCADA
(Windows) Systems are virtually identical. The following section describes the
differences between the QUICS IV and Windows versions of the Survalent SCADA
systems.
Each section will discuss the interfaces behavior and any possible user concerns or
required actions.
DLL Names
The QUICS IV SCADA version of the interface is linked to the NdaClient.dll used in all
previous versions of the interface. The Windows SCADA version is linked to the new
NdaClientWin.dll.
SCADA Station and Tag Names
On QUICS IV SCADA systems the station name is 4 characters maximum and the tag
name is 6 characters maximum and must be upper case and blank filled to the maximum
length. The interface handles the formatting so the user only needs to be concerned with
the maximum length. For example: AB AMPS would be station AB and point AMPS so that
the InstrumentTag would be STA=AB POI=AMPS.
On Windows SCADA systems the maximum length for both station and point names is
32 characters, separated with a comma. They are not case sensitive. For example:
AB,AMPS would be station AB and point AMPS so that the InstrumentTag would be
STA=AB POI=AMPS.
Quindar SCADA Interface to the PI System
5
Introduction
The interface properly formats the station and tag name according to the target SCADA
System’s naming convention. When interfacing to the QUICS IV SCADA, the lengths of
the station and tag names defined via the InstrumentTag attribute must not exceed the
maximum for the target SCADA system. Otherwise, the point will be rejected and a
message logged to the PI message log.
Maximum Point Counts
The maximum number of points on the QUICS IV SCADA System is 25,000 for both
analog and status points.
For Windows SCADA Systems the point count has increased to 100,000 for analog and
200,000 for status points.
No user interaction is required for either SCADA platforms.
Starting Point Numbers
The following shows the starting point numbers for analog and status points on the
QUICS IV and Windows SCADA Systems.

QUICS IV Analog – 5,001

QUICS IV Status – 30,001

Windows SCADA Analog – 300,000

Windows SCADA Status – 400,000
The interface translates SCADA station and tag names to SCADA point IDs internally.
No user interaction is required for either SCADA platform.
Analog Value Format
On QUICS IV SCADA Systems the floating-point data is represented in a
single-precision floating-point variable. On Windows SCADA this has been increased to
a double-precision floating-point variable.
The user may wish to use double-precision floating point tags in PI when interfacing to a
Windows SCADA System in order to avoid loss of precision.
6
Principles of Operation
The QUICS IV VMS SCADA System runs on a DEC ALPHA computer. The Windows
SCADA System runs on an Intel-based computer running a version of Microsoft
Windows listed above. A customer may choose to run up to four SCADA nodes, each of
which can be configured with redundant network cards. This effectively provides for
quad redundancy for network connectivity.
The PI Quindar Interface runs on a PC running a Microsoft Windows operating system
listed above. The PC can also have multiple network cards installed for added
redundancy for connections to the SCADA Server(s).
Data Collection
The PI Quindar Interface retrieves analog and status data from the SCADA system. The
status data can be one of possible four states.
The interface can be configured to collect data from the SCADA System on either an
Exception or Polled basis (/is parameter). The default is to collect on an exception
basis.
Exception-mode Processing
When the interface uses the default exception mode, data is collected from the SCADA
system as changes on the SCADA System occur. It should be noted that exception mode
processing only applies to the way the data is collected from SCADA by the interface.
Data is always returned to PI based on the scan rate for each PI point.
As exception data is received, the interface uses the SCADA point id and point type to
locate the internal data structure that represents the corresponding PI point, if one exists.
If no PI point is configured for the SCADA point, the data is discarded. Otherwise, the
internal structure is updated with the new data and a flag is set indicating that new data
has been received.
The exception to the above behavior is immediately after a connection or reconnection to
the SCADA System occurs. When a connection or reconnection is made to the SCADA
System, the Nda Client sends an initial update for all points on the SCADA regardless of
changes. Since the interface updates its internal structures with the update data, the next
scan from PI will send a complete update for all points.
When a scan class is serviced, the data comes from the interface’s internal storage
instead of polling the device for current data. Since some points may not change for
extended periods of time, the interface does a periodic poll of all points in a scan class at
the rate of once every 10 minutes, by default. This rate can be adjusted by specifying the
/cr=x parameter. This poll is also performed whenever a scan class is modified, since
newly added points may not get an exception event for a long time.
Note: When a periodic poll of data is made, no SCADA timestamp is provided with the
data. As such, the data is timestamped with current PI server time.
When the interface is using exception mode, the exception data coming from SCADA
contains a timestamp for each value returned. The interface, by default, uses this
timestamp when it sends the data to PI. Optionally, the interface can adjust the SCADA
Quindar SCADA Interface to the PI System
7
7
Principles of Operation
time to the time on the PI server at the time the event occurred (/at parameter). When
this parameter is used, the interface periodically computes a delta based on the time on
the SCADA vs. the time on the PI server. This delta is applied to the timestamp provided
by the SCADA. In order to prevent the interface from applying slightly different deltas
on a frequent basis, the delta is only updated if it varies by more than 5 seconds from the
previous delta.
Note: It is highly recommended that the /sn parameter be specified in the interface
startup file if data collection is to be done by exception so that the interface does not do its
own exception processing on top of the SCADA System’s.
Note: If the interface is running in exception mode, the initial value for a newly created
point will occur when an exception occurs or when the interface polls to force new values
for the scan class, whichever occurs first.
Scan-mode Processing
When the interface uses scan-mode processing or polling, each time a scan class is
scanned, a call is made to read all points in that scan class. This is much less efficient
than collecting data via exception mode and is not the recommended mode of operation.
Timestamps in scan mode are always the PI server time at the time the scan is performed.
Status Handling
Regardless of the scan mode used, the interface first applies a globally valid status first,
then a scan class-based status, and finally a point-based status. If, for example, the
communications is lost to the SCADA, all points receive I/O Timeout status. If
however, an API call fails for a group of points, only those points are affected. Finally, if
a single point is in error, only that point is affected.
OMS Record Handling
The interface can also retrieve Operator Message String Records (OMSRecords), which
will be stored in PI into a single string tag. The string tag that will be used is specified
by the command-line parameter /ot=x. If no tag is specified, the OMSRecords will not
be written to PI.
OMSRecords are stored in the SCADA System in a circular file. A PI tag is used to keep
track of the most recent record index that has been processed. The integer PI tag that
will hold the record index is specified by the /oi=x parameter. If the interface loses
communication with the SCADA System, once communication has been re-established
the interface will resume where it left off, unless the file has wrapped around. Collection
of OMSRecords is done by polling for them at the scan class frequency specified for the
string tag, which will hold the information. Collection of OMSRecords is optional and
will only occur if both the string tag to hold the information and the integer tag to old the
index are specified. If one tag is specified and not the other, the interface will exit and
print out a message indicating which one of the two tags was either not specified or was
invalid.
SCADA Failover
The Survalent SCADA System provides fault tolerance by allowing up to four SCADA
nodes to be configured. In the example below four SCADA hosts are configured. They
are HOSTA, HOSTB, HOSTC and HOSTD. In this case, the interface would specify all
8
four hosts via the /sh=x;x;x;x startup parameter. This is explained in detail later in
this manual. The Nda API detects the failure of a SCADA host and will transparently
switch to an available SCADA host. In the configuration shown below the user would
specify the host by using the parameter /sh=HOSTA;HOSTB;HOSTC;HOSTD.
SCADA Host
HOSTA
PI Interface Node
SCADA Host
HOSTB
SCADA Host
HOSTC
PI Server Node
SCADA Host
HOSTD
Additionally, each SCADA host can be configured with multiple network interface
adapters on separate LANs for added reliability. The typical node naming convention in
this configuration would be HOSTA_LAN1, HOSTA_LAN2, HOSTB_LAN1,
HOSTB_LAN2, etc. Each of these would be specified via the /sh=x;x;x;x commandline parameter.
Failover between the SCADA hosts is handled by the Nda client and is transparent to the
PI Quindar Interface. However, if communication to all SCADA hosts is lost, the
interface will then write the digital state of I/O Timeout to all input points belonging
to the interface. It may take as much as two or more minutes for the Nda client to
recognize that it cannot communicate to any of the SCADA hosts. The interface
attempts reconnection to the SCADA system every 10 seconds. Once communication is
re-established with at least one SCADA host, data collection resumes once again.
UniInt Failover
This interface supports UniInt failover. Refer to the UniInt Failover Configuration
section of this document for configuring the interface for failover.
Quindar SCADA Interface to the PI System
9
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this
checklist helps get the Interface running. If not familiar with PI interfaces, return to this
section after reading the rest of the manual in detail.
1. Install the PI Interface Configuration Utility (which installs PI SDK and PI API)
2. Verify that PI API has been installed.
3. Install the Quindar Nda Library. (Refer to the Nda API Users Guide.)
4. Install the interface.
5. Test the connection between the interface node and the Quindar SCADA system
using PICheckNda.

Specify a node to connect to and issue NdaConnect.

Read/Write specified status tag. The utility will properly format the station and
tag name to be compatible with the target SCADA System.

Read/Write specified analog tag. The utility will properly format the station and
tag name to be compatible with the target SCADA System.

Retrieve OMSRecords
6. Define OMS Record tags. (OMSRecordText and OMSRecordID)
7. Define digital states.
Define interface-specific system digital states.
These states must be consecutive states in the system state table. By default, the
interface expects them at system states 500-505 but they can be relocated to any
available range, except 193-320 which are reserved for OSIsoft applications, by
using the /ds=# command line parameter. For example: To use states 400-405, the
/ds=400 command line parameter would be specified.
The following states need to be defined in the system state table:
CCTELEMETRYFAILED – Status indicating RTU failure or RTU communications
error.
CCMANUAL – No longer used but required for backward
compatiblity.
CCCALCULATED – No longer used but required for backward
compatiblity.
FDB_BAD – Nda Bad Parameter specified (Internal interface error)
FDB_NSF – Nda error indicating an invalid tag or station was specified.
FDB_UNKOWN – Unknown Nda error
8. Choose a point source.
9. Configure PI points.
Location1 is the interface instance.
Location2 is the IO Direction (0=read, 1=write)
Location3 is not used
Location4 is the scan class.
Quindar SCADA Interface to the PI System
11
11
Installation Checklist
Location5 is not used.
exdesc is not used.
instrumenttag defines the SCADA station and tag names
10. Use the ICU to configure the startup command file.
11. Configure performance points.
12. Configure I/O Rate tag.
13. Set up security.
14. Start the interface without buffering.
15. Verify data.
16. Stop interface, start buffering, start interface.
17. Configure UniInt Failover. Refer to the UniInt Failover Configuration section of this
document for details relating to configuring the interface for failover.
12
Interface Installation
OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly
on the PI Server node. A PI Interface Node is any node other than the PI Server node
where the PI Application Programming Interface (PI API) has been installed (see the PI
API manual). With this approach, the PI Server need not compete with interfaces for the
machine’s resources. The primary function of the PI Server is to archive data and to
service clients that request data.
After the interface has been installed and tested, Bufserv should be enabled on the PI
Interface Node (once again, see the PI API manual). Bufserv is distributed with the
PI API. It is a utility program that provides the capability to store and forward events to a
PI Server, allowing continuous data collection when communication to the PI Server is
lost. Communication will be lost when there are network problems or when the PI Server
is shut down for maintenance, upgrades, backups, or unexpected failures.
In most cases, interfaces on PI Interface Nodes should be installed as automatic services .
Services keep running after the user logs off. Automatic services automatically restart
when the computer is restarted, which is useful in the event of a power failure.
The guidelines are different if an interface is installed on the PI Server node . In this case,
the typical procedure is to install the PI Server as an automatic service and install the
interface as an automatic service that depends on the PI Update Manager and PI Network
Manager services. This typical scenario assumes that Bufserv is not enabled on the PI
Server node. Bufserv can be enabled on the PI Server node so that interfaces on the PI
Server node do not need to be started and stopped in conjunction with PI, but it is not
standard practice to enable buffering on the PI Server node. See the UniInt End User
Document for special procedural information.
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface
executable is PIQuindar.exe and that the startup command file is called
PIQuindar.bat.
When Configuring the Interface Manually
When configuring the interface manually it is customary for the user to rename the
executable and the startup command file when multiple copies of the interface are run .
For example, PIQuindar1.exe and PIQuindar1.bat would typically be used for
interface number 1, PIQuindar2.exe and PIQuindar2.bat for interface number 2,
and so on. When an interface is run as a service, the executable and the command file
must have the same root name because the service looks for its command-line parameters
in a file that has the same root name.
Quindar SCADA Interface to the PI System
13
13
Interface Installation
Interface Directories
PIHOME Directory Tree
The PIHOME directory tree is defined by the PIHOME entry in the
pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located
in the %windir% directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on
the C: drive. OSIsoft recommends using \pipc as the root directory name. The
PIHOME directory does not need to be on the C: drive.
Interface Installation Directory.
The install kit installs the Window SCADA version and VMS SCADA version into
separate sub-directory under the main interface directory. The suggested directories are:
PIHOME\Interfaces\Quindar\ for the manual and release notes
PIHOME\Interfaces\Quindar\NT SCADA\ for the Windows version
executable, sample batch file
PIHOME\Interfaces\Quindar\VMS SCADA\ for the VMS version
executable, sample batch file
Replace PIHOME with the corresponding entry in the pipc.ini file.
Interface Installation Procedure
The PI Quindar Interface setup program uses the services of the Microsoft Windows
Installer. Windows Installer is a standard part of Windows 2000 and greater operating
systems. When running on Windows NT 4.0 systems, the PI Quindar setup program will
install the Windows Installer itself if necessary. To install, run the Quindar_x.x.x.x.exe
installation kit.
Installing Interface as a Windows Service
The PI Quindar Interface service can be created, preferably, with the PI Interface
Configuration Utility, or can be created manually.
14
Installing Interface Service with PI ICU
The PI Interface Configuration Utility provides a user interface for creating, editing, and
deleting the interface service:
Service Configuration
Service name
The Service name box shows the name of the current interface service. This service name
is obtained from the interface executable.
ID
This is the service id used to distinguish multiple instances of the same interface using
the same executable.
Display name
The Display Name text box shows the current Display Name of the interface service. If
there is currently no service for the selected interface, the default Display Name is the
service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft
suggests that the prefix “PI-” be appended to the beginning of the interface to indicate
that the service is part of the OSIsoft suite of products.
Log on as
The Log on as text box shows the current “Log on as” Windows User Account of the
interface service. If the service is configured to use the Local System account, the Log
on as text box will show “LocalSystem.” Users may specify a different Windows User
account for the service to use.
Password
If a Windows User account is entered in the Log on as text box, then a password must be
provided in the Password text box, unless the account requires no password.
Quindar SCADA Interface to the PI System
15
Interface Installation
Confirm Password
If a password is entered in the Password text box, then it must be confirmed in the
Confirm Password text box.
Startup Type
The Startup Type indicates whether the interface service will start automatically or needs
to be started manually on reboot.

If the Auto option is selected, the service will be installed to start automatically
when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but
will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.
Generally, interface services are set to start automatically.
Dependencies
The Installed services list is a list of the services currently installed on this machine.
Services upon which this Interface is dependent should be moved into the Dependencies
list using the
button. For example, if PI API Buffering is running, then “bufserv”
should be selected from the list at the right and added to the list on the left. To remove a
service from the list of dependencies, use the
removed from the “Dependencies” list.
button, and the service name will be
When the PI Interface is started (as a service), the services listed in the dependency list
will be verified as running (or an attempt will be made to start them). If the dependent
service(s) cannot be started for any reason, then the PI interface service will not run.
Note: Please see the PI Log and Operating System Event Logger for messages that may
indicate the cause for any server not running as expected.
- Add Button
To add a dependency from the list of Installed services, select the dependency name, and
click the Add button.
- Remove Button
To remove a selected dependency, highlight the service name in the Dependencies list,
and click the Remove button.
The full name of the service selected in the Installed services list is displayed below the
Installed services list box.
Create
The Create button adds the displayed service with the specified Dependencies and with
the specified Startup Type.
16
Remove
The Remove button removes the displayed service. If the service is not currently
installed, or if the service is currently running, this button will be grayed out.
Start or Stop Service
To Start or Stop an interface service, use the Start button
and a Stop button
on
the ICU toolbar. If this interface service is not currently installed, these buttons will
remain grayed out until the service is added. If this interface service is running, the Stop
button is available. If this service is not running, the Start button is available.
The status of the Interface service is indicated in the lower portion of the PI ICU dialog.
Status of
the ICU
Status of the
Interface
Service
Service
installed or
uninstalled
Installing Interface Service Manually
Help for installing the interface as a service is available at any time with the command:
PIQuindar.exe –help
Change to the directory where the PIQuindar1.exe executable is located. Then,
consult the following table to determine the appropriate service installation command.
Windows Service Installation Commands on a PI Interface Node or a PI Server Node
with Bufserv implemented
Manual service
PIQuindar.exe –install –depend “tcpip bufserv”
Automatic service
PIQuindar.exe –install –auto –depend “tcpip bufserv”
*Automatic service with
service id
PIQuindar.exe –serviceid X –install –auto –depend “tcpip bufserv”
Windows Service Installation Commands on a PI Interface Node or a PI Server Node
without Bufserv implemented
Manual service
PIQuindar.exe –install –depend tcpip
Automatic service
PIQuindar.exe –install –auto –depend tcpip
*Automatic service with
service id
PIQuindar.exe –serviceid X –install –auto –depend tcpip
*When specifying service id, the user must include an id number. It is suggested that this
number correspond to the interface id (/id) parameter found in the interface .bat file.
Check the Microsoft Windows services control panel to verify that the service was added
successfully. The services control panel can be used at any time to change the interface
from an automatic service to a manual service or vice versa.
Quindar SCADA Interface to the PI System
17
PICheckNda Connection Test Utility
Before the interface can collect data there must be a valid connection between the
interface node and the SCADA System. OSIsoft provides the test program PICheckNda
to make the validation easier. The program should be in the PI Quindar interface
directory, the same location as the executable.
Start the program by typing:
PICheckNda
The program prompts:
Enter Host Name(s) as name1;name2;name3;name4
The following menu is displayed.
Enter Function
1 – Connect
2 – NdaGet
3 – NdaPut
4 – NdaAnaExc
5 – NdaStaExc
6 – Get OMS Records
7 – NdaGetTime
8 – Create PIConfig structure file for analog or status tags
0 – Exit
Function 1 is used to issue an NdaConnect to the SCADA system.
Function 2 is used to retrieve data (single or multiple) for a single point.
Function 3 is used to write data to the SCADA System for a single point.
Function 4 is used to test analog exceptions.
Function 5 is used to test status record exceptions.
Function 6 is used to get OMS records.
Function 7 is used to test the NdaGetTime function.
Function 8 can be used to generate a PIConfig input file(s) to assist in creating the initial
points for the interface.
Function 0 is used to exit the program.
Quindar SCADA Interface to the PI System
19
19
Define OMS Record Tags
If OMS Record processing is desired, two PI tags must be defined for use by the OMS
Record processing logic in the interface. The point source for both of these tags should
typically be something other than the point source used by the interface. If the tags
inadvertently have the same point source used by the interface, the tag(s) will be
rejected, but will still be used by the interface for OMS Record processing. Entries will
however be logged to the message log indicating the rejection of the point, this could
potentially be a nuisance.
The first tag, specified via the /ot=x parameter is used to store the OMS Record text
returned from the SCADA System. X must be a string tag.
The second tag, specified by the /oi=x parameter is used to keep track of the index
corresponding to the most recently OMS record archived in PI. This tag should be an
int32 tag because the Nda API uses a 32-bit integer as the OMS record ID. This tag
should also have exception and compression turned off.
Shutdown events should also be disabled for both tags.
Note: With a newly installed interface there will be no archived value for the OMS Record
ID. The interface will log an informational message indicating that a status of –253 (Point
Created) was received for the OMS Record ID tag and the value will default to 0. This is
normal and all OMS Records starting with the oldest message in the SCADA queue will
be sent to PI.
Quindar SCADA Interface to the PI System
21
21
Digital States
For more information regarding Digital States, refer to the PI Server documentation.
Digital State Sets
PI digital states are discrete values represented by strings. These strings are organized in
PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated
from 0 to n to represent different values of discrete data. For more information about
PI digital tags and editing digital state sets, see the PI Server manuals.
An interface point that contains discrete data can be stored in PI as a digital tag. A
Digital tag associates discrete data with a digital state set, as specified by the user.
System Digital State Set
Similar to digital state sets is the system digital state set. This set is used for all tags,
regardless of type to indicate the state of a tag at a particular time. For example, if the
interface receives bad data from an interface point, it writes the system digital state
bad input to PI instead of a value. The system digital state set has many unused states
that can be used by the interface and other PI clients. Digital States 193-320 are reserved
for OSIsoft applications.
The following states need to be defined in the system state table. These can be defined in
any unused contiguous area except in the range of 193 to 320. Each state must be in the
order shown below, but the text of the state can be anything desired. The starting digital
state code for the group of digital states is passed in the interface startup file by the
command line parameter /ds=# where # is the digital state code of
CCTELEMETRYFAILED. If this parameter is not specified, the default starting state will
be 500. A message will be printed in the pipc.log indicating the start code used.

CCTELEMETRYFAILED – SCADA status indicating RTU failure or
omm..
Error.

CCMANUAL – No longer used but required for backwards
compatibility

CCCALCULATED - No longer used but required for backwards
compatibility

FDB_BAD – Nda Bad Parameter specified (Internal interface error)

FDB_NSF – Nda error indicating an invalid tag or station was specified.

FDB_UNKNOWN – Unknown Nda error
Quindar SCADA Interface to the PI System
23
23
PointSource
The PointSource is a unique, single or multi-character string that is used to identify the
PI point as a point that belongs to a particular interface. For example, the string Boiler1
may be used to identify points that belong to the MyInt Interface. To implement this, the
PointSource attribute would be set to Boiler1 for every PI Point that is configured for
the MyInt Interface. Then, if /ps=Boiler1 is used on the startup command-line of the
MyInt Interface, the Interface will search the PI Point Database upon startup for every PI
point that is configured with a PointSource of Boiler1. Before an interface loads a
point, the interface usually performs further checks by examining additional PI point
attributes to determine whether a particular point is valid for the interface. For additional
information, see the /ps parameter.
Case-sensitivity for PointSource Attribute
If the interface is running on a PINet node, use a capital letter (or a case-insensitive
character such as a number, a question mark, etc.) for the PointSource attribute when
defining points. For all other scenarios, the case of the PointSource is insignificant.
In all cases, the PointSource character that is supplied with the /ps command-line
argument is not case sensitive. That is, /ps=P and /ps=p are equivalent. It is only
necessary to be careful with the case of the PointSource during point definition and only
if the Interface will be running on a PINet node communicating to a PI Server.
Reserved Point Sources
Several subsystems and applications that ship with PI are associated with default
PointSource characters. The Totalizer Subsystem uses the PointSource character T, the
Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance
Equations Subsystem uses C. Do not use these PointSource characters or change the
default point source characters for these applications. Also, if a PointSource character is
not explicitly defined when creating a PI point; the point is assigned a default
PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the
PointSource character for an interface.
Note: Do not use a point source character that is already associated with another
interface program. However it is acceptable to use the same point source for multiple
instances of an interface.
Quindar SCADA Interface to the PI System
25
25
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the
PI Server. A single point is configured for each measurement value that needs to be
archived.
Point Attributes
Use the point attributes below to define the PI Point configuration for the Interface,
including specifically what data to transfer.
Tag
A tag is a label or name for a point. Any tag name can be used in accordance with the
normal PI point naming conventions.
Length
The length of the Tag field is limited by the version of the PI API, the version of the PI
Server, and sometimes by a specific Interface. The table below explains this in more
detail. When the maximum possible lengths differ for the software installed on site, the
shortest length applies.
PI API
PI Server
Maximum Length
1.6 or higher
3.4.370.x or higher
1023
1.6 or higher
Below 3.4.370.x
255
Below 1.6
3.4.370.x or higher
255
Below 1.6
Below 3.4.370.x
255
PointSource
The PointSource is a unique single or multiple-character string that is used to identify the
PI point as a point that belongs to a particular interface. For additional information, see
the /ps command-line argument and the “Point Source” section.
PointType
Typically, device point types do not need to correspond to PI point types. For example,
integer values from a device can be sent to floating point or digital PI tags. Similarly, a
floating-point value from the device can be sent to integer or digital PI tags, although the
values will be truncated.
Float16, float32, float 64, int16, int32, digital and string point types are supported. For
more information on the individual PointTypes, see PI Server manuals.
Quindar SCADA Interface to the PI System
27
27
PI Point Configuration
Location1
Location1 indicates to which copy of the interface the point belongs. The value of this
attribute must match the /id startup parameter.
Location2
Location2 specifies the I/O direction of the point.

0 – Input Point

1 – Output Point
Location3
Location5 is not used by this interface.
Location4
Scan-based Inputs
For interfaces that support scan-based collection of data, Location4 defines the scan class
for the PI point. The scan class determines the frequency at which input points are
scanned for new values. For more information, see the description of the /f parameter in
the section called Startup Command File .
Trigger-based Inputs, Unsolicited Inputs, and Output Points
Location 4 should be set to zero for these points.
Location5
Location5 is not used by this interface.
InstrumentTag
Length
The length of the InstrumentTag field is limited by the version of the PI API, the version
of the PI Server, and sometimes by a specific Interface. The table below explains this in
more detail. When the maximum possible lengths differ for the software installed on
site, the shortest length applies.
PI API
PI Server
Maximum Length
1.6 or higher
3.4.370.x or higher
1023
1.6 or higher
Below 3.4.370.x
32
Below 1.6
3.4.370.x or higher
32
Below 1.6
Below 3.4.370.x
32
The PI Quindar Interface uses the InstrumentTag attribute to specify the RTU Station ID
and Tagname. The format for this field is:
28
STA[TION]=SSSS POI[NTNAME]=TTTTTT
SSSS is the station name, with a maximum of 4 characters for VMS SCADA or 32
characters for Windows SCADA. TTTTTTT is the tag name, with a maximum of 6
characters for VMS SCADA and 32 characters for Windows SCADA. The SCADA
System requires that internal and ending spaces be present. The interface adjusts for the
spacing requirements.
STATION may be abbreviated as STA and POINT as POI.
Note: The interface converts the station and point names to upper case (required for the
VMS SCADA systems), thus making these fields case insensitive.
ExDesc
Length
The length of the Extended Descriptor field is limited by the version of the PI API, the
version of the PI Server, and sometimes by a specific Interface. The table below
explains this in more detail. When the maximum possible lengths differ for the software
installed on site, the shortest length applies.
PI API
PI Server
Maximum Length
1.6 or higher
3.4.370.x or higher
1023
1.6 or higher
Below 3.4.370.x
80
Below 1.6
3.4.370.x or higher
80
Below 1.6
Below 3.4.370.x
80
Performance Points
For UniInt-based interfaces, the extended descriptor is checked for the string
“PERFORMANCE_POINT”. If this character string is found, UniInt treats this point as a
performance point. See the section called Performance Point Configuration.
Trigger-based Inputs
For trigger-based input points, a separate trigger point must be configured. An input
point is associated with a trigger point by entering a case-insensitive string in the
extended descriptor (ExDesc) PI point attribute of the input point of the form:
keyword=trigger_tag_name
where keyword is replaced by “event” or “trig” and trigger_tag_name is replaced
by the name of the trigger point. There should be no spaces in the string. UniInt
automatically assumes that an input point is trigger-based instead of scan-based when the
keyword=trigger_tag_name string is found in the extended descriptor attribute.
An input is triggered when a new value is sent to the Snapshot of the trigger point. The
new value does not need to be different than the previous Snapshot value to trigger an
input, but the timestamp of the new value must be greater than (more recent than) or
equal to the timestamp of the previous value. This is different than the trigger mechanism
Quindar SCADA Interface to the PI System
29
PI Point Configuration
for output points. For output points, the timestamp of the trigger value must be greater
than (not greater than or equal to) the timestamp of the previous value.
Conditions can be placed on trigger events. Event conditions are specified in the
extended descriptor as follows:
Event=‘trigger_tag_name’ event_condition
The trigger tag name must be in single quotes. For example,
Event=‘Sinuoid’ Anychange
will trigger on any event to the PI Tag sinusoid as long as the next event is different than
the last event. The initial event is read from the snapshot.
The keywords in the following table can be used to specify trigger conditions.
Event
Condition
Description
Anychange
Trigger on any change as long as the value of the current event is different than
the value of the previous event. System digital states also trigger events. For
example, an event will be triggered on a value change from 0 to “Bad Input,” and
an event will be triggered on a value change from “Bad Input” to 0.
Increment
Trigger on any increase in value. System digital states do not trigger events. For
example, an event will be triggered on a value change from 0 to 1, but an event
will not be triggered on a value change from “Pt Created” to 0. Likewise, an
event will not be triggered on a value change from 0 to “Bad Input.”
Decrement
Trigger on any decrease in value. System digital states do not trigger events. For
example, an event will be triggered on a value change from 1 to 0, but an event
will not be triggered on a value change from “Pt Created” to 0. Likewise, an
event will not be triggered on a value change from 0 to “Bad Input.”
Nonzero
Trigger on any non-zero value. Events are not triggered when a system digital
state is written to the trigger tag. For example, an event is triggered on a value
change from “Pt Created” to 1, but an event is not triggered on a value change
from 1 to “Bad Input.”
Scan
The Scan attribute has the default value of 1, indicating that the Interface should collect
data for the point. Setting the Scan attribute to 0 turns data collection off. If the Scan
attribute is 0 when the interface starts, the Interface writes SCAN OFF to the point. If the
user changes the Scan attribute from 1 to 0 while the interface is running, the Interface
also writes SCAN OFF.
There is one other situation, which is independent of the Scan attribute, where UniInt
will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is
edited so that the point is no longer valid for the interface, the point will be removed
from the interface, and SCAN OFF will be written to the point. For example, if the
PointSource of a PI point that is currently loaded by the interface is changed, the point
will be removed from the interface and SCAN OFF will be written to the point.
30
Shutdown
The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown
subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The
timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by
the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which
means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes
in the event of a power failure. For additional information on shutdown events, refer to
PI Server manuals.
Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are
independent of the SHUTDOWN events that are written by the interface when the
/stopstat=Shutdown command-line argument is specified.
SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting
the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI
Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that
have their Shutdown attribute set to 0. To change the default behavior, edit the
\PI\dat\Shutdown.dat file, as discussed in PI Server manuals.
Bufserv
It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a
utility program that provides the capability to store and forward events to a PI Server,
allowing continuous data collection when the Server is down for maintenance, upgrades,
backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue
to collect data for the interface, making it undesirable to write SHUTDOWN events to
the PI points for this interface.
Output Points
Output points control the flow of data from the PI Server to any destination that is
external to the PI Server, such as a PLC or a third-party database. For example, to write a
value to a register in a PLC, use an output point. Each interface has its own rules for
determining whether a given point is an input point or an output point. There is no de
facto PI point attribute that distinguishes a point as an input point or an output point.
Outputs are triggered for UniInt-based interfaces. That is, outputs are not scheduled to
occur on a periodic basis. There are two mechanisms for triggering an output.
Trigger Method 1 (Recommended)
For trigger method 1, a separate trigger point must be configured. The output point must
have the same point source as the interface. The trigger point can be associated with any
point source, including the point source of the interface. Also, the point type of the
trigger point does not need to be the same as the point type of the output point.
The output point is associated with the trigger point by setting the SourceTag attribute of
the output point equal to the tag name of the trigger point. An output is triggered when a
new value is sent to the Snapshot of the trigger point. The new value does not need to be
different than the previous value that was sent to the Snapshot to trigger an output, but
the timestamp of the new value must be more recent than the previous value. If no error
is indicated, then the value that was sent to the trigger point is also written to the output
Quindar SCADA Interface to the PI System
31
PI Point Configuration
point. If the output is unsuccessful, then an appropriate digital state that is indicative of
the failure is usually written to the output point. If an error is not indicated, the output
still may not have succeeded because the interface may not be able to tell with certainty
that an output has failed.
Trigger Method 2
For trigger method 2, a separate trigger point is not configured. To trigger an output,
write a new value to the Snapshot of the output point itself. The new value does not need
to be different than the previous value to trigger an output, but the timestamp of the new
value must be more recent than the previous value.
Trigger method 2 may be easier to configure than trigger method 1, but trigger method 2
has a significant disadvantage. If the output is unsuccessful, there is no tag to receive a
digital state that is indicative of the failure, which is very important for troubleshooting.
32
Performance Point Configuration
Performance points can be configured to monitor the amount of time in seconds that an
interface takes to complete a scan for a particular scan class. The closer the scan
completion time is to 0 seconds, the better the performance. The scan completion time is
recorded to millisecond resolution
Configuring Performance Points with PI ICU (Windows)
The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and
managing Performance Points.
Create
To create a Performance Point, right-click the line belonging to the tag to be created, and
select Create.
Delete
To delete a Performance Point, right-click the line belonging to the tag to be deleted, and
select Delete.
Correct
If the “Status” of a point is marked “Incorrect”, the point configuration can be
automatically corrected by ICU by right-clicking on the line belonging to the tag to be
corrected, and selecting Correct. The Performance Points are created with the following
PI attribute values. If ICU detects that a Performance Point is not defined with the
following, it will be marked Incorrect:
Quindar SCADA Interface to the PI System
33
33
Performance Point Configuration
Attribute
Details
Tag
Tag name that appears in the list box
PointSource
Point Source for tags for this interface, as specified on the first tab
Compressing
Off
ExcMax
0
Descriptor
Interface name + “ Scan Class # Performance Point”
Rename
Right-click the line belonging to the tag and select “Rename” in order to rename the
Performance Point.
Status
The Status column in the Performance Points table indicates whether the Performance
Point exists for the scan class in column 2.

Created – Indicates that the Performance Point does exist

Not Created – Indicates that the Performance Point does not exist

Deleted – Indicates that a Performance Point existed, but was just deleted by the
user
Scan Class
The Scan Class column indicates which scan class the Performance Point in the
Tagname column belongs to. There will be one scan class in the Scan Class column for
each scan class listed in the Scan Classes combo box on the UniInt Parameters tab.
Tagname
The Tagname column holds the Performance Point tag name.
Snapshot
The Snapshot column holds the snapshot value of each Performance Point that exists in
PI. The Snapshot column is updated when the Performance Points/Counters tab is
clicked, and when the interface is first loaded.
Configuring Performance Points Manually
Performance point configuration is the same on all operating system platforms.
Performance points are configured as follows.
1. Set the extended descriptor to:
PERFORMANCE_POINT
or to:
PERFORMANCE_POINT=interface_id
where interface_id corresponds to the identifier that is specified with the
/id parameter on the startup command-line of the interface. The character string
PERFORMANCE_POINT is case insenstive. The interface_id does not need to be
34
specified if there is only one copy of an interface that is associated with a particular
point source.
2. Set Location4 to correspond to the scan class whose performance is to be monitored.
For example, to monitor scan class 2, set Location4 to 2. See the /f parameter for a
description of scan classes.
3. Set the PointSource attribute to correspond to the /ps parameter on the startup
command-line of the interface.
4. Set the PointType attribute to float32.
Quindar SCADA Interface to the PI System
35
I/O Rate Tag Configuration
An I/O Rate tag measures the throughput of an Interface. In particular, the value of an
I/O Rate point represents a 10-minute average of the total number of values per minute
that the Interface sends to the PI Server. Because values are averaged over a 10-minute
interval, the first calculated value is not written to the PI Server until 10 minutes after the
Interface has started. The user can configure one I/O Rate tag for each copy of the
Interface that is in use.
Monitoring I/O Rates on the Interface Node
For Windows nodes, the 10-minute rate averages (in events/minute) can be monitored
with a client application such as PI ProcessBook.
Configuring I/O Rate Tags with PI ICU (Windows)
The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and
managing I/O Rate Tags.
PI ICU currently allows for one I/O Rate tag to be configured for each copy of the
interface that is in use. Some interfaces allow for multiple I/O Rate tags.
Enable IORates for this Interface
The Enable IORates for this interface check box enables or disables I/O Rates for the
current interface. To disable I/O Rates for the selected interface, uncheck this box. To
enable I/O Rates for the selected interface, check this box.
Tag Status
The Tag Status column indicates whether the I/O Rate tag exists in PI. The possible
states are:

Created – This status indicates that the tag exist in PI
Quindar SCADA Interface to the PI System
37
37
I/O Rate Tag Configuration

Not Created – This status indicates that the tag does not yet exist in PI

Deleted – This status indicates that the tag has just been deleted

Unknown – This status indicates that the PI ICU is not able to access the PI
Server
In File
The In File column indicates whether the I/O Rate tag listed in the tag name and the
event counter is in the IORates.dat file. The possible states are:

Yes – This status indicates that the tag name and event counter are in the
IORates.dat file

No – This status indicates that the tag name and event counter are not in the
IORates.dat file
Event Counter
The Event Counter correlates a tag specified in the iorates.dat file with this copy of the
interface. The command-line equivalent is /ec=x, where x is the same number that is
assigned to a tag name in the iorates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the I/O Rate tag.
Snapshot
The Snapshot column holds the snapshot value of the I/O Rate tag, if the I/O Rate tag
exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is
clicked, and when the Interface is first loaded.
Button Menu Options
Create
Create the suggested I/O Rate tag with the tag name indicated in the Tagname column.
Delete
Delete the I/O Rate tag listed in the Tagname column.
Rename
Allow the user to specify a new name for the I/O Rate tag listed in the Tagname column.
Add to File
Add the tag to the IORates.dat file with the event counter listed in the Event Counter
Column.
Search
Allow the user to search the PI Server a previously defined I/O Rate points.
38
Update Snapshot
Allow the user to refresh the snapshot value
Configuring I/O Rate Tags Manually
There are two configuration steps.
1. Configuring the PI Point on the PI Server
2. Configuration on the Interface Node
Configuring PI Point on the PI Server
Create an I/O Rate Tag with the following point attribute values.
Attribute
Value
PointSource
L
PointType
float32
Compressing
0
ExcDev
0
Configuration on the Interface Node
For the following examples, assume that the name of the PI tag is
sys.io.nodexyz.quindar001, and that the name of the I/O Rate on the home node is
sys.io.nodexyz.quindar001.
1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The
PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in
the pipc.ini file, which is located in the %windir% directory. If both are specified,
the PIPCSHARE entry takes precedence.
Since the PIHOME directory is typically C:\PIPC, the full name of the
iorates.dat file will typically be C:\PIPC\dat\iorates.dat.
Add a line in the iorates.dat file of the form:
sys.io.nodexyz.quindar001, x
where sys.io.nodexyz.quindar001 is the name of the I/O Rate Tag and x
corresponds to the first instance of the /ec=x parameter in the startup command file.
X can be any number between 2 and 34 or between 51 and 200, inclusive. To specify
additional rate counters for additional copies of the interface, create additional I/O
Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x,
should be unique for each copy of the interface.
2. Set the /ec=x parameter on the startup command file of the interface to match the
event counter in the iorates.dat file.
The interface must be stopped and restarted in order for the I/O Rate tag to take effect.
I/O Rates will not be written to the tag until 10 minutes after the interface is started.
Quindar SCADA Interface to the PI System
39
Startup Command File
Command-line parameters can begin with a / or with a -. For example, the
/ps=quindar and
–ps=quindar command-line parameters are equivalent.
For Windows, command file names have a .bat extension. The Windows continuation
character (^) allows for the use of multiple lines for the startup command. The maximum
length of each line is 1024 characters (1 kilobyte). The number of parameters is
unlimited, and the maximum length of each parameter is 1024 characters.
The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the
Interface startup command file.
The PI Quindar Interface on Windows has a PI ICU Control that will aid in configuring
the PI Quindar Interface startup command file.
Configuring the Interface with PI ICU
The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the
Interface startup command file.
Note: PI ICU requires PI 3.3 or greater.
The PI Interface Configuration Utility provides a graphical user interface for configuring
PI interfaces. If the interface is configured by the PI ICU, the batch file of the interface
(quindar.bat) will be maintained by the PI ICU and all configuration changes will be
kept in that file. The procedure below describes the necessary steps for using PI ICU to
configure the PI Quindar Interface.
From the PI ICU menu, select Interface, New, and then Browse to the PIQuindar.exe
executable file. Then, enter values for Point Source and Interface ID#. A window such
as the following results:
Quindar SCADA Interface to the PI System
41
41
Startup Command File
“Interface name as displayed in the ICU (optional)” will have PI- pre-pended to this
name and it will be the display name in the services menu.
Click on Add.
You should then see a display such as the following:
Note that in this example the Host PI System is MPKELLYLAPTOP, which means that
the interface will be configured to communicate with the local PI Server. However, to
configure the interface to communicate with a remote PI Server, select the
‘Connections…’ item from PI ICU menu and make it the default server. If the remote
node is not available in the list of servers, it can be added.
Once the interface is added to PI ICU, near the top of the main PI ICU screen, the
Interface Type should be quindar. If not, use the drop-down box to change the
Interface Type to be quindar.
Since the PI Quindar Interface is a UniInt-based interface, in some cases the user will
need to make appropriate selections in the UniInt section of the ICU. This section
allows the user to access UniInt features through the PI ICU and to make changes to the
behavior of the interface.
To set up the interface as a Windows Service, use the Service section. This section
allows configuration of the interface to run as a service as well as starting and stopping
of the interface. The interface can also run interactively from the PI ICU. To do that go
to menu, select the Interface item and then Start Interactive.
42
For more detailed information on how to use the above-mentioned and other PI ICU
sections and selections, please refer to the PI Interface Configuration Utility User
Manual. The next section describes the selections that are available from the quindar
section. Once selections have been made on the PI ICU GUI, press the Apply button in
order for PI ICU to make these changes to the interface’s startup file.
General Parameters Tab
Adjust timestamps to PI Server time
Adjust SCADA timestamp to that of the PI server time. Used when the interface collects
data on exception basis. (/AT)
Use scan mode instead of exception mode
Retrieve data from the SCADA on a scan basis instead of the default exception mode.
(/IS)
Override exception mode default scan rate
Change the demand scan rate used when running in exception mode. The default is 600
seconds. (/CR=#, Default:600)
New scan rate (seconds)
Integer value providing the demand scan rate when running in exception mode. The
default is 600 seconds. (/CR=#, Default:600)
Quindar SCADA Interface to the PI System
43
Startup Command File
Specify starting digital state code to use for error status messages
Provide the starting System digital state to use for interface specific status and error
messages. (/DS=#)
Digital state selector
Provide the starting System digital state to use for interface specific status and error
messages. This is not an optional command line parameter if the 6 required states are not
found starting at code 500.(/DS=#)
Process OMS Records
If OMS Record processing is desired, allows the tags to be used for this to be specified.
Tag that will provide OMS Record text strings
String tag to use for OMS Record text strings. (/OT=tagname)
Tag that will provide OMS Record ID
Int32 tag to use for OMS Record ID’s. (/OI=tagname)
Enable NdaClient Dll Debug (VMS SCADA build only)
Enables and sets the debug level in the NdaClient Dll. Current selections are 0(disabled)
and 1(enabled). (/NdaDebug=#)
Configure NdaRetries (VMS SCADA build only)
Configures the maximum retries for each host. For example; a value of 2 would retry
each host 2 times before returning a connection error. (/NdaRetries=#)
Additional Parameters
In the space provided the user can enter any additional parameters that are not available
through PI ICU.
44
Quindar Hosts Tab
Override default SCADA host name
Use a different SCADA host, other than the default of “host”. (/SH=host;host;host)
Hosts
Up to 8 hosts can be provided, using a combination of network name, IP address, or
Fully Qualified Domain Name. (/SH=host;host;host)
Validate hosts
Validate the list of hosts provided. This will attempt to resolve host names and Fully
Qualified Domain Names to IP address, and IP addresses to the host name.
Quindar SCADA Interface to the PI System
45
Startup Command File
Command-line Parameters
Parameter
/at
Optional
Default: Use SCADA
system for timestamps.
Description
Adjust SCADA timestamp to that of PI Time. This parameter only
pertains to the situation when the interface will collect data on an
exception basis. If /at is specified, the time offset between the PI
Server and the SCADA System (delta) will be added to the timestamp
from the SCADA System. The default is to use the timestamp directly
from the SCADA System.
The delta is checked every 120 seconds and updated whenever the new
delta is more than 5 seconds different than the current delta.
/cr=seconds
Optional
Default:
/cr=600
/ds=state
Optional
When the /cr parameter is specified, the interface uses the supplied
integer value to override the default rate, in seconds, that a demand scan
is performed when running in exception mode. This parameter is
ignored if running in scan mode. The default value is 600 seconds.
Specifies the starting system digital state to use for interface-specific
error statuses if different that the default of 500-505.
Default:
/ds=500
/ec=#
Optional
The first instance of the /ec parameter on the command-line is used to
specify a counter number, #, for an I/O Rate point. If # is not specified,
then the default event counter is 1. Also, if the /ec parameter is not
specified at all, there is still a default event counter of 1 associated with
the interface. If there is an I/O Rate point that is associated with an event
counter of 1, each copy of the interface that is running without /ec=#
explicitly defined will write to the same I/O Rate point. This means
either explicitly defining an event counter other than 1 for each copy of
the interface or not associating any I/O Rate points with event counter 1.
Configuration of I/O Rate points is discussed in the section called “I/O
Rate Tag Configuration.”
For interfaces that run on Windows nodes, subsequent instances of the
/ec parameter may be used by specific interfaces to keep track of
various input or output operations. Subsequent instances of the /ec
parameter can be of the form /ec*, where * is any ASCII character
sequence. For example, /ecinput=10, /ecoutput=11, and
/ec=12 are legitimate choices for the second, third, and fourth event
counter strings.
/f=SS
or
/f=SS,SS
or
/f=HH:MM:SS
or
/f=HH:MM:SS,
hh:mm:ss
Required for reading
46
The /f parameter defines the time period between scans in terms of
hours (HH), minutes (MM), and seconds (SS). The scans can be
scheduled to occur at discrete moments in time with an optional time
offset specified in terms of hours (hh), minutes (mm), and seconds (ss).
If HH and MM are omitted, then the time period that is specified is
assumed to be in seconds.
Each instance of the /f parameter on the command-line defines a scan
class for the interface. There is no limit to the number of scan classes
that can be defined. The first occurrence of the /f parameter on the
command-line defines the first scan class of the interface; the second
Parameter
scan-based inputs
Description
occurrence defines the second scan class, and so on. PI Points are
associated with a particular scan class via the Location4 PI Point
attribute. For example, all PI Points that have Location4 set to 1 will
receive input values at the frequency defined by the first scan class.
Similarly, all points that have Location4 set to 2 will receive input
values at the frequency specified by the second scan class, and so on.
Two scan classes are defined in the following example:
/f=00:01:00,00:00:05 /f=00:00:07
or, equivalently:
/f=60,5 /f=7
The first scan class has a scanning frequency of 1 minute with an offset
of 5 seconds, and the second scan class has a scanning frequency of
7 seconds. When an offset is specified, the scans occur at discrete
moments in time according to the formula:
scan times = (reference time) + n(frequency) + offset
where n is an integer and the reference time is midnight on the day that
the interface was started. In the above example, frequency is 60 seconds
and offset is 5 seconds for the first scan class. This means that if the
interface was started at 05:06:06, the first scan would be at 05:06:10, the
second scan would be at 05:07:10, and so on. Since no offset is specified
for the second scan class, the absolute scan times are undefined.
The definition of a scan class does not guarantee that the associated
points will be scanned at the given frequency. If the interface is under a
large load, then some scans may occur late or be skipped entirely. See
the section called Performance Point Configuration for more
information on skipped or missed scans.
Sub-second Scan Classes
Sub-second scan classes can be defined on the command-line, such as
/f=0.5 /f=00:00:00.1
where the scanning frequency associated with the first scan class is
0.5 seconds and the scanning frequency associated with the second scan
class is 0.1 of a second.
Similarly, sub-second scan classes with sub-second offsets can be
defined, such as
/f=0.5,0.2 /f=1,0
Wall Clock Scheduling
Scan classes that strictly adhere to wall clock scheduling are now
possible. This feature is available for interfaces that run on Windows
and/or UNIX. Previously, wall clock scheduling was possible, but not
across daylight saving time. For example,
/f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8
AM. However, after a Daylight Saving Time change, the scan would
occur either at 7 AM or 9 AM, depending upon the direction of the time
shift. To schedule a scan once a day at 8 AM (even across daylight
saving time), use /f=24:00:00,00:08:00,L. The ,L at the end of
the scan class tells UniInt to use the new wall clock scheduling
algorithm.
Quindar SCADA Interface to the PI System
47
Startup Command File
Parameter
Description
/host=host:port
The /host parameter is used to specify the PI Home node. Host is
the IP address of the PI Sever node or the domain name of the PI Server
node. Port is the port number for TCP/IP communication. The port is
always 5450. It is recommended to explicitly define the host and port on
the command-line with the /host parameter. Nevertheless, if either the
host or port is not specified, the interface will attempt to use defaults.
Required
Examples:
The interface is running on a PI Interface Node, the domain name of the
PI home node is Marvin, and the IP address of Marvin is 206.79.198.30.
Valid /host parameters would be:
/host=marvin
/host=marvin:5450
/host=206.79.198.30
/host=206.79.198.30:5450
/id=x
The /id parameter is used to specify the interface identifier.
Highly Recommended
The interface identifier is a string that is no longer than 9 characters in
length. UniInt concatenates this string to the header that is used to
identify error messages as belonging to a particular interface. See the
section called Appendix A: Error and Informational Messages for more
information.
UniInt always uses the /id parameter in the fashion described above.
This interface also uses the /id parameter to identify a particular
interface copy number that corresponds to an integer value that is
assigned to Location1. For this interface, use only numeric characters in
the identifier. For example,
/id=1
/is
Optional
When the /is parameter is specified, the interface is set to scan mode.
The default is exception mode.
Default: Use
exception-mode
processing
/NdaDebug=#
Optional for VMS
SCADA and not valid
for NT SCADA.
Enables and sets the debug level in the NdaClient Dll. Current selections
are 0(disabled) and 1(enabled).
Default: No Debug
/NdaRetries=#
Optional for VMS
SCADA and not valid
for NT SCADA.
Configures the maximum retries for each host. For example; a value of 2
would retry each host 2 times before returning a connection error.
Default: 4
/oi=tagname
48
Required when
reading OMSRecords.
This parameter specifies the tag name to use for the OMSRecord ID.
The OMSRecord Text tag must be specified using /ot=tagname as
well.
Default: None
This tag must be a PI integer 32 tag.
Parameter
/ot=tagname
Required when
reading OMSRecords.
Description
This parameter specifies the tag name to use for the OMSRecord text
strings. The OMSRecord ID tag must be specified using
/oi=tagname as well.
Default: None
This tag must be a PI string tag.
/ps=<string>
The /ps parameter specifies the point source for the interface.
<string> is not case sensitive and can be any unique single or
multiple-character string. For example, /ps=P and /ps=p are
equivalent.
Required
The point source that is assigned with the /ps parameter corresponds to
the PointSource attribute of individual PI Points. The interface will
attempt to load only those PI points with the appropriate point source.
/sh=x;x;x;x
Optional
Default:
/sh=host
/sio
Optional
Override the default SCADA host name of “Host.” If not specified, the
default behavior of the NdaClient API is to use the name “Host.” Note
that multiple host names are separated by semi-colons.
The /sio parameter stands for “suppress initial outputs.” The
parameter applies only for interfaces that support outputs. If the /sio
parameter is not specified, the interface will behave in the following
manner.
When the interface is started, the interface determines the current
Snapshot value of each output tag. Next, the interface writes this value
to each output tag. In addition, whenever an individual output tag is
edited while the interface is running, the interface will write the current
Snapshot value to the edited output tag.
This behavior is suppressed if the /sio parameter is specified on the
command-line. That is, outputs will not be written when the interface
starts or when an output tag is edited. In other words, when the
/sio parameter is specified, outputs will only be written when they are
explicitly triggered.
Quindar SCADA Interface to the PI System
49
Startup Command File
Parameter
/stopstat
or
/stopstat=
digstate
Default:
/stopstat=
”Intf Shut”
Optional
Description
If the /stopstat parameter is present on the startup command line,
then the digital state Intf Shut will be written to each PI Point when
the interface is stopped.
If /stopstat=digstate is present on the command line, then the
digital state, digstate, will be written to each PI Point when the
interface is stopped. For a PI 3 Server, digstate must be in the
system digital state table. For a PI 2 Server, where there is only one
digital state table available, digstate must simply be somewhere in the
table. UniInt uses the first occurrence in the table.
If neither /stopstat nor /stopstat=digstate is specified on
the command line, then no digital states will be written when the
interface is shut down.
Note: The /stopstat parameter is disabled If the interface is
running in a UniInt failover configuration as defined in the UniInt
Failover Configuration section of this manual. Therefore, the
digital state, digstate, will not be written to each PI Point when
the interface is stopped. This prevents the digital state being
written to PI Points while a redundant system is also writing data
to the same PI Points. The /stopstat parameter is disabled
even if there is only one interface active in the failover
configuration.
Examples:
/stopstat=shutdown
/stopstat=”Intf Shut”
The entire digstate value should be enclosed within double quotes
when there is a space in digstate.
Sample PIQuindar.bat File
REM ======================================================================
REM
REM
PIQuindar.bat
REM
REM Sample startup file for the PI Quindar SCADA Interface to the PI System.
REM
REM ======================================================================
REM
REM OSIsoft strongly recommends using the PI ICU to modify startup files.
REM
REM Sample command line
REM
PIQuindar.exe /ps=Quindar /host=XXXXXX:5450 /sn /f=00:00:01 /f=00:00:10 ^
/id=1 /sio /ot=OMSRecordText /oi=OMSRecordID
REM
REM End of PIQuindar.bat File
50
UniInt Failover Configuration
Introduction
UniInt provides support for a hot failover configuration. When properly configured, the
interface will provide a no data loss solution for bi-directional data transfer between the
PI Server and the Data Source given a single point of failure in the system architecture.
This failover solution requires that two copies of the interface be installed on different PI
Interface nodes collecting data simultaneously from a single data source. Each copy of
the interface participating in failover has the ability to monitor and determine liveliness
and failover status. Moreover, the failover operation is automatic and operates with no
user interaction. To assist in administering system operations, the ability to manually
trigger failover to a desired copy of the interface is also supported by this failover
scheme. Implementing the UniInt failover solution requires configuration of the startup
command file, Data Source failover control points, and PI failover control tags as
described below.
Each copy of the interface participating in the failover solution will queue two intervals
worth of data to prevent any data loss. When a failover occurs, there may be a period of
overlapping data for up to 2 intervals. The exact amount of overlap is determined by the
timing and the cause of the failover and may be different every time. Using the default
update interval of 1 second will result in overlapping data between 0 and 2 seconds. The
no data loss claim is based on a single point of failure. If both copies of the interface
have trouble collecting data for the same period of time, data will be lost during that
time.
The failover scheme is described in detail in the UniInt End User Document, which is a
supplement to this manual.
Failover Installation Checklist
The checklist below may be used to configure this Interface for failover. The failover
configuration requires the two copies of the interface participating in failover be installed
on different nodes. Users should verify non-failover interface operation as discussed in
the Installation Checklist section of this manual prior to configuring the interface for
failover operations. If not familiar with UniInt failover configuration, return to this
section after reading the rest of the “UniInt Failover Configuration” section in detail. If a
failure occurs at any step below, correct the error and start again at the beginning of the
checklist. For the discussion below, the first copy of the interface configured and tested
will be considered the primary interface and the second copy of the interface configured
will be the backup interface.
1. Verify non-failover interface operation as described in the Installation Checklist
section of this manual.
2. Use the PI ICU to modify the startup command file to include the proper UniInt
failover startup command-line parameters: /UFO_ID, /UFO_OtherID, and
/UFO_Interval. See the Failover Configuration Using the PI ICU section below.
Quindar SCADA Interface to the PI System
51
51
UniInt Failover Configuration
3. Create and initialize the three required failover control points on SCADA.– one
Active ID and two Heartbeat points. For Windows SCADA the SCADA Explorer
application which is supplied with the Survalent SCADA software is used. For VMS
SCADA, the STNED X-Windows application is used. See the Data Source Failover
Control Point Configuration section below.
4. Create and initialize the six required failover PI Points on the PI Server for the
Active ID and Heartbeat control tags. See the section PI Failover Control Tag
Configuration below for instructions. Pay particular attention to the PointSource,
Location1, and ExDesc attributes.
5. Start the primary interface interactively without buffering.
6. Verify a successful interface start by reviewing the pipc.log file. The log file will
contain messages that indicate the failover state of the interface. A successful start
with only a single interface copy running will be indicated by an informational
message stating “UniInt failover: Interface in the “Primary” state
and actively sending data to PI. Backup interface not
available.”. If the interface has failed to start, an error message will appear in
the log file. For details relating to informational and error messages, refer to the
Messages section below.
7. Verify data on the Data Source.
Using the PICheckNda Connection Test Utility provided with the interface, check
for proper operation of the failover tags on the SCADA system.

The Active ID control point on the SCADA system must be set to the value of
the running copy of the interface as defined by the /UFO_ID startup commandline parameter.

The Heartbeat control point on the SCADA system must be changing values at a
rate specified by the /UFO_Interval startup command-line parameter.
8. Verify data on the PI Server using available PI tools.

The Active ID control tag on the PI Server must be set to the value of the
running copy of the interface as defined by the /UFO_ID startup command-line
parameter.

The Heartbeat control tag on the PI Server must be changing values at a rate
specified by the /UFO_Interval startup command-line parameter.
9. Stop the primary interface.
10. Start the backup interface interactively without buffering. Notice that this copy will
become the primary because the other copy is stopped.
11. Repeat steps 7, 8, and 9.
12. Stop the backup interface.
13. Start buffering.
14. Start the primary interface interactively.
52
15. Once the primary interface has successfully started and is collecting data, start the
backup interface interactively.
16. Verify that both copies of the interface are running in a failover configuration.

Review the pipc.log file for the copy of the interface that was started first.
The log file will contain messages that indicate the failover state of the interface.
The state of this interface must have changed as indicated with an informational
message stating “UniInt failover: Interface in the “Primary”
state and actively sending data to PI. Backup interface
available.”. If the interface has not changed to this state, browse the log file
for error messages. For details relating to informational and error messages,
refer to the Messages section below.

Review the pipc.log file for the copy of the interface that was started last. The
log file will contain messages that indicate the failover state of the interface. A
successful start of the interface will be indicated by an informational message
stating “UniInt failover: Interface in the “Backup” state.”. If
the interface has failed to start, an error message will appear in the log file. For
details relating to informational and error messages, refer to the Messages
section below.
17. Verify data on the Data Source.
Using the PICheckNda Connection Test Utility provided with the interface, check
for proper operation of the failover tags on the SCADA system.

The Active ID control point on the SCADA system must be set to the value of
the running copy of the interface as defined by the /UFO_ID startup commandline parameter.

The Heartbeat control point on the SCADA system must be changing values at a
rate specified by the /UFO_Interval startup command-line parameter.
18. Verify data on the PI Server using available PI tools.

The Active ID control tag on the PI Server must be set to the value of the
running copy of the interface that was started first as defined by the /UFO_ID
startup command-line parameter.

The Heartbeat control tags for both copies of the interface on the PI Server must
be changing values at a rate specified by the /UFO_Interval startup commandline parameter or the scan class which the points have been built against.
19. Test Failover by stopping the primary interface.
20. Verify the backup interface has assumed the role of primary by searching the
pipc.log file for a message indicating the backup interface has changed to the
“UniInt failover: Interface in the “Primary” state and actively
sending data to PI. Backup interface not available.” The backup
interface is now considered primary and the previous primary interface is now
backup.
21. Verify no loss of data in PI. There may be an overlap of data due to the queuing of
data. However, there must be no data loss.
Quindar SCADA Interface to the PI System
53
UniInt Failover Configuration
22. Start the backup interface. Once the primary interface detects a backup interface, the
primary interface will now change state indicating “UniInt failover:
Interface in the “Primary” state and actively sending data to
PI. Backup interface available.” In the pipc.log file.
23. Verify the backup interface starts and assumes the role of backup. A successful start
of the backup interface will be indicated by an informational message stating
“UniInt failover: Interface in “Backup” state.” Since this is the initial
state of the interface, the informational message will be near the beginning of the
start sequence of the pipc.log file.
24. Test failover with different failure scenarios (e.g. loss of PI connection for a single
interface copy). UniInt failover guarantees no data loss with a single point of failure.
Verify no data loss by checking the data in PI and on the data source.
25. Stop both copies of the interface, start buffering, start each interface as a service.
26. Verify data as stated above.
27. To designate a specific interface as primary. Set the Active ID point on the Data
Source Server of the desired primary interface as defined by the /UFO_ID startup
command-line parameter.
Startup Command File Configuration
Note: The /stopstat parameter is disabled If the interface is running in a UniInt failover
configuration as defined by this section. Therefore, the digital state, digstate, will not be
written to each PI Point when the interface is stopped. This prevents the digital state
being written to PI Points while a redundant system is also writing data to the same PI
Points. The /stopstat parameter is disabled even if there is only one interface active in
the failover configuration.
There are three interface startup parameters that control UniInt failover: /UFO_ID,
/UFO_OtherID, and /UFO_Interval. UFO stands for UniInt Failover. The /UFO_ID
and /UFO_OtherID parameters are required for the interface to operate in a failover
configuration, but the /UFO_Interval is optional. All parameters specified must be
configured correctly at interface startup. If they are not, the interface will not start and an
error message will be printed to the interface log file. All existing UniInt startup
parameters (e.g., /ps, /id, /q, /sn, etc.) will continue to function as documented and
must be identical in both copies of the interface. Each of the failover startup parameters
is described below.
54
Parameter
Description
/UFO_Interval=i
The optional /UFO_Interval startup parameter specifies the
failover update interval for unsolicited failover control tags.
Each copy of the interface may define the failover update
interval as specified by the /UFO_Interval=i. However,
both instances of the interface participating in failover must
use the same value, i, specified by the /UFO_Interval=i
parameter. The failover update interval, i, is specified in
milli-seconds with the default being 1000 milli-seconds (1
second.) The update interval controls the rate at which the
Heartbeat points are updated. The update interval also
controls the amount of time the backup copy of the interface
will remain in the backup state when the primary interface
fails to update its Heartbeat point. The backup interface will
assume the role of the primary interface if the Heartbeat point
for the primary interface does not update in 5 failover update
intervals.
Optional
Default: 1000
The setting for this parameter may depend on network
latency. If the failover configuration appears to be thrashing
back and forth between primary and backup, consider
increasing the failover interval.
Default: 1000 milli-seconds
Range: 50 – 20000 milli-seconds
Note: The /UFO_Interval startup parameter can only be
used with unsolicited input interface failover control tags. If the
interface supports scan-based input data and the interface
failover tags are defined as scan-based input tags, the update
interval is determined by the scan class for which the
Heartbeat tags are defined.
/UFO_ID=n
Required
The required /UFO_ID startup parameter specifies the
failover ID for the current copy of the interface. Each copy of
the interface requires a failover ID specified by the
/UFO_ID=n. The value, n, represents the identification
number for this copy of the interface. Each copy of the
interface must also know the failover ID for the redundant
instance of the interface specified by the /UFO_OtherID=m.
The integer number, n, used for /UFO_ID must be different
than the number, m, used for /UFO_OtherID. The failover ID
for both copies of the interface must be a positive integer.
The failover ID is written to the Active ID point when the
interface attempts to become the primary interface. The
failover ID is also used to identify the Heartbeat tag for this
copy of the interface. For more information on Heartbeat tag
configuration, see the “Heartbeat” section below.
Quindar SCADA Interface to the PI System
55
UniInt Failover Configuration
Parameter
/UFO_OtherID=m
Required
Description
The required /UFO_OtherID startup parameter specifies the
failover ID for the redundant copy of the interface. Each copy
of the interface requires a redundant failover ID specified by
the /UFO_OtherID=m. The value, m, represents the
identification number for the redundant interface instance.
Moreover, m must be a positive integer and must differ from
the value, n, provided by the /UFO_ID=n parameter.
The other failover ID is used in conjunction with the Active
ID point to determine when the redundant interface is
primary. The other failover ID is also used to identify the
Heartbeat tag for the redundant interface copy. For more
information on Heartbeat tag configuration, see the section
below.
Sample Interface Startup Files
The following is an example of the PIQuindar interface configured for UniInt failover.
In this example, the interface name is PIQuindar and the interface executable is
PIQuindar.exe. The two interface copies are installed on different PI Interface nodes.
The interface nodes are referred to as IFNode1 and IFNode2. Any additional
command-line parameters needed for the interface would be identically defined in both
startup command-line files. The startup command file for the interface on IFNode1
would be defined as follows:
PIQuindar.exe /PS=E /ID=1 /UFO_ID=1 /UFO_OtherID=2 ^
/host=PISrv:5450
The startup command file for the interface on IFNode2 would be defined as follows:
PIQuindar.exe /PS=E /ID=1 /UFO_ID=2 /UFO_OtherID=1 ^
/host=PISrv:5450
CAUTION: The only differences in the startup parameters for the two interface
copies are the /UFO_ID and /UFO_OtherID startup parameters. These parameters must
be the reverse of one another. A configuration error in these parameters could result in
no data being collected from either copy of the interface.
Data Source Failover Control Point Configuration
In order to synchronize the two copies of the interface, there must be three interface
Control Points residing on the Data Source. There must be one Active ID control point
and one Heartbeat control point for each copy of the interface defined on the Data
Source. Each of these control points must be initialized to a valid value that when read
by the interface would not produce an error that would write a system digital state value
to PI.
56
Note: Data Source control points that cannot be initialized may produce a bad result when
read by UniInt failover and cause the interface to fail. If the points on the Data Source
cannot be initialized and return a bad result to the interface, bypass failover operations by
removing the failover startup command-line parameters and run the interface in a nonfailover configuration. Force an output value from PI to each of the failover control points;
Active ID and Heartbeat points. To output a value for the interface specific Heartbeat
point, each interface participating in failover will need to be run separately. Once the
values on the Data Source are valid, insert the proper failover startup command-line
parameters and restart the interface.
Active ID
The Active ID point is used to identify which copy of the interface will act as the
primary interface sending data to PI. The UniInt failover scheme will determine which
copy of the interface will act as the primary copy and which will act as the backup copy
of the interface. The primary copy of the interface will set the Active ID control point on
the Data Source to the value of its ID as defined by the /UFO_ID=n startup commandline for the primary interface copy. The status of an interface as primary or backup can
be changed by simply changing the value of the Active ID control point on the Data
Source to the ID of the desired primary copy of the interface.
During a normal interface shutdown sequence, the interface will write a value of zero to
the Active ID control point if the interface is in a primary role as indicated by the Active
ID control point. Setting the Active ID control point to zero allows the backup copy of
the interface to quickly transition to the primary role.
Heartbeat
The two Heartbeat control points are used to monitor the liveliness of the failover
configuration. Each copy of the interface is assigned one Heartbeat control point on the
Data Source to write (output) values. Each copy of the interface also reads (input) the
value of the Heartbeat control point of the other interface in the failover configuration.
Simply put, the concept of operation for the Heartbeat control point is for each copy of
the interface to output a Heartbeat value to its Heartbeat control point and read the
Heartbeat value of the other copy of the interface.
During a normal interface shutdown sequence, the interface will write a value of zero to
its Heartbeat control point. Setting the Heartbeat control point to zero allows the backup
copy of the interface to quickly transition to the primary role.
Quindar SCADA Interface to the PI System
57
UniInt Failover Configuration
Control Point Data Flow
The figure below shows the data flow to and from the Heartbeat and Active ID control
points for a typical failover configuration.
QUICS VMS or Windows SCADA Nodes (Typically Redundant)
Quindar Tag 1
Bi-Directional Data
Bi-Directional Data
Quindar Tag n
UFO_Heartbeat1
Write
UFO_Heartbeat1
Value
Read
UFO_Heartbeat2
Value
Read
UFO_Heartbeat1
Value
UFO_Heartbeat2
Write
UFO_Heartbeat2
Value
Write Active ID 2
Write Active ID 1
UFO_ActiveID
Read Active ID
Read Active ID
IFNode1
IFNode2
PI Quindar
Interface
PI Quindar
Interface
/UFO_ID=1
/UFO_ID=2
/UFO_OtherID=2
/UFO_OtherID=1
Procedure for Configuring Failover Points on SCADA Hosts
The procedure for creating failover points on SCADA is dependent on the version of
SCADA being used. The following sections describe the procedure for Windows
SCADA and VMS SCADA.
Configuring Failover Points on Windows SCADA Hosts
Open the Scada Explorer application from the Start Menu. This application is
installed when the Survalent client software is loaded.
58
Expand the Stations node and then right click on one of the stations in the right hand
pane.
Enter a station name to be used for the failover points in the Name field. In these
examples UI will be used throughout. Enter a description if desired and set the User
Type to Pseudo. Click OK to accept.
Quindar SCADA Interface to the PI System
59
UniInt Failover Configuration
There should now be a node in the left panel with the station name that was used above.
Expand the new station point node and select Analog. Right click one of the lines in the
right pane and select new.
60
Enter a name for the point. In this example HB1, HB2 and INTFID are being used for the
Heartbeat1, Heartbeat2 and ActiveId tags respectively. Set the User Type, Device Class
Zone Group and Format Code fields as shown. Enter a description if desired.
Repeat this step for the Heartbeat2 and ActiveId tags.
Configuring Failover Points on VMS SCADA Hosts
Log into the SCADA system.
Create a new station which will contain the failover device points. From the Master
Station Status screen shown above, Press F1 and enter STNED. The Station Editor
screen will appear as shown below.
Quindar SCADA Interface to the PI System
61
UniInt Failover Configuration
Enter the name to be used for the station. In this example the station name is UI. Select
STATION for the point type. Press enter.
62
Fill in the form as shown above. Enter F10 to save.
Quindar SCADA Interface to the PI System
63
UniInt Failover Configuration
Enter the tag name for the Heartbeat 1 tag. In this case we use the name HB1. Click the
ANALOG field. It will begin to flash. Press the Enter key.
64
Enter a description if desired and press F10 to save. Repeat the last two steps for
the Heartbeat2 and the ActiveID tags.
Quindar SCADA Interface to the PI System
65
UniInt Failover Configuration
PI Failover Control Tag Configuration
CAUTION: Users must not delete the failover control tags once the
interface has started. Deleting any of the failover control tags after interface
startup will cause the interfaces in the failover scheme to shutdown and log an
error message to the pipc.log file.
For details on proper configuration of failover control tags, refer to the sections
below. It is highly recommended that the PI System Administrator be consulted
before any changes to failover tags are made.
Synchronization of the two failover interface copies requires the configuration of six PI
tags that are used to send and received data for each of the Data Source failover control
points. All six PI tags must be configured correctly at interface startup or the interface
will not start and an error message will be logged to the interface log file. The six PI tags
are used exclusively for configuring the interface control points. Values written to a
Data Source failover control point are also written to the corresponding PI tag as a
historical record.
The only PI tag attribute used specifically for Data Source failover control point
configuration is the ExDesc attribute. All other PI tag attributes are configured
according to the interface documentation. For example, the PointSource attribute
must match the /ps interface startup parameter or the interface will not load the PI tag.
This interface supports the use a PI Auto Point Synchronization (APS) connector. If
using APS to synchronize the Data Source and PI points, special attention should be paid
to the failover control points and tags. Check that the failover control points and tags are
not included in the APS synchronization scheme. Synchronizing the control points will
cause the failover tags to be edited by APS and may result in possible interface
shutdown.
The interface installation kit includes the sample file,
UniInt_Failover_Sample_PI_Tags.csv that can be used with the Tag
Configurator add-in for Excel to create UniInt failover control tags as well as the failover
state tags. Simply modify the point attributes as described in the sections below and use
the Tag Configurator to create the tags on the PI server. Use this file if the version of PI
ICU is 1.4.0.3 or below since it does not support UniInt Failover configuration. If you
have PI ICU 1.4.1.0 or later you can use the ICU to create the above file in the UniInt
Failover section of the ICU by right clicking the list of Failover tags and choose Export
Point Configuration (.csv).
Note: The PointSource and Location1 attributes must be identical for all the failover
control tags in the failover scheme and must match the PointSource and Location1
attributes for PI tags loaded by the interface. Failure to comply with this rule will result in
the interface failing to start.
66
Active ID
The Active ID tag is used to identify which copy of the interface is currently acting as
the primary interface and is sending data to PI. For a redundant interface installation,
one interface Active ID input tag and one Active ID output tag must be configured. The
Active ID input tag must be configured to read from the Active ID control point on the
Data Source. Whereas the Active ID output tag must be configured to write to the
Active ID control point on the Data Source. The Active ID tags must be successfully
loaded or the interface will log a message to the interface log and fail to start.
To configure the interface Active ID tag, the string [UFO_ActiveID] must be found
in the ExDesc attribute of the PI tag. The UFO_ActiveID keyword is not case
sensitive. The square brackets must be included. The Interface Active ID Tag should be
configured as an integer tag.
During a normal interface shutdown sequence, the interface will write a value of zero to
its Active ID control point and PI tag. Setting the Active ID control point to zero allows
the backup copy of the interface to quickly transition to the primary role.
Active ID Tag Configuration
Attributes
ActiveID IN
Tag
<Intf>_Active_IN <Intf>_Active_OUT
InstrumentTag STA=UI
AcitveID OUT
STA=UI
POI=ActiveID
POI=ActiveID
ExDesc
[UFO_ActiveID]
[UFO_ActiveID]
Location1
Match # in /id=#
Match # in /id=#
Location2
0 (Input)
1 (Output)
Point Source
Match x in /ps=x
Match x in /ps=x
Point Type
Int32
Int32
Shutdown
0
0
Step
1
1
Heartbeat
The Heartbeat tags are used to configure and monitor the liveliness of the failover
configuration. For interface failover to operate properly, each copy of the interface must
have an input Heartbeat PI tag, and an output Heartbeat PI tag. Therefore, a total of four
Heartbeat tags are required.
The input and output tag for each interface copy must have the string
[UFO_Heartbeat:n] in the ExDesc attribute of the PI tag. The value of n must match
the failover ID for the interface as defined by the /UFO_ID or /UFO_OtherID startup
parameter (see example below). The UFO_HeartBeat keyword is not case sensitive.
The square brackets must be included. All four of the Heartbeat tags must be
successfully loaded or the interface will log a message to the pipc.log and fail to start.
Quindar SCADA Interface to the PI System
67
UniInt Failover Configuration
For example: An interface copy participating in failover has /UFO_ID=5 and
/UFO_OtherID=6 on the startup command line indicating that its interface ID is 5 and
the other copy of the interface has an ID of 6. The ExDesc attribute for the input and
output Heartbeat tags for the interface with an ID of 5 must have
[UFO_Heartbeat:5] defined. Likewise, the ExDesc attribute for the input and
output Heartbeat tags for the interface with an ID of 6 must have
[UFO_Heartbeat:6] defined.
During a normal interface shutdown sequence, the interface will write a value of zero to
its Heartbeat control point. Setting the Heartbeat control point to zero allows the backup
copy of the interface to quickly transition to the primary role.
Heartbeat Tag Configuration
Attribute
Heartbeat 1 IN
Heartbeat 1 OUT
Heartbeat 2 IN
Heartbeat 2 OUT
Tag
<HB1>_IN
<HB1>_OUT
<HB2>_IN
<HB2>_OUT
[UFO_Heartbeat:#]
[UFO_Heartbeat:#]
[UFO_Heartbeat:#]
[UFO_Heartbeat:#]
ExDesc
Match # in
/UFO_ID=#
Match # in
/UFO_ID=#
Match # in
/UFO_OtherID=#
Match # in
/UFO_OtherID=#
InstrumentTag
STA=UI
STA=UI
STA=UI
STA=UI
POI=HB1
POI=HB1
POI=HB2
POI=HB2
Location1
Match # in /id=#
Match # in /id=#
Match # in /id=#
Match # in /id=#
Location2
0
1
0
1
Point Source
Match x in /ps=x
Match x in /ps=x
Match x in /ps=x
Match x in /ps=x
Point Type
int32
int32
int32
int32
Shutdown
0
0
0
0
Step
1
1
1
1
Interface State Tag
UniInt failover provides the ability to monitor the operational state of the interface using
a PI tag. Each copy of the interface participating in failover can have an interface state
tag defined to monitor the individual interface. To configure the interface readiness tag,
the string [UFO_State:n] must be found in the ExDesc attribute of the PI tag. The
value of n must match the failover ID for the interface as defined by the /UFO_ID
startup parameter. The UFO_State keyword is not case sensitive. The square brackets
must be included. The Interface state should be configured as a digital tag.
Note: UniInt limits the number of interface state tags to one per interface copy. If more
than one tag is created for a particular copy of the interface, only the last tag sent to the
interface during the startup process will be configured to monitor the interface state. All
other interface state tags for this copy of the interface will be ignored and will not receive
data.
68
Interface State Tag Configuration
Point Attribute
Primary
Backup
Tag
<Tagname1>
<Tagname2>
DigitalSet
UFO_State
UFO_State
ExDesc
[UFO_State:#]
[UFO_State:#]
(Match /UFO_ID=# on primary node)
(Match /UFO_ID=# on backup node)
Location1
Match # in /id=#
Same as for Primary node
PointSource
Match x in /ps=x
Same as for Primary node
PointType
digital
digital
Shutdown
0
0
Step
1
1
Digital State Configuration
OSIsoft recommends configuring digital state set when using interface state tags to
monitor the operational state of the failover configuration. UniInt is capable of
providing six different states (values) that indicate the operational condition of interfaces
participating in failover.
State Number
State Name
Description
0
Off
The interface is not started.
1
Backup_No_DataSource
The interface is connected to the PI Server, but
not to the Data Source. No data is being
collected by the interface.
2
Backup_No_PI
The interface is connected to the Data Source, but
not to the PI Server. The interface is actively
collecting and queuing data. If the primary
interface fails, this copy of the interface will
continue to collect data and if a connection to PI
becomes available, the queued data will be sent to
the PI Server.
The primary copy of the interface has the ability
to monitor the backup interface and is able to set
the state of the backup interface on the PI Server
accordingly.
3
Backup
The interface is connected to PI and the Data
Source. Data is being collected and queued by
the interface. If the primary interface fails, this
copy of the interface will transition to primary
and send its queued data to PI and continue in the
primary role.
4
Transition
The interface is changing roles from Backup to
Primary. The interface remains in this state for
two update intervals.
Quindar SCADA Interface to the PI System
69
UniInt Failover Configuration
State Number
5
State Name
Primary
Description
The interface is connected to both the PI Server
and the Data Source. Data is actively being sent
to the PI Server.
Failover Configuration Using the PI ICU
The use of the PI ICU is the recommended and safest method for configuring the
Interface for UniInt failover. With the exception of the notes described in this section,
the Interface shall be configured with the PI ICU as described in the “Configuring the
Interface with the PI ICU” section of this manual.
Note: With the exception of the /UFO_ID and /UFO_OtherID startup command-line
parameters, the UniInt failover scheme requires that both copies of the interface have
identical startup command files. This requirement causes the PI ICU to produce a
message when creating the second copy of the interface stating that the “PS/ID combo
already in use by the interface” as shown in the figure below. Ignore this message and
click the Add button.
Create the Interface Instance with the ICU
If the interface does not already exist in the ICU it must first be created. The procedure
for doing this is the same as for non-failover interfaces.
PI ICU configuration screen displaying a message that the “PS/ID combo already
in use by the interface.” The user must ignore the yellow boxes, which indicate
errors, and click the Add button to configure the interface for failover.
Configure the Failover Startup Parameters
70
There are three interface startup parameters that control UniInt failover: /UFO_ID,
/UFO_OtherID, and /UFO_Interval. The UFO stands for UniInt Failover. The
/UFO_ID and /UFO_OtherID parameters are required for the interface to operate in a
failover configuration, but the /UFO_Interval is optional. Each of these parameters is
described in detail in Startup Command File Configuration section above. These
parameters must be entered into the UniInt Failover configuration screen of the ICU.
The figure above illustrates the PI ICU failover configuration screen showing the UniInt
failover startup parameters. This copy of the interface defines its ID as 1 (/UFO_ID=1)
and the other interfaces ID as 2 (/UFO_OtherID=2). The other failover interface copy
must define it’s ID as 2 (/UFO_ID=2) and the other interface ID as 1 (/UFO_OtherID=1)
in its ICU failover configuration screen.
Create the Failover State Digital State Set
If you do not have PI ICU 1.4.1.0 or greater follow the setup in the section “Importing
Failover Digital Set to PI via PI SMT 3” below.
The UFO_State digital set is used in conjunction with the failover state digital tag. If the
UFO_State digital set has not been created manually and you have PI ICU 1.4.0.1 or
greater it can be created using the UniInt – Failover section of the ICU by right clicking
any of the failover tags in the tag list and selecting the “Create UFO_State
Digital Set on Server XXXXXX”, where XXXXXX is the PI Server. This
option will be disabled if the set already exists on the PI Server.
Optionally the “Export UFO_State Digital Set” can be selected to create a
comma separated file to be imported via SMT.
Quindar SCADA Interface to the PI System
71
UniInt Failover Configuration
Create the Failover Control and Failover State Tags
The ICU can be used to create a comma delimited file that contains all of the noninterface specific tag attributes configured correctly for failover. This file can be edited
according to the failover tag configuration sections above.
To use the ICU UniInt – Failover section to create this file simply right click any of the
failover tags in the tag list and select “Export Point Configuration” then edit
this file as needed and import with SMT.
Once the failover control and failover state tags have been created the Failover page of
the ICU should similar to the illustration below.
72
Importing Failover Digital Set to PI via PI SMT 3
The interface installation kit includes the digital set file,
UniInt_Failover_DigitalSet_UFO_State.csv, that can be imported using the PI
System Management Tools (SMT) (version 3.0.0.7 or above) application. The procedure
below outlines the steps necessary to create a digital set on a PI Sever using the “Import
from File” function found in the SMT application. The procedure assumes the user has a
basic understanding of the SMT application.
1. Open the SMT application.
2. Select the appropriate PI Server from the PI Servers window. If the desired server is
not listed, add it using the PI Connection Manager. A view of the SMT application
is shown in Figure 1 below.
3. From the System Management Plug-Ins window, select Points then Digital States. A
list of available digital state sets will be displayed in the main window for the
selected PI Server. Refer to Figure 1 below.
4. In the main window, right click on the desired server and select the “Import from
File” option. Refer to Figure 1 below.
Figure 1: PI SMT application configured to import a digital state set file. The PI Servers
window shows the “localhost” PI Server selected along with the System Management
Plug-Ins window showing the Digital States Plug-In as being selected. The digital state
set file can now be imported by selecting the Import from File option for the localhost.
Quindar SCADA Interface to the PI System
73
UniInt Failover Configuration
5. Navigate to and select the UniInt_Failover_DigitalSet_UFO_State.csv file
for import using the Browse icon on the display. Select the desired Overwrite
Options. Click on the OK button. Refer to Figure 2 below.
Figure 2: PI SMT application Import Digital Set(s) window.
This view shows the
UniInt_Failover_DigitalSet_UFO_State.csv file as
being selected for import. Select the desired Overwrite
Options by choosing the appropriate radio button.
6. Navigate to and select the UniInt_Failover_DigitalSet_UFO_State.csv file
for import using the Browse icon on the display. Select the desired Overwrite
Options. Click on the OK button. Refer to Figure 2 above.
7. The UFO_State digital set is created as shown in Figure 3 below.
74
Figure 3: The PI SMT application showing the UFO_State digital set created on the
“localhost” PI Server.
Messages
The following are examples of typical error and informational messages that can be
found in the pipc.log file.
Informational
16-Oct-07 10:38:00
PIQuindar 1> UniInt failover: Interface in the “Backup” state.
Meaning:
Upon system startup, the initial transition is made to this state. While in
this state the interface monitors the status of the other interface
participating in failover. Data received from the data source is queued
and not sent to the PI Server while in this state. The amount of data
queued while in this state is determined by the failover update interval.
In any case, there will be typically no more than two update intervals of
data in the queue at any given time. Some transition chains may cause
the queue to hold up to five failover update intervals worth of data
Quindar SCADA Interface to the PI System
75
UniInt Failover Configuration
16-Oct-07 10:38:05
PIQuindar 1> UniInt failover: Interface in the “Primary” state and
actively sending data to PI. Backup interface not available.
Meaning:
While in this state, the interface is in its primary role and sends data to
the PI Server as it is received. This message also states that there is not a
backup interface participating in failover.
16-Oct-07 16:37:21
PIQuindar 1> UniInt failover: Interface in the “Primary” state and
actively sending data to PI. Backup interface available.
Meaning:
While in this state, the interface sends data to the PI Server as it is
received
Errors
16-Oct-07 17:29:06
PIQuindar 1> Loading Failover Synchronization tag failed
Error Number = 0: Description = [FailOver] or [HeartBeat:n] was
found in the exdesc for Tag Active_IN
but the tag was not loaded by the interface.
Failover will not be initialized unless another Active ID tag is
successfully loaded by the interface.
Cause:
The Active ID or Heartbeat tag is not configured properly.
Resolution:
Check validity of point attributes. For example, make sure Location1
attribute is valid for the interface. All failover tags must have the same
PointSource and Location1 attributes. Modify point attributes as
necessary and restart the interface.
16-Oct-07 17:29:06
PIQuindar 1> One of the required Failover Synchronization points was not
loaded.
Error = 0: The Active ID synchronization point was not loaded. The
input PI tag was not loaded
76
Cause:
The Active ID tag is not configured properly.
Resolution:
Check validity of point attributes. For example, make sure Location1
attribute is valid for the interface. All failover tags must have the same
PointSource and Location1 attributes. Modify point attributes as
necessary and restart the interface.
16-Oct-07 17:38:06
PIQuindar 1> One of the required Failover Synchronization points was not
loaded.
Error = 0: The Heartbeat point for this copy of the interface was
not loaded. The input PI tag was not loaded
Cause:
The Heartbeat tag is not configured properly.
Resolution:
Check validity of point attributes. For example, make sure Location1
attribute is valid for the interface. All failover tags must have the same
PointSource and Location1 attributes. Modify point attributes as
necessary and restart the interface.
17-May-06 09:05:39
PIQuindar 1> Error reading Active ID point from Data source
Active_IN (Point 29600) status = -255
Cause:
The Active ID point value on the data source produced an error when
read by the interface. The value read from the data source must be valid.
Upon receiving this error, the interface will enter the “Backup in Error
state.”
Resolution:
Check validity of the value of the Active ID point on the data source.
Use the SCADA Analog Point View, then modify the value of the point
to a valid value.
17-May-06 09:06:03
PIQuindar 1> Error reading the value for the other copy’s Heartbeat point
from Data source HB2_IN (Point 29604) status = -255
Cause:
The Heartbeat point value on the data source produced an error when
read by the interface. The value read from the data source must be valid.
Upon receiving this error, the interface will enter the “Backup in Error
state.”
Resolution:
Check validity of the value of the Heartbeat point on the data source.
For example, if the value for the Heartbeat point shows up as “***” on
the SCADA Analog Point View, then modify the value of the point to a
valid value.
17-May-06 09:06:03
PIQuindar 1> UniInt failover: Interface in an “Error” state.
Could
not read failover control points.”
Cause:
The failover control points on the data source are returning a value to the
interface that is in error. This error can be caused by creating a noninitialized control point on the data source.”
Resolution:
Check validity of the value of the control points on the data source.
Quindar SCADA Interface to the PI System
77
UniInt Failover Configuration
17-May-06 09:06:03
PIQuindar 1> The Uniint FailOver ID (/UFO_ID) must be a positive integer
Cause:
The UFO_ID parameter has not been assigned a positive integer value.
Resolution:
Change and verify the parameter to a positive integer and restart the
interface.
17-May-06 09:06:03
PIQuindar 1> The Failover ID parameter (/UFO_ID) was found but the ID for
the redundant copy was not found
78
Cause:
The UFO_OtherID parameter is not defined or has not been assigned a
positive integer value.
Resolution:
Change and verify the UFO_OtherID parameter to a positive integer and
restart the interface.
Interface Node Clock
Windows
Make sure that the time and time zone settings on the computer are correct. To confirm,
run the Date/Time applet located in the Windows Control Panel. If the locale where the
interface node resides observes Daylight Saving Time, check the box marked
“Automatically adjust clock for daylight saving changes”. For example,
In addition, make sure that the TZ environment variable is not defined. All of the
currently defined environment variables can be viewed by opening a Command Prompt
window and typing set. That is,
C:> set
Make sure that the TZ environment variable is not defined. All of the currently defined
environment variables can be viewed by opening a Command Prompt window and typing
set. Confirm that TZ is not in the resulting list. If it is, run the System applet of the
Control Panel, click the Environment tab, and remove TZ from the list of environment
variables.
Quindar SCADA Interface to the PI System
79
79
Security
Windows
The PI Firewall Database and the PI Proxy Database must be configured so that the
interface is allowed to write data to the PI Server. See “Modifying the Firewall
Database” and “Modifying the Proxy Database” in the PI Server manuals.
Note that the Trust Database, which is maintained by the Base Subsystem, replaces the
Proxy Database used prior to PI version 3.3. The Trust Database maintains all the
functionality of the proxy mechanism while being more secure.
See “Trust Login Security” in the chapter “PI System Management” of the PI Universal
Data Server System Management Guide.
If the interface cannot write data to the PI Server because it has insufficient privileges, a
–10401 error will be reported in the pipc.log file. If the interface cannot send data to a
PI2 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational
Messages” for additional information on error messaging.
PI Server v3.3 and Higher
Security configuration using piconfig
For PI Server v3.3 and higher, the following example demonstrates how to edit the PI
Trust table:
C:\PI\adm> piconfig
@table pitrust
@mode create
@istr Trust,IPAddr,NetMask,PIUser
a_trust_name,192.168.100.11,255.255.255.255,piadmin
@quit
For the above,
Trust: An arbitrary name for the trust table entry; in the above example,
a_trust_name
IPAddr: the IP Address of the computer running the Interface; in the above example,
192.168.100.11
NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr
PIUser: the PI user the Interface to be entrusted as; piadmin is usually an
appropriate user
Security Configuring using Trust Editor
The Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit
the PI Trust table.
See the PI System Management chapter in the PI Server manual for more details on
security configuration.
Quindar SCADA Interface to the PI System
81
81
Security
PI Server v3.2
For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:
C:\PI\adm> piconfig
@table pi_gen,piproxy
@mode create
@istr host,proxyaccount
piapimachine,piadmin
@quit
In place of piapimachine, put the name of the PI Interface node as it is seen by PI
Server.
82
Starting / Stopping the Interface on Windows
This section describes starting and stopping the interface once it has been installed as a
service. See the UniInt End User Document to run the interface interactively.
Starting Interface as a Service
If the interface was installed a service, it can be started from PI ICU, the services control
panel or with the command:
PIQuindar.exe –start
To start the interface service with PI ICU, use the
button on the PI ICU toolbar.
A message will inform the user of the the status of the interface service. Even if the
message indicates that the service has started successfully, double check through the
Services control panel applet. Services may terminate immediately after startup for a
variety of reasons, and one typical reason is that the service is not able to find the
command-line parameters in the associated .bat file. Verify that the root name of the
.bat file and the .exe file are the same, and that the .bat file and the .exe file are in
the same directory. Further troubleshooting of services might require consulting the
pipc.log file, Windows Event Viewer, or other sources of log messages. See the
section “Appendix A: Error and Informational Messages,” for additional information.
Stopping Interface Running as a Service
If the interface was installed a service, it can be stopped at any time from PI ICU, the
services control panel or with the command:
PIQuindar.exe –stop
The service can be removed by:
PIQuindar.exe –remove
To stop the interface service with PI ICU, use the
Quindar SCADA Interface to the PI System
button on the PI ICU toolbar.
83
83
Buffering
This Interface is not compatible with OSIsoft’s standard buffering mechanisms, PI API
Buffer Server (Bufserv) and the PI Buffer Subsystem (PIBufss). Instead, the Interface …
Buffering refers to an Interface Node’s ability to temporarily store the data that
interfaces collect and to forward these data to the appropriate PI Servers. OSIsoft
strongly recommends that you enable buffering on your Interface Nodes. Otherwise, if
the Interface Node stops communicating with the PI Server, you lose the data that your
interfaces collect.
The PI SDK installation kit installs two buffering applications: the PI Buffer Subsystem
(PIBufss) and the PI API Buffer Server (Bufserv). PIBufss and Bufserv are mutually
exclusive; that is, on a particular computer, you can run only one of them at any given
time.
If you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering.
N-way buffering refers to the ability of a buffering application to send the same data to
each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering, but
OSIsoft recommends that you run PIBufss instead.)
Which Buffering Application to Use
You should use PIBufss whenever possible because it offers better throughput than
Bufserv. In addition, if the interfaces on an Interface Node are sending data to a PI
Collective, PIBufss guarantees identical data in the archive records of all the PI Servers
that are part of that collective.
You can use PIBufss only under the following conditions:

the PI Server version is at least 3.4.375.x; and

all of the interfaces running on the Interface Node send data to the same PI
Server or to the same PI Collective.
If any of the following scenarios apply, you must use Bufserv:

the PI Server version is earlier than 3.4.375.x; or

the Interface node runs multiple interfaces, and these interfaces send data to
multiple PI Servers that are not part of a single PI Collective.
If an Interface Node runs multiple interfaces, and these interfaces send data to two or
more PI Collectives, then neither PIBufss nor Bufserv is appropriate. The reason is that
PIBufss and Bufserv can buffer data only to a single collective. If you need to buffer to
more than one PI Collective, you need to use two or more Interface Nodes to run your
interfaces.
It is technically possible to run Bufserv on the PI Server Node. However, OSIsoft does
not recommend this configuration.
Quindar SCADA Interface to the PI System
85
85
Buffering
How Buffering Works
A complete technical description of PIBufss and Bufserv is beyond the scope of this
document. However, the following paragraphs provide some insights on how buffering
works.
When an Interface Node has Buffering enabled, the buffering application (PIBufss or
Bufserv) connects to the PI Server. It also creates shared memory storage.
When an interface program makes a PI API function call that writes data to the PI Server
(for example, pisn_sendexceptionqx()), the PI API checks whether buffering is
enabled. If it is, these data writing functions do not send the interface data to the PI
Server. Instead, they write the data to the shared memory storage that the buffering
application created.
The buffering application (either Bufserv or PIBufss) in turn

reads the data in shared memory, and

if a connection to the PI Server exists, sends the data to the PI Server; or

if there is no connection to the PI Server, continues to store the data in shared
memory (if shared memory storage is available) or writes the data to disk (if
shared memory storage is full).
When the buffering application re-establishes connection to the PI Server, it writes to the
PI Server the interface data contained in both shared memory storage and disk.
(Before sending data to the PI Server, PIBufss performs further tasks such data validation
and data compression, but the description of these tasks is beyond the scope of this
document.)
When PIBufss writes interface data to disk, it writes to multiple files. The names of these
buffering files are PIBUFQ_*.DAT.
When Bufserv writes interface data to disk, it writes to a single file. The name of its
buffering file is APIBUF.DAT.
As a previous paragraph indicates, PIBufss and Bufserv create shared memory storage at
startup. These memory buffers must be large enough to accommodate the data that an
interface collects during a single scan. Otherwise, the interface may fail to write all its
collected data to the memory buffers, resulting in data loss. The buffering configuration
section of this chapter provides guidelines for sizing these memory buffers.
When buffering is enabled, it affects the entire Interface Node. That is, you do not have a
scenario whereby the buffering application buffers data for one interface running on an
Interface Node but not for another interface running on the same Interface Node.
Buffering and PI Server Security
After you enable buffering, it is the buffering application—and not the interface
program—that writes data to the PI Server. If the PI Server’s trust table contains a trust
entry that allows all applications on an Interface Node to write data, then the buffering
application is able write data to the PI Server.
However, if the PI Server contains an interface-specific PI Trust entry that allows a
particular interface program to write data, you must have a PI Trust entry specific to
86
buffering. The following are the appropriate entries for the Application Name field of a
PI Trust entry:
Buffering Application
Application Name field for PI Trust
PI Buffer Subsystem
PIBufss.exe
PI API Buffer Server
APIBE (if the PI API is using 4 character process
names)
APIBUF (if the PI API is using 8 character
process names)
To use a process name greater than 4 characters in length for a trust application name,
use the LONGAPPNAME=1 in the PIClient.ini file.
Enabling Buffering on an Interface Node with the ICU
The ICU allows you to select either PIBufss or Bufserv as the buffering application for
your Interface Node. Run the ICU and select Tools > Buffering.
Choose Buffer Type
To select PIBufss as the buffering application, choose Enable buffering with PI Buffer
Subsystem.
To select Bufserv as the buffering application, choose Enable buffering with API
Buffer Server.
If a warning message such as the following appears, click Yes.
Quindar SCADA Interface to the PI System
87
Buffering
Buffering Settings
There are a number of settings that affect the operation of PIBuffss and Bufserv. The
Buffering Settings section allows you to set these parameters. If you do not enter values
for these parameters, PIBuffss and Bufserv use default values.
PIBufss
For PIBuffss, the paragraphs below describe the settings that may require user
intervention. Please contact OSIsoft Technical Support for assistance in further
optimizing these and all remaining settings.
Primary and Secondary Memory Buffer Size (Bytes)
This is a key parameter for buffering performance. The sum of these two memory buffer
sizes must be large enough to accommodate the data that an interface collects during a
single scan. A typical event with a Float32 point type requires about 25 bytes. If an
interface writes data to 5,000 points, it can potentially send 125,000 bytes (25 * 5000) of
data in one scan. As a result, the size of each memory buffer should be 62,500 bytes.
The default value of these memory buffers is 32,768 bytes.
88
Send rate (milliseconds)
Send rate is the time in milliseconds that PIBufss waits between sending up to the
Maximum transfer objects (described below) to the PI Server. The default value is 100.
The valid range is 0 to 2,000,000.
Maximum transfer objects
Maximum transfer objects is the maximum number of events that PIBufss sends between
each Send rate pause. The default value is 500. The valid range is 1 to 2,000,000.
Event Queue File Size (Mbytes)
This is the size of the event queue files. PIBufss stores the buffered data to these files.
The default value is 32. The range is 8 to 131072 (8 to 128 Gbytes). Please see the
section entitled, “Queue File Sizing” in the pibufss.chm file for details on how to
appropriately size the event queue files.
Event Queue Path
This is the location of the event queue file. The default value is [PIHOME]\DAT.
For optimal performance and reliability, OSIsoft recommends that you place the PIBufss
event queue files on a different drive/controller from the system drive and the drive with
the Windows paging file. (By default, these two drives are the same.)
Quindar SCADA Interface to the PI System
89
Buffering
Bufserv
For Bufserv, the paragraphs below describe the settings that may require user
intervention. Please contact OSIsoft Technical Support for assistance in further
optimizing these and all remaining settings.
Maximum buffer file size (KB)
This is the maximum size of the buffer file ([PIHOME]\DAT\APIBUF.DAT). When
Bufserv cannot communicate with the PI Server, it writes and appends data to this file.
When the buffer file reaches this maximum size, Bufserv discards data.
The default value is 2,000,000 KB, which is about 2 GB. The range is from 1 to
2,000,000.
Primary and Secondary Memory Buffer Size (Bytes)
This is a key parameter for buffering performance. The sum of these two memory buffer
sizes must be large enough to accommodate the data that an interface collects during a
single scan. A typical event with a Float32 point type requires about 25 bytes. If an
interface writes data to 5,000 points, it can potentially send 125,000 bytes (25 * 5000) of
data in one scan. As a result, the size of each memory buffer should be 62,500 bytes.
The default value of these memory buffers is 32,768 bytes.
Send rate (milliseconds)
Send rate is the time in milliseconds that Bufserv waits between sending up to the
Maximum transfer objects (described below) to the PI Server. The default value is 100.
The valid range is 0 to 2,000,000.
90
Maximum transfer objects
Max transfer objects is the maximum number of events that Buferv sends between each
Send rate pause. The default value is 500. The valid range is 1 to 2,000,000.
Buffered Servers
The Buffered Servers section allows you to define the PI Servers or PI Collective that the
buffering application writes data.
PIBufss
PIBufss buffers data only to a single PI Server or a PI Collective. Select the PI Server or
the PI Collective from the Buffering to collective/server drop down list box.
The following screen shows that PIBufss is configured to write data to a standalone PI
Server named starlight. Notice that the Replicate data to all collective member nodes
check box is disabled because this PI Server is not part of a collective. (PIBufss
automatically detects whether a PI Server is part of a collective.)
The following screen shows that PIBufss is configured to write data to a PI Collective
named admiral. By default, PIBufss replicates data to all collective members. That is, it
provides n-way buffering.
You can override this option by not checking the Replicate data to all collective member
nodes check box. Then, uncheck (or check) the PI Server collective members as desired.
Quindar SCADA Interface to the PI System
91
Buffering
Bufserv
Bufserv buffers data to a standalone PI Server, or to multiple standalone PI Servers. (If
you want to buffer to multiple PI Servers that are part of a PI Collective, you should use
PIBufss.)
If the PI Server to which you want Buferv to buffer data is not in the Server list, enter its
name in the Add a server box and click the Add Server button. This PI Server name must
be identical to the API Hostname entry:
The following screen shows that Bufserv is configured to write to a standalone PI Server
named etamp390. You use this configuration when all the interfaces on the Interface
Node write data to etamp390.
92
The following screen shows that Bufserv is configured to write to two standalone PI
Servers, one named etamp390 and the other one named starlight. You use this
configuration when some of the interfaces on the Interface Node write data to etamp390
and some write to starlight.
Installing Buffering as a Service
Both the PIBufss and Bufserv applications run as a Service.
Quindar SCADA Interface to the PI System
93
Buffering
PI Buffer Subsystem Service
Use the PI Buffer Subsystem Service page to configure PIBufss as a Service. This page
also allows you to start and stop the PIBufss service.
PIBufss does not require the logon rights of the local administrator account. It is
sufficient to use the LocalSystem account instead. Although the screen below shows
asterisks for the LocalSystem password, this account does not have a password.
94
API Buffer Server Service
Use the API Buffer Server Service page to configure Bufserv as a Service. This page also
allows you to start and stop the Bufserv Service
Bufserv version 1.6 and later does not require the logon rights of the local administrator
account. It is sufficient to use the LocalSystem account instead. Although the screen
below shows asterisks for the LocalSystem password, this account does not have a
password.
Quindar SCADA Interface to the PI System
95
Appendix A:
Error and Informational Messages
A string NameID is pre-pended to error messages written to the message log. Name is a
non-configurable identifier that is no longer than 9 characters. ID is a configurable
identifier that is no longer than 9 characters and is specified using the /id parameter on
the startup command line.
Message Logs
The location of the message log depends upon the platform on which the interface is
running. See the UniInt End User Document for more information.
Messages are written to PIHOME\dat\pipc.log at the following times.

When the interface starts many informational messages are written to the log. These
include the version of the interface, the version of UniInt, the command-line
parameters used, and the number of points.

As the interface retrieves points, messages are sent to the log if there are any
problems with the configuration of the points.

If the /db is used on the command line, then various informational messages are
written to the log file.
Messages
The following messages are specific to this interface.
Informational Messages
Starting System state set to nnn
This message indicates the first System state to use for interface specific error
status.
Interface scan mode set to EXCEPTIONMODE or Interface scan mode set to
SCANMODE
This message indicates the mode in which the interface is operating..
Status -103 returned getting value for current OMS Record Number,
defaulting to 0
This message will occur the first time the interface is started after the creation of the
OMS RecordId tag.
Quindar SCADA Interface to the PI System
97
97
Appendix A: Error and Informational Messages
OMS Record Processing tags specified, OMS Record processing will be
done.
The OMS Record processing tags were not found in PI. If OMS Record Processing is
desired then check the values for the /oi and /ot parameters and verify the the specified
tags exist in PI.
Initial Connection to SCADA Host Complete
Indicates a successful initial connection to the SCADA host.
Warning Messages
Illegal interface number (nnn), set to default of 1
The parameter specified via the /in parameter must be an integer number between 1-99.
“nnn” in the example above will represent the actual value specified on the command
line.
Invalid starting state defined via /ds arg, using default of 500
The starting system digital state specified via the /ds parameter must be an integer value
and should be and available system state that has been created via piconfig. Refer to the
section describing the use of system digital states.
Invalid check rate defined via /cr arg, using default of 600
The parameter specified via the /cr parameter must be an integer value specifying the
time period, in seconds, that the interface will perform a demand scan when operating in
Exception Mode.
/SH flag specified – Overriding default SCADA Host name with
NEWSCADAHOST
The default SCADA host name of HOST is being overridden by the value specified in
the /sh parameter. “NEWSCADAHOST” in the example above will represent the host
name to be used instead of the default.
/SH flag syntax incorrect, use /SH=HOSTNAME, using Nda Default
When overriding the default QUICS IV SCADA Host name via the /sh parameter, the
syntax must be /sh=XXXX, where XXXX is the new host name to use.
Initial Connection to SCADA Host FAILED, will keep retrying every 10 secs
The interface was unable to establish the initial connection to the SCADA host. Check
the network connectivity to SCADA hosts on the network.
Syntax error in instrument tag for tag TAGNAME(POINTID), point not added
The syntax in the InstrumentTag field of the tag was incorrect. Refer to the section
describing the use of this field.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
98
Syntax error in instrumenttag[STATION] specification for tag
TAGNAME(POINTID), point not added
The syntax in the STATIONID part of the InstrumentTag field of the tag was incorrect.
Refer to the section describing the use of this field.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
Quindar Station Name STATIONNAME > than max 32 char for tag
TAGNAME(POINTID), point not added
The Station Id has a maximum length of 32 characters for Windows SCADA Systems.
This is an Nda Client restriction.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error and STATIONNAME will indicate the station
name parsed out of the instrumenttag attribute.
Quindar Station Name STATIONNAME > than max 4 char for tag
TAGNAME(POINTID), point not added
The Station Id has a maximum length of 4 characters for VMS SCADA Systems. This is
an Nda Client restriction.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error and STATIONNAME will indicate the station
name parsed out of the instrumenttag attribute.
Quindar Point Name POINTNAME > than max 32 char for tag
TAGNAME(POINTID), point not added
The point name has a maximum length of 32 characters for Windows SCADA Systems.
This is an Nda Client restriction and STATIONNAME will indicate the station name
parsed out of the instrumenttag attribute.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error and POINTNAME will indicate the station name
parsed out of the instrumenttag attribute.
Quindar Point Name POINTNAME > than max 6 char for tag
TAGNAME(POINTID), point not added
The point name has a maximum length of 6 characters for VMS SCADA Systems. This
is an Nda Client.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error restriction and POINTNAME will indicate the
station name parsed out of the instrumenttag attribute. .
Syntax error in InstrumentTag[POINT] specification for tag
TAGNAME(POINTID)
The syntax in the POINTID part of the InstrumentTag field of the tag was incorrect.
Refer to the section describing the use of this field.
Quindar SCADA Interface to the PI System
99
Appendix A: Error and Informational Messages
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
Invalid Parameter specified in InstrumentTag field for tag
TAGNAME(POINTID), point not added
The valid keywords for the InstrumentTag field are STATIONID or POINTID. Only the
first 3 characters of the keyword are used. Refer to the section describing the use of the
InstrumentTag field.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
Invalid PI data type for Quindar Analog type for Tag TAGNAME(POINTID),
point not added
SCADA Analog tags can be converted to either a PI Float or Integer type tag value.
Recreate the PI point with the correct data type.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
Invalid PI data type for Quindar Status type for Tag TAGNAME(POINTID),
point not added
SCADA Status tags can be converted to either a PI Digital or Integer type tag value.
Recreate the PI point with the correct data type.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
Quindar point type not Analog or Status for Tag TAGNAME(POINTID), point
not added
The SCADA point type reported by the Nda Client API was invalid. This condition
should never occur and should be reported to OSI and/or Survalent Technology
Technical support.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
Location2 must be 0(INPUT) or 1(OUTPUT), for Tag TAGNAME(POINTID),
point not added
Location2 must be either 0 for an input(to PI) tag or 1 for an output(from PI).
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
NDA Error Code PDB_NSF (No Such File/Point) returned from NdaGetipn
for tag TAGNAME(POINTID), point not added
The Station ID and Point Name specified in the InstrumentTag field could not be
resolved by the Nda Client API. Make sure that the information specified is a valid
station/point.
100
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
NDA Error Code PDB_BAD (Bad Parameter) returned from NdaGetipn for
tag TAGNAME(POINTID), point not added
This condition should never occur and should be reported to the OSI and /or Survalent
Technology Technical Support.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
Unknown NDA Error Code nnn returned from NdaGetipn for tag
TAGNAME(POINTID), point not added
This condition should never occur and should be reported to the OSI and /or Survalent
Technology Technical Support.
“TAGNAME” and “POINTID” in the example above will be replaced with the PI tag
name and PI point id of the tag in error.
The actual Nda error code is represented by the “nnn” value.
Connection lost to Quindar Host Node(s), attempting reconnection
This condition indicates that connection to all QUICS hosts has failed. Check the
network connectivity of the hosts.
Reconnection successful, resuming operation
This message indicates that the connectivity to the SCADA host(s) has been
reestablished.
Unable to reconnect, will retry every 10 seconds
The first reconnect to the SCADA host failed and will be retried every 10 seconds until
reconnected.
Fatal Error Messages
Error ERRORNUM returned getting value for current OMS Record Number,
intf exiting
A PI error was returned when the interface was attempting to establish the initial value to
use for retrieving OMS Records.
ERRORNUM in the example above will be replaced by the PI error number returned.
Error ERRORNUM returned while finding point id for OMS Record Text tag
OMSTEXTTAG, intf exiting
The /OT parameter was specified but the PI point ID could not be resolved. Make sure
that an integer tag with this point name has been created. Refer to the section describing
OMS Record processing.
ERRORNUM in the example above will be replaced by the PI error number returned and
OMSTEXTTAG will indicate the PI tagname.
Quindar SCADA Interface to the PI System
101
Appendix A: Error and Informational Messages
Error ERRORNUM returned while finding point id for OMS Record ID tag
OMSTEXTTAG, intf exiting
The /OI parameter was specified but the PI point ID could not be resolved. Make sure
that a string tag with this point name has been created. Refer to the section describing
OMS Record processing.
ERRORNUM in the example above will be replaced by the PI error number returned and
OMSTEXTTAG will indicate the PI tagname.
Memory Allocation Error
Memory allocation errors always cause the interface to exit. This condition should never
occur so should be reported to OSI Technical Support. It is OK to restart the interface,
but it may fail again so it should be monitored more carefully until a fix can be uploaded.
System Errors and PI Errors
System errors are associated with positive error numbers. Errors related to PI are
associated with negative error numbers.
Error Descriptions on Windows
On Windows, descriptions of system and PI errors can be obtained with the pidiag
utility:
\PI\adm\pidiag –e error_number
102
Revision History
Date
Author
Comments
20-Oct-2001
JLH
Initial Release – version 1.0.0
16-Nov-2001
CG
Added Test Connection
23-Dec-2002
CG
Changed the title to include QUICS IV SCADA;
changed PINdaTest to PICheckNda to match code
23-Dec-2002
CG
Added to 1.0.1.0
23-Oct-2004
JH
Version 2.0.0.0 Changed to reflect interface updates
to support Windows SCADA
26-Oct-2004
JH
Added Generic ICU Control information
15-Nov-2004
CG
Version 2.0.0.0 Rev B: fixed headers & footers;
fixed section breaks; fixed typos; clarified parameters
01-Dec-2004
JH
Version 2.0.0.0 Rev C: fixed formatting; misc.
clarifications; added dll discussion based on change
in dll name for Windows SCADA
16-Dec-2004
JPM
Added ICU control information to Startup Command
File section
03-Feb-2005
Jhartman
Recompiled with UniInt 3.5.12. Changed all version
information to 2.0.0.1 to reflect change. No
functional changes to interface made.
10-Jun-2005
Chrys
Version 2.0.0.1 Rev B: Fixed installed section to
reflect actual installation.
20-Jun-2005
Jhartman
Recompiled with UniInt 3.5.16. Changed all version
information to 2.0.0.2 to reflect change. No
functional changes to interface made.
21-Jun-2005
MKelly
Added to the Configuring the Interface with PI ICU a
section on browsing for the correct version based on
either the NT SCADA or VMS SCADA version of
the interface.
27-Oct-2007
Jhartman
Upgraded to skeleton version 2.5.2 and added
failover.
11-Dec-2007
Jhartman
Added NdaDebug and NdaRetries command line
parameter information.
14-Dec-2007
MKelly
Version 2.0.1.26, Rev A: Replaced sample batch file,
removed Interface Release Team instructional notes,
fixed references, updated ICU Control screenshots in
UniInt Failover section. Expanded the installation
directory description to include the two sub
directories where the two versions are installed.
Updated the TOC and fixed headers and footers.
Quindar SCADA Interface to the PI System
103 103
Revision History
104
Date
Author
Comments
14-Dec-2007
Janelle
Version 2.0.1.26, Revision B: updated /PS
descriptions throughout document to reflect multiple
character support; changed references to “NT” to
“Windows”
20-Dec-2007
Jhartman
Fixed typo and broken reference.
28-Jun-2008
Jhartman
Version 2.0.2.0; Updated version
23-Jul-2008
MKelly
Version 2.0.2.0, Revision A: Removed NT4.0 from
support features table, changed references to
hyperlinks.
25-Jul-2008
MKelly
Version 2.0.2.0, Revision B: Added terminology
section and updated the Buffering section.
28-Jul-2008
MKelly
Version 2.0.2.0, Revision C: Modified the checklist
and command line parameters section for the /ds=#
command line parameter.