PI Citect

Citect Interface to the PI System
Version 2.6.2.9 Revision I
How to Contact Us
OSIsoft, Inc.
777 Davis St., Suite 250 San Leandro, CA 94577 USA
Worldwide Offices OSIsoft Australia

Perth, Australia Auckland, New Zealand
Telephone
(01) 510-297-5800 (main phone) (01) 510-357-8136 (fax) (01) 510-297-5828 (support phone) techsupport@osisoft.com Houston, TX Johnson City, TN Mayfield Heights, OH Phoenix, AZ Savannah, GA Seattle, WA Yardley, PA
OSI Software GmbH

Altenstadt, Germany
OSI Software Asia Pte Ltd.

Singapore
OSIsoft Canada ULC

Montreal, Canada
OSIsoft, Inc. Representative Office

Shanghai, Peoples Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.

Mexico City, Mexico
Sales Outlets and Distributors

Brazil Middle East/North Africa Republic of South Africa Russia/Central Asia South America/Caribbean Southeast Asia South Korea Taiwan
WWW.OSISOFT.COM
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such partys products or any affiliation with such party of any kind. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 Unpublished rights reserved under the copyright laws of the United States. 1997-2008 OSIsoft, Inc. PI_Citect.doc
Table of Contents
Introduction....................................................................................................................1 Reference Manuals..................................................................................................................1 Supported Features.................................................................................................................2 Diagram of Hardware Connection............................................................................................5 Principles of Operation.................................................................................................8 Input Points..............................................................................................................................8 Output Points...........................................................................................................................8 Installation Checklist...................................................................................................10 Interface Installation....................................................................................................11 Naming Conventions and Requirements...............................................................................11 Interface Directories...............................................................................................................11 The PIHOME Directory Tree..............................................................................................11 Interface Installation Directory............................................................................................12 Interface Installation Procedure.............................................................................................12 Installing the Citect API DLL files...........................................................................................12 Installing the Interface as an Windows Service.....................................................................13 Installing the Interface Service with PI Interface Configuration Utility................................13 Installing the Interface Service Manually............................................................................16 Communication Test Programs..................................................................................17 Testing the Connection to PI..................................................................................................17 Testing the Connection to Citect............................................................................................17 Connecting to Citect...........................................................................................................17 Reading Points...................................................................................................................18 Writing Points.....................................................................................................................18 Digital States................................................................................................................20 Interface Status Tag...............................................................................................................20 PI Point Configuration.................................................................................................23 Point Attributes.......................................................................................................................23
iii
Table of Contents Tag.....................................................................................................................................23 PointSource........................................................................................................................23 PointType...........................................................................................................................23 Location1............................................................................................................................23 Location2............................................................................................................................24 Location3............................................................................................................................24 Location4............................................................................................................................24 Location5............................................................................................................................24 InstrumentTag....................................................................................................................24 ExcDesc.............................................................................................................................25 Scan ..................................................................................................................................25 Zero/Span..........................................................................................................................26 Shutdown...........................................................................................................................26 Output Points.........................................................................................................................27 Trigger Method 1 (Recommended)...................................................................................27 Trigger Method 2................................................................................................................27 Performance Point Configuration...............................................................................28 Configuring Performance Points with PI ICU (Windows).......................................................28 Configuring Performance Points Manually.............................................................................29 I/O Rate Tag Configuration..........................................................................................30 Monitoring I/O Rates on the Interface Node..........................................................................30 Configuring I/O Rate Tags with PI ICU (Windows).................................................................30 Configuring I/O Rate Points Manually....................................................................................32 Configuring the PI Point on the PI Server..........................................................................32 Configuration on the Interface Node..................................................................................32 Startup Command File.................................................................................................34 Configuring the Interface with PI ICU.....................................................................................34 citect Interface Tab.............................................................................................................36 Command-line Parameters....................................................................................................41 Sample PI_Citect.bat File...................................................................................................46 Interface Failover Configuration.................................................................................47 Examples...............................................................................................................................47 Interface Watchdog Configuration and StartService............................................49 Interface Node Clock...................................................................................................50
iv
Security.........................................................................................................................51 Windows ...............................................................................................................................51 Starting / Stopping the Interface.................................................................................53 Starting Interface as a Service...............................................................................................53 Stopping Interface Running as a Service...............................................................................53 Buffering.......................................................................................................................54 Configuring Buffering with PI ICU (Windows).........................................................................54 Configuring Buffering Manually..............................................................................................57 Example piclient.ini File..........................................................................................................59 Appendix A: Error and Informational Messages.......................................................60 Message Logs........................................................................................................................60 Interface Messages................................................................................................................60 System Errors and PI Errors..................................................................................................61 Appendix B: Point Builder Utility................................................................................63 Configuration Tab...............................................................................................................64 Digital Sets Tab..................................................................................................................67 Point Builder Tab................................................................................................................71 Revision History...........................................................................................................72
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 NT 4.0 (service pack 3) or greater. The interface supports input tags (from Citect to PI) and output tags (from PI to Citect). It counts the events to and from these tags, including exception tests, and sends its totals periodically to PI. 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. 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 the /db and /df headings of the Startup Command File. 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 only connect to one Citect Server regardless 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.
Reference Manuals
OSIsoft
UniInt Interface User Manual PI Data Archive Manual

1
Introduction Vendor Citect Users Guide Version 5 or later Citect Getting Started PI API Installation Instructions PI ICUUserManual.doc
Supported Features
Feature Part Number *Platforms APS Connector Point Builder Utility ICU Control PI Point Types Sub-Second Timestamps Sub-Second Scan Classes Automatically Incorporates PI Point Attribute Changes Exception Reporting Outputs from PI Inputs to PI: Scan-Based / Unsolicited / Event Tags Supports Questionable Bit Supports Multi-character PointSource Maximum Point Count *Uses PI SDK PINet String Support * Source of Timestamps History Recovery * Fail over * UniInt-based Disconnected Startup * Set Device Status * Vendor Software Required on PI Interface Node * Vendor Software Required on Foreign Device Vendor Hardware Required * Additional PI Software Included with Interface Serial Based Interface
2
Support PI-IN-CI-CITEC-NTI Windows NT4, 2000, XP, 2003 No Yes Yes real, digital, integer, string Yes Yes Yes Yes Yes Scan-based / Event Tags No Yes Unlimited No N/A PI Interface No Yes Yes Yes Yes Yes Yes No Yes No
* See paragraphs below for further explanation. Platforms The Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater. For NT4.0 it requires SP3 or greater. Uses PI SDK The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface does not specifically make PI SDK calls. Source of Timestamps Timestamps are generated within the interface. If the scan class is sub-second, then subsecond timestamps will be used. UniInt-based UniInt stands for Universal Interface, and it is an OSIsoft-developed template used to create many of our interfaces. UniInt is not a separate product or file, it is solely a template used by our developers, and is integrated into the interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our interfaces as possible. It also allows for the very rapid development of new interfaces. UniInt is constantly being upgraded with new options and features. In any UniInt interface, UniInt uses some of the supplied configuration parameters, and some parameters are interfacespecific features of the interface. The UniInt Interface User Manual is a supplement to this manual. Set Device Status The PI Citect Interface is built with UniInt 4.3.0.36. New functionality has been added to support health tags. The Health tag with the point attribute Exdesc = [UI_DEVSTAT], is used to represent the status of the connection to the Citect system. The following events can be written into the tag: a) "1 | Starting" - the interface is starting b) "2 | Connected/No Data" - the interface is part of a failover pair and is not currently active. c) " 3 | 1 device(s) in error | Not connected to Citect" - the interface is unable to connect to the Citect system. d) "Good" - the interface is scanning the Citect system for data. e) 4 | Intf Shutdown interface has shutdown. Please refer to the UniInt Interface User Manual.doc file for more information on how to configure health points. Failover This interface supports an interface-specific failover mechanism. The UniInt-based failover is not supported. Two instances of the interface can run to collect data for the same set of PI tags. Using a command-line parameter, one instance is defined as the primary and the other as the secondary. They both may run on the same machine, or on different machines. They use
Citect Interface to the PI System 3
Introduction TCP/IP to coordinate the data collection. Multiple TCP/IP connections between the two interfaces can be used to increase the level of redundancy. When using UniInt health tags with interfaces running in failover, the instances of the interface should be started with the /uht_id=x command-line parameter and the health tags with location3 set to x, so that each instance of the interface will write to a different set of health tags. Vendor Software Required on 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.2.3.4. The version of Citect API client depends on the version of Citect. Version 2.x of the interface has been built for Version 5.1 or later of Citect. The Citect API consists of a set of DLL files, which should be copied from the Citect machine onto the PI Interface node. 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.
Introduction
Option 2 also supports buffering; nevertheless, access to Citect is required including an additional machine. 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.
Option 3 is when the interface is run directly on the PI Server. This is simple to install; however, it lacks any buffering and therefore it is not the recommended approach.
Principles of Operation
When the interface starts up, it receives several parameters from the interface startup file. These parameters define the PI Point Source code, interface id, and the set of Scan Class time periods to be available as well as other parameters as described in the section Startup Command File. Log messages are recorded either in the PI log file or the PI application log file. The PI log file is named PI\PILog\pimsg_yymmdd.dat and is renewed daily. The status of the interface is recorded in the PI application log file PIPC\Dat\pipc.log. The interface begins by searching the PI Point Database for all tags configured with the PointSource code specified in the interface startup file. If the interface identifier (/id=) has been specified as a command-line parameter, then the point configuration is checked to ensure the point has the same interface identifier. It then records these tags in dynamic group structures in the computer memory based on logical groupings (e.g. one list per scan class, per point type). When the interface process has completed these initial tasks, it enters a permanent loop in which it processes input and output tags. This loop is repeated until the interface is stopped. The actions taken within this loop are described below.
Input Points
Input tags are serviced by the interface to collect data from Citect and send it to PI. They can either be scan-based or event-based. Scan-based tags are serviced regularly at a predefined time interval. Event-based tags are serviced when a change occurs in a separate PI tag. Scan-based It is possible to configure an input tag to be updated at a regular time interval specified by any one of a set of user-defined scan classes. The interval of each scan class is based from and controlled by the interface. When a scan classs time interval expires, the data for the tags that are configured for that scan class is requested. All tags for a particular scan class are retrieved from Citect at once. For information about defining scan-based input tags, see the description of /f in the Startup Command File section. Event-based An input tag can be configured to send data to PI on an event, based on the exception of the data from a separate PI point. When the value of this separate PI point changes the data for the actual tag is requested from Citect. For information about setting up an exception tag, see the ExDesc heading of the PI Point Configuration section.
Output Points
Output tags are serviced by the interface to collect data from PI and send it to Citect based on the exception of a separate PI tag (referred to as a source tag). When the value of this source tag changes, it is sent both to Citect and to the output tag. This keeps a record of data that were sent to Citect. For more information about setting up an output tag, see the SourceTag heading in the PI Point Configuration section. If a tag is defined to be an output tag, its settings override any settings that apply to input tags.
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI Citect interface running. If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual in detail. 1. Install the PI Interface Configuration Utility (which installs PI SDK and PI API) 2. Verify that PI API has been installed. 3. Install the interface. 4. Ensure that the Citect API DLL files are installed on the interface node. 5. Ensure that there are sufficient Citect API licenses available on the Citect node. 6. Test the connection between the interface node and the Citect node using the PI_CitectTest.exe connection tester. 7. Define digital states. Cit_Bad_Conn - an indicator of communication problems with the Citect node. If an interface status tag (/itag=) is to be used then a digital set as defined in Interface Status Tag section (page 20) is required. 8. Choose a point source.Configure PI points. Location1 is the input / output parameter (0=input, 1=output). Location2 is the interface identifier. Location3 is not used. Location4 is the scan class. Location5 is not used. ExDesc is optional and used for event driven point scans (EVENT=). InstrumentTag is the Citect point name. 9. Configure the interface using the PI Interface Configuration Utility or edit startup command file. OSIsoft recommends using the PI Interface Configuration Utility. If the interface is NOT running directly on the Citect node then the following parameters must be defined /cihost= name of Citect node /ciuser= name of Citect user used by remote connection /cipass= password for user defined by /ciuser= 10. Configure performance points. 11. Configure I/O rate tag. 12. Setup interface node clock. 13. Setup security. 14. Start the interface without buffering. 15. Verify data. 16. Stop interface, start buffering, start interface.
10
Interface Installation
OSIsoft recommends that interfaces be installed on PI Interface nodes instead of directly on the PI Server node. An Interface node is any node other than the PI Server node where the PI Application Programming Interface (PI API) has been installed (see the PI API Installation Instructions manual). With this approach, the PI Server need not compete with interfaces for CPU time. The primary function of the PI Server is to archive data and to service clients that request data. After the interface has been installed and tested, Bufserv should be enabled on the API node (once again, see the PI API Installation Instructions manual). Bufserv is distributed with the PI API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures. In most cases, interfaces on API nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure. The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and interfaces as manual services that are launched by site-specific command files when the PI Server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI Server by site-specific command files. This typical scenario assumes that Bufserv is not enabled on the PI Server node. Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not need to be started and stopped in conjunction with PI; however, it is not standard practice to enable buffering on the PI Server node. Please see the UniInt Interface User Manual for special procedural information.
Naming Conventions and Requirements

