PI Interface for Citect
Version 3.0.4.x
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web:
OSIsoft Australia • Perth, Australia
OSIsoft Europe GmbH • Frankfurt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoft Canada ULC • Montreal & Calgary, Canada
OSIsoft, LLC 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 BrasilSistemas Ltda. • Sao Paulo, Brazil
OSIsoft France EURL • Paris, France
PI Interface for Citect
Copyright: © 1997-2013 OSIsoft, LLC. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework (PI AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Coresight, PI Data Services, PI Event Frames, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 09/2013
Table of Contents
Chapter 1.Introduction
Reference Manuals
Supported Operating Systems
Supported Features
Diagram of Hardware Connection
Chapter 2.Upgrading from Version 2.x to 3.x
Location1
Location2
Command line Parameter Changes
UniInt Failover Changes
Chapter 3.Principles of Operation
Input Points
Scan-based
Event-based
Output Points
Chapter 4.Installation Checklist
Data Collection Steps
Interface Diagnostics
Advanced Interface Features
Chapter 5.Interface Installation
Naming Conventions and Requirements
Interface Directories
PIHOME Directory Tree
Interface Installation Directory
Interface Installation Procedure
Installing the Citect API DLL files
Installing Interface as a Windows Service
Installing Interface Service with PIInterfaceConfigurationUtility
Service Configuration
Installing Interface Service Manually
Chapter 5.Communication Test Programs
Testing the Connection to Citect
Connecting to Citect
Reading Points
Writing Points
Chapter 6.Digital States
Chapter 7.PointSource
Chapter 8.PI Point Configuration
Point Attributes
Tag
PointSource
PointType
Location1
Location2
Location3
Location4
Location5
InstrumentTag
ExDesc
Scan
Shutdown
Output Points
Trigger Method 1 (Recommended)
Trigger Method 2
Chapter 9.Startup Command File
Configuring the Interface with PI ICU
Citect Interface Page
General Tab
Debug Tab
Command-line Parameters
Sample PICitect.bat File
Chapter 10.UniInt Failover Configuration
Introduction
Quick Overview
Synchronization through a Shared File (Phase 2)
Configuring Synchronization through a Shared File (Phase 2)
Configuring UniInt Failover through a Shared File (Phase 2)
Start-Up Parameters
Failover Control Points
PI Tags
Detailed Explanation of Synchronization through a Shared File (Phase2)
Steady State Operation
Failover Configuration Using PI ICU
Create the Interface Instance with PI ICU
Configuring the UniInt Failover Startup Parameters with PIICU
Creating the Failover State Digital State Set
Using the PI ICU Utility to create Digital State Set
Using the PI SMT 3 Utility to create Digital State Set
Creating the UniInt Failover Control and Failover State Tags (Phase 2)
Chapter 11.Interface Node Clock
Chapter 12.Security
Windows
Chapter 13.Starting / Stopping the Interface
Starting Interface as a Service
Stopping Interface Running as a Service
Chapter 14.Buffering
Which Buffering Application to Use
How Buffering Works
Buffering and PI Server Security
Enabling Buffering on an Interface Node with the ICU
Choose Buffer Type
Buffering Settings
Buffered Servers
Installing Buffering as a Service
Chapter 15.Interface Diagnostics Configuration
Scan Class Performance Points
Performance Counters Points
Performance Counters
Performance Counters for both (_Total) and (Scan Class x)
Performance Counters for (_Total) only
Performance Counters for (Scan Class x) only
Interface Health Monitoring Points
I/O Rate Point
Interface Status Point
Appendix A.Error and Informational Messages
Message Logs
Fatal Errors
Serious Errors
Point Errors
Warnings
System Errors and PI Errors
UniInt Failover Specific Error Messages
Informational
Errors (Phase 1 & 2)
Errors (Phase 2)
Appendix B.Point Builder Utility
Configuration Tab
Digital Sets Tab
Point Builder Tab
Appendix C.PI SDK Options
Appendix D.Terminology
Appendix E.Technical Support and Resources
Appendix F.Revision History
PI Interface for Citect1
Chapter 1.Introduction
The PI Citect Interface provides communication between PI and Citect. It is based on a version of the OSIsoft standard Universal Interface (UniInt), adapted for the Citect environment.
Data is transferred between Citect and PI via the Citect application programming interface (CTAPI) and the PI API. The interface runs on Microsoft Windows XP operating systems, or greater.
The interface supports input tags (from Citect to PI) and output tags (from PI to Citect). Data from Citect is received at cyclic frequencies or by exception in the data. The frequency of the cycles is configured by the user and controlled by the interface. The number of tags that the interface is capable of servicing is limited only by external limitations, for example, the amount of available memory in the computer and the load on the Citect IO server.
Changes that are made to the PI point database are reflected in the interface. This includes the adding, editing and deleting of tags.
All error information and some summary information are output to a log file. If the interface is run interactively from an MS-DOS prompt, then the output is displayed on the screen. The amount of summary information that is output is configurable by the user and is minimal by default. For information about configuring information messages, see/df in the Command-line Parameters section.
For the interface to be able to connect to the Citect database, the Citect node must have sufficient API licenses available. The number of Citect licenses available is shown in the “General” window of the “Citect Kernel” utility. Note that with earlier versions of Citect (before 5.40), Citect included 2 API licenses by default. As of version 5.40, the Citect API licenses (also known as Connection licenses) must be explicitly included.
Citect Clusters
Starting with Citect version 7.0 all servers need to be assigned to a Citect cluster. When referencing Citect points (see the InstrumentTag attribute), the Citect point name can be prefixed with the cluster name, i.e. “<cluster name>.<point name>”. If only one Citect cluster is defined on site, the use of the Cluster prefix is optional. If multiple clusters are defined in an environment, the cluster prefix must be specified.
Each instance of the PI Citect interface can connect to only one Citect Server regardless of whether the server is a clustered server or not. To connect to a pair of Citect servers in a Reliable Clustering configuration, two interface instances configured in failover mode are required. Both servers must be located in the same Operational or Ad-Hoc Cluster.
Note:Throughout this manual there are references to where messages are written by the interface which is the PIPC.log. This interface has been built against a UniIntversion (4.5.0.59 and later) which now writes all its messages to the local PI Message log.
Please note that any place in this manual where it references PIPC.log should now refer to the local PI message log. Please see the document UniInt Interface Message Logging.docx in the %PIHOME%\Interfaces\UniInt directory for more details on how to access these messages.
Reference Manuals
OSIsoft
- PI Server manuals
- PI API Installation Instructionsmanual
- UniInt Interface User Manual
Vendor
- Citect Users Guide Version 5 or later
- Citect Getting Started
Supported Operating Systems
Platforms / 32-bit application / 64-bit applicationWindows XP / 32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / No
Windows 2003 Server / 32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / No
Windows Vista / 32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / No
Windows 2008 / 32-bit OS / Yes / No
Windows 2008 R2 / 64-bit OS / Yes (Emulation Mode) / No
Windows 7 / 32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / No
Windows 8 / 32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / No
Windows 2012 / 64-bit OS / Yes (Emulation Mode) / No
The interface is designed to run on the above mentioned Microsoft Windows operating systems and their associated service packs.
The interface is designed to run on the above-mentioned Microsoft Windows operating systems. Because it is dependent on vendor software, newer platforms may not yet be supported.
Please contact OSIsoft Technical Support for more information.
Supported Features
Feature / SupportInterface Part Number / PI-IN-CI-CITEC-NTI
Auto Creates PI Points / No
Point Builder Utility / Yes
ICU Control / Yes
PI Point Types / real / digital / integer / string
Sub-second Timestamps / Yes
Sub-second Scan Classes / Yes
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / Yes
Inputs to PI: / Scan-based/Event Tags
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / Unlimited
* Uses PI SDK / No
PINet String Support / N/A
* Source of Timestamps / PI Interface
History Recovery / No
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes
* Failover / UniInt Failover (Phase 2); Cold, Warm and Hot
* Vendor Software Required on Interface Node / PINet Node / Yes
Vendor Software Required on Foreign Device / Yes
Vendor Hardware Required / No
Additional PI Software Included with interface / Yes
Device Point Types
Serial-Based interface / No
* See paragraphs below for further explanation.
Source of Timestamps
Timestamps are generated within the interface. If the scan class is sub-second, then sub-second timestamps will be used.
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoftdeveloped template used by developers and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniIntsupplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.
The UniInt Interface User Manual is a supplement to this manual.
Disconnected Start-Up
The PICitectinterface is built with a version of UniInt that supports disconnected start-up. Disconnected start-up is the ability to start the interfacewithout a connection to the PI Server. This functionality is enabled by adding /cachemode to the list of start-up parameters or by enabling disconnected startup using the ICU. Refer to the UniInt Interface User Manual for more details on UniInt disconnected startup.
SetDeviceStatus
The PI Citect Interface is built with UniInt 4.5.4.0 New functionality has been added to support health tags. The Health tag with the point attributeExdesc = [UI_DEVSTAT], is used to represent the status of the connection to the Citect system. The following events can be written into the tag:
- “1 | Starting” - the interface is starting
- “2 | Connected/No Data” - the interface is part of a failover pair and is not currently active.
- “3 | 1 device(s) in error | Not connected to Citect” - the interface is unable to connect to the Citect system.
- “Good” - the interface is scanning the Citect system for data.
- “4 | Intf Shutdown” – interface has shutdown.
Refer to the UniInt Interface User Manual.doc file for more information about how to configure health points.
Failover
- UniInt Failover Support
UniInt Phase 2 Failover provides support for cold, warm orhot failover configurations. The Phase 2 hot failover results in a no data loss solution for bi-directional data transfer between the PI Server and the Data Source given a single point of failure in the system architecture similar to Phase 1. However, in warm and cold failover configurations, you can expect a small period of data loss during a single point of failure transition. This failover solution requires that two copies of the interface be installed on different interfacenodes collecting data simultaneously from a single data source.Phase 2 Failover requires each interface have access to a shared data file. Failover operation is automatic and operates with no user interaction. Each interface participating in failover has the ability to monitor and determine liveliness and failover status. To assist in administering system operations, the ability to manually trigger failover to a desired interface is also supported by the failover scheme.
The failover scheme is described in detail in the UniInt Interface User Manual, which is a supplement to this manual. Details for configuring this interface to use failover are described in the UniInt Failover Configuration section of this manual.
Vendor Software Requiredon PI Interface Node
The interface requires that the PI API and Citect API be installed on the PI Interface node. The PI API version must be at least 1.6.x.x.
The Citect API consists of a set of DLL files, which should be copied from the Citect machine onto the PI Interface node.
These files are (and must be copied into the folder where the PI_Citect.exe is located):
- CtApi.dll
- CtEng32.dll
- CiDebugHelp.dll
- CtRes32.dll
- CtUtil32.dll
- Ct_ipc.dll
It is recommended that the version of the Citect API DLL files used be the same as the version of the Citect system it is connecting to.
Note: Version 3.0.2.x of thr PI-Citect interface was built in such a way that the interface required the Citect 7.2 DLLs. This limitation has been removed with version 3.0.4.x or later.
Vendor Software Required on Foreign Device
The interface requires that Citect API licenses are available on the Citect system. If the Citect system does not have an API license available, the connection request from the interface will be rejected by the Citect node.
Additional PI Software
A test utility called “PI_CitectTest.exe” is included with the interface. This can be used to ensure that the machine running the interface can connect successfully to the Citect node and read values from the Citect real-time database.
Diagram of Hardware Connection
There are several options for how the PI Citect interface is run.
If the Citect host node is not heavily loaded then option 1, where the PI Citect interface and the PI API software are run directly on the Citect node is the recommended approach. It has the advantage of the interface running locally on the Citect node and so eliminates a network connection, but also supports buffering for when there are network or PI Server problems.
Option 2 also supports buffering; nevertheless, access to Citect is required including an additional computer. This configuration is well suited for situations where the Citect node is heavily loaded. It is also useful when several Citect nodes are to be scanned, as several copies of the Citect interface can run on the same PI Interface node.
With option 3 the interface runs directly on the PI Server. This is simple to install; however, it lacks any buffering and therefore it is not the recommended approach.
PI Interface for Citect1
Chapter 2.Upgrading from Version 2.x to 3.x
Version 3.x represents some important and big changes to functionality and the features of the PI Citect interface. The most significant change is that point attribute Location1 now describes the interface ID and Location2 now describes if the point is an input or an output point. (Location1 and Location2 point attributes have been reversed.) You will need to edit all points for this interface to accommodate these changes. Make sure you do these point edits before implementing ICU changes.
Location1
Location1 indicates to which copy of the interface the point belongs. The value of this attribute must match the /id command-line parameter.
Location2
This field is used to specify whether a PI tag is an input tag (from Citect to PI) or an output tag (from PI to Citect).
- 0 – Input tag
- 1 – Output tag
You can use multiple methods like PI Tag configurator to edit the tags. Provided is a piconfig.exe utility example that will be available on every installation of the PI server. To quickly edit all the tags for the PI Citect Interface you can use this piconfig.exe script to handle all the changes. It works by exporting the Location1 and Location2 information for all the tags with Citect as the pointsource. Then it edits all the tags to the new format.
Open a command prompt and navigate to the pi server adm folder found at
C:\Program File\pi\adm run the piconfig.exe utility and enter this script (Replace the Citect pointsource with the pointsource of your 1itect tags.)
@table pipoint,classic
@mode list
@ostr tag,location2,location1
@select tag=*
@select pointsource=Citect
@outp locationswitch.csv
@ends
This will generate a locationswitch.csv file in the PI/adm directory. Check this list because all the tags here will be edited to reflect the location 1 and 2 changes. If you only want to edit an instance of the interface you’ll need to add another select statement to reflect this, i.e. @select location2=5 (with 5 being the designated interface instance id to change).
Once the file gets generated, the following script needs to be run to modify the tags.
piconfig
@table pipoint,classic
@mode edit
@istr tag,location1,location2
@input locationswitch.csv
@ends
Command line Parameter Changes
Obsolete Parameters
/ihost
/imode
/itag
/nopiwrite
/onlockup
/restartutil
/servicename
/wto
New Parameters
/CitectTS
/ReconnectRate
/citectdelay
/UsePIAPI
/V2
Optional UniInt phase 2 failover parameters
UniInt Failover Changes
The next big change is the deprecation of the interface specific failover which is replaced by UniInt Phase 2 (Hot, Warm and Cold) Failover. All interface specific failover command line parameters should be removed (if left they will be ignored). The ICU will handle this for you or you can do it yourself by editing the interface’s .bat file. That includes /ihost /imode /itag /nopiwrite /onlockup /restartutil /servicename and /wto. In order to continue using failover you will need to refer to the UniInt Failover Configuration chapter to add the appropriate command line parameters, set up the shared file and two interfaces to support UniInt Failover.