PI Universal Interface (UniInt) 4.6.4
User Guide
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com
PI Universal Interface (UniInt) 4.6.4 User Guide
© 1992-2018 by OSIsoft, LLC. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or
by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission
of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services,
OSIsoft Connected Services, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API,
PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive,
PI DataLink, PI DataLink Server, PI Developer’s Club, PI Integrator for Business Analytics, PI Interfaces,
PI JDBC driver, PI Manual Logger, PI Notifications, PI ODBC, PI OLEDB Enterprise, PI OLEDB Provider,
PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square, PI System, PI System Access, PI Vision,
PI Visualization Suite, PI Web API, PI WebParts, PI Web Services, RLINK, and RtReports are all trademarks
of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective
owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC
license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as
applicable. OSIsoft, LLC.
Version: 4.6.4
Published: 15 February 2018
Contents
Introduction to PI Universal Interface.......................................................................... 1
Related documentation for UniInt interfaces................................................................................................... 1
Operational overview for UniInt interfaces...................................................................................................... 2
UniInt-based interfaces................................................................................................................................... 3
Configuration overview for UniInt interfaces................................................................ 5
Startup configuration overview....................................................................................................................... 5
Create interface instances........................................................................................................................... 5
Configure the batch file............................................................................................................................... 6
Interface security configuration overview........................................................................................................ 7
Read-only and read-write interfaces............................................................................................................ 7
Security requirements and best practices for interfaces...............................................................................8
Create the interface service....................................................................................................................... 12
PI Data Archive security............................................................................................................................. 13
UniInt input and output point configuration...................................................................................................16
PI Point attributes...................................................................................................................................... 16
Input points............................................................................................................................................... 23
Output points............................................................................................................................................ 25
Manually update the snapshot...................................................................................................................26
UniInt failover configuration overview........................................................................................................... 27
Hot, warm, and cold failover modes.......................................................................................................... 29
Configure interface failover....................................................................................................................... 30
Test the failover configuration................................................................................................................... 36
Convert from phase 1 to phase 2 failover....................................................................................................37
Failover configuration for redundant data sources..................................................................................... 38
UniInt failover scenarios............................................................................................................................ 40
Disconnected startup overview......................................................................................................................43
Limitations of disconnected startup...........................................................................................................45
Configure disconnected startup.................................................................................................................46
Build cache files on remote interface machines......................................................................................... 46
Interface buffering overview.......................................................................................................................... 47
Performance and status points...................................................................................................................... 48
Health points............................................................................................................................................. 50
Performance counter points.......................................................................................................................55
Create performance points........................................................................................................................ 58
I/O rate points............................................................................................................................................58
Failover status points.................................................................................................................................59
UniInt interface operation........................................................................................ 61
Start the interface......................................................................................................................................... 61
Stop the interface..........................................................................................................................................61
PI point updates............................................................................................................................................ 62
Modify point check frequency....................................................................................................................62
Process large point updates....................................................................................................................... 62
UniInt diagnostics and troubleshooting......................................................................................................... 63
Start and stop the interface interactively................................................................................................... 63
Disable exception reporting.......................................................................................................................64
Hit, missed, and skipped scans.................................................................................................................. 64
PI Universal Interface (UniInt) 4.6.4 User Guide
iii
Contents
Use command prompts............................................................................................................................. 65
UniInt parameter reference....................................................................................................................... 65
View Windows performance counters........................................................................................................ 77
Error and informational messages............................................................................................................. 78
Technical support and other resources....................................................................... 87
iv
PI Universal Interface (UniInt) 4.6.4 User Guide
Introduction to PI Universal Interface
PI Universal Interface (UniInt) is an OSIsoft framework for interfaces to PI Data Archive. UniInt
provides generic functions required by most interfaces, such as establishing a connection to a
PI Data Archive node and monitoring changes to PI points. The UniInt framework ensures a
standard set of features for OSIsoft interfaces.
PI Universal Interface (UniInt) User Guide explains the operation and functionality provided by
the UniInt framework. Each interface includes a user guide that describes its specific features,
configuration, function and usage.
PI Server naming conventions
OSIsoft is revising its terminology to reflect the growth of the PI System from its original singleserver architecture. In the revised terminology, PI Data Archive is the component that stores
time-series data (formerly called PI Server). PI Server is the entire suite of PI System server
products, and includes both PI Data Archive and PI Asset Framework. This document uses the
revised terminology.
Related documentation for UniInt interfaces
UniInt interfaces use and interact with many other components of the PI System. For related
information, refer to the following documents:
• Read-only versus Read-write Interfaces FAQ
Describes information on the differences between read-only and read-write interfaces, and
instructions for migrating from the read-write to the read-only option. See "Read-only
versus read-write interfaces" in Live Library (https://livelibrary.osisoft.com) .
• PI Server System Management Guide
Documentation for managing PI Server installations, interfaces, PI points, and digital state
sets. See the PI Server System Management Guide (https://techsupport.osisoft.com/
Downloads/File/b481399c-463e-4bcb-a93f-6ef85295263e) for more information.
• PI Server Configuring PI Server Security
Includes information about PI Data Archive security.
See the Configuring PI Server Security (https://techsupport.osisoft.com/Downloads/File/
349de824-dd52-44a3-a8e1-ef0316537f8d) for more information.
• High Availability Administrator Guide
Describes how to configure high availability and manage PI Data Archive and interface
installations when using PI collectives.
See the High Availability Adminstrator Guide (https://techsupport.osisoft.com/Downloads/
File/670d4bab-503f-48e7-9c1a-9fe796c6f8ab).
• PI SDK and PI API Online Help Files
Documentation for the PI SDK and PI API libraries used by interfaces. The embedded help
(.chm) files are located in the %PIHOME%\PIPC\Help\ directory. PIHOME is an environment
PI Universal Interface (UniInt) 4.6.4 User Guide
1
Introduction to PI Universal Interface
variable that contains the PI API installation path. See PI SDK and PI API Online Help Files
(https://techsupport.osisoft.com/Downloads/File/3414fad3-9117-4a22-bcdff01ce9909293).
• PI API Installation Instructions User Guide
Details about installing supporting components, including buffering to prevent data loss if
the connection to PI Data Archive is lost. See PI API Installation Instructions User Guide
(https://techsupport.osisoft.com/Downloads/File/
e77a2bb7-1bc7-4641-9efc-96d038e006eb).
• PI Buffering Manager Help Files
Explains how to configure buffering using PI Buffer Subsystem 4.3 or later, including how to
upgrade from API Buffer Server (bufserv) if needed. The embedded help files are located at
PIPC/HELP/BufferManager.chm. See PI Buffering Manager Help Files (https://
livelibrary.osisoft.com/LiveLibrary/content/en/server-v6/GUID-55D9DB9F-B6CD-46A7B0DE-18FC75E349AB).
• PI Interface Configuration Utility User Guide
Describes how to configure interfaces using PI ICU. See PI Interface Configuration Utility
User Guide (https://livelibrary.osisoft.com/LiveLibrary/web/ui.xql?
action=html&resource=publist_home.html&filter=interface_connector&pub_category=PIInterface-Configuration-Utility).
• Interface logging
For more information about reading message logs, see the OSIsoft Knowledge Base article
How to read new UniInt 4.5.0.x and later Interface message logs (http://
techsupport.osisoft.com/techsupport/nontemplates/KB/article.aspx?id=KB00401).
• Interface release notes
Release-specific information about functional updates, bug fixes, and new features. Release
notes are provided both for the UniInt framework and for each interface. See Interface
Release Notes (https://techsupport.osisoft.com/Downloads/File/
48305bfa-6eda-406f-8448-a0dd508bc005).
Operational overview for UniInt interfaces
Interfaces connect data sources to the PI System by connecting to the data source, collecting
data, and then sending it to PI Data Archive. Interfaces can be configured to run as services, use
failover, limit user access, increase data security, monitor interface performance and status, use
disconnected startup, and in some cases, write data back to the data source.
Interface operation uses the following processes:
1. Startup
2. Connection to PI Data Archive
3. Data collection
4. Point updates
5. Shutdown
2
PI Universal Interface (UniInt) 4.6.4 User Guide
Introduction to PI Universal Interface
Startup
At startup, the interface connects to PI Data Archive. If the PI Data Archive node is unavailable,
the interface continuously attempts to connect. If the interface cannot connect to PI Data
Archive and disconnected startup is not enabled, the interface cannot collect data.
Connection to PI Data Archive
For interfaces to connect to PI Data Archive, PI trusts must be enabled. See security processes.
Data collection
For interfaces where disconnected startup is enabled, the interface loads PI points from a
locally-cached subset of the PI Data Archive point database, and starts collecting data whether
or not it is connected to PI Data Archive.
For interfaces where disconnected startup is not enabled, the interface connects to PI Data
Archive, loads the PI points, and starts collecting data. Time-series data is collected and sent to
PI Data Archive for each successfully loaded point.
Point updates
After starting and loading the PI points, the interface checks and updates point attributes for
points that have been added, changed, or deleted.
Shutdown
The UniInt exit handler will perform an orderly shutdown with the following operations:
1. Write Intf Shut system digital state to all health points for the interface.
2. Write stop status information to failover points or interfaces configured with UniInt failover,
when the interface is the last running instance of the failover pair.
3. Clean up the interface.
4. Update scan-based and event-based input points with the specified digital state for
interfaces with a configured shutdown status,
5. Update the I/O rate point and reset the I/O rate counter to zero for interfaces with an
associated I/O rate.
6. Disconnect from PI Data Archive.
UniInt-based interfaces
UniInt-based interfaces have interface-specific features for connecting to data sources and
archiving data.
Features common to interfaces based on the UniInt framework include:
• Failover
• Disconnected startup
• Writing from input points to PI Data Archive, including performance and status point values
from the interface
• Writing to output points in the data source
PI Universal Interface (UniInt) 4.6.4 User Guide
3
Introduction to PI Universal Interface
PI API and PI SDK
UniInt-based interfaces require the PI API library for functionality. However, some features for
interfaces are only available for earlier versions of PI Data Archive when using the PI SDK
library. Interfaces that use PI SDK cannot use the disconnected startup feature.
PI Data Archive before version 3.4.370 requires PI SDK to be enabled for the following features:
• Extended descriptor (exdesc) and data source name (instrumenttag) attribute lengths
up to 1023 characters
• Full 32-bit values for exception reporting interval attributes (excmin and excmax)
• Multi-character point source attribute
Refer to the specific interface user guide for information about whether PI SDK is enabled, or if
it can be enabled optionally. To enable PI SDK for the interface, see Enable PI SDK.
Interfaces send data using PI API. Buffering for interfaces using PI API requires a different
configuration than buffering for interfaces using PI SDK. For more information about interface
buffering, see Interface buffering overview.
For more information about PI API and PI SDK, see PI SDK and PI API Online Help Files
(https://techsupport.osisoft.com/Downloads/File/3414fad3-9117-4a22-bcdf-f01ce9909293).
Read-write and read-only interfaces
Interfaces can be available as read-write or read-only versions. For increased security,
interfaces without a read-only version can be disabled from writing to the data source. For
more information, see Read-only and read-write interfaces.
4
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
UniInt interfaces start by using a batch file that runs the interface executable. Interfaces are
normally configured to run as services, and do not have their own graphical user interface
(GUI).
To configure each interface installation, use PI Interface Configuration Utility (PI ICU). For each
interface you install, PI ICU provides a pane for configuring interface-specific settings in the
batch file. Run-time settings for the interface are specified in the batch file using command-line
parameters.
UniInt interfaces require configuration for multiple functions. For more information about
using PI ICU to configure interfaces, see PI Server System Management Guide (https://
techsupport.osisoft.com/Downloads/File/b481399c-463e-4bcb-a93f-6ef85295263e).
Topics in this section
• Startup configuration overview
• Interface security configuration overview
• UniInt input and output point configuration
• UniInt failover configuration overview
• Disconnected startup overview
• Interface buffering overview
• Performance and status points
Startup configuration overview
Interfaces can be started in the following ways:
• Run the interface as an automatic Windows service. Recommended for standard operation.
The service starts when the interface node is restarted.
• Run the interface interactively through PI ICU. Used for debugging and viewing messages.
• Start the interface from a command prompt window using a batch (.bat) file.
• Start the interface from a command prompt window by entering the interface executable
(.exe) file name, followed by all parameters, on the command line.
Topics in this section
• Create interface instances
• Configure the batch file
Create interface instances
Interface instances can be created from the interface executable (.exe) file or from a copy of a
batch (.bat) file configured for the interface. Interfaces come with sample .bat files, but these
PI Universal Interface (UniInt) 4.6.4 User Guide
5
Configuration overview for UniInt interfaces
files will not have the necessary configurations, and should not be used for standard
installations.
Procedure
1. Navigate to the interface .exe file and run the installation.
The interface instance is now available in PI ICU.
2. Configure the interface instance using PI ICU.
Refer to this document for more information about configuring UniInt interfaces.
After you finish
Once the startup parameters are configured, create additional interface instances using the
New Windows Interface Instance from BAT File menu option in PI ICU. Make the appropriate
changes to the interface ID parameter and other interface instance-specific startup parameters.
Configure the batch file
The interface .bat file contains a list of parameters that control how the interface runs.
Procedure
1. Open PI ICU and select the interface instance.
Any new interfaces added to PI ICU (using New Windows Interface Instance from EXE and
New Windows Interface Instance from BAT File operations) are included in the drop-down
list.
2. Select or enter your interface parameters.
For more information about configuring interfaces using PI ICU, refer to the PI Interface
Configuration Utility (PI ICU) User Guide.
For more information about parameter settings, see UniInt parameter reference.
Note:
To ensure scan class performance counters are created for all scan classes, define the
scan classes for the interface before creating the interface service, unless you disable
performance counters. To update scan class performance counters after creating the
interface service, see Update performance counters.
3. Save and run the interface to make the parameter changes take effect.
Enable PI SDK
In cases where the PI Data Archive version requires PI SDK for certain PI point attributes,
enable PI SDK.
Note:
Enabling PI SDK will prevent the availability of some UniInt features that use PI API,
including disconnected startup.
6
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Procedure
1. Open PI ICU and select the interface instance.
2. On the UniInt tab, locate PI SDK and select Enable PI SDK.
Interface security configuration overview
Interfaces connect data sources to PI Data Archive. Sending data across networks and through
individual machines within those networks can pose security risks. Therefore, OSIsoft
recommends you configure your interface service accounts using the most secure methods
possible that meet your requirements. Additionally, consider whether the interface needs to
write to a data source before selecting a read-write version of an interface.
Topics in this section
• Read-only and read-write interfaces
• Security requirements and best practices for interfaces
• Create the interface service
• PI Data Archive security
Read-only and read-write interfaces
OSIsoft provides both read-only and read-write options of many interfaces. Due to the inherent
security risks associated with writing to the data source, OSIsoft recommends using the readonly option when possible.
• If you do not need to write to the data source, select the read-only version of the interface.
For more information about the read-only version of the interface, or if you are migrating
from a read-write version to a read-only version and want to view the migration procedure,
see the Read-only versus Read-write FAQ document on Live Library: "Read-only versus readwrite interfaces" in Live Library (https://livelibrary.osisoft.com). If a read-only version is
not available, disable interface updates to the data source. See the Disable read-write
interface updates to the data source section of this document.
• If you need to write to the data source, select the read-write version of the interface and
secure your points in the following ways:
◦ Create an output point whitelist file that is secured so that only authorized users can
change it. See Secure output points using a whitelist file.
◦ Isolate output points using a separate interface instance from the input point interface
instance.
Disable read-write interface updates to the data source
OSIsoft recommends using the read-only option of the interface whenever possible. If a readonly option is not available, perform the following steps to disable outputs using PI ICU to
secure the data source.
PI Universal Interface (UniInt) 4.6.4 User Guide
7
Configuration overview for UniInt interfaces
Procedure
1. Open PI ICU and select the interface instance.
2. On the UniInt tab, select Disable all outputs from PI.
3. Click Apply.
PI ICU saves the configuration.
Security requirements and best practices for interfaces
Interface installation requires an administrator account for the following tasks:
• Installing the interface software
• Creating the interface service account
• Creating, editing, and removing the interface service
• Adding, updating, and removing performance counters
Caution:
Except for interfaces that are included with PI Data Archive, OSIsoft discourages
installing interfaces on the PI Data Archive machine. Interface installations on the PI Data
Archive machine automatically default to the piadmin super-user or the piadmins
group, which have high-level privileges and can expose your system to security risks.
When interfaces are configured to run as a service, the account type used to run the service
depends on the interface. Use an account with the lowest-level privilege required to run the
interface.
Most interfaces based on UniInt version 4.6 or later do not need administrator privileges to
run. Security best practices for running the interface using the least-privileged account apply to
interfaces based on versions of UniInt earlier than 4.6, but this document only discusses
security as it applies to UniInt version 4.6 and later.
Caution:
Running interfaces with accounts that have high-level privileges can expose your system
to security risks. Secure your system using accounts with the lowest-level privilege
required to run the interface, and limit the access rights of the account if possible.
In some cases, the interface service account privileges can be restricted to limit file, folder, and
registry key access. Virtual service accounts, managed service accounts, non-administrator
domain service accounts, and non-administrator local service accounts are the best options for
limiting service account permissions.
Certain types of use cases can restrict access. The main level of restriction for an interface
should be focused on the data source and the \Program Files(x86)\PIPC\ directory on the
machine. You should restrict access to an interface based on the level of security needed to
interact with the data source. Standard PI Interfaces do not need access to the registry. The
only folder/file access for an interface should be focused on the PIPC folder and interface folder
contained within it.
File system access should be determined on an as-needed basis. If you are using an interface
feature that requires reading/writing to a file, you must give the interface service the needed
access to the file. Registry access should normally only be as read only because performance
counters are now created during the interface service creation process. All modifications to
8
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
performance counters must be done by an administrator, using either the ICU or service
editing command line options. Interface services are no longer required to start as an
administrator in order to obtain the interface's performance counters.
Read access to the .bat file and its directory are the minimum file and registry required to run
the interface. The following are needed for writing to files/folders:
• If the interface is using failover, then the interface will need read/write access to the failover
sync file.
• If the interface is using disconnected startup, then the interface will need read/write access
to the Disconnected Start cache sync file.
• If the interface creates or uses its own files and moves these files between folders, the
interface will need access to the base location for these actions.
You will also need PI Data Archive access for the interface and security permissions on the PI
points.
The virtual account permissions on a service allow the service to access a local machine in the
same way it would access any other basic machine. A service that runs using a virtual account
can access network resources by using the identity and credentials of the local computer
account. It's designed to eliminate the overhead of password management for services that
only need resources on their local machine. An account running a service should not be
affected during an interface upgrade.
Note:
If an interface has been upgraded using the Local System account for its services, you
should consider modifying the account being used to run the service. Local System gives a
service the highest level of administrative privileges on a machine and is a security
vulnerability.
Topics in this section
• Service hardening
• Service account types
• Restricted access for service accounts
• Restricted directory access for disconnected startup files
Service hardening
When considering your vulnerability to cyber security threats, OSIsoft recommends making
Windows service hardening a primary focus. Service hardening increases your ability to defend
against cyber security threats by enforcing the principle of least privileges on Windows
services. Windows services are only granted the permissions necessary to maintain
functionality. This approach reduces attack surface area (and damage potential) should a cyber
attack occur.
To better understand the implications of upgrading and how to manually harden services, see
https://tswiki.osisoft.int/kb_articles/kb01160_securing_pi_interfaces_with_service_hardening.
PI Universal Interface (UniInt) 4.6.4 User Guide
9
Configuration overview for UniInt interfaces
Note:
In the UniInt 4.6 doc, the interface applies these techniques on a new install, but the
upgrade will not provide these benefits as stated in the referenced KB. However, if you
upgrade from an earlier version of the interface, service hardening must be applied
manually, as explained in the KB.
Service account types
Windows services can run as the following account types:
• Domain user account
If the service interacts with network services or accesses domain resources like file shares
on other computers, consider using a minimally-privileged domain account. A domain
administrator must create the account before interface services can be configured to use the
account.
• Local user account
If the computer is not part of a domain, a local user account can be used. OSIsoft
recommends that the account not have administrator permissions.
• Local Service account
This is a built-in low-privilege account. This limited access helps safeguard the system if
individual services or processes are compromised. Services that run as the Local Service
account access network resources as a null session without credentials (anonymous). For
service creation, the actual name of the account is NT AUTHORITY\LocalService. For
controlling access to local files or other securable objects, the account name is Local
Service.
• Network Service account
This is a built-in low-privilege account. Services that run as the Network Service account
access network resources by using the credentials of the computer account. For service
creation, the actual name of the account is NT AUTHORITY\NetworkService. For
controlling access to local files or other securable objects, the account name is Network
Service.
• Virtual accounts
Microsoft introduced virtual accounts in Windows 7 and Windows Server 2008 R2. A virtual
account has the same privileges as the built-in Network Service account. The difference is
that a virtual account is specific to one service but multiple services can share the Network
Service account. Therefore, a virtual account can have finer granularity of access control
for local resources (like files and folders) than the Network Service account. On Windows
versions that support virtual accounts, virtual accounts are preferable to the Network
Service or Local Service account for interface services. For service creation, the actual
name of the account is NT SERVICE\servicename, where servicename is the interface
executable name plus the service ID.
• Managed Service Account
A Managed Service Account (MSA) is a type of service account that can be associated with
services on individual machines, and is available for Windows 7 and Windows Server 2008
R2 computers. A managed service account is a domain account, which must be created by a
10
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
domain administrator. The advantage of a managed service account over a user domain
account is that MSA accounts cannot be used to log into a machine, have rotating passwords
that are managed by the domain, and cannot be locked out.
• Local System account
This is the highest privileged built-in account. It has extensive privileges on the local system
and acts as the computer on the network. The actual name of the account is .
\LocalSystem.
Caution:
Avoid using the Local System account for interface services. The Local System
account has higher privileges than administrator accounts.
Security for service account types can be grouped by the level of security they offer:
• Most-secure account types
◦ Non-administrative local account
◦ Non-administrative domain account
◦ Built-in Local Service account
◦ Built-in Network Service account
◦ Built-in virtual service account
◦ Managed Service Account
• Less-secure account types
◦ Administrative local account
◦ Administrative domain account
• Least-secure account type
Built-in Local System account
Note:
Local and user-domain accounts have password administration issues that require
additional security considerations, which are not discussed in this document.
Restricted access for service accounts
For some service account types, the service account that runs the interface can be restricted so
that it cannot access sensitive folders, files, and registry keys. Access control for folders and
files is performed through property pages in Windows Explorer. Access control for registry
keys is performed through regedit.exe.
Service account types can be grouped by the possible restrictions in the following ways:
• Virtual service accounts, non-administrator Domain and Local Service accounts
Recommended: Restrictions can be configured to individual folder, files, and registry keys.
PI Universal Interface (UniInt) 4.6.4 User Guide
11
Configuration overview for UniInt interfaces
• Local Service and Network Service accounts
Limited restrictions can be configured. Accounts are shared by multiple services, including
Windows services, which require different levels of access.
• Domain or Local Service accounts in Administrators group
Restrictions are difficult to configure. Access is required for administrator-level tasks and
restrictions are not recommended.
• Local System service account
Not recommended: No restrictions are possible.
You must allow access to restricted folders and files for service accounts with lower-level
privileges. Without adding access for the low-privileged account, the interface will not run
properly.
Restricted directory access for disconnected startup files
By default, interfaces install in the %PIHOME% directory under \Program Files or \Program
Files (x86). Both of these folders are protected with restricted access in Windows Vista or
later.
The default location for disconnected startup files is the interface installation folder. To use the
default folder for the cache files on Windows systems that protect the folder, an administrator
must grant the interface service account write access to the interface installation folder.
Otherwise, choose a non-protected folder for the cache files.
Create the interface service
To run an unattended interface as a service that restarts when the computer starts, create a
Windows service for the interface. Use PI ICU to create the interface service.
PI ICU version 1.4.14.18 or later automatically selects the most-secure service account type as
the default to run the interface service, unless you use API Buffer Server (bufserv) buffering. PI
Buffer Subsystem (pibufss) can use the most-secure service account type, but API Buffer Server
must use the Local System account.
PI ICU uses the following defaults for creating services:
• For Windows 7 and Windows Server 2008 R2 and later, uses a Virtual Account
• For Windows Vista and Windows Server 2008 and earlier, uses a Network Service account
Note:
Follow best security practices when selecting your service account type. For information
about interface security, see Security requirements and best practices for interfaces.
In some case it may not be possible to create the interface service using PI ICU. In these cases,
see the OSIsoft Knowledge Base article How do you create a new PI Interface Windows service
(https://techsupport.osisoft.com/Troubleshooting/KB/KB00324).
12
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Before you start
Unless performance counters for the interface are disabled, define the scan classes before you
create the interface service. For more information about scan classes, which are defined using
the f startup parameter, see Standard parameters.
Procedure
1. In PI ICU, select the interface instance and navigate to the Service page.
2. Select either Auto or Manual in the Startup Type area.
3. Ensure the buffering service is added in the Dependencies list.
If the buffering service has not been added, select the buffering service from the Installed
services list and click < to move it to the Dependencies list.
4. Click Create.
After you finish
Once the interface service is created, you can optionally restrict access to folders and files
through the property page in Windows Explorer. You can also restrict registry key access
through regedit.exe. Consider whether or not the interface requires access to specific files
or folders before restricting access permissions for the service.
PI Data Archive security
Interfaces use security processes and components to connect to PI Data Archive.
PI Data Archive security processes
In order for the interface to connect to PI Data Archive, the interface service account must be
authenticated and authorized for communications. Interfaces use the following security
processes:
• Authentication
The process of confirming the identity of a user from credentials or other evidence provided
by the user, such as a password.
• Authorization
The process of determining whether the user has permission to perform certain operations.
PI Data Archive provides the following three authentication methods:
◦ PI trust authentication. This method is required for interface service authentication.
◦ Password authentication. This method does not support unattended Windows services.
◦ Windows integrated security: This method is not supported by PI API.
After authentication validates the identity claim, authorization determines what actions the
user can perform in the PI Data Archive. For more information about PI Data Archive security,
see the manual Configuring PI Server Security.
When an interface successfully authenticates through a trust, the interface is granted the
access rights for the associated identity, user, or group.
PI Universal Interface (UniInt) 4.6.4 User Guide
13
Configuration overview for UniInt interfaces
PI Data Archive security components
A PI trust is associated with one PI identity. The trust connects a client to the PI Data Archive
object permissions using matching authentication credentials.
Interfaces use the following security components:
• PI identity
PI identities are the link between Windows authentication and PI Data Archive
authorization. Each PI identity represents a set of access permissions to PI Data Archive.
• PI users and PI groups
Special types of PI identities that can be associated with the PI trust.
Caution:
Avoid using the piadmin super-user or the piadmins group. These built-in users and
groups have high-level privileges that can pose security risks.
The piadmin super-user permissions cannot be restricted. The piadmins group is enabled
by default with permissions necessary for administrator-level tasks and should not be
restricted. Additional built-in PI identities have either no default write permissions or no
default permissions at all.
• PI trust
A set of credentials that maps a machine, application, or a Windows domain or local account
to a specific identity on PI Data Archive.
PI trusts for interface and buffering services are contained in a database. Use PI System
Management Tools (PI SMT) or the piconfig command-line utility to view, create new trusts,
and modify existing trusts. Optionally, use Buffering Manager to set up and manage trusts
for buffering.
Note:
OSIsoft recommends the use of PI Identities rather than PI Trusts wherever possible.
• PI point security
Permissions for the identity to access PI points can be restricted using the data access
(dataaccess) and point access (ptaccess) attributes for each point. Multiple points can
be configured at once using the PI Tag Configurator plug-in for Excel, available with PI SMT.
Procedure
1. Create the PI identity for the interface.
2. Enable PI Data Archive access for the PI identity.
Create the PI identity for the interface
The PI identity controls access to objects in PI Data Archive. The recommended best practice
for PI Data Archive security is to use an identity that has only the access rights which are
necessary for the interface to operate.
Use PI SMT to create PI identities and PI trusts, and update mappings between trusts and
identities. Optionally, use Buffering Manager to create the trust for the buffering application.
14
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Procedure
1. Choose an existing PI identity for the interface or create a new PI identity.
Note:
Select an identity with a lower privilege level. OSIsoft discourages using highlyprivileged identities in PI trusts for interfaces.
You can create trusts based on PI API application names for more secured trusts for the
interface.
2. Create a PI trust that maps to the PI identity and matches the credentials of the interface.
OSIsoft recommends using two or more matched items in a trust (commonly referred to as a
2+ Trust). These matched items are the interface application name, interface node name,
and IP address.
Trusts are required for each interface instance and executable that connects to PI Data
Archive. The minimum required trusts are one for the interface and one for the buffering
subsystem. During setup, creating trusts for apisnap and PI-SDK utilities is helpful for
testing communication between the interface node and PI Data Archive.
Enable PI Data Archive access for the PI identity
Use PI SMT or piconfig to allow the interface access to start and write data to PI Data Archive.
Use PI Tag Configurator in PI SMT to configure point permissions for large point counts. The PI
trust database is also sometimes referred to as the trust table.
Procedure
1. Grant the PI identity in the PI trust that authenticates the interface instance the following
permission:
PI database security
Permission
PIPOINT
r
2. Grant the same database security permissions to each instance of the interface.
3. Configure all the PI points created for the interface to grant the interface read and possibly
write access to the points. To grant the interface access to the points, set the permissions for
the PI identity assigned to the PI trust for the interface. Configure access using the point
security (ptsecurity) and data security (datasecurity) attributes. Necessary access
depends on the buffering configuration:
◦ For interface instances that access interface points, grant read permission in the point
security attribute.
◦ For interface instances running on unbuffered interface nodes, where the interface
instance sends point updates directly to PI Data Archive, grant read and write access to
the PI identity in the PI trust that authenticates the interface instance using the data
security attribute.
◦ For interfaces running on buffered interface nodes, where the interface instance sends
point updates to the buffering application which then relays updates to PI Data Archive,
grant read access to the PI identity in the PI trust that authenticates the interface
instance.
PI Universal Interface (UniInt) 4.6.4 User Guide
15
Configuration overview for UniInt interfaces
PI point database security
Permission
ptsecurity
r
datasecurity (for unbuffered data)
r, w
datasecurity (for buffered data)
r
UniInt input and output point configuration
Interfaces read data from data sources and sometimes write data to data sources using PI
points in PI Data Archive. A PI point stores a series of time-stamped measurements, such as
temperature readings from a tank meter every five minutes. Input points store data from
devices (data sources), and output points send data from PI Data Archive to devices.
PI points are also used to track the performance and status of interfaces. For more information,
see Performance and status points.
Some point attributes have an interface-specific application. For details, refer to the interface
user guide for which you are configuring points.
To configure points, you can use PI SMT. To configure large point counts, you can use the PI Tag
Configurator, a Microsoft Excel plug-in.
For more details about configuring and managing PI points, refer to PI Server System
Management Guide (https://techsupport.osisoft.com/Downloads/File/b481399c-463e-4bcba93f-6ef85295263e).
Topics in this section
• PI Point attributes
• Input points
• Output points
• Manually update the snapshot
PI Point attributes
The attributes stored in a PI point specify its name, data type, associated interface instance,
adjustments to the point value, and additional data collection configurations. The attributes
listed below are ones used by UniInt; indivitual interfaces may use additional attributes, so you
should look at the user guides for each of your interfaces. Additionally, information about all PI
Point attributes and classes is available in the "PI Server documentation" in Live Library
(https://livelibrary.osisoft.com). Choose your server version and view the topic Point
classes and attributes .
Topics in this section
• Point association attributes
• Point security attributes
• Data collection attributes
16
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Point association attributes
PI point attributes used to associate the point with the data source and interface instance
include the point name (or tag), point source, interface instance, extended descriptor,
instrument name, and trigger source point.
Topics in this section
• Tag
• PointSource
• Location1
• Extended descriptor attribute
• Instrument name attribute
• Trigger source name attribute
Tag
The Tag attribute (or tag name) is the name for a 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.
Follow these rules for naming PI points:
• The name must be unique in the PI Data Archive.
• The first character must be alphanumeric, the underscore (_), or the percent sign (%).
• Control characters such as linefeeds or tabs are illegal.
• The following characters also are illegal: * ’ ? ; { } [ ] | \ ` '‘"“
Length
Depending on the version of the PI API and the PI Data Archive, this interface supports Tag
attributes whose length is at most 255 or 1023 characters. The following table indicates the
maximum length of this attribute for all the different combinations of PI API and PI Data
Archive versions.
PI API
PI Data Archive
Maximum Length
6.0.2 or later 4.370.x or later
4.370.x or later
1023
6.0.2 or later
Earlier than 3.4.370.x
255
Earlier than 1.6.0.2
4.370.x or later
255
Earlier than 1.6.0.2
Earlier than 3.4.370.x
255
If the PI Data Archive version is earlier than 3.4.370.x or the PI API version is earlier than
1.6.0.2, and you want to use a maximum Tag length of 1023, you need to enable the PI SDK. See
*** SDK options*** for information.
PI Universal Interface (UniInt) 4.6.4 User Guide
17
Configuration overview for UniInt interfaces
PointSource
The PointSource attribute contains a unique, single or multi-character string that is used to
identify the PI point as a point that belongs to a particular interface.
Location1
Location1 indicates to which copy of the interface the point belongs. The value of this attribute
must match the /id command-line parameter.
Extended descriptor attribute
The extended descriptor (exdesc) attribute is used by interfaces to configure multiple
settings. UniInt extended descriptors use keywords to configure performance points, trigger
points, failover control points, and interface health points.
The syntax for each extended descriptor depends on the type of point being configured, and
many exdesc settings are interface-specific. Refer to the interface manual for details.
Instrument name attribute
The instrument name (instrumenttag) attribute usually identifies the origin of the data that
the PI point receives, such as a point, address or location on a device. The use of this attribute
is interface-specific. Refer to the interface manual for details.
Trigger source name attribute
The trigger source name (sourcetag) attribute is the name of the PI point that triggers an
output point update.
Note:
If the source point name length exceeds 80 characters, you must use the source point
mapping (scriptid) attribute, due to a limitation of PI API.
Point security attributes
You can configure security for PI point attributes and PI point data by restricting user access.
For each point, you can restrict user access using the following point attributes:
• Point security attribute
The point security (ptsecurity) attribute controls which users can read and make changes
to PI point attributes.
The PI identity in the PI trust that authenticates the interface instance must be granted read
access by the ptsecurity attribute of every PI point that the interface services.
• Data security attribute
The data security (datasecurity) attribute controls which users can read or edit PI point
data values.
18
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
The PI identity in the PI trust that authenticates the interface instance must be granted read
access by the datasecurity attribute of every PI point that the interface instance services.
If the interface is used without a buffering application, write access also must be granted. If
the interface is used with a buffering application, the buffering application requires write
access, but the interface does not.
For more information about interface security, see Security requirements and best practices for
interfaces.
Data collection attributes
Interfaces use scan, scan class, data type, digital state set, valid and typical point value,
exception and compression, and shutdown attributes to determine how data is collected and
archived.
Topics in this section
• Scan
• Location4
• Data type attribute
• Digital state set attribute
• Valid point value attributes
• Typical point value attribute
• Exception reporting attributes
• Compression attributes
• Shutdown
Scan
By default, the Scan attribute has a value of 1, which means that scanning is turned on for the
point. Setting the Scan attribute to 0 turns scanning off. If the Scan attribute is 0 when the
interface starts, a message is written to the log and the point is not loaded by the interface.
There is one exception to the previous statement.
If any PI point is removed from the interface while the interface is running (including setting
the Scan attribute to 0), SCAN OFF will be written to the PI point regardless of the value of the
Scan attribute. Two examples of actions that would remove a PI point from an interface are to
change the point source or set the Scan attribute to 0. If an interface-specific attribute is
changed that causes the point to be rejected by the interface, SCAN OFF will be written to the
PI point.
Location4
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. In addition, points in the first scan class will be configured for exception data
collection. Points in all other scan classes will be configured to collect archive data.
Specify scan frequency and optional offset using the following format:
PI Universal Interface (UniInt) 4.6.4 User Guide
19
Configuration overview for UniInt interfaces
HH:MM:SS.##,HH:MM:SS.##
Data type attribute
The data type ( pointtype) attribute specifies what type of data is stored in the PI point.
Example data types are strings, integers, and digital values. Unless the interface documentation
specifies otherwise, only string and blob type data can be saved to a string PI point. UniInt does
not convert integer, float, or digital values to string values.
Device data types do not need to match PI point data types exactly, but the data types must be
compatible. For example, integer values from a device can be sent to floating-point or digital PI
points. Similarly, a floating-point value from the device can be sent to integer or digital PI
points, although the values might be truncated.
To determine which data types are supported by an interface, refer to the interface
documentation.
For details about PI Data Archive data types, refer to the PI Server Management Guide (https://
techsupport.osisoft.com/Downloads/File/b481399c-463e-4bcb-a93f-6ef85295263e).
Digital state set attribute
For digital PI points, the digitalset attribute specifies the name of the associated digital
state set. For more information about digital state sets, see the PI Server System Management
Guide. See PI Server System Management Guide (https://techsupport.osisoft.com/Downloads/
File/b481399c-463e-4bcb-a93f-6ef85295263e).
Valid point value attributes
Valid point values for the PI point limit what values can be written to points. The following
attributes are used to set valid point values:
• Zero attribute
The lowest valid value for a point is defined in the zero attribute.
• Span attribute
The range of valid point values is defined in the span attribute.
The span attribute value is added to the zero attribute value to specify the highest possible
valid value for the point.
The zero and span attributes are required for numeric points, because the settings affect the
data representation in PI Data Archive for these point types. Setting these attributes for other
point types can affect data collection, especially if the compression and exception specifications
are specified using the percentage point attributes. For digital points, PI Data Archive sets zero
and span internally.
Typical point value attribute
The typical point value (typicalvalue) attribute is used to specify a reasonable value for the
PI point. Default typical point value is 50.
20
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Required for numeric points if the default value (50) does not fall within the minimum and
maximum valid point values defined with the zero and span attributes.
Exception reporting attributes
To minimize the data that is stored and transmitted over the network, you can use exception
reporting to filter out value changes that are not meaningful.
Filtering takes place on the interface node. Values are sent to PI Data Archive if they exceed the
specified deadband or have a timestamp that differs from the preceding value outside the
bounds of the specified minimum or maximum, also known as the deadband. The deadband is
defined by the specified deviation or percentage of the span. When exception values are stored,
the preceding value is also stored, to accurately reflect the trend (the value and time stamp
before the value fell outside the deadband).
For more information about exception reporting, refer to the following resources:
• To determine if your interface has implemented exception reporting that differs from
standard UniInt, consult the interface documentation.
• For more information about exception reporting, see the PI Server System Management
Guide. See PI Server System Management Guide (https://techsupport.osisoft.com/
Downloads/File/b481399c-463e-4bcb-a93f-6ef85295263e).
• For recommendations about configuring exception reporting settings, see the OSIsoft
Knowledge Base article What are recommended Exception and Compression settings
(https://techsupport.osisoft.com/Troubleshooting/KB/3226OSI8).
The following attributes define the exception reporting settings:
• Minimum exception reporting interval
Minimum frequency interval (excmin) value, in seconds. Using this value, the interface will
not record values more frequently than the specified interval. If a value arrives before the
specified time has elapsed, it is not sent to PI Data Archive.
• Maximum exception reporting interval
Maximum frequency interval (excmax) value, in seconds. Using this value, the interface will
write values to PI Data Archive no less frequently than the specified interval.
Set excmax to 0 to disable exception reporting.
• Exception deviation
The exception deviation, or deadband, value is stored in the excdev attribute, and specifies
how much a value must differ from the previous value before it is considered to be a
significant value.
Set the exception deviation to a value, in engineering units, that is slightly smaller than the
precision of the data source instrument.
• Exception deviation percentage
The exception deviation percentage value is stored in the excdevpercent attribute, and
specifies how much a value must differ from the previous value before it is considered to be
a significant value, as a percentage of the span value.
PI Universal Interface (UniInt) 4.6.4 User Guide
21
Configuration overview for UniInt interfaces
The excdev attribute is related to excdevpercent attribute as shown in the equation: excdev
= excdevpercent * span / 100. If either attribute is changed, the other is automatically
updated to be compatible.
Compression attributes
Compression settings enable you to store just enough data to reproduce the signal, discarding
any data that is not significant. Compression is performed on PI Data Archive unless PI Buffer
Subsystem is running on the interface node, in which case compression is performed on the
interface node by PI Buffer Subsystem.
For more information about compression, see the PI Server System Management Guide
(https://techsupport.osisoft.com/Downloads/File/b481399c-463e-4bcba93f-6ef85295263e).
The following attributes define the compression settings:
• Minimum compression reporting interval
Minimum frequency (compmin) attribute value, in seconds for recording updates. Values are
recorded to PI Data Archive no more frequently than the specified interval.
• Maximum compression reporting interval
Maximum time (compmax) attribute value, in seconds, for recording values from the
interface to PI Data Archive.
• Compression deviation
The compression deviation (compdev) attribute, or deadband, is the acceptable variation
used to determine the amount of variation that is considered meaningful. The interface
records exceptions, or values whose variation exceeds the deadband.
• Compression deviation percentage
The compression deviation percentage value is stored in the compdevpercent attribute
and specifies what percentage of the span attribute constitutes an exception.
The compdev attribute is related to the compdevpercent attribute as shown in the equation
compdev = compdevpercent * span / 100. If either attribute is changed, the other
attribute is automatically updated to be compatible.
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 Data Archive
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 parameter is specified.
22
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
To configure PI Shutdown Subsystem to write SHUTDOWN events only for PI points that have
their shutdown attribute set to 1, edit the \PI\dat\Shutdown.dat file, as described in the PI
Server System Management Guide (https://techsupport.osisoft.com/Downloads/File/
b481399c-463e-4bcb-a93f-6ef85295263e).
SHUTDOWN events can be disabled from being written to PI points when the PI Data Archive 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
Shutdown.dat file, as discussed in the PI Data Archive manuals.
Bufserv and PIBufss
It is undesirable to write shutdown events when buffering is being used. Bufserv and PIBufss
are utility programs that provide the capability to store and forward events to a PI Data
Archive, allowing continuous data collection when the PI Data Archive is down for
maintenance, upgrades, backups, and unexpected failures. That is, when the PI Data Archive is
shutdown, Bufserv or PIBufss will continue to collect data for the interface, making it
undesirable to write SHUTDOWN events to the PI points for this interface. Disabling Shutdown
is recommended when sending data to a Highly Available PI Data Archive collective. Refer to
the Bufserv or PIBufss manuals for additional information.
Input points
Input points record data that interfaces receive from data sources and send to PI Data Archive.
Input points can be scan-based, unsolicited, or trigger-based, and use the location4 attribute in
the following ways:
Scan-based input points
Values are sent to the points at the frequency configured for the point’s scan class. To assign a
scan class to a point, set the location4 attribute to a scan class. Scan classes are defined with
the f parameter. For more information about the scan class parameter, see Standard
parameters.
Unsolicited input points
Some interfaces do not poll for data, because the data source controls the timing of data sent to
the interface. For details about configuring such unsolicited input points, refer to the interface
documentation. Because these points are not scanned, the location4 attribute should be set
to 0.
Trigger-based input points
Trigger-based input points are updated when a new value is sent to the snapshot of a specified
trigger point. Because these points are not scanned, the location4 attribute should be set to
0.
Configure input trigger points
To configure trigger-based input points, configure the following point attributes.
PI Universal Interface (UniInt) 4.6.4 User Guide
23
Configuration overview for UniInt interfaces
Procedure
1. Configure the scan class. Set location4 to 0.
2. Specify the trigger point name and the condition in the extended descriptor (exdesc)
attribute.
You can specify the trigger point in the exdesc attribute in three ways:
◦ event='trigger_point_name'
◦ trigger='trigger_point_name'
◦ trig='trigger_point_name'
The trigger point name must be in single quotes.
The following table shows valid conditions for the extended descriptor (exdesc) attribute.
Condition
Description
anychange
Trigger on any change if 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 is triggered on a value
change from 0 to Bad Input, or a change from
Bad Input to 0.
increment
Trigger on any increase in value. System digital
states do not trigger events.
For example, an event is triggered on a value
change from 0 to 1, but not on a change from Pt
Created to 0 or 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, or 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 point.
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.
For example, event='Sinusoid' anychange.
24
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Note:
Data loss can occur for Event Points ( ExDesc contains event='trigger_tag_name'
condition) if the connection to the PI Server is lost. The interface signs up for events
from Update Manager for the source points configured for the Event Points. When
there is no connection, the source point data cannot be sent to PI, nor can updates be
received from the Update Manager for the Event Points. Thus, Event Points will not be
updated during the time period when connectivity is lost, nor can data be recovered
during the period of lost connectivity.
Output points
Output points send data from PI Data Archive through an interface to any external data source
capable of receiving inputs, such as a PLC or a third-party database. Each interface has its own
requirements for configuring output points. For UniInt-based interfaces, outputs are triggered
as opposed to occurring on a regularly-scheduled basis.
There are two ways to trigger new values sent to output points:
• Specify an input point to trigger the output point. The output point will update every time
the input point receives a new value.
• Manually write a new value to the snapshot of the output point itself, triggering output to
the destination.
If the output point is configured correctly, the new value is written to the destination when the
output point is successfully updated. A success status indicates that the output point has been
updated; however, this does not guarantee that the external data source was updated. To verify
data source updates, create a corresponding input point and check its value.
If the interface does not successfully receive a value, it records a digital state that describes the
error.
Topics in this section
• Configure output points
• Secure output points using a whitelist file
Configure output points
Configure the attributes of the output point to specify the input point that will trigger updates.
Note:
The data type of the input point must be compatible with that of the triggered output
point.
Procedure
1. For the triggered output point, configure the sourcetag and pointsource attributes.
a. Set the sourcetag attribute to the tag attribute value of the input point that will trigger
updates.
PI Universal Interface (UniInt) 4.6.4 User Guide
25
Configuration overview for UniInt interfaces
The input point is the PI point that contains the values you want written to the
destination data source.
b. Set the pointsource attribute to match the point source (ps) parameter value of the
interface instance connected to the data source.
The point source of the output point must match the point source of the interface
instance, but the input point can be associated with any point source.
Secure output points using a whitelist file
For enhanced security, create a whitelist of output points to specify authorized point updates to
the data source. When using a whitelist, the interface verifies an output point against the list
before updating the data source.
The whitelist file is a comma-separated values (.csv) file that contains a list of valid output
points and any attributes necessary to specify the output points and their intended location
within the data source.
Additionally, the zero and span attributes can be used to specify the minimum and maximum
values allowed by the output point.
For more information about UniInt security, see Interface security configuration overview.
Procedure
1. Extract a list of output tags from PI Data Archive using the PI Builder add-in for Microsoft
Excel.
The output tags open in a spreadsheet.
2. Delete any output points that you want to disable.
3. For whitelist output points, delete any columns for point attributes that the interface does
not use to associate the output point to the data source.
4. Export the spreadsheet as a .csv file.
5. Copy the whitelist .csv file to the desired location. The default file location is in the
interface installation directory.
a. Edit the file permissions so that the interface service account can read the file and only
authorized users can read and write to it.
6. Use PI ICU to select the Enable Output Point Security option on the UniInt page, or edit
the .bat file for the interface to add the /whitelist=path\filename parameter,
specifying the location and name of the .csv file.
7. Restart the interface.
Manually update the snapshot
You can test trigger point configurations by manually updating a point value to trigger an
update either to the data source or PI Data Archive using PI System Management Tools (PI
SMT).
26
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Procedure
1. Locate the output point in the archive editor.
2. Enter a time stamp value of * (now).
The point value does not need to change to trigger the update. The time stamp must be
more recent than the last time stamp value in PI Data Archive.
3. Click the save icon to update the snapshot to the output point.
Results
Triggered input points will update the archive value. Output points will write to the interface to
update the data source. You can use a visualization tool to see the updated point value, or verify
the update on the data source.
UniInt failover configuration overview
UniInt failover minimizes data loss by enabling a backup interface instance to collect data using
a shared file if the primary interface instance fails. UniInt failover is designed to handle cases
with a single point of failure, either for the interface failing to connect to the data source, or the
interface failing to connect to PI Data Archive.
To configure failover, you create instances of the same interface on two different computers.
Failover configuration modes are hot, warm, or cold.
Note:
Synchronization through the data source (phase 1 failover) is now deprecated and is not
recommended. To migrate to shared file (phase 2) failover, see Convert from phase 1 to
phase 2 failover.
Shared file failover operation
Shared-file UniInt failover uses PI points and a shared file to coordinate failover operation.
Status information from the points is maintained in a shared file, removing the requirement for
a PI Data Archive connection after the instances are running. If the shared file cannot be
accessed, the interface instances read status information from PI Data Archive if it is available.
The first interface instance to start (IF-Node1) acts as the primary interface instance, and the
second interface instance (IF-Node2) acts as the backup. Either interface can be the primary.
Failover seeks to keep a running instance of the interface connected to the data source using
the following process:
1. If IF-Node1 fails, IF-Node2 becomes the primary and takes over transmitting data from the
data source to PI Data Archive.
2. If IF-Node1 is restored and IF-Node2 then fails, IF-Node1 becomes the primary again.
If both IF-Node1 and IF-Node2 can neither connect to PI Data Archive nor the shared file, IFNode1 remains as the primary with the "Primary Error" state and IF-Node2 remains as the
backup with the "Backup Error" state. Data loss is possible if IF-Node1 loses connection to the
data source. The interface with the status "Backup Error" does not collect data, and cannot
become the primary unless it reconnects to either PI Data Archive or the shared file.
PI Universal Interface (UniInt) 4.6.4 User Guide
27
Configuration overview for UniInt interfaces
In a hot failover configuration, each interface instance queues three failover intervals' worth of
data to prevent any data loss. When failover occurs, data for up to three intervals might
overlap. The exact amount of overlap is determined by the timing and the cause of the failover.
For example, if the update interval is five seconds, data can overlap between 0 and 15 seconds.
For more information about UniInt failover scenarios, see UniInt failover scenarios.
Failover with disconnected startup
If the interface instances are configured to use disconnected startup, they can start and trigger
failover in order to continue collecting data, even if PI Data Archive is unavailable, as long as
they both have access to the shared file. If the interface instances do not have access to PI Data
Archive or the shared file, they will both enter Backup No PI state until they reconnect and
establish the primary and backup roles. If buffering has been enabled, the primary interface
instance then sends any data that was collected.
Failover status and keywords
During normal operation, IF-Node1 collects data from the data source and sends it to PI Data
Archive. The interface instances read and write to the shared file to update status information.
To identify failover attributes that are written to the shared file, the interface uses the
heartbeat, active ID, and failover ID failover keywords are defined in the extended descriptor
(exdesc) attribute.
Both IF-Node1 and IF-Node2 perform the following operations simultaneously:
• Update their own heartbeat value at a configured interval
• Monitor the heartbeat value and device status for the other instance
• Check the active ID value in the shared file
Normal operation continues as long as the following conditions are met:
28
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
• The heartbeat value for the primary interface indicates that it is running.
• The active ID point has not been changed manually.
• The device status on the primary interface is good.
• The active ID keyword and its corresponding entry in the shared file are set to the failover
ID of the primary interface instance.
To indicate that it is running, each interface instance refreshes its heartbeat value by
incrementing it at the rate specified by the failover update interval. The heartbeat value starts
at 1 and increments until it reaches 15, at which point it resets to 1.
If the instance loses its connection to PI Data Archive, the value of the heartbeat cycles from 17
to 31. When the connection is restored, the heartbeat value reverts back to the range for a
running interface. During a normal shutdown process, the heartbeat value is set to zero. For
more information about failover status points, see Failover status points.
Failover with collectives
If you have a PI collective and PI Data Archive sends outputs to the data source through the
interface in your deployment, you can use UniInt interface failover to ensure the availability of
the PI Data Archive node that provides outputs. Each interface receives outputs from a specific
PI Data Archive node in the collective. If that PI Data Archive node becomes unavailable, the
interface will no longer receive outputs. However, you can configure each interface to receive
outputs from a different collective member. For more information on configuring interface
outputs for UniInt failover in a PI collective, see the host parameter in Standard parameters
topic.
If the PI Data Archive node connected to the primary interface fails, the backup interface takes
over, receives outputs from its collective member, and reports time-series data to the collective.
The backup interface must remain connected to the data source to trigger this failover
scenario.
Topics in this section
• Hot, warm, and cold failover modes
• Configure interface failover
• Test the failover configuration
• Convert from phase 1 to phase 2 failover
• Failover configuration for redundant data sources
• UniInt failover scenarios
Hot, warm, and cold failover modes
The failover mode specifies how the backup interface instance handles connecting to a data
source and adding points when failover occurs. The sooner the backup interface can take over
data collection, the less data is lost. However, increasing the failover level also increases data
source load and system resource usage.
To determine which mode to use, consider how much data you can afford to lose and how
much workload your system can handle. Be prepared to experiment, and consult your data
source documentation and vendor as needed.
PI Universal Interface (UniInt) 4.6.4 User Guide
29
Configuration overview for UniInt interfaces
UniInt provides three levels of failover: cold, warm and hot. Higher ("hotter") levels preserve
more data in the event of failover, but impose increasing workload on the system.
Hot failover
Hot failover is the most resource-intensive mode. Both the primary and backup interface
instances collect data. No data is lost during failover (unless both the primary and backup
interface nodes fail together), but the data source carries a double workload.
Warm failover
In a warm failover configuration, the backup interface does not actively collect data. The
backup interface loads the list of PI points and waits to collect data until the primary interface
fails or stops collecting data for any reason. If the backup interface assumes the role of primary,
it starts collecting data. Some data loss can occur in a warm failover configuration.
Cold failover
In cold failover, the backup instance does not connect with the data source or load the list of PI
points until it becomes primary. This delay almost always causes some data loss but imposes
no additional load on the data source. Cold failover is required for the following cases:
• A data source can support only one client.
• You are using redundant data sources and the backup data source cannot accept
connections.
Configure interface failover
Configure failover for interfaces using PI ICU.
Procedure
1. Create the primary and backup interface instances.
2. Configure interface buffering.
3. Configure the shared file location.
4. Configure and enable failover in PI ICU.
5. If you are configuring health points, configure them in the following order:
a. Create health points for the first interface node.
b. Create health points for the second interface node.
Topics in this section
• Create paired interface instances for failover
• Configure buffering for failover
• Configure the failover shared file location
• Create UniInt failover points
• Enable UniInt failover
• Set delays for cold failover
30
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Create paired interface instances for failover
Before enabling UniInt failover, configure the primary and backup interface instances for
failover as nearly-identical copies of the same interface. Create the interface instances using PI
ICU.
Multiple instances of an interface may use the same executable (.exe) file without copying and
renaming the interface executable file. PI ICU assigns a new service ID to each interface
instance to distinguish it from other copies of the interface that use the same executable. The
service ID then becomes part of the interface service name.
Procedure
1. Use PI ICU to configure the first interface instance.
2. Create a second interface instance on another machine.
3. Copy the contents of the batch file for the first interface instance and paste them in the
batch file of the second interface instance, or use PI ICU to import the batch file on the
second interface instance.
Copying or importing the batch file ensures the instances are identical.
4. Verify that both instances can collect data.
Note:
Do not run both instances simultaneously.
After you finish
After you create the identical interface instances, configure buffering.
Configure buffering for failover
Configure buffering for UniInt failover using PI ICU. Buffering can be configured to use API
Buffer Server or PI Buffer Subsystem.
Procedure
1. Open PI ICU and select the interface instance.
2. Click Tools > Buffering and configure buffering.
Note:
If PI ICU 1.4.15 or later and PI Buffer Subsystem 4.3 or later are installed, you will be
prompted to configure PI Buffer Subsystem. Accepting this configuration upgrades
your buffering to PI Buffer Subsystem if you previously used API Buffer Server. For
more information about buffering subsystems, see Interface buffering overview and
the PI Interface Configuration Utility User Guide.
3. Verify that buffering is working.
After you finish
After you configure buffering, configure the location of the shared file.
PI Universal Interface (UniInt) 4.6.4 User Guide
31
Configuration overview for UniInt interfaces
Configure the failover shared file location
Interface instances paired for phase 2 UniInt failover both read from and write to a shared
folder to communicate status with each other. Configure the location of this file for both
interface instances.
Caution:
The shared failover file must only be used by a single pair of interface instances,
otherwise detrimental behavior such as interface thrashing will occur
Procedure
1. Create a folder for the shared file.
Note:
OSIsoft recommends creating the folder on a machine that is neither the primary nor
the backup interface instance machine, to ensure the file remains accessible if either
interface node fails. The machine should be a Windows Server platform that has the
Server role configured.
2. Set the folder properties to grant read/write access to the user account that runs the
interface service.
Results
The folder location is used in PI ICU to create the shared binary file for failover.
Create UniInt failover points
Create failover points for each interface instance of the failover pair for UniInt failover. UniInt
failover points are PI points that track the status of the interface instances, and are required to
trigger failover. Create failover points in PI ICU.
Note:
Do not use other tools to create these points.
Procedure
1. Recommended: Create all failover points. Navigate to the Failover tab, right-click within the
PI point list, and then click Create all points (UFO Phase 2).
PI ICU automatically creates all the failover points for the interface instance.
Failover status points and attributes
UniInt uses PI points to track the statuses of the interface instances paired for failover.
Configure failover using PI ICU to create the active ID, heartbeat, state, and device status PI
points on the Failover tab.
Failover status points
The failover points used by the interface instances are:
32
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
• Active ID point
• Heartbeat point for instance 1
• Heartbeat point for instance 2
• Optional:
◦ State point for instance 1 and state point for instance 2
◦ Device status point for instance 1 and device status point for instance 2
Failover point attributes
The point name (tag) attributes for UniInt failover points require a particular syntax. For each
failover point, use the following syntax:
Failover point tag attribute
Attribute syntax
Active ID point tag
PIDataArchiveNameInterfaceGenericName_InstanceID_PointSo
urce_UFO2_ActiveID
Heartbeat point tag
PIDataArchiveNameInterfaceGenericName_InstanceID_PointSo
urce_UFO2_UFO2_Heartbeat_ID
State point tag
PIDataArchiveNameInterfaceGenericName_InstanceID_PointSo
urce_UFO2_UFO2_State_ID
Device status point tag
PIDataArchiveNameInterfaceGenericName_InstanceID_PointSo
urce_UFO2_UFO2_DeviceStatus_ID
The extended descriptor (exdesc) attribute defines UniInt failover control points. Values must
be contained in square brackets and require the following syntax:
Failover point extended descriptor attribute
Attribute syntax
Active ID exdesc
[UFO2_ActiveID]
Heartbeat point exdesc
[UFO2_Heartbeat:failoverID]
State point exdesc
[UFO2_DeviceStat:failoverID]
Device status point exdesc
[UFO2_State:failoverID]
Additionally, set the following attributes for all UniInt failover points:
Additional failover point attributes
Description
compmax
Set to 0.
location1
Set to the interface ID.
PI Universal Interface (UniInt) 4.6.4 User Guide
33
Configuration overview for UniInt interfaces
Additional failover point attributes
Description
location3
For cold failover only. Sets the delay for the
primary interface instance with a good device
status to stay in the primary state before allowing
the backup interface instance with the bad device
status a chance to become primary.
To enable this delay, set location3 to a positive
value, in minutes, for the amount of time the
primary interface instance with a GOOD status will
stay in the primary state before allowing the
backup interface instance with the bad device
status a chance to become primary. The backup
interface instance must actively be reporting a
good heartbeat in order for the primary interface
instance to allow the backup interface instance to
become primary.
To disable this delay, set location3 to 0.
location4
For cold failover only. Sets the delay for the backup
interface instance to allow the interface instance
assuming primary role to clear a bad device status
by using a delay. Only valid when location3 is set
for delay.
To configure this delay, set location4 to a positive
value, in minutes, for the backup interface instance
with a good device status to stay in backup-ready
state before reverting to normal failover operation.
If the primary interface instance did not update to
a good device status during the delay, the backup
attempts to resume primary role.
Default: location4 value of 0, which is a 5-minute
delay.
location5
For cold failover only. Sets the delay for the backup
interface instance to attempt to assume primary
role when both primary and backup interface
instances have equally bad device status. Only
valid when location3 is set for delay.
To configure this delay, set location5 to a positive
value, in minutes, for the backup interface instance
to wait for the primary interface instance to update
to a better device status before attempting to
assume primary role.
Default: location5 value of 0, which is a 10minute delay.
34
pointsource
Set to the point source for all points maintained by
this interface instance.
pointtype
Must be set to Int32.
shutdown
Must be set to 0.
step
Must be set to 1.
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Enable UniInt failover
Use PI ICU to configure and enable UniInt failover for the interface.
Before you start
Before you enable UniInt failover, create both instances of the interface, configure buffering,
and configure the shared file location.
Procedure
1. For the first interface instance, click UniInt > Failover.
2. Select Enable UniInt Failover and choose Phase 2.
3. In the Synchronization File Path box, specify the location of the shared file.
Note:
See KB article https://techsupport.osisoft.com/Troubleshooting/KB/KB00443
(https://techsupport.osisoft.com/Troubleshooting/KB/KB00443). Also see KB article
https://techsupport.osisoft.com/Troubleshooting/KB/KB00444 (https://
techsupport.osisoft.com/Troubleshooting/KB/KB00444).
4. From the UFO Type list, choose the level of failover.
Options for failover are HOT, WARM, or COLD. For more information about failover modes, see
Hot, warm, and cold failover modes.
5. Browse to the location of the other interface instance.
Note:
Ensure the interface failover ID (ufo_id) parameter settings of each interface
instance match the other interface failover ID (ufo_otherid) parameter settings of
the other interface instance.
6. Optional: Configure the following settings:
◦ Set the update rate for the heartbeat point if you need a value other than the default of
5000 milliseconds.
◦ If the PI Data Archive node is part of a collective and writes output point data to the data
source, configure the primary and backup instances to connect to different members of
the collective using PI ICU. For each interface instance, perform the following steps:
i. Go to the General page for the interface instance.
ii. In the PI Hostname section, set the Server/Collective and SDK Member boxes to point
to different PI Data Archive hosts for each interface instance. This ensures that data
continues to be written to the data source if one of the PI Data Archive connections
fail. For more information, see the discussion of failover in the . See High Availability
Administrator Guide (https://techsupport.osisoft.com/Downloads/File/
670d4bab-503f-48e7-9c1a-9fe796c6f8ab).
7. Click Apply.
8. Create the failover digital state set if it has not been created. Right-click the PI point list, and
then click Create UFO_State Digital Set on Server ServerName.
9. On the first interface instance only, right-click the list of failover points and then click Create
all points (UFO Phase 2) to create all the required failover PI points.
PI Universal Interface (UniInt) 4.6.4 User Guide
35
Configuration overview for UniInt interfaces
10. Click Close to save.
Set delays for cold failover
In a cold failover configuration, you can configure delays that ensure that the interface
instances update their status in a coordinated way, to prevent one or the other from being
locked into the role of backup.
Consider setting delays if you need to run the interface on an unreliable network where the
communication between the interface and the data source is disrupted on a regular basis. On a
robust and reliable network, you do not need to set delays.
Procedure
1. To configure delays, set the following attributes of the active ID failover point:
◦ location3
Specifies how long to wait after assuming the backup role before resuming the primary
role and resetting status.
Default: location3 set to 0 (cold failover is disabled).
◦ location4
Specifies how long to wait before assuming the primary role if the other instance has a
bad status.
Default: location4 set to 0 (5 minutes).
◦ location5
When both the primary and backup interface instances have equally bad device status,
specifies how long to wait before the backup transitions to primary.
Default: location5 set to 0 (10 minutes).
For more information, see Failover status points and attributes.
Test the failover configuration
To test the UniInt failover configuration, use PI ICU to start the interface interactively and view
the output.
36
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Procedure
1. Start the first interface instance interactively using PI ICU.
The first interface to start assumes the role of primary interface.
2. Check the output to verify that failover is correctly configured.
Successful failover output would look similar to the following example:
OPCpi> 1 1> UniInt failover: Successfully Initialized: This Failover ID
(/UFO_Id): 1 Other Failover ID (/UFO_OtherId): 2
The primary interface runs and collects data.
3. Start the second interface instance.
4. Check the output to verify that failover for the second instance is configured correctly.
The second interface instance assumes the role of backup interface.
5. Stop the primary interface.
6. Verify that the backup interface has detected the absence of the primary instance and has
taken over data collection. Examine the output for the following messages:
> UniInt failover: Interface is attempting to assume the
"Primary" state.
Waiting 2 ufo intervals to confirm state of other copy.
Fri Jun 22 11:43:26 2012
> UniInt failover: Waited 2 ufo intervals, Other copy has
not updated our activeId, transition to primary.
Fri Jun 22 11:43:26 2012
> UniInt failover: Interface in the "Primary" state and
actively sending data to PI.
7. Check for data loss in PI Data Archive.
For example, use PI ProcessBook to display a data trend.
8. Test failover with different failure scenarios. Verify the level of data loss by checking the
data in PI Data Archive and on the data source.
For hot failover, there should be no data loss. For warm and cold failover, there will be a
short period of data loss during the failover transition.
For example, test loss of the PI Data Archive connection for one of the instances.
After you finish
Once you have tested failover for a successful configuration, stop both copies of the interface,
start buffering, configure each interface instance as a service, and then start both copies of the
interface.
Convert from phase 1 to phase 2 failover
Phase 1 failover, which relies on the data source, is deprecated. OSIsoft recommends phase 2
failover, which uses a shared file. Convert from phase 1 failover to phase 2 failover. Repeat this
task for each interface instance.
PI Universal Interface (UniInt) 4.6.4 User Guide
37
Configuration overview for UniInt interfaces
Before you start
Use PI ICU to delete the phase 1 failover points for the UniInt failover pair, as they are no longer
needed for phase 2 failover.
Procedure
1. Open PI ICU and select the interface instance.
2. Navigate to UniInt Failover and select the Enable UniInt Failover checkbox and the Phase 2
radio button.
3. Enter the shared file location in the Synchronization File Path field. Both interface instances
must have access to this file location.
Note:
Both interface instances must have access to this file location. For more information,
see KB article https://techsupport.osisoft.com/Troubleshooting/KB/KB00443
(https://techsupport.osisoft.com/Troubleshooting/KB/KB00443). Also see KB article
https://techsupport.osisoft.com/Troubleshooting/KB/KB00444 (https://
techsupport.osisoft.com/Troubleshooting/KB/KB00444).
4. If not already created, right-click the tag list and then select Create UFO_State Digital Set
on Server ServerName.
5. Right-click the tag list and select Create all points (UFO Phase 2).
6. Save the configuration.
7. Configure and save the settings for the second interface instance using the previous steps,
using the interface instance ID of the first interface instance as failover ID number of the
second interface instance.
8. Return to the first interface instance in PI ICU, configure the failover ID number to match the
interface instance ID number of the second interface instance, and save.
Failover configuration for redundant data sources
The following figure illustrates the UniInt failover configuration for redundant data sources.
38
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Redundant data source failover configuration
Configure failover for redundant data sources
If you are running redundant data sources, you can configure multiple UniInt failover pairs that
use the same point source and interface ID.
PI Universal Interface (UniInt) 4.6.4 User Guide
39
Configuration overview for UniInt interfaces
Procedure
1. For each pair of interface instances, when you set the exdesc attribute of the active ID
point, ensure the failover ID values always refer to the correct interface instance for the
failover pair.
For more information about the syntax for the exdesc attribute of the active ID failover
point, see Failover status points and attributes.
UniInt failover scenarios
UniInt failover can be triggered in multiple scenarios. The following topics describe different
causes of failover in UniInt interfaces version 4.6 or later.
For each failover pair, assume that IF-Node1 is the first interface instance to start. IF-Node1
assumes the primary interface instance role and writes data to PI Data Archive. IF-Node2 is the
interface instance that acts as backup and queues data. During failover transitions, the
interface instances will change state, as described in the following failover scenarios.
Topics in this section
• Graceful primary shutdown triggers failover
• Primary instance stops updating the heartbeat point
• Manual failover
• Primary instance loses connection to PI Data Archive
• Interface instances attempt to be primary at the same time
• UniInt phase 2 failover: miscellaneous scenarios
Graceful primary shutdown triggers failover
A graceful shutdown performs the following operations:
1. IF-Node1 stops.
2. At exit, the IF-Node1 writes a value of 0 to its heartbeat point and active ID point.
3. IF-Node2 reads the active ID point, detects the 0 value, and assumes the role of primary.
In some cases, IF-Node1 stops shortly after IF-Node2 checks the value of the failover control
points. When this happens, IF-Node2 will not recognize that IF-Node1 has shut down for an
additional failover update interval. This does not result in data loss for hot failover
configurations because the backup queues data for two failover intervals and any additional
time where the primary status was unknown. When IF-Node2 assumes the primary role, it
sends queued data to PI Data Archive. This results in overlapping data for one or two failover
update intervals.
When IF-Node2 assumes the role of primary interface, it performs the following operations:
1. IF-Node2 writes its failover ID to the active ID point.
2. IF-Node2 waits for two failover update intervals, then verifies that the active ID value is the
same as its failover ID. Depending on the verification result, IF-Node2 performs the
following actions:
40
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
◦ If the active ID is equal to the failover ID for IF-Node1, IF-Node2 remains in the backup
role.
◦ If the active ID is the same as the failover ID for IF-Node2, IF-Node2 assumes the primary
interface role and sends queued data to PI Data Archive.
Primary instance stops updating the heartbeat point
There are multiple situations that cause IF-Node1 to stop updating the heartbeat point.
Examples include:
• The interface crashes.
• The interface is unable to write data for any reason.
• The interface hangs in a function call that does not return.
When IF-Node1 stops updating the heartbeat point, IF-Node2 determines if it should assume
primary role using the following operations:
1. At each failover update interval, IF-Node2 reads and stores the value of the heartbeat point
for IF-Node1.
2. If the heartbeat point value for IF-Node1 does not update between two readings, IF-Node2
stops deleting older queued data and continues to queue data until it knows the state of IFNode1.
3. If the heartbeat point value for IF-Node1 does not update for four failover update intervals,
IF-Node2 transitions to the AssumingControl state.
4. In AssumingControl state, IF-Node2 immediately writes its failover ID to the active ID
point.
5. IF-Node2 remains in AssumingControl state for two update intervals.
6. If the active ID value is still the same as the failover ID for IF-Node2, IF-Node2 transitions to
PrimaryReady state and writes all queued data to PI Data Archive.
Total failover time for this scenario is between three and five failover update intervals. The
exact amount of time depends on when IF-Node1 failed and when IF-Node2 read the control
points. When using hot failover, overlapping data is dependent on this timing.
Manual failover
To initiate manual failover, IF-Node2 must be in an equal or better state than IF-Node1. For
example, failover will not trigger when IF-Node1 has a connection to PI Data Archive and IFNode2 does not. IF-Node2 knows the state of IF-Node1 by reading the value of the heartbeat
point for IF-Node1.
Manual failover results in overlapping data for two failover update intervals.
You trigger manual failover by changing the value of the active ID point from the failover ID for
IF-Node1 to the failover ID for IF-Node2.
Changing the active ID point value on PI Data Archive causes the interfaces to perform the
following operations:
PI Universal Interface (UniInt) 4.6.4 User Guide
41
Configuration overview for UniInt interfaces
1. IF-Node2 reads the active ID value from both the shared file and the point.
2. IF-Node2 recognizes that the values are not the same and waits two failover update
intervals to determine which value is correct.
3. When IF-Node1 does not update the active ID point, IF-Node2 updates the active ID value in
the shared file and assumes primary role.
4. IF-Node1 reads the new active ID value in the shared file and immediately assumes backup
role.
Primary instance loses connection to PI Data Archive
In cases where failover is configured to ensure a continuous data flow to PI Data Archive to
prevent disruption of operations dependent on the server connection, primary and backup
interfaces perform the following operations:
1. If any PI API functions return a value indicating PI Data Archive is unavailable, UniInt
signals that IF-Node1 lost its connection to PI Data Archive, and IF-Node1 writes a value to
its heartbeat point. This value increments from 17 to 31 in a cycle that repeats while IFNode1 is disconnected.
2. During its next failover cycle, IF-Node2 reads the value in the heartbeat point indicating a
failover trigger and stops discarding queued data.
3. At the following failover update, IF-Node2 tries to read the value of the active ID point on PI
Data Archive.
4. For a successful active ID read, IF-Node2 transitions to AssumingControl state and
updates the active ID point value to its own failover ID.
5. IF-Node1 reads the value of the active ID for IF-Node2 and immediately assumes backup
role.
Interface instances attempt to be primary at the same time
In scenarios where both instances of the interface are started at the same time, or both are
running and the data source is started, IF-Node1 and IF-Node2 might both try to assume the
role of primary.
At startup, both copies check the active ID point value and the heartbeat point value for the
backup. The value determines the role of the node:
• Primary: If the interface instance reads its own failover ID, it transitions to the primary role.
This transition takes two failover interval updates for new data to show up in PI Data
Archive.
• Backup: when the interface instance reads the other instance's failover ID, it remains in
backup role and monitors the heartbeat value for the other interface instance. If the
heartbeat value stops updating, the backup transitions to primary. This process takes four
failover update intervals, in order to monitor, verify heartbeat value, assume control, and
update PI Data Archive.
• Unassigned: If both interface instances start at approximately the same time and the active
ID point value is unclaimed, IF-Node1 and IF-Node2 both write their failover ID values to
the active ID point, transition to AssumingControl, and wait two failover update intervals.
42
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Assume IF-Node2 was the last to write its value. At the next failover update interval, IFNode1 reads the failover ID of IF-Node2 as the active ID value and transitions to the backup
role, and IF-Node2 reads its own failover ID and transitions to the primary role. While the
point update is immediate, the delay in role transitions resolves any role conflicts that may
have occurred before the update reached the data source.
UniInt phase 2 failover: miscellaneous scenarios
The following Phase 2 failover scenarios could potentially affect whether the interface
continues to collect and buffer data.
Scenario 1: Access lost to shared file and PI server
This scenario occurs for example, if the NIC goes bad, router/switch goes down, cable is
unplugged, etc. This scenario has two points of failure. Uniint failover is designed to function
correctly for a single point of failure in the system. If an interface loses communication with the
shared file and the PI server, the interface instance will remain in its current state. The
interface will not assume primary if the interface was in backup mode at the time that both
connections went down, and similarly the interface will not transition out of primary if the
interface was in primary mode when both connections went down.
Scenario 2: PI Server Collective architecture
This scenario occurs when primary PI server fails and shared file access fails. Each instance
reads from its designated "/host" and receives outputs from its designated "/host"; therefore,
the interface instance will remain in its current state.
Scenario 3: Disaster recovery
In this scenario, the shared file is on the interface node which has a system failure that requires
the entire node to be rebuilt. In this situation, the interface will failover to the other node and
collect/buffer data. When the failed node is rebuilt, the interface will get back in sync
automatically once the file is created. The file will be created when the interface on the failed
node is started, or if the sync file was backed up on the ghost image. Note that if the sync file
was on a separate machine from the interface nodes and that machine crashed, the sync node
must be restored from a ghost image or created manually. Otherwise, one of the interface
instances would require a restart to create the sync file. Until the sync file is created, failover
would be controlled via PI server reads.
Disconnected startup overview
Disconnected startup allows the interface to start from a local cache file with or without a valid
connection to PI Data Archive. This prevents data loss when an interface starts up without a
connection to PI Data Archive. Disconnected startup should only be configured and enabled
after you have configured the interface and tested your configurations. Buffering must be
configured.
Disconnected startup uses the following processes for an initial startup:
1. The interface connects to PI Data Archive.
2. The interface delays startup and creates two local cache files. One file contains PI point
configuration and the other contains digital state information needed to start the interface.
PI Universal Interface (UniInt) 4.6.4 User Guide
43
Configuration overview for UniInt interfaces
3. The interface synchronizes the cache files to PI Data Archive.
4. The interface service begins data collection.
5. The interface collects and buffers data collected from the data source when no connection to
PI Data Archive is available.
Subsequent disconnected startups use the following processes:
1. The interface starts and checks for the local cache files.
If the cache files are missing or unusable, the interface must recreate them using the initial
startup process.
2. The interface loads points from the cache file instead of PI Data Archive.
3. The interface service begins data collection.
4. The interface collects and buffers data collected from the data source when no connection to
PI Data Archive is available.
Using a local cache for startup has the additional benefit that the interface starts collecting data
more quickly by loading points from the local cache, which is faster than loading points across
the network. For example, an interface with 50,000 associated PI points may take several
minutes to retrieve all the PI points from PI Data Archive. The disconnected startup feature can
reduce the time to load the same 50,000 PI points from the cache file to approximately 10
seconds. Results will vary depending on the system architecture, network latency, and work
load on PI Data Archive.
Point modification and synchronization
Interfaces using the disconnected startup configuration:
• Load points designated for the interface from locally stored cache files.
• Retrieve point information from PI Data Archive during normal updates or during point
synchronization.
• After losing the PI Data Archive connection and reconnecting, the interface synchronizes
interface point configuration data with that of PI Data Archive.
For example, an interface started using the disconnected startup configuration loses its
connection to PI Data Archive due to a network failure. While the interface connection to PI
Data Archive is down, the administrator modifies the point database. When the connection to
PI Data Archive is restored, the interface synchronizes its point cache to match the current
point configuration on PI Data Archive. Without restarting the interface, points that were
created on PI Data Archive while disconnected are added to the interface. Similarly, edited
points are updated in the interface and deleted points are removed from the interface. Avoid
running the interface in disconnected startup mode while making major point modifications to
PI Data Archive, because major point modifications can take a long time to sync with the
disconnected startup file.
Point modification messages
Messages about point modifications that occurred while the interface was running but
disconnected from PI Data Archive are logged to the PI Message Log file after the interface
reestablishes a connection, including information about point creation, editing, or deletion.
These messages appear once per point modification.
44
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
In some cases, an error message may be generated because data is being sent to PI points that
no longer exist on PI Data Archive. Typically, the interface logs one message for a given error
code only once per point that is in error. These informational and error messages are normal
and should require no action by the user.
For more information, see Disconnected startup messages.
Topics in this section
• Limitations of disconnected startup
• Configure disconnected startup
• Build cache files on remote interface machines
Limitations of disconnected startup
Known limitations imposed on an interface running with disconnected startup enabled include
extended attribute length, using PI SDK, and suspended output point updates.
Extended attribute lengths
To maximize the functionality of the disconnected startup configuration, the use of PI Data
Archive version 3.4.370 or later is recommended. PI Data Archive version 3.4.370 or later in
conjunction with PI API version 1.6.1.x or later provides greater field lengths for the tag,
descriptor, exdesc, instrumenttag, and pointsource attributes. Moreover, PI SDK is no
longer required for support of the increased field lengths.
The following table lists the maximum field lengths for a given PI point attribute for the version
of PI Data Archive used. In all cases, the PI API version is assumed to be 1.6.1.x or later to
support disconnected startup.
Maximum attribute lengths
Attribute
PI Data Archive 3.4.370.x or later PI Data Archive earlier than
3.4.370.x
tag
1023
255
descriptor
1023
26
exdesc
1023
80
instrumenttag
1023
32
pointsource
1023
1
Note:
If the actual data stored for the point attribute is greater than the maximum field length
specified in the table, the returned value for the attribute is truncated to the maximum
length for the given PI Data Archive version.
Interfaces using PI SDK
The disconnected startup feature utilizes PI API to retrieve extended point information from PI
Data Archive that is stored in the necessary caching files. Disconnected startup is not
supported if PI SDK is required for the interface to start. The operational need for PI SDK is
interface-specific. Interfaces supporting disconnected startup will explicitly say that
disconnected startup is supported in the Supported Features table of the interface manual.
PI Universal Interface (UniInt) 4.6.4 User Guide
45
Configuration overview for UniInt interfaces
In the case where the interface supports disconnected startup, uses PI SDK by default to
retrieve extended point attribute information, and PI Data Archive is earlier than version
3.4.370, you must define the /pisdk=0 parameter to disable PI SDK before enabling
disconnected startup. For cases where PI Data Archive is later than version 3.4.370, the
interface always uses PI API to retrieve extended attribute information and does not require
disabling PI SDK.
For more information about enabling and disabling PI SDK, see Enable PI SDK.
Suspended output point updates
The interface can start and run in the disconnected startup configuration while PI Data Archive
is unavailable. However, outputs will not function while disconnected from PI Data Archive.
Once the interface establishes a valid connection, outputs from PI Data Archive to the interface
resume normal operation.
Configure disconnected startup
Use PI ICU to configure disconnected startup for the interface.
Procedure
1. In PI ICU, select the interface instance and select Disconnected Startup from the UniInt tab.
2. Select the Enable disconnected startup (with point caching) check box.
3. Required: Configure the cachemode parameter for disconnected startup.
4. Configure optional parameters:
◦ pisdk
If you use PI SDK to retrieve extended point attribute information for points from PI Data
Archive, disable PI SDK by defining /pisdk=0 in the .bat file, or remove any
disconnected startup parameters.
Disconnected startup requires PI API. Some UniInt based interfaces require PI SDK to
retrieve point information if PI API is earlier than version 1.6 or PI Data Archive is earlier
than version 3.4.370.x. In this case, setting the /pisdk=0 startup parameter may not
disable PI SDK, prohibiting the use of disconnected startup. Running disconnected
startup with PI SDK configured to retrieve point attribute information will cause the
interface to log an error message and then shut down.
◦ cachepath
Specify the cache file path.
◦ cachesynch
Specify the cache file synchronization interval.
For more information, see Disconnected startup parameters.
5. Click Apply to save the changes.
Build cache files on remote interface machines
The cache files for disconnected startup can be built from either the interface node or the
remote node for the interface.
46
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Before you start
Building cache files on remote machines requires disconnected startup to be enabled and a
connection from the interface to PI Data Archive.
Procedure
1. Start the interface instance on the remote node.
The interface delays startup and creates two local cache files, one for PI point configuration
and the other for PI digital state information for interface startup.
2. Wait for the interface to synch point information from PI Data Archive, and then transfer the
cache files to the interface node you want to use.
If the node you want to use cannot synch points, use the command line to disable syncing by
setting the parameter /cachesynch=0.
3. Start the interface on the node you want to use.
The interface loads the points from the cache file and begins collecting data.
4. View the message logs to verify that the interface is using the existing cache files on the
correct machine.
Interface buffering overview
The interface node uses buffering to prevent data loss when PI Data Archive is not available.
UniInt interfaces can buffer data to store point values when network communication to PI Data
Archive is unavailable. UniInt disconnected startup requires buffering, and it is highly
recommended for failover. Buffering for interfaces is configured and enabled through PI ICU.
The PI System offers two services to implement buffering at interfaces. Only one of them, PI
Buffer Subsystem, supports buffering for clients. For more information about buffering, see the
"PI Interface Configuration Utility User Guide" in Live Library (https://livelibrary.osisoft.com).
• PI Buffer Subsystem (pibufss)
PI Buffer Subsystem is the best option for most environments, particularly if you use
version 4.3 or later. Starting with version 4.3, PI Buffer Subsystem supports buffering to
multiple servers and collectives. For information about configuring this buffering service,
and the considerations for using PI Buffer Subsystem 4.3 or later, see "PI Interface
Configuration Utility User Guide" in Live Library (https://livelibrary.osisoft.com).
• API Buffer Server (bufserv)
API Buffer Server is needed only by those with unusual configurations, for example, those
connecting to older versions of PI Data Archive.
If the interface is properly configured with buffering, the interface service cannot run unless
the buffering service is also running.
Note:
Correct interface service dependencies are a common troubleshooting point. Ensure the
interface service dependencies for the buffering service are configured correctly.
Without buffering running during a loss of connection to PI Data Archive, any data collected
while the connection is unavailable is permanently lost.
PI Universal Interface (UniInt) 4.6.4 User Guide
47
Configuration overview for UniInt interfaces
Buffering and collectives
PI Buffer Subsystem 4.3 and later can buffer data to multiple independent servers, including
those configured as PI Server collectives. For interfaces to use PI Buffer Subsystem with PI
Server collectives, the PI Data Archive servers must be running PI Data Archive version 3.4.375
or later.
Caution:
API Buffer Server does not detect and validate the PI Server collective configuration. As a
result, API Buffer Server requires manual configuration whenever a collective changes.
Also, because API Buffer Server results in compression at the PI Data Archive machine,
archives at different servers in the collective could contain different records.
Buffering configuration
Use PI Interface Configuration Utility (PI ICU) to configure interface buffering.
The Tools > Buffering option helps you configure buffering. Depending on your current
configuration, this option does one of the following:
• If this computer is configured to buffer data using PI Buffer Subsystem 4.3 or later, the
Buffering Manager window opens and shows a buffering dashboard. The dashboard shows
information about the status of buffering on this computer.
• If this computer is not currently configured to buffer data, and PI Buffer Subsystem 4.3 or
later is installed, you are prompted to configure PI Buffer Subsystem. If you click Yes, the
Buffering Manager window opens and shows the installation wizard, which helps you
configure PI Buffer Subsystem.
• If this computer is configured to buffer data using API Buffer Server (Bufserv), and PI Buffer
Subsystem 4.3 or later is installed, you are prompted to convert to and configure PI Buffer
Subsystem. If you click Yes at both prompts, the Buffering Manager window opens and
shows the upgrade wizard, which helps you upgrade from API Buffer Server to PI Buffer
Subsystem.
• If PI Buffer Subsystem 4.3 is not yet installed, the Buffering window opens for API Buffering
or the earlier version of PI Buffer Subsystem.
For PI Buffer Subsystem 4.3, when configuring an interface to buffer data to a PI Data Archive
server which has not been added to the buffered server list you must enable buffering. Click the
Enable button in the Buffering Status box on the interface General page. To verify that the
buffering status is On , exit PI ICU, then restart and select the interface.
You can use Buffering Manager to configure, monitor, and troubleshoot buffering using PI
Buffer Subsystem. PI Buffer Subsystem is recommended for applications connecting to PI Data
Archive 3.4.375 or later. Older versions of PI Data Archive require API Buffer Server, as do some
sites with custom solutions. See Buffering Manager help (PIPC/HELP/BufferManager.chm)
for more information.
Performance and status points
UniInt provides the following options for monitoring the status and performance of an
interface instance:
48
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
• Health points
PI points that track the interface and data source statuses and other interface-specific
metrics. Health points can be configured in PI ICU and viewed in PI System visualization
tools such as PI SMT, PI ProcessBook, or PI Coresight. Configuring health points is the
recommended method for monitoring interfaces.
OSIsoft recommends using health points to track interface status.
• Performance counter points
PI points that store data from Windows performance counters. Windows performance
counters can be viewed in Windows Performance Monitor. Performance counter points
require PI Performance Monitor Interface to collect and archive data from Windows
Performance Monitor.
Windows performance counter points provide real-time information about the performance
of the operating system, application, service, or driver related to interface operation.
Performance counter points can be configured to provide a more detailed level of
performance information than health points.
• UniInt performance points
Interface-specific PI points that track how long it takes an interface to complete a scan for a
particular scan class.
• I/O rate points
Track the average rate of data collection.
• Failover status points
Track status information for UniInt failover.
• PI Interface Status Utility (PI ISU) points
Required for server-level failover configuration for PI to PI Interface. A PI ISU watchdog
point only monitors a single PI point, and is not recommended for monitoring interface
health.
Topics in this section
• Health points
• Performance counter points
• Create performance points
• I/O rate points
• Failover status points
PI Universal Interface (UniInt) 4.6.4 User Guide
49
Configuration overview for UniInt interfaces
Health points
Health points enable an interface to store its status information in PI Data Archive, providing a
history of interface operation.
Health point details
Health Point
Extended
Data Type
Descriptor (exdesc)
Keyword
When Updated
When Reset
Device Status
[UI_DEVSTAT]
String
On change
N/A
Heartbeat
[UI_HEARTBEAT]
Interface Point
Count
[UI_POINTCOUNT] Integer
Integer
Variable
N/A
On change
N/A
IO Rate
[UI_IORATE]
Integer
Heartbeat
Heartbeat
Message Count
[UI_MSGCOUNT]
Integer
60 seconds
N/A
Output Bad Value
Rate
[UI_OUTPUTBVRAT Integer
E]
Heartbeat
Performance
summary period
Output Rate
[UI_OUTPUTRATE] Integer
Heartbeat
Performance
summary period
Scan Class Bad
Value Rate
[UI_SCBVRATE]
Integer
At scan
At Scan
Scan Class Device
Scan Time
[UI_SCINDEVSCAN Integer
TIME]
At scan
N/A
Scan Class
Information
[UI_SCINFO]
String
Perf interval
N/A
Scan Class IO Rate
[UI_SCIORATE]
Integer
At scan
At Scan
Scan Class Point
Count
[UI_SCPOINTCOUN Integer
T]
On change
N/A
Scan Class Scan
Count
[UI_SCSCANCOUNT Integer
]
At scan
Performance
summary period
Scan Class Scan
Time
[UI_SCINSCANTIM Integer
E]
At scan
N/A
Scan Class Scans
Skipped
[UI_SCSKIPPED]
Integer
On change
Performance
summary period
Trigger Bad Value
Rate
[UI_TRIGGERBVRA Integer
TE]
Heartbeat
Performance
summary period
Trigger Rate
[UI_TRIGGERRATE Integer
]
Heartbeat
Performance
summary period
Health point heartbeats are updated in the following way:
• If there are no scan classes defined, the heartbeat updates once per second.
• If one or more scan classes are defined for the interface, the heartbeat updates at the rate of
the most frequent scan class.
• Non-scan class health points are updated when the heartbeat is updated.
• All scan class health points are updated when the class is scanned.
50
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Some health points keep a running total of events until they are reset to 0. Several points are
zeroed at the reporting period, which is based on the performance summary interval (by
default, 8 hours).
During normal shutdown, the interface writes the system digital state of Intf Shut to all
health points loaded by the interface.
Topics in this section
• General health status points
• Scan class health points
• Create health monitoring points
General health status points
The following health points track general interface status. These points do not require a scan
class to be defined in the location4 attribute of the PI point. Health points that return strings
use the pipe symbol | as a delimiter between fields.
Use the extended descriptor (exdesc) point attribute keyword to specify what type of
information to gather. Use square brackets around the keyword.
General UniInt health status points include the following types:
• Heartbeat
Keyword: [UI_HEARTBEAT]
The heartbeat point indicates whether or not the interface is running. The heartbeat point is
updated continuously unless the interface is shut down or in a deadlock situation. As long as
the interface is running, the value of the point cycles incrementally from 1 to 15. The
heartbeat point does not indicate whether the interface is connected to or collecting data
from a data source.
Note:
The interface health heartbeat point is different than the UniInt failover heartbeat
point. An interface can have both loaded simultaneously.
If no scan classes are defined for the interface, the heartbeat is updated once a second. If the
interface has scan classes defined, the update interval is set to the highest-frequency scan
rate (no lower than once a second or higher than once a minute).
• Scan class information
Keyword: [UI_SCINFO]
This string point lists the scan rates, including the heartbeat scan rate, in seconds. The point
is updated once at interface startup and again at each performance interval. The scan class
information string uses the following format: # rates | heartbeat_rate | scan
class 1 | … | scan class n.
For example, for an interface with three scan classes of 5, 10, and 60 seconds, the point
returns the following string: 3 | 5 | 5 | 10 | 60
• Device status
Keyword: [UI_DEVSTAT]
PI Universal Interface (UniInt) 4.6.4 User Guide
51
Configuration overview for UniInt interfaces
This string point contains information about communication between the interface and the
data source. This point is evaluated only while the heartbeat point is updating and is
updated on startup, on change, on shutdown, and on each performance summary interval.
The point contains a string indicating status, formatted as follows: Status code |
Description | Interface-specific text.
For standard message strings, see UniInt device status messages.
• I/O rate
Keyword: [UI_IORATE]
Counts the number of all point values (inputs, outputs, triggered inputs) being sent to PI
Data Archive before exception processing occurs. Can contain zero for update intervals
during which no data was sent to PI Data Archive. If the value stops updating, the interface
has stopped collecting data. Updated at the same rate as the heartbeat point.
• Message counter
Keyword: [UI_MSGCOUNT]
Tracks the number of messages that the interface has logged since start-up. A large number
of log messages can indicate a problem that requires investigation. Updated every 60
seconds.
• Output rate
Keyword: [UI_OUTPUTRATE]
Tracks the number of output point events that are sent to PI Data Archive before exception
processing. Updated according to the heartbeat point update interval and reset each
performance summary interval. If no output points are defined, the digital state value NO
RESULT is written to the health point.
• Output bad value rate
Keyword: [UI_OUTPUTBVRATE]
Counts number of output point events with non-GOOD status that are sent to PI Data
Archive before exception processing. Output points update based on some event and cannot
be scheduled for an update rate. These points are updated at the same rate as the heartbeat
point and reset after the performance summary interval.
If no output points are defined, the digital state value of NO RESULT is written to the health
point.
• Interface point count
Keyword: [UI_POINTCOUNT]
Counts number of PI points loaded by the interface. This count includes all input, output
and triggered input points. This count does not include any interface health points or
performance points. Updated on startup, on change, and shutdown.
• Trigger input rate
Keyword: [UI_TRIGGERRATE]
52
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Counts number of triggered input point events that are sent to PI Data Archive before
exception processing. Triggered input points update based on some event and cannot be
scheduled for an update rate. Therefore, the value of these points is updated at the same
rate as the heartbeat point and reset after the performance summary interval.
If no trigger input points are defined, the digital state value of NO RESULT is written to the
point.
• Trigger input bad value rate
Keyword: [UI_TRIGGERBVRATE]
Counts number of triggered input point events with non-GOOD values that are sent to PI
Data Archive before exception processing. Triggered input points update based on some
event and cannot be scheduled for an update rate. The value of these points is updated at
the same rate as the heartbeat point and reset after the performance summary interval.
If no trigger input points are defined, the digital state value of No Result is written to the
point.
Scan class health points
To configure a health point for a scan class, set its location4 attribute to the scan class. To
monitor the point count for unsolicited points, set location4 to 0. Unless otherwise stated in
the description of the point, a scan class health point receives the system digital state NO
RESULT if there are no interface points loaded for the scan class.
Use the extended descriptor (exdesc) point attribute keyword to specify what type of
information to gather. Use square brackets around the keyword.
Scan class point count [UI_SCPOINTCOUNT]
Contains the number of points loaded by the interface for a specified scan class. If location4
is 0, the point monitors the point count for unsolicited points. The scan class point count
returns 0 when there are no points for the scan class.
Scan class health points include the following types:
• Scan class I/O rate
Keyword: [UI_SCIORATE]
Tracks the number of events sent to PI Data Archive before exception processing for the
given scan class. If the scan class update executed successfully, the point contains a value
between zero and the scan class point count inclusive. If location4 is 0, the point monitors
the I/O rate for unsolicited points. If the point stops updating in PI Data Archive, an error
has occurred and the points for that scan class are no longer receiving new data. The point
is updated after the completion of each scan.
• Scan class bad value rate
Keyword: [UI_SCBVRATE]
Calculates all the bad values being sent to PI Data Archive before exception processing from
the device with a status of anything other than good. This point can be defined for each scan
class and is used for all input points in that particular scan class. Updated at the completion
PI Universal Interface (UniInt) 4.6.4 User Guide
53
Configuration overview for UniInt interfaces
of associated scan class. If location4 is 0, the point monitors the bad value for unsolicited
points.
• Scan class scans skipped
Keyword: [UI_SCSKIPPED]
The total number of scans skipped since the last reporting period. This point tracks the
number of scans that were not performed before the scan time elapsed and the next
scheduled scan was executed. The value of this point is event-driven and updates each time
a scan is skipped. If location4 is 0, the point monitors the total scans skipped for all of the
scan classes. The value of the point is set to zero at the beginning of each reporting period.
• Scan class scan count
Keyword: [UI_SCSCANCOUNT]
The number of scans performed by the interface since the last reporting period. The value of
this point is incremented after the completion of every scan. If location4 is 0, the point
monitors the total number of scans for all of the scan classes. The value of the point is set to
zero at the beginning of each reporting period.
• Scan class scan time
Keyword: [UI_SCINSCANTIME]
The total amount of elapsed time in milliseconds required for the interface to read data
from the foreign device, populate the input points, and send the data to PI Data Archive. The
value for this point is updated after each completed scan.
• Scan class input device scan time
Keyword: [UI_SCINDEVSCANTIME]
The time in milliseconds required to read data from the foreign device and populate the
input points. This value is a subset of the total scan class scan time and can be used to
determine the percentage of time spent communicating to the foreign system compared
with the percentage of time spent communicating with PI Data Archive.
If the scan class scans skipped point value is increasing, consult the scan class
scan time and scan class input device scan time points to identify where the
delay is occurring: the data source communication, the PI System communication, or
elsewhere.
Create health monitoring points
Create health monitoring points using PI ICU.
Procedure
1. On the Health Points tab, right-click the list of points, and then click Create or Create All.
A basic health point configuration should include the following points:
◦ Heartbeat
◦ Device status
54
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
◦ I/O rate
◦ Skipped scans for each scan class
Additional health tags that are helpful include the following points:
◦ Scan count for each scan class
◦ Scan time for each scan class
◦ Scan class point count for each scan class
Performance counter points
To archive performance counter data in PI Data Archive, install PI Performance Monitor
Interface and create performance points for the interface using PI ICU.
In addition to interface-specific counters, the following performance counters are associated
with UniInt-based interfaces for which counters are enabled.
Counter Name
Description
Device Scan Time (milliseconds)
Time in milliseconds to gather data from data
source. Does not include the amount of time to
write the values to PI Data Archive. There is one
"Device Scan Time" counter per scan class. Applies
to scan classes only. Does not apply to the instance
(_Total).
Device Actual Connections
The actual number of data sources currently
connected to the interface instance and working
properly.
Device Expected Connections
Total number of data sources that the interface is
expected to be communicating with at runtime.
Only applies to the instance ( _Total).
Device Status
Stores communication information about the
interface and the connection to the data source.
The device status performance counter indicates
status using the following values:
• 0: Interface working properly, reading/writing
data
• 10: Connected to data source, not receiving
data
• 30 to 79: Interface-specific statuses
• 50: UniInt failover is in a state where the
backup interface may take over if needed after
a certain period of time. 10 minutes is the
default, but can be configured using the
location5 attribute of the active ID point.
• 90: Starting interface, not connected to data
source
• 95: Communication error with data source
• 99: Shutting down the interface
Only applies to the instance (_Total).
PI Universal Interface (UniInt) 4.6.4 User Guide
55
Configuration overview for UniInt interfaces
56
Counter Name
Description
Failover Status
Stores the failover state of the interface when
configured for UniInt failover. Contains 0 if the
interface is primary, 1 if backup.
Interface heartbeat
The heartbeat of the interface. Default: once a
second. Set to the highest frequency scan rate,
between once a second and once a minute. Uses
default if no scan classes are defined. Only applies
to the instance (_Total).
Interface up-time (seconds)
The number of seconds since the interface has
started. This counter is incremented once a
second. Only applies to the instance (_Total).
IO Rate (events/second)
The number of events per second received by the
interface. If this counter is viewed from the
Windows performance monitor, increase the
update time of the performance monitor to the
minimum scan period for the interface. For
example, if the minimum scanning period for the
interface is 5 seconds (/f=5), set the update rate of
the performance monitor to 5 seconds by selecting
the Chart command from the Options menu. On
the window, change the periodic update time to 5
seconds. If the update time is left at 1 second, the
IO Rate appears to go to zero between scans
because no events are received between scans.
Only applies to instance (_Total).
Log file message count
Number of messages that have been written to the
log file. Only applies to the instance (_Total).
PI Status
Status of the connection to PI Data Archive. If the
connection is GOOD the value is 0. If the
connection is anything other than GOOD the value
is 1. Only applies to the instance (_Total).
Points added to the interface
Number of points that have been added to the
interface. Only applies to the instance (_Total).
Point edited in the interface
Number of point edits that have occurred. Only
applies to the instance (_Total).
Point Count
Number of points loaded by the interface. Does not
include UniInt-controlled points such as health
points or failover points. Applies to both instance
(_Total) and scan classes.
Points Good
Number of points that have sent a GOOD current
value to PI Data Archive. If the last value sent to PI
Data Archive is a system digital state value, or the
last value sent to PI Data Archive is older than the
Stale timeout, the point is not counted in the Points
Good count. This value equals Point Count when all
points are updating with a GOOD current value.
Only applies to instance (_Total).
Points In Error
Number of points that have sent a system digital
state value as the current value to PI Data Archive.
The total number of Points In Error, Points Good
and Points Stale equals the Point Count. Only
applies to the instance (_Total).
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Counter Name
Description
Points removed from the interface
Number of points that have been removed from
the interface. Only applies to the instance (_Total).
Points Stale 10(min)
Number of points that have not received a new
value in the last 10, 30, 60 or 240 minutes. If a
point had a GOOD current value that is now stale,
the Stale count goes up and the Points Good count
goes down. Only good points go stale; points in
error do not. Only applies to the instance (_Total).
Points Stale 30(min)
Points Stale 60(min)
Points Stale 240(min)
Scan Time (milliseconds)
Time in milliseconds to collect values from data
source. One "Scan Time" counter per scan class.
Does not apply to the instance. Applies to scan
classes only.
Scheduled Scans: % Missed
Percentage of missed scans since starting the
interface. If a scan occurs more than one second
after its scheduled time, the scan is considered
missed. One "Missed Scans" counter per scan class.
Applies to both instance (_Total) and scan classes.
Scheduled Scans, % Skipped
Percentage of skipped scans since starting the
interface. If a scan occurs one scan period or more
after its scheduled time, those scans are
considered skipped. One "Skipped Scans" counter
per scan class. Applies to both instance (_Total)
and scan classes.
Scheduled Scans: Scan count this interval
The total number of scans in the current
performance interval. This total is the current
sample size that is used to evaluate the % Missed
Scans and the % Skipped scans. The performance
interval is 8 hours by default, and can be changed
using PI ICU (Debug tab) or by setting the perf
command-line parameter. The minimum
performance interval is 60 seconds. When the
performance interval is exceeded, the previous
samples are discarded and sampling starts again.
Applies to both instance (_Total) and scan classes.
Standard deviation above mean
The quantity calculated to indicate the extent of
deviation for input and output data for each
heartbeat interval above the average of the values.
This calculation accounts for up to 30 days of
history. Only applies to instance (_Total).
Standard deviation below mean
The quantity calculated to indicate the extent of
deviation for input and output data for each
heartbeat interval below the average of the values.
This calculation accounts for up to 30 days of
history. Only applies to instance (_Total).
Update performance counters
If you update scan classes after creating the interface service, you can update the scan class
performance counters and ensure new points are created for scan classes that were added.
PI Universal Interface (UniInt) 4.6.4 User Guide
57
Configuration overview for UniInt interfaces
Procedure
1. Update the Windows performance counters in one of two ways:
◦ Use the Windows service-related parameter (syntax: /upcvalue) in PI ICU to update
Windows performance counters.
◦ Using a command prompt, issue the command: interface.exe /upc /
serviceidinterfaceid.
For more information, see Windows service-related parameters.
Create performance points
Performance points can be configured to monitor the amount of time, in seconds, that it takes
an interface to complete a scan for a particular scan class. The lower the scan time, the better
the performance. The scan time is recorded to millisecond resolution.
Several other measurements concerning the performance of the interface can be monitored
with performance points. Performance points are not relevant if the interface gathers data
asynchronously, because the data source is not regularly scanned.
Create performance points using PI ICU.
Procedure
1. On the Performance Points tab, right-click the list of points, and then click Create or Create
All.
I/O rate points
I/O rate points monitor the data collection rate of an interface.
An I/O rate point can be configured to receive ten-minute averages of the total number of
exceptions per minute that are sent to PI Data Archive by the interface. A value is considered an
exception if it has exceeded the exception limits for a given PI point. Because ten-minute
averages are taken, the first average is not written to PI Data Archive until ten minutes after the
interface has started. One I/O rate point can be configured for each copy of the interface that is
in use. Some interfaces permit more than one I/O rate point per interface. See the interface
user guide for details.
Note:
In HOT failover mode, the value of the I/O rate point on a backup interface might be
higher than that of the I/O rate on the primary interface. This might happen because the
failover primary interface instance switch occurs after values are processed in
preparation for sending to PI Data Archive. These values are discarded by the backup
interface; however, the I/O rate point value seems to show that the events are being sent
to PI Data Archive.
To create I/O rate points using PI ICU, go to the IO Rate tab. To display the averages as events
per minute, use a client application such as PI ProcessBook. For detailed information about the
I/O rates mechanism, refer to the PI-API Installation Instructions documentation or PI API
online help through the OSIsoft Tech Support site.
58
PI Universal Interface (UniInt) 4.6.4 User Guide
Configuration overview for UniInt interfaces
Failover status points
UniInt failover tracks status using the following PI points:
• Active ID
Tracks which interface instance is currently forwarding data from the data source to PI Data
Archive. If the backup instance detects that the primary instance has failed, it sets the active
ID point to its own failover ID and assumes responsibility for data collection, becoming the
primary.
• Heartbeat for UFO instance 1
Enables the backup interface instance to detect whether the primary instance is running.
• Heartbeat for UFO instance 2
Enables the primary interface instance to detect whether the backup instance is running.
• Device Status for UFO instance 1
• Device Status for UFO instance 2
Displays interface status.
Device status point values
Device Status
Description
0
Interface working properly, reading/writing data
10
Connected to device, not receiving data
30-70
Interface-specific error; consult interface manual
90
Starting interface, not connected to device
95
Communication error with device
99
Shutting down the interface
Note:
Device status points are different than the UniInt health device status points. The
information in the two point types is similar, but failover device status points are
integer values and the health device status points are string values.
Heartbeat point values
Value
Status
1 - 15
The interface instance is running.
This value cycles through 1 - 15 based on the rate
specified by the failover update interval.
17 - 31
The interface instance has lost its connection to PI
Data Archive.
This value cycles through 17 - 31 until the
connection is restored.
0
The interface instance is in a normal shutdown
process.
PI Universal Interface (UniInt) 4.6.4 User Guide
59
Configuration overview for UniInt interfaces
60
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
Interface operation includes startup, shutdown, point updates, and diagnostics and
troubleshooting.
Topics in this section
• Start the interface
• Stop the interface
• PI point updates
• UniInt diagnostics and troubleshooting
Start the interface
Starting the interface as a Windows service is best for normal interface operation. The other
options can be better for testing and troubleshooting.
Procedure
1. Choose one of the interface startup methods:
◦ Start the interface from PI ICU, either starting the service or as a non-service in the
command prompt window.
◦ Run the Windows service for the interface.
From the Windows menu, click Control Panel > Administrative Tools, and then doubleclick Services. Select the service for the interface and click Start.
◦ Run the batch file with the interface startup commands.
◦ Run the interface executable command from a command prompt window, and specify the
parameters from the command line.
Stop the interface
You can stop the interface and trigger an orderly shutdown where UniInt performs all the
shutdown processes.
Procedure
1. For orderly shutdown of interfaces running as a service, stop the interface service in one of
two ways:
◦ Stop the interface service in PI ICU.
◦ Stop the interface service in Windows.
If the computer crashes or the process is stopped, the interface can be terminated without
completing an orderly shutdown.
2. For interfaces running interactively in a command prompt window, press Ctrl+C to begin
orderly shutdown.
PI Universal Interface (UniInt) 4.6.4 User Guide
61
UniInt interface operation
Note:
To interrupt orderly shutdown for interactive interface processes in the command
prompt window, press Ctrl+C more than once.
PI point updates
After startup, the interface checks for points that have been added, changed, or deleted.
Normal point updates happen in a cycle with the following conditions:
• Default point updates occur every two minutes after startup and process 25 point updates
at a time.
• For more than 25 pending updates, the interface processes updates in batches and splits the
update interval to increase processing speed. Updates occur every 30 seconds or at onequarter of the update interval (updateinterval) parameter, whichever is lower, until the
updates are complete.
UniInt writes the digital state SCAN OFF to any removed points.
Updates and point synchronization that involve numerous point changes require additional
time before the interface handles all the point changes. To update large batches of point
updates at the same time, see the Process large point updates section in this document.
Without disconnected startup, any point updates that occur during a loss of connection to the
PI Data Archive are lost until the interface is restarted.
Topics in this section
• Modify point check frequency
• Process large point updates
Modify point check frequency
The default frequency for the interface to check for PI point updates is 120 seconds. You can
modify this value to change the point check frequency.
Procedure
1. Open PI ICU and select the interface instance.
2. From the navigation pane, select the UniInt page.
3. In the Performance and Behavior area, select Point update interval (sec.), and enter the new
point check frequency.
This new value updates the update interval (updateinterval) parameter in the .bat file.
The new point check frequency takes effect at the end of the current update interval.
Process large point updates
Point updates are processed in batches. Large point updates can be processes more quickly by
stopping and restarting the interface, either for updating point attributes that change while
connected, or for synchronizing the disconnected startup cache files. However, this process
causes some data loss.
62
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
Note:
Avoid running the interface in disconnected startup mode while making major point
modifications to PI Data Archive.
Procedure
1. Stop the interface.
You can stop the interface service from PI ICU or Windows.
2. If you are using disconnected startup, move or delete any previously created cache files for
the interface.
This prevents the interface from using the outdated cache files during subsequent restarts.
3. Restart the interface.
The interface collects all the point updates and processes them in one batch.
UniInt diagnostics and troubleshooting
Diagnostic information is available for UniInt interfaces using the following methods:
• Review error and informational message logs in the PI message log file
• Use the pipc parameter to print all messages to the pipc.log file in addition to the PI
message log file
• View Windows performance counters using the Windows Performance Monitor, or use the
PI Interface for Performance Monitor to create performance counter points
• View interface health, status, and performance points using a visualization tool
• Change parameters from the command line and test the output
Topics in this section
• Start and stop the interface interactively
• Disable exception reporting
• Hit, missed, and skipped scans
• Use command prompts
• UniInt parameter reference
• View Windows performance counters
• Error and informational messages
Start and stop the interface interactively
For interactive parameter configuration, running the interface service you can use PI ICU to run
the interface interactively.
Note:
Interfaces running as services must be stopped before you can run them interactively.
PI Universal Interface (UniInt) 4.6.4 User Guide
63
UniInt interface operation
Procedure
1. Open PI ICU and select the interface instance.
2. Click Interface > Start Interactively.
A command prompt window opens and interface operation begins automatically.
3. Optional: Press Ctrl+C to initiate orderly shutdown. You can also close the command prompt
window to stop running the interface interactively.
Note:
Press Ctrl+C more than once during orderly shutdown to stop the interface
immediately and end any interface-specific cleanup processes.
The interface stops.
Disable exception reporting
Standard exception reporting is enabled by default, and is disabled using the sn parameter in
the .bat file. You can use PI ICU to disable exception reporting for the interface instance. Use
PI SMT to change point attributes.
Procedure
1. To disable exception reporting for the interface instance, launch PI ICU and select the
interface instance, navigate to the UniInt page and select Bypass exception.
2. To disable exception reporting for a PI point, use PI SMT, and set excmin, excmax, excdev,
and excdevpercent attributes to 0.
This setting takes effect after the interface restarts.
Hit, missed, and skipped scans
UniInt logs the percentage of scans that are hit, missed, and skipped for scan-based input
points. Scans are defined as follows:
• Hit scans occur on time.
• Missed scans occur more than one second after the scheduled scan time.
• Skipped scans occur one or more scan periods after the scheduled scan time.
For example, if a particular scan class has a period of two seconds and a scan for this class
occurs 1.1 seconds after its scheduled time, then one scan has been missed. No scans have been
skipped, because the next scan can occur at its scheduled time, 0.9 seconds after the last scan
in this case.
For scan classes that have periods of one second or less, scans are considered either hit or
skipped. Because every skipped scan is also considered to be a missed scan, the percentage of
skipped and missed scans is the same for scan classes with periods of one second or less.
Adjust scan performance summary logs
By default, the performance summary for hit, missed, and skipped scans is logged every 8
hours if the hit ratio (hits / (hits + misses)) drops below 0.95.
64
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
You can change scan performance summary logging in the following ways:
• Adjust the log frequency.
• Disable logging for unsolicited input points.
Procedure
1. To adjust the frequency of logging using PI ICU, set its value on the Debug tab. In the startup
batch file, set the perf parameter.
2. For interfaces that use unsolicited input points, deactivate performance summaries using PI
ICU by going to the UniInt > Debug tab and setting Scan performance summary to 0, or
specify /perf=0 in the .bat file.
Performance summaries are meaningless for unsolicited inputs.
Disable data collection
You can disable data collection before starting the interface, or while the interface is running.
Data collection is enabled by default.
Procedure
1. Using PI SMT, set the scan attribute for each point to 0.
The interface will detect the change at the next update interval (by default, 2 minutes).
Multiple update intervals are necessary to process point updates of 25 or more.
2. Optional: To enable data collection, set the scan attribute to 1.
Use command prompts
For troubleshooting, you can open a command prompt and change parameters from the
command line instead of configuring the .bat file using PI ICU.
Before you start
Ensure the interface instance was created and configured correctly in PI ICU.
Procedure
1. From the Windows menu, open a command prompt window.
2. Navigate to the interface directory and run the .bat file.
The interface starts.
3. Enter the interface executable name followed by /help to list parameters supported by the
interface.
For information about interface parameters, see UniInt parameter reference.
UniInt parameter reference
Parameters can be used to configure general interface settings, the Windows service, failover,
and disconnected startup.
Parameter syntax uses the following rules:
PI Universal Interface (UniInt) 4.6.4 User Guide
65
UniInt interface operation
• Parameters are not case sensitive
• Parameter values or parameters that use embedded spaces must be enclosed in quotes
• Enable or disable parameters that do not have values either by adding or removing the
parameter.
• Most interfaces can use either the / or - characters as parameter delimiters, unless specified
in the interface user guide. Use PI ICU to select the delimiter.
Each interface has a list of supported parameters, which you can view in a command prompt
window when running the interface interactively by entering /help. Interface version
information is available by entering /v.
Windows-related parameters should never be included in the .bat file for the interface.
Topics in this section
• Windows service-related parameters
• Standard parameters
• UniInt failover parameters
• Disconnected startup parameters
Windows service-related parameters
Windows service-related parameters should be specified from the command line or PI ICU. Do
not include Windows-related parameters in the .bat file.
Windows service-related parameters for UniInt
66
Parameter and syntax
Description
/query
Query the operating system for the status of the
interface service. Returns RUNNING, NOT RUNNING
or NOT INSTALLED.
/install
Create a Windows service. The default name of the
service is the executable name, unless you specify
the serviceid parameter.
/start
Start the interface service.
/stop
Stop the interface service.
/remove
Remove the interface service from the list of
services in the Windows Services control applet.
/disabled
Create the interface as a disabled service.
/display name
Install service using the specified display name.
/serviceid instanceID
Specify the instance ID of the service you are
maintaining, using a concatenation of the interface
executable name and the serviceid parameter.
This value is different than the id parameter for
the interface or the ufo_id parameter for failover.
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
Parameter and syntax
Description
/upc value
Install, remove, or update Windows performance
counters.
Valid value options are update (default), add, or
remove. This parameter should only be included in
the .bat file if the administrator wants to use it to
update performance counters for an interface and
then shut down.
Standard parameters
Interfaces use startup parameters to control how the interface runs. Some parameters require
values. Standard settings for the interface include the following parameters:
• Application name (appname)
Syntax: /appname=Name
For API trusts, this parameter configures the name sent to PI Data Archive when the
interface connects. The interface includes the Name value in message logs.
By default, the interface sends the first four characters of the executable name appended
with the letter E. Maximum length is eight characters.
To use eight characters for the Name value, ensure the PIClient.ini file contains the
following setting:
[PISERVER]
LONGPROCNAME=1
• Debug UniInt (dbuniint)
Syntax: /dbuniint=level-bitmask
Enables debug output for one or more specified functions. This parameter can be added,
removed, or modified while the interface is running. Options include:
◦ Enable a single debug option. Set the associated bit value for the parameter.
◦ Enable all debugging options. Set all bit values to: /dbuniint=0xFFFF.
The bitmask is a 32-bit integer, which can be specified as either a hexadecimal number or a
decimal number. Hexadecimal values begin with 0x. Bitmask values for UniInt debug
settings include the following options.
Description
Hexadecimal Value
Decimal Value
Initialization
0x0002
2
Exit Handler
0x0008
8
Update PI Data Archive
0x0010
16
Control Loop
0x0020
32
Point List Loading
0x0040
64
Point Edits
0x0080
128
IO Rate points
0x0100
256
PI Universal Interface (UniInt) 4.6.4 User Guide
67
UniInt interface operation
Description
Hexadecimal Value
Decimal Value
Time Functions
0x0400
1024
Performance Counters
0x0800
2048
Digital State Caching
0x2000
8192
Whitelist
0x4000
16384
Standard Deviation
0x8000
32768
• TrimSyntax: /digstatetrimleft leading spaces from digital state tags
(digstatetrimleft)
Syntax: /digstatetrimleft
Removes both leading and trailing spaces from digital state tags. If this parameter is not set,
then only trailing spaces are deleted.
• Disable counters (disablecounters)
Syntax: /disablecounters
Disables Windows performance counters.
Syntax: /ec[=#]
The event counter (ec) parameter associates an I/O rate point in the inIOrates.dat file
with this copy of the interface. The value specifies the number of the point in the file.
Valid ec value ranges are:
◦ 2 to 34
◦ 50 to 200
Interfaces that share an ec value will write to the same I/O rate point, making the data
unusable. To avoid this problem, define a unique event counter for each copy of the
interface. The default ec value is 1. The default value is associated with the interface in the
following cases:
◦ If the # value is not specified
◦ If the ec parameter is omitted from the command line
The event counter can be used by specific interfaces to keep track of input or output
operations. In these cases, you can define subsequent instances of the ec parameter. Refer
to the interface-specific documentation to see if subsequent instances of the ec parameter
have any effect. For interfaces that use subsequent instances of the ec parameter, use the
form /ec*=#, where * is any ASCII character sequence. For example, /ecinput=10, /
ecoutput=11, and /ec=12 are acceptable for the second, third, and fourth event counter
strings.
• Scan class (f)
The f parameter defines one or more scan classes. Scan classes specify how often a data
source is checked for new data.
Syntax: /f=scan-interval
Specify scan interval and optional offset using the following format: time value,time offset,L
68
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
Scan class time and offset time values use the following format: HH:MM:SS.##, where:
◦ HH is hours
◦ MM is minutes
◦ SS is seconds
◦ ## is hundredths of seconds (01 to 99)
If you omit HH and MM, the scan period is assumed to be in seconds. For example, /
f=00:01:00,00:00:05 is equivalent to /f=60,5.
The L value associates the time unit value with the local computer time-of-day settings.
Time-of-day scans use a 24-hour clock and are automatically adjusted for daylight saving
time. This is also known as wall clock scheduling. The following example uses a scan
frequency of 24 hours (once a day), an offset of eight hours from midnight (8 AM), and
enables time-of-day scanning by specifying the L value: /f=24:00:00,08:00:00,L
The scan class frequency determines how often to scan for data. The offset specifies how
long after the frequency's time value to scan for data. To balance the scanning workload,
specify an offset for scan classes that have the same interval so that they are not scanned
simultaneously.
For each scan class that you want to define, specify the f parameter. Scan classes are
numbered by the order in which you define them. Scan class 1 is the first defined f
parameter, and scan class 2 is the second f parameter you define.
Examples:
◦ Scan class 1 has a scanning frequency of one minute with an offset of five seconds, and
scan class 2 has a scanning frequency of seven seconds with no offset:
/f=00:01:00,00:00:05 /f=00:00:07
◦ Two scan classes, defined using only seconds:
/f=60,5 /f=7
◦ Sub-second scan classes defined as decimal values:
/f=0.5 /f=00:00:00.1
Note:
Deleting scan classes or changing their order can adversely affect the operation of
existing PI points, which are closely related to scan rates. Scan classes should be
adjusted only by PI System administrators who are fully aware of the PI System
configuration and the effects of any such changes.
For more information about scan classes, see the PI Interface Configuration Utility (PI ICU)
User Guide.
• Foxboro Coordinated Universal Time (foxutc)
Syntax: /foxutc
Enabling this option determines the Coordinated Universal Time (UTC) of the PI Data
Archive node by using the same process as that used in PI Interface for Foxboro. This
parameter is not necessary if the PI API version is 1.6.x or later and the PI Data Archive
version is 3.4.370.x or later.
PI Universal Interface (UniInt) 4.6.4 User Guide
69
UniInt interface operation
The foxutc parameter is used in situations where the default method of calculating the
UTC offset between the interface node and the PI Data Archive node does not work properly.
For PI Interface for Foxboro, the time zone on the interface node is always set to GMT
standard time, but the wall clock time is adjusted by one hour during daylight savings time
changes, so the UTC time on the interface node also changes by one hour.
This parameter also enables you to calculate time zone differences of less than one hour.
• Host name (host)
Syntax: /host=host[:port]
Required: Specifies the host name of the PI Data Archive.
The host can specify IP address, host name, or fully-qualified domain name. The port
specifies the TCP/IP port on which PI Data Archive listens for requests. Default for port is
5450.
The following examples are all valid host parameter values:
/host=marvin
/host=marvin:5450
/host=206.79.198.30
/host=206.79.198.30:5450
When failover is enabled, the host parameter has additional meaning. The value of the
host parameter depends on the PI Data Archive configuration, where:
◦ If the redundant interfaces are configured to send data to a PI Data Archive node that is
not part of a collective, the value of host must be identical on both interface computers.
◦ If the redundant interfaces are configured to send data to a PI Data Archive collective, the
value of host must be set on the different interface nodes to different members of the
collective. This parameter ensures that outputs continue to be sent to the data source if
one of the PI Data Archive nodes becomes unavailable for any reason.
• Interface ID (id)
Syntax: /id=id#
The id parameter specifies the integer ID of the interface instance. The maximum length of
the id# value is interface-specific.
• I/O source time (iosourcetime)
Syntax: /iosourcetime
Enable the iosourcetime parameter for output points. At startup, the interfaces sends the
time stamp of the source point’s snapshot value to the interface-specific code that handles
the actual output.
• Maximum stop time (maxstoptime)
Syntax: /maxstoptime
Specifies the maximum amount of time that the interface can use to perform cleanup tasks
when shutting down. If shutdown exceeds the specified time, the interface exits without
performing remaining tasks. Default is two minutes.
70
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
• No outputs (nooutputs)
Syntax: /nooutputs
Disable outputs to the data source in a read-write version of an interface. The interface
cannot write data from PI Data Archive to the data source, but it can read data from the data
source into PI Data Archive .
Note:
If the interface is available in both read-write and read-only versions, use the readonly version instead of disabling outputs.
• Percent up (percentup)
Syntax: /percentup
For interfaces that connect to multiple devices (data source), specifies the percentage of
connections that is required to be valid for the interface to report a device status of "0 |
Good".
If the number of valid connections drops below the specified percentage, the interface sets
the device performance counter to indicate failure. By default, 100 percent of connections
must be valid.
• Performance summary logging (perf)
Syntax: /perf=interval
Specifies how often, in hours, performance summaries are logged.
If the percentage of scans performed on time drops below 95%, the interface logs
performance summaries for each scan class. By default, summaries are reported every eight
hours.
This setting can be changed using PI ICU, from the Debug tab. If the data source uses an
unsolicited reporting mechanism for all input data to the interface, performance summaries
are meaningless. In this case, you can disable performance summaries by setting the
interval value to 0.
• PIPC Message Log (pipc)
Syntax: /pipc
When enabled, the interface sends error and informational messages to the pipc.log file in
addition to the PI Message Log.
• PI SDK (pisdk)
Syntax: /pisdk=#
Enables PI SDK connections for the interface. By default, PI SDK connections to PI Data
Archive are disabled unless the interface enables them. This parameter is ignored if the
interface is running with PI API version 1.6.x or later, and connecting to PI Data Archive
version 3.4.370.x or later.
Enable PI SDK: /pisdk=1
Disable PI SDK: /pisdk=0
PI Universal Interface (UniInt) 4.6.4 User Guide
71
UniInt interface operation
• PI SDK connection timeout (pisdkcontimeout)
Syntax: /pisdkcontimeout=timeout
Specifies the time, in seconds, for how long to wait for a connection to PI Data Archive
before timing out. Overrides any connection timeout configured using PI Connection
Manager.
To adjust the PI SDK connection timeout, use PI Connection Manager. Only configure this
setting if the interface uses PI SDK and you must configure a connection timeout that is
different than the setting configured with PI Connection Manager.
• PI SDK data access timeout (pisdktimeout)
Syntax: /pisdktimeout=timeout
Specifies the time, in seconds, for the PI SDK data access timeout.
Configure this setting only if the interface uses PI SDK and you need to override the timeout
that is configured using PI Connection Manager.
• Point source (ps)
Syntax: /ps=point-source
Required: Specifies the point source for the interface instance.
The point source is used by the interface to determine which points to load at startup and
during operation. This point source value is not case-sensitive.
Note:
If the PI API version is earlier than 1.6.x, or the PI Data Archive version is earlier than
3.4.370.x, the point-source value must be a single character, or PI SDK must be used to
load points.
The following point sources are reserved. Do not configure them for interface instances.
Point Source
Reserved By
T
PI Totalizer Subsystem
G and @
PI Alarm Subsystem (PI Alarm)
R
PI Interface for Random (Random interface)
9
PI Interface for RampSoak (RampSoak interface)
C
PI performance equations subsystem
• Service events timeout (svceventsto)
Syntax: /svceventsto=timeout
Specifies the service events timeout for how many milliseconds the interface spends
servicing events from the event queue before switching to perform its other tasks.
Default is 500 milliseconds. Maximum is 3000 milliseconds (3 seconds).
If you specify /svceventtsto=0, UniInt interfaces will service 36 events before switching
to other tasks. Used when servicing outputs and triggered inputs to ensure that the
servicing of events does not exceed the Service Events Timeout time limit.
72
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
• Suppress initial outputs (sio)
Syntax: /sio
The sio parameter is enabled to suppress initial outputs. Suppresses the default interface
startup behavior. Outputs will be written only when they are explicitly triggered.
By default, when a UniInt interface is started, it determines the current snapshot value of
each output point and writes this value to each output point. In addition, when an output
point is edited, the interface writes the current snapshot value to the point by default.
• Disable exception reporting (sn)
Syntax: /sn
Specifying the sn parameter disables exception reporting, which is enabled by default. Do
not use for normal interface operation.
• Startup delay (startup_delay)
Syntax: /startup_delay[=delay]
Specifies the time, in seconds, for how long the interface waits after logging the Starting
message before proceeding. Startup delays for interfaces are not enabled by default. If you
enable this parameter, default delay value is 30 seconds.
• Stop state (stopstat)
Syntax: /stopstat[=digitalstate]
Writes the digital state defined in the system digital state set to PI points when the interface
is stopped. By default, no digital states are written to PI points when the interface shuts
down.
If you omit the digitalstate value, the interface writes Intf Shut to the PI points.
In a UniInt failover configuration, the digital state is not written to points when an interface
instance is stopped, because the other interface instance takes over writing data to the
point. For more information about the PI Data Archive system digital state set, see PI Server
System Management Guide PI Server System Management Guide (https://
techsupport.osisoft.com/Downloads/File/b481399c-463e-4bcb-a93f-6ef85295263e).
• Unique redundant interface ID (uht_id)
Syntax: /uht_id=ID#
Specifies a unique ID for interfaces that are run in a redundant mode without using the
UniInt failover mechanism.
Some UniInt interfaces implement their own version of failover. This setting enables you to
configure health points to monitor a copy of such an interface. The interface loads only
health points that contain the specified ID# value in the location3 attribute.
• UniInt point trace (uitrace)
Syntax: /uitrace=tagname
Enables tracing for the PI point specified in tagname.
PI Universal Interface (UniInt) 4.6.4 User Guide
73
UniInt interface operation
Note:
Trace output can bloat log files. Limit usage of this parameter.
This parameter can be added, removed, or modified while this interface is running.
• Update interval (updateinterval)
Syntax: /updateinterval=interval
Specifies time, in seconds, for how often the interface checks for changes to the PI point
database, such as point additions, deletions, or attribute modifications.
Default is 120 seconds. Must specify a value between 1 and 300.
To disable checking, set interval to 0. When checking is disabled, changes are not detected
until you stop and restart the interface. If the PI point database is very stable, disabling the
checking for point updates can slightly reduce the chances of missing scans when
communication between PI Data Archive and the interface is interrupted.
• Whitelist (whitelist)
Syntax: /whitelist=path\filename
Specifies a list of permitted output tags and their attributes, which the interface uses to
write output data to the data source.
UniInt failover parameters
Interfaces use failover parameters to control how failover operates. Some parameters require
values. Failover settings for UniInt failover include the following parameters:
• Do not failover (ufo_dnfbpi)
Syntax: /ufo_dnfbpi
If both interface instances lose connectivity to PI Data Archive, do not attempt failover.
Enabling this option ensures that if both instances lose connectivity to PI Data Archive,
incoming data is buffered by a single interface instance to prevent the buffer from being
split.
• Interface failover ID (ufo_id)
Syntax: /ufo_id=failoverID#
Required: Specifies the failover ID for this interface instance.
The active ID point maintains the failover ID of the interface that is currently primary in a
failover configuration. Valid values: integer from 1 to 4,294,967,295.
Note:
The interface failover ID (ufo_id) and interface ID (id) parameters are different
settings.
• Other interface failover ID (ufo_otherid)
Syntax: /ufo_otherid=otherID#
74
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
Required: Specifies the failover ID of the other interface instance in the failover
configuration.
The otherID# value must be different from the value specified for ufo_id. Valid values:
integer from 1 to 99.
• Synchronization file path (ufo_sync)
Syntax: /ufo_sync=path\[filename]
Required: Specifies the path to the directory containing the shared file used for failover
synchronization and an optional filename that overrides the default filename. Each node in
the failover configuration must specify the same path and filename and must have read,
write, and file creation rights to the shared directory. If the file does not exist, the first
interface instance to start creates the file.
The default filename is executablename_pointsource_interfaceID.dat.
The path value can be one of the following types:
◦ Fully qualified machine name and directory
◦ Mapped drive letter
◦ Local path, if the shared file is on one of the interface nodes
The path value must end with either a slash / or backslash \. The interface interprets path
names without a terminating slash as a filename value.
Note:
If you specify the file name, omit the trailing slash.
If there are spaces in the path or filename, enclose the entire path and filename in double
quotes. If you quote a path, use two backslashes \\ at the end of the path.
• Failover type (ufo_type)
Syntax: /ufo_type=type
Required: Specifies the type of failover. Type values can be HOT, WARM, or COLD. If an interface
does not support the requested type of failover, the interface logs an error and shuts down.
• Failover interval (ufo_interval)
Syntax: /ufo_interval=time
Specifies time, in milliseconds, for how often the interface checks and updates the failover
heartbeat points.
The time value must be the same on both interface computers. Minimum is 50, maximum is
20,000, and the default is 5000 milliseconds.
• Output failover-specific debug messages (ufo_debug)
Syntax: /UFO_Debug=x
Debug off (default) = 0x00
Debug ActiveID = 0x01
Debug this Heartbeat = 0x02
Debug other Heartbeat = 0x04
PI Universal Interface (UniInt) 4.6.4 User Guide
75
UniInt interface operation
Debug shared file = 0x08
Debug other DeviceStatus = 0x10
Debug reads from PI = 0x20
Debug max = 0xFF
• Host name (host)
When failover is enabled, the host parameter has additional meaning. For more
information, see Standard parameters.
Disconnected startup parameters
Interfaces use disconnected startup parameters to control how disconnected startup operates.
Some parameters require values. Disconnected startup settings for UniInt interfaces include
the following parameters:
• Cache mode (cachemode)
Syntax: /cachemode
Required. If enabled, the cachemode startup parameter indicates that the interface is
configured for disconnected startup.
Default: Not Defined.
• Cache file path (cachepath)
Syntax: /cachepath=path
Specifies the directory path to the cache files. The specified directory must already exist on
the interface node. By default, the cache files are created in the same location as the
interface executable, which may require increased service account access permissions. For
more information about security for access to the default file path, see Restricted access for
service accounts.
If the path contains any spaces, enclose the path in quotes. For example:
◦ /cachepath=D:\PIPC\Interfaces\CacheFiles
◦ /cachepath="D:\Program Files\PIPC\MyFiles"
• Cache file synchronization (cachesynch)
Syntax: /cachesynch=#
Specifies the amount of time in milliseconds that the interface takes to synchronize the
point cache file with PI Data Archive during each update.
Note:
If the value of the cachesynch parameter is greater than the interval of any scan class,
input scans will be missed while the cache file is being synchronized. Ensure that the
value is less than the smallest scan class period (defined with the f parameter).
Interfaces often have multiple scan classes.
76
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
By default, the interface synchronizes the point cache if running in disconnected startup
mode. UniInt allocates a maximum of # milliseconds during each pass through the control
loop, synchronizing the interface point cache until the file is completely synchronized.
The default value is 250 milliseconds. The minimum value is 50 milliseconds, and the
maximum is 3000 milliseconds. The interface changes # values of 1 to 49 to the minimum
value of 50 milliseconds and values greater than 3000 to the maximum value of 3000
milliseconds. To disable synchronization of the point cache file, set # to 0. For example:
◦ /cachesynch=50 (50 millisecond interval)
◦ /cachesynch=3000 (3 second interval)
◦ /cachesynch=0 (do not synchronize the cache file)
View Windows performance counters
UniInt enables Windows performance counters by default when the interface runs as a service.
To view performance counters for an interface service, launch the Windows Performance
Monitor control panel and perform the following steps:
Procedure
1. Click the + button.
The Add Counters window opens.
2. Select one or more performance counters from the Available counters list, and then click the
Add>> button.
The counters are listed in the Added counters list.
PI Universal Interface (UniInt) 4.6.4 User Guide
77
UniInt interface operation
3. Click OK.
The values of the selected counters are displayed on the graph.
Error and informational messages
Informational and error messages generated by the interface are logged to the PI Message Log
file. Interface-specific errors are discussed in the interface documentation.
To view system and PI Data Archive errors, use the AboutPI-SDK or PI SDK utilities, or PI SMT.
To translate an error number to an error description, you can perform one of the following:
• Issue the following command in a command prompt: pidiag –e error_number.
• Use the Error Lookup tool from the AboutPI-SDK utility. Enter the error number and click
Lookup.
Errors use the following numbering:
• Positive: System errors
• Negative: PI Data Archive errors
You can enable standard deviation debugging messages using the debug UniInt (dbuniint)
parameter to record the following information:
78
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
• Standard deviation thread starting and stopping
• Calculated queue size
• Variances of more than two units of standard deviation from the current mean
Additionally, interfaces can write messages to the pipc.log file by setting the pipc parameter
in the .bat file to /pipc.
For details about interface message and error logging, see the OSIsoft Knowledge Base article
How to read new UniInt 4.5.0.x and later Interface message logs (https://
techsupport.osisoft.com/Troubleshooting/KB/KB00401?).
Topics in this section
• UniInt failover-specific messages
• Disconnected startup messages
• UniInt device status messages
UniInt failover-specific messages
This section contains informational messages and their meanings, and error messages and
their causes and resolutions.
Informational messages:
• 16-May-06 10:38:00
ifc 1> UniInt failover: Interface in the "Backup" state.
Meaning: At system startup, the interface assumes the backup role and monitors the status
of the other interface participating in failover. When configured for Hot failover, data
received from the data source is queued and not sent to PI Data Archive while in backup
mode. The amount of data queued while in this state is determined by the failover update
interval. Typically no more than two update intervals of data reside in the queue, though
state negotiations can cause the queue to hold up to five failover update intervals worth of
data.
• 16-May-06 10:38:05
ifc 1> UniInt failover: Interface in the "Primary" state and actively sending
data to PI.
Meaning: The interface is collecting data and sending it to PI Data Archive.
• 16-May-06 16:37:21
ifc 1> UniInt failover: Interface in the "Primary" state, Backup interface
available.
Meaning: The interface is collecting data and sending it to PI Data Archive . The other copy
of the interface is ready to take over the role of primary if failover occurs.
• 16-May-06 16:37:21
ifc 1> UniInt failover: Interface in the "Primary" state, Backup interface not
available.
Meaning: The interface is collecting data and sending it to PI Data Archive . However, the
other copy of the interface is not ready to take over the role of primary if failover is
triggered.
PI Universal Interface (UniInt) 4.6.4 User Guide
79
UniInt interface operation
Error messages:
• 16-May-06 17:29:06
ifc 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
Cause: The active ID point is not configured properly.
Resolution: Check validity of point attributes. Make sure the location1 attribute is valid
for the interface. All failover points must have the same settings for the pointsource and
location1 attributes. Modify point attributes as necessary and restart the interface.
• 16-May-06 17:38:06
ifc 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 point is not configured properly.
Resolution: Check validity of point attributes. Make sure the location1 attribute is valid
for the interface. All failover points must have the same settings for the pointsource and
location1 attributes. Modify point attributes as necessary and restart the interface.
• 17-May-06 09:06:03
ifc> 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 the parameter to a positive integer and restart the interface.
• 17-May-06 09:06:03
ifc 1>The Failover ID parameter (/UFO_ID) was found but the ID for the
redundant copy was not found
Cause: The ufo_otherid parameter is not defined or has not been assigned a positive
integer value.
Resolution: Change the parameter to a positive integer and restart the interface.
• 17-May-06 09:06:03
ifc 1> UniInt failover: Interface in an "Error" state.
failover control points.
Could not read
Cause: The failover control points on the data source are returning an erroneous value. The
error can be caused by creating a non-initialized control point on the data source. (Phase 1
failover only.)
Resolution: Check validity of the value of the control points on the data source.
• 16-May-06 17:29:06
ifc 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 point is not configured properly. (Phase 1 failover only.)
Resolution: Check validity of point attributes. For example, make sure location1 attribute
is valid for the interface. All failover points must have the same pointsource and
location1 attributes. Modify point attributes as necessary and restart the interface.
80
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
• 17-May-06 09:05:39
ifc 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. As a result of receiving this
error, the interface enters the Backup in Error state.
Resolution: Check validity of the value of the active ID point on the data source. For example,
if the value for the active ID point shows up as *** on the Cimplicity Point Control Panel,
modify the value of the point to a valid value.
• 17-May-06 09:06:03
ifc 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 enters 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 Cimplicity Point Control
Panel, modify the value of the point to a valid value.
• 27-Jun-08 17:27:17
PI Eight Track 1 1> Error 5: Unable to create file
‘\\georgiaking
\GeorgiaKingStorage\UniIntFailover\\PIEightTrack_eight_1.dat’
Verify that interface has read/write/create access on file server machine.
Initializing UniInt library failed
Stopping Interface
Cause: This message is logged when the interface is unable to create a new failover
synchronization file at startup. The creation of the file only takes place the first time either
copy of the interface is started and the file does not exist. The error number most commonly
seen is error number 5. Error number 5 is an access denied error and is likely the result of a
permissions problem.
Resolution: Ensure that the account that the interface is running under has both read and
write permissions for the folder. Change the folder permissions to allow the account in the
Log on as property of the Windows service to create files in the folder.
• Sun Jun 29 17:18:51 2008
PI Eight Track 1 2> WARNING> Failover Warning: Error = 64
Unable to open Failover Control File ‘\\georgiaking\GeorgiaKingStorage\Eight
\PIEightTrack_eight_1.dat’
The interface will not be able to change state if PI is not available
Cause: The interface is unable to open the failover synchronization file (phase 2 failover).
The interface failover operates correctly as long as communication to PI Data Archive is not
interrupted. If communication to PI Data Archive is interrupted while one or both interfaces
cannot access the synchronization file, the interfaces remain in the state they were in at the
time of the second failure, so the primary interface remains primary and the backup
interface remains backup.
Resolution: Change the folder or file permissions to allow the account in the Log on as
property of the Windows service to read and write the failover synchronization file.
PI Universal Interface (UniInt) 4.6.4 User Guide
81
UniInt interface operation
Disconnected startup messages
This section contains informational messages and their meanings, and error messages and
their causes and resolutions.
Informational messages:
• 21-Nov-06 16:57:51
WriteSeconds.exe>PI-API> Attempting to initialize and validate cache file:
c:/pipc/interfaces/test/test_freebird_abc_1_dgcache.dat.
Meaning: API Cache Manager looks for the digital cache file in the specified path and
attempts to initialize and validate the file. If the file is not found, it attempts to create it.
• 21-Nov-06 16:54:41
WriteSeconds.exe>PI-API> Successfully validated cache file:
c:/pipc/interfaces/test/test_freebird_abc_1_dgcache.dat
Meaning: API Cache Manager was able to validate the existing digital cache file. A valid
cache file means the digital cache file is designated for this particular instance of the
interface, contains PI Data Archive version information, and that the files are capable of
receiving new data. The file might not contain all the necessary point information.
• 21-Nov-06 16:54:41
WriteSeconds.exe>PI-API> Successfully validated cache file:
c:/pipc/interfaces/test/test_freebird_abc_1_ptcache.dat
Meaning: API Cache Manager was able to validate the existing point cache file. A valid cache
file means the point cache file is designated for this particular instance of the interface,
contains PI Data Archive version information, and that the files are capable of receiving new
data. The file might not contain all the necessary point information.
• 21-Nov-06 16:57:51
WriteSeconds.exe>PI-API> Successfully created cache file:
c:/pipc/interfaces/test/test_freebird_abc_1_dgcache.dat.
Meaning: API Cache Manager was able to create the specified file. The interface successfully
connected to PI Data Archive to retrieve the version information needed to create the cache
file. The file has not been constructed with digital state information and continues to
require a connection to PI Data Archive.
• 21-Nov-06 16:57:51
WriteSeconds.exe>PI-API> Successfully created cache file:
c:/pipc/interfaces/test/test_freebird_abc_1_ptcache.dat.
Meaning: API Cache Manager was able to create the specified file. The interface successfully
connected to PI Data Archive to retrieve the version information needed to create the cache
file. The file has not been constructed with point information and continues to require a
connection to PI Data Archive.
• 21-Nov-06 16:54:41
WriteSeconds.exe>PI-API> Point information will be loaded from cache file:
c:/pipc/interfaces/test/test_freebird_abc_1_ptcache.dat
Meaning: API Cache Manager has determined the point and digital cache files have been
completely constructed and can be used to load point information. No connection to PI Data
Archive is necessary for the interface to start.
• 21-Nov-06 17:00:04
WriteSeconds.exe>PI-API> Renamed cache file:
82
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
c:/pipc/interfaces/test/test_freebird_abc_1_dgcache.dat
to
c:/pipc/interfaces/test/test_freebird_abc_1_dgcache_20061121220004.dat.
Meaning: API Cache Manager has determined the current digital cache file is invalid and
unusable. The file has been renamed as indicated in the message. Expect to see a message
indicating a new digital cache file has been created. A connection to PI Data Archive must be
available for the interface to start.
• 21-Nov-06 17:00:04
WriteSeconds.exe>PI-API> Renamed cache file:
c:/pipc/interfaces/test/test_freebird_abc_1_ptcache.dat
to
c:/pipc/interfaces/test/test_freebird_abc_1_ptcache_20061121220004.dat.
Meaning: API Cache Manager has determined the current point cache file is invalid and
unusable. The file has been renamed as indicated in the message. Expect to see a later
message indicating that a new point cache file has been created. A connection to PI Data
Archive is required for the interface to start.
• 21-Nov-06 16:57:51
WriteSeconds.exe>PI-API> Cache valid for reading and writing, but not complete.
Point information will be retrieved from the PI Server and saved in cache
file:
c:/pipc/interfaces/test/test_freebird_abc_1_ptcache.dat.
Meaning: API Cache Manager was able to create and validate the point cache file, but the file
has not been constructed with point record and attributes information. This message also
indicates the digital cache must be constructed with digital state information. A connection
to PI Data Archive is required for the interface to start so the file can be constructed.
• 21-Nov-06 16:57:51
PI-WriteSeconds 1> Point cache being constructed to store point information.
Cache file: c:/pipc/interfaces/test/test_freebird_abc_1_ptcache.dat.
Cache synchronization enabled with period set to 250 ms.
Meaning: UniInt Cache Manager has detected a point caching file that has not been
constructed with point record and attributes information. This message also indicates the
digital cache must be constructed with digital state information. A connection to PI Data
Archive is required for the interface to start so the file can be constructed. The message also
indicates that cache synchronization is enabled with a time period set to 250 milliseconds.
• 21-Nov-06 16:57:51
PI-WriteSeconds 1> Begin synching cache file: c:/pipc/interfaces/test/
test_freebird_abc_1_ptcache.dat
Meaning: UniInt Cache Manager has loaded point information from the cache, entered the
control loop, connected to PI Data Archive , and begun cache synchronization. The digital
cache has also begun synchronization.
• 21-Nov-06 16:57:51
PI-WriteSeconds 1> Completed synching cache file: c:/pipc/interfaces/test/
test_freebird_abc_1_ptcache.dat
Meaning: UniInt Cache Manager has completed point and digital cache synchronization.
Updates will be sent to the interface.
Configuration errors:
• 22-Nov-06 16:21:19
PI-WriteSeconds 1> Error = -1: Point caching configuration error.
PI Universal Interface (UniInt) 4.6.4 User Guide
83
UniInt interface operation
The PI SDK is being used to retrieve point attribute information.
Unable to utilize point caching while in this mode.
Disable cachemode by removing "/cachemode" parameter from the
startup command file and restart the interface.
Stopping Interface
Cause: UniInt Cache Manager has determine PI SDK is being used to retrieve point attribute
information while attempting to start the interface in a disconnected startup mode. Caching
will be disabled and the interface will be shutdown.
Resolution:
◦ Option 1: Remove the cachemode startup command parameter and restart the interface.
◦ Option 2: Try using the /pisdk=0 startup command parameter to disable the interface.
Restart the interface. Not all interfaces can disable PI SDK using this option.
• 29-Nov-06 15:45:08
PI-WriteSeconds 1> Disconnected Startup is not available with PI API prior to
Version: 1.6, Build 1.5
To utilize the disconnected startup configuration, upgrade to
PI API Version: 1.6, Build 1.5 or later and restart the interface.
Stopping Interface.
Cause: UniInt Cache Manager has found a PI API version currently installed on the interface
node that does not support disconnected startup. The interface has been configured with
the cachemode startup parameter and will be stopped.
Resolution:
◦ Option 1: Upgrade PI API on the interface node to version 1.6.1.x or later. Restart the
interface.
◦ Option 2: Remove the cachemode startup command parameter. Restart the interface.
• 29-Nov-06 15:56:19
PI-WriteSeconds 1> Error: 0, Setting cache function pointer failed.
Unable to load picm_closecache from API dll
Point caching unavailable for this interface.
Correct the error or remove the /cachemode startup command parameter.
Stopping Interface.
Cause: UniInt Cache Manager has failed to load a required function from PI API. The
interface has been configured with the cachemode startup parameter and will be stopped.
Resolution:
◦ Option 1: Upgrade PI API on the interface node to version 1.6.1.x or later. Restart the
interface.
◦ Option 2: Remove the cachemode startup command parameter. Restart the interface.
Other errors:
• 22-Nov-06 16:35:27
WriteSeconds>PI-API> Error initializing digital set cache file: /opt/home/
piadmin/pi/clients/interfaces/test/test_freebird_ab_1_dgcache.dat.
Point information will be retrieved from the PI Server.
Cause: PI API Cache Manager was unable to create the digital cache file necessary for
disconnected startup. The message also indicates PI Data Archive will be used to retrieve
point information. To start, the interface requires a connection to PI Data Archive.
84
PI Universal Interface (UniInt) 4.6.4 User Guide
UniInt interface operation
Resolution: Make sure the file path to the filename is identical to the path shown in the
error message.
UniInt device status messages
The device status health point produces messages based on the interface device status.
Messages that are interface-specific are documented in the interface user guide.
The following table lists standard status strings.
Message
Description
0 | Good
The interface is working properly, and reading/
writing data.
10 | Connected / No Data
The interface is connected to the device, but not
receiving data.
30-70
Interface-specific status messages. Refer to
interface user guide for more information.
90 | Starting
The interface is starting, but not connected to the
device.
95 | Device(s) in error
There is a communication error with the device.
99 | Intf Shutdown
The interface is shutting down.
PI Universal Interface (UniInt) 4.6.4 User Guide
85
UniInt interface operation
86
PI Universal Interface (UniInt) 4.6.4 User Guide
Technical support and other resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or through the
OSIsoft Tech Support Contact Us page (https://techsupport.osisoft.com/Contact-Us/). The
website offers additional contact options for customers outside of the United States.
When you contact OSIsoft Technical Support, be prepared to provide this information:
• Product name, version, and build numbers
• Details about your computer platform (CPU type, operating system, and version number)
• Time that the difficulty started
• Log files at that time
• Details of any environment changes prior to the start of the issue
• Summary of the issue, including any relevant log files during the time the issue occurred
To ask questions of others who use OSIsoft software, join the OSIsoft user community,
PI Square (https://pisquare.osisoft.com). Members of the community can request advice and
share ideas about the PI System. The PI Developers Club space within PI Square offers
resources to help you with the programming and integration of OSIsoft products.
PI Universal Interface (UniInt) 4.6.4 User Guide
87
Technical support and other resources
88
PI Universal Interface (UniInt) 4.6.4 User Guide