In the installation procedure below, it is assumed that the name of the interface executable is PI_Citect.exe and that the startup command file is called
PI_Citect.bat.
It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, one would typically use PI_Citect1.exe and PI_Citect1.bat for interface number 1, PI_Citect2.exe and PI_Citect2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line parameters in a file that has the same root name.
Interface Directories
The PIHOME Directory Tree
The PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the %WinDir% directory. A typical pipc.ini file contains the following lines:
[PIPC]
11
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on the C: drive. OSI recommends using \pipc as the root directory name. The PIHOME directory does not need to be on the C: drive.
Interface Installation Directory

Place all copies of the interface into a single directory. The suggested directory is:
PIHOME\Interfaces\Citect\
Replace PIHOME with the corresponding entry in the pipc.ini file.
Interface Installation Procedure

The PI Citect interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and later. When running on Windows NT 4.0 systems, the PI Citect setup program will install the Windows Installer itself if necessary. To install, run the Citect_x.x.x.x.exe installation kit.
Installing the Citect API DLL files

For the interface to run, it must be able to locate the Citect API DLL. If the interface is running directly on the Citect node then the interface will be able to find the DLL files if the Citect Bin directory is on the PATH, or the DLL files are copied to either the Windows\System32 directory or to the interface installation directory. The recommended method is to having the Citect Bin directory added to the PATH. This means that there are no duplicate copies of files that can cause problems if the Citect software is updated. If the interface is running on a separate PI interface node and connecting to a remote Citect machine then the DLLs must be copied from the Citect machines Bin directory into the interface installation directory. The DLL files required by the interface are
CtApi.dll Ct_ipc.dll CtEng32.dll CtRes32.DLL CtUtil32.dll CiDebugHelp.dll (only on Citect 5.41 or later)
Note : It is important that the version of the DLL files used by the interface are the same
version as those used by the Citect system itself. If the Citect software is updated then any copies of the DLLs must also be updated.
12
Installing the Interface as an Windows Service

The PI Citect interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.
Installing the Interface Service with PI Interface Configuration Utility

The PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service. For example:
Service Configuration
Service name The Service to Add box shows the name of the current interface service. This service name is obtained from the interface executable. ID This is the service id used to distinguish multiple instances of the same interface using the same executable. 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. OSIsoft suggests that the prefix PI- be appended to the beginning of the interface to indicate that the service is part of the OSIsoft suite of products.
Interface Installation Log on as The Log on as text box shows the current Log on as Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show LocalSystem. Users may specify a different Windows User account for the service to use. Password If a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password. Confirm password If a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box. Dependencies The Installed services list is 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 button. For example, if API Buffering is running, 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. To remove a service from the list of dependencies, use the the service name will be removed from the Dependencies list. button, and
When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.
Note: Please see the PI Log and Operating System Event Logger for messages that may indicate the cause for any server not running as expected.
- Add Button To add a dependency from the list of Installed services, select the dependency name, and click the Add button. - Remove Button To remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button. The full name of the service selected in the Installed services list is displayed below the Installed services list box. Create The Create button adds the displayed service with the specified Dependencies and with the specified Startup Type. Remove The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.
14
Startup Type The Service Type indicates whether the interface service will start automatically or need to be started manually on reboot. If the Auto option is selected, the service will be 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, interface services are set to start automatically. Create The Create button adds the displayed service with the specified Dependencies and with the specified Startup Type. Remove The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.
Start or Stop Service

To Start or Stop an interface service, use the Start button and a Stop button on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available. The status of the Interface service is indicated in the lower portion of the PI ICU dialog. Status of the ICU Status of the Interface Service Service installed or uninstalled
15
Installing the Interface Service Manually

One can get help for installing the interface as a service at any time with the command:
PI_Citect.exe help
Change to the directory where the PI_Citect1.exe executable is located. Then, consult the following table to determine the appropriate service installation command.
Windows Service Installation Commands on a PI Interface Node or a PI Server node with Bufserv implemented Manual service Automatic service *Automatic service with service id PI_Citect.exe install depend tcpip bufserv PI_Citect.exe install auto depend tcpip bufserv PI_Citect.exe serviceid X install auto depend tcpip bufserv
Windows Service Installation Commands on a PI Interface Node or a PI Server node without Bufserv implemented Manual service Automatic service *Automatic service with service id PI_Citect.exe install depend tcpip PI_Citect.exe install auto depend tcpip PI_Citect.exe serviceid X install auto depend tcpip
*When specifying service id, the user must include an id number. It is suggested that this number correspond to the interface id (/id) parameter found in the interface .bat file. Check the Microsoft Windows services control panel to verify that the service was added successfully. The services control panel can be used at any time to change the interface from an automatic service to a manual service or vice versa.
.
16
Communication Test Programs

The interface is supplied with a program, PI_CitectTest.exe that connects only to Citect. This test program connects to Citect in exactly the same way as the interface does. It eliminates PI from the equation during any connection problems that may occur because it makes no reference to the PI system. The program is run from the MS-DOS command prompt and needs no command-line parameters. It begins by initializing a connection to Citect and displaying version information as retrieved from Citect. Before attempting to run the interface, a connection test should be done individually for both the PI API and Citect API client. If a test program is run that makes reference to only one system, any problems that occur with the communication will be specific to the system being connected to; thus problems can be found and corrected more efficiently. Once connection has been established and confirmed using the test programs described below, the connection specifications for both PI and Citect that have been set up will function equally well for the interface.
Testing the Connection to PI

PI is supplied with a test program, Apisnap.exe, which makes a connection only to PI, eliminating any potential problems connecting to Citect. For more information about ApiSnap.exe see the PI Server manual.
Testing the Connection to Citect

