PI Interface Configuration Utility (ICU) 1.5.

User Guide
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577 USA
Tel: (1) 510-297-5800
Fax: (1) 510-357-8136
Web: http://www.osisoft.com

PI Interface Configuration Utility (ICU) 1.5.1 User Guide

© 1992-2020 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, OSIsoft EDS, 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 Developers Club, PI Integrator for Business Analytics, PI Interfaces,
PI JDBC Driver, PI Manual Logger, PI Notifications, PI ODBC Driver, PI OLEDB Enterprise,
PI OLEDB Provider, PI OPC DA Server, 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-19, or their successors, as applicable. OSIsoft, LLC.
Version: 1.5.1.8
Published: 23 March 2020
Contents

Introduction to PI Interface Configuration Utility (PI ICU)..............................................1

Version requirements...................................................................................................................................... 1
How PI ICU works............................................................................................................................................ 1
Multiple interface instances.........................................................................................................................2
Interface-specific PI ICU controls................................................................................................................. 2
Required PI Server configuration................................................................................................................. 2
Required Windows permissions................................................................................................................... 5

Getting started with PI ICU......................................................................................... 7

Register an interface instance with PI ICU....................................................................................................... 8
Create a new instance of a PI interface........................................................................................................ 8
Create a new instance of a PI interface from an existing instance...............................................................10
Start the PI interface service.......................................................................................................................... 10
Run the PI interface interactively................................................................................................................11
PI Buffer Subsystem (version 2018 SP2 Patch1 or later)................................................................................. 12
Start buffering (PI Buffer Subsystem version 4.3 or later)............................................................................... 12
Start buffering (PI Buffer Subsystem versions earlier than 4.3)....................................................................... 13
View PIPC log files......................................................................................................................................... 13
Start PIPC log server......................................................................................................................................14
Manage interfaces......................................................................................................................................... 14
Remove interfaces.........................................................................................................................................14
Remove an interface from PI ICU............................................................................................................... 15
Remove and uninstall an interface from PI ICU...........................................................................................15
Backup and restore........................................................................................................................................ 15

Using PI ICU............................................................................................................. 17
Interface selection and operation.................................................................................................................. 18
General page................................................................................................................................................. 19
General options......................................................................................................................................... 20
Scan Classes.............................................................................................................................................. 20
PI Host Information................................................................................................................................... 21
Interface Installation Path.......................................................................................................................... 23
Interface Batch Filename........................................................................................................................... 23
Interface page............................................................................................................................................... 23
Interface-Specific Parameters....................................................................................................................24
Additional parameters input...................................................................................................................... 24
Service page.................................................................................................................................................. 25
Service Configuration................................................................................................................................ 26
Installed services and Dependencies..........................................................................................................28
Startup Type..............................................................................................................................................29
Create / Remove........................................................................................................................................ 30
Start, Stop, or Restart................................................................................................................................ 30
UniInt page....................................................................................................................................................30
Performance and Behavior.........................................................................................................................31
Data Handling............................................................................................................................................33
Timestamps...............................................................................................................................................34
Outputs..................................................................................................................................................... 35
(UniInt) Failover.............................................................................................................................................36

PI Interface Configuration Utility (ICU) 1.5.1 User Guide iii

Contents

Phase 1...................................................................................................................................................... 36
Phase 2...................................................................................................................................................... 39
Select the other interface of a failover pair.................................................................................................41
(UniInt) Health Points.................................................................................................................................... 41
UniInt health point types........................................................................................................................... 43
(UniInt) Performance Counter Points............................................................................................................. 47
Performance counter point types.............................................................................................................. 49
(UniInt) Performance Points.......................................................................................................................... 52
(UniInt) PI SDK.............................................................................................................................................. 54
PI SDK options...........................................................................................................................................54
(UniInt) Disconnected Startup....................................................................................................................... 55
(UniInt) Debug............................................................................................................................................... 57
Debug Levels............................................................................................................................................. 58
Debugging Options................................................................................................................................... 58
IO Rate page................................................................................................................................................. 59
Interface Status page.................................................................................................................................... 60
Interface Status Utility Instance Information..............................................................................................61
Interface Status Utility Tag Definition........................................................................................................ 61
Watchdog point.........................................................................................................................................62

PI ICU menu options................................................................................................. 65

Interface menu.............................................................................................................................................. 65
New Windows Interface Instance from EXE............................................................................................... 65
New Windows Interface Instance from BAT file.......................................................................................... 67
New UNIX/VMS Interface Instance............................................................................................................ 68
Delete Interface Instance...........................................................................................................................69
Unregister Interface from ICU....................................................................................................................69
SDK Connections....................................................................................................................................... 70
Connect to Primary....................................................................................................................................70
Save...........................................................................................................................................................70
View Command Line..................................................................................................................................70
Start Interactively...................................................................................................................................... 70
Exit............................................................................................................................................................ 71
Tools menu.................................................................................................................................................... 71
Log Files.....................................................................................................................................................71
Buffering.................................................................................................................................................... 73
Buffering Manager..................................................................................................................................... 75
Run apisnap...............................................................................................................................................84
Diagnostics................................................................................................................................................85
PointSources............................................................................................................................................. 86
Date/Time Properties................................................................................................................................ 86
View Digital State Sets.............................................................................................................................. 86
Interface Tag Creation Utility..................................................................................................................... 87
Interface Communication Test Utility.........................................................................................................87
Interface Specific Configuration................................................................................................................. 87
Options......................................................................................................................................................87

PI ICU installation.................................................................................................... 93
Installation of PI ICU...................................................................................................................................... 93
Uninstall PI ICU............................................................................................................................................. 94

Migrate an interface to another PI Server...................................................................95

iv PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Contents

Error and informational messages for PI ICU.............................................................. 97

Technical support and other resources..................................................................... 101

PI Interface Configuration Utility (ICU) 1.5.1 User Guide v

Contents

vi PI Interface Configuration Utility (ICU) 1.5.1 User Guide

Introduction to PI Interface Configuration Utility
(PI ICU)
PI Interface Configuration Utility (PI ICU) is an application that aids in PI System management
by consolidating the setup and configuration options required for new and existing PI
interfaces. Any new or existing PI interface, with a couple of exceptions, can be configured and
maintained using PI ICU.
PI ICU allows you to:
• Configure all interface parameters.
• Manage, start and stop the interface service.
• View and configure interface service dependencies.
• Configure and run buffering.
• Configure and run the PI Log Server application.
• Manage multiple PI interfaces.
• Quickly find and view the PIPC log files.
• View the PI message log.
• Execute interface configuration diagnostics.
• Run the pibufss -cfg buffering utility.
• Run the bufutil buffering utility.

Topics in this section

• Version requirements
• How PI ICU works

Version requirements
• PI Server 3.3.361.43 or later is required for the host PI Server. PI ICU uses the PI Module
Database on the PI Server as a repository for interface startup parameters.
• PI ICU 1.4.1.0 and later requires that PI SDK version 1.3.4 or later be installed on the
machine where PI ICU runs. PI SDK is installed with PI ICU.
• PI ICU 1.5.1, which includes an enhanced version of the PI SDK, is supported by Windows
8.1 and 10, and Win Server 2012 and later.

How PI ICU works

PI ICU works as the PI System Manager's main access point for managing and configuring PI
interfaces, eliminating the need for users to build and maintain batch (.bat) files. PI ICU
automatically stores information in the PI Module Database and in the interface .bat file
simultaneously.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 1

Introduction to PI Interface Configuration Utility (PI ICU)

Note:
Once an interface has been configured with PI ICU, all subsequent interface management
should be done with this utility.

Topics in this section

• Multiple interface instances
• Interface-specific PI ICU controls
• Required PI Server configuration
• Required Windows permissions

Multiple interface instances

Multiple instances of an interface may use the same executable (.exe) without copying and
renaming the interface executable file. A new interface instance is assigned a service ID 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.
This service ID is not related to the Interface ID number (/id) specified on the General page.
However, users may select the same service ID that they will use for the ID number.

Interface-specific PI ICU controls

