PI Interface Configuration Utility. Version

Transcription

1 PI Interface Configuration Utility Version

2 OSIsoft, Inc. 777 Davis St., Suite 250 San Leandro, CA USA Additional Offices Houston, TX Johnson City, TN Longview, TX Mayfield Heights, OH Philadelphia, PA Phoenix, AZ Savannah, GA Sales Outlets/Distributors Middle East/North Africa Republic of South Africa Russia/Central Asia South America/Caribbean Southeast Asia South Korea Taiwan International Offices OSIsoft Australia Perth, Australia Auckland, New Zealand OSIsoft Germany GmbH Altenstadt, Germany OSIsoft Asia Pte Ltd. Singapore OSIsoft Canada ULC Montreal, Canada Calgary, Canada OSIsoft, Inc. Representative Office Shanghai, People s Republic of China OSIsoft Japan KK Tokyo, Japan OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil Contact and Support: Main phone: Fax: Support phone: Web site: Support web site: Support (01) (01) (01) techsupport@osisoft.com Copyright: OSIsoft, Inc. 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, Inc. OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI Web Parts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, Inc. 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, Inc. license agreement and as provided in DFARS , DFARS , FAR , FAR , as applicable. OSIsoft, Inc. Published: 8/12/2009

3 Table of Contents Chapter 1 Introduction...1 Version Requirements...1 How PI ICU Works...2 Chapter 2 Getting Started with PI ICU...7 Create Interfaces...8 Start the PI Interface Service...10 Start Buffering...11 PIPC Log Files and Service...11 Manage Interfaces...12 Remove Interfaces...12 Backup and Restore...13 Chapter 3 Using PI ICU...15 Interface Selection and Operation...16 General Page...17 UniInt Page...22 (UniInt) PI SDK...27 (UniInt) Disconnected Startup...29 (UniInt) Debug...31 (UniInt) Failover...33 (UniInt) Performance Points...39 (UniInt) Performance Counters...41 (UniInt) Health Points...44 Interface Page...50 Service Page...52 IO Rate Page...55 Interface Status Page...57 Chapter 4 Menu Commands...61 Interface Menu...61 Tools Menu...67 Chapter 5 Installation...93 Install PI ICU...93 Uninstall PI ICU...94 PI Interface Configuration Utility iii

4 Table of Contents Chapter 6 Migration...95 Chapter 7 Troubleshooting...97 Technical Support and Resources...99 iv

5 Chapter 1 Introduction The 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 can be configured and maintained using PI ICU. PI ICU allows the user to: Configure all Interface parameters. Manage, start and stop the interface service. View and configure Interface service dependencies. Configure and run the PI Buffer Subsystem and API Buffer Server applications. Configure and run the PI Log Server application. Manage multiple PI Interfaces. Quickly find and view the PIPC log files. Execute Interface configuration diagnostics. Run the bufutil buffering utility. Version Requirements PI ICU uses the PI Module Database on the PI server as a repository for interface startup parameters. PI or greater on Windows 2000/XP/2003 Server/Vista/2008 Server is required for the host PI server. PI ICU and later requires PI SDK 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 or later is not supported on Windows NT 4.0 because PI SDK is not supported on Windows NT 4.0. PI ICU versions prior to are supported on Windows NT 4.0. PI Interface Configuration Utility 1