The interface is supplied with a program, PI_CitectTest.exe that connects only to Citect. This test program connects to Citect in exactly the same way as the interface does. It eliminates PI from the equation during any connection problems that may occur because it makes no reference to the PI system. The program is run from the MS-DOS command prompt and needs no command line parameters. It begins by initializing a connection to Citect and displaying version information as retrieved from Citect.
Connecting to Citect
The program will prompt for a host with which to establish a remote connection to Citect. If the Citect system to be connected to is version 5.20 or greater and is on a remote machine, the remote machine name or IP address must be entered at the prompt. The program will then prompt for a Citect user name and password before it attempts to connect. Following is an example:
Citect host: 206.347.209.32 Citect User: ENGINEER Password : ****** Attempting to connect to Citect on 206.347.209.32 ... Connected to Citect Version 5.20 Rev. 00 handle = 7e45f0 Iead or (W)rite: ...
17
Communication Test Programs If the Citect system is on the local machine, it is not necessary to supply a host name. Also, if the version of Citect is earlier than 5.20, remote connections to Citect are not possible. Pressing <enter> will bypass remote connections and attempt a connection to the Citect system on the local machine. Following is an example:
Citect host: Attempting to connect to Citect on local machine ... Connected to Citect Version 5.20 Rev. 00 handle = 7e45f0 Iead or (W)rite: ...
Note: The test program supplied with version 2.0.x of the interface will not prompt for a host but immediately attempt to connect to the Citect system on the local machine.
Reading Points
After connecting to Citect, pressing R (not case-sensitive) will put the test program into read mode. It will ask the user for the name of a Citect point to read and display the value for that point. It will only display the value once and then ask for another Citect point to read. Pressing <enter> without entering a point name will cause the program to use the last point that was entered. Following is an example of the test programs output using read mode:
... Iead or (W)rite: R Citect point to read LOOP_1_PV = 136.500 Citect point to read LOOP_1_PV = 145.200 Citect point to read LOOP_1_PV = 149.600 Citect point to read LOOP_2_PV = 5.700 Citect point to read LOOP_2_PV = 7.200 Citect point to read LOOP_2_PV = 10.500 Citect point to read
from: LOOP_1_PV from: from: from: LOOP_2_PV from: from: from: ^C
Writing Points
After connecting to Citect, pressing W (not case-sensitive) will put the test program into write mode. It will ask the user for the name of a Citect point to write to and ask for a value to write to that point. Pressing <enter> without entering a point name will cause the program to use the last point that was entered. Pressing <enter> without entering a value will cause the program to write a random number.
18
Following is an example of the test programs output using read mode:

... Iead or (W)rite: W Citect point to write to: LOOP_1_SP Value to write: 95.22 Citect point to write to: Value to write: Writing random number: 75.602 Citect point to write to: LOOP_2_SP Value to write: Writing random number: 77.230 Citect point to write to: ^C
19
Digital States
PI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 1 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Data Archive Manual for Windows NT and Unix manual. A Citect point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user. System Digital State Set Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time. For example, if the interface receives bad data from a Citect point, it writes the system digital state BAD INPUT to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients. The interface uses two states that are not defined as part of the standard PI system digital state set. They are as follows:
Cit_Bad_Conn: This state indicates that the connection to Citect has been lost. It must
be entered precisely as shown.

I/F_Stopped: This state indicates that the interface was not running at a particular
time. This state can be entered as any string but must match the /stopstat parameter in the interface startup file. See the /stopstat heading of the Startup Command File section for more information. These two states need to be inserted into unused states in the system digital state set. An unused state is identified by a label ?# where # is the number of the unused state; for example, if state 100 is unused it will have ?100 as its label.
Interface Status Tag

When using the /itag= parameter to specify an interface status PI tag, the interface assumes than the tag will contain a predefined set of digital states. If the tag does not have the states as expected, the value of the PI tag will be meaningless. The following shows the digital state set that should be used for the interface status tag.
State 0 1 2 3 4 5 6 Digital State String Intf Running Intf Stopped Intf DCS Error Pri Running Pri Stopped Pri DCS Error Sec Ready Description Standalone, interface running normally Standalone, interface stopped Standalone, unable to communicate with Citect node Primary, interface running and collecting data from Citect Primary, interface stopped Primary, unable to communicate with Citect node Secondary, interface running (waiting) 20
State 7 8 9 10
Digital State String Sec Stopped Sec DCS Error Sec Socket Down Sec Primary Down
Description Secondary, interface stopped Secondary, unable to communicate with Citect node Secondary, TCP/IP sockets error Secondary, interface running and collecting data from Citect as the primary interface has failed.
There should be one status tag for each copy of the interface running. The tags should also have the PointSource attribute set to L.
21
Point Source
The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For example, the string Boiler1 may be used to identify points that belong to the MyInt Interface. To implement this, the PointSource attribute would be set to Boiler1 for every PI Point that is configured for the MyInt Interface. Then, if /ps=Boiler1 is used on the startup command-line of the MyInt Interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of Boiler1. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the /ps parameter. Case-sensitivity for PointSource Attribute The PointSource character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=P and /ps=p are equivalent. It is only necessary to be careful with the case of the PointSource during point definition and only if the Interface will be running on a PINet node communicating to a PI Server. Reserved Point Sources Several subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface.
Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.
22
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the PI Data Archive. A single point is configured for each measurement value that needs to be archived. Use the point attributes below to define what data to transfer.
Point Attributes
Tag
A tag is a label or name for a point. Any tag name can be used in accordance to the normal PI point naming conventions. Length The length of the Tag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
PI API 1.6 or higher 1.6 or higher Below 1.6 Below 1.6
PI Server 3.4.370.x or higher Below 3.4.370.x 3.4.370.x or higher Below 3.4.370.x
Maximum Length 1023 255 255 255
PointSource
The PointSource is unique name that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line parameter and the Point Source section.
PointType
Typically, device point types do not need to correspond to PI point types. For example, integer values from a device can be sent to floating point or digital PI tags. Similarly, a floating-point value from the device can be sent to integer or digital PI tags, although the values will be truncated. Float16, float32, float64, int16, int32, digital, and string point types are supported on PI 3 Servers. For more information on the individual point types, see PI Data Archive for NT and UNIX.
Location1
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).
23
PI Point Configuration 0 Input tag 1 Output tag
Location2
The second location field specifies the interface instance number. In the startup .bat file, there is a parameter for interface ID, /ID=#, where # is any number. The Location2 field for each tag must match that number, or the tag will be ignored.
Location3
Location 3 is not used in this interface.
Location4
Scan-based Inputs For scan-based collection of data, Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the /f parameter in the section called Startup Command File. Trigger-based Inputs and Output Points Location 4 should be set to zero for these points.
Location5
Location 5 is not used in this interface.
InstrumentTag
Length The length of the InstrumentTag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
This field contains the full name of Citect point with which it is associated. For input tags, it represents the Citect point that the data is to be collected from. For output tags, it represents the Citect point that data is to be written to. The point name in this field is not case sensitive.
24
ExcDesc
Length The length of the Extended Descriptor field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
Trigger-based Inputs For trigger-based input points, a separate trigger point must be configured. An input point is associated with a trigger point by entering a case-insensitive string in the extended descriptor (ExDesc) PI point attribute of the input point of the form:
keyword=trigger_tag_name
where keyword is replaced by event or trig and trigger_tag_name is replaced by the name of the trigger point. There should be no spaces in the string. UniInt automatically assumes that an input point is trigger-based instead of scan-based when the keyword=trigger_tag_name string is found in the extended descriptor attribute. An input is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous Snapshot value to trigger an input, but the timestamp of the new value must be greater than (more recent than) or equal to the timestamp of the previous value. This is different than the trigger mechanism for output points. For output points, the timestamp of the trigger value must be greater than (not greater than or equal to) the timestamp of the previous value. Performance Points For UniInt-based interfaces, the extended descriptor is checked for the string PERFORMANCE_POINT. If this character string is found, UniInt treats this point as a performance point. See the section called Performance Point Configuration.
Scan
By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the PI point after the point edit is detected by the interface. There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed
PI Point Configuration from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point. Input tags are serviced by the interface to collect data from Citect and send it to PI. They can either be scan-based or event-based. Scan-based Scan based tags are serviced regularly at a pre-defined time interval. An input tag can be configured to be updated at a regular time interval specified by any one of a set of userdefined scan classes. The interval of each scan class is based from and controlled by the interface. When a scan classs time interval expires, the data for the tags that are configured for that scan class is requested. All tags for a particular scan class are retrieved from Citect at once. For information about defining scan-based input tags, see the description of /f in the Startup Command File section. Event-based Event-based tags are serviced when a change occurs in a separate PI tag. An input tag can be configured to send data to PI on an event, based on the exception of the data from a separate PI point. When the value of this separate PI point changes the data for the actual tag is requested from Citect. For information about setting up an exception tag, see the Trigger-based Inputs heading of the PI Point Configuration section.
Zero/Span
This field specifies the range of the PI tags zero and span. If the value of a Float16 or Int16 tag is outside of its specified range, either the digital state UnderRange or OverRange will be written to the tag. If the tag is specified as a Float32 or Int32, the input value is written to PI even when it is out of range. This range is also used to determine the compression dead-band width in engineering units when using the CompDevPercent attribute. For more information about the CompDevPercent attribute, see the PI Data Archive for Windows NT and Unix manual.
Shutdown
The shutdown attribute is used only if the server node is a PI 3 system. The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Data Archive for NT and UNIX.
Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the /stopstat command-line parameter is specified.
One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Data Archive for NT and UNIX.
26
Bufserv It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shutdown, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.
Output Points
Output points control the flow of data from the PI Data Archive to any destination that is external to the PI Data Archive, such as a PLC or a third-party database. For example, to write a value to a setpoint on the Citect system, one would use an output point. Outputs are triggered for UniInt-based interfaces. That is, outputs are typically not scheduled to occur on a periodic basis. There are two mechanisms for triggering an output.
Trigger Method 1 (Recommended)

For trigger method 1, a separate trigger point must be configured. The output point must have the same point source as the interface. The trigger point can be associated with any point source, including the point source of the interface. Also, the point type of the trigger point does not need to be the same as the point type of the output point. The output point is associated with the trigger point by setting the SourceTag attribute of the output point equal to the tag name of the trigger point. An output is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous value that was sent to the Snapshot to trigger an output, but the timestamp of the new value needs to be more recent than the previous value. If no error is indicated, then the value that was sent to the trigger point is also written to the output point. If the output is unsuccessful, then an appropriate digital state that is indicative of the failure is usually written to the output point. If an error is not indicated, the output still may not have succeeded because the interface may not be able to tell with certainty that an output has failed.
Trigger Method 2
For trigger method 2, a separate trigger point is not configured. To trigger an output, write a new value to the Snapshot of the output point itself. The new value does not need to be different than the previous value to trigger an output, but the timestamp of the new value must be more recent than the previous value. Trigger method 2 may be easier to configure than trigger method 1, but trigger method 2 has a significant disadvantage. If the output is unsuccessful, there is no tag to receive a digital state that is indicative of the failure, which is very important for troubleshooting.
27
Performance Point Configuration

One can configure performance points to 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
Configuring Performance Points with PI ICU (Windows)
Create To create a Performance Point, right click the line belonging to the tag to be created, and select Create. Delete To delete a Performance Point, right click the line belonging to the tag to be deleted, and select Delete. Correct If the Status of a point is marked Incorrect, the point configuration can be automatically corrected by ICU by right clicking on the line belonging to the tag to be corrected, and selecting Correct. The Performance Points are created with the following PI attribute values. If ICU detects that a Performance Point is not defined with the following, it will be marked Incorrect:
Attribute Tag Point Source Compressing Excmax Descriptor Details Tag name that appears in the list box Point Source for tags for this interface, as specified on the first tab Off 0 Interface name + Scan Class # Performance Point
28
Rename To rename a Performance Point, right click the line belonging to the tag to be renamed, and select Rename. 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 Performance Point does exist Not Created Indicates that the Performance Point does not exist Deleted Indicates that a Performance Point existed, but was just deleted by the user
Scan Class The Scan Class column indicates which scan class the Performance Point in the Tagname column belongs to. There will be one scan class in the Scan Class column for each scan class listed in the Scan Classes combo box on the Uniint Parameters tab. Tagname The Tagname column holds the Performance Point tag name. Snapshot The Snapshot column holds the snapshot value of each Performance Point that exists in PI. The Snapshot column is updated when the Performance Points/Counters tab is clicked, and when the interface is first loaded.
Configuring Performance Points Manually

Performance point configuration is the same on all operating system platforms. Performance points are configured as follows. 1. Set the extended descriptor to:
PERFORMANCE_POINT
or to:
PERFORMANCE_POINT=interface_id where interface_id corresponds to the identifier that is specified with the /id parameter on the startup command line of the interface. The character string PERFORMANCE_POINT is case insenstive. The interface_id does not need to be
specified if there is only one copy of an interface that is associated with a particular point source. 2. Set Location4 to correspond to the scan class whose performance is to be monitored. For example, to monitor scan class 2, set Location4 to 2. See the /f parameter for a description of scan classes. 3. Set the PointSource attribute to correspond to the /ps parameter on the startup command line of the interface. 4. Set the PointType attribute to float32.
29
I/O Rate Tag Configuration

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. One I/O Rate tag can be configured for each copy of the interface that is in use.
Monitoring I/O Rates on the Interface Node

For Windows and UNIX nodes, the 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook. For Open VMS nodes, the rate (events/minute) can be monitored with the PISysExe:IOMonitor.exe program or with another client program such as Process Book. The IOMonitor program is discussed in PI System Manual I.
Configuring I/O Rate Tags with PI ICU (Windows)

The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and managing IORates Tags.
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 the I/O Rate point for the Interface. To disable the I/O Rate point, uncheck this box. To enable the I/O Rate point, check this box.
30
Event Counter The Event Counter number correlates a point specified in the IORates.dat file with this Interface. This correlation results from the command line parameter
/ec=x
where x is the same number that is assigned to the point named in the IORates.dat file. Tagname The tag name listed under the Tagname column is the name of the I/O Rates point. Tag Status The Tag Status column indicates whether the I/O Rate point currently exists in PI Server. The possible states are: In File The In File column indicates whether the I/O Rates point listed in the Tagname column and the event counter number listed in the Event Counter column are in the IORates.dat file. The possible states are: Yes This status indicates that the I/O Rate point and the event counter number are in the IORates.dat file No This status indicates that the I/O Rate point and the event counter number are not in the IORates.dat file Created This status indicates that the point exists in PI Server Not Created This status indicates that the point does not yet exist in PI Server Deleted This status indicates that the point has just been deleted Unknown This status indicates that the PI ICU is not able to access PI Server
Snapshot The Snapshot column holds the snapshot value of the I/O Rate tag, if the I/O Rate tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the Interface is first loaded.
Button Menu Options

Create Create the suggested I/O Rates point with the tag name indicated in the Tagname column. Delete Delete the I/O Rate point listed in the Tagname column. Reset Change the value in the Tagname text box back to the default value.
31
I/O Rate Tag Configuration Rename Allow the user to specify a new name for the I/O Rate point listed in the Tagname column. Add to File Add the I/O Rate point and the event counter number to the IORates.dat file. Search Allow the user to search the PI Server a previously defined I/O Rate points. Update Snapshot Allow the user to refresh the snapshot value.
Configuring I/O Rate Points Manually

There are two configuration steps. 1. Configuring the PI Point on the PI Server 2. Configuration on the Interface Node
Configuring the PI Point on the PI Server

Create an I/O Rate Point with the following PI point attribute values.
Attribute PointSource PointType Compressing ExcDev L float32 0 0 Value
Configuration on the Interface Node

For the following examples, assume that the name of the PI tag is sycitect01 and that name of the I/O Rate on the home node is sycitect001. 1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the %windir% directory. If both are specified, the PIPCSHARE entry takes precedence. Since the PIHOME directory is typically C:\PIPC, the full name of the iorates.dat file will typically be C:\PIPC\dat\iorates.dat. Add a line in the iorates.dat file of the form:
sycitect001, x
where sycitect001 is the name of the I/O Rate Tag and x corresponds to the first instance of the /ec=x parameter in the startup command file. X can be any number between 2 and 34 or between 51 and 200, inclusive. To specify additional rate
32
counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x, should be unique for each copy of the interface. 2. Set the /ec parameter on the startup command file of the interface to match the event counter in the iorates.dat file. The interface must be stopped and restarted in order for the I/O Rate to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started. .
33
Startup Command File

For NT, command file names have a .bat extension. The Windows continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters.
Note: The UniInt Interface User Manual includes details about other command line parameters which may be useful.
Configuring the Interface with PI ICU

Note: PI ICU requires PI 3.3 or greater.
The PI Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the interface is configured by the PI ICU, the batch file of the interface (PI_Citect.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file. The procedure below describes the necessary steps for using PI ICU to configure the PI Citect Interface. From the PI ICU menu, select Interface, New, and then Browse to the PI_Citect.exe executable file. Then, enter values for Point Source and Interface ID#. A window such as the following results:
Interface name as displayed in the ICU (optional) will have PI- pre-pended to this name and it will be the display name in the services menu. Click on Add. You should then see a display such as the following:
34
Note that in this example the Host PI System is localhost, which means that the interface will be configured to communicate with the local PI Server. However, if you want the interface to communicate with a remote PI Server, you can do this by selecting Connections item from PI ICU menu and make it your default server. If you do not see the remote node in the list of servers, you can add that in. Once you add the interface to PI ICU, near the top of the main PI ICU screen, the Interface Type should be citect. If not, use the drop-down box to change the Interface Type to be citect. Click on Apply to enable the PI ICU to manage this copy of the PI Citect Interface.
The next step is to make selections in the interface-specific tab (i.e. 35itect) that allow you to enter values for the startup parameters that are particular to the PI Citect Interface.
35
Since the PI Citect Interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt tab. This tab allows the user to access UniInt features through the PI ICU and to make changes to the behavior of the interface. If you want to set up the interface as a Windows Service, you can do that by using the Service tab. This tab allows you to configure the interface to run as a service as well as to start and stop the interface. You can also run the interface interactively from the PI ICU. To do that go to menu, select the Interface item and then Start Interactive. For more detailed information on how to use the above-mentioned and other PI ICU tabs and selections, please refer to the PI Interface Configuration Utility User Manual. In the next section we will describe the selections that are available from the 36itect tab. After you have made your selections on the PI ICU GUI, you will need to press the Apply button in order for PI ICU to make these changes to the interfaces startup file.
citect Interface Tab

Since the startup file of the PI Citect Interface is maintained automatically by the PI ICU, you should use the 36itect tab to configure the startup parameters and not make changes in the file manually. The following is the description of interface configuration parameters used in the PI ICU Control and corresponding manual parameters.
36
Citect Connection
Citect host machine This parameter specifies the remote Citect machine name. An IP address may also be used instead of the host name. If the interface is to run on the same computer as Citect, then this parameter should not be used. This parameter MUST be used in conjunction with the /ciuser and /cipass command-line parameters. (/CIHOST=hostname). Citect user name This parameter specifies the user name with the remote Citect machine. It is used in conjunction with the /cihost and /cipass parameters. If the /cihost is specified and the /ciuser is not, the interface will fail to initialize. (/CIUSER=username). Citect password This parameter specifies the password for the username within the remote Citect machine as specified by the /ciuser parameter. It is used in conjunction with the /cihost parameters. If /cihost is specified and the /cipass is not, the interface will fail to initialize. (/CIPASS=password). Dont send data to PI This parameter prevents the interface from sending its data to PI. It is used for testing the throughput of Citect and the interface, generating as little interaction
Startup Command File with PI as possible. If the appropriate event counters are configured, the interface will still count the number of Citect reads and writes and send their averages to the event counter tags in PI. It will not count the number of exceptions. (/NOPIWRITE)
Interface Recovery
On Lockup The interface is able to detect when the Citect API failed to return. When this lockup occurs, the interface can Abort, Ignore the problem, or Restart. The default is /ONLOCKUP=Abort. If the interface is running under Windows 2000 as a service, the service can be configured to automatically restart on a failure. If /ONLOCKUP=Restart is used, the interface will start an external utility and abort. The utility will wait for the service to stop and then restart it. (This is only required with Windows) Service Name This parameter specifies the name of the service that the restart utility will attempt to start if the interface detects a lockup and the /ONLOCKUP=Restart is used. The default is to use the name of the interface executable filename as the service name. If multiple instances of the service are configured to use the same executable file, then the service name will need to be defined explicitly. (/SERVICENAME=servicename) Restart Utility The parameter specifies the name of the external utility to be started if the interface detects a lockup and the /ONLOCKUP=Restart is used. The default utility name is StartService. The utility must be in the same directory as the interface executable. (/RESTARTUTIL=executablename) Watchdog Timer (sec) This parameter specifies the watchdog timeout period, in seconds. If the watchdog timer is not updated by the interface within this time period, then the interface will carry out the action defined by the /ONLOCKUP=x parameter (Ignore, Abort, Restart) (/WTO=#, default=60)
Citect Debug Parameters

All messages This is the same as specifying all of the debug parameters for /df=. If this parameter is used, all others are effectively redundant. (/DF=A) Verbose messages As for All debug messages, but also includes messages relating to the usage of the Citect API calls. Due to the large amount of data output, care should be taken when using this option. (/DF=V)
38
List creation messages Every tag is added to a list in the CTAPI for retrieval from Citect, A message is reported every time one of these lists is created. (/DF=L) Tag creation A message is reported every time a tag is added to a CTAPI internal point list. The message indicates which list the point was added to. (/DF=T) Input tag data A message is reported that displays the value and status of the first five tags in each scan class and event class. (/DF=I) Output tag data A message is reported that displays the values and status of the first five tags in each output class. (/DF=O) ctListRead() messages A message is reported before and after each call to the ctListRead() Citect API function, which occurs when a scan list is read. (/DF=X) ctListData() messages A message is reported before and after each call to the ctListData() Citect API function, which occurs when the value is read for each tag in a scan list. This option will fill the pipc.log file very quickly and should be used with caution. (/DF=Y)
Failover
Enable failover This check box is used to enable the interface to use failover. Primary node When running redundant interface, this parameter specifies whether this instance will be the primary (P) or secondary (S) node. Only one instance can be specified as Primary. (/IMODE=P or S) Failover Tag The parameter specifies the name of a PI digital tag that will be used to store the status of the interface. The digital tag should have a digital state set as specified in the section Interface Status Tag. (/ITAG=digitaltag) Health Tag ID This value is used when creating UniInt health points for an interface that uses Non-UniInt interface failover. It is used for the Location3 point attribute for UniInt health points. (/UHT_ID=#)
39
Startup Command File Failover nodes and Ports When running redundant interfaces, this parameter give the host name and port number that should be used to establish the communications between the two instances of the interface. If both interface are running on the same machine, then use the host name localhost. The port number can be any unused port on the system. Up to two failover nodes:ports can be specified. (/IHOST=host:port)
Additional Parameters
This section is provided for any additional parameters that the current ICU control does not support.
40
Command-line Parameters
Command-line parameters can begin with a / or with a -. For example, the /ps=M and ps=M command-line parameters are equivalent.
Parameter /cihost= Citect_hostname Citect Host Name Optional
Description This parameter specifies the remote Citect machine name. An IP address may also be used instead of a host name. If the interface is to run on the same computer as Citect, then this parameter should not be used. Note: Remote Citect connections are available for use only with version 2.1.x and greater of the interface connecting to Citect version 5.20, service pack B or greater. Note: This parameter MUST be used in conjunction with the /ciuser and /cipass command-line parameters.
/cipass= Citect_password Citect User Password Optional Required if /cihost used /ciuser= Citect_username Citect User Name Optional Required if /cihost used. /db=n UniInt Debug Level
This parameter specifies the password for the user name within the remote Citect machine as specified by the /ciuser parameter. It is used in conjunction with the /cihost parameter. If /cihost is specified and /cipass is not, the interface will fail to initialize. This parameter specifies the user name within the remote Citect machine. It is used in conjunction with the /cihost and /cipass parameters. If /cihost is specified and /ciuser is not, the interface will fail to initialize.
This refers to the debug messages output by the standard OSI universal interface (UniInt) template that the interface is based on. Various levels can be specified which display different types of messages. They are as follows: /db or /db=1 all messages /db=2 initialization /db=3 tag building and updates /db=8 exit handling
/df=xxxx Interface Debug parameters Optional
This parameter defines parameters that cause further information to be reported. These parameters are normally only used during installation or when a problem with the interface occurs. Using them under normal operation of the interface will cause it to slow down. Because this information is also sent to the interface log file Pipc.log, it may quickly grow very large. Each parameter determines what kind of information messages to report during operation of the interface. Each kind of message is specified by a letter of the alphabet (not case sensitive). They are listed below: A (A)ll Debug Messages. The same effect as specifying all of the debug parameters for /df=. If this parameter is used, all others are effectively redundant.
41

Parameter Description V (V)erbose Messages. As for All debug messages, but also includes messages relating to the usage of the Citect API calls. Due to the large amounts of data output, care should be taken when using this option. L (L)ist Creation Messages. Every tag is added to a list in the CTAPI for retrieval from Citect. A message is reported every time one of these lists is created. T (T)ag Creation. A message is reported every time a tag is added to a CTAPI internal point list. The message indicates which list the point was added to. I (I)nput Tag Data. A message is reported that displays the value and status of the first five tags in each scan class and event class. O (O)utput Tag Data. A message is reported that displays the value and status of the first five tags in each output class. X Log ctListRead() calls. A message is reported that displays the value and status of the first five tags in each output class. Y Log ctListData() calls. A message is reported that displays the value and status of the first five tags in each output class. For debug parameters I and O, each line of data takes the following format: <PI tag name>(<PI point number>) data = <Rval>, <Istat> These parameters may be present in any order and may be repeated or omitted. For example, /df=OTLT will cause the interface to report list creation, tag creation and output data information messages. /ec=# Optional The first instance of the /ec parameter on the command line is used to specify a counter number, #, for an I/O Rate point. If # is not specified, then the default event counter is 1. Also, if the /ec parameter is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, each copy of the interface that is running without /ec=# explicitly defined will write to the same I/O Rate point. This means that one should either explicitly define an event counter other than 1 for each copy of the interface or one should not associate any I/O Rate points with event counter 1. Configuration of I/O Rate points is discussed in the section called I/O Rate Tag Configuration. The /f parameter defines the time period between 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. Each instance of the /f parameter on the command line defines a scan class for the interface. There is no limit to the number of scan
/f=SS or /f=SS,SS or /f=HH:MM:SS or /f=HH:MM:SS,hh:m m:ss
42
Parameter Required for reading scan-based inputs
Description classes that can be defined. The first occurrence of the /f parameter on the command line defines the first scan class of the interface, the second occurrence defines the second scan class, and so on. 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: /f=00:01:00,00:00:05 /f=00:00:07 or, equivalently: /f=60,5 /f=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 will be 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 section called Performance Point Configuration for more information on skipped or missed scans. This interface does not support sub-second scan classes. 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, /f=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 /f=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.
43

Parameter /host=host:port Required for PI ICU Description The /host parameter is used to specify the PI Home node. Host is the IP address of the PI Sever node or the domain name of the PI Server node. Port is the port number for TCP/IP communication. The port is always 5450 for a PI 3 Server. It is recommended to explicitly define the host and port on the command line with the /host parameter. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults. Defaults: The default port name and server name is specified in the pilogin.ini or piclient.ini file. The piclient.ini file is ignored if a pilogin.ini file is found. Refer to the PI API Installation Instructions manual for more information on the piclient.ini and pilogin.ini files. Examples: The interface is running on an API node, the domain name of the PI 3 home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host parameters would be: /host=marvin /host=marvin:5450 /host=206.79.198.30 /host=206.79.198.30:5450 /id=x Optional Note: Corresponds to location2 point attribute. The /id parameter is used to specify the interface identifier. The interface identifier is a string that is no longer than 9 characters in length. UniInt concatenates this string to the header that is used to identify error messages as belonging to a particular interface. See the section called Error and Informational Messages for more information. UniInt always uses the /id parameter in the fashion described above. This interface also uses the /id parameter to identify a particular interface copy number that corresponds to an integer value that is assigned to the Location2 point attribute. If the /id parameter is a valid integer, then the interface will only process PI tags with the same value in the Location2 attribute. If the /id parameter is not an integer, then the interface will process all PI tags with a matching PointSource and ignore the value of the attribute location2. /ihost=host:port Optional When running redundant interfaces, this parameter gives the host name and port number that should be used to establish the communications between the two instances of the interface. If both interfaces are running on the same machine, then use the host name localhost. The port number can be any unused port on the system. e.g. /ihost=localhost:6789 /imode=x Optional When running redundant interfaces, this parameter specifies whether this instance will be the primary (p) or the secondary (s).
44
Parameter /itag=x Optional
Description This parameter specifies the name of a PI digital tag that will be used to store the status of the interface. The digital tag should have a digital state set as defined in the Interface Status Tag section on page 20. There should be a tag for each copy of the interface running. This parameter prevents the interface from sending its data to PI. It is used for testing the throughput of Citect and the interface, generating as little interaction with PI as possible. If the appropriate event counters are configured, the interface will still count the number of Citect reads and writes and send their averages to the event counter tags in PI. It will not count the number of exceptions. The interface is able to detect when the Citect API has failed to return. When this lockup occurs, the interface can abort, ignore the problem, or restart. The default is /onlockup=abort. If the interface is running under Windows2000 as a service, the service can be configured to automatically restart on a failure. If /onlockup=restart is used, the interface will start an external utility and abort. The utility will wait for the service to stop and then restart it. (This is only required with NT)
/nopiwrite No PI Write Optional
/onlockup=xx Optional
/ps=x Required /stopstat or /stopstat= digstate default: /stopstat= Intf Shut Optional
The /ps parameter specifies the point source for the interface. X is not case sensitive and can be unique name. For example, /ps=P and /ps=p are equivalent. If the /stopstat parameter is present on the startup command line, then the digital state I/O Timeout will be written to each PI Point when the interface is stopped. If /stopstat=digstate is present on the command line, then the digital state, digstate, will be written to each PI Point when the interface is stopped. For a PI 3 Server, digstate must be in the system digital state table. For a PI 2 Server, where there is only one digital state table available, digstate must simply be somewhere in the table. UniInt uses the first occurrence in the table. If neither /stopstat nor /stopstat=digstate is specified on the command line, then no digital states will be written when the interface is shut down. Examples: /stopstat=Intf Shut The entire parameter is enclosed within double quotes when there is a space in digstate.
/q Optional /restartutil=xx Optional
When the /q parameter is present, Snapshots and exceptions are queued before they are sent to the PI Server node. This parameter specifies the name of the external utility to be started if the interface detects a lockup and the /onlockup=restart. The default utility name is StartService. The utility must be in the same directory as the interface executable.
45

Parameter /servicename=xx Optional Description This parameter specifies the name of the service that the restart utility will attempt to start if the interface detects a lockup and the /onlockup=restart. The default is to use the name of the interface executable filename as the service name. If multiple instances of the service are configured to use the same executable file, then the service names will need to be defined explicitly. This parameter is used only when Non-UniInt failover is enabled for this interface. Its value is used when creating UniInt health points when Non-UniInt failover is enabled. It is used for the Location3 point attribute when creating UniInt health points. This parameter specifies the watchdog timeout period, in seconds. If the watchdog timer is not updated by the interface within this time period, then the interface will carry out the action defined by the /onlockup=xx parameter (ignore, abort or restart) The default value is 60 seconds.
/UHT_ID=#
/wto=xx Optional
Sample PI_Citect.bat File

The following is an example startup command-line:
REM======================================================================= REM REM PI_Citect.bat REM REM Sample startup file for the Citect Interface to the PI System REM REM======================================================================= REM REM OSIsoft strongly recommends using PI ICU to modify startup files. REM REM Sample command line REM REM REM -------------------------------------------------------------REM SAMPLE Command Line REM PI_Citect.exe /ps=Citect /id=1 /host=XXXXXX:5450 ^ /cihost=ci-node1 /ciuser=piuser /cipass=trustn01 ^ /f=00:00:10 /f=00:01:00 /f=00:30:00 ^ /q /stopstat REM REM End of PI_Citect.bat File
46
Interface Failover Configuration

The interface failover functionality allows two instances of the interface to be run, either on the same machine or on different machines. The two instances of the interface communicate with each other and exchange status information. One instance of the interface is defined as the primary, the other as the secondary. The primary interface will normally collect the data from the Citect system, and the secondary will monitor the primary. If the primary interface loses its connection to the Citect system, or the secondary interface is unable to communicate with the primary (i.e. the primary has stopped), then the secondary interface will start to collect the Citect data. The command-line parameters listed below are used to define the interface failover
/imode=x
where x is P for the primary interface and S for the secondary

/ihost=hostname:port
defines the TCP/IP ports to be used by the interface for communicating with the other instance of the interface. The primary interface will listen on the specified port for connections (and therefore should be local), and the secondary will attempt to connect to that port.
/itag=tagname
The tagname specifies the name of a PI tag that will be used to store the status of this instance of the interface. Each instance must have a separate status tag. The status tags must be digitals, and contain the digital state set as defined in the Interface Status Tag section on page 20. When using UniInt health tags with interfaces running in failover, the instances of the interface should be started with the /uht_id=x command-line parameter and the health tags with location3 set to x, so that each instance of the interface will write to a different set of health tags.
Note: There is a limitation with the failover functionality. If the communication link between the two instances of the interfaces is lost, it is possible for the primary AND secondary interfaces to both collect data. This can cause duplicate events to be sent to the PI server. Use redundant connections between the interfaces to reduce the possibility of this occurring. If the machines running the interfaces have multiple network cards, more than one /ihost parameter can be defined so that there are multiple independent connections between the two interfaces.
Examples
8...
The primary interface is to run on CitectA, and the secondary on CitectB. Both machines are also running the Citect software. Each machine has a secondary network card, with the TCP/IP host names CitectA_2 and CitectB_2.
47
Interface Failover Configuration

Primary PI_Citect /ps=A /f=00:00:10 /imode=P /ihost= CitectA:5451 ^ /ihost=CitectA_2:5452 /itag=Citect_Primary Secondary PI_Citect /ps=A /f=00:00:10 /imode=S /ihost= CitectA:5451 ^ /ihost=CitectA_2:5452 /itag=Citect_Secondary
Because Citect is running locally, the /cihost, /ciuser and /cipass parameters are not required. Also note that there are two /ihost parameters listed for each interface, one for each network connection. 2) Both instances of the interface are running on a PI Interface node called PIAPI. The instances are named PI_Citect1 and PI Citect2. Citect is running on redundant machines CitectA (master) and CitectB (standby).
Primary PI_Citect1 /ps=A /f=00:00:10 /cihost=CitectA ^ /ciuser=piuser /cipass=passwd ^ /imode=P /ihost=localhost:5451 /itag=Citect_Primary Secondary PI_Citect2 /ps=A /f=00:00:10 /cihost=CitectB ^ /ciuser=piuser /cipass=passwd ^ /imode=S /ihost=localhost:5451 /itag=Citect_Secondary
48
Interface Watchdog Configuration and StartService

The interface includes a watchdog timer which is used to detect when there is a problem with the Citect API not responding. The watchdog timer is controlled with the command line parameters /onlockup, /servicename, /restartutil, and /wto. The older versions of the Citect API had timing issues that meant that it was possible for the interface to attempt to read a list of points but the Citect function would never return control to the interface, and the interface would lockup. The timeout period for the watchdog timer is 60 seconds by default. If the Citect system is very slow to respond, but has not locked up, it is possible to change the period using the /wto= parameter. By default, if the interface detects a lockup of the Citect API, it will abort itself. Under Windows 2000 or later, the interface service can be configured so that if it aborts, the service will be automatically restarted by the OS. To enable this option, open the services applet (Start -> Settings -> Control Panel -> Administrative Tools -> Services), find the interface service you wish to restart and right click on it, choose Properties from the menu, choose the Recovery tab, on the first, second and subsequent failures dropdown boxes, choose Restart the Service. Unfortunately, this restart functionality is not available under Windows NT. There are third-party programs available that can monitor the status of a service, and restart the service if it aborts. The interface also has an option where it will use another utility to restart itself. If the command-line parameter /onlockup=restart is set, then the interface will execute a program as a separate process and then abort itself. By default, this program that is started is called StartService.exe. This program is included in the interface installation kit. This program will wait for the interface service to abort itself, and when the service has stopped, it will attempt to restart the service. It is possible to use different programs to restart the service, by specifying the name of the program with the /restartutil= parameter. The interface will start the program and pass the service name as a parameter. By default the service name is the executable file base name. If the service is not using the executable name as the service name (e.g. multiple instances of the interface on one machine), then the actual service name can be specified with the /servicename= parameter.
49
Interface Node Clock

Make sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the box marked Automatically adjust clock for daylight saving changes. For example,
In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,
C:> set
Make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.
50
Security
Windows
The PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. See Modifying the Firewall Database and Modifying the Proxy Database in the PI Server manuals. Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure. See Trust Login Security in the chapter PI System Management of the PI Universal Data Server System Management Guide. If the interface cannot write data to the PI Server because it has insufficient privileges, a 10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Serve, it writes a 999 error. See the section Appendix A: Error and Informational Messages for additional information on error messaging.
PI Server v3.3 and Higher

Security configuration using piconfig For PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:
C:\PI\adm> piconfig @table pitrust @mode create @istr Trust,IPAddr,NetMask,PIUser a_trust_name,192.168.100.11,255.255.255.255,piadmin @quit
For the above,

Trust: An arbitrary name for the trust table entry; in the above example, a_trust_name IPAddr: the IP Address of the computer running the Interface; in the above example, 192.168.100.11 NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate
user Security Configuring using Trust Editor The Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table. See the PI System Management chapter in the PI Server manual for more details on security configuration.
51
PI Server v3.2
For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:
C:\PI\adm> piconfig @table pi_gen,piproxy @mode create @istr host,proxyaccount piapimachine,piadmin @quit
In place of piapimachine, put the name of the PI Interface node as it is seen by PI Server. .
52
Starting / Stopping the Interface

This section describes starting and stopping the interface once it has been installed as a service. See the UniInt Interface User Manual to run the interface interactively.
Starting Interface as a Service

If the interface was installed a service, it can be started from the services control panel or with the command:
PI_Citect.exe start
A message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. Even if the message indicates that the service started successfully, make sure that the service is still running by checking in the services control panel. There are several reasons that a service may immediately terminate after startup. One is that the service may not be able to find the command-line parameters in the associated .bat file. For this to succeed, the root name of the .bat file and the .exe file must be the same, and the .bat file and the .exe file must be in the same directory. If the service terminates prematurely for whatever reason, no error messages will be echoed to the screen. The user must consult the pipc.log file for error messages. See the section Error and Informational Messages for additional information.
Stopping Interface Running as a Service

If the interface was installed a service, it can be stopped at any time from the services control panel or with the command:
PI_Citect.exe stop
The service can be removed by:

PI_Citect.exe remove
53
Buffering
For complete information on buffering, please refer to the PI API Installation Instruction. PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.
Note: Change the Local Security Policy on Windows XP. 1. Open Administrative Tools from the control panel. 2. Open Local Security Policy from administrative tools. 3. Browse to Security Options under Local Policies. 4. Double click on System Objects: Default owner for objects created by members of the Administrators group. 5. Change the dropdown from Object Creator to Administrators group. The behavior of Bufserv should now be the same on XP as it was for NT4 and 2000.
Configuring Buffering with PI ICU (Windows)

Buffering is enabled through the PI Interface Configuration Utilitys Tools>API Buffering menu. Unless buffering is explicitly enabled, the PI API will not buffer data, sending data directly to the home node. The API Buffering dialog allows the user to view and configure the parameters associated with the API Buffering (bufserv) process. The user can start and stop the API Buffering process from the Service tab:
54
Service Tab
The Service tab allows for some API Buffering service configuration. For further configuration changes, use the Services applet. Service Name The Service name displays the name of the API Buffering Service. Display Name The Display name displays the full name associated with the API Buffering service. Log On As Log on as indicates the Windows user account under which the API Buffering service is setup to start automatically on reboot, or manually. Password Password is the name of the password for the Windows user account entered in the Log on as:above. Confirm password You must reenter the password again to verify you have typed it correctly both times. Dependencies The Dependencies lists the Windows services on which the API Buffering service is dependent. Dependent Services The Dependent services area lists the Windows services that depend on bufserv to function correctly. Start / Stop Service The Start / Stop buttons allow for the API Buffering service to be started and stopped. If the service is not created this box will show Not Installed. After a change is made to any of the settings on the Settings tab, the OK button must be clicked to save these settings, and then the service must be stopped and restarted for the changes to be picked up by bufserv. Service Startup Type The Startup Type indicates whether the API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled. If the Auto option is selected, the service will be 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 API Buffering service is set to start automatically.
55
Buffering Create/Remove Service The Create / Remove buttons allow for the creation or removal of the API Buffering service. Clicking the Create button will cause the service to be created using the Log on as and passwords given. Once the service is created the Start / Stop buttons will be activated.
Settings Tab
The Settings tab allows for configuration of the 7 configurable settings used by API Buffering. Default values are used if no other value is provided.
Enable Buffering Enables the API Buffering feature. Maximum File Size Maximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000. The Use Default button places the default value into the text box. To keep this value, click the Apply button. Send Rate Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000. The Use Default button places the default value into the text box. To keep this value, click the Apply button.
56
Primary Memory Buffer Size Primary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000. The Use Default button places the default value into the text box. To keep this value, click the Apply button. Secondary Memory Buffer Size Secondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000. The Use Default button places the default value into the text box. To keep this value, click the Apply button. Max Transfer Objects Max transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000. The Use Default button places the default value into the text box. To keep this value, click the Apply button. Pause Rate When buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000. The Use Default button places the default value into the text box. To keep this value, click the Apply button. Retry Rate When the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000. The Use Default button places the default value into the text box. To keep this value, click the Apply button. Max Theoretical Send Rate This is the theoretical max send rate which is calculated like this: max = MAXTRANSFEROBJS / SENDRATE * 1000 Default value is 5000. This value is automatically calculated for the user and can not be changed. There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.
Configuring Buffering Manually

Buffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI API will not buffer data, sending data directly to the home node. There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.
57
Buffering
Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.
Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under Windows. This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows) to the desired values.
The following settings are available for buffering configuration:

Keywords BUFFERING PAUSERATE Values 0,1 0 2,000,000 Defau lt 0 2 Description Turn off/on buffering. OFF = 0, ON = 1, When buffers are empty the buffering process will wait for this long before attempting to send more data to the home node (seconds) When the buffering process discovers the home node is unavailable it will wait this long before attempting to reconnect (seconds) Maximum buffer file size before buffering fails and discards events. (Kbytes) Maximum number of events to send between each SENDRATE pause. Primary memory buffer size. (bytes) Secondary memory buffer size. (bytes) The time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds)
RETRYRATE
0 2,000,000
120
MAXFILESIZE
1 2,000,000
100,000
MAXTRANSFEROBJ S BUF1SIZE BUF2SIZE SENDRATE
1 2,000,000 64 2,000,000 64 2,000,000 0 2,000,000
500 32768 32768 100
58
In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define the default PI server and an optional time offset change that may occur between the client and server.
Keywords PIHOMENODE DSTMISMATCH Values string 0 2,000,000 Defau lt none 0 Description Windows default server is in pilogin.ini The time that the server and client local time offset is allowed to jump. Typically, 3600 if the nodes are in time zones whose DST rules differ (seconds)
Example piclient.ini File

On Windows the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a connection before retrying. On Windows a piclient.ini file might look like:
[APIBUFFER] BUFFERING=1 MAXFILESIZE=100000 ; The PI API connection routines have a 1 minute default timeout. RETRYRATE=600
59
Appendix A: Error and Informational Messages

A string NameID is pre-pended to error messages written to the message log. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id parameter on the startup command line.
Message Logs
The location of the message log depends upon the platform on which the interface is running. See the UniInt Interface User Manual for more information. Messages are written to PIHOME\dat\pipc.log at the following times. When the interface starts many informational messages are written to the log. These include the version of the interface, the version of UniInt, the command-line parameters used, and the number of points. As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points. If the /db or /df is used on the command line, then various informational messages are written to the log file.
Interface Messages
Fatal Errors
No value specified after /id= Interface expects value following /id= command line parameter. Invalid value for /id= parameter (1-99) The value of the interface identifier has a valid range of 1 to 99. Citect username not specified for host xxxxx A remote Citect node has been specified with the /cihost parameter but no corresponding /ciuser parameter was found. Citect password not specified for host xxxxx A remote Citect node has been specified with the /cihost parameter but no corresponding /cipass parameter was found.
Serious Errors
dev_service_input_list() ERROR : Citect list handle == NULL Attempt to read from invalid Citect list. Indicates corrupted memory. Please contact OSI Tech Support. dev_service_output_list() ERROR : Citect output list handle == NULL Attempt to read from invalid Citect list. Indicates corrupted memory. Please contact OSI Tech Support. ctListRead() returned error : xxxxx Error reading from Citect point list. Citect error message should be appended to this message.
60
PI Tag xxxxx (CiTag yyyyy) has invalid Citect handle Attempt to read from invalid Citect point. Indicates corrupted memory. Please contact OSI Tech Support. PI Tag xxxxx (CiTag yyyyy) ERROR : xxxxx Error reading from Citect point list. Citect error message should be appended to this message.
Point Errors
PI Tag[] location2 value out of range : point refused PI point attribute location2 value is out of range. PI Tag xxxxx (CiTag yyyyy) Error : Invalid data type to write to Citect Mismatch in data type when writing value to Citect point Unable to create [ scan list xx |output list | event list ] : xxxxxx Error creating Citect tag list. Citect error message should be appended to this message. Error : PI tag xxxxx (1234) (CiTag yyyyy) to scan list xx > xxxxxx Error adding Citect tag to Citect tag list. Citect error message should be appended to this message. Normally caused where the Citect tag listed in InstrumentTag attribute of the PI point is incorrect (Citect tag not found).
Warnings
Invalid character in /id= parameter tags will not be filtered using /id If the /id parameter is not a value between 1 and 99 then the tags will not be filtered by interface identifier. The /id parameter will be used in the log files. Cannot find xxxxx state Bad Input will be used instead The digital state specified by the /stopstat parameter was not found in the system digital state set. Cannot connect to remote Citect host: xxxxx Unable to connect to the specified Citect host node. The interface will attempt to connect periodically. Cannot connect to local Citect host Unable to connect to the local Citect host node. The interface will attempt to connect periodically. Connection lost xxxxx The connection to the Citect node was lost. The interface will attempt to reconnect periodically. Could not remove temporary recovery file xxxxx When the interface is shutdown, it will attempt to recover the crash recovery file. If the file can not be removed it could be caused by permissions or a sharing violation.
System Errors and PI Errors