PI ICU provides standard parameters and configuration settings for each PI interface. Many
interfaces have similar settings, such as those based on OSIsoft's UniInt framework.
For parameters unique to individual PI interfaces, there are interface-specific PI ICU controls.
PI ICU controls provide access to interface-specific options through the common PI ICU
application framework. When a PI ICU control is installed, the Interface page in PI ICU includes
an interface-specific dialog box containing the native interface settings.
If available, PI ICU controls are usually installed with the interface.
You can visit the OSIsoft Customer Portal (https://my.osisoft.com/ ) to use the OSIsoft Tech
Support PI Interfaces Search page to see if your interface has a PI ICU control and if your
version is the latest.
Note that any PI interface may still be configured with PI ICU, even if the PI ICU control for the
interface has not been installed or developed yet, by using a generic dialog box supplied in the
Interface page. For more details on interface-specific settings, consult the appropriate PI
interface's user guide.

Required PI Server configuration

This section provides the information that you need to configure:
• Connection and authentication methods for PI ICU.
• PI Server security to grant the required access rights to these connections.
When PI ICU is installed on an interface node, PI ICU obtains permissions to access PI Server
objects by logging on with some form of credentials. The PI Server authenticates these
credentials and establishes a security context for each client program. The security context is

2 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Introduction to PI Interface Configuration Utility (PI ICU)

specific to the credentials used to log on. Each securable PI Server object has access control
information. Authorization for a client program to access a securable PI Server object is
determined by comparing information in the security context with the access control
information for the object.
Several methods are available for logging on:
• Explicit login
• PI trust
• PI mapping (requires PI Server version 3.4.380 or later and PI SDK 1.3.6 or later)
PI ICU is an interactive application and all the methods for logging on to the PI Server can be
used.
If the PI Server is version 3.4.380 or later, OSIsoft recommends using Windows security
through PI mappings. Windows security provides the strongest authentication and full
Windows account traceability in the PI Server log and audit trail records.
Refer to the PI Server documentation for details about how to create PI trusts or PI mappings.

PI Module Database permissions

PI ICU creates the module Interfaces under the %OSI module. PI ICU configuration settings
are stored in a hierarchy of modules under the Interfaces module.
PI ICU requires the following:
• Write access for the PIModules table (Database Security) in order to create modules.
• Write access for the %OSI module in order to create the Interfaces module.
• Write access for the Interfaces hierarchy to register interface instances with PI ICU and to
change configuration settings.

Digital state table permissions

When PI ICU starts, it checks for the existence of a digital set named InterfaceStatus. If this
digital set does not exist, PI ICU requires write access for the PI Server digital state table (PIDS
in Database Security) to create the InterfaceStatus digital set.
When UniInt failover is configured for an interface instance, PI ICU checks for the existence of a
digital set that is used by special UniInt failover digital points. If this digital set does not exist,
PI ICU requires write access for the PI Server digital state table (PIDS).
The PI ICU controls for some interfaces have the ability to create specific digital sets that are
needed by the interface. Consult the PI ICU control section in the user guide for each interface
that PI ICU will manage. Since PI ICU controls run inside the PI ICU process, PI ICU requires
write access for the PI Server digital state table for an ICU Control to create digital sets.

PI point database permissions

PI ICU can create, edit, or delete the following types of points that are common to UniInt-based
interfaces:
• PI Perfmon interface performance counter points
• UniInt performance points
• UniInt health points

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 3

Introduction to PI Interface Configuration Utility (PI ICU)

To create or delete these types of points, PI ICU requires write access for the PI Server PIPoint
table (database security).
To edit or delete individual points of these types, PI ICU requires write access for each point. PI
points have two sets of security attributes: one set controls access to the point attributes and
the other set controls access to the point data. PI ICU needs write access for point attributes of
these types of points. PI ICU does not access point data.
The PI ICU controls for some interfaces have the ability to create interface-specific points.
Consult the user guide for each interface that PI ICU will manage. Since PI ICU controls run
inside the PI ICU process, PI ICU requires write access for the PI Server PIPoint table for an ICU
Control to create points.

Access permissions summary

This section summarizes the access permissions that PI ICU requires for PI Server securable
objects.
PI Securable object Access permissions
PIDBSEC table R
PIModules table RW
%OSI module RW
%OSI\Interfaces module and all submodules RW
PIPoint table RW
Individual PI points (PtAccess or PtSecurity attribute) RW
PIDS table RW

With the access permissions in this table, PI ICU can perform all its functions.

PI mappings and security permissions

For PI Server version 3.4.380 or later, PI mappings can be created that allow PI ICU to log on
automatically. For details about PI mappings, see the PI Server documentation.
The Windows accounts that are allowed to run PI ICU must map to a PI identity that has the
access permissions in the table in the “Access permissions summary” section above.

PI trust and security permissions

To grant the required security permissions to PI ICU, a PI trust can be created that allows PI
ICU from a specific computer, or from any computer, to log on automatically. For details about
PI trusts, see the PI Server documentation.
Prior to PI Server version 3.4.380, PI trusts specify a PI user to log on. With PI Server version
3.4.380 and later, the PIUser attribute of a PI trust also can be a PI identity or PI group. In the
following PI trust example, replace identity with a PI user, PI group, or PI identity, depending on
the PI Server version.
You can change the trust name to any unique name. For example, if multiple interface nodes are
used with one PI Server, the trust names for PI ICU on each computer must be different.
PI trusts can specify the trusted interface node by either its network node name or IP address.
If a name resolution service, like DNS, is available, OSIsoft recommends using the IPHost
attribute as shown in the following example. To specify the interface node by IP address,

4 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Introduction to PI Interface Configuration Utility (PI ICU)

replace the IPHost attribute with the IPAddr attribute, which must be accompanied by the
NetMask attribute.
The following trust allows PI ICU on the computer named in the trust to log on automatically to
the PI Server:
Trust = PIICUTrust
AppName = PI-ICU.exe
IPHOST = Host name of the computer where PI ICU is located
PIUser = identity

In this trust the identity must have the access permissions in the table in the “Access
permissions summary” section.
Note:
With this PI trust, anyone who can log on to the interface node can use PI ICU to change
interface configuration settings. To restrict the ability to change interface configuration
settings, add the Domain and OSUser attributes to the trust definition and create
individual PI trusts for each Windows account that is allowed to change interface
settings.
OSIsoft recommends PI mappings over PI trusts to control the Windows accounts that have
access to PI ICU.

Required Windows permissions

The following sections describe the Windows permissions and security privileges required by
PI ICU.

Registry permissions
PI ICU stores some settings in the local registry. The PI ICU user account must have read/write
permissions to update these registry keys and any below them:
For 32-bit operating systems:
HKEY_LOCAL_MACHINE\SOFTWARE\PISystem\PI-SDK
HKEY_LOCAL_MACHINE\SOFTWARE\PISystem\InterfaceConfigurationUtility
HKEY_LOCAL_MACHINE\SOFTWARE\PISystem\Interfaces
HKEY_LOCAL_MACHINE\SOFTWARE\PISystem\ICU

For 64-bit operating systems:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\PISystem\PI-SDK
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\PISystem\InterfaceConfigurationUtility
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\PISystem\Interfaces
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\PISystem\ICU

Service Control Manager permissions

PI ICU makes calls to the Service Control Manager in order to query service status of interfaces,
bufserv, and pinetmgr, and creates, edits, and removes services. In Windows, only
Administrators and Power Users can start, stop, or pause a service by default.
For more information about methods for granting users the rights to manage services, see the
Microsoft Knowledge Base article How to grant users rights to manage services in Windows
Server 2003 (http://support.microsoft.com/?kbid=325349).

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 5

Introduction to PI Interface Configuration Utility (PI ICU)

Folder permissions
PI ICU reads and writes to files in the PIPC directory tree. The following permissions are
required for it to function correctly:
• Read Permissions to PIPC directory
• Read/Write Permissions to PIPC\dat directory
• Read/Write Permissions to PIPC\Interfaces directory and any subdirectories under this
directory.

6 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

Getting started with PI ICU
PI ICU provides a user interface for setting parameters and managing PI interface services:
• Under the menu and toolbar, interface selection and connection controls describe the
current interface.
• The tree control on the left allows you to access groups of settings.
• Control settings appear on the right and are dependent on the selection in the tree control.

Topics in this section

• Register an interface instance with PI ICU
• Start the PI interface service
• PI Buffer Subsystem (version 2018 SP2 Patch1 or later)
• Start buffering (PI Buffer Subsystem version 4.3 or later)
• Start buffering (PI Buffer Subsystem versions earlier than 4.3)
• View PIPC log files
• Start PIPC log server
• Manage interfaces
• Remove interfaces

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 7

Getting started with PI ICU

• Backup and restore

Register an interface instance with PI ICU

Interfaces must be registered in order to work with PI ICU. To register an interface, you can
either:
• Create a new instance of a PI interface, or
• Create an additional instance of a PI interface from an existing instance

Topics in this section

• Create a new instance of a PI interface
• Create a new instance of a PI interface from an existing instance

Create a new instance of a PI interface

Note:
After PI ICU has been used to configure a PI interface, all subsequent configuration
changes should be conducted in PI ICU. PI ICU will prompt you if the command line
parameters stored in the Module Database do not match those stored in the PI interface
batch file (.bat file).

Before you start

Consult the interface-specific user guide for configuration details required to run the interface.
Go to the OSIsoft Customer Portal Products page (https://customers.osisoft.com/s/products)
page or to Live Library (https://livelibrary.osisoft.com/LiveLibrary/web/ui.xql?
action=html&resource=publist_home.html) to download interface user guides.

Procedure
1. Install the PI interface you want to configure.
2. Install any ICU controls available for the interface, if not already installed.
3. Run PI ICU and choose Interface > New Windows Interface Instance from EXE. You can also
click the Create new interface instance button on the toolbar.

The Configure a New Interface dialog box opens.

8 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Getting started with PI ICU

4. Click Browse to browse to the interface executable (.exe) file for the new interface.
5. From the Host PI Data server/collective list, select the PI Server or PI Server collective to
which the interface will send data.
6. If you specify a collective, then from the Collective Member list, select the specific collective
member to which the interface will send data.
7. If you have the information available, enter the optional settings in the Interface name,
Point Source, Interface ID # and Service ID fields.
8. Click Add to add the interface.
9. In the Confirmation dialog box, click OK.
The interface appears in the Interface text box in the main ICU window.
10. Select the proper Type for the interface on the main ICU window, if it is not selected
automatically.
11. Complete configuration of the interface by filling in the desired fields on the PI ICU page
window.
For details on which attributes are required by a particular interface, see the appropriate PI
interface user guide.
12. Use PI ICU and an application to create the PI points needed to configure and run the PI
interface. Available applications include:

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 9

Getting started with PI ICU

◦ Point Builder tool in PI System Management Tools (PI SMT) - see the "Point Builder"
topic in the "PI Server 2018 SP3" in Live Library (https://livelibrary.osisoft.com) user
guide.
◦ PI Tag Configurator add-in to Microsoft Excel (included with PI SMT) - see the "Use
worksheets created in PI Tag Configurator" topic in "PI Server 2018 SP3" in Live Library
(https://livelibrary.osisoft.com) user guide.
◦ PI Builder add-in to Excel - see the "PI Builder" topic in the "PI Server 2018 SP3" in Live
Library (https://livelibrary.osisoft.com) user guide.

Create a new instance of a PI interface from an existing instance

You can create a new instance of the same interface without copying and renaming the
interface executable file. The new interface is assigned a service ID to distinguish it from other
copies of the interface that use the same executable file.
Note:
After PI ICU has been used to configure a PI interface, all subsequent configuration
changes should be conducted within PI ICU. PI ICU overwrites any manual edits made to
PI interface batch (.bat) files.

Procedure
1. Install an ICU control for the existing PI interface, if available.
2. Run PI ICU and choose Interface > New Windows Interface Instance from BAT file. You can
also click the Import existing interface .BAT file button on the toolbar. Use the dialog
box that appears to browse to the proper file, and click Open.
The interface is loaded and appears in the main PI ICU dialog box.
3. Select the appropriate Type for the interface, if it is not selected automatically. For details on
which attributes are required by a particular interface, see the appropriate PI interface user
guide.
4. For details on which attributes are required by a particular interface, see the appropriate PI
interface user guide.
5. Use PI ICU and the following applications to create PI points and to configure and run the PI
interface:
◦ Point Builder tool in PI System Management Tools (PI SMT) - see the "Point Builder"
topic in the "PI Server 2018 SP3" in Live Library (https://livelibrary.osisoft.com) user
guide.
◦ PI Tag Configurator add-in to Microsoft Excel (included with PI SMT) - see the "Use
worksheets created in PI Tag Configurator" topic in "PI Server 2018 SP3" in Live Library
(https://livelibrary.osisoft.com) user guide.
◦ PI Builder add-in to Excel - see the "PI Builder" topic in the "PI Server 2018 SP3" in Live
Library (https://livelibrary.osisoft.com) user guide.

Start the PI interface service

After parameters and PI points are configured for the interface, you can use PI ICU to create
and start the interface service.

10 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Getting started with PI ICU

Before starting, you can change settings for the service using the Service branch in the PI ICU
tree:

• Make appropriate changes to the Display Name as desired.

• Set service dependencies using the Add and Remove buttons to move existing services into
and out of the Interface Dependencies list.
Services listed in the Interface Dependencies list are started automatically by the Service
Control Manager when the interface is started.
To start or stop the PI interface service:

• Click the Start or Stop button on the PI ICU toolbar.

The current status of a selected PI interface service is indicated in the status bar at the bottom
of the PI ICU application.

• Navigate to the Tools > Options > Service page where you can set the rate at which status is
updated.

Run the PI interface interactively

PI interfaces can be run interactively in order to easily see debug messages and errors.

Procedure
1. Choose Interface > Start Interactive to start the interface in interactive mode.
2. Press Ctrl-C or close the command prompt window to stop operation in interactive mode.
A command prompt appears and the interface begins operation automatically. Messages
appear at the command prompt that indicate the status of the interface and other pertinent
information.

Note:
If the interface is already running as a service, you are prompted to stop the service
before running it again interactively.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 11

Getting started with PI ICU

PI Buffer Subsystem (version 2018 SP2 Patch1 or later)

PI Buffer Subsystem (PIBufss), which works with PI Server 3.4.375 or later, is one of two
buffering services supported in PI ICU, the other being API Buffer Server (bufserv). See
Buffering for information on those two services.

PIBufss is designed to enhance the high availability (HA) features of PI Server. PIBufss buffers
data only to one non-replicated PI Server or one PI collective (with its various member nodes).
Note:
In order to assure that PI buffering functions properly, the user specified in the "Log on
as" portion of the Service tab must be a member of either the "PI Buffering
Administrators" or the "PI Buffer Writers" user groups. A virtual service account can be
added to those local groups, just like with any local/domain account. Failure to add a user
to at least one of these user groups could result in a failure to buffer data. For more
details please see the PI Buffer Subsystem (https://customers.osisoft.com/s/
productcontent?id=a7R1I000000XyVJUA0) user guide.
The version of PI Buffer Subsystem currently installed determines the process you follow to
start buffering. It does not matter whether buffering is configured on this computer, or
whether you use PI Buffer Subsystem or API Buffer Server.

Start buffering (PI Buffer Subsystem version 4.3 or later)

Before you start
These instructions apply only if PI Buffer Subsystem version 4.3 or later is installed on this
computer.
To determine the version that you have installed, select ToolsBuffering... from the PI ICU
toolbar. If you have PI Buffer Subsystem version 4.3 or later installed, the Buffering Manager
window displays. In that case, you would use the following procedure to start buffering.
If version 3.4.380.79 or earlier is installed, an alert displays indicating that PI Buffer Subsystem
is not configured. If you get that alert, refer to Start buffering (PI Buffer Subsystem versions
earlier than 4.3).

Procedure
1. Click Tools > Buffering....
2. When the dialog box displays asking if you want to configure PI Buffer Subsystem, click Yes.
Note:
If you currently use API Buffer Server (bufserv), you may need to confirm more than
one prompt.
The Buffering Manager - New Install Wizard window opens. This indicates one of two things:
◦ This computer is configured to buffer data using API Buffer Server (bufserv). In this case,
and before continuing, review the "Install or upgrade to PI Buffer Subsystem 4.3 or later"
topic found in the Help system. From the Buffering Manager - New Install Wizard window,

12 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Getting started with PI ICU

click Help to navigate to the topic, which also contains information on upgrades from API
Buffer Server.
◦ This computer is not configured to use any form of buffering.
3. To configure buffering, follow the instructions in the Buffering Manager - New Install Wizard
window.
4. After you finish, return to the PI Interface Configuration Utility window. Select each interface,
and on the General page under PI Host Information, look at the Buffering Status setting:
◦ If Buffering Status is On, the buffering configuration for the server to which this interface
sends data is complete. (This is the server specified in the API Hostname field for this
interface.)
◦ If Buffering Status is Off, you need to configure the server specified in the API Hostname
field to receive buffered data from this interface. To add the server to the buffering
configuration, click the Enable button and follow the instructions on the Buffering
Manager screen.

Start buffering (PI Buffer Subsystem versions earlier than 4.3)

PI ICU assists in configuring and running buffering (API Buffer Server or PI Buffer Subsystem).

Before you start

These instructions apply only if PI Buffer Subsystem version 3.4.380.79 or earlier is installed
on this computer. If version 4.3 or later is installed, refer to Start buffering (PI Buffer
Subsystem version 4.3 or later).
Note:
The version of PI Buffer Subsystem currently installed determines the process you follow
to start buffering. It does not matter whether buffering is configured on this computer, or
whether you use PI Buffer Subsystem or API Buffer Server.

Procedure
1. Choose Tools > Buffering to display the Buffering Manager window.
2. Click Settings and select Global. Advanced global configuration.
3. Click Advanced global configuration.
4. Use the drop down menus to select buffering options:
◦ Buffering: Off
◦ PI API Buffering: On
◦ AF SDK Buffering: Buffer if possible (default)
◦ PI SDK Buffering: Off

View PIPC log files

You can use PI ICU to view current PI Log files and modify the settings for the PIPC Log Server
(PILogSrv) service.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 13

Getting started with PI ICU

Procedure
1. Choose Tools > Log Files to access the Log Files dialog box. The PIPC.Log Files page lists all of
the logs currently existing under PIHOME\dat directory by name.
2. Double-click the desired log file in the list to view history in a log file.
Note:
Log files open for viewing in PI ICU do not automatically update. Any messages that
are written while a log file is being viewed will not be visible until the log file is re-
opened in PI ICU.
3. Click Continuous PIPC.Log to open a command prompt window and view messages as they
are written to a PIPC log file.
4. Click Continuous PI Msg Log to open a command window and view the PI message log
messages as they are written.

Start PIPC log server

Use the PIPC Log Server page in PI ICU to start and stop the PIPC Log Server service.

Procedure
1. Configure the Maximum Log File and Maximum Log File Size parameters of the PIPC Log
Server, if desired.
2. Click the Start button to start the service.

Manage interfaces
All PI interfaces registered on the current internet node are listed with the host PI Server in the
Interface drop-down list that appears at the top of the main PI ICU display.

• To switch between registered interfaces, select any interface from the Interface drop-down
list.
You can specify whether interfaces that write to all servers in the known servers list are loaded,
or only interfaces that write to the default PI Server. To specify interface loading:

• Choose Tools > Options > Loading to access interface loading options.
Note:
If there are many servers in the known servers list, PI ICU startup will take longer. If
interfaces on the current node talk only to the default PI Server, it is best to set the
loading option to load interfaces from the default PI Server to expedite PI ICU startup.

Remove interfaces
You can unregister an interface from the PI ICU, which only removes the interface from the PI
Module Database, or you can completely uninstall the interface.

14 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Getting started with PI ICU

Topics in this section

• Remove an interface from PI ICU
• Remove and uninstall an interface from PI ICU

Remove an interface from PI ICU

Use this procedure to remove (unregister) an interface from the PI ICU without uninstalling it.
Note:
De-registering an interface from PI ICU does not delete the batch (.bat) file or the
executable file (.exe) associated with the interface.

Procedure
1. Select the interface to be removed in the Interface drop-down list.
2. Choose Interface > Unregister Interface from ICU.
A confirmation dialog box appears to confirm that you want to de-register the interface
from PI ICU without touching the interface service or files.

Remove and uninstall an interface from PI ICU

Use this procedure to remove (unregister) an interface in PI ICU and remove it from the
machine.

Procedure
1. Select the interface to be removed in the Interface drop-down list.
2. Choose Interface > Delete Interface Instance.
A confirmation dialog box appears to verify removal of the interface service, and prompt
whether to remove the .bat file as well.

Backup and restore

PI ICU loads and stores its settings for each interface in the PI Module Database of the host PI
Server. PI ICU also keeps the .bat file for an interface in sync with the Module Database
whenever the user saves the interface configuration in PI ICU.

Procedure
• During backups, the PI Module Database must be backed up with the host PI Server.
◦ You can back up interface .bat files with system backups.
◦ You can also re-generate a .bat file with PI ICU from settings stored in the PI Module
Database:
Open PI ICU on the interface node, select the desired interface and choose Interface >
Save.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 15

Getting started with PI ICU

16 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

Using PI ICU
PI ICU provides a user interface for setting parameters and managing PI interface services.

• Under the menu and toolbar, interface selection and connection controls describe the
current interface.
• The tree control at left allows you to access groups of settings.
• Control settings appear at right, dependent on the selection in the tree control.

The tree control on the left allows you to access a series of configuration pages that hold
different categories of interface parameters and options. These operations and features are
described in subsequent sections.

Topics in this section

• Interface selection and operation
• General page
• Interface page
• Service page
• UniInt page
• (UniInt) Failover

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 17

Using PI ICU

• (UniInt) Health Points

• (UniInt) Performance Counter Points
• (UniInt) Performance Points
• (UniInt) PI SDK
• (UniInt) Disconnected Startup
• (UniInt) Debug
• IO Rate page
• Interface Status page

Interface selection and operation

All configuration operations are made to the interface selected in the Interface field.
The status of the selected interface service is indicated in the task bar along the bottom of the
PI ICU main dialog box. An asterisk (*) appears in the PI ICU title bar when unsaved changes
exist for the currently-selected interface.

• Click Apply to save changes and keep the PI ICU application active, or choose Interface >
Save.
• Click Close to save any outstanding changes to the currently selected interface and exit the
PI ICU application.
Note:
Saved configuration changes are not applied to running interfaces. For a change to take
effect, the interface must be stopped and restarted.
The interface definition area contains the following settings:

• Interface
The Interface drop-down list indicates the currently selected PI interface. 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.
Only one interface can be selected for configuration at any given time. If - select - appears in
the Interface drop-down list, no interface has yet been selected.
• Rename
Click Rename to specify a different display name for the interface, as the interface is listed in
the Interface drop-down list. If a new name is specified, then the interfaces are reloaded.
• Type
The Type menu specifies the type of interface being configured and provides a list of
supported interface types. In most cases the PI ICU is able to determine the interface type
automatically. If the PI ICU is not able to determine the interface type, you must select the
proper interface type to access a matching PI ICU control.
Once the correct interface type is selected, a PI ICU control installed for the interface type
becomes available under the Interface page. The full name of the interface type is displayed
to the right.

18 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

Note:
Be sure that the Type field is properly set when registering an interface in PI ICU.
• Description
The description field is an optional text field for the user to document/identify the specified
interface.

General page
The General page includes general preference settings for a selected interface.
Note:
Remember to click Apply after making any modifications whenever in PI ICU. An asterisk
(*) appears in the PI ICU caption if there are any pending changes that have not been
applied.

Topics in this section

• General options
• Scan Classes
• PI Host Information
• Interface Installation Path
• Interface Batch Filename

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 19

Using PI ICU

General options
• Point Source
The Point Source field holds the point sources used by all PI points for the interface. The
command-line equivalent is /ps=x, where x is the point source. Point source is not case
sensitive and can be a single or multiple character value depending on the interface
selected. For details on the length restrictions for an interface, see the appropriate interface
user guide.
Interfaces built with UniInt version 4.3 and later support multiple point source definitions
per interface. If multiple sources are supported, the list box below the Point Source field is
enabled. The Add button is enabled when a unique PointSource definition is entered. If
the interface does not support multiple point sources, the list box and Add button are
disabled.
• Interface ID
The Interface ID is either the number or text assigned to identify this instance of the
interface. The command line equivalent is /id=x, where x is the ID number or ID text.

Scan Classes
The Scan Classes list defines the time period between interface scans in terms of hours (HH),
minutes (MM), and seconds (SS). The scans can be scheduled to occur at discrete moments in
time with an optional time offset specified in terms of hours (hh), minutes (mm), and seconds
(ss). If HH and MM are omitted, then the time period is assumed to be in seconds.

• To create a new scan class, click the new scan class button , enter the desired scan class
value in the field provided, and press Enter.
• To delete a scan class, select it from the list and click the delete button .

The command-line equivalent is /f=x, where x is the scan period.

• Select the scan class to be moved and click the appropriate arrow key to adjust the order of
scan classes .

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 Managers who are fully aware of the PI System configuration and the
effects of any such changes.
There is no limit to the number of scan classes that can be defined. PI points are associated
with a particular scan class via the Location4 PI point attribute. For example, all PI points that
have Location4 set to 1 will receive input values at the frequency defined by the first scan
class. Similarly, all points that have Location4 set to 2 will receive input values at the
frequency specified by the second scan class, and so on.
Two scan classes are defined in the following example:

20 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

• Scan class 1: 00:01:00,00:00:05

• Scan class 2: 00:00:07
or, equivalently:

• Scan class 1: 60,5

• Scan class 2: 7
The first scan class has a scanning frequency of 1 minute with an offset of 5 seconds, and the
second scan class has a scanning frequency of 7 seconds. When an offset is specified, the scans
occur at discrete moments in time according to the formula:
scan times = (reference time) + n(frequency) + offset

where n is an integer and the reference time is midnight on the day that the interface was
started.
In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class.
This means that if the interface was started at 05:06:06, the first scan would be at 05:07:05, the
second scan would be at 05:08:05, and so on. Since no offset is specified for the second scan
class, the absolute scan times are undefined.
The definition of a scan class does not guarantee that the associated points are scanned at the
given frequency. If the interface is under a large load, then some scans may occur late or be
skipped entirely. For more information on skipped or missed scans, see the "Hit, skipped, or
missed scans" topic in the "PI Universal Interface (UniInt) User Guide" in Live Library (https://
livelibrary.osisoft.com).

Wall clock scheduling

Scan classes that strictly adhere to wall clock scheduling are now possible. This feature is
available for interfaces that run on Windows and/or UNIX.
Previously, wall clock scheduling was possible, but not across daylight savings time. For
example, 24:00:00,08:00:00 corresponds to one scan a day starting at 8 AM. However, after
a Daylight Savings Time change, the scan would occur either at 7 AM or 9 AM, depending upon
the direction of the time shift.
To schedule a scan once a day at 8 AM (even across daylight savings time), one should use
24:00:00,00:08:00,L. The ,L at the end of the scan class tells UniInt to use the new wall
clock scheduling algorithm.

PI Host Information
PI Host Information is detailed in the right pane of the PI ICU General page.

• Server/Collective
The Server/Collective field is the name of the host PI System where the PI points belonging
to this interface reside.
To appear in the drop-down list, the host PI System must be connected to the interface and
the correct loading option must be set. To connect the interface and the host PI System, click

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 21

Using PI ICU

Interfaces > SDK Connections and add the server. To set the loading option, click Tools >
Options > Loading.
• SDK Member
When connected to a non-replicated PI Server, the SDK Member will always match the
Server/Collective field. When connected to a collective, the SDK Member displays which
member of the collective this interface reports to.
• API Hostname
When connected to a non-replicated PI Server, the API Hostname will always match the
Server/Collective field. When connected to a collective, the API Hostname displays the node
name, fully qualified domain name, or IP address of the collective member in the SDK
Member field.
The command-line equivalent is /host=<hostname>, where <hostname> is the computer
name of the host PI System.
• User
The current user is the user name on the host PI System that the current PI API and PI SDK
connections are using.
• Type
The Type field indicates the type of the PI Server in the SDK Member field. The possible
types are:

◦ Primary - PI3
◦ Secondary - PI3
◦ Non-replicated - PI3
• Version
The Version field indicates the version of PI Server in the SDK Member field.
• Port
The Port field is the machine port number that the current PI API and PI SDK connections
are using.
• Buffering Status
The Buffering Status field is always shown if you use PI Buffer Subsystem 4.3 or later to
buffer data from this interface, or in certain cases if you use API Buffer Server (bufserv).
When using PI Buffer Subsystem 4.3 or later, Buffering Status is On when buffering is
configured for the server to which this interface sends data. (This is the server specified in
the API Hostname field for this interface.)
Buffering Status is Off and an Enable button is displayed if the server specified in the API
Hostname field is not configured to receive buffered data. The Enable button allows you to
add the appropriate server and complete the buffering configuration.
When using API Buffer Server, Buffering Status is Misconfigured if the server specified
under PI Host Information is not configured to receive buffered data.

22 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

Interface Installation Path

The Interface Installation Path points to the location in which the selected interface is
installed. Normally, this should not be changed. If the interface is moved, use the edit button

to change the installation path using the Browse dialog box.

If the Installation Path is changed, click Apply on the General page to save the new installation
path.
Note:
If an interface executable is to be moved, you will first need to remove the interface
service on the Service page with the Remove button.

Interface Batch Filename

The Interface Batch Filename is the name of the batch file that is being modified. This helps the
user know exactly which batch file is being updated when changes are made.

Interface page
The Interface page will display either:

• An interface-specific PI ICU control that aids in configuring parameters specific to just the
current interface.
• A text box into which additional parameters specific to just the current interface can be
added.

Topics in this section

• Interface-Specific Parameters
• Additional parameters input

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 23

Using PI ICU

Interface-Specific Parameters
Interface-specific PI ICU controls are available for an assortment of PI interfaces to make
configuration and management of these interfaces easier. If the PI ICU control for the selected
interface has been installed on the PI ICU machine, then the Interface page will display a dialog
box tailored to this interface.
Refer to the user guard for the interface you are using to learn if a PI ICU control is available for
that interface, and for instructions on how to use the interface's PI ICU control.
The example below shows the PI ICU control for the OPCInt interface. The controls developed
for other PI interfaces are similar in format.

Note:
For details on how to use interface-specific ICU controls, and on interface-specific
commands, refer to the user guide for the interface that you are configuring.

Additional parameters input

If no interface-specific PI ICU control is present, then a generic form is provided. An example of
this form is shown below.

24 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

The Additional parameters text box allows you to enter parameters that may be required by
the interface that is being configured.
Parameters should be entered into this text box in standard PI interface command line format.
For example:
/arg1=value1 /arg2 /arg3=value3

Service page
Use the settings in the Service Configuration pane, on the right side of the Service page, to
configure the interface to run as a service.

PI ICU uses two buffering services, which are selected from the Installed services list:

• PI Buffer Subsystem (PIBufss)

PI Buffer Subsystem is designed primarily to enhance the high availability (HA) features of
the PI Server. PI Buffer Subsystem buffers data only to one non-replicated PI Server or one
PI collective (with its various member nodes).

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 25

Using PI ICU

• API Buffer Server (bufserv)

If you send buffered data to PI Server version 3.4.370 or earlier, or if your interfaces run on
a non-Windows platform, you need to use bufserv, which has most of the same capabilities
of PIBufss.
Refer to the Installed services and Dependencies section for details on adding and configuring
services.

Topics in this section

• Service Configuration
• Installed services and Dependencies
• Startup Type
• Create / Remove
• Start, Stop, or Restart

Service Configuration
On the Services page, use settings in the Service Configuration pane to select and configure
installed services.

• Service name
The Service name field shows the name of the current interface service. This service name
is obtained from the interface executable.
• ID
The service ID field is enabled only if the interface service has not yet been created, and can
be used to select a new service ID for the selected interface. Changing the service ID causes
the PI ICU to rename the interface and to reload all interfaces. If a service ID is selected that
is already in use, the text box background turns yellow, and the service ID save button is
disabled. The service ID is usually a number, but can be any text up to 20 characters in
length.
• Save
The save button is enabled once a new valid service ID has been selected for an
interface whose service has not yet been created. Changing the service ID causes the PI ICU
to rename the interface and reload all interfaces.
• Display name
The Display name text box shows the current display name of the interface service. If there
is currently no service for the selected interface, the default display name is the service
name with a 'PI-' prefix. Users may specify a different display name, although it is
recommended to append the prefix 'PI-' to the name of the interface to indicate that the
service is part of your PI system.
• Log on as
There are two choices for the Log on as account. The default depends on the OS your system
runs and the version of UniInt that the interface uses.

26 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

If you are logging on to install an interface, an account with administrator-level privileges

must be used.
Note:
Currently, ICU always runs with elevated (admin) permissions.
For optimal security, run the interface service under an account with the least required
privileges, and limit the rights of the identity to access resources. Preferably, use a local non-
system or service account.
Several account types are available:

◦ Domain User Account

If the service must interact with network services, access domain resources like file
shares or if it uses linked server connections to other computers, then consider using a
minimally-privileged domain account. This account should be pre-created by domain
administration in your environment.

◦ Local User Account

If the computer is not part of a domain, a local user account without Windows
administrator permissions is recommended.

◦ Local System
This is a very high-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 NT
AUTHORITY\LOCALSYSTEM.

◦ Network Service
This is a built-in account that has more access to resources and objects than members of
the Users group. Services that run as the Network Service account access network
resources by using the credentials of the computer account. The actual name of the
account is NT AUTHORITY\NETWORKSERVICE.

◦ Virtual - Service Account

This is a built-in account introduced with Windows Server 2008 R2 and Windows 7. It
requires no password management and has the ability to access the network with a
computer identity in a domain environment. The actual name of the account is NT
SERVICE\servicename.
• UserName
If you select [Domain\]UserName for Log on as, then the Username, Password, and Confirm
Password text boxes appear. Enter the user name that you want the service to use. This
must be a valid Windows/domain account.
• Password / Confirm password
If you select [Domain\]UserName for Log on as and the specified user name requires a
password, then enter the password in this field. If no password is required, this field can
remain blank. The Confirm password text box is used to confirm the password typed into
the Password field.
• OMF health configuration

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 27

Using PI ICU

Available only with interfaces that support OMF Health Tags and after creating a service.
Once selected, a configuration file is created and the user specifies the OCS and/or PI Web
API endpoint(s). For further information on OMF Health Tags, refer to the "PI Universal
Interface (UniInt) Framework" in Live Library (https://livelibrary.osisoft.com) user guide.

Installed services and Dependencies

Installed services provides a list of the services currently installed on this machine. Services
upon which this interface is dependent should be moved into the Dependencies list using the
arrow button.

• Use the Add and Remove buttons to move services between the Installed services and
Dependencies lists.
The full name of the service selected in the Installed services list is displayed below the
Installed services field.
For example, if API Buffering is installed as a Windows service and is enabled, then bufserv
should be selected from the list at the right and added to the list on the left. If API Buffering
using PIBufss is installed as a Windows service and is enabled, then pibufss should be
selected from the list at the right and added to the list on the left. Only one API Buffering choice
should be selected, either bufserv or pibufss.
Often interface services also depend on a vendor program, such as the Fisher-Rosemount
chipservice. See the interface user guide for details on what dependencies a specific
interface may require.
There are three dependencies that the PI ICU provides assistance with: bufserv, pibufss, and
tcpip.

• PI ICU checks to see if bufserv or pibufss is installed as a Windows service and is

enabled. If bufserv or pibufss is installed as a service and is enabled, then PI ICU puts
bufserv or pibufss in the dependency list for the user before the service is created. If
bufserv or pibufss is installed as a service and is enabled and the service already exists
without a dependency on bufserv or pibufss, PI ICU prompts you to add bufserv or
pibufss as a dependency.
• By default, tcpip is always added to this list of dependencies by the ICU.
When the PI interface is started (as a service), Windows service control manager verifies that
the services listed in the dependency list are running (or an attempt is made to start them). If
the dependent service(s) cannot be started for any reason, then the PI interface service will not
run.
See the PI Log and operating system Event Logger for messages that might indicate the
cause for any service not running as expected.

Run PIBufss –Cfg

If you have selected buffering any of the three buffering types, you can run PIBufss –Cfg
from the command line to open a command window with configuration and status information
about the PI Buffer Subsystem.

28 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

Run Bufutil
If you are sending buffered data to PI Server version 3.4.370 or earlier, or if your interfaces run
on a non-Windows platform, you need to use API Buffer Server. You can access information
about the API Buffer Server running Bufutil from the command line.
When the command window displays, enter the number of the menu item you wish to look at
and hit return.

Startup Type
The service Startup Type indicates whether the interface service will start automatically or
must be started manually on restart. Typically, interface services are set to start automatically.

• If the Auto option is selected, the service is installed to start automatically when the
machine restarts.
• If the Manual option is selected, the interface service will not start on restart, but will
require someone to manually start the service.
• If the Disabled option is selected, the service will not start at all.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 29

Using PI ICU

Create / Remove
The Create button adds the displayed service with the specified Dependencies and with the
specified Startup Type.
The Remove button removes the displayed service. If the service is not currently installed, or if
the service is currently running, this button is disabled.

Start, Stop, or Restart

The Start , Stop , and Restart buttons on the toolbar are used to stop and start a
service.
If this interface service is running, the Stop and Restart buttons are enabled. If this service is
not running, the Start button is available. If the interface service is not currently installed,
these buttons remain disabled until the service is added.
The status of the interface service is indicated in the status bar at the bottom of the PI ICU
window.

UniInt page
General UniInt settings appear on the main UniInt page.

30 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

Topics in this section

• Performance and Behavior
• Data Handling
• Timestamps
• Outputs

Performance and Behavior

On the UniInt page, use the settings in the Performance and Behavior pane on the right to
configure interface performance and behavior options.

• Maximum stop time

When a service is stopped, the Service Control Manager spawns a new thread for the exit
handler. The exit handler sets the keep going flag for the interface to false and then
waits a maximum of stop time seconds for the main thread to reach a safe exit point before
the exit handler continues with its cleanup operations.
By default, stop time is 120 seconds. If stop time seconds are exceeded, the exit handler will
continue with its cleanup operations and then force the interface to exit.
The command-line equivalent for setting this option is /maxstoptime=#.
Click Reset to load the default Maximum stop time setting to the text box. Leave Maximum
stop time blank to equal the default setting of 120 seconds.
Entering a value of 0 causes the Maximum stop time to be exceeded, which forces the
interface to immediately exit instead of waiting for UniInt to perform cleanup operations.
• Startup delay
After UniInt prints out the Starting Interface startup message, UniInt waits for several
delay seconds before proceeding. If the startup delay parameter is specified without
specifying a delay time, then the default delay is 30 seconds.
If an interface has been compiled to use the PI SDK, a delay time is needed before the
interface connects to the PI SDK. If no delay is set, the interface may hang indefinitely when
trying to connect to the PI SDK after a reboot has occurred.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 31

Using PI ICU

The command-line equivalent for setting this option is /startup_delay=#.

Click Reset to load the default Startup Delay setting to the text box. Leave the Startup Delay
value blank to equal the default setting of 30 seconds. If Startup Delay time is set to 0, no
delay will occur.
• Point update interval
Use Point update interval to adjust the interval with which UniInt checks for point updates.
The default interval is 120 seconds, the minimum interval is 1 second, and the maximum
interval is 300 seconds. See the section on point updates in the "PI Universal Interface
(UniInt) Framework" in Live Library (https://livelibrary.osisoft.com) user guide for more
information.
The command line equivalent for setting this option is /updateinterval=#.
Click Reset to load the default point update interval setting to the field.
• Service events period
The Service events period controls the Service Events TimeOut parameter, specified in
milliseconds. Events are serviced (retrieved from the evmexceptions queue on PI Server) for
500 milliseconds, or until there are no more events in the queue. In either event, UniInt will
perform the other tasks it is responsible for, such as scanning for input data and checking
for PI point database changes.
If the interface is servicing many events, the time might not be sufficient and can be
adjusted with the Service events period start-up parameter. The minimum value is 0. If the
Service Events TimeOut parameter is set to 0, UniInt will service 36 events at a time
and then continue to perform its other tasks. The maximum value for x is 3000 (3 seconds).
The command line equivalent for setting this option is /SvcEventsTO=#.
Click Reset to load the default service events period setting.
• Percent Up
Use Percent Up to adjust the percentage of devices that have a good status, which will
determine the value for the devices status performance counter.
The command line equivalent for setting this option is /PercentUp=#, Default: 100.
Click Reset to load the default PercentUp setting.
• API Connection name
The API connection name string controls the name sent to PI Server in order to establish
the PI API trust. Prior to version 4.1 of UniInt, the interface name was used to establish the
PI API trust with the PI Server, which limited the PI Administrator’s options when setting up
security for an interface node. There was no way to configure different PI API trusts for
different instances of the interface running on the same computer. The PI Administrator is
now able to specify an application name for each instance by using the API connection name
parameter.
The maximum length of this parameter is determined by the version of the PI API that is
installed on the interface node. If the PI API version is prior to 1.6, the maximum length is
four characters. For PI API version 1.6 or greater, the maximum length is eight characters.
Check the PIClient.ini file for the following settings to use eight characters for the
appname parameter:

32 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

[PISERVER]
LONGPROCNAME=1

Note:
The PI API puts an E at the end of the app name when setting up the PI trust if you use
the four-character appname.
The command line equivalent for setting this option is /AppName=<Name>.
• Disable UniInt performance counters
UniInt-based interfaces expose performance counters that provide information about the
health of the interface. To disable this feature of UniInt interfaces, select the Disable UniInt
performance counters check box.
With UniInt 4.3.0.0 and later, UniInt will write this health information directly to points,
rather than to the Performance Counter objects. These new points are referred to as UniInt
Health Points.
The command line equivalent for setting this option is /disablecounters.
• Include Point Source in the header of log messages
When the Include Point Source in the header of log messages check box is selected, the
point source for the interface will be included in the header of the log messages sent to the
pipc.log file.
The command line equivalent for setting this option is /logps.
• Include UFO_ID in log messages
Use the Include UFO ID in log messages check box to tell UniInt to add the value of the /
UFO_ID to all the failover log messages.
The command-line equivalent for setting this option is /LogUFOID. Default: deselected for
interfaces built on UniInt 4.4.5.4 and earlier. This command line parameter only applies to
interfaces built on UniInt 4.4.5.4 and earlier. Later versions of UniInt always include the UFO
ID in failover log messages.
• Trim Digital State Names
Use the Trim Digital State Names check box to tell UniInt to trim leading spaces from digital
state tags.
The command-line equivalent for setting this option is /DigStateTrimLeft. Default:
unchecked for interfaces built against UniInt 4.6.0.x and later. This check box is invisible for
interfaces built against versions of UniInt earlier than 4.6.0.x.

Data Handling
From the UniInt page, use settings in the Data Handling pane to the right to queue data, select
bypass exceptions, and write status to tags on shutdown.

• Queue data (for active interfaces)

The Queue data setting tells the interface whether to queue up events before putting the
data into the PI System.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 33

Using PI ICU

The Queue option causes the interface to be more efficient if the interface is on a separate
computer from the PI Server. However, it will slightly delay the update of the snapshot value
if the data rate is low. The buffer size of the event queue for the interface is 128 events.
The command line equivalent for enabling this option is /q.
Starting with UniInt version 4.4.0.14, the Queue option is the default behavior for active
interfaces and cannot be selected. The choice is disabled.
• Bypass exception
Selecting the Bypass exception check box tells the interface to ignore the exception
specifications of the PI point and put all the input events into the PI Snapshot. By default,
this option is disabled in order to reduce data traffic.
The command-line equivalent for enabling this option is /sn.
• Write status to tags on shutdown
The stop status setting indicates whether a digital state value is written to a PI point when
the interface stops.
The list is populated with the states in the system digital state set from PI Server. If the
Write status to tags on shutdown check box is selected, but no system digital state is
entered into the text box, then the system digital state Intf Shut is written to all PI points
belonging to this interface when the interface stops.
If the check box is selected and a valid system digital state is entered, then that system
digital state is written to all PI points belonging to this interface when the interface stops. A
digital state named Intf Shut should be added to the system digital set and specified in
this text box.
The command line equivalent is /stopstat or /stopstat=x, where x is the system digital
state to be written to all PI points.

Timestamps
In some cases, the default method used to calculate the UTC offset between interface and PI
Server nodes does not work properly.
One example is the Foxboro interface on UNIX or Windows, where the time zone on the
interface node is always set to GMT standard time. During daylight savings time, when the wall
clock time is adjusted 1 hour forward, the net effect is that the UTC time on the interface node
jumps by 1 hour, independently of whether the PI SDK is enabled.
In this case, select Use alternate method of determining UTC seconds to determine the UTC
time of the PI Server node in the same manner that the Foxboro interface determines the UTC
time of the PI Server node. This feature can also be used when the PI SDK is not enabled. For
example, the default UTC offset calculation fails when the interface communicates to a PI
Server across a time zone that differs by a fraction of an hour, such as a 30-minute difference in
time zones between the interface node and the PI Server node. In this case, the 30-minute time
zone difference can be handled by enabling Use alternate method of determining UTC seconds
or Enable PI SDK.
The command-line equivalent for enabling this option is /foxutc.

34 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

Outputs
On the UniInt page, use settings in Outputs pane, to the right, to manage outputs.

• Disable all outputs from PI

If Disable all Outputs from PI is selected, outputs are entirely disabled for the interface
instance, and when the interface starts the following message is written to the message log:
/NOOUTPUTS flag detected. Outputs from PI disabled

The definition of NoOutputs is to disable output tag triggering. Output tags are not loaded,
and data is not written to the data source. The message above will display in the log file, and
the following message will be displayed for each tag configured as an output tag:
"Output tag" << tag->tag_name << "will not be loaded for read only interface"

Printing the UniInt Help produces this message:

nooutputs Disable output tag triggering

The command-line equivalent for enabling this option is /NoOutputs.

• Suppress initial outputs from PI
The Suppress initial outputs from PI checkbox applies only for interfaces that support
outputs. When the interface starts without this option, it determines the current snapshot
value of each output PI point, and then writes the values to corresponding points. If an
output point is edited while the interface is running, the interface writes the current PI
Snapshot value to the edited output point.
The Suppress initial outputs from PI option suppresses this behavior for interfaces that
support outputs. When selected, outputs are not written when the interface starts or when
output PI points are edited. Instead, they are written only when explicitly triggered.
The command-line equivalent for enabling this option is /sio.
• Use event timestamp instead of current timestamp for initial outputs
Some interfaces send the current value of the source PI point at start-up. By default, the
time stamp sent with the initial value is the current PI time.
This option instructs UniInt to send the time stamp of the source point's PI Snapshot value
to the interface-specific code that handles the actual output, instead of the current PI time
value.
The command-line equivalent for enabling this option is /IOSourceTime.
• Enable Output Point Security
Use the Enable Output Point Security to tell UniInt to use a whitelist file to specify a list of
tags and their attributes that can be used by the interface to output data to the interface's
data source.
The command-line equivalent for enabling this feature is /Whitelist=<UNCPath>. Default:
unchecked for interfaces built against UniInt 4.6.0.x and later. Once the check box is
selected, the user can then browse to the whitelist file. This file must already exist. This
check box is invisible for interfaces built against versions of UniInt earlier than 4.6.0.x.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 35

Using PI ICU

(UniInt) Failover
UniInt supports two types of failover.

Topics in this section

• Phase 1
• Phase 2
• Select the other interface of a failover pair

Phase 1
UniInt Failover Phase 1 is supported on a per-interface basis for interfaces built with UniInt
4.2.0.0 and later. See the individual interface user guide for the type of failover supported by
the interface.

If an interface does not support UniInt failover, the UniInt Failover page displays a message in
the status line at the bottom.

• Enable UniInt Failover

This page is enabled if the interface supports UniInt failover. Check Enable UniInt Failover to
enable failover for the selected interface.
• Phase 1 / Phase 2
If the interface supports both types of failover, you must choose which type to use. If the
interface supports only one type of failover, the other type is disabled. This must be the first
item selected when you configure failover.
• Failover ID# for this instance
In a failover interface installation, each copy of the interface has its own unique positive
integer identifier. This identifier is referred to as the failover ID and is specified with the
interface startup parameter /UFO_ID=n.
• Failover ID# of the other instance
This is the failover ID assigned to the other interface in the failover pair. By default, the pairs
are named 1 and 2.

36 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

See Select the other interface of a failover pair.

• Do Not Failover when both interfaces lose connection to PI
This option can only be used with interfaces built with UniInt 4.5.1.0 and later. It is used to
prevent the primary and the backup failover pair from both buffering data when they have
lost connection to PI Server. The equivalent startup parameter is /UFO_DNFBPI.
• Failover control tags are unsolicited (not scan based)
This option can only be used with unsolicited input interface failover control points. If the
interface supports scan-based input data and the interface failover points are defined as
scan-based input points, the update interval is then defined by the scan class to which the
control points belong.
The failover update interval determines the rate at which UniInt updates the heartbeat
points, how long it takes for the interface to failover, and how much overlapping data may
be sent to PI Server. The optional /UFO_Interval=# startup parameter specifies the failover
update interval for unsolicited failover control points.
Both interface copies participating in failover must use the same failover update interval.
The failover update interval, #, is specified in milliseconds with the default being 5000
milliseconds or 5 seconds. The minimum interval is 50 milliseconds.
The failover update interval can be changed in the Rate at which the heartbeat point is
updated/checked field.

Topics in this section

• UniInt failover points for Phase 1 failover
• Interface state points

UniInt failover points for Phase 1 failover

Each failover pair requires that six (6) failover control points and two (2) optional state points
be defined:

• UFO Active ID In
• UFO Active ID Out
• UFO Heartbeat 1 In
• UFO Heartbeat 1 Out
• UFO Heartbeat 2 In
• UFO Heartbeat 1 Out
• UFO Interface 1 State
• UFO Interface 2 State
The failover control points are interface-specific points, so the ICU is unable to aid in the
creation of these points. However, the ICU will display the failover control points if they are
found:

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 37

Using PI ICU

Active ID Point
The active ID point is located on the data source and identifies which copy of the interface is
primary. The primary interface active ID value is set by the /UFO_ID=n startup command-line
parameter for the primary interface copy. The value of n must be a positive integer. The value of
the active ID point is referred to as the ActiveID.

Heartbeat Point
The heartbeat point is used to indicate that the interface is functioning. This point is updated
once every failover update interval.
If the interface is connected to the PI Server, the value of the heartbeat point is incremented by
UniInt from 1 - 15 and then wraps around to a value of 1 again. If the connection to the PI
Server is lost, the value of the heartbeat point is incremented from 17 - 31 and then wraps
around to a value of 17 again.
Once the connection to the PI Server is restored, the heartbeat values will revert back to the 1 -
15 range. During a normal shutdown process, the heartbeat value is set to zero.

Interface state points

You can define an optional pair of digital interface state points to show the current failover
state of each interface in the failover pair. The failover control points require interface-specific
configuration as well as UniInt failover point-specific configuration.
Right-click to display a pop-up menu and choose from the following options:

• Export Point Configuration (.csv)

If the points exist in PI Server, the attributes that are exported to the .csv file are imported
from PI Server. If the points do not exist in PI Server, the attributes that are exported to
the .csv file are defined as they should be for UniInt failover to operate, but will require
that the interface-specific changes be made to them so that the interface can read from and
write to the points on the control system. For details on configuring your UniInt failover
control points for your interface, see the interface user guide.
• Export UFO_State Digital Set (.csv)
If the UFO_State digital set exists in PI Server, then the UFO_State digital set and states in
the .csv file are imported from PI Server. If the UFO_State digital set does not exist in PI
Server, the set and states in the .csv file are defined as UniInt requires.
• Create UFO_State Digital Set on Server <name>
If the UFO_State digital set does not exist in PI Server, this menu command is enabled and
can be used to create the UFO_State digital set on the PI Server to which this interface
writes.

38 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

Phase 2
UniInt Failover Phase 2 is supported on a per-interface basis for interfaces built with UniInt
4.4.0.0 and later. See the individual interface user guide for the type of failover supported by
the interface.

If an interface supports UniInt Failover Phase 2, the Synchronization File Path field is
populated and a UFO Type is selected from the drop down list.
If an interface supports both Phase 1 and Phase 2 UniInt Interface Level Failover, then two
option buttons will appear at the top. You select the type of failover to enable. If the interface
only supports Phase 2 this option button is automatically selected.

• Phase 1 / Phase 2
If the interface supports both types of failover, you must choose which type to use. If it only
supports one type, the other option is disabled. This must be the first item you select when
configuring failover.
• Failover ID# for this instance
In a failover interface installation, each copy of the interface has its own unique positive
integer identifier. This identifier is referred to as the failover ID and is specified with the
interface startup parameter /UFO_ID=n.
• Failover ID# of the other instance
This is the failover ID assigned to the other interface in the failover pair. By default, the pairs
are named 1 and 2.
See Select the other interface of a failover pair.
• Do Not Failover when both interfaces lose connection to PI
This option can only be used with interfaces built with UniInt 4.5.1.0 and later. It is used to
prevent the primary and the backup failover pair from both buffering data when they have
lost connection to PI Server. /UFO_DNFBPI is the equivalent startup parameter.
• Failover control tags are unsolicited (not scan based)
The failover update interval determines the rate at which UniInt updates the heartbeat
points, how long it takes for the interface to fail over, and how much overlapping data can be

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 39

Using PI ICU

sent to PI Server. The optional /UFO_Interval=# startup parameter specifies the failover
update interval for unsolicited failover control points.
Both interface copies participating in failover must use the same failover update interval.
The failover update interval, #, is specified in milliseconds with the default being 5000
milliseconds or 5 seconds. The minimum interval is 50 milliseconds.
You can change the failover update interval in the Rate at which the heartbeat point is
updated/checked field.
• UFO Type
UniInt Interface Level Failover Phase 2 can be configured for one of three types: HOT, WARM
or COLD. PI ICU will only allow you to choose types supported by the interface you are
configuring. The default type is COLD.
The command-line equivalent for this parameter is /UFO_Type=<type> where <type> is HOT,
WARM or COLD.
• Synchronization File Path
This identifier is referred to as the UniInt Failover synchronization path and filename. It is
specified with the interface startup parameter, /UFO_Sync=<path_filename>.
The default file name should be <exe_name>_<ps>_<id>.dat where <exe_name> is either
the name of the executable or the short interface name, <ps> is the point source (/ps) and
<id> is the interface id (/id).

UniInt failover points for Phase 2 failover

Each failover pair requires you to define three (3) failover control points and two (2) optional
state points:

• UFO2 Active ID
• UFO2 Heartbeat 1
• UFO2 Heartbeat 2
• UFO2 State 1
• UFO2 State 2
To create these PI points with the PI ICU, right-click any one of the points listed and choose
Create all points (UFO Phase 2). This command creates the three failover control points and the
two optional state points.

40 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

Select the other interface of a failover pair

Use this procedure to specify a different interface as the current interface of a failover pair

Procedure
1. On the UniInt Failover page in PI ICU, click the Browse button next to Failover ID# of the
other instance. A dialog box appears that displays the interfaces registered with the ICU for
this PI Server from all interface nodes.

The interface that represents the current interface is marked as (* Current Interface), and
cannot be selected.
2. Click the name of the other interface to select it, and click OK.
On the UniInt Failover page, the interface you selected appears in the Failover ID# for this
instance field.

(UniInt) Health Points

UniInt health points are supported by interfaces built with UniInt 4.3.0.0 and later.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 41

Using PI ICU

Right-click and choose a menu option to work with UniInt health points:
• Choose Create to create the selected point.
• Choose Create All to create all points marked Not Created or Deleted.
• Choose Delete to delete a selected point.
• Choose Delete All to delete all UniInt Health Points, except for the Interfaces Information
point.
• Choose Correct to correct a selected point's definition.
• Choose Correct All to correct all points marked Incorrect.
• Choose Rename to specify a new name for the selected point.
• Choose Refresh Snapshots to update the Snapshot column for all points.
• Choose Refresh Table to reload all health points in the table. This will refresh the Tagname
column if the interface was moved from one node to another.
If a point already exists, the status is marked Created and the Delete option is enabled. If a
point does not exist, the status is marked Not Created or Deleted and the Create option is
enabled.

• Status
The Status column in the Health Points table indicates whether the health point exists.

◦ Created
Indicates that the point does exist
◦ Not Created
Indicates that the point does not exist
◦ Deleted
Indicates that a point existed, but was just deleted by the user
◦ Incorrect
Indicates that the point exists in PI Server, but is not correctly defined
• Tagname

42 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

The Tagname column holds the name of the health point name.
• Type
The Type column holds the reserved keyword for the specified health point that is written
to the extended descriptor (ExDesc) of the health point.
• Scan Class #
Some health points belong to interface scan classes. For those that do, the Scan Class #
column indicates the scan class of the health point.
• UFO ID
If the interface is configured to use UniInt failover, the Location3 PI point attribute must
match the UniInt failover ID configured with the /UFO_ID parameter. For all of the PI points
that match the PointSource, id and optionally the /UFO_ID, the ExDesc attribute is
searched for a keyword. If the keyword is found, some other PI point attributes may be
verified before the point is loaded by the interface.
Note:
If the interface does not support UniInt failover or uses interface-level failover, the
Location3 attribute must match the UniInt health point ID configured with the /
UHT_ID parameter. This parameter must be configured in the interface-specific page
of the PI ICU control.
• PS
The PS field is the point source of the UniInt health point.
• ID
This field is the ID and typically contains the Location1 attribute (but sometimes another
attribute) for the selected UniInt health point.
• Point Type
This is the PointType attribute of the UniInt health point.
• Eng Units
This field is the engineering units of the UniInt health point.
• Snapshot
If the point exists in PI Server, then the Snapshot column holds the snapshot value for this
point.

UniInt health point types

There are several types of points that can be created to monitor the health of an interface. For
more details on each of these health points, see the UniInt Interface User Guide (https://
livelibrary.osisoft.com/LiveLibrary/web/ui.xql?
action=html&resource=publist_home.html&pub_category=PI-Universal-Interface-(UniInt)-
Framework).

Topics in this section

• General interface health points
• Scan class health points

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 43

Using PI ICU

General interface health points

The general interface health points pertain to the operation of the interface in general. A list of
scan class health points follows. The scan class health points require a valid scan class be
configured in Location4 of the PI point. The general interface health points do not consider
the Location4 value.

• Heartbeat [UI_HEARTBEAT]
The heartbeat point is the primary PI point used to determine if the interface is running. If
the value of the heartbeat point is updating, then the interface is running but not necessarily
connected to and collecting data from a data source. The default update interval is 1 second
if there are no scan classes defined for the interface.
If the interface has defined scan classes, the update interval will be set to the highest
frequency (lowest value) scan rate with the following limitations. If the scan rate is less than
1 second, the update interval will be set to 1 second. If the scan rate for the highest
frequency scan class is greater than 1 minute, the update interval will be set to 60 seconds.
The value written to the heartbeat point increments from a value starting at 1, increments
to a value of 15 and then restarts at 1.
The heartbeat point will stop updating if the interface is shut down or if the interface is in a
deadlock situation.
Note:
The interface health heartbeat point is completely separate from the UniInt failover
heartbeat point. An interface can have both an Interface health heartbeat point and a
UniInt failover heartbeat point loaded simultaneously.

• Device status [UI_DEVSTAT]

The device status point stores communication information about the interface and the data
source. The device status point is a string type PI point evaluated only while the heartbeat
point is updating. During normal shutdown of the interface, the string text of 4 | Intf
Shut will be written to this point.
Format: n | UniInt-provided string text | interface-specific text (when provided).
The n value in the text and the pipe separator are formatting devices that may be used to
quickly parse and analyze the value of the device status point.
The update values and meaning of this point are as follows.

◦ System Digital State “Good"

The interface is properly communicating with the data source and is able to read/write
data to the device as required. When in this state, the system digital state of Good will be
written to the device status point.
◦ 1 | Starting
The interface is starting.
◦ 2 | Connected / No Data

44 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

The interface is connected to the data source. While in this state, the interface is not
capable or reading or writing data to the data source. Optional text that can be provided
by the interface is appended to the UniInt-provided string value.
◦ 3 | n device(s) in error
The interface is unable to communicate with n device(s). Optional text that may be
provided by the interface is appended to the UniInt-provided string value.
◦ 4 | Intf Shutdown
The interface is shutting down.
◦ 5 | interface_specific_message
Text provided by the interface will be the only text following the 5 |.

• Scan class information [UI_SCINFO]

The scan class information point is a string point that contains the number of scan classes
used by the interface and their associated scan rates. The heartbeat scan rate is also
included in the string. The point is updated once at interface startup and at each
performance interval.
For example, the value for the scan class information point for an interface with three scan
classes of 5 seconds, 10 seconds and 60 seconds is 3 | 5 | 5 | 10 | 60, where the first
number is the number of scan classes and the second is the heartbeat update rate. Numbers
that follow depend on the rate and number of scan classes defined, with each rate written in
seconds.

• IO rate (events per second) [UI_IORATE]

Counts the number of all values (inputs, outputs, triggered inputs) being sent to PI Server
before exception processing occurs. This point will update based on the update rate of the
heartbeat point and may report zero for update intervals where no data was sent to PI
Server. If the value stops updating in PI Server, then this is an indication that the interface
has stopped collecting data.

• Message counter [UI_MSGCOUNT]

Tracks the number of messages the interface has logged to the pipc.log file since interface
start-up. The value of this point is used solely for ad-hoc queries and diagnostics. Generally,
a large number of messages indicate a problem that should be investigated.

• Output rate [UI_OUTPUTRATE]

Counts the number of output point events sent to PI Server before exception processing.
Output points update based on an event and cannot be scheduled for an update rate.
Therefore, the values of output points are updated at the same rate as the heartbeat point
and reset after the performance summary interval.
Note:
If no output points are defined, the digital state value of No Data will be written to the
point.

• Output bad value rate [UI_OUTPUTBVRATE]

Counts output point events sent to PI Server (before exception processing) with status other
than good. Output points update based on an event and cannot be scheduled for an update

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 45

Using PI ICU

rate. The value is updated at the same rate as the heartbeat point and is reset after the
performance summary interval.
Note:
If no output points are defined, the digital state value of No Data will be written to the
point.

• Interface point count [UI_POINTCOUNT]

Counts the 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.

• Trigger input rate [UI_TRIGGERRATE]

Counts number of triggered input point events that are sent to PI Server 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 will be updated at the same rate as the
heartbeat point and will reset after the performance summary interval.
Note:
If no trigger input points are defined, the digital state value of No Data will be written
to the point.

• Trigger input bad value rate [UI_TRIGGERBVRATE]

Counts triggered input point events sent to PI Server (before exception processing) with
status anything other than good. Triggered input points update based on an event and
cannot be scheduled for an update rate. The value is updated at the same rate as the
heartbeat point, and is reset after the performance summary interval.
Note:
If no trigger input points are defined, the digital state value of No Data will be written
to the point.

Scan class health points

Unless otherwise stated in the description of the point, a scan class health point will receive the
system digital state No Data if a scan class is defined and a scan class health point for the class
is loaded by the interface but there are no interface points loaded for the scan class. For points
configured to monitor a particular scan class, the PI point attribute Location4 must be set to a
valid scan class. Scan classes are defined with the /f startup parameter. See the list of startup
parameters for a description of the /f parameter.

• Scan class IO rate [UI_SCIORATE]

Shows the health of input points defined for a particular scan class. The point indicates the
number of events sent to PI Server before exception processing for the given scan class. As
long as the current value of the point is between zero and the scan class point count
inclusive, then the scan class update executed successfully.
If the scan class IO rate point stops updating in PI Server, an error has occurred and the
points for that scan class are no longer receiving new data. The value of this point is
updated after the completion of each scan.

46 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

• Scan class bad value rate [UI_SCBVRATE]

Calculates the number of values sent to PI Server (before exception processing from the
device) with a status other than good. This point can be defined for each scan class and is
used for all input points in that particular scan class.

• Scan class scan count [UI_SCSCANCOUNT]

Tracks the number of scans that were performed by the interface since the last reporting
period. The value of this point is incremented after the completion of every scan. The value
of the point is set to zero at the beginning of each reporting period.

• Scan class scans skipped [UI_SCSKIPPED]

Tracks the number of scans not performed before the scan time elapsed and the next
scheduled scan executed. The value represents the total number of scans skipped since the
last reporting period, and updates each time a scan is skipped. The value is reset to zero at
the beginning of each reporting period.

• Scan class point count [UI_SCPOINTCOUNT]

The number of points loaded by the interface for a particular scan class. The value of this
point is updated after every scan. If there are no points loaded by the interface for the
associated scan class, 0 will be written to the scan class point count point.

• Scan class scan time [UI_SCINSCANTIME]

The total amount of elapsed time in milliseconds to read data from the data source,
populate the input points, and then send the data to PI Server. The value for this point is
updated after each completed scan.

• Scan class input device scan time [UI_SCINDEVSCANTIME]

The time in milliseconds to read data from the data source and populate input points. The
scan class device scan time is a subset of the total scan class scan time and can be used to
determine the percentage of time spent communicating to the data source compared with
the percentage of time spent communicating with PI Server.
If the scan class skipped point value is increasing, the scan time points along with the device
scan time points can be used to help identify where the delay is occurring; for instance, the
data source communication, PI System communication, or elsewhere in the interface control
loop.

(UniInt) Performance Counter Points

The Performance Counter Points page allows you to create, delete, correct and rename PI
PerfMon interface performance counter points. Performance counters are available only in
UniInt-based interfaces built with UniInt 3.5.0.0 and later. This section is enabled only if the
selected interface meets the following four conditions:
• UniInt-based interface built with UniInt version 3.5 or later
• PI API 1.3.4 or later is present

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 47

Using PI ICU

• PI Performance Monitor interface is installed as a service and writing data to the same host
PI Server as the current interface
• The currently selected interface is installed as a service on this machine

Right-click and choose a menu command to work with performance counter points:
• Choose Create to create the selected point.
• Choose Create All to create all points marked Not Created or Deleted.
• Choose Delete to delete a selected point.
• Choose Delete All to delete all performance counter points listed.
• Choose Correct to correct a selected point's definition.
• Choose Correct All to correct all points marked Incorrect.
• Choose Rename to specify a new name for the selected point.
• Choose Refresh Snapshots to update the Snapshot column for all points.
• Choose Refresh Table to reload all performance points in the table. This will refresh the
Tagname column if the interface was moved from one node to another.
If a point already exists, the status is marked Created and the Delete option is enabled. If a
point does not exist, the status is marked Not Created or Deleted and the Create option is
enabled.
Performance counter points are created with the following PI point attribute values:
• Tag
Point name that appears in the list box
• Point Source
Point source for performance counter points is the point source used by the PI PerfMon
interface
• Exdesc
◦ If the performance counter is for the entire interface:

48 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

\\Local_node_name + \Interface_service_display_name + "(_Total)\ +

Performance_Counter
If the performance counter is for a particular scan class in the interface:
\\Local_node_name + \Interface_service_display_name + "(Scan Class #)\ +
Performance_Counter
• Status
The Status column in the Performance Counter Points table indicates whether the
performance counter point exists for the scan class in column 2.

◦ Created
Indicates that the point does exist
◦ Not Created
Indicates that the point does not exist
◦ Deleted
Indicates that a point existed, but was just deleted by the user
◦ Incorrect
Indicates that the point exists in PI, but is not correctly defined
• Tagname
The Tagname column holds the name of the performance counter point.
• PS
The PS field is the point source of the performance counter point.
• Snapshot
If the point exists in PI Server, then the Snapshot column holds the snapshot value for this
point.
• Performance Counter
The Performance Counter column indicates for which performance counter the
performance counter point collects data.

Performance counter point types

The following performance counter point types are available and appear in the Descriptor
point attribute.
Counter name Description
Device Actual Connections The actual number of data sources currently connected to
the interface instance and working properly. Only applies
to the instance (_Total).
Device Expected Connections Total number of devices that the interface is expected to
be communicating with at runtime. Only applies to the
instance (_Total)

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 49

Using PI ICU

Counter name Description

Device Scan Time (milliseconds) Time in milliseconds to call developer function and gather
data from a data source. Does not include the amount of
time to write the values to PI Server. There is one Device
Scan Time counter per scan class. Applies to scan classes
only. Does not apply 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 device, 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 Active ID tag's location5 attribute.
• 80
Percentage of devices connected below minimum
required
• 90
Starting interface, not connected to device
• 95
Communication error with device
• 99
Shutting down the interface
• 100
For internal use only
Only applies to the instance (_Total).

Failover Status Stores the failover state of the interface when configured
for UniInt level failover. Contains 0 if the interface is
primary, 1 if backup. 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)

50 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

Counter name Description

IO Rate The number of events per second received by the
interface. If this counter is viewed from the Windows
Note: performance monitor, increase the update time of the
This counter was removed from performance monitor to the minimum scan period for the
UniInt starting with version 4.5.0.x. interface. For example, if the minimum scanning period for
The counter has been reinstated for the interface is 5 seconds (/f=5), set the update rate of the
UniInt 4.6.0.x and later. 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 the PI Server. 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)
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 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).
Points Good Number of points that have sent a GOOD current value to
PI Server. If the last value sent to PI Server is a System
Digital State value or the last value sent to PI Server is
older than the Stale timeout, the point is not counted in
the Points Good count. The value of Points Good
equals the value of 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 Server. The total of Points
In Error, Points Good, and Points Stale equals
Point Count. Only applies to the instance (_Total).
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
Points Stale 30(min)
current value that is now stale, the Points Stale count
Points Stale 60(min) goes up and the Points Good count goes down. Only
good points go stale; points in error do not. Only applies to
Points Stale 240(min) the instance (_Total).
Scan Time (milliseconds) Time in milliseconds to call developer function and to
write values to PI Server. One "Scan Time" counter per
scan class. Does not apply to the instance. Applies to scan
classes only.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 51

Using PI ICU

Counter name Description

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 standard deviation of values above the currently
calculated mean. Only applies to instance (_Total).
Standard deviation below mean The standard deviation of values below the currently
calculated mean. Only applies to instance (_Total).

(UniInt) Performance Points

Performance points only pertain to UniInt-based interfaces. This section is disabled if the
interface being configured is not UniInt-based.

Performance points monitor the amount of time in seconds that it takes an interface to
complete a scan for a particular scan class. The closer the scan time is to 0 seconds, the better
the performance. The scan time is recorded to millisecond resolution.

52 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

The Performance Points page allows you to create, delete, correct and rename UniInt interface
performance points. Right-click and choose a menu command to work with performance
points:
• Choose Create to create the selected point.
• Choose Create All to create all points marked Not Created or Deleted.
• Choose Delete to delete a selected point.
• Choose Correct to correct a selected point's definition.
• Choose Correct All to correct all points marked Incorrect.
• Choose Rename to specify a new name for the selected point.
• Choose Refresh Snapshots to update the Snapshot column for all points.
• Choose Refresh Table to reload all performance points in the table. This will refresh the
Tagname column if the interface was moved from one node to another.
If a point already exists, the status is marked Created and the Delete option is enabled. If a
point does not exist, the status is marked Not Created or Deleted and the Create option is
enabled.
Performance points are created with the following PI point attribute values:
• Tag
Point name that appears in the list box
• PointSource
Point source for points for this interface, as specified on the first page
• Compressing
Off
• Excmax
0
• Descriptor
Interface name + Scan Class # Performance Point

• Status
The Status column in the Performance Points table indicates whether the performance point
exists for the scan class in column 2.

◦ Created
Indicates that the point does exist.
◦ Not Created
Indicates that the point does not exist.
◦ Deleted
Indicates that a point existed, but was just deleted by the user.
◦ Incorrect

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 53

Using PI ICU

Indicates that the point exists in PI, but is not correctly defined.
• Scan Class #
The Scan Class # column indicates the scan class to which the performance point in the
Tagname column belongs. There is one scan class in the Scan Class # column for each scan
class listed in the Scan Classes field on the General page.
• Tagname
The Tagname column holds the name of the performance point.
• PS
The PS field is the point source of the performance point.
• Location<ID>
The ID field is updated to show the attribute that the currently selected interface uses to
hold the ID. In this example, that is Location5. Many interfaces use Location1.
• Exdesc
The extended descriptor field holds the performance point definition, as used by UniInt.
• Snapshot
If the point exists in PI Server, then the Snapshot column holds the snapshot value for this
point.

(UniInt) PI SDK
The PI SDK cannot be used if the interface has been configured to use the disconnected startup
feature. If disconnected startup is configured, the PI SDK options will be disabled. If PI SDK is
required, the disconnected startup feature must be turned off. Most of the features that have
required PI SDK support in the past are supported by PI API 1.6.1.5 and greater.

PI SDK options
• Determine whether the interface may use PI SDK

54 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

UniInt-based interfaces have the option of disabling, enabling, or using the built-in default
set by the interface developer regarding whether to use PI SDK features. These settings can
be used to override the default setting specified by the interface developer.

◦ Disable PI SDK tells the interface not to use PI SDK features, regardless of the setting
specified by the interface developer. The command-line equivalent for setting this option
is /pisdk=0.
◦ Use the Interface's default setting tells the interface not to override the PI SDK on/off
setting specified by the interface developer.
◦ Enable PI SDK tells the interface to use PI SDK features, regardless of the setting
specified by the interface developer. The command-line equivalent for setting this option
is /pisdk=1.
• Override default SDK timeout
The timeout in seconds set here is used by PI SDK calls, overriding the data access timeout
listed in the Connection Settings window that can be viewed from the PI Connection
Manager. The PI Connection Manager should be used for adjusting the PI SDK data access
timeout. This parameter should only be specified if the interface uses the PI SDK and a data
access timeout that is different from the one set with the PI Connection Manager is required.
The command line equivalent for setting this option is /pisdktimeout=#.
Click Reset to load the default SDK timeout setting to the text box.
• Override default initial SDK connection timeout
The timeout in seconds used for opening the initial connection to the PI Server. All other PI
SDK calls use the timeout defined in the PI Connection Manager, or the Override default
SDK timeout setting, if configured.
The timeout set with this parameter overrides the connection timeout listed in the
connection settings dialog that can be viewed from the PI Connection Manager. The PI
Connection Manager should be used for adjusting the PI SDK connection timeout. This
parameter should only be specified if the interface uses the PI SDK and a connection
timeout that is different than the connection timeout set with the PI Connection Manager is
required.
The command-line equivalent for setting this option is /pisdkcontimeout=#.
Click Reset to load the default initial PI SDK connection timeout setting to the text box.

(UniInt) Disconnected Startup

These options set preferences for disconnected startup of a UniInt interface.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 55

Using PI ICU

• Enable disconnected startup (with point caching)

Interfaces built with UniInt version 4.3.0.0 or later include functionality to take advantage of
disconnected startup, which allows the interface to start from a local cache file with or
without a valid connection to the host PI Server. For more information on this feature, see
the PI Universal Interface (UniInt) Framework (https://livelibrary.osisoft.com/
LiveLibrary/web/ui.xql?action=html&resource=publist_home.html&pub_category=PI-
Universal-Interface-(UniInt)-Framework) user guide.
Check Enable disconnected startup (with point caching) to enable the disconnected startup
option. Disconnected startup cannot be used with the interface default setting, or if the PI
SDK is enabled and retrieves point attribute information from the PI Server. Enable
disconnected startup (with point caching) is disabled if either Enable PI SDK or Use the
Interface's default setting are activated.
The command line equivalent for enabling this option is /CacheMode.
• Cache synchronization period
The Cache synchronization period specifies the time slice in milliseconds (ms) allocated by
UniInt to synchronize the interface point cache file with the PI Server. By default, the
interface synchronizes if running in disconnected startup mode. UniInt allocates a
maximum number of ms for each pass through the control loop until the file is completely
synchronized.
Synchronization can be disabled by setting Cache synchronization period to 0. The default
synchronization period is 250 ms, the minimum period is 50 ms, and the maximum period
is 3000 ms (3s). Period values between 1 and 49 ms, and above 3000 ms are reset by the
interface to match the minimum and maximum period values.
Note:
Take care when adjusting this parameter. The synchronization period value must be
less than the smallest scan class period defined, or else input scans are missed while
the point cache file is synchronized.
The command-line equivalent for enabling this option is /CacheSynch=#.
• Cache Path
The Cache Path specifies a directory in which to create the point caching files. The directory
specified must already exist on the target machine. By default, the files are created in the
same directory as the interface executable.

56 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

The command-line equivalent for enabling this option is /CachePath=<path>.

• Cache Files
Two cache files are used by the interface. If either file is missing when the interface starts,
the interface will create the missing file. By default, cache files are created in the same
directory as the interface executable. If the path to the executable cannot be established, the
PI API provides a default location based on information available to the application.
The file name is constructed using the executable name, host name, point source, and ID
provided by the startup command file. The point cache file will have the form: filepath/
exename_hostname_pointsource_id_ptcache.dat
Likewise, the digital cache file will have the form
filepath/exename_hostname_pointsource_id_dgcache.dat
Note:
Part of creation includes storing interface and PI Server version information in each
file to be used for validation. The connection to the PI Server must be available during
the initial creation process for the disconnected startup operation to be configured
correctly.
The cache files store point configuration used during interface startup. After a successful
startup, the files are updated at regular intervals during data collection pause periods.
Normally, the files are updated automatically when any changes are made to the server. A
cache file can also be purged and re-created manually using two buttons:

◦ Rename Files
Renames the cache files by appending the current time in seconds after the filename.
◦ Delete Files
Deletes the cache files.
Cache files can only be renamed or deleted if not presently in use by the running interface.
The buttons are enabled only when the interface is not running.

(UniInt) Debug
The Debug page provides preferences and debugging tools.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 57

Using PI ICU

Topics in this section

• Debug Levels
• Debugging Options

Debug Levels
UniInt > Debug Levels specifies the level of debug messaging that the interface will log. Select
the desired combination of the UniInt debug messages by activating the appropriate check
boxes. All debugging messages can be turned on using the Maximum check box selection.
During normal operation the UniInt debug Level should be set to 0 (all check boxes unselected)
to prevent an excess of messages being written to the pipc.log file. The command-line
equivalent is /dbUniInt=x, where x is the level of debug messaging.
To clear all selected check boxes, click Reset.
The Point list creation debug level replaces the Point Additions debug level in interfaces built
with UniInt 3.5.4 and later and is disabled for interfaces built with UniInt versions 3.5.4 and
later.
The Whitelist and Standard Deviation debug levels are only visible when the interface is built
with UniInt 4.6.0.x and later.
The following debug levels have been removed from PI ICU as of UniInt version 3.5.0.0 or later:
• Sending data to PI
• Main control loop
• Services
• PI-SDK

Debugging Options
On the UniInt/Debug page, use the settings in the Debugging Options window to the right to
configure debugging options.

• Scan Performance Summary

When the percentage of scans that a UniInt-based interface performs on-time drops below
95%, UniInt will log performance summaries for each scan class. For information on
Performance summaries, see the "Performance points" topic in the "PI Universal Interface
(UniInt ) User Guide" in Live Library (https://livelibrary.osisoft.com).
The interface checks whether a performance summary should be logged every interval
hours. For example, if Scan Performance Summary is 0.025, the interface will log
performance summaries every 90 seconds if the percentage of on-time scans is below 95%.
The minimum time between summaries is 60 seconds. Setting Scan Performance Summary
to 0 disables summaries.
If the inputs for the interface are unsolicited, then Scan Performance Summary should be
set to 0 because performance summaries are meaningless for unsolicited input points. Click
Reset to load the default Scan Performance Summary (8) setting to the text box.

58 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

The command-line equivalent for setting this option is /perf or /perf=x.

• Log all values & timestamps for
If the Log all values & timestamps for check box is selected, the values and time stamps that
are received by the interface are also written to the log file.
Tracing can be enabled for a particular point by specifying a tag name or point ID in the text
box provided. The Tag Search button brings up the Tag Search dialog box. This option
should be used with caution because specifying this option could cause the log file to
become very large.

IO Rate page
The Input IORates Tag page allows users to create, edit and delete the I/O rate point.

An I/O rate point can be configured to receive 10-minute averages of the total number of
exceptions per minute that are sent to PI Server by the interface. An exception is a value that
has passed the exception specifications for a given PI point. Since 10-minute averages are
taken, the first average is not written to PI Server until 10 minutes after the interface has
started.
PI ICU currently allows for one I/O rate point to be configured for each copy of the interface
that is in use. Some interfaces allow for multiple points for I/O rates.

• Enable I/O Rates for this interface

This check box enables or disables I/O rates for the current interface. To disable I/O rates
for the selected interface, clear the check box. To enable I/O rates for the selected interface,
select the check box.
• Buttons are provided for tasks on the Input IORates Tag page:
◦ Click Create to create or edit the I/O rate point or to save the new event counter.
◦ Click Delete to delete a point.
◦ Click Reset to reset the I/O rate configuration as PI ICU suggests.
◦ Click Rename to specify a new name for the selected point.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 59

Using PI ICU

◦ Click Add to File to add the point to the IORates.dat file with the event counter listed in
the Event Counter column.
◦ Click Suggest a new, unused event counter.
◦ Click Tag Search to search the PI Server for a previously defined I/O rate point.
◦ Click Refresh Snapshots to update the snapshot.
• Event Counter
The event counter correlates a point specified in the IORates.dat file with this copy of the
interface. The command-line equivalent is /ec=x, where x is the same number that is
assigned to a point name in the IORates.dat file.
• Tagname
Tagname indicates the name of the I/O rate point.
• Tag Status
Tag Status indicates whether the I/O rate point exists in PI Server. The possible states are:

◦ Created
Indicates that the point exists.
◦ Not Created
Indicates that the point does not exist.
◦ Deleted
Indicates that a point existed, but was just deleted by the user.
◦ Unknown
Indicates that the PI ICU cannot access the PI Server.
• In File
In File indicates whether the I/O rate point listed in the Tagname field and the counter
indicated in the Event Counter field is in the IORates.dat file. The possible states are:

◦ Yes
This status indicates that the point name and event counter are in the IORates.dat file
◦ No
This status indicates that the point name and event counter are not in the IORates.dat
file
• Snapshot
If the I/O rate point exists, the snapshot value is displayed in the Snapshot column.

Interface Status page

The Interface Status page allows you to create, edit and delete the Interface Status Utility (ISU)
PI point.

60 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

Topics in this section

• Interface Status Utility Instance Information
• Interface Status Utility Tag Definition
• Watchdog point

Interface Status Utility Instance Information

The Interface Status Utility Instance Information section displays information about the
instance of the Interface Status Utility PI point that is configured for the PI Server to which the
current interface writes.

Interface Status Utility Tag Definition

The section at the top of this frame displays configuration and status errors regarding the ISU
instance and the ISU PI point definition.

The Tagname is the name of the point that belongs to the Interface Status Utility for each
interface. Right-click and choose a menu option to work with interface status points:

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 61

Using PI ICU

• Choose Create to create a point.

• Choose Delete to delete a selected point.
• Choose Correct to correct a selected point.
• Choose Rename to specify a new name for a point.
• Choose Suggest Tagname to add a point name with the default naming convention.
• Choose Tag Search to search the PI Server for a previously defined point.
• Choose Refresh Snapshots to update the snapshot value of the ISU point.

Watchdog point
The watchdog point is a PI point that belongs to the current interface. UniInt 4.3.0.0 and later
supports a heartbeat point, which is configured on the Health Points page. Although any point
may be used, OSIsoft recommends that you use this heartbeat point as a watchdog point.
• Click the Tag Search button to search for a point that belongs to the current interface as the
watchdog point.
The Tag Search dialog box displayed will be connected to the host PI Server. Search for the
interface point that will act as the watchdog point, select it, and click OK.
PI Interface Status monitors a watchdog point to determine the status of the monitored
interface. When choosing an interface watchdog point, consider the following:

• The scan rate of the interface watchdog point should reflect the scan rate of the majority of
the points in the monitored interface. For example, if the majority of the points in the
monitored interface have a scan rate of 10 seconds, the interface watchdog point should
have a scan rate of 10 seconds.
The scan rate of the interface watchdog point should be slightly more frequent than the
monitor frequency (Location4) of the PI Interface Status point. For example, if you want PI
Interface Status to monitor an interface every 1 minute, its interface watchdog point should
be updating around every 30 seconds.
• The monitor frequency of the PI Interface Status point should depend upon the scan rates of
the points in the monitored interface. Choose a monitor frequency that is a little less
frequent than the majority of the scan rates for the points in the monitored interface.
For example, an interface with most of its points scanning every 30 seconds could have a
monitor frequency of 1 minute. An interface with most of its points scanning every second
could have a monitor frequency of 10 seconds.
In addition to the scan frequency, the Location2 and Location3 attributes must also be set.

• Scan Frequency
The scan frequencies listed are the scan frequencies currently defined for the PI Interface
Status Utility (PIIntStatus) service. Select the appropriate scan frequency for the point
selected. If a different scan frequency is required, the PIIntStatus configuration needs to be
modified and a new scan class needs to be added before proceeding. Scan classes are
configured on the General page of PI ICU.
• Location2

62 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Using PI ICU

Location2 defines ISU behavior when data becomes stale. This parameter has three possible
values:

◦ 0
No digital state written to input points.
◦ 1
Write ISU Saw No Data.
◦ 2
Write ISU Saw No Data, but ignore interface shutdown state.
• Location3
This selection is only enabled if Location2 is not equal to 0. It defines ISU behavior when
communication resumes. This parameter has three possible values:

◦ 0
Remove the system digital state written by ISU.
◦ 1
Do not remove the system digital state written by ISU.
◦ 2
Remove the system digital state written by ISU if an archive value is present.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 63

Using PI ICU

64 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

PI ICU menu options
The following sections describe menu options in the PI ICU.

Topics in this section

• Interface menu
• Tools menu

Interface menu
The Interface menu includes the following options:

Topics in this section

• New Windows Interface Instance from EXE
• New Windows Interface Instance from BAT file
• New UNIX/VMS Interface Instance
• Delete Interface Instance
• Unregister Interface from ICU
• SDK Connections
• Connect to Primary
• Save
• View Command Line
• Start Interactively
• Exit

New Windows Interface Instance from EXE

The New Windows Interface Instance from EXE option opens a Configure a New Interface
dialog box that will start the process of configuring a new instance of a PI interface. Completion
of this operation results in a registered interface within PI ICU, including a .bat file.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 65

PI ICU menu options

• Browse to interface executable (required)

Use the Browse button to select the desired interface executable file.
• Host PI Data server/collective (required)
The host PI Server for the new interface. This field depends on the Loading Option selected
by the user via Tools > Options. If PI ICU is set to load interfaces only from the default PI
Server, then this field is not editable, otherwise a drop-down list is provided of all 3.3 or
later PI Servers.
• Path
The path to the selected PI Server, or currently connected member of a collective. In order to
create a new interface instance, a primary server in a collective must be available.
• Interface name as displayed in the ICU (optional)
The interface name appears in the PI ICU dialog box Interface drop-down list. If no name is
specified, then the name is <interface_exe><service_id>
(<interface_exe><service_id>) -> <hostname>. For example, the first instance of a
PItoPI interface using 1 as the service ID would be:
PItoPI1 (PItoPI1) -> HostName
• Point Source
The point source assigned to all points belonging to the new interface. The point source can
be added or edited later from the General page of the main PI ICU dialog box.
• Interface ID #

66 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

The ID number used to distinguish points belonging to this interface instance from other
points with the same Point Source. Not all interfaces require an ID number.
• Service ID
Select a service ID to use with this instance of the interface. The service ID is usually a
number but can be any text up to 20 characters in length.
• Add
When the required interface information is entered in the dialog box, click Add to create the
new interface instance. The new interface is registered and added to the drop-down list in
the main PI ICU window.
• Clear Fields
Clears all the fields on the Configure a New Interface dialog box.
• Cancel
Click to exit without creating a new interface.
• Status Bar
The status bar at the bottom of the dialog box indicates the current step in the registration
process.

New Windows Interface Instance from BAT file

The New Windows Interface Instance from BAT file option is used to register existing
interfaces with PI ICU. A Browse dialog box displays all .bat files in the currently selected
directory. Browse to a previously configured interface startup batch file (.bat file), from which
an existing interface can be loaded into the PI ICU.
Note:
Once an interface has been loaded by the PI ICU, the .bat file should not be modified
manually.
If the host parameter specified in the .bat file is not in the current list of servers, a dialog box
allows another host to either be selected or added:

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 67

PI ICU menu options

Add or select the correct server. Click Cancel to cancel the import.

New UNIX/VMS Interface Instance

Some UNIX- and VMS-based interfaces are configured using a digital state set, stored in the
interface's host PI Server, to store the command-line parameters. This option allows users to
configure one of these interfaces to be managed by the PI ICU.

68 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

Step 1: Define Interface

• Host PI System
Indicates the host PI System for the new interface. This field depends on the Loading Option
selected by the user via Tools > Options. If PI ICU is set to load interfaces only from the
default PI Server, then this field is not editable, otherwise a drop-down is provided of all 3.3
or later PI Servers.
• Interface node
The interface node is the name of the UNIX or VMS node on which the interface runs.
• Interface ID
The ID number that is used to distinguish PI points belonging to this interface from other
points with the same point source. Not all interfaces require an ID number.
• Interface type
Indicates to PI ICU the type of the interface being configured.

Step 2: Configuration Digital State Set

• Digital Set
The digital state set that this interface will use to hold its configuration parameters.
• States
As other fields are filled in, the Digital Set name is validated. If the set exists, the states are
retrieved and displayed in the States section.
• Configure
The Configure button is enabled when all the required information is provided. The new
interface is registered and added to the drop-down list in the main PI ICU window. A PI
point by the same name as the digital set is created when the digital state set is created.
An error is returned if a point by the same name as the digital set already exists.
• Cancel
Click to exit without creating a new interface.

Delete Interface Instance

Delete Interface Instance removes the selected interface from PI ICU, and removes the
interface service (stopping the interface service if it is running), and prompts the user whether
to delete the interface .bat file.

Unregister Interface from ICU

Unregister Interface from ICU allows the user to remove the selected interface from PI ICU
without removing the interface service or any of the interface files.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 69

PI ICU menu options

SDK Connections
Displays the PI Connection Manager.

Connect to Primary
Use Connect to Primary to attempt to reconnect to the primary server of a PI collective. Under
normal operation, the ICU will detect that the primary server is available again and
automatically connect to the primary server. However, under certain circumstances, the PI ICU
may not be aware that the primary server is available again, and this menu option tells the PI
ICU to attempt to connect to the primary. This option is enabled only when connected to a
secondary server in a PI collective.

Save
Click Save to save the current interface configuration. Changes made to the interface
configuration are only loaded when the interface starts.
A dialog box reminds the user to stop and restart the interface service after interface changes
are saved.

View Command Line

This is used to display the last saved command-line parameters in a dialog box.

Start Interactively
Start Interactively starts the currently selected interface interactively using the associated
batch (.bat) file. Typically an interface is executed interactively during the startup of a new
interface implementation and run later as a service for normal operation.

70 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

Note:
The interface cannot be started interactively if it is already running as a service.

Exit
Closes the PI Interface Configuration Utility. A message box will appear to allow you to save any
unsaved changes to the currently selected interface.

Tools menu
This section describes the menu items available from the Tools menu.

Topics in this section

• Log Files
• Buffering
• Buffering Manager
• Run apisnap
• Diagnostics
• PointSources
• Date/Time Properties
• View Digital State Sets
• Interface Tag Creation Utility
• Interface Communication Test Utility
• Interface Specific Configuration
• Options

Log Files
Choose Log Files to view existing PIPC log files and modify the settings for the PIPC Log Server
(PILogSrv) service. The PILogSrv service controls the size that PIPC logs become prior to
archiving and the number of old pipc.log files that are retained. You can also start and stop
the PILogSrv process from this window.

Topics in this section

• PIPC.Log Files page
• PIPC Log Server page

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 71

PI ICU menu options

PIPC.Log Files page

Log files found under the PIHOME\dat directory are listed in this Window. Double-click the log
file name to view the log files.
The Continuous PIPC.log button opens a window into which all messages written to PIPC.Log
are displayed as they are written to the file.
The Continuous PI Msg Log button opens a window into which all messages written to the PI
message log are displayed as they are written to the file.

PIPC Log Server page

• Service

To apply changes made to the settings, click OK, then stop and restart the PILogSrv service.
• Startup Type

72 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

The Startup Type indicates whether the PILogSrv service is setup to start automatically on
reboot or manually on reboot, or is disabled.

◦ If the Auto option is selected, the service is installed to start automatically when the
machine restarts.
◦ If the Manual option is selected, the PILogSrv service will not start on reboot, but will
require someone to manually start the service.
◦ If the Disabled option is selected, the service will not start at all.
Generally, the PILogSrv service is set to start automatically.
• Settings
There are two configurable parameters used by the PILogSrv service that manage the
number of files to be stored on the system and the size at which the log files are to roll over.
To change the maximum number of pipc*.log files to be kept on the local system, specify a
value in the text box provided. The default is 20, and the range is 1 to 9,999.
The Use Default button populates the Maximum log files text box with the default value.
To change the size at which the pipc.log files are renamed and a new pipc.log file
created, specify a value in kilobytes in the field provided. The default is 256 KB. The range is
1 KB to 4 MB

Buffering
Buffering of data occurs on the interface nodes while PI Data Archive is unavailable. Buffering
processes include PI Buffer Subsystem (pibufss) and API Buffer Server (bufserv).

• API Buffer Server (bufserv)

The API Buffer Server buffers data from PI interface nodes and client nodes in case the PI
Data Archive server receiving the data becomes unavailable for any reason. This might occur
during a network outage, maintenance, or backup.

• PI Buffer Subsystem (PIBufss)

PIBufss is designed to enhance the high availability (HA) features of PI Server. PIBufss has
most of the same capabilities of bufserv, with a few differences. PI Buffer Subsystem buffers
data only to one non-replicated PI Server or one PI collective (with its various member
nodes). PI Buffer Subsystem works with PI Server 3.4.375 or later.
Note:
Only one Buffer Type can be enabled on a machine at any time. If the Buffering dialog
detects that both types are enabled, an error message is displayed.

Overview of buffering versions

Select Tools > Buffering to configure buffering.
• If your 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

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 73

PI ICU menu options

information about the status of buffering on this computer. See Buffering Manager for more
information.
• If your 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.
Note:
PI Buffer Subsystem supports only one non-replicated server, or one or more member
nodes of a collective. PI ICU verifies if buffering is enabled to more than one server or
collective and prompts you for confirmation if there is a conflict. You may need to
make configuration changes to support the subsystem.
• If your 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.
• Regardless of your current buffering configuration, if PI Buffer Subsystem 4.3 is not yet
installed, the Buffering Manager window opens.
Use Buffering Manager to configure, monitor, and troubleshoot buffering using PI Buffer
Subsystem. PI Buffer Subsystem is recommended for applications connecting to PI Server
3.4.375 or later. Older versions of PI Server require API Buffer Server, as do some sites with
custom solutions (for example, high availability solutions). See Buffering Manager for more
information.

Buffering types
Buffering queues data from PI interface nodes and client nodes in case the PI Data Archive
server receiving the data becomes unavailable for any reason. For example, this might occur
during a network outage, maintenance, or backup.
When the connection with the PI Data Archive server or collective is restored, the buffering
service sends all the stored data from the buffer to the PI Data Archive server in the order it
was received.
There are three types of data that can be buffered:

• PI API
Data from PI API applications is usually buffered using PI Buffer Subsystem. If you send
buffered data to PI Server version 3.4.370 or earlier, or if your interfaces run on a non-
Windows platform, you need to use API Buffer Server.

• PI SDK
Data from PI SDK applications can be buffered only using PI Buffer Subsystem. PI SDK
buffering was introduced with PI SDK 2010 R2.
Note:
BuffSS is recommended for PI SDK version 1.4.7.602 and PI API version 1.6.9

74 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

• AF SDK
Data from AF SDK applications can be buffered only using PI Buffer Subsystem. AF SDK
buffering was introduced with PI Asset Framework 2014 (2.6).
Note:
Only one Buffer Type can be enabled on a machine at any time. If the Buffering dialog
detects that more than one type is enabled, an error message is displayed.

Buffering Manager
Buffering configuration is done using PI Buffering Manager. In the Tools menu of PI ICU,
Buffering Manager is an application that runs outside of PI ICU and has its own Help system.
Select Help/View Help from the Buffering Manager main page to find information about how
the application works.

Buffering status information is provided on the main Buffering Manager page.

There are two important links provided:
• PI messages: Click to read information on reported buffering issues.
• Settings: Click to open the Buffering Settings window, where you can select buffering
options.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 75

PI ICU menu options

A list of Logical Servers is provided. Double-click on a listed server to see buffering setting
options for that particular server.

Buffering Manager menu options

The Buffering Manager provides three menus:

• File
Options include:
◦ Add Data server...
◦ Export buffering report...
◦ Exit

• View
Options include:
◦ PI messages...
◦ Point errors...
◦ Buffering upgrade report...
◦ Settings

• Help
Options include:
◦ View Help
◦ Give us feedback
◦ About

Add Data server

To add a data server, perform the following:

Procedure
1. In the Buffering Manager, click File and select Add Data server...
2. Configure buffering for: Select from the drop-down menu the data source for which you are
configuring buffering.
3. Server: Either click the browse link to navigate to the PI Data Archive server to which data is
to be sent, or enter the name of the server in the Server field.
4. Click Next.
5. PI Data Archive Security: Select either PI Mapping (recommended) or PI trust
authentication method.
6. Fill in the PI Identity field using one of the following methods:

76 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

◦ Enter a new name and click Create.

◦ Click the browse link to open the Select PI Identify, PI Group, or PI User window. Select PI
Identity from the Type drop-down menu, then click OK.
7. If you selected PI trust authentication, the Client name and IP address fields display in
the IP Information section of the window. Those fields populate automatically with the
corresponding Computer Name and IP Address of the machine on which the ICU is running.
Select both the Client name and IP address.
8. Click Next.
Note:
An alert displays if the configuration of the added data server conflicts with security
standards: The PI Buffer Subsystem has not passed all security tests. Would you like to
continue anyway? Click Yes to continue, No to cancel the operation. A Verification
window displays to confirm that the server was added successfully.
9. Click Exit Add Service Wizard.

Export buffering report...

Use the Export buffering report... function to generate a text file detailing buffering
events over a specified period of time.

Procedure
1. In the Buffering Manager window, click File and select Export buffering report... The
Save As window opens.
2. Name the text file.
3. Navigate to the location where you want to save the file.
4. Click Save.

View: PI messages
The PI messages option in the View menu opens the PI messages window, where you can
select and view exported PI messages.

Procedure
1. Select PI messages from the View menu. The PI messages window displays (similar to the
following sample screenshot).

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 77

PI ICU menu options

2. Double-click on a listed message to open the Message Details window, which includes
the following tabs:
◦ Details
Information provided in the Details tab includes:
▪ Time: The date and time when the message was generated.
▪ Severity: PI messages are classified as Informational or Debug.
▪ ID: The ID property of a LogMessage is a Read-Only long integer that identifies the
message template under which the message was inserted.
▪ Program: The name of the program (ProgramName) that originated the message.
▪ Source 1: General information.
▪ Source 2: More specific information.
◦ Identity
Information on the Originating User and Process User is provided in the Identify tab.
Host, OS User, and PI User details can be found in PI-SDK Help under the
SendLogMessage method page.
▪ Host: The Originating User Host is the Process User Host.
▪ OS User: The Originating OS User is the Process OS User.
▪ PI User: The Originating PI User is the Process PI User.
▪ ID: The ID under the Process User is the Process ID from which the message
originated.
3. Click Close to return to the Message Details window.

View: Point errors...

Buffered points in error are listed.

Buffering upgrade report...

The Buffering upgrade report lists updates to the buffering function, and details issues in the
upgrade process.

78 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

View: Settings
Select the Settings... option to display the Buffering Settings window. See Settings for
details on buffer configuration.

PI messages
Clicking on the PI messages link in the Buffering Manager window opens the PI Messages
window. There you can view buffering messages generated from the selections you make using
the Select buffering messages options, including:

• Time
Time frame for the buffering messages displayed.

• Program
Name of the program associated with buffering messages displayed.

• Message
Text message detailing an event.

• Category
The category message parameter.

• Originating Host
The fully qualified domain name (FQDN) of the machine sending a message as determined
by an application.

• Originating OS User
The user sending a message as determined by an application.

• Originating PI User
The authenticated PI user sending a message as determined by an application.

• Priority
An integer between 1 and 10 (1 being the most important - "highest priority") that is used
by an application to define the order in which a message condition should be handled
relative to other messages.

• Process Host
Domain name of the machine sending a message.

• Process OS User
The authenticated user of the application which is logging the message.

• Process PI User
The authenticated PI user associated with a message being logged.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 79

PI ICU menu options
• Process ID
ID of the process that sent the message.

• ID
The number or text identifying this instance of the interface.

• Source 1
Log messages sent with the PI-SDK automatically send the application name with each
message. When a programmer wishes to further identify the cause or contributors to a
condition a message is reporting, these extra source fields can be supplied with a string
value. By convention the sources are ordered going from general to specific, Source1 being
the most general, Source2 to being the next level of specificity and so on.

• Source 2
See above.
For detailed descriptions of these fields, refer to the "SendLogMessage" method in the PI SDK
user guide (https://techsupport.osisoft.com/Documentation/PI-SDK/PI_SDK_Interfaces/PI-
SDK_Objects/MessageLog2/IDH_MLG_SENDLOGMSG.htm).

Select buffering messages options

Clicking on the PI messages link in the Buffering Manager window opens the PI Messages
window. There you can view buffering messages based on your selection of parameter options.

Procedure
1. From the Time Range drop-down menu, select the range of options provided for defining
the time frame for the buffering messages you wish to display. The options are:
◦ Last hour
◦ Last 12 hours
◦ Last day
◦ Last week
◦ Last month
◦ Custom range... (See Identify a custom range.)
2. Use the drop-down menu to set the Severity level of the buffering messages that you wish to
display. The options are:
◦ Critical: The message is of a critical nature and requires attention.
◦ Error: The message represents an error condition that should be understood and
possibly corrected
◦ Warning: The message is merely a warning that something out of the ordinary has
occurred.
◦ Informational: The message is purely for informational purposes.
◦ Debug: The message is for troubleshooting purposes only.
3. Optionally, enter in the Program field the name of a program for which you want to see
buffering messages.

80 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

4. Optionally, enter in the Message field any message that you would like to associate with the
buffering messages to be displayed.
5. Identify the Source from which you wish to display buffering messages.
◦ Source 1: See the description in PI messages.
◦ Source 2: See Source 1.
6. Click Close.

Identify a custom range

Selecting the Custom range... option opens the Custom Time Range window. There you can
set custom parameters for the time frame from which buffering messages may be displayed.

Procedure
1. In the Custom Time Range window, identify the format for the range of time you are
specifying by selecting either Relative time or Specific time.
◦ Relative time: Relative time specifies the number of minutes, hours, days, weeks or
years ago that a buffering message was published. Example:
From: *(Now)
To: *-15m(15 minutes before Now)

The order in which you enter the Relative time makes no difference.
◦ Specific time: Specific time specifies the exact date and time that a message was
published. Example:
From: 2/13/2020 3:15:21 PM
To: 2/14/2020 8:25:36 AM

<example From, example To>

2. In the From field, enter the earliest time from which you want to see buffering messages.
Use the appropriate format for the Relative time or Specific time you are specifying.
3. In the To field, enter the latest time from which you want to see buffering messages. Use the
appropriate time format.
4. Click OK.

Settings
Clicking the Settings link in the Buffering Manager window opens the Buffering Settings
window, which consists of left and right panes.
In the left pane is a directory of installed interfaces, which are listed below a Global settings
configuration file.

Configure Global settings

There are three buffering settings that are applied to all interfaces using PI System. Buffering is
either globally enabled or disabled, a location is specified for the temporary storage of buffered
files should a server temporarily fail, and Authentication options for accessing servers are
specified. Use the following procedure to configure those Global settings:

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 81

PI ICU menu options

Procedure
1. Buffering: Enable buffering by selecting On from the drop-down menu.
2. Queue path: Set the path to where buffered files will be temporarily stored should a server
become unavailable. A typical path would be C:\ProgramData\OSIsoft\Buffering.
Click Browse... to navigate to the file location where you wish to temporarily store buffered
files.
3. Authentication options: From the drop-down menu, select Windows
authentication, PI trust, or Any. Any is the default option.
4. Determine if you want to configure advanced global settings:
◦ Click Show advanced global configuration to display advanced configuration options.
Refer to Configure Advanced Global settings.
5. Click Save.

Configure Advanced Global settings

In the Global settings pane, you have the option to click the Show advanced global
configuration link to display a list of configuration options to be applied to all interfaces in the
system. Use the following procedure to set these options:

Procedure
1. Buffering: Select On from the drop-down menu to enable buffering.
2. PI API buffering: Select "On" from the drop-down menu to allow PI API connections, or
"Off". Observe the caution note in PI ICU. If you change the PI API buffering value, you
must restart the PI Buffer Subsystem and its dependent interfaces.
3. AF SDK buffering: Select Buffer if possible (default), Always Buffer, or Do
Not Buffer from the drop-down menu. Note that AF SDK applications can override this
setting for some or all features.
4. PI SDK buffering: Select "On" from the drop-down menu to enable PI SDK connections,
or "Off".
5. Queue capacity sample period: In the second(s) field, enter a value (for example, 600)
to determine the buffer queue capacity. This is based on the average bytes written to buffer
queue(s) over this sampling period. This may be adjusted to ensure that data is written to
the buffering queue at a consistent rate.
6. Queue capacity warning trigger: In the hour(s) field, enter the value. A warning is
then sent when the remaining queue capacity reaches this number of hours.
7. Queue capacity error trigger: In the hour(s) field, enter the value. An error is shown
when the remaining queue capacity reaches this number of hours.
8. Registration check interval: In the second(s) field, enter the value specifying the
intervals at which PI Buffer Subsystem checks the PI SDK and AF SDK client connections. It
drops any that are no longer active, or no longer associated with buffered data.
9. Flush cycle: In the second(s) field, enter the value specifying the intervals at which
cached snapshot records are written to disc and the cache is cleared.

82 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

10. Pause rate: In the millisecond(s) field, enter the value specifying the rate at which data is
processed to the API buffer.
11. Click Save.

Configure default server configuration

Default server settings apply to all servers that do not have explicit values.
Note:
If you have completed the procedure detailed in Configure Global settings, the Queue
path and Authentication options will already be set. You may want to skip this
procedure and click the Show advanced default server configuration link to display
advanced options, then refer to Set advanced default server configuration.

Procedure
1. Queue path: Set the location where buffered files will be temporarily stored should a
server become unavailable. A typical path would be C:\ProgramData\OSIsoft
\Buffering. Click Browse... to navigate to the file location where you wish to temporarily
store buffered files.
2. Authentication options: From the drop-down menu, select Windows
authentication, PI trust, or Any. Any is the default option.
3. Determine if you want to set additional server configuration options.
◦ If you do, click the Show advanced default server configuration link to display advanced
options. Refer to Set advanced default server configuration.
4. Click Save.

Set advanced default server configuration

These settings apply to all servers in PI Buffer Subsystem.
Note:
The Queue path, Authentication options, and Buffering will have already been
set if you completed the Configure Global settings and Configure default server
configuration procedures.

Procedure
1. Queue path: Set the location where buffered files will be temporarily stored should a
server become unavailable. A typical path would be C:\ProgramData\OSIsoft
\Buffering. Click Browse... to navigate to the file location where you wish to temporarily
store buffered files.
2. Authentication options: From the drop-down menu, select Windows
authentication, PI trust, or Any. Any is the default option.
3. Buffering: Enable buffering by selecting On from the Buffering drop-down menu.
4. Autotune: Enable the autotune function, which optimizes the rate at which PI Buffer
Subsystem writes data to the server, by selecting On (default) from the drop-down menu, or
disable that automatic function by selecting Off.
5. Queue size: Set the default size of each queue file by entering a value into the MB field (for
example, 32).

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 83

PI ICU menu options

6. Connection timeout: Set the amount of time PI Buffer Subsystem waits for a connection
to a server before assuming connection cannot be made and logging an error. Enter a value
in the second(s) field (for example, 60).
7. Post timeout: Set the amount of time PI Buffer Subsystem waits to send data to a server
before logging an error and retrying. Enter a value in the second(s) field (for example, 60).
8. Registration timeout: Set the amount of time you will wait when registering with the PI
Snapshot Subsystem before logging an error and retrying. Enter a value in the second(s)
field (for example, 120).
9. Maximum post rate: Set the events per second rate at which data will be sent to a server
by entering a value in the events / second field. <We show 0 in the example. Is that the
normal default? What would that mean?>
10. Retry rate: Set the time you will wait to attempt to reconnect to a server by entering a
value in the second(s) field (for example 120).
11. Send rate: Set the intervals at which data will be sent to a server by entering a value in the
millisecond(s) field (for example, 100).
12. Autotune events trigger: Set the number of events that will allowed to accumulate in
the buffer queue before autotune is triggered by entering a value in the event(s) field (for
example, 12000000).
13. Autotune queue trigger: Set the period of time after which optimization if the number
of events in a queue is less than or equal to the Autotune events trigger value, set in
step 12, by entering a value in the second(s) field (for example, 600).
14. Post rate smooth time: Set the number of events PI Buffer Subsystem sends to each
server each second by entering a value in the second(s) field (for example, 20).
15. Click Save.

Configure individual servers

While you may use global configuration settings to set the buffering specifics for all servers in a
PI Buffer Subsystem, you also have the option of configuring individual servers.

Procedure
1. In the Buffering Settings window, click on the name of server you wish to configure from
among those listed in the left pane.
2. Complete the steps for configuring a server as detailed in Configure Advanced Global
settings.

Run apisnap
This option runs apisnap.exe in a command window. If an interface is selected, apisnap will
run pointing to the PI Server that interface writes to. If an interface is not selected, apisnap
runs pointing to the default PI Server. This option is disabled if apisnap.exe is not found on
the machine.

84 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

Diagnostics
Diagnostics creates a diagnostic file (text format) with information about the current interface
and the API node. The user is prompted for the location of the file. This diagnostics file is useful
for OSIsoft technical support for debug purposes and may be requested during a support call.
The following information is written to this file:
• Current command line
• Interface type
• Full name
• Interface binary (including path)
• Interface description
• Interface node name
• Interface version
• UniInt-based flag
• UniInt version
• Current installation path
• PI Host Server information
• Local PI SDK version
• Local PI API version
• Interface Service information
• Local IORates.dat file
• Contents of the local IORates.dat file
• Performance points information
• Performance counter points (Performance Monitor points) information
• UniInt health points
• PILogSrv Service information
• Local pipc.ini file
• Bufserv Service information
• PIBufss Service information
• SDK Buffering status
• Local Buffering settings from PIClient.ini
• Entire PIClient.ini file
• Local PILogin.ini settings

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 85

PI ICU menu options

PointSources
The PI Point Sources dialog box displays the list of known PI 3.3 servers from which the user
may select. All interfaces registered on that PI Server are listed, along with their Point Source.
This dialog box is sizeable, so the user may resize the dialog box to see all the entries.

Date/Time Properties
Displays the Windows Date/Time Properties dialog box that can be used to configure the
computer's time and time zone.

View Digital State Sets

If an interface is selected, the digital state sets on the PI Server the interface writes to are
displayed. If an interface is not selected, the digital state sets on the default PI Server are
displayed. This dialog box is sizeable, so the user may resize the dialog box to see all the
entries.

86 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

Interface Tag Creation Utility

If PI ICU is able to locate a utility to create PI points (available depending on the Type of
interface selected), this menu option is enabled. Click the menu option to run the PI point
creation utility. For details on the point creation utility for individual interfaces, refer to the
interface user guide.

Interface Communication Test Utility

If PI ICU is able to locate a utility to test a connection to the data source (available depending
on the Type of interface selected), this menu option is enabled. Click to run the communication
test utility. For details on each individual interface's communication test utility, refer to the
interface user guide.

Interface Specific Configuration

If PI ICU is able to locate a utility to configure the interface (available depending on the Type of
interface selected), this menu option is enabled. Click to run the configuration utility provided
by the interface. For details on each individual interface's configuration utility, refer to the
interface user guide.

Options
The Options dialog box has seven choices. Four apply generally to all interfaces:
• Loading
• Naming Conventions
• Debug
• Reserved Point Sources
Three apply only to the currently selected interface and are inactive until an interface is
selected:
• Service
• .Bat Files
• Warnings

Loading
Use Loading options to tell PI ICU whether to load interfaces that talk only to the default PI
Server, to check all servers in the known servers table for interfaces that run on the current API
node, or to check just the selected servers for interfaces that run on this API node. The default
behavior is to display interfaces that run on the local node that talk to all known PI Servers.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 87

PI ICU menu options

Naming Conventions
Use the Interface Point Naming Conventions page to establish conventions used when creating
points with the ICU. Any naming mask must have either the Interface Service Name ([if
service]) or the Interface Service Display Name ([if display name]) in it, since these settings are
applied across all interfaces, and names must have something unique in them.

The Interface Point Naming Convention is used by ICU to name the various points that it
creates, if these points do not already exist:

• I/O rate points

• Interface Status Utility points
• UniInt performance points and UniInt health points
• Performance counter points

88 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

The default behavior is to use the machine name followed by the interface service name. The
arrow button can be used to display the naming options for each type of point:

• IORates Tag Prefix

• Machine Name
• Interface Service Name
• Interface Service Display Name
• Period
• Space
• Underscore

Debug
Debug messages can be logged to the pipc.log file during PI ICU startup, during import of
configuration (.bat) files and during creation of new interface instances. These messages help
determine where PI ICU is spending its time when startup or import is slow.

Reserved Point Sources

The Reserved Point Sources page displays the default reserved point sources on each PI server/
collective from which the PI ICU is configured to load interfaces. The reserved point source can
be changed for any of the listed types.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 89

PI ICU menu options

To change the point source, select the row representing the point source to be modified and
right-click to display the Change Reserved Point Source dialog box.

Type in the new point source, and click OK to accept the changes, or Cancel to cancel. Once all
changes have been made, click Apply or OK to save changes, or Cancel to exit.

Service

• Service Status
The service update rate determines how often PI ICU checks for the current status of the
interface service. This is necessary only if users manage interface services outside of PI ICU
while PI ICU is running. Setting this value to 0 seconds turns this feature off.
• Interface Service Display Name Naming Convention

90 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 PI ICU menu options

The Interface Service Display Name Naming Convention is used by PI ICU to generate the
service display name, if the service does not already exist. The default behavior is to use the
service name.

.Bat Files

• Command Line History

The default behavior is to save old command lines to the interface .BAT file with a REM
statement before them. This leaves an audit trail within the batch file. To turn off this
feature and have only the current command line saved, check this box.
• Command Line Parameter Delimiter
The default command line parameter is the slash "/", but users may override this default.
Some interfaces, such as the PI SNMP interface, presently require a dash "-" for its
command-line parameter delimiter.
If the Command Line Parameter Delimiter section is disabled, then the selected interface
requires a particular command-line delimiter, and this option is not available to the user to
configure.

Warnings
PI ICU may display two warning messages, which the user can suppress so that they are not
displayed again by clicking a corresponding check box:
• Suppress the warning dialog box that appears when interface settings are saved for an
interface with a running service.
• Suppress the warning dialog box that appears when the user moves to the ICU control page
with unsaved changes on another page in the PI ICU.
The warnings can be reactivated by clearing the respective check boxes.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 91

PI ICU menu options

92 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

PI ICU installation
The PI Interface Configuration Utility uses the Microsoft Windows Installer technology for
installation.

Topics in this section

• Installation of PI ICU
• Uninstall PI ICU

Installation of PI ICU
To install, run the PIICUSetup_#.#.#.#.exe file. The PI ICU files are installed to an ICU
directory below PIHOME, as specified in the %windir%\pipc.ini file. Support files are
installed in the Library directory below PIHOME.
The following table shows the files that are installed by the PI ICU setup program and the
directories in which they are located.
PIHOME\
Help\
PIInterfaceConfigurationUtility.chm
Library\
PISpt.dll
OSIsoft.PISpt.dll
PIGenericNames.dll
OSIsoft.PIGenericNames.dll

ICU\
PI-ICU.exe
PIICURegisterControl.dll
Watchlog.exe

The following table describes each file that the PI ICU setup program installs.
File Description
PI-ICU.exe PI Interface Configuration Utility executable file
PISpt.dll Library used by PI ICU
OSIsoft.PISpt.dll PISpt.dll Interop DLL
PIGenericNames.dll Library that manages interface generic names
OSIsoft.PIGenericNames.dll PIGenericNames.dll Interop DLL
PIICURegisterControl.dll Library used by PI ICU to register interfaces with
PI ICU
WatchLog.exe Log Files program to watch the PIPC.log file
continuously from within PI ICU.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 93

PI ICU installation

File Description
PIInterfaceConfigurationUtility.chm PI ICU Help file

A PI Interface Configuration Utility shortcut is added to Start > Program Files > PI System.

Uninstall PI ICU
Two methods can be used to uninstall PI ICU:

• Run Add or Remove Programs (Start Menu > Settings > Control Panel > Add or Remove
Programs) and remove the PI Interface Configuration Utility.
• Extract the files from PIICUSetup_#.#.#.#.exe to a temporary directory with WinZip,
and enter the following at the command prompt:
setup.exe /u
Note:
The PI Software Development Kit (PI SDK) might have been installed using PI ICU, or
might have been installed prior to the PI ICU installation. Remove it at your discretion
using Add or Remove Programs.

94 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

Migrate an interface to another PI Server
Interfaces are often configured by writing to a test PI Server, and then migrating the interfaces
to a production PI Server when they are ready. The PI ICU stores interface information (startup
command line, for example) in the PI Module Database of the PI Server to which an interface
writes.
Follow this procedure to move an interface configuration from one PI Server to another.

Procedure
1. On the General page of the PI ICU, change the Server/Collective to which the interface
belongs.

If the Server/Collective drop-down list is disabled, or if the name of the new PI Server is not
in the Server/Collective drop-down list, continue through the following steps.

a. Click Interface > SDKConnections to display the Connections window and verify that the
new PI Server exists.
b. Click Tools > Options > Loading and verify that the ICU Loading settings are correct.
You can load interfaces from all known PI Servers or from a selected list of PI Servers.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 95

Migrate an interface to another PI Server

If you load from a selected list of PI Servers, make sure that both the old server and the
new server are selected. Click OK to save and close the window. The PI ICU will reload
interfaces.
c. Load the interface you want to redirect from one PI Server to another, and select the new
PI Server in the Host drop-down list.
The interface configuration is moved to the new PI Server. This means that the interface
entry in the old PI Server's PI Module Database is removed and is added to the new PI
Server's PI Module Database.
During the configuration move, the PI ICU status bar at the bottom of the PI ICU displays
progress, and when complete, the status bar reads Ready.

96 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

Error and informational messages for PI ICU
The following table describes common troubleshooting issues for PI ICU.
Remember to click Apply (or Interface > Save) to apply changes whenever you edit PI ICU
settings. An asterisk (*) appears in the PI ICU caption if there are any pending changes that
have not been applied.
Message / issue Comment
The required support DLL This error indicates that the PIPC\Library
PIGenericNames.dll is not \PIGenericNames.dll file is not installed, missing or
present or not registered unregistered. To register the file, open a command window,
change directories to the PIPC\Library directory, and type in the
following command:
Regsvr32 PIGenericNames.dll

The required support DLL This error indicates that the PIPC\Library\PISpt.dll file is not
PISpt.dll is not present or installed, missing or unregistered. To register the file, open a
not registered command window, change directories to the PIPC\Library
directory, and type in the following command:
Regsvr32 PISpt.dll

The PI SDK version is older PI ICU requires PI SDK 1.3.4 or later on the machine on which PI
than the required version ICU is to run. If the PI SDK version is older, it must be upgraded.
Error 713 attempting to This error indicates that the PI ICU control has been registered on
load the ICU Control this machine, but the physical file has been moved or deleted. To
fix this problem, re-install the PI ICU control for the interface type.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 97

Error and informational messages for PI ICU

Message / issue Comment

Error 450 attempting to This error indicates that the PI ICU control is registered and
load the ICU Control physically present on this machine, but it does not provide all the
methods that PI ICU requires. Generally, this indicates that the PI
ICU control version is inappropriate for the version of the PI ICU
running on this machine. The PI ICU control user manual should
indicate which version(s) of the PI ICU control are compatible with
which versions of PI ICU.
Error -2147220478 This error indicates that either the local or remote PI Network
Manager process is not running, and the PI SDK is not able to
communicate to the local or remote PI servers.
Start the PI Network Manager service on the appropriate node and
then restart PI ICU.

No interfaces showing up in This indicates that the PI ICU program could not access the
Interface drop down list for a Module Database on the particular node in question. If the drop
particular node down Interface list is empty or missing interface instances for a
particular node, make sure that a connection can be made to that
Host's PI Server. If it can and you still are missing interface
instances, make sure you have read/write access to the Module
Database from the node where the PI ICU is being run. If not,
correct the connection problems and rerun PI ICU to load the
interface instances.
PI ICU control is on machine, but This usually indicates that the PI ICU control has not been
does not show up in PI ICU registered. The setup kit for a particular PI ICU control will
attempt to register the control. To manually register a control,
open a command window, change directories to the PIPC\ICU
\<ICU Control Directory> directory, and type in the following
command:
Regsvr32 <ICU Control dll or ocx Name>
Critical Error -11425 from PIBufss This error indicates that a buffered server was selected that
PIBufss cannot communicate with and therefore PIBufss cannot
buffer data to it.
Make sure the server selected can be reached and that the PI
mappings or PI trust definitions are correct.

98 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

 Error and informational messages for PI ICU

Message / issue Comment

Critical Error -11452 and -11402 This error indicates that PIBufss cannot create the shared memory
from PIBufss buffers or disk buffer file.
The most likely reason for this error is because some application
was running and buffering, but it was not shut down before
PIBufss was restarted. It is holding open the shared memory
buffers.
To fix this problem, PIBufss and the application must be stopped
and then PIBufss is restarted followed by this application.

PI Interface Configuration Utility (ICU) 1.5.1 User Guide 99

Error and informational messages for PI ICU

100 PI Interface Configuration Utility (ICU) 1.5.1 User Guide

Technical support and other resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or through the
OSIsoft Customer Portal Contact Us page (https://customers.osisoft.com/s/contactus). The
Contact Us page 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 Interface Configuration Utility (ICU) 1.5.1 User Guide 101

Technical support and other resources

102 PI Interface Configuration Utility (ICU) 1.5.1 User Guide