cdn.osisoft.comcdn.osisoft.com/interfaces/873/PI_CHIPtoPI_HP_2.9.2.0… · Web viewcdn.osisoft.com

Fisher-Rosemount CHIP Interface

Version 2.9.4.0Revision B

OSIsoft, LLC 777 Davis St., Suite 250San Leandro, CA 94577 USATel: (01) 510-297-5800Fax: (01) 510-357-8136Web: http://www.osisoft.com

OSIsoft Australia • Perth, AustraliaOSIsoft Europe GmbH • Frankfurt, GermanyOSIsoft Asia Pte Ltd. • Singapore OSIsoft Canada ULC • Montreal & Calgary, CanadaOSIsoft, LLC Representative Office • Shanghai, People’s Republic of ChinaOSIsoft Japan KK • Tokyo, JapanOSIsoft Mexico S. De R.L. De C.V. • Mexico City, MexicoOSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil

Fisher-Rosemount CHIP InterfaceCopyright: © 2001-2023 OSIsoft, LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework(PI-AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.

U.S. GOVERNMENT RIGHTSUse, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.

Published: 06/2011

http://www.osisoft.com/

Table of Contents

Terminology...................................................................................................................vii

Chapter 1. Introduction...................................................................................................1Reference Manuals............................................................................................1Supported Features...........................................................................................2Diagram of Hardware Connection......................................................................7

Chapter 2. Principles of Operation................................................................................9

Chapter 3. Installation Checklist..................................................................................13Data Collection Steps.......................................................................................13Interface Diagnostics........................................................................................15Advanced Interface Features...........................................................................15

Chapter 4. Interface Installation...................................................................................17Naming Conventions and Requirements..........................................................17Interface Directories.........................................................................................18

PIHOME Directory Tree.........................................................................18Interface Installation Directory...............................................................18

Interface Installation Procedure.......................................................................18Installing Interface as a Windows Service........................................................18Installing Interface Service with PI Interface Configuration Utility....................19

Service Configuration............................................................................19Installing Interface Service Manually.....................................................21

Chapter 5. Viewing Local CHIP Database...................................................................23CHIP_UTIL – Windows....................................................................................23

Chapter 6. Digital States...............................................................................................27

Chapter 7. PointSource.................................................................................................29

Chapter 8. PI Point Configuration................................................................................31Point Attributes.................................................................................................31

Tag........................................................................................................31PointSource...........................................................................................32PointType...............................................................................................32Location1...............................................................................................32Location2...............................................................................................32Location3...............................................................................................32Location4...............................................................................................33Location5...............................................................................................33

Fisher-Rosemount CHIP Interface iii

InstrumentTag........................................................................................33ExDesc..................................................................................................34UserInt1.................................................................................................37UserInt2.................................................................................................37UserReal1..............................................................................................37UserReal2..............................................................................................37Convers.................................................................................................37SquareRoot............................................................................................37Zero.......................................................................................................38Span......................................................................................................38Scan......................................................................................................38Shutdown...............................................................................................38

Input-specific Attributes....................................................................................39Output Points...................................................................................................44

Trigger Method 1 (Recommended)........................................................44Trigger Method 2...................................................................................44

Output-specific Attributes.................................................................................45Scaling.............................................................................................................46Conversion Factor............................................................................................47Alarm Processing.............................................................................................488-bit Status Processing....................................................................................4916-bit Status Processing..................................................................................50Controller-mode Processing.............................................................................50PIconfig and CHIP Gener.................................................................................51Request/Response Definition Files..................................................................53

Request Section....................................................................................53Response Section..................................................................................54Sample Request/Response Definition Files...........................................55Creation or Modification of Request/Response Definition Files.............56

Chapter 9. Startup Command File...............................................................................59Configuring the Interface with PI ICU...............................................................59

CHIPtoPI Interface Page........................................................................62Command-line Parameters..............................................................................67Sample PICHIPtoPI.bat File.............................................................................74

Chapter 10. Failover Overview...................................................................................75Comparison of Failover Mechanisms...............................................................75

Chapter 11. UniInt Failover Configuration................................................................77Introduction......................................................................................................77

Quick Overview......................................................................................78Synchronization through the Data Source (Phase 1).......................................79Configuring Synchronization through the Data Source (Phase 1)....................80Configuring UniInt Failover through the Data Source (Phase 1)......................83

Start-Up Parameters..............................................................................83Data Source Points................................................................................84PI Tags..................................................................................................85

Detailed Explanation of Synchronization through the Data Source..................88Steady State Operation..........................................................................89

Failover Configuration Using PI ICU................................................................91

Fisher-Rosemount CHIP Interface iv

Create the Interface Instance with PI ICU........................................................91Configuring the UniInt Failover Startup Parameters with PI ICU......................92Creating the Failover State Digital State Set....................................................92

Using the PI ICU Utility to create Digital State Set.................................93Using the PI SMT 3 Utility to create Digital State Set............................93

Creating the UniInt Failover Control and Failover State Tags (Phase 1)..........96

Chapter 12. Interface-Level Failover Using Microsoft Cluster................................97Overview..........................................................................................................97Configuring Cluster Failover.............................................................................98Failover Tag.....................................................................................................99Cluster Failover Requirements.........................................................................99

General..................................................................................................99Hardware...............................................................................................99Software...............................................................................................100Installation Checklist............................................................................100Typical Configuration...........................................................................106Scenarios Covered..............................................................................107Primary/Secondary Interface Failover..................................................107Cluster Failover Command Line Parameters.......................................109Sample Startup File on Primary and Secondary Nodes.......................110

Chapter 13. Interface Node Clock............................................................................111

Chapter 14. Security..................................................................................................113Windows........................................................................................................113

Chapter 15. Starting / Stopping the Interface.........................................................115CHIPService..................................................................................................115Starting Interface as a Service.......................................................................115Stopping Interface Running as a Service.......................................................116

Chapter 16. Recognizing CHIP Point Database Changes......................................117

Chapter 17. Buffering................................................................................................119Which Buffering Application to Use................................................................119How Buffering Works.....................................................................................120Buffering and PI Server Security....................................................................120Enabling Buffering on an Interface Node with the ICU...................................121

Choose Buffer Type.............................................................................121Buffering Settings................................................................................122Buffered Servers..................................................................................124Installing Buffering as a Service...........................................................127

Chapter 18. Interface Diagnostics Configuration...................................................131Scan Class Performance Points....................................................................131Performance Counters Points........................................................................134

Performance Counters.........................................................................135Performance Counters for both (_Total) and (Scan Class x)...............135Performance Counters for (_Total) only...............................................137Performance Counters for (Scan Class x) only....................................139

Fisher-Rosemount CHIP Interface v

Table of Contents

Interface Health Monitoring Points.................................................................141I/O Rate Point................................................................................................147Interface Status Point.....................................................................................150

Appendix A. Error and Informational Messages....................................................153Message Logs................................................................................................153Messages.......................................................................................................153System Errors and PI Errors..........................................................................155UniInt Failover Specific Error Messages........................................................156

Informational........................................................................................156Errors (Phase 1 & 2)............................................................................157Errors (Phase 1)..................................................................................158

Appendix B. PI SDK Options....................................................................................159

Appendix C. Technical Support and Resources....................................................161Before You Call or Write for Help.........................................................161Help Desk and Telephone Support......................................................161Search Support....................................................................................162Email-based Technical Support...........................................................162Online Technical Support.....................................................................162Remote Access....................................................................................162On-site Service....................................................................................163Knowledge Center...............................................................................163Upgrades.............................................................................................163OSIsoft Virtual Campus (vCampus).....................................................163

Appendix D. Revision History..................................................................................165

vi

Terminology

To understand this interface manual, you should be familiar with the terminology used in this document.

BufferingBuffering refers to an Interface Node’s ability to store temporarily the data that interfaces collect and to forward these data to the appropriate PI Servers.

N-Way BufferingIf you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering to multiple PI Servers however it does not guarantee identical archive records since point compressions attributes could be different between PI Servers. With this in mind, OSIsoft recommends that you run PIBufss instead.)

ICUICU refers to the PI Interface Configuration Utility. The ICU is the primary application that you use to configure PI interface programs. You must install the ICU on the same computer on which an interface runs. A single copy of the ICU manages all of the interfaces on a particular computer.

You can configure an interface by editing a startup command file. However, OSIsoft discourages this approach. Instead, OSIsoft strongly recommends that you use the ICU for interface management tasks.

ICU ControlAn ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common to all interfaces, an ICU Control implements interface-specific behavior. Most PI interfaces have an associated ICU Control.

Interface NodeAn Interface Node is a computer on which

the PI API and/or PI SDK are installed, and

PI Server programs are not installed.

PI APIThe PI API is a library of functions that allow applications to communicate and exchange data with the PI Server. All PI interfaces use the PI API.

Fisher-Rosemount CHIP Interface vii

Terminology

PI CollectiveA PI Collective is two or more replicated PI Servers that collect data concurrently. Collectives are part of the High Availability environment. When the primary PI Server in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI clients.

PIHOMEPIHOME refers to the directory that is the common location for PI 32-bit client applications.

A typical PIHOME on a 32-bit operating system is C:\Program Files\PIPC.

A typical PIHOME on a 64-bit operating system is C:\Program Files (x86)\PIPC.

PI 32-bit interfaces reside in a subdirectory of the Interfaces directory under PIHOME.

For example, files for the 32-bit Modbus Ethernet Interface are in

[PIHOME]\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory path. For example, ICU files in [PIHOME]\ICU.

PIHOME64PIHOME64 is found only on a 64-bit operating system and refers to the directory that is the common location for PI 64-bit client applications.

A typical PIHOME64 is C:\Program Files\PIPC.

PI 64-bit interfaces reside in a subdirectory of the Interfaces directory under PIHOME64.

For example, files for a 64-bit Modbus Ethernet Interface would be found in

C:\Program Files\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory path. For example, ICU files in [PIHOME]\ICU.

PI Message LogThe PI message Log is the file to which OSIsoft interfaces based on UniInt 4.5.0.x and later writes informational, debug and error message. When a PI interface runs, it writes to the local PI message log. This message file can only be viewed using the PIGetMsg utility. See the UniInt Interface Message Logging.docx file for more information on how to access these messages.

PI SDKThe PI SDK is a library of functions that allow applications to communicate and exchange data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of the PI SDK.

PI Server NodeA PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node.

viii

PI SMTPI SMT refers to PI System Management Tools. PI SMT is the program that you use for configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs on either a PI Server Node or a PI Interface Node.

Pipc.logThe pipc.log file is the file to which OSIsoft applications write informational and error messages. When a PI interface runs, it writes to the pipc.log file. The ICU allows easy access to the pipc.log.

PointThe PI point is the basic building block for controlling data flow to and from the PI Server. For a given timestamp, a PI point holds a single value.

A PI point does not necessarily correspond to a “point” on the foreign device. For example, a single “point” on the foreign device can consist of a set point, a process value, an alarm limit, and a discrete value. These four pieces of information require four separate PI points.

ServiceA Service is a Windows program that runs without user interaction. A Service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.

The ICU allows you to configure a PI interface to run as a Service.

Tag (Input Tag and Output Tag)The tag attribute of a PI point is the name of the PI point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms “tag” and “point” interchangeably.

Interfaces read values from a device and write these values to an Input Tag. Interfaces use an Output Tag to write a value to the device.

Fisher-Rosemount CHIP Interface ix

Chapter 1. Introduction

The Fisher-Rosemount CHIP Interface to the PI System (CHIPtoPI) moves data from the DH6200 series CHIP software to the PI System. The interface program reads the PI point database to determine which points to read from CHIP. It then scans the CHIP database and sends exception reports to the PI System. The Interface can also send values from PI to the CHIP database.

This Interface runs on Microsoft Windows operating systems. The Interface needs to reside on the same computer as the CHIP on Windows software from Fisher. The CHIP software communicates with the PROVOX instrumentation from Fisher. See the CHIP User Guide from Fisher for more information about this software. The Fisher-Rosemount CHIP software must be version P5.0 or later.

Note: The value of [PIHOME] variable for the 32-bit Interface will depend on whether the Interface is being installed on a 32-bit operating system (C:\Program Files\PIPC) or a 64-bit operating system (C:\Program Files (x86)\PIPC).

The value of [PIHOME64] variable for a 64-bit interface will be C:\Program Files\PIPC on the 64-bit operating system.

In this documentation [PIHOME] will be used to represent the value for either [PIHOME] or [PIHOME64]. The value of [PIHOME] is the directory which is the common location for PI client applications.

Note: Throughout this manual there are references to where messages are written by the Interface which is the PIPC.log. This Interface has been built against a UniInt version (4.5.0.59 and later) which now writes all its messages to the local PI Message log.

Please note that any place in this manual where it references PIPC.log should now refer to the local PI message log. Please see the document UniInt Interface Message Logging.docx in the %PIHOME%\Interfaces\UniInt directory for more details on how to access these messages.

Reference Manuals

OSIsoftPI Server manuals

PI API Installation manual

UniInt Interface User Manual

Fisher-Rosemount CHIP Interface 1

Fisher-RosemountUsing DH6200-Series CHIP Software

Configuring DH6200-Series CHIP Software

Technical Reference for DH6200-Series CHIP Software

Supported Features

Feature Support

Part Number PI-IN-FI-CHIP-NTI-Platform

* Platforms 32-bit Interface 64-bit Interface

Windows XP

32-bit OS Yes No

64-bit OS Yes (Emulation Mode) No

Windows 2003 Server

32-bit OS Yes No


Windows Vista

32-bit OS Yes No


Windows 2008

32-bit OS Yes No

Windows 2008 R2


Windows 7

32-bit OS Yes No


Auto Creates PI Points APS Connector

Point Builder Utility No

ICU Control Yes

PI Point Types Int16, int32, float16, float32, float64, digital, string

Sub-second Timestamps Yes

Sub-second Scan Classes Yes

Automatically Incorporates PI Point Attribute Changes

Yes

Exception Reporting Yes

Outputs from PI Yes

Inputs to PI: Scan-based/Event Tags

Supports Questionable Bit No

Supports Multi-character PointSource Yes

Maximum Point Count Limited by resources

* Uses PI SDK No

PINet String Support No


Feature Support

* Source of Timestamps PI Server

History Recovery No

* UniInt-based* Disconnected Startup* SetDeviceStatus

YesYesYes

* Failover YesUniInt Failover (Phase 1)Interface-Level Failover Using Microsoft Cluster

* Vendor Software Required on PI Interface Node / PINet Node

Yes

Vendor Software Required on Foreign Device

No

Vendor Hardware Required No

* Additional PI Software Included with Interface

Yes

* Device Point Types See below

Serial-Based Interface No

* See paragraphs below for further explanation.

PlatformsThe Interface is designed to run on the above mentioned Microsoft Windows operating systems and their associated service packs.

Please contact OSIsoft Technical Support for more information.

Uses PI SDKThe 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 TimestampsThe CHIPtoPI Interface uses PI Server timestamps.

UniInt-basedUniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers and is integrated into many interfaces, including this Interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

The UniInt Interface User Manual is a supplement to this manual.

Disconnected Start-UpThe CHIPtoPI Interface is built with a version of UniInt that supports disconnected start-up. Disconnected start-up is the ability to start the Interface without a connection to the PI Server. This functionality is enabled by adding /cachemode to the list of start-up parameters or by


Introduction

enabling disconnected startup using the ICU. Refer to the UniInt Interface User Manual for more details on UniInt Disconnected startup.

SetDeviceStatusThe CHIPtoPI Interface is built with UniInt. Performance has been improved on tag loading during interface startup. New functionality has been added to support non-output health tags. The health tag with the point attribute ExDesc = [UI_DEVSTAT] is used to represent the status of the source device. The following events can be written into the tag:

"Good" - the Interface is properly communicating with the local CHIP database and can read values from it.

"2 | Connected/No Data | "Successfully connected to CHIP" - the Interface is properly communicating with the local CHIP database, but no points have been collected by the Interface yet. This might be caused by no points being configured for the Interface.

The following list of events represents the failure to communicate with the local CHIP database:

"3 | 1 devices(s) in error | CHIPService not running. CHIPtoPI Interface will need to be restarted once CHIPService is restarted."

Please refer to the UniInt Interface User Manual.doc file for more information on how to configure health points.

FailoverInterface-Level Failover using Microsoft Clustering

Cluster failover allows two copies of the Interface to run on two clustered machines, with only one copy actually collecting data at any given time. This method of failover requires Microsoft Cluster Server.

Details for configuring this Interface to use Cluster failover are described in the Interface-Level Failover Using Microsoft Cluster chapter of this manual.

UniInt Failover Support

UniInt Phase 1 Failover provides support for a hot failover configuration which results in a no data loss solution for bi-directional data transfer between the PI Server and the Data Source given a single point of failure in the system architecture. This failover solution requires that two copies of the Interface be installed on different interface nodes collecting data simultaneously from a single data source. Phase 1 Failover requires that the Interface support output points to the Foreign System. Failover operation is automatic and operates with no user interaction. Each Interface participating in failover has the ability to monitor and determine liveliness and failover status. To assist in administering system operations, the ability to manually trigger failover to a desired Interface is also supported by the failover scheme.

The failover scheme is described in detail in the UniInt Interface User Manual, which is a supplement to this manual. Details for configuring this Interface to use UniInt failover are described in the UniInt Failover Configuration chapter of this manual.

Vendor Software RequiredThe Interface needs to reside on the same computer as the CHIP on Windows software from Fisher. The CHIP software communicates with the PROVOX instrumentation from Fisher.

4

The Fisher-Rosemount CHIP software on Windows must be version P5.0 or later.

Additional PI SoftwareThe PI API for interfaces is required to run the CHIPtoPI Interface in Windows.

Device Point TypesThe CHIPtoPI Interface can scan data from the following Fisher Point Types:

Local Inputs Remote Inputs Local Outputs Remote Outputs

Type 1 Remote DDPs Type 1 PVs

Type 2 Type 4 Discrete

Type 4 Type 5 Parallel Discrete

Type 5 Type 7 Mode

Type 7 Type 8 SP (Type 1 only)

Type 8 Type 10 IVP

Type 9 Type 12 SP (Supervisory)

Type 10 Type 18 Bias

Type 11 Type 19 Ratio

Type 12 Type 31 CV float

Type 13 DDP

Type 14

Type 18

Type 19

Type 21

Type 31

For details on which attributes belonging to each of these types can be read from or written to, see the tables in chapter PI Point Configuration.

The Windows version of the CHIPtoPI Interface also has the ability to issue “request” messages to PROVOX devices and obtain data for PI points from the resulting “response” messages. PI points that use this method to obtain data are referred to as request/response points. Request/response points can access information that is not in the local CHIP database, such as device integrity or performance data from PROVOX Data Highway traffic directors or bridges. Data from these sources can provide valuable insights into the PROVOX system itself.

The structure of the request and response messages is described in Chapter 4 of Fisher’s Technical Reference for DH6200-Series CHIP Software, TR2.0:DH6200.

The time required to complete a single request/response transaction can be several hundred milliseconds. As a result, request/response points have performance limitations and several instances of the Interface may be necessary to obtain the desired scan rates for the request/response points.

Note: To eliminate the possibility of request/response points interfering with standard CHIP point types, an instance of the CHIPtoPI Interface will not accept points of both types. That is, standard CHIPtoPI points and request/response points cannot be assigned to the same interface instance. Dedicated instances of the Interface must be created for each class of points.


Introduction

Diagram of Hardware Connection

Recommended Configuration

Optional Configuration

6

Chapter 2. Principles of Operation

The PI System can run on the same computer as CHIP. The PI System can also run on another computer with the CHIP computer as a PI Interface node. In this way, it is possible to have several CHIP systems on different computers sending data to a PI System. Also, running on a PI Interface node, the Interface can put data into either a PI Server 2.x or a PI Server 3.x.

When reading values from CHIP, questionable status (a status code of 8 from CHIP routines) is treated the same as good status. Questionable status occurs during conditions such as loss of controller redundancy that do not affect the values. Tags with communication failures (status code 9 returned from CHIP routines) are recorded in PI with a status of I/O Timeout. For all other unsuccessful status values from CHIP routines, PI point status is set to Bad Input.

In addition to reading data from or writing data to standard CHIP points, the Windows version of the CHIPtoPI Interface has the ability to issue “request” messages to PROVOX devices and obtain data for PI points from the resulting “response” messages. This capability allows a PI point to obtain data that is not in the local CHIP database. For example, a request message can instruct a PROVOX device to respond with its integrity or other status information. Another potential use is to obtain performance data from the highway traffic directors or bridges, such as local highway scan times. Data from response messages can provide useful information about the operation of the PROVOX system itself.

The total elapsed time between sending a request and receiving a response from a device on the same highway as CHIP can be a tenth of a second or more. Elapsed time between request and response from a device on a remote highway can be 0.2 seconds or more. On heavily loaded highways, the elapsed times can be significantly longer. The scan rates that the Interface can sustain are constrained by these relatively long times per request/response transaction.

Note: To prevent request/response points from adversely affecting the scan rate of standard CHIP points, each instance of the CHIPtoPI Interface dedicates itself to only standard CHIP points or only request/response points. The first point added by a given instance of CHIPtoPI establishes the point class affinity for that interface instance. Other points for the instance are accepted only if they are in the same point class.

To effectively use the request/response capability, it is necessary to have a clear understanding of Chapter 4 of the Technical Reference for CHIP, which describes the structure of the request and response messages, and know the specific devices that constitute your PROVOX system. As can be seen from Chapter 4 of the Technical Reference for CHIP, the format of responses for some request messages depends on the type of device. This is an important point: identical request messages sent to different types of PROVOX devices can and do have different response message formats.


Principles of Operation

Some request messages contain values that are specific to the PROVOX installation. To make the CHIPtoPI Interface flexible enough to support the needs of every PROVOX installation, the CHIPtoPI Interface obtains the structures of request/response messages from external text files called request/response definition files (or simply definition files). Each definition file specifies the exact contents of one request message and the field structure for the expected response message from one specific type of PROVOX device. In each definition file, user-chosen names are assigned to response fields in addition to specification of the field’s location in the response message and data type. The section Request/Response Definition Files describes the syntax used in the request/response definition files and several example definition files are included with the Interface.

To configure a PI point to send a request message and obtain data from the response, the CHIPtoPI Interface needs three things:

A request/response definition file,

The Data Highway address of the device to be sent the request, and

The name of the field to extract from the response.

When a request/response point is added or edited, the Interface will reject the point if the Data Highway address is invalid. Otherwise, the point will be accepted even though other configuration problems may prevent the Interface from obtaining data for the point (as discussed later in this section). If the request/response definition file exists and does not contain fatal syntax errors, a compiled version of the file is loaded into the Interface’s memory, replacing any previous in-memory version of the same definition file. The response field names will be checked for all points that use this definition file, not just the point being added or edited. Thus, if a definition file is changed, editing one PI point that refers to the file is sufficient to refresh all other points that use the same definition file and interface ID.

When the CHIPtoPI Interface scans a request/response point, it first checks for the in-memory version of the definition file and the existence of the response field name in the definition. If either check fails, the digital state Configure is sent (through the standard exception algorithm) as the new snapshot value for the point. If both checks pass, the in-memory request message is sent to the Data Highway address. The Interface then waits for a response message. If a good response message is received, the in-memory response message structure is used to extract the named field’s value. If there is an error in sending the request or no response is received within CHIP’s time limit, a digital state will be used for the field value as discussed at the beginning of this section. The value is processed through the standard PI exception algorithm. If the value passes the exception tests, it is sent to PI as the new snapshot value for the point.

The total elapsed time between sending a request and receiving a response from a device on the same highway as CHIP can be a tenth of a second or more. Elapsed time between request and response from a device on a remote highway can be 0.2 seconds or more. On heavily loaded highways, the elapsed times can be significantly longer. These latencies limit the rate that the CHIPtoPI Interface can process request/response transactions.

As discussed above, request/response transactions have relatively long latencies. Since the response from a single request may contain fields for more than one PI point, the CHIPtoPI Interface avoids making redundant requests by specifically looking for points that can share a request/response transaction. The search for sharable responses is done within scan classes. When the Interface receives a good response, the set of points in the scan class is searched for other points that have an identical definition file name and Data Highway address. For points that meet these criteria, fields are extracted from the response to obtain new values for the points. The new value for each point is subjected to the standard PI exception tests and

10

conditionally sent to PI as the new snapshot value. When these points are subsequently encountered during the same scan cycle, the Interface notices that a new value has already been obtained and continues on to the next point in the scan class. As a result, a single request/response transaction is performed for each unique combination of definition file name and Data Highway address in the scan class.

UniInt FailoverThis Interface supports UniInt failover. Refer to the UniInt Failover Configuration section of this document for configuring the Interface for failover.


Chapter 3. Installation Checklist

If you are familiar with running PI data collection interface programs, this checklist helps you get the Interface running. If you are not familiar with PI interfaces, return to this section after reading the rest of the manual in detail.

This checklist summarizes the steps for installing this Interface. You need not perform a given task if you have already done so as part of the installation of another interface. For example, you only have to configure one instance of Buffering for every Interface Node regardless of how many interfaces run on that node.

The Data Collection Steps below are required. Interface Diagnostics and Advanced Interface Features are optional.

Data Collection Steps

1. Confirm that you can use PI SMT to configure the PI Server. You need not run PI SMT on the same computer on which you run this Interface.

2. If you are running the Interface on an Interface Node, edit the PI Server’s Trust Table to allow the Interface to write data.

3. Run the installation kit for the PI Interface Configuration Utility (ICU) on the Interface Node if the ICU will be used to configure the Interface. This kit runs the PI SDK installation kit, which installs both the PI API and the PI SDK.

4. Run the installation kit for this Interface. This kit also runs the PI SDK installation kit which installs both the PI API and the PI SDK if necessary.

5. If you are running the Interface on an Interface Node, check the computer’s time zone properties. An improper time zone configuration can cause the PI Server to reject the data that this Interface writes.

6. Run the ICU and configure a new instance of this Interface. Essential startup parameters for this Interface are:

Point Source (/PS=x)Interface ID (/ID=#)PI Server (/Host=host:port) Scan Class (/F=##:##:##,offset)


7. If request/response points will be configured:

a. Create dedicated instances of the Interface for request/response points.

b. Create the definition files that will be needed.

c. Use the Checkformat utility to check the syntax of the definition files.

d. Use the Chipsendreq utility to send a request to the PROVOX devices with which the definition file will be used and verify that the response contains the expected data.

8. If you will use digital points, define the appropriate digital state sets.

9. Build input tags and, if desired, output tags for this Interface. Important point attributes and their purposes are:

Location1 is the CHIP database index (DBI) number (or the CHIP tag name can be placed in the InstrumentTag or ExDesc field).Location2 is the CHIP point type taken from the PI Point Configuration chapter . Location3 is the CHIP occurrence number taken from the PI Point Configuration chapter.Location4 specifies the scan class.Location5 is the interface instance.ExDesc is the CHIP tag name (unless the DBI is specified in Location1 or CHIP tag name is specified in InstrumentTag) for standard points or the definition file name for request/response points.InstrumentTag is the CHIP tag name (unless the DBI is specified in Location1) for standard points or the response field name for request/response points.

10. Start the Interface interactively and confirm its successful connection to the PI Server without buffering.

11. Confirm that the Interface collects data successfully.

12. Stop the Interface and configure a buffering application (either Bufserv or PIBufss). When configuring buffering use the ICU menu item Tools Buffering… Buffering Settings to make a change to the default value (32678) for the Primary and Secondary Memory Buffer Size (Bytes) to 2000000. This will optimize the throughput for buffering and is recommended by OSIsoft.

13. Start the buffering application and the Interface. Confirm that the Interface works together with the buffering application by either physically removing the connection between the Interface Node and the PI Server Node or by stopping the PI Server.

14. Configure the Interface to run as a Service. Confirm that the Interface runs properly as a Service.

15. Restart the Interface Node and confirm that the Interface and the buffering application restart.


Interface Diagnostics

1. Configure Scan Class Performance points.

2. Install the PI Performance Monitor Interface (Full Version only) on the Interface Node.

3. Configure Performance Counter points.

4. Configure UniInt Health Monitoring points

5. Configure the I/O Rate point.

6. Install and configure the Interface Status Utility on the PI Server Node.

7. Configure the Interface Status point.

Advanced Interface Features

1. Configure the Interface for Disconnected Startup. Refer to the UniInt Interface User Manual for more details on UniInt Disconnected startup.

16. Configure failover; see later chapters in this document for details related to configuring the Interface for failover.


Chapter 4. Interface Installation

OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PI Server node. A PI Interface Node is any node other than the PI Server node where the PI Application Programming Interface (PI API) is installed (see the PI API manual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. 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, Buffering should be enabled on the PI Interface Node. Buffering refers to either PI API Buffer Server (Bufserv) or the PI Buffer Subsystem (PIBufss). For more information about Buffering see the Buffering chapter of this manual.

In most cases, interfaces on PI Interface 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 install the interface as an automatic service that depends on the PI Update Manager and PI Network Manager services. This typical scenario assumes that Buffering 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, but it is not standard practice to enable buffering on the PI Server node. The PI Buffer Subsystem can also be installed on the PI Server. 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 CHIPtoPI.exe and that the startup command file is called CHIPtoPI.bat.

When Configuring the Interface ManuallyIt is customary for the user to rename the executable and the startup command file when multiple copies of the Interface are run. For example, CHIPtoPI1.exe and CHIPtoPI1.bat would typically be used for interface instance 1, CHIPtoPI2.exe and CHIPtoPI2.bat for interface instance 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

PIHOME Directory Tree

32-bit InterfacesThe [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.

For 32-bit operating systems, a typical pipc.ini file contains the following lines:[PIPC]PIHOME=C:\Program Files\PIPC

For 64-bit operating systems, a typical pipc.ini file contains the following lines:[PIPC]PIHOME=C:\Program Files (X86)\PIPC

The above lines define the root of the PIHOME directory on the C: drive. The PIHOME directory does not need to be on the C: drive. OSIsoft recommends using the paths shown above as the root PIHOME directory name.

Interface Installation Directory

The interface install kit will automatically install the Interface to:PIHOME\Interfaces\CHIPtoPI\

PIHOME is defined in the pipc.ini file.

Interface Installation Procedure

The CHIPtoPI Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and later operating systems. To install, run the appropriate installation kit.

CHIPtoPI_#.#.#.#_.exe

Installing Interface as a Windows Service

The CHIPtoPI Interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.


Installing Interface Service with PI Interface Configuration Utility

The PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service:

Service Configuration

Service nameThe Service name box shows the name of the current interface service. This service name is obtained from the interface executable.

IDThis is the service id used to distinguish multiple instances of the same interface using the same executable.

Display nameThe 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 name to indicate that the service is part of the OSIsoft suite of products.

Log on asThe 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.

PasswordIf 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.


Interface Installation

Confirm passwordIf a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.

DependenciesThe Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependent should be moved into the Dependencies list using the

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. To remove a service from the list of

dependencies, use the button, and the service name will be removed from the Dependencies list.

When the 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 interface service will not run.

Note: Please see the PI Log and Windows Event Logger for messages that may indicate the cause for any service not running as expected.

- Add ButtonTo add a dependency from the list of Installed services, select the dependency name, and click the Add button.

- Remove ButtonTo remove a selected dependency, select 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.

Startup TypeThe Startup Type indicates whether the interface service will start automatically or needs 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.

20

CreateThe 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

The toolbar contains a Start button and a Stop button . 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.

Installing Interface Service Manually

Help for installing the Interface as a service is available at any time with the command:CHIPtoPI.exe –help

Open a Windows command prompt window and change to the directory where the CHIPtoPI.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 implementedManual service CHIPtoPI.exe –install –depend "CHIPService

bufserv"Automatic service CHIPtoPI.exe –install –auto –depend

"CHIPService bufserv"*Automatic service with service id

CHIPtoPI.exe –serviceid X -install -auto -depend "CHIPService bufserv"

Windows Service Installation Commands on a PI Interface Node or a PI Server Node without Bufserv implementedManual service CHIPtoPI.exe –install –depend "CHIPService

tcpip"Automatic service CHIPtoPI.exe –install –auto –depend

"CHIPService tcpip"*Automatic service with service id

CHIPtoPI.exe –serviceid X -install -auto -depend "CHIPService tcpip"


Status of the ICU Service

installed or uninstalled

Status of the Interface Service

Interface Installation

*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.

22

Chapter 5. Viewing Local CHIP Database

There is a utility that allows users to view the current value for a CHIP tag in the local CHIP database on a node where the CHIPtoPI Interface runs. Use the chip_util.exe utility in the CHIP directory to view the CHIP database

CHIP_UTIL – Windows

To run CHIP_UTIL, go to the Start menu, select Programs, select the CHIP folder, and select the CHIP_UTIL utility. This opens a command window with the following options:

Enter 1 to view the CHIP Local Utilities Menu


Enter 3 to View and Operate on CHIP Database Points

The first point displayed will be the point with the lowest DBI in the local CHIP database. To display a different tag or DBI, type N for (N)ew TAG/DBI:


Enter either a CHIP tag name found in either the PI tag’s ExDesc (Extended Descriptor) field or the InstrumentTag field, or enter the CHIP DBI (found in the PI tag’s Location1 field).

This will display the selected DBI or CHIP tag:

There are many different types of CHIP tags. The PI tag’s Location2 parameter must match the “Type” of the CHIP tag. In the above example, the tag is a Type 5, so the PI tag that is scanning this point must have Location2 = 5. The PI tag’s Location3 parameter determines which value the PI tag is scanning. For example, in the Type 5 tag above, if Location3 is set to 1, then the PI tag will be scanning the “%Process Variable”. If the Location3 value is 4, then the PI tag will be scanning the “Mode”.

To exit the CHIP_UTIL utility, press the ENTER key until the window closes.


Chapter 6. Digital States

For more information regarding Digital States, refer to the PI Server documentation.

Digital State SetsPI 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 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.

An interface point that contains discrete data can be stored in PI as a digital point. A digital point associates discrete data with a digital state set, as specified by the user.

The following digital state sets for the controller mode and the alarm status may need to be created:

Offset CHIPMode CHIPAlarm CHIPAlmComb

0 Zero No Alarm noalarm

1 Manual C Alarm C

2 Auto B Alarm B

3 RSP A Alarm CB

4 SUP D Alarm A

5 DDC CA

6 COM BA

7 HMAN CBA

8 D

9 CD

10 BD

11 CBD

12 AD

13 CAD

14 BAD

15 CBAD


The following command lines can be used as input to PIconfig in order to create these digital state sets.@table PIDS@mode create@istru set,state,...Onoff,Off,OnCHIPMODE,Zero,Manual,Auto,RSP,SUP,DDC,COM,HMANCHIPALARM,no alarm,C alarm,B alarm,A alarm,D alarmCHIPALMCOMB,noalarm,C,B,CB,A,CA,BA,CBA,D,CD,BD,CBD,AD,CAD,BAD,CBAD@ends

These digital state sets need to be defined before the digital tags are defined.

System Digital State SetSimilar to digital state sets is the system digital state set. This set is used for all points, regardless of type, to indicate the state of a point at a particular time. For example, if the Interface receives bad data from the data source, 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. Digital States 193-320 are reserved for OSIsoft applications.


Chapter 7. PointSource

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 CHIPtoPI Interface. To implement this, the PointSource attribute would be set to Boiler1 for every PI point that is configured for the CHIPtoPI Interface. Then, if /ps=Boiler1 is used on the startup command-line of the CHIPtoPI 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. If the PI API version being used is prior to 1.6.x or the PI Server version is prior to 3.4.370.x, the PointSource is limited to a single character unless the SDK is being used.

Case-sensitivity for PointSource AttributeThe PointSource character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=P and /ps=p are equivalent.

Reserved Point SourcesSeveral 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.


Chapter 8. PI Point Configuration

The PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each measurement value that needs to be archived.

Point Attributes

Use the point attributes below to define the PI point configuration for the Interface, including specifically what data to transfer.

This document does not discuss the attributes that configure UniInt or PI Server processing for a PI point. Specifically, UniInt provides exception reporting and the PI Server provides data compression. Exception reporting and compression are very important aspects of data collection and archiving, which are not discussed in this document.

Note: See the UniInt Interface User Manual and PI Server documentation for information on attributes that are significant to PI point data collection and archiving.

Tag

The Tag attribute (or tag name) is the name for a point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI documentation uses the terms “tag” and “point” interchangeably.

Follow these rules for naming PI points:

The name must be unique on the PI Server.

The first character must be alphanumeric, the underscore (_), or the percent sign (%).

Control characters such as linefeeds or tabs are illegal.

The following characters also are illegal: * ’ ? ; { } [ ] | \ ` ' "

LengthDepending on the version of the PI API and the PI Server, this Interface supports tags whose length is at most 255 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.

PI API PI Server Maximum Length1.6.0.2 or higher 3.4.370.x or higher 1023

1.6.0.2 or higher Below 3.4.370.x 255

Below 1.6.0.2 3.4.370.x or higher 255

Below 1.6.0.2 Below 3.4.370.x 255


If the PI Server version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and you want to use a maximum tag length of 1023, you need to enable the PI SDK. See Appendix_B for information.

PointSource

The PointSource attribute contains 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 additional information, see the /ps command-line parameter and the PointSource chapter.

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.

Negative integer values can be sent to PI.

Float16, float32, int16, int32, digital, and string point types are supported. For more information on the individual PointTypes, see PI Server manuals.

Location1

This is the CHIP DBI (database index). If Location1 is 0, the CHIP tag name must be in the InstrumentTag or in the beginning of the Extended Descriptor. Note that the Interface will convert the CHIP tag name to its corresponding DBI upon startup. If at any time the DBI for any tag changes, the affected PI tag will need to be re-added to the Interface, or the Interface will have to be stopped and restarted. To cause the tag to be re-added to the Interface, modify a benign tag attribute field, such as the descriptor. The Interface will pick up the change, re-add the tag to the Interface, and re-obtain the DBI.

For request/response points, indicated by Location2=0, Location1 is not used.

Location2

This is the CHIP point type for inputs and local outputs (see Table B-6 of the CHIP User Manual, UM4.10:DH6215) or 0 for request/response points (supported only on Windows). The sign of this parameter determines the direction of data transfer. If this value is positive, the value is transferred from CHIP to PI. If this is the negative of the CHIP point type, values are sent from PI to CHIP. The exception to this is when sending data to the CHIP Highway points, where the sign is positive.

Location3

This determines which CHIP parameter is associated with this PI tag for local inputs and outputs. Location2 determines how this parameter is interpreted (see tables below).

For request/response points, this attribute contains the PROVOX Data Highway address of the device to which the request is to be sent. For this attribute, the Data Highway address is a


three-digit integer hdd where h is the highway number and dd is the device. That is, Location3 is a Fisher PROVOX @h-dd address without the @ and – punctuation. Valid ranges for Location3 are 000 to 006 for network devices or h00 to h30 for local highway devices where h is 1 to 8. For example, Location3 would be 204 for device 4 on highway 2 (corresponding to PROVOX address @2-04).

Location4

Scan-based InputsLocation4 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 Startup Command File chapter.

Trigger-based Inputs, Unsolicited Inputs, and Output PointsLocation 4 should be set to zero for these points.

Location5

This is the CHIP System Number or the interface ID number. It is used when more than one instance of the Interface is running with the same PointSource, possibly on different computers. In the case of instances on different computers, this parameter differentiates between points with the same DBI on different CHIP systems. If the interface ID number is specified in the interface startup command file, only points with Location5 matching the /ID number are loaded. If the startup command file does not specify an interface ID number or it specifies -1, all the tags with matching PointSource are loaded, i.e. Location5 is ignored. Interface ID must be in the range -1 to 99, inclusive.

InstrumentTag

LengthDepending on the version of the PI API and the PI Server, this Interface supports an InstrumentTag attribute whose length is at most 32 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.


1.6.0.2 or higher Below 3.4.370.x 32

Below 1.6.0.2 3.4.370.x or higher 32

Below 1.6.0.2 Below 3.4.370.x 32

If the PI Server version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and you want to use a maximum InstrumentTag length of 1023, you need to enable the PI SDK. See Appendix B for information.

If Location1 is 0, the InstrumentTag field should contain the CHIP tag name. For compatibility with previous versions of this Interface, this field or the ExDesc field can contain the CHIP tag name.


PI Point Configuration

For request/response points (Location2=0), which are supported only on Windows, this attribute must be set to the response field name. Leading white space is ignored and the first trailing white space character terminates the field name (the syntax for request/response definition files does not permit white space in field names). The field name may also be enclosed in single quotes, although there is probably no reason to do so. If the first non-white space character is a single quote, characters between the opening single quote and matching closing single quote are taken as the field name. Any characters following the closing quote are not part of the field name. After the opening single quote, two single quote characters in succession indicate a literal single quote that is part of the field name.

ExDesc

LengthDepending on the version of the PI API and the PI Server, this Interface supports an ExDesc attribute whose length is at most 80 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.


1.6.0.2 or higher Below 3.4.370.x 80

Below 1.6.0.2 3.4.370.x or higher 80

Below 1.6.0.2 Below 3.4.370.x 80

If the PI Server version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and you want to use a maximum ExDesc length of 1023, you need to enable the PI SDK. See Appendix_B for information.

CHIP Tag NameThe Extended Descriptor can be used to specify a number of attributes for the CHIPtoPI Interface tag. If Location1 is 0 and the CHIP tag name is not defined in the InstrumentTag field, the first 16 characters of the Extended Descriptor must contain the CHIP tag name.

LCP Status Word Bit or the EDCD StatusesYou can also use the Extended Descriptor to specify the bit to extract in the LCP Status Word or the EDCD statuses. Use the syntax:

BIT=x, where x is the bit number from 1 to 32.

If the BIT option is not specified for a LCP Status Word tag or if the BIT option is set to 0, the whole status word is stored into PI.

Occurrence NumberYou can also use the Extended Descriptor to specify the Occurrence number for point type 100 DDP Highway Outputs. Use the syntax:

DDP=x, where x is the occurrence number.

Structure of the Request and Response MessagesFor request/response points, the Extended Descriptor must contain the name of the file that defines the structure of the request and response messages.

34

The Extended Descriptor may also contain other UniInt or interface-specific point configuration information. The contents of the Extended Descriptor are interpreted according to the first of the following syntax summaries that matches (where elements enclosed in square brackets are optional):[whitespace][UniInt key(s)]FILE='filename'[UniInt key(s)]

[whitespace][UniInt key(s)]FILE=filename

[whitespace]'filename'[UniInt key(s)]

[whitespace]filename

If one of the FILE= forms is used, white space may optionally be used on either side of the equal sign.

If filename is enclosed in single quotes, two single quote characters in succession indicate a literal single quote that is part of filename. For example, the following Extended Descriptor contentsFILE='embedded''quote'

specifies a filename of embedded'quote.

If filename is unquoted, any trailing white space is considered to be part of filename.

The filename may be a relative or absolute path for the specific operating system on which the Interface is executing. If the filename is a relative path and the /rrdir= argument is present on the command-line, the directory named in the /rrdir= argument will be prefixed onto filename to form the file path that is opened. If the resulting file path is not absolute, it will be relative to the current working directory of the Interface.

The native path specification syntax on Windows uses a leading “\” to indicate an absolute path. Windows also accepts “/” as an alternative to “\”. The CHIPtoPI Interface considers a file name that begins with either slash to be an absolute path specification. A Windows path may also contain a drive letter followed by a colon. Since colons are only allowed as the delimiter for a drive specification, the CHIPtoPI Interface also considers a filename containing “:” to be an absolute path specification. If concatenating the /rrdir directory string with filename does not produce an absolute path, the path will be relative to the current directory of the Interface, which depends on how the Interface was started. If the Interface is installed as a Windows Service, its current directory will be %windir%\system32. If the Interface is started from a command window, the current directory established in the command window will be inherited by the Interface.

Due to the long latencies of request/response transactions, the Interface attempts to minimize the number of requests that are actually sent. If two or more points in the same scan or event-triggered class have the same filename and device address (Location3), the points can share the response from a single request.

Note: The Interface’s comparison of filenames for the purpose of sharing responses is case sensitive. Even though the operating system may ignore case in file names, the case of the filenames in two points must match exactly for the points to share a request/response transaction.

Note: The EVENT= or TRIG= options discussed below may be used to configure a request/response point as an event-based input.



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 Scan Class Performance Points.

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.

Conditions can be placed on trigger events. Event conditions are specified in the extended descriptor as follows:Event='trigger_tag_name' event_condition

The trigger tag name must be in single quotes. For example,Event='Sinusoid' Anychange

will trigger on any event to the PI Tag sinusoid as long as the next event is different than the last event. The initial event is read from the snapshot.

The keywords in the following table can be used to specify trigger conditions.

Event Condition

Description

Anychange Trigger on any change as long as the value of the current event is different than the value of the previous event. System digital states also trigger events. For example, an event will be triggered on a value change from 0 to “Bad Input,” and an event will be triggered on a value change from “Bad Input” to 0.

Increment Trigger on any increase in value. System digital states do not trigger events. For example, an event will be triggered on a value change from 0 to 1, but an event will not be triggered on a value change from “Pt Created” to 0. Likewise, an event will not be triggered on a value change from 0 to “Bad Input.”

Decrement Trigger on any decrease in value. System digital states do not trigger events. For example, an event will be triggered on a value change from 1 to 0, but an event will not be triggered on a value change from “Pt Created” to 0. Likewise, an event will not be triggered on a value change from 0 to “Bad Input.”

Nonzero Trigger on any non-zero value. Events are not triggered when a system digital state is written to the trigger tag. For example, an event is triggered on a value change from “Pt Created” to 1, but an event is not triggered on a value change from 1 to “Bad Input.”

36

UserInt1

This parameter determines whether a conversion factor is to be applied to CHIP Point Type 31 CV5 to CV8 input values. The default behavior is to apply no conversion to the CV5 to CV8 input values. If UserInt1 = 1 and the PI tag is a floating point tag, then the CV value will be converted from PROVOX highway percent to floating point value (effectively dividing the value by 256). This feature requires that the PI API be version 1.3.x or greater.

UserInt2

If Convers is not zero or one, UserInt2 determines whether the Interface multiplies or divides the point value by Convers. If UserInt2 is zero, the Interface divides the value by Convers. If UserInt2 is not zero, the Interface multiplies the value by Convers.

See the Conversion Factor section for more information about the conversion factor option.

UserReal1

If UserReal2 is zero, the Interface does not use this attribute.

If UserReal2 is not zero, the Interface scales the PI point values. Four PI point attributes configure the scaling option: Zero, Span, UserReal1, and UserReal2. See the Scaling section for the purpose of UserReal1 in the scaling calculation.

UserReal2

If UserReal2 is zero, the Interface does not scale the PI point values.

If UserReal2 is not zero, the Interface scales the PI point values. Four PI point attributes configure the scaling option: Zero, Span, UserReal1, and UserReal2. See the Scaling section for the purpose of UserReal2 in the scaling calculation.

Convers

If Convers is not zero or one, UserInt2 determines whether the Interface multiplies or divides the point value by Convers. If UserInt2 is zero, the Interface divides the value by Convers. If UserInt2 is not zero, the Interface multiplies the value by Convers.

See the Conversion Factor section for more information about the conversion factor option.

SquareRoot

The SquareRoot attribute controls log messages that trace the processing of data for the PI point. If the SquareRoot attribute is not zero, the Interface writes log messages at significant steps in the Interface code. If the SquareRoot attribute is zero, the Interface writes log messages only to report abnormal or error conditions.

Note: Per-point trace messages can be enabled or disabled by editing the SquareRoot attribute while the Interface runs. That is, restarting the Interface is not required.



The Interface has a command-line parameter (/db=) that also enables tracing messages. The command-line parameter applies to all points for the Interface. For a production Interface with hundreds or thousands of points, the /db command-line parameter can produce so many tracing messages that finding useful information is difficult and time consuming. Also, the Interface must be stopped and restarted to change the /db command-line parameter. For these reasons, the recommended method of controlling tracing messages is with the SquareRoot attribute instead of the /db command-line parameter.

Zero

If UserReal2 is zero, the Interface does not use this attribute. Other PI clients, such as ProcessBook, may use this attribute.

If UserReal2 is not zero, the Interface scales the PI point values. Four PI point attributes configure the scaling option: Zero, Span, UserReal1, and UserReal2. See the Scaling section for the purpose of Zero in the scaling calculation.

Span

If UserReal2 is zero, the Interface does not use this attribute for scaling. However, the Span attribute is related to the exception deviation attributes ExcDevPercent and ExcDev, which are used by the Interface regardless of scaling. For consistency between interfaces, UniInt provides the exception reporting logic. See the “Point Attributes” section in UniInt Interface User Manual for an explanation of exception reporting and the attributes that control exception reporting.

If UserReal2 is not zero, the Interface scales the PI point values. Four PI point attributes configure the scaling option: Zero, Span, UserReal1, and UserReal2. See the Scaling section for the purpose of Span in the scaling calculation.

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, a message is written to the pipc.log and the tag is not loaded by the Interface. There is one exception to the previous statement.

If any PI point is removed from the Interface while the Interface is running (including setting the scan attribute to 0), SCAN OFF will be written to the PI point regardless of the value of the Scan attribute. Two examples of actions that would remove a PI point from an interface are to change the point source or set the scan attribute to 0. If an interface-specific attribute is changed that causes the tag to be rejected by the Interface, SCAN OFF will be written to the PI point.

Shutdown

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

38

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 Server manuals.

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=Shutdown command-line parameter is specified.

SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed 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 Server manuals.

Bufserv and PIBufssIt is undesirable to write shutdown events when buffering is being used. Bufserv and PIBufss are utility programs that provide the capability to store and forward events to a PI Server, allowing continuous data collection when the PI Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shutdown, Bufserv or PIBufss will continue to collect data for the Interface, making it undesirable to write SHUTDOWN events to the PI points for this Interface. Disabling Shutdown is recommended when sending data to a Highly Available PI Server Collective. Refer to the Bufserv or PIBufss manuals for additional information.

Input-specific Attributes

The Interface recognizes the CHIP point types and parameters listed in this table. The first PI PointType listed is most like the Fisher CHIP database point type. If there are two listed and they are separated by a comma, both point types are recommended. If the second value is in parentheses, it is second choice for matching the Fisher CHIP database point type.

Local Inputs

CHIP Point Type (Location2)

CHIP Parameter Location3 Recommended PI PointType

1 PV 1 Float16 (Int16)

Mode 4 Digital (Int16)

Alarm 5-10 Digital (Int16)

2 Count 1 Int16


4 PV1 1 Float16

PV2 2 Float16

5 PV 1 Float16

SP 2 Float16

IVP 3 Float16



Output Tracking 35 Float32, Digital





Integral Tracking 36 Float32, Digital

Setpoint Tracking 37 Float32, Digital

7 PV 1 Float16

SP 2 Float16

IVP 3 Float16



Bias or Ratio 11 Float16

8 PV 1 Float16

SP 2 Float16

IVP 3 Float16



Bias 11 Float16

Ratio 12 Float16

9 Value bit number, 1-4 Digital (Int16)


10 Mode 4 Digital (Int16)

Number UV's 13 Int16

Operation Number 14 Int16

Step Number 15 Int16

Phase Number 16 Int16

Unit State 17 Int16

Hold Phase Number 18 Int16

Operation Complete 19 Int16

Unit Status 20 Int16

Operation Timer 21 Int16

State Timer 22 Int16

Step Timer 23 Int16

Iteration 24 Int16

Fail Index 25 Int16

OAR 26 Int16

OAR Sequence No. 27 Int16

Message Number 28 Int16

Message Param 1 29 Float16

Message Param 2 30 Float16

Activity Point DBI 31 Int16

Highway Address of Console 32 Int16

Unit Variable #n 100 + n (note 1) Float (note 1)


In/out of Service 13 Digital, Int16

40



Off Scan 14 Int16

SP Number 15 Int16

PV Number 16 Int16

Group Status 17 Digital (Int16)

Fail Index 18 Int16

12,13 Mode 4 Digital (Int16)


Off Scan 14 Digital, Int16

Discrete Value 15 Int16




SP Number 15 Int16

PV Number 16 Int16

DCD Status 17 Digital (Int16)

Input Channel Status 18 (note 4) Digital, Int32

Output Channel Stat 20 (note 4) Digital, Int16

Interlocks Configured 21 (note 4) Digital, Int16

Condition – Status 22 (note 4) Digital, Int16

Condition – Last Fail 23 (note 4) Digital, Int16

Condition – Override 24 (note 4) Digital, Int16

Miscellaneous Flags 25 (note 4) Digital, Int16

Setpoint Disables 26 (note 4) Digital, Int32

18 PV 1 Float32 (Int32)

Local DDP 171-186 Float32 (Int32)

19 Real Value 1 Float32 (Int32)

ASCIIMSG 34 (note 5) String



Activity State 13 Digital (Int16)

Activity Status 14 Int16

Iteration Count 17 Int16

Procedure Index 24 Int16

Process Index 25 Int16

Hold Process Index 26 Int16

Grade Index 27 Int16

Point Set Number 28 Int16

Activity Index 29 Int16

Statement Index 31 Int16

Fail Value 32 Int16

State Timer 33 Int16





Batch ID 34 (note 5) String

Point Status Mask(MVPSTMSK 1-16) (2.8.0.3)

38 (note 4) Digital (Int16)





Fail Index 17 Int16

State 18 Int16

Status Word 19 (note 2) Int16

User-Defined integer (2.5.9.0)

20 (note 2) Int16

Point Status Mask(MVPSTMSK 1-16) (2.8.0.3)

38 (note 4) Digital (Int16)

CV #n 100 + n (note 3) Float32 (Int32)

Note 1: n is between 1 and 32 for Unit Variables. UVs 1-8 use Float64, UVs 9-32 use float16.

Note 2: For LCP Status Words and User-defined integers, you can extract a single bit from the Status Word with the BIT keyword in the Extended Descriptor. The PI tag in this case can be an Integer or Digital Point Type. If you don’t use the BIT processing option, the entire Status word is returned. Since the value can exceed the maximum integer value of 32767, it is recommended that the PI 3 tag be defined as an int32 tag.

Note 3: n is between 1 and 12 for the CVs.

Note 4: 16-bit statuses with Extended Descriptor field = 0 or 17 (record the whole status) must be int32 (float32) on PI 3, otherwise the value could result in an Over/Under Range value. To specify just one bit, specify the bit # in the Extended Descriptor field, in the form BIT=x.

To read the first bit set to ON from the 8-bit statuses, specify BIT=10 in the Extended Descriptor field.

Highway Inputs

Location2 CHIP Parameter Location3 ExDesc

200 Remote DDPs (note 1) mnemonic # Occurrence # optional, 1-x (note 2)

Note 1: Highway reads take longer than local database reads. It is recommended that a separate instance of the Interface be run to collect DDPs. Local database reads/writes and Highway outputs can all be collected/written by the same instance of the Interface. Supported Remote DDP reads include DDP mnemonics 1-385 and mnemonics 769-1023.

42

Note 2: DDP=x, where x is the optional occurrence number, can be placed in the Extended Descriptor.

Example: The DDP to read data from is VC50116A 90.11 where 90 is the mnemonic# and 11 is the occurrence number. Therefore, Loc2 = 200, Loc3 = 90, and the extended descriptor contains DDP=11.

Request/Response Points

Location2 Response Field Type (note 2)

Location3 Recommended PI PointType

0 byte (unsigned) PROVOX address

Digital, Int16

sbyte (note 3) Digital, Int16

short (note 3) Int16, Digital

ushort Int32 (Float32)

int (note 3) Int32 (Digital)

uint (note 4) Int32 (note 4)

hpct Float32, Float16

real Float32

bit# Digital, Int16

bit field (unsigned) Digital, Int16

Note 1: The elapsed time between issuing a request message and receiving a response from a device on the same highway can be a tenth of a second or more; latencies can be significantly longer if the Interface’s CHIP and the target for the request are on different highways. The time per request/response transaction limits the throughput rate for request/response points. Multiple instances of the Interface may be required to achieve the desired scan rates for request/response points. The Interface does attempt to minimize the number of requests actually sent on the Data Highway. Within a scan class, the Interface examines the list of points to be scanned. Any points that have the same request/response definition file name and same device address (Location3) will share a single request/response transaction. To prevent request/response points from adversely affecting the scan rate of standard CHIP points, each instance of CHIPtoPI dedicates itself to standard CHIP points only or request/response points only. The first point added by an instance of CHIPtoPI establishes the point class affinity for that interface instance and other points with the interface ID of the instance will only be accepted if they are in the same point class.

Note 2: See the section Request/Response Definition Files for additional information about response field types.

Note 3: This is a signed field. Therefore, a Digital PI point type may not be suitable unless the negative values have meaning as digital states.

Note 4: This is a 32-bit unsigned field. If values can exceed 231-1, a PI 3 int32 point will not be able to correctly represent all field values. Use float64 if the entire 32-bit precision of the field must be preserved. If some loss of precision is acceptable, float32 may be used.



Output Points

Output points control the flow of data from the PI Server to any destination that is external to the PI Server, such as a PLC or a third-party database. For example, to write a value to a register in a PLC, use an output point. Each interface has its own rules for determining whether a given point is an input point or an output point. There is no de facto PI point attribute that distinguishes a point as an input point or an output point.

Outputs are triggered for UniInt-based interfaces. That is, outputs are not scheduled to occur on a periodic basis. There are two mechanisms for triggering an output.

As of UniInt 3.3.4, event conditions can be placed on triggered outputs. The conditions are specified using the same event condition keywords in the extended descriptor as described in the Trigger-based Inputs section earlier in this document. The only difference is that the trigger tag is specified with the SourceTag attribute instead of with the “event” or “trig” keywords. Otherwise, the behavior of event conditions described in the Trigger-based Inputs section is identical for output points. For output points, event conditions are specified in the extended descriptor as follows:event_condition

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 must 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.

44

Output-specific Attributes

Local outputs are transferred from the PI System to the CHIP shareable image. Local CHIP points can be read by consoles on the PROVOX highway. You can use local outputs to display the results of calculations in the PI System to operators.

An output is sent when either the PI snapshot value, status, or time has changed for the source tag. All outputs are sent on the first scan after restarting the Interface if the /sio option is not specified in the interface startup file. If the output tag is not the same as the source tag, each output value is written to the output tag on PI so that the user has a record of when an output event has occurred. PI exception report specifications are not used for outputs to CHIP but are used when writing the output value to the output tag on PI.

For highway outputs, a point must be defined in the CHIP database. The Interface uses the CHIP database's point attributes to determine the highway address for the output as well as the scaling factor and limits for the highway output value. The CHIP point output can also be defined as an input to PI.

For outputs to the PROVOX highway, the remote device may reject the value if the point is not in the correct mode. The correct mode for accepting an output depends on the point type. Appendix C of the CHIP User Manual lists which parameters may be changed for each point type. The Interface writes a message to the PI Message Log when a highway output is not successful.

Local Outputs

CHIP Point Type(Location2)


-1 PV 1 Int16

-4 PV1 1 Int16

-4 PV2 2 Int16

-5, -7, -8 PV 1 Int16

-5, -7, -8 SP 2 Int16

-10 Activity Point DBI (ATAG)

31 Int16

-12 Discrete Value 15 Int16

-18 PV 1 Int16

-19 PV 1 Int16

-21 ASCIIMSG 34 String, Float32, Int32, Digital

-31 CV #n 100 + n (note 1) Float32 or Int32

Note 1: n is between 1 and 12 for the CVs.



Highway Outputs

Location2 CHIP Parameter Location3 ExDesc

41 PV n/a n/a

42 UOC group or DCD SP

n/a n/a

43 UOC group or DCD supervisory SP

n/a n/a

45 Discrete n/a n/a

47 (note 2) Parallel Discrete n/a n/a

48 Mode n/a n/a

50 SP (only CHIP Type 1)

n/a n/a

51 IVP n/a n/a

52 SP (Supervisory) n/a n/a

53 Bias n/a n/a

54 (note 2) Ratio n/a n/a

84 (note 2) CV float CV number n/a

100 DDP mnemonic # Occurrence # optional, 1-x (note 1)

Note 1: DDP=x, where x is the optional occurrence number, can be placed in the extended descriptor.

Example: The DDP to output data to is VC50116A 90.11 where 90 is the mnemonic# and 11 is the occurrence number. Therefore, Loc2 = 100, Loc3 = 90, and the extended descriptor contains DDP=11.

Note 2: Highway outputs for Parallel Discrete (47), Ratio (54), and CV float (84) are not yet supported.

Scaling

The Interface can optionally scale an input or output value before sending the value to the PI point or PROVOX parameter, respectively. For example, if a measurement for an input point can range from 4 to 20 to represent temperatures from 0 to 100 degrees, this option can transform the input value to meaningful engineering units before sending the value to the PI point. That is, transform 4 to 0, 12 to 50, 20 to 100, and so forth.

The scaling option is applied only to integer or floating-point PI points.

Four PI point attributes configure the scaling option: Zero, Span, UserReal1, and UserReal2. If UserReal2 is zero, the scaling feature is disabled for the PI point.

If UserReal2 is nonzero, Zero and Span define the expected range of the PI point value, UserReal1 is the expected minimum value for the PROVOX value, and UserReal2 is the span for the PROVOX value. That is, UserReal1 and UserReal2 are the zero and span that define the range for the PROVOX value.

46

The Interface applies the following formula to input values from PROVOX:PI point value = (PROVOX value – UserReal1)/UserReal2 * Span + Zero

The Interface applies the following formula to output values from PI:PROVOX value = (PI point value – Zero)/Span * UserReal2 + UserReal1

If UserReal2 is nonzero, the scaling formula is applied before the optional conversion factor described later. The scaling formula is more general than the conversion factor option. If the scaling formula is configured, the effect of the conversion factor option can be achieved by appropriately setting the attribute values that configure the scaling formula. That is, using both options on the same PI point is unnecessary and discouraged.

Conversion Factor

The Interface can optionally apply a conversion factor to an input or output value before sending the value to the PI point or PROVOX parameter, respectively.

The conversion factor option is applied only to integer or floating-point PI points.

The conversion factor is a simpler form of the scaling option described earlier. If the scaling option is required for a PI point, the effect of the conversion factor option can be achieved by appropriately setting the attribute values that configure the scaling formula. Using the conversion factor option with the scaling option on the same PI point is discouraged. However, if both options are configured for the same PI point, the conversion factor is applied to the result of the scaling formula.

Two PI point attributes configure the conversion factor option: Convers and UserInt2. If Convers is zero or one, the conversion factor feature is disabled for the PI point.

If Convers is not zero or one, UserInt2 determines whether the Interface multiplies or divides the value by Convers. If UserInt2 is zero, the Interface divides the value by Convers. If UserInt2 is not zero, the Interface multiplies the value by Convers.

The conversion factor option was added in version 2.9.1.0 of CHIPtoPI. In CHIPtoPI version 2.9.1.0 through 2.9.4.3 inclusive, the conversion factor option does not work as intended.

Note: In CHIPtoPI version 2.9.1.0 through 2.9.4.3 inclusive, the Interface always divides by the conversion factor. To avoid compatibility problems with versions later than 2.9.4.3, set UserInt2 to 0 for all PI points where Convers is not zero or one.



Alarm Processing

The Interface gives three options for interpreting alarm values from CHIP:

A five-state result shows which alarm bit is set. Only one alarm at a time can be recorded.

A 15-state result shows any possible combinations of the alarm bits.

A single alarm bit can be assigned to a tag.

If the Location3 parameter is 5, the alarm states are:

0 = no alarm

1 = C alarm

2 = B alarm

3 = A alarm

4 = D alarm

If two alarm bits are set, the first one in the above list is reported. For example, if both B and D alarm bits are set, the PI value will be the B alarm state.

If Location3 is 6, the combination of the 4 alarms for a point is recorded. The value returned will have a range of 0-15, where:

1 = C alarm

2 = B alarm

4 = A alarm

8 = D alarm

These values are summed for alarm bits that are set to represent the combined alarm state.

Use a Location3 in the range 7-10 to record a single alarm bit. State 0 means no alarm. State 1 means the specified bit is set.

7 = A alarm

8 = B alarm

9 = C alarm

10 = D alarm

For alarms, the PI PointType can be float, integer, or digital. Note that the meaning of the alarm state may be site-specific. The defaults are:

A alarm - deviation alarm

B alarm - Low alarm

C alarm - High alarm

D alarm - user defined

A sample Digital State table that shows these states is in the section Digital States.

48

8-bit Status Processing

The Interface gives three options for interpreting 8-bit statuses from CHIP.

A nine-state result shows the first bit set to ON. Only one status at a time can be recorded.

The integer value of the entire 8-bit status may be assigned to a tag and recorded.

A single alarm bit may be assigned to a Digital or Integer tag and recorded.

To read one bit of an 8-bit status, one of the following ExDesc field BIT= settings must be used:

0 = All bits are to be read. This is optional; if the ExDesc field is blank or contains BIT=0, the whole status is read.

1 = 1st status bit is to be read

2 = 2nd status bit is to be read

3 = 3rd status bit is to be read

4 = 4th status bit is to be read





For statuses, the PI PointType can be float, integer, or digital. The default status states are:

0 = Off

1 = On

If the Location3 parameter is 5, the alarm states are:

0 = no alarm

1 = C alarm

2 = B alarm

3 = A alarm

4 = D alarm

If two alarm bits are set, the first one in the above list is reported. For example, if both B and D alarm bits are set, the PI value will be the B alarm state.



16-bit Status Processing

The Interface gives two options for interpreting statuses from CHIP:

The integer value of the entire 16-bit status may be assigned to a tag and recorded.

A single status bit may be assigned to a Digital or Integer tag and recorded.

To read one bit of a 16-bit status, one of the following ExDesc field BIT= settings must be used:

0 = all bits are to be read. This is optional; if the ExDesc field is blank or contains BIT=0, the whole status is read.

1 = 1st status bit is to be read2 = 2nd status bit is to be read3 = 3rd status bit is to be read4 = 4th status bit is to be read5 = 5th status bit is to be read6 = 6th status bit is to be read7 = 7th status bit is to be read8 = 8th status bit is to be read9 = 9th status bit is to be read10 = 10th status bit is to be read11 = 11th status bit is to be read12 = 12th status bit is to be read13 = 13th status bit is to be read14 = 14th status bit is to be read15 = 15th status bit is to be read16 = 16th status bit is to be read

For bit statuses, the PI PointType can be float, integer or digital. The default status states are:

0 = Off1 = On

For the entire 16-bit status, the PI PointType needs to be Int32 or Float32.

Controller-mode Processing

The controller modes are shown below. A sample Digital State table that shows these states is in the section Digital States.

1 - MAN2 - AUTO3 - RSP4 - SUP5 - DDC6 - COM7 - HMAN

50

PIconfig and CHIP Gener

The CHIP points in the PI database are usually created after defining the CHIP database. The CHIP database is compiled from an ASCII file with a Fisher-supplied utility called Gener. The input file is based upon keywords that Gener recognizes as prompts that precede the CHIP database parameters. This same ASCII file can usually be used, with some editing, to create points in PI. The file is used as a data file for the PI tag database creation/maintenance utility, PIconfig.

When using the Gener input file as the data file for PIconfig, consider the following fields:

Gener Keyword PIconfig Keyword

POINT Tag

DESC Descriptor

DBI Location1

POINT TYPE Location2

EU EngUnits

LOLIMIT Zero

HILIMIT Span + Zero

The exception specifications in CHIP could be used for PI's ExcDev and ExcMin time.

Since the Interface is using the CHIP functions Access_Point and Change_Point, the CHIP database must have valid HI and LO limit specifications. The HI and LO limits are used by CHIP to convert the PROVOX highway values to engineering units. If these limits are not set, all analog values from CHIP will be zero.

Following is a sample file for the CHIP Gener utility. Below the database fragment is a PIconfig file to create tags.



Gener Sample FileRECORD 1, LENGTH = 240DBI = 1 LOCAL = FALSEPOINT TYPE = 1 UNSOLICITED = TRUEDEVICE ADDRESS = 0- 6 SLOT PARAMETERS --POINT NUMBER = 35-156 DEADZONE ENABLEDDEADZONE VALUE = 0.0625SAMPLE INTERVAL = 60TAG = 510X9116DESCRIPTOR = BREAK #1 P. M.UNITS =EU HIGH = 1.00EU LOW = 0.00

RECORD 2, LENGTH = 240DBI = 2 LOCAL = FALSEPOINT TYPE = 1 UNSOLICITED = TRUEDEVICE ADDRESS = 0- 6 SLOT PARAMETERS --POINT NUMBER = 35-184 DEADZONE ENABLEDDEADZONE VALUE = 0.0625SAMPLE INTERVAL = 60TAG = 520X9144DESCRIPTOR = BREAK #2 P. M.UNITS =EU HIGH = 1.00EU LOW = 0.00

52

PIconfig File* chipconfig.pdf* OSIsoft, LLC** Structure file for creating PI3.X Points from the CHIP * file shown above.** Point Database Directives@ptclas classic@tabl pipoint@mode create@stype fixed** Defaulted Items@modi ptclass=classic @modi pointtype=R@modi pointsource=F@modi location3=1@modi location5=1@modi excmax=600** Tag Attributes@istr tag,8,16,10@istr descriptor,9,16,16@istr engunits,10,16,10@istr typicalvalue,11,16,10@istr zero,12,16,10@istr span,11,16,10@istr location1,2,22,5@istr location2,3,24,3@istr excdev,6,21,6@istr excmin,7,24,3** End of structure definition section



Request/Response Definition Files

The CHIPtoPI Interface has the ability to issue a “request” message to a PROVOX device and use a field from the resulting “response” message to obtain input data for a PI point. The Interface reads the structures of the request and response messages from definition files. Each file defines one request message and the response expected from a specific type of PROVOX device for that request. This is an important point: the same request message sent to different types of PROVOX devices can have different response message formats. This section presents the syntax of the request/response definition files. The structure of the request and response messages is in Chapter 4 of Technical Reference for DH6200-Series CHIP Software, TR2.0:DH6200. The terminology used in this section is taken from that manual. The main term which may be unfamiliar is I-frame. The I-frame is the “information payload” of a PROVOX Data Highway packet, excluding highway addressing and CHIP overhead.

Note: The PROVOX Data Highway uses “big endian” byte ordering. That is, multi-byte values are transmitted most-significant byte first. This may be opposite to the native representations of the host CHIP system. Except for the real type below, which is defined as the native host four-byte, floating-point representation, the Interface converts the byte order between the representations of the host system and the Data Highway if necessary.

A request/response definition file contains two sections. The first section defines the request message to be transmitted to a PROVOX device. The second section defines the fields in the response message expected from the device. Blank lines may be used anywhere in the file to aid readability. Comments are introduced by the # character and continue to the end of the line. Thus, entire lines may be comments and comments may be included at the end of a line that contains non-comment text. The case of non-comment text is not significant (that is, keywords will be recognized in upper, lower, or mixed case).

Request Section

The request section is relatively free format. This section begins with the keyword request: followed by two, integer numbers. These two integers are the Fisher request code and I-frame byte length, respectively. The remainder of the request section is a list of pairs of type keywords and values that define the request I-frame contents. The type of each pair specifies how the following value is interpreted. The type keywords are:

byte the unsigned integer value fills the next I-frame bytesbyte the signed integer value fills the next I-frame byteshort the signed integer value fills the next 2 bytesushort the unsigned integer value fills the next 2 bytesint the signed integer value fills the next 4 bytesuint the unsigned integer value fills the next 4 byteshpct the floating-point value is converted to highway percent and fills the

next 2 bytesreal the floating-point value in host format fills the next 4 bytes

54

The type, value pairs must construct a request I-frame whose length exactly matches the I-frame length specified at the beginning of the section.

Any errors in the request section are fatal. That is, the Interface will not use a definition file that has errors in the request section. Any point that is configured to use a defective definition file will receive digital state Configure on each scan.

Response Section

The keyword response: ends the request section and begins the definition of the fields of the response message.

The response section is line-oriented, with each response field on a separate line. Blank lines and all-comment lines may be intermixed with the field definition lines. Comments are also allowed at the end of lines that define fields. Each field is defined by a line containing:fieldName byteOffset type

The fieldName is a name that identifies the field and should be unique within a definition file. The only restrictions on fieldName are that it may not contain whitespace or exceed 32 characters. The fieldName is used in point configuration to connect a point to a specific response field: a point’s InstrumentTag attribute is set to fieldName to identify the response field that provides data for the point. The byteOffset specifies the field’s location relative to the start of the response message I-frame and type specifies the data type and implicit length of the field. The byteOffset is a zero-based offset to the first byte of the field. That is, the first field in the response I-frame has a byteOffset of 0. The type may be any of the request field types listed above. For response fields, additional types are allowed. The additional types include bit0, bit1, …, bit31 that may be used to extract a specific bit. Bit0 is the high-order bit of the byte at byteOffset, bit7 is the low-order bit of the byte at byteOffset, bit8 is the high-order bit of the byte at byteOffset+1, and so forth. Multi-bit fields may be specified by providing a three-digit number for type. In this case, type will have the form nii where n is the number of bits in the field and ii is the starting bit number. Not all combinations of values for n and ii are valid. For example, n=0 is invalid because a field with no bits is meaningless. Bit fields must be completely contained in a single byte. Thus, 206 is a valid specification for a field containing the two low-order bits at byteOffset but 207 is not valid because the field would span two bytes.

The Interface skips erroneous response field lines and attempts to continue reading the definition file so that as many correct response fields as possible will be recognized. If the field name configured for a point either does not exist in the file or is unusable due to errors, the point will receive digital state Configure on each scan.



Sample Request/Response Definition Files

These files are provided with the Interface.

IFC_UOC_Detailed_Status.txtAs an example of a request/response definition file, this is the IFC_UOC_Detailed_Status.txt:# Request 178 - Detailed Device Status# Response format from IFC or UOC

request: 178 #Detailed Device Status Request1 # I-frame lengthbyte 0response:ResponseCode 0 byte #Request CodeVersionNo 1 byte #Version numberOption 2 byte #OptionLoad5secAvg 3 hpct #Average 5-second loadLoad1minAvg 5 hpct #Average 1-minute loadOverload 7 byte #OverloadFreeMemory 8 byte #Free memoryFreeSlots 9 ushort #Free message slotsFreeDevices 11 byte #Number of free devicesSimplex 12 byte #Simplex or redundant

To configure a point to scan the average 1-minute load for an Integrated Function Controller (IFC) at Data Highway address @2-19 using the above file, set the point attributes to:

Attribute Value Description

Location2 0 Specifies that this tag is a request/response point

Location3 219 Data Highway address

Location4 1 - 99 Scan class

Location5 <integer> Interface ID

PointSource <one or more characters> Interface PointSource

InstrumentTag load1minavg Field name -- Average 1-minute load

ExDesc IFC_UOC_Detailed_Status.txt Request/response definition filename

Several sample request/response definition files are provided with the Interface. The sample files are:

Device_Type.txtThis file defines a code 128 request for the type of a device. The response for this request is uniform for all device types, making this definition file suitable for use with any PROVOX device. Since device type does not vary unless devices are added, removed, or replaced, this definition file has limited utility for defining PI points. However, it can be used with the Chipsendreq utility as an alternative to the CHIP utilities for determining the device type at a specific Data Highway address.

56

LTD_Traffic_Statistics.txtThis file defines a code 183 request for traffic statistics from a Local Traffic Director (LTD). The response to this request contains three fields for every possible device on the local highway: number of packets received, number of packets sent, and number of busy messages sent. The response also contains average scan time of the local highway, packets sent by the LTD to local and network areas, and packets received by the LTD from local and network areas.

NTD_Traffic_Statistics.txtThis file defines a code 184 request for traffic statistics from a Network Traffic Director (NTD). (NTDs are only present on Data Highway I network areas.) The response message from this request includes average NTD scan time, local area scan times, packets received by each network device and LTD, busy messages sent to each network device and LTD, received OKs sent to each network device and LTD, and packets sent and received by the NTD.

IFC_UOC_Detailed_Status.txtThis file defines a code 178 request for detailed device status and the response message structure expected from an Integrated Function Controller (IFC) or Unit Operation Controller (UOC). The response contains 5-second average load, 1-minute average load, amount of free memory, number of free message slots, and number of additional devices that the IFC/UOC can report to, and so forth.

MUX_Detailed_Integrity.txtThis file defines a code 179 request for detailed internal integrity and the response expected from a Multiplexer. The individual multiplexer internal integrity bits are decoded as individual fields. The 16 file select and file status fields are not defined in this file.

Creation or Modification of Request/Response Definition Files

To assist with the creation or modification of request/response definition files, two utility programs are included with the Interface. Both utility programs are intended to be run from a command prompt. In the discussions of the two utilities, the usage summaries and examples show options introduced by a minus sign. The utility programs also recognize “/” as an option indicator, as does CHIPtoPI.

CheckformatThe first utility is Checkformat. This utility performs a syntax check on one or more request/response definition files using the same parsing code as the Interface. Thus, Checkformat can verify that a request/response definition is valid before the file is used with the actual Interface. The usage summary for this utility is:checkformat [ -v | -d ] file(s) ...

The arguments in square brackets are optional and control the amount of output from the utility. When the options are not used, Checkformat is terse unless errors are detected. The -v (verbose) option enables informational messages about the progress of parsing. The –d (debug) option enables the most detailed level of output; this option is primarily intended to



assist the developer with debugging and testing. If more than one of these options is used, the rightmost one has precedence. One or more files may be specified. For example:checkformat Device_Type.txt IFC_UOC_Detailed_Status.txtFile "Device_type.txt" has been checked.File "IFC_UOC_Detailed_Status.txt" has been checked.

ChipsendreqThe second utility is Chipsendreq. This utility uses a definition file to send a request to a PROVOX device. The field values from the resulting response message are displayed. This utility allows a definition file to be tested with an actual PROVOX device before configuring points for the Interface. The usage summary for this utility is:chipsendreq [ -v ] –h highway –d device –f file

The highway and device parameters are the PROVOX Data Highway address of the device to which the request message defined in file is to be sent. The –v (verbose) argument is optional. Without –v, the utility outputs error messages and the values from the response fields. The –v option enables detailed progress messages that are primarily intended to assist the developer with debugging and testing. However, the -v option output includes a combined decimal and hexadecimal dump of the request and response I-frames that may be useful to a request/response definition file developer. To demonstrate this utility, the file Device_Type.txt will be used to obtain the type of PROVOX device at Data Highway address @2-17. The Device_Type.txt file contains:# Request 128 - Device Type Requestrequest: 128 # Device Type Request2 # I-frame contains one point numbershort 0 # point 0 is the device itselfresponse:ResponseCode 0 byte #Request CodeUnusedByte1 1 byte #UnusedByte2 2 byte #DeviceType 3 byte #

The command line and output from the utility follow:chipsendreq -h2 -d17 -f Device_Type.txt

Device Type RequestResponse from request 128 to @2-17field index value descriptionResponseCode 1 128 Request CodeUnusedByte1 2 0UnusedByte2 3 0DeviceType 4 196

From Chapter 4 of the Technical Reference for CHIP, the value 196 for the “DeviceType” field indicates that the device at Highway address @2-17 is a UOC.

58

Chapter 9. Startup Command File

Command-line parameters can begin with a / or with a -. For example, the /ps=M and -ps=M command-line parameters are equivalent.

For Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of 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.

The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the interface startup command file.

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 (CHIPtoPI.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file and the module database. The procedure below describes the necessary steps for using PI ICU to configure the CHIPtoPI Interface.

From the PI ICU menu, select Interface, then NewWindows Interface Instance from EXE..., and then Browse to the CHIPtoPI.exe executable file. Then, enter values for Host PI System, 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 Add.

The following message should appear:

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, to configure the Interface to communicate with a remote PI Server, select Connections… from the PI ICU Interface menu and select the default server. If the remote node is not present in the list of servers, it can be added.

Once the Interface is added to PI ICU, near the top of the main PI ICU screen, the Interface Type should be CHIPtoPI. If not, use the drop-down box to change the Interface Type to be CHIPtoPI.

Click Apply to enable the PI ICU to manage this instance of the CHIPtoPI Interface.

The next step is to make selections in the interface-specific tab (that is, “CHIPtoPI”) that allow the user to enter values for the startup parameters that are particular to the CHIPtoPI Interface.


Since the CHIPtoPI Interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt page. This page allows the user to access UniInt features through the PI ICU and to make changes to the behavior of the Interface.

To set up the Interface as a Windows Service, use the Service page. This page allows configuration of the Interface to run as a service as well as to starting and stopping of the interface service. The Interface can also be run interactively from the PI ICU. To do that, open the Interface menu and then click Start Interactive.

For more detailed information on how to use the above-mentioned and other PI ICU pages and selections, please refer to the PI Interface Configuration Utility User Manual. The next section describes the selections that are available from the CHIPtoPI page. Once selections have been made on the PI ICU GUI, press the Apply button in order for PI ICU to make these changes to the interface’s startup file.


Startup Command File

CHIPtoPI Interface Page

Since the startup file of the CHIPtoPI Interface is maintained automatically by the PI ICU, use the CHIPtoPI page to configure the startup parameters and do 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.

CHIPtoPI

The CHIPtoPI ICU Control for PI ICU has 3 sections/tabs. A yellow text box indicates that an invalid value has been entered or that a required value has not been entered.

General

Allow highway outputsAllow highway outputs enables Highway Outputs. The command line equivalent is /hiway.

Toggle Chip Questionable statusIf this is checked the Interface will toggle the CHIP questionable status. The command line equivalent is /TCQ.

62

Pause before loading CHIP pointsThis tells the Interface to pause x milliseconds before loading the CHIP points to allow for the CHIP database to startup fully. The default is not to pause on startup. The command line equivalent is /sp=x, where x is the number of milliseconds to pause before loading CHIP points.

Update DBIs everyIn the Update DBIs every x hours box, x can be any integer from 1 to 24. The default is to update DBIs once every 24 hours. The command line equivalent is /udbi=x, where x is how often in hours to update the DBIs.

Number of times to retry a failed DDP readIn the Number of times to retry a failed DDP read box, x can be any integer from 1 to 6. The default is 1 retry. The command line equivalent is /ddprr=x, where x is how many read retries to perform.

Directory containing request/response definition filesIf the request/response feature of the CHIPtoPI Interface is to be used, then this field must contain the path to the directory where the request/response definition files are stored. The command line equivalent is /rrdir=x, where x is the path to the directory where the request/response definition files are stored.

Failover



A detailed discussion of failover can be found later in this manual in the Interface-Level Failover Using Microsoft Cluster chapter.

Enable Interface-Level Failover using Microsoft ClusteringIf checked, this allows for failover to be configured using Microsoft Clustering.

This is the Primary nodeOne node must be marked primary. If this is the primary Interface, check the This is the Primary Node check box. The name of the primary node may optionally be entered. The command line equivalent is /primary[=nodename].

Secondary CHIP addressThis is required only on the primary interface node and is the CHIP address of the secondary node. The first box is the highway number. The second box is the device number. The CHIP address can be retrieved by running CHIP_UTIL on the secondary node and selecting option 1: CHIP Utilities Menu 1 - CHIP_DB_UTIL - CHIP Local Utilities Menu 2 - CHIP_SYS_UTIL - PROVOX System Utilities Menu 3 - QUIT - or Press Return to QUIT Enter number of your choice:

Then select option 6: CHIP Local Utilities Menu 1 - FSLOG - CHIP Error Logging Program 2 - SMRY - CHIP Database Summary 3 - POINT_UTIL - View and Operate on CHIP Database Points 4 - HIFSTATS - View Highway Interface Statistics 5 - CHIPTASKS - Monitor Status of CHIP Programs 6 - OUR_ADDR - Address of this CHIP 7 - REV_LVL - Revision and DB Info of this CHIP 8 - CLEAR_DB - Clear ERR flag on CHIP Points 9 - QUIT - or Press Return to QUIT Enter number of your choice:

And the CHIP address will be displayed:The Address of This CHIP Device is: @1- 0

The command line equivalents are /fosh=# and /fosd=#, respectively.

Maximum attempts to stop APIOnlineThe Maximum attempts to stop APIOnline sets the number of tries to stop the APIOnline process during an attempted failover. The command line equivalent is /foasa=x, where x is the maximum number (default: 40).

Health Tag IDThis command-line parameter is used to specify a unique ID for interfaces that are run in a redundant mode without using the UniInt failover mechanism. In order for health tag(s) to be configured to monitor a single copy of the Interface, an additional parameter is required. If this command line parameter is specified, only health tags with a location3 equal to this value will be loaded (/UHT_ID=#).

64

Failover numberThe Failover number only applies to failover on Windows. The failover number is the number assigned to APIOnline process which is monitored by the Cluster for failover. See the discussion in the APIOnline# section. The command line equivalent is /fo=#, where # is the failover number.

Other failover nodeThe Other failover node parameter is required on both failover nodes. This is the computer name of the other node in the failover pair. The command line equivalent is /secn=nodename, where nodename is the computer name of the other node.

Failover tagThe Failover tag is required on both failover nodes. The failover tag must be digital and needs to have at least two states – one state to identify each of the two failover nodes. The ‘…’ button invokes the tag search dialog so that a failover tag can be selected, if one already exists. The command line equivalent is /ft=tagname, where tagname is the name of the digital failover tag.

Digital stateThe failover tag’s Digital state is required on both nodes in a failover setup. It is the digital state from the failover tag’s digital state set that is assigned to this node as a flag that indicates which Interface is collecting data. The command line equivalent is /fds=digitalstate, where digitalstate is the digital state.

Error thresholdThe Error threshold is the number of consecutive error 9s – Fisher CHIP communication errors – that can be received in one scan loop before the Interface assumes that the communication errors indicate that this node’s connection to the Data Highway is down. This feature allows the Interface to exit in the middle of a scan loop. Between scans, the primary copy of the Interface checks the connection to the Data Highway and initiates failover if necessary. The command line equivalent is /fo9=x, where x is the number of error 9s. The minimum value if used is 1, default: not used.

Pause between highway communication checksThe Pause between highway communications checks specifies how many seconds must elapse between highway communication checks. The command line equivalent is /fosh=x, where x is the number of seconds to pause between checks (default: 60).



Debug Levels

The Debug Level parameter is used to set a debug level for debug messaging. Check all types of debug messages that you would like to see logged. Any combination of debug levels can be applied. The command line equivalent is /db=x, where x indicates the level of debug messaging.

Additional ParametersThis section is provided for any additional parameters that the current ICU Control does not support.

Note: The UniInt Interface User Manual includes details about other command-line parameters, which may be useful.

66

Command-line Parameters

Parameter Description

/CacheModeOptionalDefault: Not Defined

Required for disconnected startup operation. If defined, the /CacheMode startup parameter indicates that the Interface will be configured to utilize the disconnected startup feature.

/CachePath=pathOptionalDefault: Not Defined

Used to specify a directory in which to create the point caching files. The directory specified must already exist on the target machine. By default, the files are created in the same location as the interface executable.If the path contains any spaces, enclose the path in quotes.Examples:/CachePath=D:\PIPC\Interfaces\CacheFiles/CachePath=D:/PIPC/Interfaces/CacheFiles/CachePath=D:/PIPC/Interfaces/CacheFiles/

Examples with space in path name:/CachePath="D:\Program Files\PIPC\MyFiles"/CachePath="D:/Program Files/PIPC/MyFiles"/CachePath="D:/Program Files/PIPC/MyFiles/"

/CacheSynch=#OptionalDefault: 250 ms

NOTE: Care must be taken when modifying this parameter. This value must be less than the smallest scan class period defined with the /f parameter. If the value of the /CacheSynch parameter is greater than the scan class value, input scans will be missed while the point cache file is being synchronized.The optional /CacheSynch=# startup parameter specifies the time slice period in milliseconds (ms) allocated by UniInt for synchronizing the interface point cache file with the PI Server. By default, the Interface will synchronize the point cache if running in the disconnected startup mode. UniInt allocates a maximum of # ms each pass through the control loop synchronizing the interface point cache until the file is completely synchronized. Synchronization of the point cache file can be disabled by setting the value /CacheSynch=0. The minimum synchronization period when cache synchronization is enabled is 50ms Whereas, the maximum synchronization period is 3000ms (3s). Period values of 1 to 49 will be changed by the Interface to the minimum of 50ms and values greater than 3000 will be set to the maximum interval value of 3000ms. Default: 250 msRange: {0, 50 – 3000} time in millisecondsExample: /CacheSynch=50 (use a 50ms interval) /CacheSynch=3000 (use a 3s interval) /CacheSynch=0 (do not synchronize the cache)



Parameter Description/db=level

OptionalDefault: No debugging

The /db parameter is used to set a debug level for debug messaging. Level is a 32-bit integer. Setting a particular bit in level to 1 turns on a particular debug parameter. To turn on every debug parameter specify:/db

or /db=-1

To turn off all debug messaging, either remove the /db from the command line, or specify:/db=0Note that level can be specified as a decimal, octal, or hexadecimal number. Octal numbers are indicated by a leading 0 and hexadecimal numbers are indicated by a leading 0x.Any combination of debug levels can be applied. For example, to turn on debug messaging for inputs and failover, specify:/db=20

0 No debug messages written1 Initialization2 Point adds, edits, and deletes4 Inputs8 Outputs16 Failover64 All onInstead of using the /db parameter to trace inputs and outputs, consider per-point tracing controlled by the SquareRoot attribute. See SquareRoot.

/ddprr=x

OptionalDefault: /ddprr=1

The /ddprr= parameter sets the number of times that a DDP read failure is retried before setting the point to a digital state indicating an error. The allowed range for x is 1 to 6. If this parameter is not specified, the default number of DDP read retries is one.

/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 the # 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, every interface that is running without /ec=# explicitly defined will write to the same I/O Rate point. Either explicitly define an event counter other than 1 for each instance of the Interface or do 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 Point.For interfaces that run on Windows nodes, subsequent instances of the /ec parameter may be used by specific interfaces to keep track of various input or output operations. Subsequent instances of the /ec parameter can be of the form /ec*, where * is any ASCII character sequence. For example, /ecinput=10, /ecoutput=11, and /ec=12 are legitimate choices for the second, third, and fourth event counter strings.

/f=SS.## or/f=SS.##,ss.##or

The /f parameter defines the time period between scans in terms of hours (HH), minutes (MM), seconds (SS) and sub-seconds (##). 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), seconds (ss) and sub-seconds (##). If HH and MM

68


/f=HH:MM:SS.##or/f=HH:MM:SS.##,hh:mm:ss.##

Required for reading scan-based inputs

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 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:07or, equivalently:/f=60,5 /f=7The 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) + offsetwhere n is an integer and the reference time is midnight on the day that the Interface was started. In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class. This means that if the Interface was started at 05:06:06, the first scan would be at 05:07:05, the second scan would be at 05:08:05, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined.The definition of a scan class does not guarantee that the associated points 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 “Performance Summaries” in the UniInt Interface User Manual.doc for more information on skipped or missed scans.Sub-second Scan ClassesSub-second scan classes can be defined on the command-line, such as/f=0.5 /f=00:00:00.1where the scanning frequency associated with the first scan class is 0.5 seconds and the scanning frequency associated with the second scan class is 0.1 of a second.Similarly, sub-second scan classes with sub-second offsets can be defined, such as/f=0.5,0.2 /f=1,0Wall Clock SchedulingScan 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 saving time. For example, /f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a Daylight Saving 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 saving time), 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.



Parameter Description/fds=state

Cluster failover onlyRequired

Required on both the primary and secondary nodes in a Cluster failover setup. State is the digital state from the failover tag’s digital state set that the Interface writes to the failover tag when this node is collecting. See the section entitled Failover Tag on setting up the failover tag and the digital state set for this tag: /fds=wolverine

/fo=x

Cluster failover onlyRequired on primary and secondary nodes

X is the number assigned to APIOnline. See the APIOnline# section for more information on what number to use for x.

/fo9=#

Cluster failover onlyOptional

This parameter tells the Interface how many consecutive Communication Errors (error 9’s) the Interface can receive when it is running in Cluster failover mode before it exits out of the current scan loop to check if its connection to the CHIP data highway is good. The default value for this parameter is 0 (no limit).

/foasa=#

Cluster failover onlyOptional on primary nodeDefault: /foasa=60

/foasa is optional and applies only to the primary Interface. This overrides the default setting of 40 stop attempts when the primary Interface attempts to stop the APIOnline process either on the primary or secondary node: /foasa=60

/fohm=#

Cluster failover onlyOptional on primary nodeDefault: /fohm=60

This parameter overrides the default setting of 60 seconds between checks to verify communication with the Data Highway. Valid range for # is 1 to 1800 seconds. The highway communication test can be slow. Setting /fohm to a small value can cause fast scan classes to miss scans.

/fosd=#

Cluster failover onlyRequired on primary node

This parameter is required only on the primary node in a Cluster failover setup. This is the device number of the secondary node HDL: /fosd=0

/fosh=#


This parameter is required only on the primary node in a Cluster failover setup. This is the highway number of the secondary node HDL: /fosh=1

/ft=tagname

Cluster failover onlyRequired

Required on both nodes in a Cluster failover setup. Tagname is the name of the digital failover tag on the PI Server that records which node is currently collecting: /ft=chipfailtag

/hiway

OptionalDefault: Highway outputs not allowed.

Enables Highway Outputs.

70


/host=host:portRequired

The /host parameter is used to specify the PI Home node. Host is the IP address of the PI Server node or the domain name of the PI Server node. Port is the port number for TCP/IP communication. The port is always 5450. 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.If the Interfaces is part of a failover configuration that is sending data to a PI Server collective, the value of the /host parameters on the two Interface Nodes must specify different members of the collective. This configuration ensures that outputs continue to be sent to the Data Source if one of the PI Servers becomes unavailable for any reason.

Examples:

The Interface is running on a PI Interface Node, the domain name of the PI 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=xHighly Recommended

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 Appendix A 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 instance number that corresponds to an integer value that is assigned to Location5 point attribute. For this Interface, use only numeric characters in the identifier. For example,/id=1

/primary


Required on primary node in Cluster failover setup; this parameter must not be specified on the secondary node. This parameter tells the Interface that this node is the primary node in a Cluster failover setup. You can optionally specify the name of this node like this: /primary=wolverine

/ps=xRequired

The /ps parameter specifies the point source for the Interface. X is not case sensitive and can be any <single/multiple> character string. For example, /ps=P and /ps=p are equivalent.The point source that is assigned with the /ps parameter corresponds to the PointSource attribute of individual PI Points. The Interface will attempt to load only those PI points with the appropriate point source. If the PI API version being used is prior to 1.6.x or the PI Server version is prior to 3.4.370.x, the PointSource is limited to a single character unless the SDK is being used.



Parameter Description/rrdir=dir

OptionalDefault: Assume ExDesc has absolute file names.

The /rrdir= parameter provides the default directory path to use with request/response points that have a relative definition file name. The syntax of dir must be suitable for pre-pending to a relative file name. That is, dir must end with “/” or “\”.Details on how this parameter affects the Interface can be found in the PI Point Configuration chapter under ExDesc.

/secn=nodename

Cluster failover onlyRequired on primary and secondary node

The parameter is required on both nodes in a failover setup to indicate the name of partner node. For instance, the primary node wolverine might specify /secn=dragon in which case the secondary node, dragon, would use /secn=wolverine.

/sioOptionalDefault: Send output values at startup and when an output tag is edited.

The /sio parameter stands for “suppress initial outputs.” The parameter applies only for interfaces that support outputs. If the /sio parameter is not specified, the Interface will behave in the following manner.When the Interface is started, the Interface determines the current Snapshot value of each output tag. Next, the Interface writes this value to each output tag. In addition, whenever an individual output tag is edited while the Interface is running, the Interface will write the current Snapshot value to the edited output tag.This behavior is suppressed if the /sio parameter is specified on the command-line. That is, outputs will not be written when the Interface starts or when an output tag is edited. In other words, when the /sio parameter is specified, outputs will only be written when they are explicitly triggered.

/sp=x

OptionalDefault: Do not pause on startup.

This tells the Interface to pause x milliseconds before loading the CHIP DB points to allow for CHIP to startup fully.

72


/stopstat=digstateor/stopstat

/stopstat only is equivalent to/stopstat="Intf Shut"

OptionalDefault = no digital state written at shutdown.

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. . UniInt will use the first occurrence of digstate found in the table.If the /stopstat parameter is present on the startup command line, then the digital state Intf Shut will be written to each PI Point when the Interface is stopped. 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.

Note: The /stopstat parameter is disabled if the Interface is running in a UniInt failover configuration as defined in the UniInt Failover Configuration chapter of this manual. Therefore, the digital state, digstate, will not be written to each PI Point when the Interface is stopped. This prevents the digital state being written to PI Points while a redundant system is also writing data to the same PI Points. The /stopstat parameter is disabled even if there is only one interface active in the failover configuration.

Examples:/stopstat=shutdown/stopstat="Intf Shut"The entire digstate value must be enclosed in double quotes when there is a space in digstate.

/tcq

OptionalDefault: Ignore the CHIP questionable status.

The /tcq parameter stands for “Toggle Chip Questionable status.” If the /tcq parameter is present, the Interface will set the questionable bit on the CHIP tag in the local CHIP database when outputs fail and will clear the questionable bit on this tag when the next successful output is written

/udbi=x

OptionalDefault: Update DBIs once every 24 hours.

Update DBIs every x hours. X can be any number from 1 to 24.

/UFO_ID=#Required for UniInt Failover Phase 1 or 2

Failover ID. This value must be different from the Failover ID of the other Interface in the failover pair. It can be any positive, non-zero integer.

/UFO_Interval=#Optional for UniInt failoverDefault: 1000Valid values are 50-20000.

This Interface does not support unsolicited input interface failover control tags and therefore does not use this command line parameter to control the update interval. The failover control points must be scanned and the failover update interval is determined by the scan class of the failover control points.

/UFO_OtherID=#Required for UniInt Failover Phase 1 or 2

Other Failover ID. This value must be equal to the Failover ID configured for the other Interface in the failover pair.




/uht_id=#OptionalRequired if any type of failover other than UniInt Failover Phase 1 or 2 is supported.

The /uht_id=# command-line parameter is used to specify a unique ID for interfaces that are run in a redundant mode without using the UniInt failover mechanism. There are several OSIsoft interfaces that are UniInt based and implement their own version of failover, including the CHIPtoPI Interface. In order for health tag(s) to be configured to monitor a single copy of the Interface, an additional parameter is required. If /uht_id=# is specified, only health tags with a Location3 value equal to # will be loaded.

Sample PICHIPtoPI.bat File

The following is an example file:REM=======================================================================REMREM CHIPtoPIbatREMREM Sample startup file for the Fisher-Rosemount CHIP REMREM=======================================================================REM REM OSIsoft strongly recommends using PI ICU to modify startup files.REMREM Sample command lineREM CHIPtoPI ^ /ps=CHIPtoPI ^ /id=1 ^ /host=XXXXXX:5450 ^ /f=00:00:10,21:00:05 ^ /f=00:00:12,00:00:00REMREM End of CHIPtoPI.bat File

74

Chapter 10. Failover Overview

A failover configuration increases the reliability of data collection from the PROVOX system. The CHIPtoPI Interface supports two types of failover:

UniInt Failover: CHIPtoPI Interface version 2.9.2.0 and later supports UniInt Phase 1 Failover.

Microsoft Cluster Interface-Level Failover

OSIsoft recommends UniInt Failover for new failover implementations.

Both types of failover are discussed in the following chapters.

Both types of failover require compatible CHIP databases on the redundant nodes (except for the CHIP exception reporting parameters). For every CHIP point that has a PI input or output point, the CHIP point must have the same database index (DBI) or CHIP tag name in both CHIP databases.

Comparison of Failover Mechanisms

As explained in the UniInt Failover Configuration chapter, UniInt failover is designed to prevent loss of data when a failure occurs. In comparison, Cluster failover can lose one or more scans when a failure occurs. To achieve the UniInt failover design goal, both Interfaces in a UniInt failover pair actively read from CHIP. Only one Interface in a Cluster failover pair actively reads from CHIP. This difference between the failover mechanisms is not significant for PI points that read from the cached values in the CHIP database. That is, traffic on the PROVOX data highway is not affected by scanning local CHIP points or remote points that are configured for unsolicited reporting. On the other hand, the effect of the two failover mechanisms on PROVOX data highway traffic is different when scanning PROVOX tags that require highway reads (that is, solicited reporting). When highway reads are required, both Interfaces in a UniInt failover pair add traffic to the data highways. With a Cluster failover pair, only the scanning Interface adds traffic to the data highways. That is, the price of not losing scans with UniInt failover is extra data highway traffic for PROVOX tags that require highway reads. Unless the data highways are heavily loaded and data is collected from a large number of tags that require highway reads, the additional highway traffic may not be significant.

The two failover mechanisms handle output points differently. Each of the Interfaces in a failover pair is associated with a CHIP, which is a combination of software and hardware. The two CHIPs are actually two distinct devices in the PROVOX system. Therefore, writing to a local point in one CHIP does not affect local points in the other CHIP. In a Cluster failover pair, both Interfaces in the pair write output data to the respective CHIP. In a UniInt failover pair, only the active Interface writes output data to CHIP (except the UniInt failover control points, which are written by both Interfaces). If some PROVOX devices (consoles or


controllers) are reading the local points in one CHIP and other PROVOX devices are reading the corresponding local points in the other CHIP, then the values from PI output points are available only to the PROVOX devices that read from the CHIP for the active Interface in a UniInt failover pair.

Two recommendations for handling output point with UniInt failover are:

Instead of local CHIP points for outputs from PI, create the PROVOX points that are written by PI in PROVOX devices other than CHIP. Include remote point definitions for these PROVOX points in the two CHIP databases. If either Interface in a UniInt failover pair writes to the remote point in CHIP, the value is sent to the remote point. Other PROVOX devices that need the PI output value can configure unsolicited reporting (or solicited read) from the remote point, which may be defined in a redundant device pair.

Note: The UniInt failover control points described in the UniInt Failover Configuration chapter must be in PROVOX devices other than CHIP.

For each UniInt failover pair, create another non-failover pair of CHIPtoPI Interfaces, which will service only outputs to local CHIP points, on the same computers as the UniInt failover pair. Configure the non-failover pair with the same point source (/ps) and interface ID (/id). If the failover pair and non-failover pair share the same point source, the interface ID must be different. For example, assign ID 1 to both Interfaces in the UniInt failover pair and assign ID 2 to both Interfaces in the non-failover pair. Except for the failover-specific interface parameters, use the same interface parameters for the non-failover pair as for the UniInt failover pair. Omit all failover-specific interface parameters (/UFO_ID, /UFO_OtherID, and so forth) from the interface parameters for the non-failover pair. Configure all input PI points and outputs to remote CHIP points to use the UniInt failover pair. Configure all outputs to local CHIP points to use the non-failover pair. With this approach, the active Interface in the UniInt failover pair services input points and remote outputs while the two Interfaces in the non-failover pair simultaneously update local points in the two CHIPs.

The following table summarizes the differences between UniInt and Cluster failover mechanisms.

UniInt Failover Cluster Failover

Both Interfaces read input values Only the scanning Interface reads input values

No data loss on failure Lost scans on failure

More PROVOX data highway traffic for PI points that require highway reads.

Outputs to local CHIP points only update one CHIP

Outputs to local CHIP points update both CHIPs


Chapter 11. UniInt Failover Configuration

Introduction

To minimize data loss during a single point of failure within a system, UniInt provides two failover schemes: (1) synchronization through the data source and (2) synchronization through a shared file. Synchronization through the data source is Phase 1, and synchronization through a shared file is Phase 2.

Phase 1 UniInt Failover uses the data source itself to synchronize failover operations and provides a hot failover, no data loss solution when a single point of failure occurs. For this option, the data source must be able to communicate with and provide data for two Interfaces simultaneously. Additionally, the failover configuration requires the Interface to support outputs.

Phase 2 UniInt Failover uses a shared file to synchronize failover operations and provides for hot, warm, or cold failover. The Phase 2 hot failover configuration provides a no data loss solution for a single point of failure similar to Phase 1. However, in warm and cold failover configurations, you can expect a small period of data loss during a single point of failure transition.

Note: This Interface supports only Phase 1 failover.

You can also configure UniInt failover to send data to a High Availability (HA) PI Server collective. The collective provides redundant PI Servers to allow for the uninterrupted collection and presentation of PI time series data. In an HA configuration, PI Servers can be taken down for maintenance or repair. The HA PI Server collective is described in the PI Server Reference Guide.

When configured for UniInt failover, the Interface routes all PI data through a state machine. The state machine determines whether to queue data or send it directly to PI depending on the current state of the Interface. When the Interface is in the active state, data sent through the Interface gets routed directly to PI. In the backup state, data from the Interface gets queued for a short period. Queued data in the backup Interface ensures a no-data loss failover under normal circumstances for Phase 1 and for the hot failover configuration of Phase 2. The same algorithm of queuing events while in backup is used for output data.


Quick OverviewThe Quick Overview below may be used to configure this Interface for failover. The failover configuration requires the two copies of the Interface participating in failover be installed on different nodes. Users should verify non-failover Interface operation as discussed in the Installation Checklist chapter of this manual prior to configuring the Interface for failover operations. If you are not familiar with UniInt failover configuration, return to this section after reading the rest of the UniInt Failover Configuration chapter in detail. If a failure occurs at any step below, correct the error and start again at the beginning of step 6 Test in the table below. For the discussion below, the first copy of the Interface configured and tested will be considered the primary Interface and the second copy of the Interface configured will be the backup Interface.

ConfigurationOne Data Source

Two Interfaces

PrerequisitesInterface 1 is the primary Interface for collection of PI data from the data source.

Interface 2 is the backup Interface for collection of PI data from the data source.

Phase 1: The data source must be configured with six failover tags (input and output tags for three tag types):

(1) Active ID.

(2) Heartbeat for Interface 1.

(3) Heartbeat for Interface 2.

Each Interface must be configured with two required failover command line parameters: (1) its FailoverID number (/UFO_ID); (2) the FailoverID number of its backup Interface (/UFO_OtherID). You must also specify the name of the PI Server host for exceptions and PI tag updates.

All other configuration parameters for the two Interfaces must be identical.


Synchronization through the Data Source (Phase 1)

Figure 1: Failover Architecture Phase 1 – Synchronization through the Data Source

Figure 1 shows Phase 1 failover architecture. The diagram shows a typical network setup. This by no means represents the myriad possible network configurations; it is an example only for the following discussions. This example is explained in greater detail after the discussion of the start-up parameters, data source points, and PI tags.


UniInt Failover Configuration

Configuring Synchronization through the Data Source (Phase 1)

Step Description

1. Verify non-failover Interface operation as described in the Installation Checklist section of this manual

2. Configure Points on the Data SourceCreate three points (Active ID, Heartbeat 1 and Heartbeat 2) on the data source. The Interface must be able to read from and write to these points. The ActiveID must accept values from 0 to the highest failover ID. The two heartbeat points must accept values from 0 to 31. The UniInt failover control points must be accessible for reading from and writing to by both copies of the CHIPtoPI Interface. If the two CHIPtoPI Interfaces are on different Interface Nodes, these points must be created in PROVOX devices other than CHIP. If the two Interfaces are on the same node (which is discouraged because the Interface Node computer and CHIP are not redundant), these points can exist in the local CHIP database or in remote PROVOX devices. See the Data Source Points section below.

3. Use the Interface Configuration Utility to configure the interface parameters Enable failover by selecting Enable UniInt Failover in the Failover section of the Interface Configuration Utility (ICU) and assign the appropriate number for the two Failover IDs: (1) a Failover ID number for the Interface; and (2) the Failover ID number for its backup Interface.The Failover ID for each Interface must be unique and each Interface must know the Failover ID of its backup Interface.All other command line parameters for the primary and backup Interfaces must be identical.If you are using a PI Collective, you must specifically set the /host parameter for the primary and backup Interfaces to different members of the collective.[Optional] Set the update rate for the heartbeat point if the input tags are unsolicited.

4. Configure the PI tagsYou must configure six PI tags for the Interface (input and output tags for each of the three failover points on the data source). For more information about configuring input and output points, refer to the Interface Manual.You can also configure two state tags for monitoring the status of the Interfaces.

Tag ExDesc digitalset

The remaining attributes must be configured according to the interface manual so the tags map to the correct points on the data source.

ActiveID_In [UFO_ACTIVEID]

ActiveID_Out [UFO_ACTIVEID]

IF1_HB_In(IF-Node1)

[UFO_HEARTBEAT:#]

IF1_HB_Out(IF-Node1)

[UFO_HEARTBEAT:#]

IF2_HB_In(IF-Node2)

[UFO_HEARTBEAT:#]

IF2_HB_Out(IF-Node2)

[UFO_HEARTBEAT:#]

IF1_State(IF-Node1)

[UFO_STATE:#] IF_State

IF2_State(IF-Node2)

[UFO_STATE:#] IF_State

80

Step Description5. If using PI APS versions earlier than 1.2.4.0 to synchronize the Data Source and PI

points, special attention must be paid to the failover control points and tags. Synchronizing the control points will cause the failover tags to be edited by PI APS and may result in possible interface shutdown.

6. Test the configuration. Run the Interface with the six Failover Control PI tags to ensure their proper operation.Start the primary Interface interactively without buffering.Verify a successful interface start by reviewing the pipc.log file. The log file will

contain messages that indicate the failover state of the Interface. A successful start with only a single interface copy running will be indicated by an informational message stating “UniInt failover: Interface in the “Primary” state and actively sending data to PI. Backup interface not available.” If the Interface has failed to start, an error message will appear in the log file. For details relating to informational and error messages, refer to the Messages section below.

For example, verify data in CHIP. The Active ID control point in CHIP must be set to the value of the running copy of

the Interface as defined by the /UFO_ID startup command-line parameter.

The Heartbeat control point in CHIP must be changing values at a rate specified by the /UFO_Interval startup command-line parameter.

Verify data on the PI Server using available PI tools.The Active ID control tag on the PI Server must be set to the value of the running

copy of the Interface as defined by the /UFO_ID startup command-line parameter.

The Heartbeat control tag on the PI Server must be changing values at a rate specified by the /UFO_Interval startup command-line parameter.

Stop the primary Interface.Start the backup Interface interactively without buffering. Notice that this copy will

become the primary because the other copy is stopped.Repeat steps 2, 3, 4 and 5.Stop the backup Interface.Start buffering.Start the primary Interface interactively.Once the primary Interface has successfully started and is collecting data, start the

backup Interface interactively.Verify that both copies of the Interface are running in a failover configuration.

Review the pipc.log file for the copy of the Interface that was started first. The log file will contain messages that indicate the failover state of the Interface. The state of this Interface must have changed as indicated with an informational message stating “UniInt failover: Interface in the “Primary” state and actively sending data to PI. Backup interface available.” If the Interface has not changed to this state, browse the log file for error messages. For details relating to informational and error messages, refer to the Messages section below.

Review the pipc.log file for the copy of the Interface that was started last. The log file will contain messages that indicate the failover state of the Interface. A successful start of the Interface will be indicated by an informational message stating “UniInt failover: Interface in the “Backup” state.” If the Interface has failed to start, an error message will appear in the log file. For details relating to informational and error messages, refer to the Messages section below.



Step Description

For example, verify data in CHIP.The Active ID control point in CHIP must be set to the value of the running copy of

the Interface that was started first as defined by the /UFO_ID startup command-line parameter.

The Heartbeat control points for both copies of the Interface in CHIP must be changing values at a rate specified by the /UFO_Interval startup command-line parameter.

Verify data on the PI Server using available PI tools.The Active ID control tag on the PI Server must be set to the value of the running

copy of the Interface that was started first as defined by the /UFO_ID startup command-line parameter.

The Heartbeat control tags for both copies of the Interface on the PI Server must be changing values at a rate specified by the /UFO_Interval startup command-line parameter or the scan class which the points have been built against.

Test Failover by stopping the primary Interface.Verify the backup Interface has assumed the role of primary by searching the

pipc.log file for a message indicating the backup Interface has changed state: “UniInt failover: Interface in the “Primary” state and actively sending data to PI. Backup interface not available.” The backup Interface is now considered primary and the previous primary Interface is now backup.

Verify no loss of data in PI. There may be an overlap of data due to the queuing of data. However, there must be no data loss.

Start the backup Interface. Once the primary Interface detects a backup Interface, the primary Interface will now change state indicating “UniInt failover: Interface in the “Primary” state and actively sending data to PI. Backup interface available.” in the pipc.log file.

Verify the backup Interface starts and assumes the role of backup. A successful start of the backup Interface will be indicated by an informational message stating “UniInt failover: Interface in “Backup” state.” Since this is the initial state of the Interface, the informational message will be near the beginning of the start sequence of the pipc.log file.

Test failover with different failure scenarios (for example, loss of PI connection for a single interface copy). UniInt failover guarantees no data loss with a single point of failure. Verify no data loss by checking the data in PI and on the data source.

Stop both copies of the Interface, start buffering, start each Interface as a service.Verify data as stated above.To designate a specific Interface as primary, set the Active ID point on the Data Source

Server of the desired primary Interface as defined by the /UFO_ID startup command-line parameter.

82

Configuring UniInt Failover through the Data Source (Phase 1)

Start-Up Parameters

Note: The /stopstat parameter is disabled If the Interface is running in a UniInt failover configuration. Therefore, the digital state, digstate, will not be written to each PI Point when the Interface is stopped. This prevents the digital state being written to PI Points while a redundant system is also writing data to the same PI Points. The /stopstat parameter is disabled even if there is only one Interface active in the failover configuration.

The following table lists the start-up parameters used by UniInt Failover. All of the parameters are required except the /UFO_Interval startup parameter.

Parameter Required/Optional

Description Value/Default

/UFO_ID=# Required Failover ID for IF-Node1 This value must be different from the failover ID of IF-Node2.

Any positive, non-zero integer / 1

Required Failover ID for IF-Node2 This value must be different from the failover ID of IF-Node1.

Any positive, non-zero integer / 2

/UFO_OtherID=# Required Other Failover ID for IF-Node1 The value must be equal to the Failover ID configured for the Interface on IF-Node2.

Same value as Failover ID for IF-Node2 / 2

Required Other Failover ID for IF-Node2 The value must be equal to the Failover ID configured for the Interface on IF-Node1.

Same value as Failover ID for IF-Node1 / 1

/UFO_Interval=# Optional This Interface does not support unsolicited input interface failover control tags and therefore does not use this command line parameter to control the update interval. The failover control points must be scanned and the failover update interval is determined by the scan class of the failover control points.

50 – 20000 / 1000



Parameter Required/Optional

Description Value/Default

/Host=server Required Host PI Server for Exceptions and PI tag updatesThe value of the /Host startup parameter depends on the PI Server configuration. If the PI Server is not part of a collective, the value of /Host must be identical on both interface computers.If the redundant Interfaces are being configured to send data to a PI Server collective, the value of the /Host parameters on the different Interface Nodes must point to different members of the collective.This configuration ensures that outputs continue to be sent to the Data Source if one of the PI Servers becomes unavailable for any reason.

For IF-Node1PrimaryPI / NoneFor IF-Node2SecondaryPI / None

Data Source Points

The following table identifies the points that are required to manage failover and the values used for each PI attribute.

Note: Local points in CHIP are not redundant. Therefore, create the UniInt failover control points in a redundant PROVOX device pair.

The following table explains each of the points required on the data source in more detail.

Point Description Value / DefaultActiveID Monitored by the Interfaces to determine which

Interface is currently sending data to PI. ActiveID must be initialized so that when the Interfaces read it for the first time, it is not an error.ActiveID can also be used to force failover. For example, if the current primary is IF-Node 1 and ActiveID is 1, you can manually change ActiveID to 2. This causes the Interface at IF-Node2 to transition to the primary role and the Interface at IF-Node1 to transition to the backup role.

From 0 to the highest Interface Failover ID number / None)Updated by the redundant InterfacesCan be changed manually to initiate a manual failover

Heartbeat 1 Updated periodically by the Interface on IF-Node1. The Interface on IF-Node2 monitors this value to determine if the Interface on IF-Node1 has become unresponsive.

Values range between 0 and 31 / NoneUpdated by the Interface on IF-Node1

Heartbeat 2 Updated periodically by the Interface on IF-Node2. The Interface on IF-Node1 monitors this value to determine if the Interface on IF-Node2 has become unresponsive.

Values range between 0 and 31 / NoneUpdated by the Interface on IF-Node2

84

PI Tags

The following tables list the required UniInt Failover Control PI tags, the values they will receive, and descriptions.

Active_ID Tag Configuration

Attributes ActiveID IN AcitveID OUT

Tag <Intf>_Active_IN <Intf>_Active_OUT

CompMax 0 0

ExDesc [UFO_ActiveID] [UFO_ActiveID]

Location5 Match # in /id=# Match # in /id=#PointSource Match x in /ps=x Match x in /ps=xPointType Int32 Int32

Shutdown 0 0

Step 1 1

Heartbeat Tag Configuration

Attribute Heartbeat 1 IN Heartbeat 1 OUT Heartbeat 2 IN Heartbeat 2 OUT

Tag <HB1>_IN <HB1>_OUT <HB2>_IN <HB2>_OUT

ExDesc[UFO_Heartbeat:#]Match # in /UFO_ID=#

[UFO_Heartbeat:#]Match # in /UFO_ID=#

[UFO_Heartbeat:#]Match # in /UFO_OtherID=#

[UFO_Heartbeat:#]Match # in /UFO_OtherID=#

Location5 Match # in /id=# Match # in /id=# Match # in /id=# Match # in /id=#Point Source

Match x in /ps=x Match x in /ps=x Match x in /ps=x Match x in /ps=x

Point Type int32 int32 int32 int32

Shutdown 0 0 0 0

Step 1 1 1 1

Interface State Tag Configuration

Attribute Primary Backup

Tag <Tagname1> <Tagname2>

CompMax 0 0

DigitalSet UFO_State UFO_State

ExDesc [UFO_State:#](Match /UFO_ID=# on primary node)

[UFO_State:#](Match /UFO_ID=# on backup node)

Location5 Match # in /id=# Same as for primary node

PointSource Match x in /ps=x Same as for primary node

PointType digital digital

Shutdown 0 0

Step 1 1



The following table describes the extended descriptor for the above PI tags in more detail.

PI Tag ExDesc Required / Optional

Description Value / Default

[UFO_ACTIVEID]

(Used for both the ActiveID IN and OUT tags.)

Required The Active ID Input Tag must be configured as an input PI tag for the Interface and it must be configured to read the ActiveID on the data source.Consult the Interface User’s Manual for a description of configuring input tags. The ExDesc must start with the case sensitive string: [UFO_ACTIVEID]

0 – highest Failover ID / NoneUpdated by the redundant Interfaces

[UFO_HEARTBEAT:#](IF-Node1)

Required The Heartbeat 1 Output Tag must be configured as an output PI tag for the Interface and it must be configured to write to the Heartbeat 1 Point on the Data Source.Consult the Interface User Manual for information about configuring output tags. The ExDesc must start with the case sensitive string: [UFO_HEARTBEAT:#]The number following the colon (:) must be the Failover ID for the Interface running on IF-Node1.

0 – 31 / None Updated by the Interface on Node 1

[UFO_HEARTBEAT:#](IF-Node2)

Required The Heartbeat 2 Input Tag must be configured as an input PI tag for the Interface and it must be configured to read the Heartbeat 2 Point on the Data Source.Consult the Interface User Manual for information about configuring input tags. The ExDesc must start with the case sensitive string: [UFO_HEARTBEAT:#]The number following the colon (:) must be the Failover ID for the Interface running on IF-Node2.

0 – 31 / None Updated by the Interface on Node 2

86

PI Tag ExDesc Required / Optional

Description Value / Default

[UFO_STATE:#](IF-Node1)

Optional The failover state tags are optional and do not require a point on the Data Source. The value of the state tag can be written to the Data Source by configuring a normal interface output tag and setting the SourceTag attribute to the failover state tag. The number following the colon (:) must be the Failover ID for the Interface running on IF-Node1.The failover state tags are digital tags assigned to a digital state set with the following values.0 = Off: The Interface has been shut down.1 = Backup No Data Source: The Interface is running but is unable to communicate to the data source.2 = Backup No PI Connection: The Interface is running and connected to the data source but has lost its communication to the PI Server.3 = Backup: The Interface is running and collecting data normally and is ready to take over if the primary shuts down or experiences problems.4 = Transition: The Interface stays in this state for only a short period of time. The transition period is designed to prevent thrashing when both primary and backup Interfaces attempt to assume the role of the primary Interface.5 = Primary: The Interface is running, collecting data, and sending the data to PI.

0 – 5 / NoneUpdated by the primary Interface

[UFO_STATE:#](IF-Node2)

Optional The failover state tags are optional and do not require a point on the Data Source. The value of the state tag can be written to the Data Source by configuring a normal interface output tag and setting the SourceTag attribute to the failover state tag.The number following the colon (:) must be the Failover ID for the Interface running on IF-Node2.

0 – 5 / NoneUpdated by the backup Interface



Detailed Explanation of Synchronization through the Data Source

Figure 2 Synchronization through Data Source (Phase 1) Failover Architecture

Synchronization through the data source uses two separate Interface Nodes communicating with the data source. The failover scheme requires six tags on the PI Server and three control points on the data source to control failover operation. The PI tags initialize the Interface with configuration information for reading and writing to the control points on the data source. Once the Interface is configured and running, the ability to read or write to the PI tags is not required for failover operation because only the control points on the data source are monitored. However, the PI tag values are sent to the PI Server so that you can monitor them with standard OSIsoft client tools. You can force manual failover by changing the ActiveID on the data source to the backup failover ID.

The figure above shows a typical network in the normal or steady state. This diagram doesn’t represent the myriad configurations that can be supported; it is simply an example for the following discussions. If your hardware configuration differs from the figure, the settings for the primary and backup Interfaces remain the same with the exception of the /host startup parameter. If the Interfaces communicate with a stand-alone PI Server, the /host parameter for both Interfaces must be the same.

To ensure that output to the data source continues when a PI Server in the collective becomes unavailable, the Interface running on the primary node (IF-Node1) needs the /host

88

parameter set to a PI Server that is part of the collective, and the Interface running on the backup node (IF-Node2) needs the /host parameter set to a different PI Server in the same collective.

The continued operation of output when a PI Server becomes unavailable presumes the source data for output data (that is, data read from PI and written to the data source) comes into PI from a process that sends values to all of the PI Servers in the collective via n-way buffering.

The solid red line in the figure shows input data flow when the Interface on IF-Node1 is in the primary state. The data is read from the data source by the Interface and sent to a buffer. Buffering sends the input data to all of the PI Servers in the collective via n-way buffering.

The solid blue line shows output data flow. Since the Interface on IF-Node1 is configured with /host=PrimaryPI, the Interface signs up for exceptions with the PI Server on PrimaryPI. Exceptions are received by the Interface and sent to the data source via the Interface.

The dashed red line shows input data flow to the backup Interface. The dashed line stops at the Interface because the Interface does not send the data to buffering unless the Interface is in the primary state. If the backup Interface transitions to the primary state for any reason, the backup Interface begins to send the input data to buffering. Buffering continues to write the data to all of the PI Servers in the collective via n-way buffering.

The dashed blue line shows output data flow to the backup Interface. The dashed line stops at the Interface because the Interface does not send data to the data source unless the Interface is in the primary state. When the backup Interface becomes the primary for any reason, it begins to send output data to the data source.

In the event that the primary PI Server becomes unavailable for any reason, the primary Interface informs the backup Interface that it has lost its connection to the PI Server. The backup Interface becomes the primary Interface because its status is better than the current primary Interface. However, if the entire network goes off line and both primary and backup Interfaces lose their connection to their respective PI Servers, the primary Interface remains primary because the current status of the backup Interface is the same as the primary, not better. In this case, output data cannot flow to the data source because there is no way for any of the Interfaces to get the exception data.

Steady State Operation

Steady state operation is considered the normal operating condition. In this state, the primary Interface is actively collecting data and sending its data to PI. The primary Interface is also updating its heartbeat point, monitoring the heartbeat point for the backup Interface, and checking the ActiveID every failover update interval. In this state, the backup Interface is actively collecting and queuing data but not sending the received data to PI. It too is updating its heartbeat point, monitoring the heartbeat point for the primary Interface, and checking the ActiveID every failover update interval. As long as the heartbeat point for the primary Interface indicates that it is operating properly and the ActiveID has not changed, the backup Interface will continue in this mode of operation.

The interaction of the control points is fundamental to failover. The discussion that follows only refers to the data written to the control points on the data source. However, every value written to the control points on the data source is echoed to the control tags on the PI Server. Updating of the control tags is assumed to take place unless communication with the



PI Server is interrupted. The updates to the PI Server will be buffered by Bufserv or PIBufss in this case.

Each interface copy participating in the failover solution will queue two failover intervals worth of data to prevent any data loss. When a failover occurs, there may be a period of overlapping data for up to 2 intervals. The exact amount of overlap is determined by the timing and the cause of the failover and may be different every time. Using the default update interval of 1 second will result in overlapping data between 0 and 2 seconds. The no data loss claim is based on a single point of failure. If both Interfaces have trouble collecting data for the same period of time, data will be lost during that time.

As mentioned above, each Interface has its own heartbeat point. In normal operation, the value of the heartbeat point on the data source is incremented by UniInt from 1 – 15 and then wraps around to a value of 1 again. UniInt increments the heartbeat point on the data source every failover update interval. The default failover update interval is 1 second. UniInt also reads the value of the heartbeat point for the other interface copy participating in failover every failover update interval. If the connection to the PI Server is lost, the value of the heartbeat point will be incremented from 17 – 31 and then wrap around to a value of 17 again. Once the connection to the PI Server is restored, the heartbeat values will revert back to the 1 – 15 range. During a normal shutdown process, the heartbeat value will be set to zero.

During steady state, the ActiveID is the failover ID of the primary Interface. This value is set by UniInt when the Interface enters the primary state and is not changed by the primary Interface until it shuts down gracefully. During shutdown, the primary Interface sets the ActiveID to zero before shutting down. The backup Interface can assume control as primary even if the current primary is not experiencing a problem. You can force this transition by setting the ActiveID control point on the data source to the failover ID of the desired Interface.

To prevent data loss during failover, the backup Interface continuously queues data in memory for the two most recent failover update intervals. As long as the backup Interface determines that the primary Interface is in good status, the backup Interface simply maintains this queue with the most recent data. When the backup Interface transitions to primary status, the backup begins transmitting to PI starting with the queued data

90

Failover Configuration Using PI ICU

The use of the PI ICU is the recommended and safest method for configuring the Interface for UniInt failover. With the exception of the notes described in this section, the Interface shall be configured with the PI ICU as described in the Configuring the Interface with PI ICU section of this manual.

Note: With the exception of the /UFO_ID and /UFO_OtherID startup command-line parameters, the UniInt failover scheme requires that both copies of the Interface have identical startup command files. This requirement causes the PI ICU to produce a message when creating the second copy of the Interface stating that the “PS/ID combo already in use by the interface” as shown in Figure 3 below. Ignore this message and click the Add button.

Create the Interface Instance with PI ICU

If the Interface does not already exist in the ICU, it must first be created. The procedure for doing this is the same as for non-failover interfaces. When configuring the second instance for UniInt Failover the Point Source and Interface ID # boxes will be in yellow and a message will be displayed saying this is already in use. This should be ignored.

Figure 3: PI ICU configuration screen shows that the “PS/ID combo is already in use by the interface.” The user must ignore the yellow boxes, which indicate errors, and click the Add button to configure the Interface for failover.



Configuring the UniInt Failover Startup Parameters with PI ICU

There are three interface startup parameters that control UniInt failover: /UFO_ID, /UFO_OtherID, and /UFO_Interval. The UFO stands for UniInt Failover. The /UFO_ID and /UFO_OtherID parameters are required for the Interface to operate in a failover configuration, but the /UFO_Interval is optional. Each of these parameters is described in detail in Configuring UniInt Failover through the Data Source (Phase 1) section and Start-Up Parameters

Figure 4: The figure above illustrates the PI ICU failover configuration screen showing the UniInt failover startup parameters (Phase 1). This copy of the Interface defines its Failover ID as 2 (/UFO_ID=2) and the other interface’s Failover ID as 1 (/UFO_OtherID=1). The other failover interface copy must define its Failover ID as 1 (/UFO_ID=1) and the other interface Failover ID as 2 (/UFO_OtherID=2) in its ICU failover configuration screen.

Creating the Failover State Digital State Set

The UFO_State digital state set is used in conjunction with the failover state digital tag. If the UFO_State digital state set has not been created yet, it can be created using either the Failover page of the ICU (1.4.1.0 or greater) or the Digital States plug-in in the SMT 3 Utility (3.0.0.7 or greater).

92

Using the PI ICU Utility to create Digital State Set

To use the UniInt Failover page to create the UFO_State digital state set, right-click on any of the failover tags in the tag list and then click the Create UFO_State Digital Set on Server XXXXXX… command, where XXXXXX is the PI Server where the points will be or are created.

This command will be unavailable if the UFO_State digital state set already exists on the XXXXXX PI Server.

Using the PI SMT 3 Utility to create Digital State Set

Optionally the Export UFO_State Digital Set (.csv) command can be selected to create a comma-separated file to be imported via the System Management Tools (SMT3) (version 3.0.0.7 or higher) or use the UniInt_Failover_DigitalSet_UFO_State.csv file included in the installation kit.

The procedure below outlines the steps necessary to create a digital set on a PI Server using the “Import from File” function found in the SMT3 application. The procedure assumes the user has a basic understanding of the SMT3 application.

1. Open the SMT3 application.

17. Select the appropriate PI Server from the PI Servers window. If the desired server is not listed, add it using the PI Connection Manager. A view of the SMT application is shown in Figure 5 below.

18. From the System Management Plug-Ins window, select Points then Digital States. A list of available digital state sets will be displayed in the main window for the selected PI Server. Refer to Figure 5 below.

19. In the main window, right-click on the desired server and select the Import from File command. Refer to Figure 5 below.



Figure 5: PI SMT application configured to import a digital state set file. The PI Servers window shows the “localhost” PI Server selected along with the System Management Plug-Ins window showing the Digital States Plug-In as being selected. The digital state set file can now be imported by selecting the Import from File command.

20. Navigate to and select the UniInt_Failover_DigitalSet_UFO_State.csv file for import using the Browse icon on the display. Select the desired Overwrite Options. Refer to Figure 6 below.

Figure 6: PI SMT application Import Digital Set(s) window. This view shows the UniInt_Failover_DigitalSet_UFO_State.csv file as being selected for import. Select the desired Overwrite Options by choosing the appropriate option button.

21. Click on the OK button. Refer to Figure 6 above.

22. The UFO_State digital set is created as shown in Figure 7 below.

94

Figure 7: The PI SMT application showing the UFO_State digital set created on the “localhost” PI Server.



Creating the UniInt Failover Control and Failover State Tags (Phase 1)

The ICU can be used to create a comma-delimited file that contains all of the non-interface specific tag attributes configured correctly for UniInt failover. This file can be edited according to the UniInt failover tag configuration sections above.

In addition, the interface installation kit installs an example file that creates the UniInt failover tags. This example file has most, but not all, of the CHIPtoPI interface-specific attributes configured. After the three required UniInt failover points are created in CHIP, determine the CHIP tag or DBI for the UniInt failover points. Edit the point definitions in the example file. For each PI point, either:

Change the InstrumentTag attribute to the CHIP tag name and change the Location1 attribute to 0.

Change the InstrumentTag attribute to an empty string and change the Location1 attribute to the CHIP point DBI.

To use the ICU Failover page to create this file, simply right-click any of the failover tags in the tag list and select Export Point Configuration then edit this file as needed and import with SMT 3.

After the failover control and failover state tags have been created, the Failover page of the ICU should look similar to the illustration below.

96

Chapter 12. Interface-Level Failover Using Microsoft Cluster

Overview

In a Cluster failover configuration, two copies of the Interface (called a failover pair) are created on two nodes in a Windows cluster. The cluster is configured to monitor and manage cluster resources. A Windows cluster provides high availability for cluster resources by ensuring that one copy of each cluster resource is running in the cluster at all times. If a node in the cluster fails, any cluster resources that were running on the failed node are restarted on an operational cluster node. Similarly, if a cluster resource fails, cluster services restart the cluster resource.

For CHIPtoPI Interface failover, a cluster resource is added to the cluster that indicates the node where the Interface scans and sends data to PI. A copy of the APIOnline service is the actual cluster resource used with the CHIPtoPI failover pair. Cluster services ensure that APIOnline is running on exactly one of the cluster nodes where the CHIPtoPI Interfaces also run. The node where APIOnline is running is the scanning node and the other node is the standby node. Observe that the physical node designated as the scanning node dynamically follows the APIOnline service, which can move to a different physical node as conditions change.

Interface parameters cause the Interfaces in the failover pair to integrate with the Windows cluster. Specifically, each Interface looks for APIOnline on the same node. Only the copy of the Interface on the scanning node (that is, the node where APIOnline is running) reads CHIPtoPI tags and sends the data to PI Server. The copy of the Interface on the standby node does not read from CHIP and does not send data to the PI Server.

In a Cluster failover pair, one of the Interfaces is designated as the primary Interface by an interface parameter. The node that runs the primary Interface is the primary node. The other Interface in the failover pair is called the secondary Interface. The node that runs the secondary Interface is the secondary node. After the Interfaces are configured, the physical nodes designated as primary and secondary are static. That is, the primary node designation is always assigned to the same physical node.

Only the primary Interface verifies the ability to communicate with PROVOX devices on the data highway. Based on the results of the communication test, the primary Interface may change the scanning node by moving the APIOnline cluster resource. That is, the primary Interface may initiate failover.

In idle time between scans, the primary Interface verifies that the local CHIP can communicate with PROVOX devices by sending a request to the CHIP for the secondary copy of the Interface. If the primary Interface receives a response, the primary Interface considers itself healthy.


The primary Interface actively takes the scanning role whenever it can. That is, if the secondary Interface node is the scanning node and the primary Interface is running and the highway communication test succeeds, the primary Interface forces a failover, which makes the primary Interface node the scanning node and the secondary Interface node becomes the standby node.

If the primary Interface node is the scanning node and the communication test fails, the primary Interface assumes that the communication failure prevents collection of current data values from PROVOX devices. Since the primary Interface is unable to collect data, the primary Interface determines if the secondary node may be able to collect data. The primary Interface gets the status of CHIP services on the secondary node. If CHIP services are running on the secondary node, the primary Interface initiates failover. If CHIP services are not running on the secondary node, the secondary node also is unable to collect data and failover is not initiated.

Observe that the secondary Interface does not verify communication with the PROVOX system and never initiates failover. The secondary Interface does nothing more than look for APIOnline on the same node. If APIOnline is running on the secondary Interface node, the secondary node is the scanning node. Therefore, the secondary Interface reads from CHIP at scan times and sends data to the PI Server. Conversely, if the secondary Interface node is the standby node, the secondary Interface does not read from CHIP and does not send data to the PI Server.

Local CHIP outputs (Location2 < 0) are written by both Interfaces regardless of the failover status. This allows PROVUE consoles to read PI outputs from either CHIP system.

A failover digital tag, specified in the /ft= parameter on the command line, specifies a digital tag that keeps the history of which node is collecting data. A digital state belonging to this tag is assigned to each of the two failover nodes, with the command line /fds= parameter, and is the value written for this tag at each failover to track which node is scanning. This digital tag is used only for tracking which node was scanning and when. It does not play a role in determining which node is currently scanning. A value is written to the failover digital tag when failover switches the scanning and standby nodes.

Configuring Cluster Failover

To configure the interface startup file to enable Cluster failover, specify /fo=x on the command line, where x is the number discussed later in the APIOnline# section.

Configure the interface startup file to specify one node as primary (required) by including /primary on the command line of the primary node.

Each copy of the Interface needs to know the name of the other node. This is passed to each Interface with the /secn=remotenode command-line parameter. This is required on both nodes. For example, on the primary node (wolverine), specify /secn=dragon, and on the secondary node (dragon), specify /secn=wolverine.


Failover Tag

Creating the Failover Status TagCHIPtoPI Cluster failover uses a digital state failover status tag to record which node is scanning. This failover digital state tag requires two digital states in its digital state set, one state for each of the two nodes in the failover cluster. For example, if the primary node is wolverine, and the secondary node is dragon, create a failover tag, such as chipfailtag, with wolverine and dragon as its digital states. For this example, the following PIconfig script creates the appropriate digital state set and the failover tag, called chipfailtag, where the failover nodes are wolverine and dragon:* Create chipfostate set@tabl pids@mode create@istr set,state,...chipfostate,wolverine,dragon@ends* Create chipfailtag@tabl pipoint@ptcl classic@mode create@istr tag,pointsource,pointtype,digitalset,compressing,excmaxchipfailtag,L,digital,chipfostate,0,0@ends@bye

Telling the Interface about the Failover Status TagTo configure the interface startup file for the failover tag, specify /ft=failover_tag on the command line. In the example above, this would be /ft=chipfailtag.

To configure the interface startup file for the failover digital state, specify /fds=failover_ds on the command line. In the example above, this would be /fds=wolverine on wolverine and /fds=dragon on dragon. Note that the digital state string is used on the command line, not the corresponding digital state number.

Cluster Failover Requirements

General

Cluster failover requires two PI Interface Nodes that have data highway access and form a Microsoft Windows cluster.

Hardware

Two Windows nodes with hardware that appears on the Microsoft Hardware Compatibility list (http://www.microsoft.com/hwtest/hcl/)

Both nodes must have CHIP installed and running, including a connection to the PROVOX Data Highway.


Interface-Level Failover Using Microsoft Cluster

Software

Both Windows nodes must have the PI API (version 1.2.3.1 or greater) installed.

Both Windows nodes must be running a Windows version that supports server clustering.

Both Windows nodes must have TCP/IP running between them.

Installation Checklist

BufferingIf Buffering is to be used with Cluster failover, a buffering service must be installed on both the primary and the secondary PI Interface Nodes before failover is setup. Buffering must be started before the Interface starts, so the interface service must have a dependency on the buffer service. The buffer service must be configured to start automatically on reboot. For more information about setting up Buffering, see the Buffering chapter.

CHIPtoPI# ServiceThe CHIPtoPI service should be set to automatic, with a dependency on CHIPService and a dependency on Bufserv or PIBufss, if buffering is to be used. For example, the following command creates a CHIPtoPI service with PI API buffering:CHIPtoPI –install –auto –depend "CHIPService bufserv"

Without buffering:CHIPtoPI –install –auto –depend CHIPService

The CHIPtoPI service on the primary node must be modified so that it runs under an account that has permissions to start and stop services on the secondary node. The cluster domain Administrator user should have the permissions required. This change can be made via the Services control panel.

APIOnline#APIOnline is a generic service program that is shared by several interfaces that implement Cluster failover. The interface installation kit distributes the files APIOnline.exe and APIOnline.bat into the interface install directory. These files are used to create a separate instance of the APIOnline service for each Cluster failover pair. The APIOnline service instances are named APIOnline#, where # is a number. Each APIOnline instance must have a unique number. As long as the number is unique, you can assign numbers as you like. If only CHIPtoPI failover pairs are running in the cluster, the recommended number for the APIOnline# service name is the number in the corresponding CHIPtoPI service name.

The Interfaces in a failover pair need the service name of the APIOnline service for the failover pair. For both copies of the Interface, set the number in the CHIPtoPI startup parameter/fo=# to the same number as in the APIOnline# service name.

The APIOnline service program requires parameters to configure each instance of the service for a specific failover pair. An APIOnline service instance obtains parameters from a .bat file that has the same file name as the service .exe file. Since one .bat file cannot contain parameters for multiple APIOnline service instances, copies of the .exe and .bat files are required to create APIOnline service instances. Use the APIOnline# service name as the name of the copies of the files.

100

Copy APIOnline.exe and name the new file APIOnline#.exe. Copy APIOnline.bat and name the new file APIOnline#.bat.

The APIOnline service is configured to depend on the interface service in two places: in the APIOnline service properties and in the /proc=interface parameter in the apionline#.bat file, where interface stands for the name of the interface service which is using Cluster failover.

APIOnline monitors the service specified by the /proc= parameter. If the interface service stops, APIOnline stops. Windows cluster services then attempt to start both again. The node on which these processes are started is determined by how the threshold parameter of the APIOnline cluster resource is configured in the Cluster Administrator. This is discussed later in this section. If APIOnline is started on the former standby node, the standby Interface will start reading values from CHIP and sending data to PI (the standby Interface is always running along with the scanning Interface, but the standby Interface does not send data to PI).

Edit the apionline#.bat file. Change the .exe name and the /proc parameter so that the .bat file contains:Apionline#.exe /proc=CHIPtoPI#

APIOnline must be installed as a service on both cluster nodes. To install APIOnline as a service and make it dependent on the CHIPtoPI service, run the following command from the directory where APIOnline#.exe is installed:APIOnline# -install -depend "CHIPtoPI#"

The following command removes the APIOnline service, if it is no longer needed:APIOnline# –remove

This command must also be run from the directory where APIOnline#.exe is installed.

APIOnline must then be registered with the Cluster Administrator.

Note: These steps are done on only one of the two cluster nodes. The settings will show up on both nodes in the cluster.

1. Run the Cluster Administrator:



2. Add a new group that will contain the APIOnline cluster resource. (The Cluster Group can be used, as well.) It is recommended that the interface name and number be included in the group name:

3. Click Next:

4. Do not specify any Preferred owners.5. Click Finish, and you will receive a confirmation message:

102

6. Add a new cluster resource called APIOnline#. Set the APIOnline Resource type to Generic Service. The Group is the group just created in the previous steps:

7. Both of the failover nodes should be listed as Possible owners.



8. The Service name is the name assigned to the APIOnline service when the service was created earlier in this section. Specify no Startup parameters.

9. Specify no registry keys in the Registry Replication dialog box:

10. Click Finish to create the resource. A confirmation message should appear:

104

11. Now the APIOnline# resource should be listed in the CHIPtoPI# Failover group:

12. Bring the new APIOnline# resource online. To do this, select the new resource, right-click, and then select Bring Online.

13. APIOnline# is now registered with the Cluster Administrator and is actively being monitored.



14. The APIOnline# resource properties need to be modified so that failover threshold is set to 1. To do this, select the resource name (APIOnline2 in the above example), and click the Properties icon on the toolbar. Select the Advanced tab and modify the Threshold to be 1:

At this point, the node listed as Owner should be the node where the cluster started the APIOnline# service.

Normally, APIOnline will only switch from one node to the other when the primary node shuts down for whatever reason. It is also possible to simulate a failover using the Cluster Administrator. To simulate a failover:

1. Run the Cluster Administrator.

2. Highlight the APIOnline# resource, right-click, and select Initiate Failover.

3. This should cause the APIOnline service to stop on the current node and start on the other node. Sometimes, Initiate Failover must be selected 3 or 4 times in order to force the failover successfully.

Typical Configuration

Processes running on scanning node:

CHIPtoPI#

APIOnline#

Processes running on standby node:

CHIPtoPI#

Scenarios Covered

1. Standby PI Interface Node goes down:106

No immediate impact, but there is no backup PI Interface Node available.

23. Scanning PI Interface Node goes down:

Cluster services start APIOnline on standby PI Interface Node.

Standby Interface detects APIOnline and starts scanning.

Standby node becomes the scanning node.

24. Scanning Interface either crashes or is stopped:

APIOnline detects interface failure and stops running on scanning node.

Cluster services start APIOnline on standby PI Interface Node.

Standby Interface detects APIOnline and starts scanning.

Standby node becomes the scanning node.

Primary/Secondary Interface Failover

All failover actions are initiated by Cluster services or the primary Interface. The secondary Interface never initiates failover. The secondary Interface simply checks the status of the APIOnline service on the secondary node. If APIOnline is running on the secondary node, the secondary node is the scanning node and the secondary Interface performs data collection and processes outputs. If APIOnline is not running on the secondary node, the secondary node is the standby node and the secondary Interface only processes outputs.

The secondary Interface assumes data collection when the primary Interface stops running. APIOnline on the primary node monitors the primary Interface service. If the primary Interface stops, APIOnline on the primary node stops. Cluster services detect that APIOnline is not running in the cluster and starts APIOnline on the secondary node, which makes the secondary node the scanning node. When the secondary Interface detects that APIOnline is running on the secondary node, the secondary Interface performs data collection.

If the primary Interface detects that the local CHIP has failed or lost communication with the PROVOX data highway, the primary Interface can direct the secondary Interface to assume data collection. Before initiating failover to the secondary Interface, however, the primary Interface gets the status of the main CHIP service (CHIPService) on the secondary node. If CHIPService is running on the secondary node, the primary Interface assumes that the secondary Interface is able to collect data from PROVOX and initiates failover. If CHIPService is not running on the secondary node, the primary Interface does not initiate failover because the secondary Interface cannot collect PROVOX data.

The primary Interface checks local CHIP health in the idle time between scans by performing the following steps:

1. Check local CHIP services. At every idle time, the primary Interface gets the status of the local CHIPService. If the local CHIPService is not running, go to step 27. Otherwise, proceed to the next step.

2. Check communication to PROVOX data highway. The communication health check can take several seconds. To minimize impact on fast scan classes, the communication health check is done less often. The interval between communication checks defaults to 60 seconds and can be changed by the /fohm= parameter. If communication errors were returned while scanning or the elapsed time since the last communication check is greater than the interval, proceed to the next step. Otherwise, return to the main processing loop.



a. Call the CHIP Snreq function to send a request for Detailed Device Status to the Highway Data Link (HDL) for the primary CHIP. If the Snreq function does not return “expect response” status (in PROVOX notation, status 0/7), go to step 26.

b. Call the CHIP Gtres function to get the Detailed Device Status response. If the function returns an error (any status code other than 0/5), go to step 26.

c. If the response message contains an error status, go to step 26.

d. If the “HDL Connected” bit in the response message is not set, go to step 26.

e. Call the CHIP Snreq function to send a request for Detailed Device Status to the HDL for the secondary CHIP. If the Snreq function does not return “expect response” status (PROVOX status 0/7), go to step 25.

f. Call the CHIP Gtres function to get the Detailed Device Status response. If the function returns an error (any status code other than 0/5), go to step 25.

g. If the response message contains an error status, go to step 25.

h. If the “HDL Connected” bit in the response message is not set, go to step 25.

25. The primary Interface is healthier than the secondary Interface. If the primary node is not the scanning node, failover to the primary node. Return to the main processing loop.

26. The primary Interface is not healthy. Get the status of CHIPService on the secondary node.

i. If CHIPService is not running on the secondary node, go to step 25.

j. Otherwise, CHIPService is running on the secondary node. Failover to the secondary node. Return to the main processing loop.

27. The primary CHIP is not running. Get the status of CHIPService on the secondary node. If CHIPService is running on the secondary node, failover to the secondary node. Return to the main processing loop.

The primary Interface initiates failover to the secondary Interface by stopping the APIOnline service on the primary node. Cluster services detect that APIOnline is not running in the cluster and starts the APIOnline service on the secondary node, which causes the secondary CHIPtoPI to assume data collection.

When the primary Interface either comes back up or communication with the PROVOX data highway is restored, the primary Interface stops the APIOnline service on the secondary node. Cluster services detect that APIOnline is not running in the cluster and starts APIOnline on the primary node, which causes the primary Interface to assume data collection.

Note: Whenever the primary Interface is running and passes health checks, the primary Interface makes the primary node the scanning node. That is, the secondary node becomes the scanning node only if the primary Interface is not running or the primary Interface is less healthy than the secondary Interface.

The interface startup file for the primary Interface must specify the name of the secondary node using the /secn=xxx parameter, where xxx is the name of the secondary PI Interface Node.

108

Note: The primary Interface must be able to resolve the name of the secondary node.

These parameters are only used when running the Interface in Cluster failover mode.

Cluster Failover Command Line Parameters

Parameter Description/fds=state

Required

Required on both the primary and secondary nodes in a failover setup. Name of the digital state from the failover tag’s digital state set that the Interface writes to the failover tag when this node is collecting. See the section entitled Failover Tag on setting up the failover tag and the digital state set for this tag: /fds=wolverine

/fo=x

Required on primary and secondary nodes

X is the number assigned to APIOnline. See the APIOnline# section for more information on what number to use for x.

/fo9=#

Optional

This parameter tells the Interface how many consecutive Communication Errors (error 9’s) the Interface can receive when it is running in failover mode before it exits out of the current scan loop to check if its connection to the CHIP data highway is good. The default value for this parameter is 0 (no limit).

/foasa=#

Optional on primary nodeDefault: /foasa=60

/foasa is optional and applies only to the primary Interface. This overrides the default setting of 40 stop attempts when the primary Interface attempts to stop the APIOnline process either on the primary or secondary node: /foasa=60

/fohm=#

Optional on primary nodeDefault: /fohm=60

This parameter overrides the default setting of 60 seconds between checks to verify communication with the Data Highway. Valid range for # is 1 to 1800 seconds. The highway communication test can be slow. Setting /fohm to a small value can cause fast scan classes to miss scans.

/fosd=#

Required on primary node

This parameter is required only on the primary node in a failover setup. This is the device number of the secondary node HDL: /fosd=0

/fosh=#


This parameter is required only on the primary node in a failover setup. This is the highway number of the secondary node HDL: /fosh=1

/ft=tagname

Required

Required on both nodes in a failover setup. Name of the digital state failover tag on the PI Server that will record which node is currently collecting: /ft=chipfailtag

/host=server The value of the /host startup parameter depends on the PI Server configuration. If the PI Server is not part of a collective, the value of /host must be identical on both interface computers.If the redundant Interfaces are sending data to a PI Server collective, the value of the /host parameters on the different Interface Nodes must specify different members of the collective. This configuration ensures that outputs continue to be sent to the Data Source if one of the PI Servers becomes unavailable for any reason.

/primary


Required on primary node in failover setup; this parameter must not be specified on the secondary node. Tells the Interface that this node is the primary node in a failover setup. You can optionally specify the name of this node like this: /primary=wolverine



Parameter Description/secn=nodename

Required on primary and secondary node

The parameter is required on both nodes in a failover setup to indicate the name of partner node. For instance, the primary node wolverine might specify /secn=dragon in which case the secondary node, dragon, would use /secn=wolverine.

Sample Startup File on Primary and Secondary Nodes

Example CHIPtoPI#.bat file on Primary NodeCHIPtoPI ^ /ps=F ^ /id=1 ^ /host=strider ^ /f=00:00:10 ^ /ec=1 ^ /fo=1 ^ /primary=wolverine ^ /secn=dragon ^ /ft=chipfailtag ^ /fds=wolverine ^ /stopstat ^ /fosh=0 ^ /fosd=6

Example CHIPtoPI#.bat file on Secondary NodeCHIPtoPI ^ /ps=F ^ /id=1 ^ /host=strider ^ /f=00:00:10 ^ /ec=1 ^ /fo=1 ^ /secn=wolverine ^ /ft=chipfailtag ^ /fds=dragon ^ /stopstat

110

Chapter 13. 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 Automatically adjust clock for daylight saving changes box. 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

Confirm 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 Variables button under the Advanced tab, and remove TZ from the list of environment variables.


Chapter 14. 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 “Managing Security” of the PI 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 Server, 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 PIconfigFor 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,PIUsera_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 EditorThe 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.

PI Server v3.2For 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,proxyaccountpiapimachine,piadmin@quit

In place of piapimachine, put the name of the PI Interface Node as it is seen by PI Server.


Chapter 15. 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.

CHIPService

The CHIPtoPI Interface can only be started after the CHIP software has been started. The CHIP on Windows software supports Windows services. Hence the startup can be automated as soon as the machine is turned on. The CHIP software has to be configured as a service. Use the CHIP Chipserv utility to configure the CHIP software to run as a service:D:\CHIP\chipserv -install Account_string Password_string

where:

D:\CHIP is the path to the CHIP product directory.

Account_string is the desired account for CHIP to execute in.

Password_string is the password for the above account.

Account_string should be in the form of "DomainName\Username". If the account belongs to the built-in domain, ".\Username" can be specified.

For more information on configuring the CHIP service, see the readme_nt.txt file that comes with the CHIP software installation.

Starting Interface as a Service

If the Interface was installed as service, it can be started from PI ICU, the Services control panel or with the command:CHIPtoPI.exe –start

To start the Interface service with PI ICU, use the button on the PI ICU toolbar.

A message will inform the user of the status of the interface service. Even if the message indicates that the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons, and one typical reason is that the service is not able to find the command-line parameters in the associated .bat file. Verify that the root name of the .bat file and the .exe file are the same, and that the .bat file and the .exe file are in the same directory. Further troubleshooting of


services might require consulting the pipc.log file, Windows Event Viewer, or other sources of log messages. See the section Appendix A: Error and Informational Messages for additional information.

Stopping Interface Running as a Service

If the Interface was installed as service, it can be stopped at any time from PI ICU, the Services control panel or with the command:CHIPtoPI.exe –stop

The service can be removed by:CHIPtoPI.exe –remove

To stop the interface service with PI ICU, use the button on the PI ICU toolbar.


Chapter 16. Recognizing CHIP Point Database Changes

The interface program automatically:

Picks up points that are added to the PI database, and

Changes in points that are edited in the PI database.

It will process twenty-five point database changes every two minutes. Time-stamped error messages are written to the PI message log. Messages describing the number of points to scan are also written whenever the Interface is restarted.

Note: When using the CHIP tag name instead of the DBI number, the Interface must be stopped and restarted when the DBI numbers change in the CHIP database.


Chapter 17. Buffering

Buffering refers to an Interface Node’s ability to temporarily store the data that interfaces collect and to forward these data to the appropriate PI Servers. OSIsoft strongly recommends that you enable buffering on your Interface Nodes. Otherwise, if the Interface Node stops communicating with the PI Server, you lose the data that your interfaces collect.

The PI SDK installation kit installs two buffering applications: the PI Buffer Subsystem (PIBufss) and the PI API Buffer Server (Bufserv). PIBufss and Bufserv are mutually exclusive; that is, on a particular computer, you can run only one of them at any given time.

If you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering, but OSIsoft recommends that you run PIBufss instead.)

Which Buffering Application to Use

You should use PIBufss whenever possible because it offers better throughput than Bufserv. In addition, if the interfaces on an Interface Node are sending data to a PI Collective, PIBufss guarantees identical data in the archive records of all the PI Servers that are part of that collective.

You can use PIBufss only under the following conditions:

the PI Server version is at least 3.4.375.x; and

all of the interfaces running on the Interface Node send data to the same PI Server or to the same PI Collective.

If any of the following scenarios apply, you must use Bufserv:

the PI Server version is earlier than 3.4.375.x; or

the Interface Node runs multiple interfaces, and these interfaces send data to multiple PI Servers that are not part of a single PI Collective.

If an Interface Node runs multiple interfaces, and these interfaces send data to two or more PI Collectives, then neither PIBufss nor Bufserv is appropriate. The reason is that PIBufss and Bufserv can buffer data only to a single collective. If you need to buffer to more than one PI Collective, you need to use two or more Interface Nodes to run your interfaces.

It is technically possible to run Bufserv on the PI Server Node. However, OSIsoft does not recommend this configuration.


How Buffering Works

A complete technical description of PIBufss and Bufserv is beyond the scope of this document. However, the following paragraphs provide some insights on how buffering works.

When an Interface Node has Buffering enabled, the buffering application (PIBufss or Bufserv) connects to the PI Server. It also creates shared memory storage.

When an interface program makes a PI API function call that writes data to the PI Server (for example, pisn_sendexceptionqx()), the PI API checks whether buffering is enabled. If it is, these data writing functions do not send the interface data to the PI Server. Instead, they write the data to the shared memory storage that the buffering application created.

The buffering application (either Bufserv or PIBufss) in turn

reads the data in shared memory, and

if a connection to the PI Server exists, sends the data to the PI Server; or

if there is no connection to the PI Server, continues to store the data in shared memory (if shared memory storage is available) or writes the data to disk (if shared memory storage is full).

When the buffering application re-establishes connection to the PI Server, it writes to the PI Server the interface data contained in both shared memory storage and disk.

(Before sending data to the PI Server, PIBufss performs further tasks such data validation and data compression, but the description of these tasks is beyond the scope of this document.)

When PIBufss writes interface data to disk, it writes to multiple files. The names of these buffering files are PIBUFQ_*.DAT.

When Bufserv writes interface data to disk, it writes to a single file. The name of its buffering file is APIBUF.DAT.

As a previous paragraph indicates, PIBufss and Bufserv create shared memory storage at startup. These memory buffers must be large enough to accommodate the data that an interface collects during a single scan. Otherwise, the interface may fail to write all its collected data to the memory buffers, resulting in data loss. The buffering configuration section of this chapter provides guidelines for sizing these memory buffers.

When buffering is enabled, it affects the entire Interface Node. That is, you do not have a scenario whereby the buffering application buffers data for one interface running on an Interface Node but not for another interface running on the same Interface Node.

Buffering and PI Server Security

After you enable buffering, it is the buffering application—and not the interface program—that writes data to the PI Server. If the PI Server’s trust table contains a trust entry that allows all applications on an Interface Node to write data, then the buffering application is able write data to the PI Server.

However, if the PI Server contains an interface-specific PI Trust entry that allows a particular interface program to write data, you must have a PI Trust entry specific to buffering. The following are the appropriate entries for the Application Name field of a PI Trust entry:


Buffering Application Application Name field for PI TrustPI Buffer Subsystem PIBufss.exe

PI API Buffer Server APIBE (if the PI API is using 4 character process names)APIBUF (if the PI API is using 8 character process names)

To use a process name greater than 4 characters in length for a trust application name, use the LONGAPPNAME=1 in the PIClient.ini file.

Enabling Buffering on an Interface Node with the ICU

The ICU allows you to select either PIBufss or Bufserv as the buffering application for your Interface Node. Run the ICU and select Tools > Buffering.

Choose Buffer Type

To select PIBufss as the buffering application, choose Enable buffering with PI Buffer Subsystem.

To select Bufserv as the buffering application, choose Enable buffering with API Buffer Server.

If a warning message such as the following appears, click Yes.


Buffering

Buffering Settings

There are a number of settings that affect the operation of PIBufss and Bufserv. The Buffering Settings section allows you to set these parameters. If you do not enter values for these parameters, PIBufss and Bufserv use default values.

PIBufssFor PIBufss, the paragraphs below describe the settings that may require user intervention. Please contact OSIsoft Technical Support for assistance in further optimizing these and all remaining settings.

Primary and Secondary Memory Buffer Size (Bytes)This is a key parameter for buffering performance. The sum of these two memory buffer sizes must be large enough to accommodate the data that an interface collects during a single scan. A typical event with a Float32 point type requires about 25 bytes. If an interface writes data to 5,000 points, it can potentially send 125,000 bytes (25 * 5000) of data in one scan. As a result, the size of each memory buffer should be 62,500 bytes.

The default value of these memory buffers is 32,768 bytes. OSIsoft recommends that these two memory buffer sizes should be increased to the maximum of 2000000 for the best buffering performance.

Send rate (milliseconds)Send rate is the time in milliseconds that PIBufss waits between sending up to the Maximum transfer objects (described below) to the PI Server. The default value is 100. The valid range is 0 to 2,000,000.

122

Maximum transfer objectsMaximum transfer objects is the maximum number of events that PIBufss sends between each Send rate pause. The default value is 500. The valid range is 1 to 2,000,000.

Event Queue File Size (Mbytes)This is the size of the event queue files. PIBufss stores the buffered data to these files. The default value is 32. The range is 8 to 131072 (8 to 128 Gbytes). Please see the section entitled, “Queue File Sizing” in the PIBufss.chm file for details on how to appropriately size the event queue files.

Event Queue PathThis is the location of the event queue file. The default value is [PIHOME]\DAT.

For optimal performance and reliability, OSIsoft recommends that you place the PIBufss event queue files on a different drive/controller from the system drive and the drive with the Windows paging file. (By default, these two drives are the same.)

BufservFor Bufserv, the paragraphs below describe the settings that may require user intervention. Please contact OSIsoft Technical Support for assistance in further optimizing these and all remaining settings.

Maximum buffer file size (KB)This is the maximum size of the buffer file ([PIHOME]\DAT\APIBUF.DAT). When Bufserv cannot communicate with the PI Server, it writes and appends data to this file. When the buffer file reaches this maximum size, Bufserv discards data.

The default value is 2,000,000 KB, which is about 2 GB. The range is from 1 to 2,000,000.


Buffering

Primary and Secondary Memory Buffer Size (Bytes)This is a key parameter for buffering performance. The sum of these two memory buffer sizes must be large enough to accommodate the data that an interface collects during a single scan. A typical event with a Float32 point type requires about 25 bytes. If an interface writes data to 5,000 points, it can potentially send 125,000 bytes (25 * 5000) of data in one scan. As a result, the size of each memory buffer should be 62,500 bytes.

The default value of these memory buffers is 32,768 bytes. OSIsoft recommends that these two memory buffer sizes should be increased to the maximum of 2000000 for the best buffering performance.

Send rate (milliseconds)Send rate is the time in milliseconds that Bufserv waits between sending up to the Maximum transfer objects (described below) to the PI Server. The default value is 100. The valid range is 0 to 2,000,000.

Maximum transfer objectsMax transfer objects is the maximum number of events that Bufserv sends between each Send rate pause. The default value is 500. The valid range is 1 to 2,000,000.

Buffered Servers

The Buffered Servers section allows you to define the PI Servers or PI Collective that the buffering application writes data.

PIBufssPIBufss buffers data only to a single PI Server or a PI Collective. Select the PI Server or the PI Collective from the Buffering to collective/server drop down list box.

The following screen shows that PIBufss is configured to write data to a standalone PI Server named starlight. Notice that the Replicate data to all collective member nodes check box is disabled because this PI Server is not part of a collective. (PIBufss automatically detects whether a PI Server is part of a collective.)

124

The following screen shows that PIBufss is configured to write data to a PI Collective named admiral. By default, PIBufss replicates data to all collective members. That is, it provides n-way buffering.

You can override this option by not checking the Replicate data to all collective member nodes check box. Then, uncheck (or check) the PI Server collective members as desired.


Buffering

BufservBufserv buffers data to a standalone PI Server, or to multiple standalone PI Servers. (If you want to buffer to multiple PI Servers that are part of a PI Collective, you should use PIBufss.)

If the PI Server to which you want Bufserv to buffer data is not in the Server list, enter its name in the Add a server box and click the Add Server button. This PI Server name must be identical to the API Hostname entry:

The following screen shows that Bufserv is configured to write to a standalone PI Server named etamp390. You use this configuration when all the interfaces on the Interface Node write data to etamp390.

The following screen shows that Bufserv is configured to write to two standalone PI Servers, one named etamp390 and the other one named starlight. You use this configuration when some of the interfaces on the Interface Node write data to etamp390 and some write to starlight.

126

Installing Buffering as a Service

Both the PIBufss and Bufserv applications run as a Service.

PI Buffer Subsystem ServiceUse the PI Buffer Subsystem Service page to configure PIBufss as a Service. This page also allows you to start and stop the PIBufss service.

PIBufss does not require the logon rights of the local administrator account. It is sufficient to use the LocalSystem account instead. Although the screen below shows asterisks for the LocalSystem password, this account does not have a password.


Buffering

API Buffer Server ServiceUse the API Buffer Server Service page to configure Bufserv as a Service. This page also allows you to start and stop the Bufserv Service

Bufserv version 1.6 and later does not require the logon rights of the local administrator account. It is sufficient to use the LocalSystem account instead. Although the screen below shows asterisks for the LocalSystem password, this account does not have a password.

128

Chapter 18. Interface Diagnostics Configuration

The PI Point Configuration chapter provides information on building PI points for collecting data from the device. This chapter describes the configuration of points related to interface diagnostics.

Note: The procedure for configuring interface diagnostics is not specific to this Interface. Thus, for simplicity, the instructions and screenshots that follow refer to an interface named ModbusE.

Some of the points that follow refer to a “performance summary interval”. This interval is 8 hours by default. You can change this parameter via the Scan performance summary box in the UniInt – Debug parameter category pane:

Scan Class Performance Points

A Scan Class Performance Point measures the amount of time (in seconds) that this Interface takes to complete a scan. The Interface writes this scan completion time to millisecond resolution. Scan completion times close to 0 indicate that the Interface is performing optimally. Conversely, long scan completion times indicate an increased risk of missed or skipped scans. To prevent missed or skipped scans, you should distribute the data collection points among several scan classes.


You configure one Scan Class Performance Point for each scan class in this Interface. From the ICU, select this Interface from the Interface drop-down list and click UniInt-Performance Points in the parameter category pane:

Right-click the row for a particular Scan Class # to open the shortcut menu:

You need not restart the Interface for it to write values to the Scan Class Performance Points.

To see the current values (snapshots) of the Scan Class Performance Points, right-click and select Refresh Snapshots.

Create / Create AllTo create a Performance Point, right-click the line belonging to the tag to be created, and select Create. Click Create All to create all the Scan Class Performance Points.

DeleteTo delete a Performance Point, right-click the line belonging to the tag to be deleted, and select Delete.


Correct / Correct AllIf 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: To correct all points, click Correct All.

The Performance Points are created with the following PI attribute values:

Attribute Details

Tag Tag name that appears in the list box

PointSource Point Source for tags for this Interface, as specified on the first tab

Compressing Off

ExcMax 0

Descriptor Interface name + “ Scan Class # Performance Point”

RenameRight-click the line belonging to the tag and select Rename to rename the Performance Point.

Column descriptions

StatusThe Status column in the Performance Points table indicates whether the Performance Point exists for the scan class in the Scan Class # column.

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.

TagnameThe Tagname column holds the Performance Point tag name.

PSThis is the point source used for these performance points and the Interface.

Location1(For the CHIPtoPI Interface, the interface ID is configured in Location5). This is the value used by the Interface for the /ID=# point attribute.


Interface Diagnostics Configuration

ExDescThis is the used to tell the Interface that these are performance points and the value is used to corresponds to the /ID=# command line parameter if multiple copies of the same Interface are running on the Interface Node.

SnapshotThe 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. You may have to scroll to the right to see the snapshots.

Performance Counters Points

When running as a Service or interactively, this Interface exposes performance data via Windows Performance Counters. Such data include items like:

the amount of time that the Interface has been running;

the number of points the Interface has added to its point list;

the number of tags that are currently updating among others

There are two types or instances of Performance Counters that can be collected and stored in PI Points. The first is (_Total) which is a total for the Performance Counter since the interface instance was started. The other is for individual scan classes (Scan Class x) where x is a particular scan class defined for the interface instance that is being monitored.

OSIsoft’s PI Performance Monitor Interface is capable of reading these performance values and writing them to PI points. Please see the Performance Monitor Interface for more information.

If there is no PI Performance Monitor Interface registered with the ICU in the Module Database for the PI Server the Interface is sending its data to, you cannot use the ICU to create any Interface instance’s Performance Counters Points:

134

After installing the PI Performance Monitor Interface as a service, select this interface instance from the Interface drop-down list, then click Performance Counters in the parameter categories pane, and right-click on the row containing the Performance Counters Point you wish to create. This will open the shortcut menu:

Click Create to create the Performance Counters Point for that particular row. Click Create All to create all the Performance Counters Points listed which have a status of Not Created.

To see the current values (snapshots) of the created Performance Counters Points, right-click on any row and select Refresh Snapshots.

Note: The PI Performance Monitor Interface – and not this Interface – is responsible for updating the values for the Performance Counters Points in PI. So, make sure that the PI Performance Monitor Interface is running correctly.

Performance Counters

In the following lists of Performance Counters the naming convention used will be:

“PerformanceCounterName” (.PerformanceCounterPoint Suffix)

The tagname created by the ICU for each Performance Counter point is based on the setting found under the Tools Options Naming Conventions Performance Counter Points. The default for this is “sy.perf.[machine].[if service]” followed by the Performance Counter Point suffix.

Performance Counters for both (_Total) and (Scan Class x)

“Point Count” (.point_count)A .point_count Performance Counters Point is available for each scan class of this Interface as well as a total for the interface instance.



The .point_count Performance Counters Point indicates the number of PI Points per scan class or the total number for the interface instance. This point is similar to the Health Point [UI_SCPOINTCOUNT] for scan classes and [UI_POINTCOUNT] for totals.

The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1(Scan Class 1).point_count) refers to scan class 1, “(Scan Class 2)” refers to scan class 2, and so on. The tag containing “(_Total)” refers to the sum of all scan classes.

“Scheduled Scans: % Missed” (.sched_scans_%missed)A .sched_scans_%missed Performance Counters Point is available for each scan class of this Interface as well as a total for the interface instance.

The .sched_scans_%missed Performance Counters Point indicates the percentage of scans the Interface missed per scan class or the total number missed for all scan classes since startup. A missed scan occurs if the Interface performs the scan one second later than scheduled.

The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1(Scan Class 1).sched_scans_%missed) refers to scan class 1, “(Scan Class 2)” refers to scan class 2, and so on. The tag containing “(_Total)” refers to the sum of all scan classes.

“Scheduled Scans: % Skipped” (.sched_scans_%skipped)A .sched_scans_%skipped Performance Counters Point is available for each scan class of this Interface as well as a total for the interface instance.

The .sched_scans_%skipped Performance Counters Point indicates the percentage of scans the Interface skipped per scan class or the total number skipped for all scan classes since startup. A skipped scan is a scan that occurs at least one scan period after its scheduled time. This point is similar to the [UI_SCSKIPPED] Health Point.

The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1(Scan Class 1).sched_scans_%skipped) refers to scan class 1, “(Scan Class 2)” refers to scan class 2, and so on. The tag containing “(_Total)” refers to the sum of all scan classes.

“Scheduled Scans: Scan count this interval” (.sched_scans_this_interval)A .sched_scans_this_interval Performance Counters Point is available for each scan class of this Interface as well as a total for the interface instance.

The .sched_scans_this_interval Performance Counters Point indicates the number of scans that the Interface performed per performance summary interval for the scan class or the total number of scans performed for all scan classes during the summary interval. This point is similar to the [UI_SCSCANCOUNT] Health Point.

The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1(Scan Class 1).sched_scans_this_interval) refers to scan class 1, “(Scan Class 2)” refers to scan class 2, and so on. The tag containing “(_Total)” refers to the sum of all scan classes.

136

Performance Counters for (_Total) only

“Device Actual Connections” (.Device_Actual_Connections)The .Device_Actual_Connections Performance Counters Point stores the actual number of foreign devices currently connected and working properly out of the expected number of foreign device connections to the Interface. This value will always be less than or equal to the Device Expected Connections counter.

“Device Expected Connections” (.Device_Expected_Connections)The .Device_Expected_Connections Performance Counters Point stores the total number of foreign device connections for the Interface. This is the expected number of foreign device connections configured that should be working properly at runtime. If the Interface can only communicate with 1 foreign device then the value of this counter will always be one. If the Interface can support multiple foreign device connections then this is the total number of expected working connections configured for this Interface.

“Device Status” (.Device_Status)The .Device_Status Performance Counters Point stores communication information about the Interface and the connection to the foreign device(s). The value of this counter is based on the expected connections, actual connections and value of the /PercentUp command line option. If the device status is good then the value is ‘0’. If the device status is bad then the value is ‘1’. If the Interface only supports connecting to 1 foreign device then the /PercentUp command line value does not change the results of the calculation. If for example the Interface can connect to 10 devices and 5 are currently working then the value of the /PercentUp command line parameter is applied to determine the Device Status. If the value of the /PercentUp command line parameter is set to 50 and at least 5 devices are working then the DeviceStatus will remain good (that is, have a value of zero).

“Failover Status” (.Failover_Status)The .Failover_Status Performance Counters Point stores the failover state of the Interface when configured for UniInt failover. The value of the counter will be ‘0’ when the Interface is running as the primary Interface in the failover configuration. If the Interface is running in backup mode then the value of the counter will be ‘1’.

“Interface up-time (seconds)” (.up_time)The .up_time Performance Counters Point indicates the amount of time (in seconds) that this Interface has been running. At startup the value of the counter is zero. The value will continue to increment until it reaches the maximum value for an unsigned integer. Once it reaches this value then it will start back over at zero.

“IO Rate (events/second)” (.io_rates)The .io_rates Performance Counters Point indicates the rate (in event per second) at which this Interface writes data to its input tags. (As of UniInt 4.5.0.x and later this performance counters point will no longer be available.)



“Log file message count” (.log_file_msg_count)The .log_file_msg_count Performance Counters Point indicates the number of messages that the Interface has written to the log file. This point is similar to the [UI_MSGCOUNT] Health Point.

“PI Status” (PI_Status)The .PI_Status Performance Counters Point stores communication information about the Interface and the connection to the PI Server. If the Interface is properly communicating with the PI Server then the value of the counter is ‘0’. If the communication to the PI Server goes down for any reason then the value of the counter will be ‘1’. Once the Interface is properly communicating with the PI Server again then the value will change back to ‘0’.

“Points added to the interface” (.pts_added_to_interface)The .pts_added_to_interface Performance Counter Point indicates the number of points the Interface has added to its point list. This does not include the number of points configured at startup. This is the number of points added to the Interface after the Interface has finished a successful startup.

“Points edited in the interface”(.pts_edited_in_interface)The .pts_edited_in_interface Performance Counters Point indicates the number of point edits the Interface has detected. The Interface detects edits for those points whose PointSource attribute matches the /ps= parameter and whose Location5 attribute matches the /id= parameter of the Interface.

“Points Good” (.Points_Good)The .Points_Good Performance Counters Point is the number of points that have sent a good current value to PI. A good value is defined as any value that is not a system digital state value. A point can either be Good, In Error, or Stale. The total of Points Good, Points In Error, and Points State will equal the Point Count. There is one exception to this rule. At startup of an interface, the Stale timeout must elapse before the point will be added to the Stale Counter. Therefore the Interface must be up and running for at least 10 minutes for all tags to belong to a particular Counter.

“Points In Error” (.Points_In_Error)The .Points_In_Error Performance Counters Point indicates the number of points that have sent a current value to PI that is a system digital state value. Once a point is in the In Error count it will remain in the In Error count until the point receives a new, good value. Points in Error do not transition to the Stale Counter. Only good points become stale.

“Points removed from the interface” (.pts_removed_from_interface)The .pts_removed_from_interface Performance Counters Point indicates the number of points that have been removed from the interface configuration. A point can be removed from the Interface when one of the point attributes is updated and the point is no longer a part of the interface configuration. For example, changing the PointSource, Location5, or Scan attribute can cause the tag to no longer be a part of the interface configuration.

138

“Points Stale 10(min)” (.Points_Stale_10min)The .Points_Stale_10min Performance Counters Point indicates the number of good points that have not received a new value in the last 10 minutes. If a point is Good, then it will remain in the good list until the Stale timeout elapses. At this time if the point has not received a new value within the Stale Period then the point will move from the Good count to the Stale count. Only points that are Good can become Stale. If the point is in the In Error count then it will remain in the In Error count until the error clears. As stated above, the total count of Points Good, Points In Error, and Points Stale will match the Point Count for the Interface.

“Points Stale 30(min)” (.Points_Stale_30min)The .Points_Stale_30min Performance Counters Point indicates the number of points that have not received a new value in the last 30 minutes. For a point to be in the Stale 30 minute count it must also be a part of the Stale 10 minute count.

“Points Stale 60(min)” (.Points_Stale_60min)The .Points_Stale_60min Performance Counters Point indicates the number of points that have not received a new value in the last 60 minutes. For a point to be in the Stale 60 minute count it must also be a part of the Stale 10 minute and 30 minute count.

“Points Stale 240(min)” (.Points_Stale_240min)The .Points_Stale_240min Performance Counters Point indicates the number of points that have not received a new value in the last 240 minutes. For a point to be in the Stale 240 minute count it must also be a part of the Stale 10 minute, 30 minute and 60 minute count.



Performance Counters for (Scan Class x) only

“Device Scan Time (milliseconds)” (.Device_Scan_Time)A .Device_Scan_Time Performance Counter Point is available for each scan class of this Interface.

The .Device_Scan_Time Performance Counters Point indicates the number of milliseconds the Interface takes to read the data from the foreign device and package the data to send to PI. This counter does not include the amount of time to send the data to PI. This point is similar to the [UI_SCINDEVSCANTIME] Health Point.

The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1 (Scan Class 1).device_scan_time) refers to scan class 1, “(Scan Class 2) refers to scan class 2, and so on.

“Scan Time (milliseconds)” (.scan_time)A .scan_time Performance Counter Point is available for each scan class of this Interface.

The .scan_time Performance Counter Point indicates the number of milliseconds the Interface takes to both read the data from the device and send the data to PI. This point is similar to the [UI_SCINSCANTIME] Health Point.

The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1(Scan Class 1).scan_time) refers to scan class 1, “(Scan Class 2)” refers to scan class 2, and so on.

140

Interface Health Monitoring Points

Interface Health Monitoring Points provide information about the health of this Interface. To use the ICU to configure these points, select this Interface from the Interface drop-down list and click Health Points from the parameter category pane:

Right-click the row for a particular Health Point to display the shortcut menu:

Click Create to create the Health Point for that particular row. Click Create All to create all the Health Points.

To see the current values (snapshots) of the Health Points, right-click and select Refresh Snapshots.



For some of the Health Points described subsequently, the Interface updates their values at each performance summary interval (typically, 8 hours).

[UI_HEARTBEAT]The [UI_HEARTBEAT] Health Point indicates whether the Interface is currently running. The value of this point is an integer that increments continuously from 1 to 15. After reaching 15, the value resets to 1.

The fastest scan class frequency determines the frequency at which the Interface updates this point:

Fastest Scan Frequency Update frequencyLess than 1 second 1 second

Between 1 and 60 seconds, inclusive

Scan frequency

More than 60 seconds 60 seconds

If the value of the [UI_HEARTBEAT] Health Point is not changing, then this Interface is in an unresponsive state.

[UI_DEVSTAT]The CHIPtoPI Interface is built with UniInt. Performance has been improved on tag loading during interface startup. New functionality has been added to support non-output health tags. The Health tag with the point attribute ExDesc = [UI_DEVSTAT], is used to represent the status of the source device. The following events can be written into the tag:

"Good" - the Interface is properly communicating with the local CHIP database and can read values from it.

"2 | Connected/No Data | "Successfully connected to CHIP" - the Interface is properly communicating with the local CHIP database, but no points have been collected by the Interface yet. This might be caused by no points being configured for the Interface.

The following list of events represents the failure to communicate with the local CHIP database:

"3 | 1 devices(s) in error | CHIPService not running. CHIPtoPI Interface will need to be restarted once CHIPService is restarted."

Please refer to the UniInt Interface User Manual.doc file for more information on how to configure health points.

[UI_SCINFO]The [UI_SCINFO] Health Point provides scan class information. The value of this point is a string that indicates

the number of scan classes;

the update frequency of the [UI_HEARTBEAT] Health Point; and

the scan class frequencies.

142

An example value for the [UI_SCINFO] Health Point is:3 | 5 | 5 | 60 | 120

The Interface updates the value of this point at startup and at each performance summary interval.

[UI_IORATE]The [UI_IORATE] Health Point indicates the sum of

1. the number of scan-based input values the Interface collects before it performs exception reporting; and

28. the number of event-based input values the Interface collects before it performs exception reporting; and

29. the number of values that the Interface writes to output tags that have a SourceTag.

The Interface updates this point at the same frequency as the [UI_HEARTBEAT] point. The value of this [UI_IORATE] Health Point may be zero. A stale timestamp for this point indicates that this Interface has stopped collecting data.

[UI_MSGCOUNT]The [UI_MSGCOUNT] Health Point tracks the number of messages that the Interface has written to the log file since start-up. In general, a large number for this point indicates that the Interface is encountering problems. You should investigate the cause of these problems by looking in log messages.

The Interface updates the value of this point every 60 seconds. While the Interface is running, the value of this point never decreases.

[UI_POINTCOUNT]The [UI_POINTCOUNT] Health Point counts number of PI tags loaded by the Interface. This count includes all input, output, and triggered input tags. This count does NOT include any Interface Health tags or performance points.

The Interface updates the value of this point at startup, on change, and at shutdown.

[UI_OUTPUTRATE]After performing an output to the device, this Interface writes the output value to the output tag if the tag has a SourceTag. The [UI_OUTPUTRATE] Health Point tracks the number of these values. If there are no output tags for this Interface, it writes the System Digital State No Result to this Health Point.

The Interface updates this point at the same frequency as the [UI_HEARTBEAT] point. The Interface resets the value of this point to zero at each performance summary interval.

[UI_OUTPUTBVRATE]The [UI_OUTPUTBVRATE] Health Point tracks the number of System Digital State values that the Interface writes to output tags that have a SourceTag. If there are no output tags for this Interface, it writes the System Digital State No Result to this Health Point.




[UI_TRIGGERRATE]The [UI_TRIGGERRATE] Health Point tracks the number of values that the Interface writes to event-based input tags. If there are no event-based input tags for this Interface, it writes the System Digital State No Result to this Health Point.


[UI_TRIGGERBVRATE]The [UI_TRIGGERBVRATE] Health Point tracks the number of System Digital State values that the Interface writes to event-based input tags. If there are no event-based input tags for this Interface, it writes the System Digital State No Result to this Health Point.


[UI_SCIORATE]You can create a [UI_SCIORATE] Health Point for each scan class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class IO Rate.sc1) refers to scan class 1, “.sc2” refers to scan class 2, and so on.

A particular scan class’s [UI_SCIORATE] point indicates the number of values that the Interface has collected. If the current value of this point is between zero and the corresponding [UI_SCPOINTCOUNT] point, inclusive, then the Interface executed the scan successfully. If a [UI_SCIORATE] point stops updating, then this condition indicates that an error has occurred and the tags for the scan class are no longer receiving new data.

The Interface updates the value of a [UI_SCIORATE] point after the completion of the associated scan.

Although the ICU allows you to create the point with the suffix “.sc0”, this point is not applicable to this Interface.

[UI_SCBVRATE]You can create a [UI_SCBVRATE] Health Point for each scan class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Bad Value Rate.sc1) refers to scan class 1, “.sc2” refers to scan class 2, and so on.

A particular scan class’s [UI_SCBVRATE] point indicates the number System Digital State values that the Interface has collected.

The Interface updates the value of a [UI_SCBVRATE] point after the completion of the associated scan.


144

[UI_SCSCANCOUNT]You can create a [UI_SCSCANCOUNT] Health Point for each scan class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Scan Count.sc1) refers to scan class 1, “.sc2” refers to scan class 2, and so on.

A particular scan class’s [UI_ SCSCANCOUNT] point tracks the number of scans that the Interface has performed.

The Interface updates the value of this point at the completion of the associated scan. The Interface resets the value to zero at each performance summary interval.

Although there is no “Scan Class 0”, the ICU allows you to create the point with the suffix “.sc0”. This point indicates the total number of scans the Interface has performed for all of its Scan Classes.

[UI_SCSKIPPED]You can create a [UI_SCSKIPPED] Health Point for each scan class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Scans Skipped.sc1) refers to scan class 1, “.sc2” refers to scan class 2, and so on.

A particular scan class’s [UI_SCSKIPPED] point tracks the number of scans that the Interface was not able to perform before the scan time elapsed and before the Interface performed the next scheduled scan.

The Interface updates the value of this point each time it skips a scan. The value represents the total number of skipped scans since the previous performance summary interval. The Interface resets the value of this point to zero at each performance summary interval.

Although there is no “Scan Class 0”, the ICU allows you to create the point with the suffix “.sc0”. This point monitors the total skipped scans for all of the Interface’s Scan Classes.

[UI_SCPOINTCOUNT]You can create a [UI_SCPOINTCOUNT] Health Point for each scan class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Point Count.sc1) refers to scan class 1, “.sc2” refers to scan class 2, and so on.

This Health Point monitors the number of tags in a scan class.

The Interface updates a [UI_SCPOINTCOUNT] Health Point when it performs the associated scan.


[UI_SCINSCANTIME]You can create a [UI_SCINSCANTIME] Health Point for each scan class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Scan Time.sc1) refers to scan class 1, “.sc2” refers to scan class 2, and so on.



A particular scan class’s [UI_ SCINSCANTIME] point represents the amount of time (in milliseconds) the Interface takes to read data from the device, fill in the values for the tags, and send the values to the PI Server.

The Interface updates the value of this point at the completion of the associated scan.

[UI_SCINDEVSCANTIME]You can create a [UI_SCINDEVSCANTIME] Health Point for each scan class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Device Scan Time.sc1) refers to scan class 1, “.sc2” refers to scan class 2, and so on.

A particular scan class’s [UI_ SCINDEVSCANTIME] point represents the amount of time (in milliseconds) the Interface takes to read data from the device and fill in the values for the tags.

The value of a [UI_ SCINDEVSCANTIME] point is a fraction of the corresponding [UI_SCINSCANTIME] point value. You can use these numbers to determine the percentage of time the Interface spends communicating with the device compared with the percentage of time communicating with the PI Server.

If the [UI_SCSKIPPED] value is increasing, the [UI_SCINDEVSCANTIME] points along with the [UI_SCINSCANTIME] points can help identify where the delay is occurring: whether the reason is communication with the device, communication with the PI Server, or elsewhere.

The Interface updates the value of this point at the completion of the associated scan.

146

I/O Rate Point

An I/O Rate point measures the rate at which the Interface writes data to its input tags. The value of an I/O Rate point represents a 10-minute average of the total number of values per minute that the Interface sends to the PI Server.

When the Interface starts, it writes 0 to the I/O Rate point. After running for ten minutes, the Interface writes the I/O Rate value. The Interface continues to write a value every 10 minutes. When the Interface stops, it writes 0.

The ICU allows you to create one I/O Rate point for each copy of this Interface. Select this Interface from the Interface drop-down list, click IO Rate in the parameter category pane, and check Enable IORates for this Interface.

As the preceding picture shows, the ICU suggests an Event Counter number and a Tagname for the I/O Rate Point. Click the Save button to save the settings and create the I/O Rate point. Click the Apply button to apply the changes to this copy of the Interface.

You need to restart the Interface in order for it to write a value to the newly created I/O Rate point. Restart the Interface by clicking the Restart button:

(The reason you need to restart the Interface is that the PointSource attribute of an I/O Rate point is Lab.)

To confirm that the Interface recognizes the I/O Rate Point, look in the pipc.log for a message such as:PI-ModBus 1> IORATE: tag sy.io.etamp390.ModbusE1 configured.



To see the I/O Rate point’s current value (snapshot), click the Refresh snapshot button:

Enable IORates for this InterfaceThe Enable IORates for this interface check box enables or disables I/O Rates for the current Interface. To disable I/O Rates for the selected Interface, uncheck this box. To enable I/O Rates for the selected Interface, check this box.

Event CounterThe Event Counter correlates a tag specified in the iorates.dat file with this copy of the Interface. The command-line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file.

TagnameThe tag name listed under the Tagname column is the name of the I/O Rate tag.

Tag StatusThe Tag Status column indicates whether the I/O Rate tag exists in PI. The possible states are:

Created – This status indicates that the tag exist in PI

Not Created – This status indicates that the tag does not yet exist in PI

Deleted – This status indicates that the tag has just been deleted

Unknown – This status indicates that the PI ICU is not able to access the PI Server

In FileThe In File column indicates whether the I/O Rate tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are:

Yes – This status indicates that the tag name and event counter are in the IORates.dat file

No – This status indicates that the tag name and event counter are not in the IORates.dat file

SnapshotThe 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.

148

Right-Click Shortcut Menu Options

CreateCreate the suggested I/O Rate tag with the tag name indicated in the Tagname column.

DeleteDelete the I/O Rate tag listed in the Tagname column.

RenameAllow the user to specify a new name for the I/O Rate tag listed in the Tagname column.

Add to FileAdd the tag to the IORates.dat file with the event counter listed in the Event Counter column.

SearchAllow the user to search the PI Server for a previously defined I/O Rate tag.



Interface Status Point

The PI Interface Status Utility (ISU) alerts you when an interface is not currently writing data to the PI Server. This situation commonly occurs if

the monitored interface is running on an Interface Node, but the Interface Node cannot communicate with the PI Server; or

the monitored interface is not running, but it failed to write at shutdown a system state such as Intf Shut.

The ISU works by periodically looking at the timestamp of a Watchdog Tag. The Watchdog Tag is a tag whose value a monitored interface (such as this Interface) frequently updates. The Watchdog Tag has its ExcDev, ExcMin, and ExcMax point attributes set to 0. So, a non-changing timestamp for the Watchdog Tag indicates that the monitored interface is not writing data.

Please see the Interface Status Interface for complete information on using the ISU. PI Interface Status Utility runs only on a PI Server Node.

If you have used the ICU to configure the PI Interface Status Utility on the PI Server Node, the ICU allows you to create the appropriate ISU point. Select this Interface from the Interface drop-down list and click Interface Status in the parameter category pane. Right-click on the ISU tag definition window to open the shortcut menu:

Click Create to create the ISU tag.

Use the Tag Search button to select a Watchdog Tag. (Recall that the Watchdog Tag is one of the points for which this Interface collects data.)

150

Select a Scan frequency from the drop-down list box. This Scan frequency is the interval at which the ISU monitors the Watchdog Tag. For optimal performance, choose a Scan frequency that is less frequent than the majority of the scan rates for this Interface’s points. For example, if this Interface scans most of its points every 30 seconds, choose a Scan frequency of 60 seconds. If this Interface scans most of its points every second, choose a Scan frequency of 10 seconds.

If the Tag Status indicates that the ISU tag is Incorrect, right-click to open the shortcut menu and select Correct.

Note: The PI Interface Status Utility – and not this Interface – is responsible for updating the ISU tag. So, make sure that the PI Interface Status Utility is running correctly.


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 loads points, messages are sent to the log if there are any problems with the configuration of the points.

If the UniInt /dbUniInt parameter is found in the command-line, then various informational messages are written to the log file.

Messages

Below is a list of potential errors from the CHIPtoPI Interface.

Message Failover> FATAL ERROR -2147221164 - Cluster class not registered

Meaning This message is only available if CHIPtoPI is being run with Cluster failover enabled. This message means that the Microsoft Cluster DLL (msclus.dll) is not present or is not registered. This DLL is a COM server, which means that it must be registered with regsvr32. There is a version of msclus.dll for WindowsNT and a version for Windows2000. As of CHIPtoPI version 2.8.0.1, both versions are provided in the interface installation directory (pipc\CHIPtoPI) in msclus.zip. The proper file needs to be extracted from the zip file and placed in the \winnt\system32 directory, and then registered with the following command:regsvr32 msclus.dll


Message communication failure for tag>x

Meaning The meaning of this error taken from the Fisher-Rosemount Systems Technical Reference manual is:“No data is available, due to communications failure”These "communication failure" messages are a regurgitation of the errors the CHIP software on the Windows is getting when communicating with the gateway. This is the return code from one of the CHIP API calls. Since it is on the CHIP/Highway side, users should contact Fisher-Rosemount CHIP support if these errors persist.

Message Fail to initialize Chip, err: 9469, 36/253CHIP internal operational status error: 44, Shared memory errorchip_util is unable to execute due to one of the above errorsError Access Denied PID xx could not access the PID yy found in CH_Security.log

Meaning According to the Installing Type DH6212 CHIP NT Software manual in section 3.2, it says the following:“SameAccount should not be used if CHIP is executed as a Windows service and the user's program is executing as a Windows service.”Modify the CHIP_SCOPE environment variable to Global or Group. If Group is chosen, make sure that the CHIPtoPI Interface and any other utility, such as CHIP_UTIL, that connects to the CHIP database are run from accounts in the same group as the CHIP service account. If CHIP_SCOPE is set to Global, set the CHIPtoPI Interface service to use the System Account by modifying the service via the Services applet. On the Log On tab, select the Local System account option.


Debug Messages

If extreme debug messaging is required, the /devdb=x command-line parameter can be used, where x is as follows:

/devdb=level The /devdb parameter is used to set a debug level for debug messaging. Level is a 32-bit integer. Setting a particular bit in level to 1 turns on a particular debug parameter. To turn on every debug parameter specify:/devdbor /devdb=-1To turn off all debug messaging, either remove /devdb from the command line, or specify:/devdb=0Note that level can be specified as a decimal, octal, or hexadecimal number. Octal numbers are indicated by a leading 0 and hexadecimal numbers are indicated by a leading 0x.Any combination of debug levels can be applied. For example, to turn on debug messaging for inputs and failover, specify/devdb=8068

Debug parameters Section of code that is debugged

0 No debug messages written

1 Initialization

2 Point adds, edits, and deletes

4 Inputs

8 Outputs

16 Request/response definition parsing

128 Failover Initialization

256 Failover CheckHighwayConnections

512 Failover RemoteConnections

1024 Failover CheckNetReads

2048 Failover SendToOtherNode

4096 Failover TruthTable

8192 All Failover Messages

System Errors and PI Errors

System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.

Error Descriptions on Windows On Windows, descriptions of system and PI errors can be obtained with the PIdiag utility:

Windows: \PI\adm\pidiag –e error_number


Error and Informational Messages

UniInt Failover Specific Error Messages

Informational

Message 16-May-06 10:38:00CHIPtoPI 1> UniInt failover: Interface in the “Backup” state.

Meaning Upon system startup, the initial transition is made to this state. While in this state, the Interface monitors the status of the other Interface participating in failover. When configured for Hot failover, data received from the data source is queued and not sent to the PI Server while in this state. The amount of data queued while in this state is determined by the failover update interval. In any case, there will be typically no more than two update intervals of data in the queue at any given time. Some transition chains may cause the queue to hold up to five failover update intervals worth of data.

Message 16-May-06 10:38:05CHIPtoPI 1> UniInt failover: Interface in the “Primary” state and actively sending data to PI. Backup interface not available.

Meaning While in this state, the Interface is in its primary role and sends data to the PI Server as it is received. This message also states that there is not a backup Interface participating in failover.

Message 16-May-06 16:37:21CHIPtoPI 1> UniInt failover: Interface in the “Primary” state and actively sending data to PI. Backup interface available.

Meaning While in this state, the Interface sends data to the PI Server as it is received. This message also states that the other copy of the Interface appears to be ready to take over the role of primary.

156

Errors (Phase 1 & 2)

Message 16-May-06 17:29:06CHIPtoPI 1> One of the required Failover Synchronization points was not loaded. Error = 0: The Active ID synchronization point was not loaded.The input PI tag was not loaded

Cause The Active ID tag is not configured properly.

Resolution Check validity of point attributes. For example, make sure Location5 attribute is valid for the Interface. All failover tags must have the same PointSource and Location5 attributes. Modify point attributes as necessary and restart the Interface.

Message 16-May-06 17:38:06CHIPtoPI 1> One of the required Failover Synchronization points was not loaded.Error = 0: The Heartbeat point for this copy of the interface was not loaded.The input PI tag was not loaded

Cause The Heartbeat tag is not configured properly.


Message 17-May-06 09:06:03CHIPtoPI > The Uniint FailOver ID (/UFO_ID) must be a positive integer.

Cause The UFO_ID parameter has not been assigned a positive integer value.

Resolution Change and verify the parameter to a positive integer and restart the Interface.

Message 17-May-06 09:06:03CHIPtoPI 1> The Failover ID parameter (/UFO_ID) was found but the ID for the redundant copy was not found

Cause The /UFO_OtherID parameter is not defined or has not been assigned a positive integer value.

Resolution Change and verify the /UFO_OtherID parameter to a positive integer and restart the Interface.


Error and Informational Messages

Errors (Phase 1)

Message 17-May-06 09:06:03CHIPtoPI 1> UniInt failover: Interface in an “Error” state. Could not read failover control points.

Cause The failover control points on the data source are returning a value to the Interface that is in error. This error can be caused by creating a non-initialized control point on the data source. This message will only be received if the Interface is configured to be synchronized through the data source (Phase 1).

Resolution Check validity of the value of the control points on the data source.

Message 16-May-06 17:29:06CHIPtoPI 1> Loading Failover Synchronization tag failedError Number = 0: Description = [FailOver] or HeartBeat:n] was found in the exdesc for Tag Active_IN but the tag was not loaded by the interface.Failover will not be initialized unless another Active ID tag is successfully loaded by the interface.

Cause The Active ID or Heartbeat tag is not configured properly. This message will only be received if the Interface is configured to be synchronized through the data source (Phase 1).


Message 17-May-06 09:05:39CHIPtoPI 1> Error reading Active ID point from Data sourceActive_IN (Point 29600) status = -255

Cause The Active ID point value on the data source produced an error when read by the Interface. The value read from the data source must be valid. Upon receiving this error, the Interface will enter the “Backup in Error state.”

Resolution Check validity of the value of the Active ID point on the data source. For example, if the value for the Active ID point shows up as “***” in CHIP, then modify the value of the point to a valid value.

Message 17-May-06 09:06:03CHIPtoPI 1> Error reading the value for the other copy’s Heartbeat point from Data sourceHB2_IN (Point 29604) status = -255

Cause The Heartbeat point value on the data source produced an error when read by the Interface. The value read from the data source must be valid. Upon receiving this error, the Interface will enter the “Backup in Error state.”

Resolution Check validity of the value of the Heartbeat point on the data source. For example, if the value for the Heartbeat point shows up as “***”in CHIP, then modify the value of the point to a valid value.

158

Appendix B.PI SDK Options

To access the PI SDK settings for this Interface, select this Interface from the Interface drop-down list and click UniInt – PI SDK in the parameter category pane.

Disable PI SDKSelect Disable PI SDK to tell the Interface not to use the PI SDK. If you want to run the Interface in Disconnected Startup mode, you must choose this option.

The command line equivalent for this option is /pisdk=0.

Use the Interface’s default settingThis selection has no effect on whether the Interface uses the PI SDK. However, you must not choose this option if you want to run the Interface in Disconnected Startup mode.

Enable PI SDKSelect Enable PI SDK to tell the Interface to use the PI SDK. Choose this option if the PI Server version is earlier than 3.4.370.x or the PI API is earlier than 1.6.0.2, and you want to use extended lengths for the Tag, Descriptor, ExDesc, InstrumentTag, or PointSource point attributes. The maximum lengths for these attributes are:

Attribute Enable the Interface to use the PI SDK

PI Server earlier than 3.4.370.x or PI API earlier than 1.6.0.2, without the use of the PI SDK

Tag 1023 255

Descriptor 1023 26

ExDesc 1023 80

InstrumentTag 1023 32

PointSource 1023 1

However, if you want to run the Interface in Disconnected Startup mode, you must not choose this option.

The command line equivalent for this option is /pisdk=1.


Appendix C.Technical Support and Resources

You can read complete information about technical support options, and access all of the following resources at the OSIsoft Technical Support Web site:

http://techsupport.osisoft.com (http://techsupport.osisoft.com)

Before You Call or Write for Help

When you contact OSIsoft Technical Support, please provide:

Product name, version, and/or build numbers

Computer platform (CPU type, operating system, and version number)

The time that the difficulty started

The log file(s) at that time

Help Desk and Telephone Support

You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table below to find the most appropriate number for your area. Dialing any of these numbers will route your call into our global support queue to be answered by engineers stationed around the world.

Office Location Access Number Local Language OptionsSan Leandro, CA, USA 1 510 297 5828 English

Philadelphia, PA, USA 1 215 606 0705 English

Johnson City, TN, USA 1 423 610 3800 English

Montreal, QC, Canada 1 514 493 0663 English, French

Sao Paulo, Brazil 55 11 3053 5040 English, Portuguese

Frankfurt, Germany 49 6047 989 333 English, German

Manama, Bahrain 973 1758 4429 English, Arabic

Singapore 65 6391 181186 021 2327 8686

English, MandarinMandarin

Perth, WA, Australia 61 8 9282 9220 English

Support may be provided in languages other than English in certain centers (listed above) based on availability of attendants. If you select a local language option, we will make best efforts to connect you with an available Technical Support Engineer (TSE) with that language skill. If no local language TSE is available to assist you, you will be routed to the first available attendant.


http://techsupport.osisoft.com/

If all available TSEs are busy assisting other customers when you call, you will be prompted to remain on the line to wait for the next available TSE or else leave a voicemail message. If you choose to leave a message, you will not lose your place in the queue. Your voicemail will be treated as a regular phone call and will be directed to the first TSE who becomes available.

If you are calling about an ongoing case, be sure to reference your case number when you call so we can connect you to the engineer currently assigned to your case. If that engineer is not available, another engineer will attempt to assist you.

Search Support

From the OSIsoft Technical Support Web site, click Search Support.

Quickly and easily search the OSIsoft Technical Support Web site’s Support Solutions, Documentation, and Support Bulletins using the advanced MS SharePoint search engine.

Email-based Technical Support

[email protected]

When contacting OSIsoft Technical Support by email, it is helpful to send the following information:

Description of issue: Short description of issue, symptoms, informational or error messages, history of issue

Log files: See the product documentation for information on obtaining logs pertinent to the situation.

Online Technical Support

From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.

Using OSIsoft’s Online Technical Support, you can:

Enter a new call directly into OSIsoft’s database (monitored 24 hours a day)

View or edit existing OSIsoft calls that you entered

View any of the calls entered by your organization or site, if enabled

See your licensed software and dates of your Service Reliance Program agreements

Remote Access

From the OSIsoft Technical Support Web site, click Contact Us > Remote Support Options.

OSIsoft Support Engineers may remotely access your server in order to provide hands-on troubleshooting and assistance. See the Remote Support Options page for details on the various methods you can use.


mailto:[email protected]

On-site Service

From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service Visit.

OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more information.

Knowledge Center

From the OSIsoft Technical Support Web site, click Knowledge Center.

The Knowledge Center provides a searchable library of documentation and technical data, as well as a special collection of resources for system managers. For these options, click Knowledge Center on the Technical Support Web site.

The Search Support feature allows you to search Support Solutions, Bulletins, Support Pages, Known Issues, Enhancements, and Documentation (including user manuals, release notes, and white papers).

System Manager Resources include tools and instructions that help you manage: Archive sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server security, PI System sizing and configuration, PI trusts for Interface Nodes, and more.

Upgrades

From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.

You are eligible to download or order any available version of a product for which you have an active Service Reliance Program (SRP), formerly known as Tech Support Agreement (TSA). To verify or change your SRP status, contact your Sales Representative or Technical Support (http://techsupport.osisoft.com / ) for assistance.

OSIsoft Virtual Campus (vCampus)

The OSIsoft Virtual Campus (vCampus) Web site offers a community-oriented program that focuses on PI System development and integration. The Web site's annual online subscriptions provide customers with software downloads, resources that include a personal development PI System, online library, technical webinars, online training, and community-oriented features such as blogs and discussion forums.

OSIsoft vCampus is intended to facilitate and encourage communication around PI programming and integration between OSIsoft partners, customers and employees. See the OSIsoft vCampus Web site, http://vCampus.osisoft.com (http://vCampus.osisoft.com) or contact the OSIsoft vCampus team at [email protected] for more information.


http://vCampus.osisoft.com/

http://techsupport.osisoft.com/

Appendix D.Revision History

Date Author Comments

06-Mar-2001 HBeeson Updated version for distribution (2.7.1.0)

08-Mar-2001 HBeeson Added CHIPtoPI ICU Control to Startup Command File section. Added ICU to Perf Points/IORates section.

24-Apr-2001 HBeeson Added info on UNIX & SHLIB_PATH (2.7.1.0, doc rev A)

04-May-2001 HBeeson Updated for 2.7.2.0 release.

17-May-2001 JML Updated with skeleton version 1.08

08-Jun-2001 HBeeson Updated with NT/2000 failover info – updated ICU (2.7.2.0 to 2.7.3.0, doc rev A)

3-Aug-2001 MGrace Updated with VMS failover using an output tag. Version 2.7.4.x

22-Aug-2001 MGrace Added more guidelines on creating the /fop point

05-Sep-2001 HBeeson Updated ICUControl section (2.7.4.x, doc rev B)

25-Sep-2001 MGrace Added new VMS Failover switches. /fow /for /foc. Updated section on creating Highway point for VMS Failover.

28-Sep-2001 HBeeson Added to NT failover section (2.7.5.0)

01-Oct-2001 HBeeson Updated for new ICU Control (2.7.5.0, doc rev A)

01-Nov-2001 MGrace Updated with new uniint switch /usepinettime to disable getting the server time from a PI2 PINET node for time syncing.

15-Jan-2002 HBeeson Point Status Mask (MVPSTMSK 1-16) for Type 21 and 31 (2.8.0.3)

06-Feb-2002 HBeeson Set ‘Automatically Incorporates PI Point Attribute Changes’ to Yes instead of No (2.8.0.3, doc rev A)

30-Apr-2002 HBeeson Added section to troubleshooting on FATAL ERROR –2147221164 (2.8.0.3, doc rev B)

11-Jun-2002 HBeeson Corrected reference to PIFTP section. (2.8.0.3, doc rev C)

19-Aug-2002 HBeeson Added chiponscan/chipoffscan section back (2.8.0.9)

31-Oct-2002 LDaley Revised for new request/response point capability (2.9.0.0): point configuration, /rrdir command-line parameter, new section on request/response definition file syntax.

04-Nov-2002 HBeeson Updated with issues located by LND (2.9.0.0, doc rev A)

11-Nov-2002 LDaley Added principles of operation for request/response points; revised request/response point configuration.

19-Nov-2002 HBeeson Added info on account for failover primary interface.

27-Jan-2003 HBeeson Request/response features supported only on Windows (2.9.0.4)

28-Jan-2003 HBeeson Updated the ICU Control section (2.9.0.4)

03-Feb-2003 HBeeson Added /tcq parameter (2.9.0.5)


Date Author Comments

08-Dec-2003 HBeeson ASCIIMSG outputs are loc2=-21 (2.9.0.5, doc rev A)

15-Jan-2004 HBeeson Clarified “Platforms” section to state: Windows (NT-Intel, Windows 2000, Windows XP) (2.9.0.5, doc rev B)

03-May-2005 LDaley Updated information on request/response (2.9.0.5, doc rev C)

09-Aug-2005 Chrys Version 2.9.0.5 Rev D: Removed comments

28-Dec-2005 Chrys Version 2.9.0.5 – 2.9.1.0 Rev E:

19-Sep-2006 Janelle Version 2.9.0.5 – 2.9.1.0 Rev F: updated Supported Features table to include support for APS; updated headers and footers; Updated How to Contact Us page.

28-Nov-2006 PRowe Version 2.9.0.5 – 2.9.1.0 Rev G, Updated manual to Skeleton v2.5.3, applied template and spell checked document

10-Jan-2007 MKelly Version 2.9.0.5 – 2.9.1.0 Rev H, Updated headers and footers, ICU screenshot and section. Added missing items from skeleton.

28-Feb-2007 HBeeson Version 2.9.2.0, Updated ICU screen shots and added UniInt failover documentation.

16-Apr-2007 MKelly Version 2.9.2.0; Rev A; Fixed headers and footers, page numbering, reduced screenshots to fit inside margins.

17-Apr-2007 Janelle Version 2.9.2.0, Rev B; Added information about support for serial connections in the supported features table; removed references to Unix and VMS versions of the interface – this version of the manual now only discusses the Windows Version built against the latest UniInt 4.3.x.

19-Apr-2007 Janelle Version 2.9.2.0, Rev C; removed Appendix B Migrating from PI CHIP to CHIP to PI Interface; updated servername in sample .bat file

29-Jul-2008 Julie Provide an example of how to configure a PI point to point to a DDP mnemonic.

24-Apr-2009 MMoore Version 2.9.3.0, Revision A: update to skeleton 3.0.11

29-Sep-2009 MMoore Version 2.9.4.0, update to skeleton 3.0.16

11-Mar-2011 NWisehart Version 2.9.4.0 Revision A: update to skeleton 3.0.32 styles and content.

16-May-2011 LDaley Version 2.9.4.0 Revision B: Added explanation of Cluster failover. Added explanation of scaling and conversion features added for version 2.9.1.0.


cdn.osisoft.comcdn.osisoft.com/interfaces/873/PI_CHIPtoPI_HP_2.9.2.0… · Web viewcdn.osisoft.com

Documents

Transcript of cdn.osisoft.comcdn.osisoft.com/interfaces/873/PI_CHIPtoPI_HP_2.9.2.0… · Web viewcdn.osisoft.com