System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.
61
Appendix A Error and Informational Messages
Error Descriptions on Windows

On Windows, descriptions of system and PI errors can be obtained with the pidiag utility:
\PI\adm\pidiag e error_number
62
Appendix B: Point Builder Utility

Point Builder Utility is a tool designed for creating PI Points for the Citect interface. It reads information from Citect variable and/or trend tables and creates files with PI Points in CSV or PIConfig format.
Point Builder Utility creates the following PI Attributes:
PI Attribute Tag PointSource PointType DigitalSet Location1 Location2 Location3
Citect Field NAME n/a TYPE n/a n/a n/a n/a
Default Value NAME none none DefaultSet 0 1 0
Commentary Prefix and suffix added to NAME field if they are specified by the user Specified by the user Calculated according set of rules specified by the user Specified by the user Interface ID
63

PI Attribute Location4 InstrumentTag Descriptor Citect Field n/a NAME COMMENT, UNIT or ADDR ENG_UNITS ENG_ZERO or RAW_ZERO ENG_FULL ENG_ZERO or RAW_FULL RAW_ZERO n/a ENG_ZERO Default Value 1 NAME COMMENT User can choose which Citec field is used for this attribute. Commentary Scan class specified by the user
EngUnits Zero
Span
ENG_FULL ENG_ZERO
Shutdown
Always 0 for all tags
Point type attribute will be assigned to PI tag according the following table:
Citect Point Type BCD BYTE DIGITAL INT LONG LONGBCD REAL STRING UINT
PI Point Type Int32 Int16 Digital Int32 Int32 Int32 Float32 String Int32
Configuration Tab
When Point Builder Utility run for the first time no configuration exists and Create Points File and Display Points buttons are disabled. The text boxes with missing or wrong settings are highlighted in yellow color indicating the bad values.
64
PI Point Attributes section

Tag Prefix if not empty the text will be added in front of Citec point name. For example, if Citec NAME field is SomeTag and Tag Prefix is Unit1: PI tag name will be Unit1:SomeTag. Tag Suffix if not empty the text will be added after Citec point name. PointSource PointsSource PI attribute for all tags. Location1 Location1 PI attribute for all tags. Location2 Location2 PI attribute. If Citect PI Interface option is selected the user can specify desired Location2 and this value will be used for all PI Tags. If OPC interface option is selected the Location2 text box is disabled. The Location2 attribute value depends on Citect Point Type and will be assigned to tags according the following table:
Citect Point Type String Digital All other types
Location2 for OPC interface 1 2 0
65
Appendix B: Point Builder Utility Location3 Location3 PI attribute for all tags. If Citect PI Interface option is selected the Location3 text box is disabled and default value 0 will be assigned to all tags. If OPC interface option is selected the user can specify desired Location3 value and this value will be assigned to all PI Tags. The valid Location3 values for OPC Interface option are 0, 1, or 2. Location4 Location4 PI attribute for all tags. Zero Citect field to be used for Zero PI attribute. The possible values are ENG_ZERO or RAW_ZERO. Span Citect fields calculation to be used for Span PI attribute. The possible values are ENG_FULL ENG_ZERO or RAW_FULL RAW_ZERO. Note that the matching values should be used for Zero and Span. If ENG is selected for Zero attribute the ENG will automatically selected for Span attribute as well and vice versa. Descriptor Citect field to be used for Descriptor PI attribute. The possible values are COMMENT , UNIT or ADDR. Use Trend Table for additional info This option is enabled only if COMMENT field is used for Descriptor PI Attribute. If this option is selected the Point Builder utility will additionally look for not empty COMMENT field in Trend table in case if COMMENT field in Variable table is empty for given Citect point. If not empty COMMENT found for this point it will be used for Descriptor attribute. If this option is not selected (default setting) and COMMENT field in Variable table is empty no further search will be done and empty Descriptor will be assigned to this PI Point.
Variable file
The variable.dbf file represents variable table used for Citect point attributes. If selected file has wrong format (not a dbf file) or doesnt have all required fields the error message will be displayed when user attempts to select such file.
PI Interface section
There are some differences in PI Tag attributes (Location2 and Location3) depending on where the tags are sourced. The two options are available Citect Interface or OPC interface.
PI Points file section

Two formats for generated PI Point file are available: CSV format and PI Config format. The CSV file can be used directly in PI Tag Configurator PISMT Excel addin. The PI
66
Config file can be used as input file for PIConfig. See PI System User manual for more details. Symbol to replace comma in fields. If there is comma symbol in Citect fields it will be replaced by another character specified by the user. The available options are: semicolon, space and underscore. PI Points file name File name and path for output file.
When all settings are correct the buttons Create Points File and Display Points are enabled.
Digital Sets Tab

Here user can specify default set name for Digital tags and create list of rules. If no rules are specified the default set will be used for all digital tags. If Default Set Name text box is empty it will have yellow backcolor specifying the wrong setting. The Create Points File and Display Points buttons will be disabled.
67
Digital Set naming frame is used to create the rules for Digital set naming. Each rule has Condition and Set Name fields. If condition is true the Set Name will be used for DigitalSet PI Attribute for given Citect Digital point.
68
For example, the first rule is if Citect COMMENT filed equal *DUMMY* then digital set name for tags with this comment will be DummySet. Note the wildcard characters in *DUMMY*. It means that all comment fields containing DUMMY pattern will match this condition. The ? wildcard is also supported. It means one any character. More complex conditions are available. Condition can be created using Build button.
In that case the NAME field should match *ABC?Tag pattern and COMMENT field shouldnt contain DUMMY pattern. Her 2 Citect fields are used to create rule.
69
The order of rules in the list is important. The first condition is checked first; if it doesnt match, the second condition checked and so on. If no conditions are true for COMMENT and/or NAME Citect fields then the Default Set name is used.
70
Point Builder Tab
The settings can be tested with Display Points button. The output PI Points file will not be created, but all points and attributes will be displayed in the grid. For creating Points file the Create Points File button should be used.
Save Settings button is used to save current setting in PointBuilder.ini file. This file located in the same directory where the Point Builder utility is.
When Point Builder utility run for the first time the settings file doesnt exist. When settings are saved the file will be created and used by Point Builder Utility in feature.
71
Revision History
Date 6-Nov-98 Autho r RGM Comments Redesign: Version 1.x.x uses the functionality of the Citect v5.00 API. Version 2.x.x has been built using the functionality of Citect v5.10 API. Enhancement: Version 2 now supports event tags and output tags Enhancement: Writes the server timestamp to a file every minute. Deletes the file upon exiting. If the interface does not exit normally, this file will not be deleted. If /stopstat is specified in the startup file, the interface will check for this file when it starts up. If it exists, it will write the state specified by /stopstat to all its points. This prevents data from being interpolated after a restart of the interface when it exits abnormally. Bug fix: Cleans up properly when a tag is removed from the interface. Bug Fix: Now supplies username and password to CTAPI connect routine. Accepts them as command line parameters. Improvement: error messages now report more consistently and Citect based error messages are retrieved from Citect. Bug Fix: The character array for holding the Citect version number was too short. Lengthened from 16 to 80. Improvement: If a tag fails to register with Citect, the Citect tag name (InstrumentTag) is reported instead of the PI tag name. 11-Dec-98 RGM Functionality Addition: Can now connect to a remote Citect host if the remote Citect host is version 5.20 service pack B or later. Use /CiHost=IP_Address /CiUser=Username /CiPass=Password 9-Mar-99 RGM Functionality Addition: Can now connect to a remote Citect host if the remote Citect host is version 5.20 service pack B or later. Use /CiHost=IP_Address /CiUser=Username /CiPass=Password Changed the I part of /df= so that the input values reported were all reported to the log in groups of 8 instead of just the first 8. Fixed a bug where the wrong message was reported in debug mode for /df=I Added version resource so version tab appears in the file properties dialog. Changed the code to read this version info when logging to pipc.log 2-Mar-01 19-Mar-01 5-Apr-01 AKF KJM KJM Updated formatting to Skeleton 1.04 Update info for PI Citect version 2.3.x Updated for PI Citect version 2.4.x Added interface failover parameters.
19-Nov-98
RGM
25-Nov-98
RGM
11-Dec-98
RGM
15-Sep-00
RGM
72
Date 16-Jan-02 26-Mar-03 08-Sep-03 30-Sep-03 26-Jan-04
Autho r Kmillar Kmillar Kmillar Kmillar Chrys
Comments Updated for PI Citect version 2.5.x String support. Added new section on failover configuration. Added ICU documentation and 2.5.7 support for lockup detection (abort and restart) Added comments about Citect API licenses. Added /wto=x parameter description 2.6.0.3 Rev A: Reformatted; fixed headers & footers; removed redundant information; reordered to put in standard format; clarified that location2 not location1 corresponds to the .id; enhanced PI ICU information; added part number; added platforms Added description of lockup detection and the StartService utility. Fixed headers and footers. Modified the section on ICU control. Updated manual to latest interface skeleton 1.15. Removed Random and replaced with PI Citect in Point Source description. Fixed headers and footer, TOC. Changed some heading formats Version 2.6.1.7 Rev C; Updated manual name to remove reference to Citect version, added Windows Server 2003 as a supported platform, fixed headers and footers. Version 2.6.2.9 Rev A; Added SetDeviceStatus section and the use of /uht_id for health tags when running in failover mode Version 2.6.2.9 Revision B: updated manual to Skeleton 2.5.2; fixed headers; alphabetized startup command line parameter table, updated screen shots of ICU Version 2.6.2.9 Revision C: Updated sections for new skeleton. Version 2.6.2.9 Revision D: Updated ICU control screen shots Version 2.6.2.9 Revision E: Added Point Builder Utility as appendix B, fixed headers and footers, updated table of contents, updated several screenshots. Version 2.6.2.9 Revision F: Added Installing the Citect API DLL files section to installation instructions. Version 2.6.2.9 Revision G: Fixed second failover example for secondary interface the /cihost should be CitectB not CitectA. Version 2.6.2.9 Revision H: Corrected error in supported features: Exception Reporting: Yes. Version 2.6.2.9 Revision I: Added section on Citect Clusters to Introduction.
9-Mar-05 11-Mar-05 21-Mar-05 21-Apr-05 31-Oct-06
Kmillar Mkelly Mkelly Chrys Mkelly
21-Jun-07 2-Jul-07
Kmillar Janelle
4-Jul-07 11-Jul-07 8-Aug-07
Kmillar Janelle Mkelly
18-Jan-08 18-Aug-08 03 Sep 09 18-Aug-10
KMillar MKelly Shorwitz MKelly
73

PI Citect

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

PI Citect

Transféré par

Droits d'auteur :

Formats disponibles

Citect Interface to the PI System

Version 2.6.2.9 Revision I

Worldwide Offices OSIsoft Australia

OSI Software GmbH

OSI Software Asia Pte Ltd.

OSIsoft Canada ULC

OSIsoft, Inc. Representative Office

OSIsoft Mexico S. De R.L. De C.V.

Sales Outlets and Distributors

Citect Interface to the PI System

UniInt Interface User Manual PI Data Archive Manual

Diagram of Hardware Connection

Citect Interface to the PI System

Citect Interface to the PI System

Citect Interface to the PI System

Citect Interface to the PI System

Naming Conventions and Requirements

Interface Installation Directory

Replace PIHOME with the corresponding entry in the pipc.ini file.

Interface Installation Procedure

Installing the Citect API DLL files

Installing the Interface as an Windows Service

Installing the Interface Service with PI Interface Configuration Utility

Start or Stop Service

Citect Interface to the PI System

Installing the Interface Service Manually

Communication Test Programs

Testing the Connection to PI

Testing the Connection to Citect

Citect Interface to the PI System

from: LOOP_1_PV from: from: from: LOOP_2_PV from: from: from: ^C

Following is an example of the test programs output using read mode:

Citect Interface to the PI System

be entered precisely as shown.

Interface Status Tag

Citect Interface to the PI System

Citect Interface to the PI System

Citect Interface to the PI System

PI API 1.6 or higher 1.6 or higher Below 1.6 Below 1.6

PI Server 3.4.370.x or higher Below 3.4.370.x 3.4.370.x or higher Below 3.4.370.x

Maximum Length 1023 255 255 255

PI Point Configuration 0 Input tag 1 Output tag

PI API 1.6 or higher 1.6 or higher Below 1.6 Below 1.6

PI Server 3.4.370.x or higher Below 3.4.370.x 3.4.370.x or higher Below 3.4.370.x

Maximum Length 1023 32 32 32

PI API 1.6 or higher 1.6 or higher Below 1.6 Below 1.6

PI Server 3.4.370.x or higher Below 3.4.370.x 3.4.370.x or higher Below 3.4.370.x

Maximum Length 1023 80 80 80

Trigger Method 1 (Recommended)

Citect Interface to the PI System

Performance Point Configuration

Configuring Performance Points with PI ICU (Windows)

Citect Interface to the PI System

Configuring Performance Points Manually

Citect Interface to the PI System

I/O Rate Tag Configuration

Monitoring I/O Rates on the Interface Node

Configuring I/O Rate Tags with PI ICU (Windows)

Enable IORates for this Interface

Citect Interface to the PI System

Button Menu Options

Citect Interface to the PI System