6 Introduction 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. 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 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, interface-specific PI ICU Controls are being developed. PI ICU Controls provide access to interface-specific options through the common PI ICU application framework. When an ICU Control is installed, the Interface page in PI ICU includes an interface-specific dialog box containing the native interface settings. Some PI ICU Controls are installed with your interface, while others are installed separately. You can visit the Interface website ( =45EB82FC-C7E7-49EE-B59D-13BC67EAA41B&posting_guid=FA6362B4-348D-42BB- A524-E47356A27BDF) and click PI Interfaces with ICU Controls to find out whether a PI ICU Control exists for a particular interface. To obtain PI ICU Controls for interfaces installed prior to the release of PI ICU, visit the Technical Support website ( 2

7 How PI ICU Works Note that any PI Interface may still be configured with PI ICU, even if the 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 User's 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 or later and PI SDK 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 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. Module Database Permission 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 3

8 Introduction 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 ICU Controls for some interfaces have the ability to create specific digital sets that are needed by the interface. Consult the ICU Control section in the user manual for each interface that PI ICU will manage. Since 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. Point Database Permissions PI ICU can create, edit, or delete the following types of points that are common to UniIntbased interfaces: PI Perfmon 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 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 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 PIModules table %OSI module %OSI\Interfaces module and all submodules PIPOINT table Individual PI Points (PtAccess or PtSecurity attribute) PIDS table Access Permission RW RW RW RW RW RW With the access permissions in this table, PI ICU can perform all its functions. 4

9 How PI ICU Works PI Mappings and Security Permissions For PI Server version 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. 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 , PI Trusts specify a PI User to log on. With PI Server version 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. PI Interface Configuration Utility 5

10 Introduction Required Windows Permissions The following sections describe the Windows permissions and security privileges required by PI ICU. Registry Permissions PI ICU stores some settings in the local registry. The PI ICU user account must have read/write permissions to update these registry keys and any below them: 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. See the Microsoft Knowledge Base article ( that describes several methods for granting users the rights to manage services in Windows 2000 for further information. Also look at Microsoft Knowledge Base article ( for Windows 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

11 Chapter 2 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. PI Interface Configuration Utility 7

12 Getting Started with PI ICU Create Interfaces 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. Create a New PI Interface Before you begin, consult the appropriate PI Interface user manual for configuration details required to run the interface. All interface manuals can be found online on the Interfaces web site ( =45EB82FC-C7E7-49EE-B59D-13BC67EAA41B&posting_guid=FA6362B4-348D-42BB- A524-E47356A27BDF). To configure a new PI Interface: 1. Install the PI Interface you want to configure. Also install any ICU Controls available for the interface, if not already installed. 2. Run PI ICU and choose Interface > New Windows Interface Instance from EXE. You can also click the Create new interface instance Configure a New Interface dialog box appears. button on the toolbar. The 3. Click Browse to browse to the interface executable (.exe) file for the new interface. 8

13 Create Interfaces 4. Enter the Interface name, Point Source, Interface ID # and Service ID fields if you have the information available. 5. Enter the name of the host PI server or collective, and click Add. 6. Click OK in the confirmation dialog box. The interface appears in the Interface text box in the main ICU dialog box. 7. Select the proper Type for the interface on the main ICU screen, if it is not selected automatically. 8. 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. 9. Use PI ICU and an application to create PI Tags (PI Point Builder application, PI Tag Configuration Excel add-in) to configure and run the PI Interface. Note: Once PI ICU has been used with a PI Interface, all subsequent configuration changes should be conducted in PI ICU. PI ICU will prompt the user if the command line parameters stored in the Module Database do not match those stored in the PI Interface batch (.bat) file. Configure an Existing PI Interface A new instance of the same interface can be created 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. To configure an existing PI Interface: 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. 3. The interface is loaded and appears in the main PI ICU dialog box. 4. 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. 5. Use PI ICU and an application to create PI Tags (PI Point Builder application, PI Tag Configuration Excel add-in) to configure and run the PI Interface. Note: Once PI ICU has been used with 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. PI Interface Configuration Utility 9

14 Getting Started with PI ICU Start the PI Interface Service Once parameters and PI tags 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. 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 > Options > 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. Choose Interface > Start Interactive to start the interface in interactive mode. Press Ctrl-C or close the DOS Command window to stop operation in interactive mode. A DOS Command prompt appears and the interface begins operation automatically. Messages are displayed in the DOS Command window indicating 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. 10

15 Start Buffering Start Buffering PI ICU assists in configuring and running buffering (API Buffer Server or PI Buffer Subsystem). 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 which server's data will be buffered. 5. Use the API Buffer Server Service and PI Buffer Subsystem pages to configure and control the buffering services. PIPC Log Files and Service PI ICU can be used 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 re-opened in PI ICU. Click Continuous to open a command window and view messages as they are written to a selected log file. The Services and Settings page is used to start and stop the service. Configure the Maximum Log File and Maximum Log File Size parameters of the PIPC Log Server, if desired. Click the Start button to start the service. PI Interface Configuration Utility 11

16 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 ICU, which only removes the interface from the PI MDB, or you can completely uninstall the interface. To remove (or unregister) an interface from PI ICU: 1. Select the interface to be removed in the Interface drop-down list. 2. Choose Interface > Unregister Interface from ICU. A confirmation dialog box appears to confirm that you want to de-register the interface from ICU without touching the interface service or files. Note: De-registering an interface from PI ICU does not delete the batch (.bat) file or the executable file (.exe) associated with the interface. To remove an interface instance from the machine and unregister it from PI ICU: 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. 12

17 Backup and Restore 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. During backups, the PI Module Database must be backed up with the host PI Server. Users 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 13

18

19 Chapter 3 Using 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. PI Interface Configuration Utility 15

20 Using PI ICU 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 by the user. 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 ICU is able to determine the interface type automatically. If the ICU is not able to determine the interface type, the user must select the proper interface type to access a matching ICU Control. Once the correct interface Type is selected, an 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. Note: Be sure 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. 16

21 General Page 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. PI Interface Configuration Utility 17

22 Using PI ICU General Options Point Source(s) The Point Source(s) field holds the point sources used by all Tags 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 enabled. The Add button is enabled when a unique Point Source definition is entered. The list box and Add button are disabled, if the interface does not support multiple Point Sources. 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. 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. If the desired Host name is not in the drop-down list, choose Interfaces > SDK Connections to add the new server. The server will then be available in the drop-down list within PI ICU. 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 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. 18

23 General Page User The Current User is the username on the host PI System that the current PI API and PI SDK connections are using. Note: The PI Interface Configuration Utility can communicate to PI Servers version 3.3 and later, and must run on a computer where PI SDK or later is installed. PI SDK and later is not supported on Windows NT 4.0, so PI ICU and later is not supported on Windows NT 4.0. PI ICU versions prior to 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. Description The Description field is the description assigned to the PI server in the SDK Member field. PI Interface Configuration Utility 19

24 Using PI ICU 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 Tags, which are closely related to scan rates for PI Tags. 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: 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:06:10, the second scan would be at 05:07:10, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined. The definition of a scan class does not guarantee that the associated points 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. 20

25 General Page 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 1 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. 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. Installation Path The 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 change the installation path using the Browse dialog box. to If the Installation Path is changed, click Apply 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. PI Interface Configuration Utility 21

26 Using PI ICU UniInt Page General UniInt settings appear on the main UniInt tab. 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 stoptime seconds for the main thread to reach a safe exit point before the exit handler continues with its cleanup operations. By default, stoptime is 120 seconds. If stoptime 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 Max 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 stoptime. 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 SDK after a reboot has occurred. The command line equivalent for setting this option is /startup_delay=#. 22

27 UniInt Page 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 The Point update interval can be used 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 Users Manual for more information. The command line equivalent for setting this option is /updateinterval=#. Click Reset button to load the default point update interval setting to the text box. 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 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, check the Disable UniInt performance counters check box. With UniInt 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. PI Interface Configuration Utility 23

28 Using PI ICU Include Point Source in the header of log messages When the Include Point Source in the header of log messages option is checked, 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. Service events period The Service events period controls the Service Events TimeOut, specified in milliseconds. Events are serviced (retrieved from the evmexceptions queue on the 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 may not be sufficient and can be adjusted with the Service events period start-up parameter. The minimum value for x 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 to the text box. 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. Bypass exception Selecting the Bypass exception checkbox tells the interface whether to ignore the exception specifications of the tag and put all the input events into the PI snapshot. By default, this option is disabled in order to reduce data traffic. The command line equivalent for enabling option is /sn. Write status to tags on shutdown The stop status setting indicates whether a digital state value is written to a tag 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 checkbox is selected, but no system digital state is entered into the text box, then the system digital state 'Intf Shut' is written to all tags belonging to this interface when the interface stops. 24

29 UniInt Page If the checkbox is selected and a valid system digital state is entered, then that system digital state is written to all tags 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 tags. 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, independent of whether the PI SDK is enabled. In this case, check 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 may 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 timezone 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 checked, 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 The Suppress Initial Outputs flag applies only for interfaces that support outputs. When the interface starts, it determines the current snapshot value of each output tag, and then writes the values to corresponding tags. If an output tag is edited while the interface is running, the interface writes the current snapshot value to the edited output tag. 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 tags are edited. Instead, they are written only when explicitly triggered. The command line equivalent for enabling this option is /sio. PI Interface Configuration Utility 25

30 Using PI ICU Use event timestamp instead of current timestamp for initial outputs Some interfaces send the current value of the source tag at start-up. By default, the timestamp sent with the initial value is the current PI time. This option instructs UniInt to send the timestamp of the source tag's 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. 26

31 (UniInt) PI SDK (UniInt) PI SDK The PI SDK may not 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 and greater. 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 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 SDK on/off setting specified by the interface developer. Enable PI SDK tells the interface to use SDK features, regardless of the setting specified by the interface developer. The command line equivalent for setting this option is /pisdk=1. PI Interface Configuration Utility 27

32 Using PI ICU Override default SDK timeout The timeout in seconds used by PI SDK calls, this option overrides 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 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 than 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 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 SDK connection timeout setting to the text box. 28

33 (UniInt) Disconnected Startup (UniInt) Disconnected Startup These options set preferences for disconnected startup of a UniInt interface. Enable disconnected startup (with point caching) Interfaces built with UniInt version 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 manual.doc file. 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 50ms, and the maximum period is 3000ms (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=#. PI Interface Configuration Utility 29

34 Using PI ICU 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. 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 up, 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 versioning 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. 30

35 (UniInt) Debug (UniInt) Debug The Debug page provides preferences and debugging tools. Debug Levels The UniInt Debug Level 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 checkbox 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 checked boxes, click Reset. The Point list creation debug level replaces the Point Additions debug level in interfaces built against UniInt and later and is disabled for interfaces built against UniInt versions and later. The following debug levels have been removed from PI ICU as of UniInt version or later: Sending data to PI Main control loop Services PI-SDK PI Interface Configuration Utility 31

36 Using PI ICU 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. 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 scan performance summary flag is omitted, then UniInt checks whether summaries should be printed out every 8 hours by default. If the inputs for the interface are unsolicited, then performance summaries should be set to 0 because performance summaries are meaningless for unsolicited input points. Click Reset to load the default Scan Performance Summary 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 and timestamps for check box is checked, the values and timestamps that are received by the interface are also written to the log file. Tracing can be enabled for a particular point by specifying a tag name or point id in the text box provided. The Tag Search button brings up the tag search dialog box. This option should be used with caution because specifying this option could cause the log file to become very large. 32

37 (UniInt) Failover (UniInt) Failover Phase 1 UniInt Failover Phase 1 is supported on a per-interface basis for interfaces built with UniInt and later. See the individual interface manual for the type of failover supported by the interface. If an interface does not support UniInt failover, the Failover page displays a message in the status text box at the bottom of the Failover tab. 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 it only supports one type, the other radio button is grayed out. This must be the first item selected when configuring failover. Failover ID# for this interface 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. PI Interface Configuration Utility 33

38 Using PI ICU Failover ID# for the other interface This is the failover ID assigned to the other interface in the failover pair. By default, the pairs are named 1 and 2. To select the other interface in the failover pair: 1. Click Browse to view all the interfaces registered with the ICU for this PI server from all interface nodes. The interface that represents the current interface is noted as (* Current Interface), and cannot be selected for the other interface. 2. Select the other interface in the failover pair. Failover control tags are unsolicited (not scan based) The /UFO_Interval startup parameter can only be used with unsolicited input interface failover control tags. If the interface supports scan based input data and the interface failover tags are defined as scan based input tags, the update interval is then defined by the scan class to which the control tags 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 tags. Both interface copies participating in failover must use the same failover update interval. The failover update interval, i, is specified in milli-seconds with the default being 1000 milliseconds or 1 second. The valid range for the failover update interval is milliseconds. The failover update interval can be changed in the "Rate at which the heartbeat point is updated/checked" text box. 34

39 (UniInt) Failover UniInt Failover Points Each failover pair requires six (6) failover control points and two (2) optional state points to 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 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. PI Interface Configuration Utility 35

40 Using PI ICU Interface State Points An optional pair of digital state interface state points can be defined to show the current failover state of each interface in the failover pair. The failover control points require interface-specific configuration as well as UniInt Failover point-specific configuration. Right-click to display a context menu and choose from the following options: Export Point Configuration (.csv): If the points exist in PI, the attributes that are exported to the csv file are pulled from PI. If the points do not exist in PI, 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, the set and states in the csv file will be pulled from PI. If the "UFO_State" digital set does not exist in PI, 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, this menu is enabled and can be used to create the "UFO_State" digital set on the PI server to which this interface writes. 36

41 (UniInt) Failover Phase 2 UniInt Failover Phase 2 is supported on a per-interface basis for interfaces built with UniInt and later. See the individual interface manual for the type of failover supported by the interface. If an interface does not support UniInt failover Phase 2, the Synchronization File Path text box and UFO Type dropdown are not displayed and UniInt failover Phase 1 will be used if enabled. If an interface supports both Phase 1 and Phase 2 UniInt Interface Level Failover then two radio buttons will appear at the top. The user should choose which type of failover to enable. If the interface only supports Phase 2 this radio button will automatically be chosen for the user. Phase 1 / Phase 2 If the interface supports both types of failover, you must choose which type to use. If it only supports one type, the other radio button is grayed out. This must be the first item you select when configuring failover. 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=<UNC path>. 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). PI Interface Configuration Utility 37

42 Using PI ICU UFO Type UniInt Interface Level Failover Phase 2 can be configured for one of three types: HOT, WARM and COLD. The ICU will only allow the user to choose supported types for the interface being configured. The default type is COLD. The command line equivalent for this parameter is /UFO_Type=<type> where <type> is HOT, WARM or COLD. 38

43 (UniInt) Performance Points (UniInt) Performance Points Performance points only pertain to UniInt-based interfaces and this section is disabled if the interface being configured is not UniInt- based. Performance points monitor the amount of time in seconds that it takes an interface to complete a scan for a particular scan class. The closer the scan time is to 0 seconds, the better the performance. The scan time is recorded to millisecond resolution. The Perf Points page allows users to create, delete, correct and rename UniInt interface Performance Points. Right-click and choose a menu option 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. If a tag already exists, the status is marked 'Created' and the Delete option is enabled. If a tag does not exist, the status is marked 'Not Created' or 'Deleted' and the Create option is enabled. PI Interface Configuration Utility 39

44 Using PI ICU Performance Points are created with the following PI attribute values: Tag: tag name that appears in the list box Point Source: Point Source for tags for this interface, as specified on the first page Compressing: Off Excmax: 0 Descriptor: Interface name + " Scan Class # Performance Point" Status The Status column in the Performance Points table indicates whether the Performance Point exists for the scan class in column 2. 'Created' - Indicates that the point does exist 'Not Created' - Indicates that the point does not exist 'Deleted' - Indicates that a point existed, but was just deleted by the user 'Incorrect' - 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 combo box on the UniInt Parameters page. Tagname The Tagname column holds the Performance Point tag name. 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 Tagname exists in PI, then the Snapshot column holds the snapshot value for this tag. 40

45 (UniInt) Performance Counters (UniInt) Performance Counters The Perf Counters page allows users to create, delete, correct and rename PI PerfMon Performance Counter Points. Performance Counters are available only in UniInt-based interfaces built with UniInt and later, and 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 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 option 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. If a tag already exists, the status is marked 'Created' and the Delete option is enabled. If a tag does not exist, the status is marked 'Not Created' or 'Deleted' and the Create option is enabled. PI Interface Configuration Utility 41

46 Using PI ICU Performance Counter Points are created with the following PI attribute values: Tag: tag name that appears in the list box Point Source: Point Source for Performance Counter tags is the Point Source used by 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 Descriptor: The descriptor used is based on the type of Performance Counter. Compressing: Off Excmax: 0 Location1: The ID used by PI PerfMon interface Location4: 1 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 Performance Counter Point tag name. PS The PS field is the Point Source of the Performance Counter Point. Snapshot If the Tagname exists in PI, then the Snapshot column holds the snapshot value for this tag. Performance Counter The Performance Counter column indicates for which Performance Counter the Performance Counter Point collects data. 42

47 (UniInt) Performance Counters Performance Counter Point Types The following Performance Counter Point Types are available and appear in the Descriptor field. Performance Counter Interface up-time (seconds) IO Rate (events/second) Point Count Scan Time (milliseconds) Scheduled Scans: % Missed Scheduled Scans: % Skipped Scheduled Scans: Scan count this interval Log file message count Points edited in the interface Points added to the interface Points removed from the interface Descriptor The number of seconds that have elapsed since the interface has started. Only applies to the instance (_Total) Number of events per second written to the PI Snapshot. Only applies to instance (_Total) Number of points loaded by the interface. Applies to both instance (_Total) and Scan Classes. Time in milliseconds to call developer function and to write values to PI. Does not apply to the instance. Applies to Scan Classes only. Percentage of missed scans since starting the interface. If a scan occurs more than 1 second after its scheduled time, the scan is considered missed. Applies to both instance (_Total) and Scan Classes. Percentage of skipped scans since starting the interface. If a scan occurs 1 scan period or more after its scheduled time, then 1 or more scans are considered skipped. Applies to both instance (_Total) and Scan Classes. Total number of scans over the current performance interval for a particular scan class. Performance interval time is set with the /PERF=<hours> flag (8 hours by default). Applies to both instance (_Total) and Scan Classes. Number of messages that have been written to the log file. Only applies to the instance _Total. Number of point edits that have occurred. Only applies to the instance _Total. Number of point that have been added to the interface. Only applies to the instance _Total Number of point that have been removed from the interface. Only applies to the instance _Total PI Interface Configuration Utility 43

48 Using PI ICU (UniInt) Health Points UniInt Health Points are supported by interfaces built with UniInt 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. If a tag already exists, the status is marked 'Created' and the Delete option is enabled. If a tag does not exist, the status is marked 'Not Created' or 'Deleted' and the Create option is enabled. Status The Status column in the Health Points table indicates whether the Health Point exists. 'Created' - Indicates that the point does exist 'Not Created' - Indicates that the point does not exist 'Deleted' - Indicates that a point existed, but was just deleted by the user 'Incorrect' - Indicates that the point exists in PI, but is not correctly defined 44

49 (UniInt) Health Points Tagname The Tagname column holds the Health Point tag name. Type The Type column holds the reserved keyword for the specified Health point that is written to the Extended Descriptor of the Health Point. Scan Class # Some Health Points belong to interface scan classes. For those that do, the Scan Class column indicates which scan class the Health Point in the Tagname column belongs to. UFO ID If the interface is configured to use UniInt failover, the Location3 property must match the UniInt Failover ID configured with the /UFO_ID parameter. For all of the PI points that match the point source, id and optionally the ufo_id, the exdesc PI property is searched for a keyword. If the keyword is found, some other PI properties 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 property must match the UniInt Health Tag ID configured with the /UHT_ID parameter. This parameter must be configured in the interface-specific page of the ICU control. PS The PS field is the Point Source of the UniInt Health Point. ID The ID (typically Location1, but sometimes another attribute) for the selected UniInt Health Point. Point Type The Point Type of the selected UniInt Health Point. Eng Units The Engineering Units of the selected UniInt Health Point. Snapshot If the Tagname exists in PI, then the Snapshot column holds the snapshot value for this tag. PI Interface Configuration Utility 45

50 Using 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 Manual. General Interface Health Tags The general interface health tags pertain to the operation of the interface in general. A list of scan class health tags follows. The scan class health tags require a valid scan class be configured in Location4 of the PI tag. The general Interface Health tags do not consider the Location4 value. Interface Information Point [UI_IF_INFO] One Interface Information Point may be configured on a PI server. The Interface Information point is used for a central place for a PI administrator to view all of the interfaces currently running connected to the PI server. There can be only one Interface Information Point per PI server. If the interface discovers and loads an Interface Information Point, the interface will write to the point the following list of values; the name of the computer the interface is running on, the IP address, the name of the interface executable, the point source, the interface id, optionally the failover id, the number of scan classes, the number of points loaded by the interface, the percentage of tags loaded by the interface that are in a good status, the count of how many messages the interface has logged since start-up, and the number of seconds the interface has been running. The following is an example value for an interface running on the computer 'IFNode1', at IP address , executable name is TestIF.exe, point source is W, and the interface ID is 1. The failover ID is not logged because the interface is not running in failover mode. There are two scan classes defined, one with a 10 second update rate and a 5 second offset and the second scan class has a 1 second interval. The rest of the information is described in the value written to the PI tag. IFNode TestIF.exe W 1 2 Scan Classes 00:00:10,5; 00:00:01 Points 4 Percent Good 100 Message Count 34 Up Time 3568 Heartbeat [UI_HEARTBEAT] The heartbeat tag is the primary tag used to determine if the interface is running. If the value of the heartbeat tag 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 tag increments from a value starting at 1, increments to a value of 15 and then restarts at 1. 46

51 (UniInt) Health Points The heartbeat tag will stop updating if the interface is shut down or if the interface is in a deadlock situation. Note: The Interface Health Heartbeat tag is completely separate from the UniInt Failover Heartbeat tag. An interface can have both an Interface Health Heartbeat tag and a UniInt Failover Heartbeat tag loaded simultaneously. Device Status [UI_DEVSTAT] The device status tag stores communication information about the interface and the foreign device. The device status tag is a string type PI point evaluated only while the heartbeat tag is updating. During normal shutdown of the interface, the string text of 4 Intf Shut will be written to this tag. 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 tag. The update values and meaning of this tag are as follows. System Digital State Good - 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 tag. 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 may be provided by the interface is appended to the UniInt provided string value. 3 n device(s) in error - the interface is not able 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 Tag is a string tag 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 tag is updated once at interface startup and at each performance interval. For example, the value for the Scan Class Information tag for an interface with three scan class of 5 seconds, 10 seconds and 60 seconds is , 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. PI Interface Configuration Utility 47

52 Using PI ICU IO Rate (events per second) [UI_IORATE] Counts number of all values (inputs, outputs, triggered inputs) being sent to PI before exception processing occurs. This tag will update based on the update rate of the heartbeat tag and may report zero for update intervals where no data was sent to PI. If the value stops updating in PI 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 tag 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 tag events sent to PI before exception processing. Output tags update based on an event and cannot be scheduled for an update rate. Therefore, the values of Output tags are updated at the same rate as the heartbeat tag and reset after the performance summary interval. Note: If no output points are defined, the digital state value of No Data will be written to the point. Output Bad Value Rate [UI_OUTPUTBVRATE] Counts output tag events sent to PI (before exception processing) with status other than 'good'. Output tags update based on an event and cannot be scheduled for an update rate. The value is updated at the same rate as the heartbeat tag 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. Trigger Input Rate [UI_TRIGGERRATE] Counts number of triggered input tag events that are sent to PI before exception processing. Triggered input tags update based on some event and cannot be scheduled for an update rate. Therefore, the value of these tags will be updated at the same rate as the heartbeat tag 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. 48

53 (UniInt) Health Points Trigger Input Bad Value Rate [UI_TRIGGERBVRATE]] Counts triggered input tag events sent to PI (before exception processing) with status anything other than 'good'. Triggered input tags update based on an event and cannot be scheduled for an update rate. The value is updated at the same rate as the heartbeat tag, 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 Tags Unless otherwise stated in the description of the tag, a scan class health tag will receive the system digital state "No Data" if a scan class is defined and a scan class health tag for the class is loaded by the interface but there are no interface points loaded for the scan class. For tags configured to monitor a particular scan class, the PI tag 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 startup parameter. Scan Class IO Rate [UI_SCIORATE] Shows the health of input tags defined for a particular scan class. The tag indicates the number of events sent to PI before exception processing for the given scan class. As long as the current value of the tag is between zero and the scan class point count inclusive, then the scan class update executed successfully. If the Scan Class IORate Tag stops updating in PI, an error has occurred and the tags for that scan class are no longer receiving new data. The value of this tag is updated after the completion of each scan. Scan Class Bad Value Rate [UI_SCBVRATE] Calculates the number of values sent to PI (before exception processing from the device) with a status other than 'good'. This tag can be defined for each scan class and is used for all input tags in that particular scan class. Scan Class Scan Count [UI_SCSCANCOUNT] Tracks of the number of scans that were performed by the interface since the last reporting period. The value of this tag is incremented after the completion of every scan. The value of the tag 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. PI Interface Configuration Utility 49

54 Using PI ICU Scan Class Point Count [UI_SCPOINTCOUNT] The number of tags loaded by the interface for a particular scan class. The value of this tag 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 tag. Scan Class Scan Time [UI_SCINSCANTIME] The total amount of elapsed time in milliseconds to read data from the foreign device, populate the input tags, and then send the data to PI. The value for this tag 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 tags. 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. If the Scan Class Skipped tag value is increasing, the Scan Time tags along with the Device Scan Time tags 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. Interface Page The Interface page will display either: An interface specific 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. Interface-Specific 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. For details on how to use an interface-specific PI ICU Control, please see the manual for the interface being configured. To see whether a particular interface has a PI ICU control, see the PI ICU Controls link on the ( =45EB82FC-C7E7-49EE-B59D-13BC67EAA41B&posting_guid=FA6362B4-348D-42BB- A524-E47356A27BDF) web site. 50

55 Interface Page The example below shows the PI ICU Control for the PItoPI Interface that writes to host PI Server dragon. 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. The Additional Parameters text box allows you to enter parameters that may be required by the interface that is being configured (in standard interface command line format). Parameters should be entered into this text box in standard PI interface command line format. For example: /arg1=value1 /arg2 /arg3=value3 PI Interface Configuration Utility 51

56 Using PI ICU 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. Service Configuration Options Service name The Service name box shows the name of the current interface service. This service name is obtained from the interface executable. The Service ID text box 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 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 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 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 This text box allows users to set what user account the interface service will use. If this text box is left blank, then LocalSystem is used. 52

57 Service Page Password / Confirm password If the username specified in the Log on as text box requires a password, this field is where the password should be typed. 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 text box. Installed Services and Dependencies Installed services provides a list of the services currently installed on this machine. Services upon which this interface is dependant 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. 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 two dependencies that PI ICU provides assistance with: bufserv and tcpip. PI ICU checks to see if bufserv is installed as a Windows service and is enabled. If bufserv is installed as a service and is enabled, then PI ICU puts bufserv in the dependency list for the user before the service is created. If bufserv is installed as a service and is enabled and the service already exists without a dependency on bufserv, PI ICU prompts the user whether to add bufserv 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 may indicate the cause for any server not running as expected. PI Interface Configuration Utility 53

58 Using PI ICU Service Startup Type The Service Startup Type indicates whether the interface service will start automatically or need to be started manually on reboot. Typically, interface services are set to start automatically. 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. Create / Remove Interface Service 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 grayed out. Start or Stop a Service 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 grayed out until the service is added. The status of the interface service is indicated in the lower portion of the PI ICU dialog box. 54

59 IO Rate Page IO Rate Page The IO Rate page allows users to create, edit and delete the IO Rate Tag. 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 I/O Rate tag to be configured for each copy of the interface that is in use. Some interfaces allow for multiple I/O Rates tags. Enable IORates for this interface The Enable IORates for this interface check box enables or disables IORates for the current interface. To disable IORates for the selected interface, uncheck this box. To enable IORates for the selected interface, check this box. Buttons are provided for tasks on the IO Rate page: Click Create/Edit to create the IO Rate tag or to save the new Event Counter. Click Delete to delete a tag. Click Reset to reset the IO Rate configuration as PI ICU suggests. Click Rename to specify a new name for the selected tag. Click Add to File to add the tag 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 IORates tag. Click Refresh Snapshots to update the Snapshot. PI Interface Configuration Utility 55

60 Using PI ICU Event Counter The Event Counter correlates a tag specified in the IORates.dat file with this copy of the interface. The command line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the IORates.dat file. Tagname The Tagname indicates the name of the IORates tag. Tag Status The Tag Status indicates whether the IORates tag exists in PI. The possible states are: 'Created' - Indicates that the tag does exist 'Not Created' - Indicates that the tag does not exist 'Deleted' - Indicates that a tag existed, but was just deleted by the user 'Unknown' - This status indicates that the ICU is not able to access the PI Server In File The In File indicates whether the IORates tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are: Yes - This status indicates that the tag name and event counter are in the IORates.dat file No - This status indicates that the tag name and event counter are not in the IORates.dat file Snapshot If the IORates tag exists, the snapshot is displayed in the Snapshot column. 56

61 Interface Status Page Interface Status Page The ISU (Interface Status Utility) page allows users to create, edit and delete the Interface Status Utility Tag. Interface Status Utility Instance Information The Interface Status Utility Instance Information section displays information on the instance of the Interface Status Utility that is configured for the server the current interface writes to. PI Interface Configuration Utility 57

62 Using PI ICU 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 tag definition. The Interface Status Tag is the name of the tag that belongs to the Interface Status Utility for each interface. Right-click and choose a menu option to work with Interface Status tags: Choose Create to create a tag. Choose Delete to delete a selected tag. Choose Correct to correct a selected tag. Choose Rename to specify a new name for a tag. Choose Suggest Tagname to add a tag name with the default naming convention. Choose Tag Search to search the PI Server for a previously defined tag. Choose Refresh Snapshots to update the Snapshot of the ISU point. Watchdog tag The Watchdog tag is a tag that belongs to the current interface. UniInt and later supports a Heartbeat point, which is configured on the Health Points page. Although any tag may be used, this Heartbeat point is recommended to use as a watchdog tag. Click the Tag Search button to search for a tag that belongs to the current interface as the watchdog tag. The SDK Tag Search dialog box displayed will be connected to the Host PI Server. Search for the tag belonging to this interface that will act as the watch dog tag, select it, and click OK. PI Interface Status monitors a watchdog tag to determine the status of the monitored interface. When choosing an interface watchdog tag, several things should be taken into consideration: The interface watchdog tag's scan rate should reflect the scan rate of the majority of the monitored interface's tags. For example, if the majority of the monitored interface's tags have a scan rate of 10 seconds, the interface watchdog tag should have a scan rate of 10 seconds. The interface watchdog tag's scan rate should be slightly more frequent than the monitor frequency (location4) of the PI Interface Status tag. For example, if you want PI Interface Status to monitor an interface every 1 minute, its interface watchdog tag should be updating around every 30 seconds. 58

63 Interface Status Page The monitor frequency of the PI Interface Status tag should depend upon the scan rates of the monitored interface's tags. A monitor frequency that's a little less frequent than the majority of the scan rates for the monitored interface's tags should be chosen. For example, an interface with most of its tags scanning every 30 seconds could have a monitor frequency of 1 minute. An interface with most of its tags scanning every second could have a monitor frequency of 10 seconds. 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 tag 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 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 the Location2 parameter is not equal to 0. It defines ISU behavior when communication resumes. This parameter has three possible values: 0 - Remove system digital state written by ISU. 1 - Do not remove system digital state written by ISU. 2 - Remove system digital state written by ISU if archive value present. PI Interface Configuration Utility 59

64

65 Chapter 4 Menu Commands The following sections describe menu commands used in PI ICU. Interface Menu The Interface menu includes the following items: New Windows Interface Instance from EXE... The New Windows Interface Instance from EXE option opens a 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. Browse to interface executable (required) Use the Browse button to select the desired interface executable file. PI Interface Configuration Utility 61

66 Menu Commands Host PI 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 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 on the 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 tags 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 # The ID number used to distinguish tags belonging to this interface from other tags 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. 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. 62

67 Interface Menu 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 PI ICU. Note: Once an interface has been loaded by 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: Add or select the correct server. Click Cancel to cancel the import. PI Interface Configuration Utility 63

68 Menu Commands 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 ICU. 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 tags belonging to this interface from other tags 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. 64

69 Interface Menu 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 tag 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 65

70 Menu Commands SDK Connections... Displays the PI Connections Manager. Connect to Primary Connect to Primary is used to attempt to reconnect to the Primary. Under normal operation, the ICU will detect that the Primary is available again and automatically connect to the Primary server. However, under certain circumstances, the ICU may not be aware that the Primary is available again, and this menu option tells the ICU to attempt to connect to the Primary. This option is enabled only when connected to a member of a collective that is not the Primary. 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. 66

71 Tools Menu Start Interactive 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. 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 The Tools menu items include the following items: PI Interface Configuration Utility 67

72 Menu Commands 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. 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 button displays a Command Window into which all messages written to PIPC.Log are displayed as they are written to PIPC.Log. 68

73 Tools Menu PIPC Log Server page Service 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. Service 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 reboots. If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service. If the Disabled option is selected, the service will not start at all. Generally, 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, specify a value in Kilobytes in the text box provided. The default is 256 KB. The range is 1KB to 4MB. PI Interface Configuration Utility 69

74 Menu Commands Buffering... 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) The Buffer Subsystem is a new component 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. The buffer subsystem buffers data only to one nonreplicated PI server or one collective PI server (with its various member nodes). The buffer subsystem works with PI and later PI servers, but cannot run on the PI server itself. Note: Only one Buffer can be enabled on a machine at any time. If the Buffering dialog detects that both buffers are enabled, an error message is displayed. 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

75 Tools Menu 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. The Help button is enabled if PI ICU is able to locate the PI Buffer Subsystem help file (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 Settings page provides configuration settings for API Buffer Server and PI Buffer Subsystems. Only the options that apply to the buffer service currently selected on the Configured Buffer 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. 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. PI Interface Configuration Utility 71

76 Menu Commands TCP/IP Port The TCP/IP port for PI server communication, set by default to Maximum buffer file size (KB) Maximum buffer file size in kilobytes before buffering fails and discards events. The default value is 100,000, with a range of 1 to 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 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 to Send rate (milliseconds) Sendrate 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 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 Retry rate (seconds) 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 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 1 to Max theoretical send rate The theoretical max send rate, calculated as max = MAXTRANSFEROBJS / SENDRATE * The default value is 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 0 to MB. Event queue path The directory path to the event queue files. The default is PIHOME\DAT. 72

77 Tools Menu 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 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 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 ICU dialog in the API Hostname drop down box. The BUFFEREDSERVERLIST and REPLICATEDSERVERLIST sections of the PIHOME\dat\piclient.ini file API Buffer Server 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. PI Interface Configuration Utility 73

78 Menu Commands Buffered Data written to a server will be buffered if the Buffered column for the server is marked 'Yes'. 'No' means 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. PI Buffer Subsystem Servers The HA release of the PI Buffer Subsystem can be configure to buffer data to one server or to any number of members of a single collective. 74

79 Tools Menu 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 PI Buffer Subsystem Service The PI Buffer Subsystem Service page is used to configure and run the 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. PI Interface Configuration Utility 75

80 Menu Commands 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 The Dependencies lists the Windows services on which the PI Buffer Subsystem service is dependent. Dependent Services The dependent services list shows all 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. 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. 76

81 Tools Menu Parameter Details The Parameter Details page for the PI Buffer Subsystem includes detailed information about each of the parameters that the PI Buffer Subsystem uses for buffering data. PI Interface Configuration Utility 77

82 Menu Commands API Buffer Server Service The API Buffer Server Service page is used to configure and run the API Buffer Server (Bufserv), if selected. API Buffer Server version 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 This 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. 78

83 Tools Menu 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 reboots. If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service. If the Disabled option is selected, the service will not start at all. Generally, the PI Buffer Server service is set to start automatically. 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. PI Interface Configuration Utility 79

84 Menu Commands Tools There are two choices under the Buffering Tools menu API Buffer Server or PI Buffer Subsystem. Use the appropriate one depending on which buffering system you have selected. 80

85 Tools Menu 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 windows will appear with the Bufutil menu. Enter the number of the menu item you wish to look at and hit return. PI Interface Configuration Utility 81

86 Menu Commands 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. 82

87 Tools Menu 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 Interface Full Name Interface binary (including path) Interface Description Interface Version UniInt-based flag UniInt version Interface Installation path Host PI Server information Local PI SDK version Local PI API version Interface Service Information IORates tag information Contents of the local IORates.dat file Performance Points information Performance Counter Points (Performance Monitor Points) information UniInt Health Points Control Program status PILogSrv Service Information Local pipc.ini file Bufserv Service Information Local Buffering settings from PIClient.ini Entire PIClient.ini file Local PILogin.ini settings PI Interface Configuration Utility 83

88 Menu Commands 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. 84

89 Tools Menu 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. 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 to run the tag creation utility. For details on each individual interface's tag creation utility, 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. PI Interface Configuration Utility 85

90 Menu Commands Options The Options dialog box has seven choices. Four apply generally to all interfaces: Loading (page 86) Naming Conventions (page 87) Debug (page 88) Reserved Point Sources (page 88) Three apply only to the currently selected interface and are inactive until an interface is selected: Services (page 88).BAT Files (page 89) Warnings (page 91) 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

91 Tools Menu Naming Conventions Use the 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. Interface Point Naming Convention 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 Rates Points Interface Status Utility Points UniInt Performance Points and UniInt Health Points Performance Counter Points 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 PI Interface Configuration Utility 87

92 Menu Commands Debug Debug messages can be logged to the pipc.log file during ICU startup, during Import of configuration (.bat) files and during creation of new interface instances. These messages help determine where ICU is spending its time when startup is slow 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 ICU is configured to load interfaces. The reserved Point Source can be changed for any of the listed types. 88

93 Tools Menu 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 The Interface Service Display Name Naming Convention is used by 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. PI Interface Configuration Utility 89

94 Menu Commands.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. 90

95 Tools Menu 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 ICU. The warnings can be reactivated by clearing the respective check boxes. PI Interface Configuration Utility 91

96

97 Chapter 5 Installation The PI Interface Configuration Utility uses the Microsoft Windows Installer technology for installation. Install PI ICU To install, run the PIICUSetup_X.X.X.X.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 PI ICU installation will install the following files: ο ο ο ο ο ο ο ο ο ο ο 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 PIAPSRegisterInterface.dll: Library used by PI ICU and PI APS to register interfaces with PI ICU and PI APS PI Interface Configuration Utility.pdf, this manual. WatchLog.exe, Log Files program to watch the PIPC.log file continuously from within PI ICU. The PI ICU help file is installed to PIHOME\Help: PIInterfaceConfigurationUtility.chm: PI ICU Help file PI Interface Configuration Utility 93

98 Installation The following files are installed: PIHOME\ Help\ Library\ ICU\ PIInterfaceConfigurationUtility.chm PISpt.dll OSIsoft.PISpt.dll PIGenericNames.dll OSIsoft.PIGenericNames.dll PIAPSRegisterInterface.dll PI Interface Configuration Utility.pdf PI-ICU.exe PIICU_ReleaseNotes.htm Watchlog.exe A PI Interface Configuration Utility shortcut is added to Start > Program Files > PI System. Uninstall PI ICU There are two methods that can be used to uninstall PI ICU: Run the Add or Remove Programs applet (Start Menu > Settings > Control Panel > Add or Remove Programs) and remove the PI Interface Configuration Utility. Extract the files from PIICUSetup_X.X.X.X.exe to a temporary directory with WinZip, and run the following command line: setup.exe /u to uninstall the following 3 programs: ο ο ο PI GenericNames PI Interface Configuration Utility PI Spt The PI Software Development Kit (PI SDK) may have been installed by PI ICU, but may have been installed prior to the PI ICU installation. Remove it at your discretion using the Add-Remove Programs applet (Start Menu > Settings > Control Panel > Add or Remove Programs). 94

99 Chapter 6 Migration Interfaces are often configured by writing to a test PI server, and then moved to a production PI server when they are ready. The ICU stores interface information (startup command line, for example) in the Module Database of the PI server to which an interface writes. To move an interface from one PI server to another: 1. Change the Server/Collective to which an interface belongs on the General page of the ICU: If the Server/Collective drop-down box is disabled, or if the name of the new PI server is not in the Server/Collective drop-down box, continue through the following steps: 2. Verify that the new PI server exists in the Connections dialog box (Interface > SDK Connections). 3. Verify that the ICU Loading settings are set properly (Tools > Options > Loading). Load interfaces from all known PI servers or from a selected list of PI servers. If you load from a selected list of PI servers, make sure that both the old server and the new server are checked. Click OK to save and close the dialog box. The ICU will reload interfaces. PI Interface Configuration Utility 95

100 Migration 4. Load the interface you want to move from one PI server to another, and select the new PI server in the Host drop-down box. The interface is moved to the new PI server. This means that the interface entry in the old PI server's Module Database is removed and is added to the new PI server's Module Database. During the move, the ICU status bar at the bottom of the ICU displays progress, and when complete, the status bar reads Ready. 96

101 Chapter 7 Troubleshooting The following topics describe common troubleshooting issues. 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. The required support DLL PIGenericNames.dll is not present or not registered This error indicates that the PIPC\Library\PIGenericNames.dll file is either not installed, missing or unregistered. To register the file, open a Command Prompt, 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 either not installed, missing or unregistered. To register the file, open a Command Prompt, change directories to the PIPC\Library directory, and type in the following command: Regsvr32 PISpt.dll PI Interface Configuration Utility 97

102 Troubleshooting The PI SDK version is older than the required version PI ICU requires PI SDK or later on the machine on which PI ICU is to run. If the SDK version is older, it must be upgraded. Error 713 attempting to load the ICU Control This error indicates that the ICU Control has been registered on this machine, but the physical file has been moved or deleted. To fix this problem, re-install the ICU Control for the interface type. Error 450 attempting to load the ICU Control This error indicates that the 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 ICU Control version is inappropriate for the version of the PI ICU running on this machine. The ICU Control user manual should indicate which version(s) of the ICU Control are compatible with which versions of PI ICU. Error 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 dropdown 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 dropdown 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. ICU Control is on machine, but does not show up in ICU This usually indicates that the ICU control has not been registered. The setup kit for a particular ICU control will attempt to register the ICU control. To manually register an ICU control, open a Command Prompt, change directories to the PIPC\ICU\<ICU Control Directory> directory, and type in the following command: Regsvr32 <ICU Control dll or ocx Name> 98