PI Interface Configuration Utility User Guide

PI Interface Configuration Utility User Guide
PI Interface Configuration Utility
User Guide
Version 1.4.15
OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com
PI Interface Configuration Utility User Guide
© 1992-2014 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, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset
Framework (PI AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI
BatchView, PI Coresight, PI Data Services, PI Event Frames, PI Manual Logger, PI ProfileView, PI
WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all
trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their
respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft,
LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR
52.227, as applicable. OSIsoft, LLC.
Version: 1.4.15
Published: July 2014
Contents
Introduction to PI Interface Configuration Utility (PI ICU)..............................................1
Version requirements...................................................................................................................................... 1
How PI ICU works............................................................................................................................................ 2
Multiple interface instances.........................................................................................................................2
Interface-specific PI ICU controls................................................................................................................. 2
Required PI Server configuration................................................................................................................. 3
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
Start buffering (PI Buffer Subsystem version 4.3 or later)............................................................................... 11
Start buffering (PI Buffer Subsystem versions earlier than 4.3)...................................................................... 12
PIPC log files and service................................................................................................................................13
Manage interfaces......................................................................................................................................... 14
Remove interfaces.........................................................................................................................................14
Remove an interface from PI ICU............................................................................................................... 14
Remove and uninstall an interface from PI ICU.......................................................................................... 14
Backup and restore........................................................................................................................................ 15
Using the 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 PI ICU controls............................................................................................................... 24
Additional parameters input...................................................................................................................... 24
Service page.................................................................................................................................................. 25
Service Configuration................................................................................................................................ 25
Installed services and Dependencies.......................................................................................................... 27
Startup Type............................................................................................................................................. 28
Create / Remove........................................................................................................................................ 28
Start, Stop, or Restart................................................................................................................................28
UniInt page................................................................................................................................................... 28
Performance and Behavior........................................................................................................................ 29
Data Handling............................................................................................................................................31
Timestamps...............................................................................................................................................32
Outputs..................................................................................................................................................... 32
(UniInt) Failover............................................................................................................................................. 33
Phase 1...................................................................................................................................................... 33
Phase 2...................................................................................................................................................... 36
Select the other interface of a failover pair.................................................................................................38
PI Interface Configuration Utility User Guide
iii
Contents
(UniInt) Health Points.................................................................................................................................... 39
UniInt health point types........................................................................................................................... 41
(UniInt) Performance Counter Points.............................................................................................................45
Performance counter point types.............................................................................................................. 46
(UniInt) Performance Points.......................................................................................................................... 49
(UniInt) PI SDK...............................................................................................................................................51
PI SDK options...........................................................................................................................................52
(UniInt) Disconnected Startup....................................................................................................................... 52
(UniInt) Debug...............................................................................................................................................54
Debug Levels............................................................................................................................................. 55
Debugging Options................................................................................................................................... 55
IO Rate page................................................................................................................................................. 56
Interface Status page.....................................................................................................................................57
Interface Status Utility Instance Information............................................................................................. 58
Interface Status Utility Tag Definition........................................................................................................58
Watchdog point.........................................................................................................................................59
PI ICU menu options.................................................................................................61
Interface menu.............................................................................................................................................. 61
New Windows Interface Instance from EXE............................................................................................... 61
New Windows Interface Instance from BAT file......................................................................................... 63
New UNIX/VMS Interface Instance............................................................................................................ 64
Delete Interface Instance........................................................................................................................... 65
Unregister Interface from ICU....................................................................................................................65
SDK Connections.......................................................................................................................................66
Connect to Primary................................................................................................................................... 66
Save.......................................................................................................................................................... 66
View Command Line................................................................................................................................. 66
Start Interactively......................................................................................................................................66
Exit............................................................................................................................................................ 67
Tools menu....................................................................................................................................................67
Log Files.................................................................................................................................................... 67
Buffering................................................................................................................................................... 69
Run apisnap............................................................................................................................................... 83
Diagnostics................................................................................................................................................84
PointSources............................................................................................................................................. 85
Date/Time Properties................................................................................................................................ 85
View Digital State Sets.............................................................................................................................. 85
Interface Tag Creation Utility.................................................................................................................... 86
Interface Communication Test Utility........................................................................................................ 86
Interface Specific Configuration................................................................................................................ 86
Options..................................................................................................................................................... 86
PI ICU installation.................................................................................................... 93
Installation of PI ICU...................................................................................................................................... 93
Uninstallation of PI ICU................................................................................................................................. 94
Migrate an interface to another PI Server...................................................................95
Error and informational messages for PI ICU.............................................................. 97
Technical support and other resources..................................................................... 101
iv
PI Interface Configuration Utility 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 ICU uses the PI Module Database on the PI Server as a repository for interface startup
parameters. PI 3.3.361.43 or greater on Microsoft Windows Server 2003, Vista, Server
2008, 2008 R2, Win7, Server 2012, or Win8 is required for the host PI Server.
• PI ICU 1.4.1.0 and later requires PI SDK 1.3.4 or greater be installed on the machine where
PI ICU runs. PI ICU can only configure interfaces that run on the same node. PI SDK is
installed as part of the PI ICU setup.
• PI ICU 1.4.1.0 or later is not supported on Windows NT 4.0 because PI SDK 1.3.4 is not
supported on Windows NT 4.0. PI ICU versions prior to 1.4.1.0 are supported on Windows
NT 4.0.
PI Interface Configuration Utility User Guide
1
Introduction to PI Interface Configuration Utility (PI ICU)
How PI ICU works
PI ICU works as the PI System Manager's main access point for managing and configuring PI
Interfaces. PI ICU eliminates 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.
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.
For example, if the interface executable is named modbus.exe, subsequent instances created
by ICU are named
• modbus1
• modbus2
• modbus3
• (and so forth)
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 standards.
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.
2
PI Interface Configuration Utility User Guide
Introduction to PI Interface Configuration Utility (PI ICU)
You can visit the OSIsoft Tech Support PI Interfaces Search page (https://
techsupport.osisoft.com/Products/PI-Interfaces/Search) 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 manual.
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
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.
PI Interface Configuration Utility User Guide
3
Introduction to PI Interface Configuration Utility (PI ICU)
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 manual 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
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 manual 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
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.
4
PI Interface Configuration Utility User Guide
Introduction to PI Interface Configuration Utility (PI ICU)
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,
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.
PI Interface Configuration Utility User Guide
5
Introduction to PI Interface Configuration Utility (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:
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
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).
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 User Guide
Getting started with PI ICU
PI ICU provides a multi-screen dialog box 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.
Topics in this section
• Register an interface instance with PI ICU
• Start the PI interface service
• Start buffering (PI Buffer Subsystem version 4.3 or later)
• Start buffering (PI Buffer Subsystem versions earlier than 4.3)
• PIPC log files and service
• Manage interfaces
• Remove interfaces
• Backup and restore
PI Interface Configuration Utility User Guide
7
Getting started with PI ICU
Register an interface instance with PI ICU
Interfaces must be registered in order to work with PI ICU. To register an interface, you can
configure it using an interface .exe file or import an existing interface from a .bat file to
create a new 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.
You can find this guide in the folder where the interface is installed.
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
button on the toolbar.
click the Create new interface instance
The Configure a New Interface dialog box opens.
8
PI Interface Configuration Utility 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 dialog box.
10. Select the proper Type for the interface on the main ICU screen, if it is not selected
automatically.
11. Complete configuration of the interface by filling in the desired fields on the PI ICU page
dialog boxes.
For details on which attributes are required by a particular interface, see the appropriate PI
Interface manual.
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 User Guide
9
Getting started with PI ICU
◦ Point Builder tool in PI System Management Tools (PI SMT)
◦ PI Tag Configurator add-in to Microsoft Excel (included with PI SMT)
◦ PI Builder add-in to Excel (included with PI Server 2014)
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
manual.
4. For details on which attributes are required by a particular interface, see the appropriate PI
Interface manual.
5. Use PI ICU and an application to create PI points (PI Point Builder application, PI Tag
Configuration Excel add-in) to configure and run the PI interface.
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.
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.
10
PI Interface Configuration Utility User Guide
Getting started with PI ICU
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.
• Use the Tools > > Services page to 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.
Start buffering (PI Buffer Subsystem version 4.3 or later)
PI ICU assists in configuring and running buffering.
Before you start
These instructions apply only if PI Buffer Subsystem version 4.3 or later is installed on this
computer. If version 3.4.380.79 or earlier is installed, refer to Start buffering (PI Buffer
Subsystem versions earlier than 4.3).
PI Interface Configuration Utility User Guide
11
Getting started with PI ICU
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. Click Tools > Buffering.
Note:
If buffering with PI Buffer Subsystem is already configured, the Buffering Manager
window opens. You will see a dashboard with information about the status of
buffering on this computer. In this case, you can skip the remaining steps.
2. When prompted, confirm that you want to configure PI Buffer Subsystem. If you currently
use API Buffer Server (bufserv), you may need to confirm more than one prompt.
The Buffering Manager window opens. This indicates one of two things:
◦ This computer is configured to buffer data using API Buffer Server (bufserv). In this case,
before you continue, review the information in the Buffering Manager window regarding
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 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.
12
PI Interface Configuration Utility User Guide
Getting started with PI ICU
Procedure
1. Choose Tools > Buffering to display the Buffering dialog box.
2. Use the Choose Buffer Type page to select a buffering option:
◦ Disable buffering
◦ Enable PI Buffer Subsystem
◦ Enable API Buffer Server
3. Use the Buffering Settings page to change default settings.
4. Use the Buffered Servers page to select one or more servers that you want to buffer data to.
5. Use the API Buffer Server Service and PI Buffer Subsystem pages to configure and control the
buffering services.
PIPC log files and service
You can use PI ICU to view current PI Log files and modify the settings for the PIPC Log Server
(PILogSrv) process.
• Choose Tools > Log Files to access the Log Files dialog box.
The PIPC.Log Files page lists all of the logs currently existing under the PIHOME\dat\
directory by name:
• 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 reopened in PI ICU.
• Click Continuous PIPC.Log to open a command prompt window and view messages as they
are written to a selected log file.
• Click Continuous PI Msg Log to open a command window and view the PI message log
messages as they are written.
Use the PIPC Log Server page in PI ICU to start and stop the PIPC Log Server service.
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.
PI Interface Configuration Utility User Guide
13
Getting started with PI ICU
Manage interfaces
All PI interfaces registered on the current API 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.
• Switch between registered interfaces by selecting any interface from the Interface dropdown 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
MDB, or you can completely uninstall the interface.
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 PI 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.
14
PI Interface Configuration Utility User Guide
Getting started with PI ICU
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 User Guide
15
Getting started with PI ICU
16
PI Interface Configuration Utility User Guide
Using the PI ICU
PI ICU provides a multi-screen dialog box 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 User Guide
17
Using the 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 User Guide
Using the 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 the main PI ICU
dialog box or any of its pages. 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 User Guide
19
Using the PI ICU
General options
• Point Source(s)
The Point Source(s) 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 casesensitive 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
manual.
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 Sources field is
button is enabled when a unique PointSource definition is entered. If
enabled. The Add
button are
the interface does not support multiple point sources, the list box and Add
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 that is specified 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
.
• 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 User Guide
Using the 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. See the Performance Point page section for more information on skipped or
missed scans.
To remove a scan class, select it and click the X button to the right of the Scan Classes menu.
The command-line equivalent is /f=x, where x is the scan period with the optional phase.
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
• 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,
PI Interface Configuration Utility User Guide
21
Using the PI ICU
click 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.
Note:
The PI ICU can communicate to PI Servers version 3.3 and later, and must run on a
computer where PI SDK 1.3.4 or later is installed. PI SDK 1.3.4 and later is not
supported on Windows NT 4.0, so PI ICU 1.4.1.0 and later is not supported on
Windows NT 4.0. PI ICU versions prior to 1.4.1.0 are supported on Windows NT 4.0.
• 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.
22
PI Interface Configuration Utility User Guide
Using the PI ICU
When using API Buffer Server, Buffering Status is Misconfigured if the server specified
under PI Host Information is not configured to receive buffered data.
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 PI ICU controls
• Additional parameters input
PI Interface Configuration Utility User Guide
23
Using the PI ICU
Interface-specific PI ICU controls
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 your interface manual to learn if a PI ICU control is available for your interface and to
learn how to use that PI ICU control.
The example below shows the PI ICU control for the Citect interface. The controls developed
for other PI interfaces are similar in format.
Note:
For details on how to use an interface-specific ICU controls or enter specific interface
commands, please see the manual for the interface being configured.
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 User Guide
Using the 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
The Service Configuration page allows the user to configure the interface to run as a service as
well as to start and stop the interface.
Topics in this section
• Service Configuration
• Installed services and Dependencies
• Startup Type
• Create / Remove
• Start, Stop, or Restart
Service Configuration
• 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.
PI Interface Configuration Utility User Guide
25
Using the PI ICU
• 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.
To install an interface, an account with administrator-level privileges must be used. For
optimal security, run the interface service under an account with the minimal number of
privileges required, 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
26
PI Interface Configuration Utility User Guide
Using the PI ICU
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.
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 list box.
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 manual 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 the user whether 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), the services listed in the dependency list are
verified as 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 server not running as expected.
PI Interface Configuration Utility User Guide
27
Using the PI ICU
Startup Type
The service Startup Type indicates whether the interface service will start automatically or
need to 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.
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 lower portion of the PI ICU dialog box.
UniInt page
General UniInt settings appear on the main UniInt page.
28
PI Interface Configuration Utility User Guide
Using the PI ICU
Topics in this section
• Performance and Behavior
• Data Handling
• Timestamps
• Outputs
Performance and Behavior
• Maximum stop time
When an NT 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. Enter a 0 value to exceed max
stop time. The exit handler will continue with cleanup operations and then force the
interface to exit.
• 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.
The command-line equivalent for setting this option is /startup_delay=#.
PI Interface Configuration Utility User Guide
29
Using the PI ICU
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 UniInt Interface User Manual
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 the 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:
[PISERVER]
LONGPROCNAME=1
30
PI Interface Configuration Utility User Guide
Using the PI ICU
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: unchecked for
interfaces built against UniInt 4.4.5.4 and earlier. This command line parameter only
applies to interfaces built against UniInt 4.4.5.4 and earlier. Later versions of UniInt always
include the UFO ID in failover log messages.
Data Handling
• 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.
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 whether 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.
PI Interface Configuration Utility User Guide
31
Using the PI ICU
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 menu is populated with the states in the system digital state set from the PI Host
computer. 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 certain instances 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.
Outputs
• Disable all outputs from PI
If Disable all Outputs from PI is selected, outputs are entirely disabled for the interface
instance, and the message:
/NoOutputs flag detected. Outputs to PI disabled
is written to the message log when the interface starts.
The command-line equivalent for enabling this option is /NoOutputs.
• Suppress initial outputs from PI
32
PI Interface Configuration Utility User Guide
Using the PI ICU
The Suppress initial outputs from PI flag applies only for interfaces that support outputs.
When the interface starts, 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 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.
(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 manual for the type of failover supported by the
interface.
PI Interface Configuration Utility User Guide
33
Using the PI ICU
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.
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. 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
34
PI Interface Configuration Utility User Guide
Using the PI ICU
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:
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 state interface state points to show the current
failover state of each interface in the failover pair. The failover control points require interfacespecific configuration as well as UniInt failover point-specific configuration.
PI Interface Configuration Utility User Guide
35
Using the PI ICU
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 pulled
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 manual.
• 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 will be pulled 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.
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 manual for the type of failover supported by the
interface.
If an interface supports UniInt Failover Phase 2, the Synchronization File Path text box and
UFO Type drop down list are enabled.
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 will automatically be selected.
• Phase 1 / Phase 2
36
PI Interface Configuration Utility User Guide
Using the PI ICU
If the interface supports both types of failover, you must choose which type to use. If it only
supports one type, the other radio button is grayed out. 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 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:
PI Interface Configuration Utility User Guide
37
Using the PI ICU
• 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.
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.
38
PI Interface Configuration Utility User Guide
Using the PI ICU
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.
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
PI Interface Configuration Utility User Guide
39
Using the PI ICU
◦ 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
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 selected UniInt health point.
• Eng Units
This field is the engineering units of the selected UniInt health point.
• Snapshot
If the point exists in PI Server, then the Snapshot column holds the snapshot value for this
point.
40
PI Interface Configuration Utility User Guide
Using the PI ICU
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.
Topics in this section
• General interface health points
• Scan class health points
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
foreign device. 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 which 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"
PI Interface Configuration Utility User Guide
41
Using the PI ICU
The interface is properly communicating with the foreign device 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
The interface is connected to the foreign device. While in this state, the interface is not
capable or reading or writing data to the foreign device. 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.
42
PI Interface Configuration Utility User Guide
Using the PI ICU
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 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.
PI Interface Configuration Utility User Guide
43
Using the PI ICU
• 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.
• 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 foreign device,
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 foreign device 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 foreign system 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 - the foreign
system communication, the PI system communication, or elsewhere in the interface control
loop.
44
PI Interface Configuration Utility User Guide
Using the PI ICU
(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 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
PI Interface Configuration Utility User Guide
45
Using the PI ICU
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:
\\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.
46
PI Interface Configuration Utility User Guide
Using the PI ICU
Counter name
Description
Device Actual Connections
The actual number of foreign devices 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)
Device Scan Time (milliseconds)
Time in milliseconds to call developer function and gather
data from foreign system. Does not include the amount of
time to write the values to PI. 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)
PI Interface Configuration Utility User Guide
47
Using the 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
performance monitor, increase the update time of the
performance monitor to the minimum scan period for the
interface. For example, if the minimum scanning period
for the interface is 5 seconds (/f=5), set the update rate of
the performance monitor to 5 seconds by selecting the
Chart command from the Options menu. On the window,
change the periodic update time to 5 seconds. If the
update time is left at 1 second, the IO Rate appears to go to
zero between scans because no events are received
between scans.
Note:
This counter was removed from
UniInt starting with version 4.5.0.x.
The counter has been reinstated for
UniInt 4.6.0.x and later.
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
current value that is now stale, the Points Stale count
goes up and the Points Good count goes down. Only
good points go stale; points in error do not. Only applies to
the instance (_Total).
Points Stale 30(min)
Points Stale 60(min)
Points Stale 240(min)
48
PI Interface Configuration Utility User Guide
Using the PI ICU
Counter name
Description
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.
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.
PI Interface Configuration Utility User Guide
49
Using the PI ICU
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.
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
50
PI Interface Configuration Utility User Guide
Using the PI ICU
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
• Scan Class #
The Scan Class # column indicates which scan class the performance point in the Tagname
column belongs to. 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
features. 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 Interface Configuration Utility User Guide
51
Using the PI ICU
PI SDK options
• Determine whether the interface may use PI SDK
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 dialog box 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.
52
PI Interface Configuration Utility User Guide
Using the 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 UniInt Interface 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 sever. 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 location as the interface executable.
PI Interface Configuration Utility User Guide
53
Using the 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
location 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.
54
PI Interface Configuration Utility User Guide
Using the 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
against UniInt 3.5.4 and later and is disabled for interfaces built against UniInt versions 3.5.4
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
• Scan Performance Summary
When the percentage of scans that a UniInt-based interface performs on time drops below
95%, UniInt will print out performance summaries for each scan class. Performance
summaries are described in the section called "Performance points" in the PI Universal
Interface (UniInt ) User Guide.
The interface checks whether a performance summary should be printed out 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.
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 checked, the values and time stamps that
are received by the interface are also written to the log file.
PI Interface Configuration Utility User Guide
55
Using the PI ICU
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 IO 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 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 until 10 minutes after the interface has started.
PI ICU currently allows for one IO rate point to be configured for each copy of the interface that
is in use. Some interfaces allow for multiple points for IO rates.
• Enable IORates for this interface
This check box enables or disables IO rates for the current interface. To disable IO rates for
the selected interface, clear the check box. To enable IO 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 IO rate point or to save the new event counter.
◦ Click Delete to delete a point.
◦ Click Reset to reset the IO rate configuration as PI ICU suggests.
◦ Click Rename to specify a new name for the selected point.
◦ 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 IO rate point.
◦ Click Refresh Snapshots to update the snapshot.
• Event Counter
56
PI Interface Configuration Utility User Guide
Using the PI ICU
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 IO rate point.
• Tag Status
Tag Status indicates whether the IO rate point exists in PI. 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 IO 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 IO 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.
PI Interface Configuration Utility User Guide
57
Using the 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 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:
58
PI Interface Configuration Utility User Guide
Using the 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
PI Interface Configuration Utility User Guide
59
Using the 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.
60
PI Interface Configuration Utility 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 drop-down list 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 User Guide
61
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 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 list is provided of all 3.3 or
later PI Servers.
• Path
The path to the selected 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 #
62
PI Interface Configuration Utility 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 PI ICU dialog box.
• 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 User Guide
63
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 system, to store the command-line parameters. This option allows users to
configure one of these interfaces to be managed by the PI ICU.
64
PI Interface Configuration Utility 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 PI ICU dialog box. 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 User Guide
65
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.
66
PI Interface Configuration Utility 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 menu items available from the Tools menu.
Topics in this section
• Log Files
• Buffering
• 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) process. The PILogSrv process controls the size that PIPC logs become prior to
archiving and the number of old pipc.log files that are retained. The user can also start and
stop the PILogSrv process from this dialog box.
Topics in this section
• PIPC.Log Files page
• PIPC Log Server page
PI Interface Configuration Utility User Guide
67
PI ICU menu options
PIPC.Log Files page
Log files found under the PIHOME\dat directory are listed in this dialog box. Log files can be
viewed by double clicking on the log file name in the list view box.
The Continuous PIPC.log button displays 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 displays 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
68
PI Interface Configuration Utility User Guide
PI ICU menu options
The Start and Stop buttons allow the user to start and stop the PILogSrv utility. After a
change is made to one of the two settings, the OK button must be clicked, and then the
service must be stopped and restarted for the changes to be picked up by PILogSrv.
• Startup Type
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 interface service will not start on reboot, but will
require someone to manually start the service.
◦ If the Disabled option is selected, the service will not start at all.
Generally, the PILogSrv service is set to start automatically.
• Settings
There are two configurable parameters used by the PILogSrv utility 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 text box provided. The default is 256 KB. The
range is 1 KB to 4 MB
Buffering
The Tools > Buffering option helps you configure buffering. Depending on your current
configuration, this option does one of the following:
• If this computer is configured to buffer data using PI Buffer Subsystem 4.3 or later, the
Buffering Manager window opens and shows a buffering dashboard. The dashboard shows
information about the status of buffering on this computer.
• If this computer is not currently configured to buffer data, and PI Buffer Subsystem 4.3 or
later is installed, you are prompted to configure PI Buffer Subsystem. If you click Yes, the
Buffering Manager window opens and shows the installation wizard, which helps you
configure PI Buffer Subsystem.
• If this computer is configured to buffer data using API Buffer Server (bufserv), and PI Buffer
Subsystem 4.3 or later is installed, you are prompted to convert to and configure PI Buffer
Subsystem. If you click Yes at both prompts, the Buffering Manager window opens and
shows the upgrade wizard, which helps you upgrade from API Buffer Server to PI Buffer
Subsystem.
• Regardless of your current buffering configuration, if PI Buffer Subsystem 4.3 is not yet
installed, the Buffering dialog box opens.
You can use Buffering Manager to configure, monitor, and troubleshoot buffering using PI
Buffer Subsystem. PI Buffer Subsystem is recommended for applications connecting to PI
PI Interface Configuration Utility User Guide
69
PI ICU menu options
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 help
for more information.
Buffering dialog box
The Buffering dialog box enables the user to start, stop and edit parameters associated with
either of the buffering services:
• API Buffer Server (bufserv)
• PI Buffer Subsystem (PIBufss) version 3.4.380.79 or earlier
PI Buffer Subsystem is designed primarily to enhance the high availability (HA) features of the
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.
Topics in this section
• Choose Buffer Type
• Buffering Settings
• Buffered Servers
• PI Buffer Subsystem Service
• API Buffer Server Service
• Tools
Choose Buffer Type
The currently configured buffer and its status are displayed on this page.
The buffer selection affects all interface buffering on the node. When you choose a different
buffering service, any interfaces currently using a different buffer service are switched to the
selected buffering service. The selected service is set to Automatic, while the prior service is
stopped (if already running) and set to Disabled. Interface services are then stopped and
restarted. Service and settings changes can be made after the conversion completes.
70
PI Interface Configuration Utility User Guide
PI ICU menu options
Choose one of the following buffering options:
• Choose Disable buffering to disable all buffering on the interface node.
• Choose Enable buffering with PI Buffer Subsystem to enable buffering with the PI Buffer
subsystem.
is enabled if PI ICU is able to locate the PI Buffer Subsystem help file
The help button
(pibufss.chm in PIHOME\Help) directory.
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.
• Choose Enable buffering with API Buffer Server to use API Buffer Server for buffering.
Buffering Settings
The Buffering Settings page provides configuration settings for API Buffer Server and PI Buffer
Subsystem.
Only the options that apply to the buffer service currently selected on the Choose Buffer Type
page are enabled and appear in the dialog box. Most settings, however, are shared by both the
PI Buffer Subsystem and the API Buffer Server.
PI Interface Configuration Utility User Guide
71
PI ICU menu options
Default values are used by API Buffer Server and PI Buffer Subsystem if no other value is
provided. Click Clear to remove values from the text fields, thus telling the Buffer service to use
default settings.
• TCP/IP Port
The TCP/IP port for PI Server communication. The default value is 5450, with a range of 1
to 65535.
• Maximum buffer file size (KB)
Maximum buffer file size in kilobytes before buffering fails and discards events. The default
value is 2,000,000, with a range of 1 to 2,000,000.
• Primary memory buffer size (Bytes)
Primary memory buffer size is the size in bytes of the Primary memory buffer. The default
value is 32768, with a range of 64 to 2,000,000.
• Secondary memory buffer size (Bytes)
Secondary memory buffer size is the size in bytes of the Secondary memory buffer. The
default value is 32768, with a range of 64 to2,000,000.
• Send rate (milliseconds)
Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server
(milliseconds). The default value is 100, with a range of 0 to 2,000,000.
• Pause rate (seconds) (API Buffer Server)
When buffers are empty, the buffering process will wait for this number of seconds before
attempting to send more data to the home node. The default value is 2, with a range of 0 to
2,000,000.
• Retry rate (seconds)
72
PI Interface Configuration Utility User Guide
PI ICU menu options
When the buffering process discovers the home node is unavailable it will wait this number
of seconds before attempting to reconnect. The default value is 120, with a range of 0 to
2,000,000.
• Maximum transfer objects
Max transfer objects is the maximum number of events to send between each SENDRATE
pause. The default value is 5000, with a range of 50 to 2,000,000.
• Max theoretical send rate
The theoretical max send rate, calculated as max = MAXTRANSFEROBJS / SENDRATE *
1000. The default value is 50,000.
• Event queue file size (Mbytes)
The nominal disk size of the event queue files, in megabytes. The default value is 32, with a
range of 8 to 131,072 MB.
• Event queue path
The directory path to the event queue files. The default is PIHOME\DAT.
• Pause time when buffers are empty (milliseconds) (PI Bufss Server)
The pause time in milliseconds when API buffers are empty. The default is 10, with a range
of 0 to 2,000,000 ms.
• Maximum data rate per server connection (events/sec)
The maximum data rate per server connection. The minimum value is 500 events/second
and the maximum is 2,000,000 events/second.
Buffered Servers
This page displays the list of servers in:
• The PINODEIDENTIFIERS section of the PIHOME\dat\pilogin.ini file
Servers are added when selected on the main PI ICU dialog box in the API Hostname drop
down box.
• The BUFFEREDSERVERLIST and REPLICATEDSERVERLIST sections of the PIHOME\dat
\piclient.ini file
Topics in this section
• API Buffer Server - Buffered Servers
• PI Buffer Subsystem - Buffered Servers
• Making changes to the Buffered Servers when using PIBufss
PI Interface Configuration Utility User Guide
73
PI ICU menu options
API Buffer Server - Buffered Servers
• Add a server
Type the server name into the Add a server text box, and click Add Server to add a server to
the list of servers to be configured for buffering and/or replication. If the server is already
in the list, the Add Server button is disabled.
• Buffered
Data written to a server will be buffered if the Buffered column for the server is marked
Yes. No means that data will not be replicated to that server. To change the buffered status
of a server, click once in the Buffered column for that server.
Note:
A server must be buffered in order to be replicated. Toggling the buffering status off
also disables replication for the server as well.
• Replicated
Data written to a server will be replicated to other servers if the Replicated column for the
server is marked 'Yes'. 'No' means data will not be replicated to that server. To change the
replicated status of a server, click once in the Replicated column for that server.
Note:
A server must be buffered in order to be replicated. Toggling the replication status on
also enables buffering for the server as well.
• Reset Buffered and Replicated settings
To reset the Buffered and Replicated setting for all servers to off, right-click on the Server
list and select the Reset all to Off.
74
PI Interface Configuration Utility User Guide
PI ICU menu options
PI Buffer Subsystem - Buffered Servers
You can configure PI Buffer Subsystem to buffer data to one server or to any number of
members in a single PI collective.
• Replicate data to all collective member nodes
This option tells PI Buffer Subsystem to automatically buffer and replicate data to all
members of the selected collective.
• Buffered Server Names
PI Buffer Subsystem can create a buffer for any one server or member node using only one
name. There are three options for how the name is used by the PI Buffer Subsystem:
◦ Path: The SDK Server Path from the SDK known server list
◦ Name: The SDK Server Name from the SDK known server list
◦ IP Address
Making changes to the Buffered Servers when using PIBufss
After changing the buffered servers and clicking the Apply button the PI ICU will check to see if
PI SDK buffering is enabled and there are any applications running which might be using PI
SDK buffering. If any is found, the following dialog will be presented.
PI Interface Configuration Utility User Guide
75
PI ICU menu options
If no PI SDK applications which might be using buffering are found, the PI ICU will stop the API
Interface Services dependent on PIBufss, restart PIBufss and then the API Interface Services
automatically. The only indication will be the status message at the bottom of the Buffering
dialog.
Note:
The check for PI SDK and PI API applications using PIBufss for buffering only checks for
API Interface services which have a dependency on PIBufss. If there are other
applications which are API-based and are not Interface Services but depend on PIBufss
for buffering, they will not be detected and could have problems buffering data after
PIBufss is restarted. These application will need to be restarted manually just like the PI
SDK applications.
• Refresh
This button when clicked will again check for SDK applications and API Interfaces which
might be using buffering and display a list of them in the appropriate box. This can be used
to see that any application that was manually stopped after the display of the dialog first
was presented has actually stopped.
• Cancel
Clicking this button will cancel any change to the Buffered Servers.
• Restart PIBufss
Clicking this button will:
76
PI Interface Configuration Utility User Guide
PI ICU menu options
a. Automatically stop all API Interface Services which have a dependency on PIBufss.
b. Stop PIBufss.
c. Restart PIBufss.
d. Restart all API Interface Services which were stopped in step 1 above.
PI Buffer Subsystem Service
Use the PI Buffer Subsystem Service page to configure and run PI Buffer Subsystem, if selected.
• PI Buffer Subsystem version
The version of the PI Buffer Subsystem installed on this machine.
• Service name
The name of the PI Buffer Subsystem.
• Display name
The full name associated with the PI Buffer Subsystem service.
• Log on as
This user account the PI Buffer Subsystem service will use. If this text box is left blank, then
LocalSystem is used.
• Password/Confirm Password
A password for the service login account, if required. If no password is required, this field
can remain blank.
• Dependencies
PI Interface Configuration Utility User Guide
77
PI ICU menu options
The Dependencies lists the Windows services on which the PI Buffer Subsystem service is
dependent.
• Dependent Services
The dependent services list shows all interface services on this machine that have a
dependency on PI Buffer Subsystem service. It also shows their current status.
• Start / Stop
The Start and Stop buttons allow for the PI Buffer Subsystem service to be started and
stopped.
After any changes are saved to the Settings tab, the service must be stopped and restarted
for the changes to be picked up.
If there are any services that are dependent on the PI Buffer Subsystem service, they must
be stopped before the PI Buffer Subsystem service can be successfully stopped. A dialog box
prompts you to stop any dependent services.
• Startup Type
Startup Type indicates whether the PI Buffer Subsystem service is setup to start
automatically or manually on reboot, or is disabled.
◦ If the Auto option is selected, the service is installed to start automatically when the
machine reboots.
◦ If the Manual option is selected, the interface service will not start on reboot, but will
require someone to manually start the service.
If the Disabled option is selected, the service will not start at all.
If the Disabled option is selected, the service will not start at all.
Generally, the PI Buffer Subsystem service is set to start automatically.
• Create / Remove
Click Create to create the PI Buffer Subsystem service with the specified dependencies and
Startup Type. Click Remove to remove the PI Buffer Subsystem service. This button is
disabled if the service is not currently installed or is currently running.
Parameter Details
The Parameter Details page for PI Buffer Subsystem includes detailed information about each
of the parameters that PI Buffer Subsystem uses for buffering data.
78
PI Interface Configuration Utility User Guide
PI ICU menu options
API Buffer Server Service
Use the API Buffer Server Service page to configure and run API Buffer Server (Bufserv), if
selected.
• API Buffer Server version
PI Interface Configuration Utility User Guide
79
PI ICU menu options
The version of the PI Buffer Server installed on this machine.
• Service name
The name of the PI Buffer Server.
• Display name
The full name associated with the PI Buffer Server service.
• Log on as
The user account the PI Buffer Server service will use. If this text box is left blank, then
LocalSystem is used.
• Password / Confirm Password
A password for the service login account, if required. If no password is required, this field
can remain blank.
• Dependencies
The Dependencies lists the Windows services on which the PI Buffer Server service is
dependent.
• Dependent Services
The Dependent Services list shows all services on this machine that have a dependency on
PI Buffer Server service. It also shows their current status.
• Start / Stop
The Start and Stop buttons allow for the PI Buffer Server service to be started and stopped.
After any changes are saved to the Settings tab, the service must be stopped and restarted
for the changes to be picked up.
If there are any services that are dependent on the PI Buffer Server service, they must be
stopped before the PI Buffer Server service can be successfully stopped. A dialog box
prompts you to stop any dependent services.
• Startup Type
Startup Type indicates whether the PI Buffer Server service is setup to start automatically
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 interface service will not start on reboot, but will
require someone to manually start the service.
◦ If the Disabled option is selected, the service will not start at all.
• Create / Remove
Click Create to create the PI Buffer Server service with the specified dependencies and
Startup Type. Click Remove to remove the PI Buffer Server service. This button is disabled if
the service is not currently installed or is currently running.
80
PI Interface Configuration Utility User Guide
PI ICU menu options
Tools
There are two choices under the Buffering > Tools menu: API Buffer Server or PI Buffer
Subsystem. Only the choice appropriate for the selected buffering system is enabled.
Topics in this section
• API Buffer Server > Run Bufutil
• PI Buffer Subsystem > Run PIBufss –Cfg
PI Interface Configuration Utility User Guide
81
PI ICU menu options
API Buffer Server > Run Bufutil
Choose API Buffer Server if you have chosen this type of buffering. Then click on the Run
Bufutil and a command window will appear with the Bufutil menu. Enter the number of the
menu item you wish to look at and hit return.
82
PI Interface Configuration Utility User Guide
PI ICU menu options
PI Buffer Subsystem > Run PIBufss –Cfg
Choose PI Buffer Subsystem if you have chosen this type of buffering.
Click Run PIBufss -Cfg to open a command window with configuration and status information
about the PI Buffer Subsystem.
Run apisnap
This option runs apisnap.exe in a command window. If an interface is selected, apisnap will
run pointing to the 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.
PI Interface Configuration Utility User Guide
83
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
84
PI Interface Configuration Utility User Guide
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 node time
and time zones.
View Digital State Sets
If an interface is selected, the digital state sets on the 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.
PI Interface Configuration Utility User Guide
85
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 manual.
Interface Communication Test Utility
If PI ICU is able to locate a utility to test a connection to the DCS (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 manual.
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 manual.
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 list 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.
86
PI Interface Configuration Utility User Guide
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:
• IO rate points
• Interface Status Utility points
• UniInt performance points and UniInt health points
• Performance counter points
PI Interface Configuration Utility User Guide
87
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.
88
PI Interface Configuration Utility User Guide
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
PI Interface Configuration Utility User Guide
89
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 in these points.
.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 grayed out, 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.
90
PI Interface Configuration Utility User Guide
PI ICU menu options
PI Interface Configuration Utility User Guide
91
PI ICU menu options
92
PI Interface Configuration Utility 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
• Uninstallation of 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 to 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 Interface Configuration Utility.pdf
PI-ICU.exe
PIICU_ReleaseNotes.htm
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
PIICU_ReleaseNotes.htm
Release notes
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
PI Interface Configuration Utility User Guide
93
PI ICU installation
File
Description
PIICURegisterControl.dll
Library used by PI ICU to register interfaces with
PI ICU
PI Interface Configuration Utility.pdf
PI Interface Configuration Utility User Guide (This
publication).
WatchLog.exe
Log Files program to watch the PIPC.log file
continuously from within PI ICU.
PIInterfaceConfigurationUtility.chm
PI ICU Help file
A PI Interface Configuration Utility shortcut is added to Start > Program Files > PI System.
Uninstallation of 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
to uninstall the following 3 programs:
◦ PI GenericNames
◦ PI Interface Configuration Utility
◦ PI Spt
The PI Software Development Kit (PI SDK) might have been installed by PI ICU, but 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 User Guide
Migrate an interface to another PI Server
Interfaces are often configured by writing to a test PI Server, and then moving 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 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 dialog box 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 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 dialog box. The PI ICU will reload
interfaces.
c. Load the interface you want to move from one PI Server to another, and select the new
PI Server in the Host drop-down list.
The interface 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 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 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
PIGenericNames.dll is not
present or not registered
This error indicates that the PIPC\Library
\PIGenericNames.dll file is not installed, missing or
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
PISpt.dll is not present or
not registered
This error indicates that the PIPC\Library\PISpt.dll file is not
installed, missing or unregistered. To register the file, open a
command window, change directories to the PIPC\Library
directory, and type in the following command:
Regsvr32 PISpt.dll
The PI SDK version is older
than the required version
PI ICU requires PI SDK 1.3.4 or later on the machine on which PI
ICU is to run. If the PI SDK version is older, it must be upgraded.
Error 713 attempting to
load the ICU Control
This error indicates that the PI ICU control has been registered on
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 User Guide
97
Error and informational messages for PI ICU
Message / issue
Comment
Error 450 attempting to
load the ICU Control
This error indicates that the PI ICU control is registered and
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
Interface drop down list for a
particular node
This indicates that the PI ICU program could not access the
Module Database on the particular node in question. If the drop
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
does not show up in PI ICU
This usually indicates that the PI ICU control has not been
registered. The setup kit for a particular PI ICU control will
attempt to register the control. To manually register an 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 User Guide
Error and informational messages for PI ICU
Message / issue
Comment
Critical Error -11452 and -11402
from PIBufss
This error indicates that PIBufss cannot create the shared memory
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 User Guide
99
Error and informational messages for PI ICU
100
PI Interface Configuration Utility User Guide
Technical support and other resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or through the
OSIsoft Tech Support website (https://techsupport.osisoft.com). The website offers additional
contact options for customers outside of the United States.
When you contact OSIsoft Technical Support, be prepared to provide this information:
• Product name, version, and build numbers
• Details about your computer platform (CPU type, operating system, and version number)
• Time that the difficulty started
• Log files at that time
• Details of any environment changes prior to the start of the issue
• Summary of the issue, including any relevant log files during the time the issue occurred
The OSIsoft Virtual Campus (vCampus) website (http://vcampus.osisoft.com) has
subscription-based resources to help you with the programming and integration of OSIsoft
products.
PI Interface Configuration Utility User Guide
101
Technical support and other resources
102
PI Interface Configuration Utility User Guide
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising