Fisher-Rosemount CHIP on Windows/VMS/HP-UXcdn.osisoft.com/interfaces/904/PI_CHIPtoPI_2.9.0.5-RevB.… · Web viewConnection Tool - Viewing the Local CHIP Database 23. CHIP_UTIL

Fisher-Rosemount CHIP onWindows/VMS/HP-UX

Interface to the PI System

Version 2.9.0.5 and greaterDocument revision B

.

How to Contact Us

Phone (510) 297-5800 (main number)(510) 297-5828 (technical support)

Fax (510) 357-8136

E-mail [email protected]

World Wide Web

http://www.osisoft.com

Mail OSIsoftP.O. Box 727San Leandro, CA 94577-0427USA

OSI Software GmbH Hauptstrae 30 D-63674 Altenstadt 1Deutschland

OSI Software, LtdP. O. Box 8256Level One, 6-8 Nugent StreetAuckland 3, New Zealand

OSI Software, Asia Pte Ltd152 Beach Road#09-06 Gateway EastSingapore, 189721

Unpublished -- rights reserved under the copyright laws of the United States.RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun

Microsystems. HP-UX is a registered trademark of Hewlett Packard Corp. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.

document.doc

2001 OSI Software, Inc. All rights reserved777 Davis Street, Suite 250, San Leandro, CA 94577

http://www.osisoft.com/

mailto:[email protected]

Table of Contents

Introduction......................................................................................................................1Reference Manuals........................................................................................................1

Supported Features........................................................................................................2

Diagram of Hardware Connection:.................................................................................5

Principles of Operation...................................................................................................7

Installation Checklist.......................................................................................................9

Interface Installation on NT...........................................................................................11Naming Conventions and Requirements......................................................................11

Microsoft DLLs..............................................................................................................12

Interface Directories.....................................................................................................12

Interface Installation Procedure....................................................................................13

Installing the Interface as an NT Service......................................................................13

Interface Installation on UNIX.......................................................................................15Naming Conventions and Requirements......................................................................15

Interface Directories.....................................................................................................16


Interface Installation on VMS........................................................................................19Naming Conventions and Requirements......................................................................19


Connection Tool - Viewing the Local CHIP Database................................................23CHIP_UTIL...................................................................................................................23

CHIPDIA.......................................................................................................................26

DigitalSet and Digital States.........................................................................................29

PointSource....................................................................................................................31

PI Point Configuration...................................................................................................33Point Attributes.............................................................................................................33

Fisher-Rosemount CHIP on NT/VMS/HP-UX Interface to the PI System iii

Input-specific PI Point Parameters...............................................................................39

Output-specific PI Point Parameters............................................................................44

Alarm Processing.........................................................................................................45

8 - Bit Status Processing..............................................................................................46

16 - Bit Status Processing............................................................................................47

Controller Mode Processing.........................................................................................48

PIDIFF and CHIP GENER............................................................................................49

Request/Response Definition Files..............................................................................51

Performance Point Configuration................................................................................57

I/O Rate Tag Configuration...........................................................................................59

Startup Command File...................................................................................................63Command-line Parameters..........................................................................................65

Interface Node Clock.....................................................................................................73NT.................................................................................................................................73

UNIX.............................................................................................................................73

VMS..............................................................................................................................73

Security...........................................................................................................................75NT and UNIX................................................................................................................75

VMS..............................................................................................................................75

Starting / Stopping the Interface on NT.......................................................................77CHIPtoPI as an NT Service..........................................................................................77

CHIPtoPI Interactively, not as a Service......................................................................78

Starting / Stopping the Interface on UNIX...................................................................79Command-Line Syntax for Background Processes......................................................79

Terminating Background Processes............................................................................80

Anomalous Background Job Termination....................................................................80

Starting / Stopping the Interface on VMS....................................................................81Starting a Detached Process........................................................................................81

Stopping.......................................................................................................................83

Failover...........................................................................................................................85General Failover Overview...........................................................................................85

General Failover Information........................................................................................86

iv

OpenVMS Failover.......................................................................................................88

Windows NT/Windows 2000 Failover...........................................................................90

Picking up CHIP Point Database Changes................................................................101

Appendix A: Error and Informational Messages.......................................................103

Appendix B: PI 2 PINET to PI 3 String Tag Support.................................................105Setting up PI Batch File Interface on the PI 3 Home Node........................................114

Appendix C: Linking/Re-linking CHIPtoPI on VMS...................................................115

Appendix D: Installation of CHIPtoPI on VMS from a Separate Tape....................117

Appendix E: Migrating from the PI-CHIP Interface to the CHIPtoPI Interface.......119The CHIPPTCONVERT Utility....................................................................................119

Appendix F: Interface Distributions as Self-Extracting Executables.....................123NT Installation.............................................................................................................123

UNIX Installation.........................................................................................................123

VMS Installation..........................................................................................................123

Documentation Updates.............................................................................................123

Appendix G: File Conversion Utilities for VMS Save Sets.......................................125Reblock.......................................................................................................................125

VMS Set File Command.............................................................................................126

Appendix H: GNR2PI -- CHIPtoPI Point Creation Utility...........................................127GNR2PI on Windows NT............................................................................................128

Revision History...........................................................................................................129

Fisher-Rosemount CHIP on NT/VMS/HP-UX Interface to the PI System v

IntroductionThe Fisher-CHIP to PI interface 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 NT operating system, OpenVMS, and HP-UX 10.20. Also, the interface needs to reside on the same computer as the CHIP on NT, CHIP on VMS, or the CHIP on HP-UX software from Fisher. The CHIP software communicates with the PROVOX instrumentation from Fisher. The Fisher CHIP Programming Library option of CHIP is required on VMS platforms only (the VMS CHIP with the Programming Library is sometimes referred to as SuperCHIP). If the interface is to be run on Windows NT or HP-UX, the programming library option is not necessary. See the CHIP User Guide from Fisher for more information about this software. The Fisher-Rosemount CHIP software should be version P4.3 or later.

Note1: If you are running Fisher-Rosemount CHIP software version P4.3 or earlier, you will need to install and use the version of the CHIPtoPI interface specifically built for P4.3 or earlier. If you are running P5.0 or later, you should run the version of the CHIPtoPI interface built for P5.0 and later. If you are running a version of the CHIPtoPI interface older than v1.2.0, and you wish to upgrade P4.3 or lower to P5.0 or greater, you will have to place a copy of chip_lib50.lib in the \winnt\system32 directory, and rename it to chip_lib.lib. You will also have to place a license_size50.dll in the \winnt\system32 directory, and rename it to license_size.dll. This makes it safe to upgrade to P5.0 with all builds of the CHIPtoPI interface.

Note2: The old VMS-based CHIP interface is no longer the primary CHIP interface. We are shipping CHIPtoPI to all new CHIP interface customers. Currently, CHIPtoPI provides failover on VMS (and Windows NT/2000). Version 1.2 of the old VMS-based PI-CHIP interface is included on this tape in the backup save set CHIP_VMS.bck for those customers who are not prepared to migrate to CHIPtoPI.

Reference Manuals

OSIsoft1. UniInt End-User Document

2. PI Universal Data Server Manual (versions 3.3 or newer), orPI Data Archive Manual (versions earlier than 3.3), or PI System Manual (for PI 2)

3. PI-API Installation Instructions

Fisher-Rosemount

1. Using DH6200-Series CHIP Software

2. Configuring DH6200-Series CHIP Software

Fisher-Rosemount CHIP on NT/VMS/HP-UX Interface to the PI System 1

3. Technical Reference for DH6200-Series CHIP Software

Supported FeaturesFeature Support

Part number PI-IN-FI-CHIP-NT

Platforms VMS / Alpha VMS / Windows (NT-Intel, Windows 2000, Windows XP) / HP-UX 10.20

PI Point Types PI 2: Integer, Real, Digital

PI 3: 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 / Unsolicited / Event Tags

Scan-BasedEvent Triggered

Maximum Point Count Limited by resources

Uses PI-SDK No

PINet to PI 3 String Support Yes

* Source of Timestamps PI Server

* History Recovery No

* Failover Yes

* UniInt-Based Yes

* Vendor Software Required on PI-API / PINet Node

Yes

* Vendor Software Required on Foreign Device

Yes / No

* Vendor Hardware Required No

* Additional PI Software Included with Interface

Yes

*Device Point Types See below

* See paragraphs below for further explanation.

Source of TimestampsThe CHIPtoPI interface uses PI server timestamps.

On VMS PINet nodes, you can configure the interface to use the local time.


History RecoveryHistory Recovery is not supported.

FailoverFailover is supported on VAX VMS, Alpha VMS, Windows NT and Windows 2000. This interface supports outputs to the PROVOX highway and supports automatic data-collection failover on VMS and Windows NT/2000. Failover for Windows NT and Windows 2000 requires Microsoft Cluster Server. This interface does not support failover on HP-UX.

UniInt-BasedUniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by our developers and is integrated into many interfaces, such as the PI-CHIPtoPI interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our interfaces as possible. It also allows for the very rapid development of new interfaces. 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 End-User Document is a supplement to this manual.

Vendor Software RequiredThe interface needs to reside on the same computer as the CHIP on NT, CHIP on VMS, or the CHIP on HP-UX software from Fisher. The CHIP software communicates with the PROVOX instrumentation from Fisher. The Fisher CHIP Programming Library option of CHIP is required on VMS platforms only (the VMS CHIP with the Programming Library is sometimes referred to as SuperCHIP). If the interface is to be run on Windows NT or HP-UX, the programming library option is not necessary. See the CHIP User Guide from Fisher for more information about this software. The Fisher-Rosemount CHIP software on VMS and NT should be version P4.3 or later. The Fisher-Rosemount CHIP software on HP-UX software should be version P4.3 or later.

Vendor Hardware RequiredNo special vendor hardware is required beyond what is required by Fisher-Rosemount CHIP.

Additional PI SoftwareThe PI-API for interfaces is required to run the CHIPtoPI interface in Windows NT/2000 or HP-UX. If the interface is to run on a VMS PINet node and scan string tags for a PI 3 home node, then the Batch File interface will be required on either the NT/2000 or UNIX PI 3 platform.


Introduction

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 section “PI Point Configuration” on page 35.

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 will be 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.

Note: 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 copies of the interface may be necessary to obtain the desired scan rates for the request/response points. To eliminate the possibility of request/response points interfering with standard CHIP point types, an individual copy of the CHIPtoPI interface will not accept points of both types. That is, standard CHIP points and request/response points cannot be assigned to the same interface ID. Dedicated copies of the interface must be activated for each class of points.

4

Diagram of Hardware Connection:


Principles of OperationThe 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-API 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-API node, the interface can put data into either a version 2.X PI server or a 3.X PI server.

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” (digital state -246). For all other unsuccessful status values from CHIP routines, PI point status is set to "Bad Input" (digital state -255).

Users migrating from the PI-CHIP interface on VMS to the CHIPtoPI interface see “Appendix E: Migrating from the PI-CHIP Interface to the CHIPtoPI Interface” for detailed information on the CHIPPTCONVERT utility.

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. To prevent request/response points from adversely affecting the scan rate of standard CHIP points, each copy of CHIPtoPI dedicates itself to standard CHIP points only or request/response points only. The first point added by a given copy 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.

To effectively use the request/response capability, you will need to understand 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 message sent to different types of PROVOX devices can and do have different response message formats. Some request messages may contain values that are specific to your PROVOX installation. To make CHIPtoPI flexible enough to support the needs of every PROVOX installation,


CHIPtoPI 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” on page 53 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, CHIPtoPI 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 name 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 CHIPtoPI 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 CHIPtoPI 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, CHIPtoPI 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 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 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.


Installation ChecklistFor those users who are familiar with running PI data collection interface programs, this checklist helps you get the CHIPtoPI interface running. If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual in detail.

1. Verify the PI-API has been installed.

2. Install the interface.

3. Define digital states (for details, see the section entitled “DigitalSet and Digital States” on page 31).

4. Choose a point source. If PI 2 home node, create the point source.

5. If request/response points will be configured (only supported on Windows):Create dedicated copies of the interface for request/response points.Create the definition files that will be needed.Use the checkformat utility to check the syntax of the definition files.Use the chipsendreq utility to send a request to the PROVOX devices with which the definition file will be used; verify that the response contains the expected data.

6. Configure PI points. 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 section titled “PI Point Configuration” on page 35. Location3 is the CHIP occurrence number taken from the section titled “PI Point Configuration”.Location4 is the scan class.Location5 is the interface instance. 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. 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.

7. Edit startup command file (for details, see the section titled “Startup Command File” on page 65).

8. Configure performance points (for details, see the section titled “Performance Point Configuration” on page 59).

9. Configure I/O Rate Tag (for details, see the section titled “I/O Rate Tag Configuration” on page 61)

10. Set interface node clock. (Note that this step should be ignored if you are running on VMS.)

11. Set up security.


12. If CHIPtoPI is running on VMS and sending data to a PI 3 home node, test the FTP mechanism for PINet to PI 3 string support. See “Appendix B: PI 2 PINet to PI 3 String Tag Support” for more information.

13. Start the interface.

14. Verify data.

15. Stop interface, start buffering, start interface. (This does not apply if the interface is running on VMS.)


Interface Installation on NTPrior to the installation of the CHIPtoPI interface, you need to install the CHIP NT software on the computer. OSIsoft recommends that interfaces be installed on PI-API nodes instead of directly on the PI Server node. A PI-API node is any node other than the PI Server node where the PI Application Programming Interface (PI-API) has been installed (see the PI-API Installation Instructions manual). With this approach, the PI Server need not compete with interfaces for 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, Bufserv should be enabled on the PI-API node (once again, see the PI-API Installation Instructions manual). Bufserv is distributed with the PI-API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.

In most cases, interfaces on PI-API nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.

The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and interfaces as manual services that are launched by site-specific command files when the PI Server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI Server by site-specific command files. This typical scenario assumes that Bufserv is not enabled on the PI Server node. Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server node. See the UniInt End-User Document for special procedural information.

The CHIPtoPI interface setup program for interface version 2.8.0.0 and later uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000. When running on Windows NT 4.0 systems, the CHIPtoPI setup program will install the Windows Installer itself if necessary. To install, run the CHIPtoPI_x.x.x.x.exe installation kit.

Naming Conventions and RequirementsIn 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.

It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, one would typically use chiptopi1.exe and chiptopi1.bat for interface number 1, chiptopi2.exe and chiptopi2.bat for interface number 2, and so on. When


an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line arguments in a .bat file that has the same root name.

Microsoft DLLsThe following Microsoft DLLs are distributed on the installation CD-ROM. Copy these files to the winnt\system32 directory only if the files in the winnt\system32 directory are older than the files on the CD-ROM.

MSVCIRT.DLL

MSVCRT.DLL

MSVCRT40.DLL

MSVCP50.DLL

MSVCP60.DLL

The following additional Microsoft DLLs are also distributed on the CD-ROM. These DLLs are only used by a debug version of the interface. Copy these files to the winnt\system32 directory only if the files in the winnt\system32 directory are older than the files on the CD-ROM.

MSVCIRTD.DLL

MSVCRTD.DLL

MSVCP50D.DLL

MSVCP60D.DLL

Interface DirectoriesThe following files are installed:PI HOME DIRECTORY\

INTERFACES\

CHIPTOPI\CHIPTOPI.EXECHIPTOPI.BAT.NEWAPIONLINE.BATAPIONLINE.EXEchiptopi_P4.3.dbgchiptopi_P4.3.exechiptopi_readme.txtClusapi.dllMSClus.zipResutils.dllchiptopi.doc


checkformat.exechipsendreq.exeDevice_Type.txtIFC_UOC_Detailed_Status.txtLTD_Traffic_Statistics.txtMUX_Detailed_Integrity.txtNTD_Traffic_Statistics.txt

The PIHOME Directory TreeThe 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 WinNT directory. A typical pipc.ini file contains the following lines:[PIPC]PIHOME=c:\pipc

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

Interface Installation DirectoryThe interface is installed to:PIHOME\interfaces\chiptopi\

Where PIHOME is the corresponding entry in the pipc.ini file.

Interface Installation ProcedureTo install, run the CHIPtoPI_x.x.x.x.exe installation kit.

Run PI-ICU to configure the interface, or alter the command-line arguments in the .bat file as discussed in section “Startup Command File” on page 65.

Try to start the interface interactively with PI-ICU or manually with the command:chiptopi.bat

If the interface cannot be started interactively, it will not be able to run as a service. It is easier to debug interactively started processes because error messages are echoed directly to the screen. Once the interface is successfully running interactively, one can try to run it as a service by following the instructions below.

Installing the Interface as an NT ServiceRun PI-ICU to configure and manage the interface service, or manually configure and manage the interface service as described below. One can get help for installing the interface as a service at any time with the command:chiptopi.exe –help

Change to the directory where the chiptopi.exe executable is located. Then, consult the following table to determine the appropriate service installation command.


Interface Installation on NT

NT Service Installation Commands on a PI-API node or a PI Server node

with Bufserv implemented

Manual service chiptopi.exe –install –depend “ChipService bufserv”

Automatic service

chiptopi.exe –install –auto –depend “ChipService bufserv”

NT Service Installation Commands on a PI-API node or a PI Server node

without Bufserv implemented

Manual service chiptopi.exe –install –depend “ChipService tcpip”

Automatic service

chiptopi.exe –install –auto –depend “ChipService tcpip”

When the interface is installed as a service on the PI Server node and when Bufserv is not implemented, a dependency on the PI network manager is not necessary because the interface will repeatedly attempt to connect to the PI Server until it is successful.

Note: Interfaces are typically not installed as automatic services when the interface is installed on the PI Server node.

Check the Microsoft Windows NT services control panel to verify that the service was added successfully. One can use the services control panel at any time to change the interface from an automatic service to a manual service or vice versa.

16

Interface Installation on UNIXPrior to the installation of the CHIPtoPI interface, install the CHIP HP-UX software on the computer. One of the first issues that must be resolved is where the interface should be installed. Should the interface be installed on the PI Server node or on a remote PI-API node? OSIsoft recommends that the interface be installed on a remote PI-API node. The primary function of the server node is to archive data and to service the clients that request that data. The PI Server should not need to compete with interfaces for the machine’s resources. If the interface is installed on a remote PI-API node, then the PI-API must be installed on that node before the interface is installed. Refer to the PI-API Installation Instructions manual.

When the interface is installed on a PI-API node, it is also a good idea to install and run Bufserv on the PI-API node. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the server is down for maintenance, upgrades, backups, and unexpected failures. It is not critical to install Bufserv before the initial installation of the interface. In fact, it is recommended that Bufserv be installed after the interface has been shown to work to ease troubleshooting. Refer to the PI-API Installation Instructions manual for installation instructions and additional information on Bufserv.

If the interface is installed on the PI Server node, the advantage of using Bufserv is diminished because it is no longer needed to protect against network failures. Bufserv would still allow data to be collected when the PI Server is brought down for routine maintenance, but one must weigh this advantage against the additional load that Bufserv incurs on the server. Typically, users do not choose to run Bufserv on the PI Server node. If Bufserv is used on the server node, one must make sure that Bufserv is started before any interfaces by the startup script for PI.

If the interface is installed on a server node, the interface should be configured to start and stop in conjunction with the PI Server. If the interface is installed on a PI-API node, then the interface should be configured to start and stop with the PI-API. Site-specific scripts can be edited for this purpose, as described in the installation procedure below. The PI Server and the PI-API, in turn, can be configured to start and stop automatically when the system is shut down or rebooted. Procedures for automatic startup and shutdown of PI or the PI-API are platform specific. The automation procedures are discussed in the PI System Management chapter of the PI Data Archive Manual (versions earlier than 3.3), or PI Universal Data Server Manual (versions 3.3 or newer), or PI System Manual (for PI 2) manual.

Naming Conventions and RequirementsIn the installation procedure below, it is assumed that the name of the interface executable is chiptopi and that the startup command file is called chiptopi.sh.

Note: UNIX does not enforce file-naming conventions, and it is possible that the file name extensions for the actual interface executable and command files are different than.sh, or it is possible that the file extensions are eliminated entirely.


In order to run multiple copies of the interface from the same directory, it is necessary to rename the executable and the command file. It is customary to use chiptopi1 and chiptopi1.sh for interface number 1, chiptopi2 and chiptopi2.sh for interface number 2, and so on.

Interface DirectoriesExample interface directory structure

The following files should be installed:PI HOME DIRECTORY/

Interfaces/

Chiptopi/chiptopichiptopi.shcheckformat.exechipsendreq.exeDevice_Type.txtIFC_UOC_Detailed_Status.txtLTD_Traffic_Statistics.txtMUX_Detailed_Integrity.txtNTD_Traffic_Statistics.txt

The PIHOME DirectoryPIHOME is an environment variable that points to the base directory where the PI-API is installed. The setting of environment variables is discussed in the PI-API Installation Instructions manual.

Interface Installation DirectoryThere are two conventions for the installation directory. The first convention is to place all copies of the interface into a single directory. If this convention is followed, it is recommended to place chiptopi1, chiptopi2, chiptopi3, etc., in the directory:$PIHOME/interfaces/chiptopi/

The second convention is to create a separate interface directory for each copy of the interface. If this convention is followed, it is recommended to place chiptopi1, chiptopi2, chiptopi3, etc., in the directories:

$PIHOME/interfaces/chiptopi1/$PIHOME/interfaces/chiptopi2/$PIHOME/interfaces/chiptopi3/

and so on.

Create the installation directories as necessary.


Interface Installation ProcedureIn the installation procedure below, it is assumed that interface number 1 is being installed and that all copies of the interface will be installed in the same directory. To install another copy of the interface, repeat the following procedure with chiptopi# used in place of chiptopi1, where # is the interface number between 0 and 99.

Copy the interface files to $PIHOME/interfaces/chiptopi/. Create the directory if necessary.

If necessary, rename the executable and command files to chiptopi1 and chiptopi1.sh. The executable and command file should have the same root name.

Alter the command-line arguments in the chiptopi1.sh file as discussed in the section “Startup Command File” on page 65.

Try to start the interface as a foreground process. It is advantageous to begin with foreground processes because the procedure for starting and stopping foreground processes is easier than for background processes. Use the following command to start the interface in the foreground:sh chiptopi1.sh

If the chiptopi1.sh file is made an executable file with the chmod +x chiptopi1.sh command, the sh on the command line is no longer necessary.

Foreground processes are most easily terminated by holding down the control key and hitting the c key while the terminal from which the interface was launched is in focus. Pressing ctrl-c sends the SIGTERM signal to the interface, causing the exit handler to be invoked. A foreground process can also be terminated with the kill command in the same manner that background jobs are stopped, as described in the later section “Starting / Stopping the Interface on UNIX” on page 83.

Once the interface is successfully running as a foreground process, one can try to run the interface in the background by following the appropriate instructions in the section “Starting / Stopping the Interface on UNIX.”

If the Fisher-Rosemount CHIP library (libchip.sl) is not in the SHLIB_PATH environment variable, its location needs to be added to this path before the interface can successfully run. To check to see if the directory is in the path, users can use this command:echo $SHLIB_PATHTo add a path to the beginning of SHLIB_PATH in the Bourne and Korn shells, users can use this command:SHLIB_PATH=/usr/somepathname:$SHLIB_PATHexport SHLIB_PATHwhere /usr/somepathname is the directory in which the CHIP library is installed.


Interface Installation on VMSThe CHIPtoPI interface is supported on the OpenVMS VAX or Alpha platform. The interface runs with a Fisher CHIP database. The CHIPtoPI program interface is linked with the CHIP Programming Toolkit library and with PI toolkit library on site, which is why the Fisher-Rosemount CHIP Programming License is required.

One of the first issues that must be resolved is where the interface should be installed. Should the interface be installed on the PI Server node or on a remote PINet node? OSIsoft recommends that the interface be installed on a PINet node. The primary function of the server node is to archive data and to service clients that request data. The PI Server should not need to compete with interfaces for the machine’s resources. If the interface is installed on a PINet node, then PINet must be installed on that node before the interface is installed. Refer to the PI 2.1.x Installation and Upgrade Handbook for installation instructions.

If the interface runs on a PINet node, interfaces can communicate to either a PI 2 Server or a PI 3 Server. If the interface runs on a PI 2 Server, the interface can only communicate to the PI 2 Server.

On a PINet node, PISysExe, PISysMgr, and PISysDat are all aliases for the PINet directory, and PIBuild is an alias for the PINetBuild directory.

Naming Conventions and RequirementsIn the installation procedure below, it is assumed that the interface executable is called chiptopi.exe, the startup command file is called chiptopi.com, and the startup command file for detached processes is called chiptopidetach.com..

Install the interface executable and command files in the PISysExe directory. If multiple instances of the interface must be run as interactive or detached processes, create multiple copies of the chiptopi.com file. For this purpose, it is customary to copy the chiptopi.com file to chiptopi1.com for instance 1, to chiptopi2.com for instance 2, and so on. The individual command files then need to be edited separately as appropriate.

Regardless of how many instances of the interface are running as interactive or detached processes, only one chiptopi.exe file and one chiptopidetach.com file are needed.

When the interface is run as a detached process, interface-specific log files are created in the PISysExe directory. The interface log file is chiptopi.out.

Note: The interface will always write error and information messages to the PISysMgr:PIMessLog.txt file.


Interface Installation ProcedureInterface files are installed and linked automatically as part of PI or PINet installations. If the interface has been automatically installed, skip to the “Starting / Stopping the Interface on VMS” section on page 85. Sometimes, however, an interface needs to be installed or upgraded separately from the PI or PINet installation. This frequently needs to be done when a newer version of the interface is available than is distributed with the PI or PINet distribution.

Interface files for VMS-based interfaces are now distributed on CD-ROM readable by NT or Windows machines. The appropriate files must be transferred over the network to the VMS node. The following files are distributed.

Distribution files

CHIPtoPI.DOC Interface manual (Microsoft Word Document). The interface-specific installation procedure is in this manual.

CHIPtoPILink.COM Installation command file for the Interface.

CHIPtoPI.BCK Save set containing the interface files.

RELEASENOTES.TXT Release notes.

REBLOCK.README Readme file for REBLOCK.EXE.

REBLOCK.EXE The interface backup save set must be reblocked before the save set can be unpacked. See the REBLOCK.README.

The following procedure is typical.

1. Transfer CHIPTOPI.BCK and REBLOCK.EXE to the VMS node by some sort of binary file transfer mechanism. For example, one could use binary FTP. Copy the files to a safe directory, one that will not be overwritten during an upgrade of PI or PINet.

2. Transfer CHIPTOPILink.COM to the VMS node by some sort of ASCII file transfer mechanism. Copy the file to the safe directory.

3. Run REBLOCK.EXE on the CHIPTOPI.BCK file. Reblock corrects the block size of the CHIPTOPI.BCK file, which is altered during the binary file transfer. Binary file transfer does not affect the block size of the REBLOCK executable itself. An example reblock session is given below. $ run reblock

REBLOCK: Convert file to blocksize 32256

Filename ("\" to exit): CHIPTOPI.bckFilename ("\" to exit): \

4. Unpack the CHIPTOPI.BCK save set to the PIBuild directory by:backup/verify/log chiptopi.bck/sav *.*


5. Install the interface files with the command:@CHIPTOPILink.comThe command file copies the files to the appropriate directories and links the interface executable. Files similar to the following are typically installed.

PIBuild directoryCHIPTOPI.OBJ Object file for the interface.UNIINT.OBJ Object file for the interface

CHIPTOPILINK.COM Command procedure for re-linking the executable.

PISysExe directoryCHIPTOPI.EXE Interface executable.

CHIPTOPI.COM Startup command file for interactive processes.

CHIPTOPIDETACH.COMStartup command file for detached processes (the command-line arguments are still defined in the CHIPTOPI.COM file).


Connection Tool - Viewing the Local CHIP DatabaseThere 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. On Windows NT/2000, use the chip_util.exe utility in the CHIP directory to view the CHIP database. On VMS use the CHIPDIA logical to run the CHIP utility_menu.com. On HP-UX, use chip_util in the CHIP installation directory.

CHIP_UTILTo 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:


Connection Tool – Viewing the Local CHIP Database

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 in N for (N)ew TAG/DBI:

26

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 windows closes.



CHIPDIAOn VMS, the CHIP diagnostic utility has a logical called CHIPDIA pointing to the .com file:

"CHIPDIA" = "CHIP_MENU:UTILITY_MENU.COM"

To launch CHIPDIA:$@chipdia

If you receive this error:%SYSTEM-F-NOPRIV, insufficient privilege or object protection violation

You may first need to set your UIC to CHIP:$set uic chip

The CHIP Utilities menu will be displayed after running @chipdia:

CHIP Utilities Menu

1 - CHIP_DB_UTIL - CHIP Local Utilities Menu 2 - CHIP_SYS_UTIL - PROVOX System Utilities Menu 3 - PROVUE_UTIL - PROVUE Specific Utilities 4 - REDIRECT OUTPUT - Define a File to Receive Output 5 - INSTRUCTIONS - Turn instruction prompting on 6 - QUIT - or Press Return to QUIT

Enter choice number [quit]: : 1

Enter 1 for CHIP Local Utilities Menu

CHIP Local Utilities Menu

1 - FSLOG - CHIP Error Logging Program 2 - SMRY - CHIP Database Summary

28

3 - POINT_UTIL - View and operate on CHIP database points 4 - HIFSTATS - View HIU Statistics 5 - WATCH_DOG - Monitor Status of CHIP Programs 6 - OUR_ADDR - Address of this CHIP 7 - REV_LEVEL - Revision, DB Info & Address of this CHIP 8 - CLEAR_DB - Clear ERR flag on CHIP Points 9 - QUIT - or Press Return to QUIT

Enter choice number [quit]: 3

Enter 3 for View and operate on CHIP database points

Do you want instructions? (Y,N,S: [NO]): n

If you wish to view instructions, type Y, otherwise, type N.

The first point displayed will be the point with the lowest DBI in the local CHIP database:

Mode ................ MANOutput Tracking ..... 0 A Alarm ... 0 Percent IVP Low ... 0Integral Tracking ... 0 B Alarm ... 0 Percent IVP Hi .... 0Setpoint Tracking ... 0 C Alarm ... 0 SP Low ............ 0Questionable Data ... 1 D Alarm ... 0 SP Hi ............. 0

%Process Variable ... 0.0000

Local/Remote ... LOCAL Slot Param ... n/a Object ID ... 1Tag .. L1-1 Type .. 1 EU High .. 100.00 EU Low .. 0.00

Source @8-20 DBI 1 status = 8 (0/8) Questionable Data

(A)ttr/Mnem list (C)hange oper param (N)ew TAG/DBI(P)oint list (D)isplay DDPs (T)ime int (Q)uit



To display a different tag or DBI, type in N for (N)ew TAG/DBI:

Enter TAG, DBI or <Return>: 5Enter 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:

Mode ................ MANOutput Tracking ..... 0 A Alarm ... 0 Percent IVP Low ... 0Integral Tracking ... 0 B Alarm ... 0 Percent IVP Hi .... 0Setpoint Tracking ... 0 C Alarm ... 0 SP Low ............ 0Questionable Data ... 1 D Alarm ... 0 SP Hi ............. 0

%Process Variable ... 0.0000%Set Point .......... 0.0000%IVP ................ 0.0000

Local/Remote ... LOCAL Slot Param ... n/a Object ID ... 5Tag .. L5-5 Type .. 5 EU High .. 100.00 EU Low .. 0.00

Source @8-20 DBI 5 status = 8 (0/8) Questionable Data

(A)ttr/Mnem list (C)hange oper param (N)ew TAG/DBI(P)oint list (D)isplay DDPs (T)ime int (Q)uit

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 CHIPDIA utility, press the “enter” key until VMS DCL prompt is displayed.

30

DigitalSet and Digital States

PI 2 Sample Digital State TableA sample Digital State Table for the CHIP alarm states is shown below. The entries at 130-4 are for alarm tags with Location3 equal to 5. According to this example, these tags should have a DigStartCode of 130 and a DigNumber of 4. The entries at 150-165 are for alarm tags with Location3 equal to 6. Entries 136-7 are for alarm tags with Location3 equal to 7. Entries 138-9 are for Location3 equal to 8. Entries 140-1 are for Location3 equal to 9. Entries 142-3 are for Location3 equal to 10.

Entries 170-177 are for controller mode tags. Note that state 0 (170) is not used. The Digital Start Code for mode tags should still be 170 for this example.

Printed out for: CET - 26-Jun-89 09:54:48PI System Digital States Definition Page 3 26-Jun-89 09:54:48 Digital States Table-----------------------------------------------------------129 145 161 D,B,C Alarms 177 HManual130 No Alarm 146 162 D,A Alarms 178131 C Alarm 147 163 D,A,C Alarms 179132 B Alarm 148 164 D,A,B Alarms 180133 A Alarm 149 165 D,A,B,C Alrm 181134 D Alarm 150 No Alarm 166 182135 151 C Alarm 167 183136 No Alarm 152 B Alarm 168 184137 A Alarm 153 B,C Alarms 169 185138 No Alarm 154 A Alarm 170 < Blank > 186139 B Alarm 155 A,C Alarms 171 Manual 187140 No Alarm 156 A,B Alarms 172 Auto 188141 C Alarm 157 A,B,C Alarms 173 RSP 189142 No Alarm 158 D Alarm 174 Sup 190143 D Alarm 159 D,C Alarms 175 DDC 191144 160 D,B Alarms 176 Com 192

PI 3 Sample Digital State TableFor a PI 3.X system, you may need to define the following digital state sets for the controller mode and the alarm status:@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 PI 3 tags digital tags are defined.


PointSourceThe PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For example, one may choose the letter F to identify points that belong to the CHIPtoPI interface. To implement this, one would set the PointSource attribute to F for every PI Point that is configured for the CHIPtoPI interface. Then, if one uses /ps=F on the startup-command line of the CHIPtoPI interface, the CHIPtoPI interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of F. 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 argument.

Case-sensitivity for PointSource AttributesIf the interface is running on a PINet node and the Server node is a PI 3 system, use a capital letter (or a case-insensitive character such as a number, a question mark, etc.) for the PointSource attribute when defining points. For all other scenarios, one does not need to be careful with the case of the PointSource.

In all cases, the point source character that is supplied with the /ps command-line argument is not case sensitive. That is, /ps=F and /ps=f are equivalent. One only needs to be careful with the case of the PointSource during point definition, and only if the interface will be running on a PINet node communicating to a PI 3 Server.

PI 2 Server Nodes The following point source characters are reserved on PI 2 systems and cannot be used as the point source character for an interface: C, ?, @, Q, T. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.

Before a PI point with a given point source can be created, the point source character must be added to the PI 2 point source table. For example, if point source P is not defined in the PI 2 point source table, a point with a point source of P cannot be created. This prevents the user from accidentally creating a point with an incorrect point source character.

Defining a Point Source Character in the PI 2 Point Source Table

1. Enter PI by typing the following command from a VMS command prompt: @pisysexe:pi

2. Select the PointSrc option from the menu.

3. Select New from the menu.


4. Assign a point source next to the Code: field. Also, assign minimum and maximum values for the Location1 to Location5 attributes.

Location1 Location2 Location3 Location4 Location5

Minimum 0 -19 1 0 0

Maximum 10240 300 385 32 99

5. Select Save from the menu.

PI 3 Server NodesNo point source table exists on a PI 3 Server, which means that points can be immediately created on PI 3 with any point source character. Several subsystems and applications that ship with PI 3 are associated with default point source characters The Totalizer Subsystem uses the point source character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Either do not use these point source characters or change the default point source characters for these applications. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.


PI Point ConfigurationA PI point or tag is a single parameter from a CHIP point. For example, a process variable and a set point are part of the same point in the Fisher system. In the PI System, these parameters are stored as two separate tags. The following PI point attributes determine how values are interpreted as they are moved from CHIP to PI or PI to CHIP.

Point Attributes

TagA tag is a label or name for a point. Any tag name can be used in accordance to the normal PI point naming conventions.

Point SourceThe point source is any one-character value, for example F. The point source must be defined in the point source library before interface operation on version 2.X of the PI system. Also, the point source used in the PI tag definition must match the point source used in the interface startup file. For additional information, see the /ps command-line argument and the “PointSource” section on page 33.

Point TypeTypically, 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.

When the interface is running on Windows or UNIX and writing data to a PI 3 home node, negative integer values can be scanned now, whereas they previously were not. If the interface runs on PINet or a PI 2 home node, this feature is not available. (2.7.0.3).

PI 2 Server NodesScaled real, full-precision real, integer, and digital point types are supported on PI 2 Servers. For more information on the individual point types, refer to the Data Archive (DA) section of PI System Manual I.

PI 3 Server NodesFloat16, float32, int16, int32, digital, string, and blob point types are supported on PI 3 Servers. For more information on the individual point types, see PI Data Archive for NT and UNIX.


PI Point Configuration

Location1This is the CHIP DBI (database index). If Location1 is 0, the CHIP tag name must be in the Instrument Tag 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. Request/response points are supported only on Windows.

Location2This 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 from CHIP to PI. 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.

Location3This 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 (supported only on Windows), 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).

Location4This parameter determines the scan class of the tag. The number of scan classes and the scan frequencies are specified in the interface startup command file. A value of 1 in Location4 assigns this tag to the first scan class specified in the startup file; a value of 3 assigns the tag to the third scan class.

Location5This is the CHIP System Number or the interface ID number. It is used when more than one copy of the interface is running with the same PointSource, possibly on different computers. In the case of copies 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

36

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 point source are loaded, i.e. Location5 is ignored. Interface ID must be in the range -1 to 99, inclusive.

Instrument TagIf Location1 is 0, the Instrument Tag field should contain the CHIP tag name. For compatibility with previous versions of PI-CHIP, this field or the Extended Descriptor field can contain the CHIP tag name.

For request/response points (Location2=0), which are supported only on Windows, this attribute must be set to the response field name. Leading whitespace is ignored and the first trailing whitespace character terminates the field name (the syntax for request/response definition files does not permit whitespace 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-whitespace 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.

Extended DescriptorThe Extended Descriptor can be used to specify a number of attributes for the CHIP interface tag. If Location1 is 0 and the CHIP tag name is not defined in the Instrument Tag field, the first 16 characters of the Extended Descriptor should contain the CHIP tag name.

Also, the interface supports event-based inputs. The syntax for defining an event-based point is to add the following in the Extended Descriptor of the input point:

EVENT=PI tag name, where the PI tag name is the name of the event trigger tag.

Every time the interface receives a new event for the event trigger tag, the interface will obtain a new value for all of the event-based input tags associated with this event tag. A new event is defined as a snapshot event with time stamp greater than the existing snapshot time. The event-based input tags are useful for batch analysis.

As of UniInt 3.3.4, 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. Please refer to the UniInt End-User Interface to the PI System manual for a discussion of the available event_conditions.

Note: Location4, scan class, is ignored for event-based points.

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

PI 2 Server: BIT=X,where X is the bit number from 1 to 16. PI 3 Server: 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.

You 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.For request/response points (supported only on Windows), the Extended Descriptor must contain the name of the file that defines the structure of the request and response messages. 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, whitespace 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’

specify a filename of embedded’quote.

If filename is unquoted, any trailing whitespace 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 syntax of file path specifications depends on the operating system that is running CHIPtoPI. Therefore, CHIPtoPI uses different criteria for deciding whether the filename in an Extended Descriptor is a relative or absolute path.

Windows NT/2000: The native path specification syntax on Windows uses a leading “\” to indicate an absolute path. Windows also accepts “/” as an alternative to “\”. CHIPtoPI 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, CHIPtoPI 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 \winnt\system32. If the interface is started

38

from a command window, the current directory established in the command window will be inherited by the interface.

UNIX: A leading “/” indicates an absolute path on UNIX. CHIPtoPI considers a filename beginning with “/” 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 standard scripts from OSIsoft are used, the working directory for the interface should be $PIHOME/interfaces/chiptopi# where # is interface ID or omitted if all interface copies are stored in a single directory.

VMS: Native VMS path specifications may contain a leading node, drive, or logical followed by a colon. Following the optional node/drive/logical, a directory specification inside square brackets may precede the file name. If a filename contains either “:” or “[“, CHIPtoPI considers it to be an absolute path specification. Since VMS will also accept a UNIX-style path specification, CHIPtoPI considers a filename with a leading “/” to be an absolute path. The -rrdir directory string and the filename in every point’s configuration should use the same style file specification (i.e. both VMS-style or both UNIX-style). Mixing styles may result in invalid path specifications. . If concatenating the –rrdir directory string with filename does not produce an absolute path, the file specification will be relative to the default directory established for the interface process by the set default command.

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. Since some operating systems support case-sensitive file names, the interface’s comparison of filenames for the purpose of sharing responses is also 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= option discussed above may be used to configure a request/response point as an event-based input. The EVENT= option is a UniInt key in the syntax summaries.

Source TagFor outputs, the tag you are creating is only a pointer tag. The name of the tag containing the values to be sent to CHIP must be entered here. If this field remains empty, the pointer tag itself contains the values to be sent.

UserInt1This 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 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. (2.1.8)



ScanBy default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the PI point after the point edit is detected by the interface.

There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.

Point Attributes that Also Affect the Interface ProgramFor further information regarding these attributes, see the UniInt End-User Document.

Exception Deviation

Exception Minimum Time

Exception Maximum Time

Note: Since this interface does exception reporting, the Compression Minimum Time should be less than the scan time for the interface in most situations. The exception reporting algorithm sends values from consecutive scans. If the Compression Minimum Time is too large, the second of these two values will never be recorded. Use the Exception Minimum Time only if it is necessary to throttle data from especially noisy points. The Scan attribute can be used to stop data collection.

Point Attributes that Do not Apply to CHIP Points Square Root

Convers

TotalCode

Input-specific PI Point ParametersThe interface program 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 PointTypePI 3 PI 2

1 PV 1 Float16 (Int16) R (I)

40

Local Inputs


CHIP Parameter Location3 Recommended PI PointType

PI 3 PI 2

Mode 4 Digital (Int16) D (I)

Alarm 5-10 Digital (Int16) D (I)

2 Count 1 Int16 I


4 PV1 1 Float16 R

PV2 2 Float16 R

5 PV 1 Float16 R

SP 2 Float16 R

IVP 3 Float16 R



Output Tracking 35 Float32, Digital R, D

Integral Tracking 36 Float32, Digital R, D

Setpoint Tracking 37 Float32, Digital R, D

7 PV 1 Float16 R

SP 2 Float16 R

IVP 3 Float16 R



Bias or Ratio 11 Float16 R

8 PV 1 Float16 R

SP 2 Float16 R

IVP 3 Float16 R



Bias 11 Float16 R

Ratio 12 Float16 R

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


10 Mode 4 Digital (Int16) D (I)

Number UV's 13 Int16 I



Local Inputs



PI 3 PI 2

Operation Number 14 Int16 I

Step Number 15 Int16 I

Phase Number 16 Int16 I

Unit State 17 Int16 I

Hold Phase Number 18 Int16 I

Operation Complete 19 Int16 I

Unit Status 20 Int16 I

Operation Timer 21 Int16 I

State Timer 22 Int16 I

Step Timer 23 Int16 I

Iteration 24 Int16 I

Fail Index 25 Int16 I

OAR 26 Int16 I

OAR Sequence No. 27 Int16 I

Message Number 28 Int16 I

Message Param 1 29 Float16 R

Message Param 2 30 Float16 R

Activity Point DBI 31 Int16 I

Highway Address of Console 32 Int16 I

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


In/out of Service 13 Digital, Int16 D (I)

Off Scan 14 Int16 I

SP Number 15 Int16 I

PV Number 16 Int16 I

Group Status 17 Digital (Int16) D (I)


12,13 Mode 4 Digital (Int16) D (I)

In/out of Service 13 Digital, Int16 D, I

Off Scan 14 Digital, Int16 D, I

Discrete Value 15 Int16 I

42

Local Inputs



PI 3 PI 2




SP Number 15 Int16 I

PV Number 16 Int16 I

DCD Status 17 Digital (Int16) D (I)

Input Channel Status 18 (note 4) Digital, Int32 D, I

Output Channel Stat 20 (note 4) Digital, Int16 D, I

Interlocks Configured 21 (note 4) Digital, Int16 D, I

Condition – Status 22 (note 4) Digital, Int16 D, I

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

Condition – Override 24 (note 4) Digital, Int16 D, I

Miscellaneous Flags 25 (note 4) Digital, Int16 D, I

Setpoint Disables 26 (note 4) Digital, Int32 D, I

18 PV 1 Float32 (Int32) R (I)

Local DDP 171-186 Float32 (Int32) R (I)

19 Real Value 1 Float32 (Int32) R (I)

ASCIIMSG 34 (note 5) String N/A



Activity State 13 Digital (Int16) D (I)

Activity Status 14 Int16 I

Iteration Count 17 Int16 I

Procedure Index 24 Int16 I

Process Index 25 Int16 I

Hold Process Index 26 Int16 I

Grade Index 27 Int16 I

Point Set Number 28 Int16 I

Activity Index 29 Int16 I

Statement Index 31 Int16 I

Fail Value 32 Int16 I



Local Inputs



PI 3 PI 2

State Timer 33 Int16 I

Batch ID 34 (note 5) String N/A

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

38 (note 4) Digital (Int16) D (I)






State 18 Int16 I

Status Word 19 (note 2) Int16 I

User-Defined integer (2.5.9.0) 20 (note 2) Int16 I

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

38 (note 4) Digital (Int16) D (I)

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

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, Digital, or Real 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 2 tag be defined as Point Type Real and High Precision, and 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 Full Precision Real tags on PI 2 or 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. (2.5.4.0)

Note 5: To scan ASCIIMSG and BATCHID string tags on a VMS PINet node and send them to a PI 3 server, run the PIFTP process and install the BatchFile interface on the PI 3 server or on a PI-API node. This is documented below in a section titled “Appendix B: PI 2 PINet to PI 3 String Tag Support”.

44

Highway Inputs

Location2 CHIP Parameter Location3 Extended Descriptor

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 copy of the interface be run to collect DDPs. Local database reads/writes and Highway outputs can all be collected/written by the same copy of the interface. Supported Remote DDP reads include DDP mnemonic#s 1-385 and mnemonic#s 769-1023.

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

Request/Response Points (supported only on Windows) (note 1)

Location2 Response Field Type (note 2)

Location3 Recommended PI PointTypePI 3 PI 2

0 byte (unsigned) PROVOX address

Digital, Int16 D, I

sbyte (note 3) Digital, Int16 D, I

short (note 3) Int16, Digital I, D

ushort Int32 (Float32) I (R)

int (note 3) Int32 (Digital) I (D)

uint (note 4) Int32 (note 4) R

hpct Float32, Float16 R

real Float32 R

bit# Digital, Int16 D, I

bit field (unsigned) Digital, Int16 D, I

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 copies 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 copy of CHIPtoPI dedicates itself to standard CHIP points only or request/response points only. The first point added by a given copy 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” on page 53 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. On PI 2, Integer point type does not support negative values, so Real point type must be used for negative values that are not suitable for 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-specific PI Point ParametersLocal 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 program 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 program writes a message to the PI Message Log (and PISysExe:CHIPtoPI.out on VMS) when a highway output is not successful.

Local Outputs Recommended PI Pointtype

CHIP Point Type(Location2) CHIP Parameter Location3

-1 PV 1 Int16 I

-4 PV1 1 Int16 I

PV2 2 Int16 I

-5, -7, -8 PV 1 Int16 I

SP 2 Int16 I

-10 Activity Point DBI (ATAG)

31 Int16 I

46

Local Outputs Recommended PI Pointtype

-12 Discrete Value 15 Int16 I

-18 PV 1 Int16 I

-19 PV 1 Int16 I

-21 ASCIIMSG 34 String, Float32, Int32, Digital

I, R, or D

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

R or I

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

Highway Outputs

Location2 CHIP Parameter Location3 Extended Descriptor

41 PV

45 Discrete

47 (note 2) Parallel Discrete

48 Mode Not Used

50 SP (only CHIP Type 1)

51 IVP

52 SP (Supervisory)

53 Bias

54 (note 2) Ratio

84 (note 2) CV float CV number

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. Note 2: Highway outputs for Parallel Discrete (47), Ratio (54), and CV float (84) are not yet supported.

Alarm ProcessingThe 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 point type can be real, 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 “DigitalSet and Digital States” on page 31.

8 - Bit Status ProcessingThe 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.

48

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 Extended Descriptor field BIT= settings must be used:

0 = all bits are to be read (this is optional; if the Extended Descriptor 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 point type can be real, 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.

A sample Digital State table that shows the status On/Off states is in the section “DigitalSet and Digital States” on page 31.

16 - Bit Status ProcessingThe 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 Extended Descriptor field BIT= settings must be used:

0 = all bits are to be read (this is optional; if the Extended Descriptor 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














For bit statuses, the PI point type can be real, integer or digital. The default status states are:

0 = Off

1 = On

For the entire 16-bit status, the PI point type needs to be a Real, Full Precision tag with a Span of 65535.

A sample Digital State table that shows the status On/Off states is in the section “DigitalSet and Digital States”.

Controller Mode ProcessingThe controller modes are shown below. A sample Digital State table that shows these states is in the section “DigitalSet and Digital States”.

1 - MAN

2 - AUTO

3 - RSP

4 - SUP

5 - DDC

6 - COM

7 - HMAN

50

PIDIFF/PICONFIG and CHIP GENERThe 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. You can often use this same ASCII file, with some editing, to create points in PI. The file is used as a data file for the PI tag database creation/maintenance utility, PIDIFF on a PI 2 system or PICONFIG on a PI 3 system.

When using the GENER input file as the data file for PIDIFF or PICONFIG, consider the following fields:

GENER Keyword PIDIFF/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 exception deviation and exception minimum time.

Since the interface is using the CHIP routines 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 PIDIFF structure file for using this file to create new PI points in 2.X PI system and a PICONFIG file to create tags in 3.X PI system.

RECORD 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.00PIdiff structure file for 2.X PI system:* Structure1.pdf* Oil Systems, Inc.** Structure file for creating PI Points from the CHIP * file shown above.** Directiveserrormax,0errorfile,PISysMgr:Errorfile.pdf** Defaulted Itemspointtype,DEFAULT,Rpointsource,DEFAULT,Flocation3,DEFAULT,1location5,DEFAULT,1excmax,DEFAULT,600res,DEFAULT,2** Tag Attributestag,8,16,10descriptor,9,16,16engunits,10,16,10typicalvalue,11,16,10zero,12,16,10span,11,16,10location1,2,22,5location2,3,24,3excdev,6,21,6excmin,7,24,3** End of file

52

The corresponding PIConfig structure definition section for creating tags in PI 3.X system is:

* chipconfig.pdf* Oil Systems, Inc.** 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 FilesThe request/response points are supported only on Windows.

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: that the same request message sent to different types of PROVOX devices can and do



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 (i.e., keywords will be recognized in upper, lower, or mixed case).

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 type, value pairs that define the request I-frame contents. The type of each pair is one of the keywords:

byte the unsigned value fills the next I-frame byte

sbyte the signed value fills the next I-frame byte

short the signed value fills the next 2 bytes

ushort the unsigned value fills the next 2 bytes

int the signed value fills the next 4 bytes

uint the unsigned value fills the next 4 bytes

hpct the floating-point value is converted to highway percent and fills the next 2 bytes

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

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.

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

54

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 typeThe 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, i.e. a point’s Instrument Tag 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; etc. 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

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

request: 178 #Detailed Device Status Request1 byte 0

response: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 slots



FreeDevices 11 byte #Number of free devicesSimplex 12 byte #Simplex or redundantTo configure a point to scan the average 1-minute load for the Integrated Function Controller (IFC) at Data Highway address @2-19 using the above file, set the point attributes to:Location2=0 (request/response point type)Location3=219 (Data Highway address)Location4=scan classLocation5=interface IDPointSource=interface point sourceInstrumentTag=load1minavgExDesc=IFC_UOC_Detailed_Status.txt

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. 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 busys 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, busys 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, etc. 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

56

decoded as individual fields. The 16 file select and file status fields are not defined in this file.

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 versions of these utilities for all platforms will accept a “-“ as an option indicator. Windows NT/2000 and VMS will also recognize “/” as an option indicator, as does CHIPtoPI. However, the UNIX versions of the utilities do not recognize “/” as an option indicator because it would be ambiguous with an absolute path specification.

The 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.The 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 fileThe 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 Request request: 128 # Device Type Request 2 # one point number short 0 # point 0 is the device itself



response: ResponseCode 0 byte #Request Code UnusedByte1 1 byte # UnusedByte2 2 byte # DeviceType 3 byte #

The command line and output from the utility follow:chipsendreq -h2 -d17 -f Device_Type.txtDevice Type RequestResponse from request 128 to @2-17field index value descriptionResponseCode 1 128 Request CodeUnusedByte1 2 0UnusedByte2 3 0DeviceType 4 196From 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 an IFC.

58

Performance Point ConfigurationOne can configure performance points to monitor the amount of time in seconds that it takes an interface to complete a scan for a particular scan class. The closer the scan completion time is to 0 seconds, the better the performance. The scan time is recorded to millisecond resolution.

Configuring Performance Points with PI-Interface Configuration Utility

Configuring Performance Points ManuallyPerformance point configuration is the same on all operating system platforms. Performance points are configured as follows.

1. Set the extended descriptor to:PERFORMANCE_POINTor toPERFORMANCE_POINT=interface_idwhere interface_id corresponds to the identifier that is specified with the /id flag on the startup command line of the interface. The character string “PERFORMANCE_POINT” is case insenstive. The interface_id does not need to be specified if there is only one copy of an interface that is associated with a particular point source.

2. Set Location4 to correspond to the scan class whose performance is to be monitored. For example, to monitor scan class 2, set Location4 to 2. See the /f flag for a description of scan classes.

3. Set the PointSource attribute to correspond to the /ps flag on the startup command line of the interface.

4. Set the PointType attribute to float32.


I/O Rate Tag ConfigurationAn IO Rate point can be configured to receive 10-minute averages of the total number of exceptions per minute that are sent to PI by the interface. An exception is a value that has passed the exception specifications for a given PI point. Since 10-minute averages are taken, the first average is not written to PI until 10 minutes after the interface has started. One IO Rate tag can be configured for each copy of the interface that is in use.

Configuring IORates Tags with PI-Interface Configuration Utility

Configuring IORates Tags ManuallyThere are two configuration steps.

Configuring the PI Point on the PI Server

PI 2 Server NodesA listing of the IO Rate Tags that are currently being monitored can be obtained with the command:@PISysDat:IOMonitor.comCreate an IO Rate Tag using one of the existing IO Rate Tags as a template. The IOMonitor program is discussed on page DA-71 of PI System Manual I.

PI 3 Server NodesCreate an IO Rate Tag with the following point attribute values.

Attribute Value

PointSource L

PointType float32

Compressing 0

ExcDev 0

The default settings can be used for the remaining PI point attributes. When Compressing is set to Zero, the IO Rate Tag acts like a heartbeat tag for the interface, which can be examined easily in ProcessBook with markers turned on. If a value is not written to the IO Rate Tag every 10 minutes, then there is problem with the interface communication.


Configuring on the Interface NodeFor the following examples, assume that the name of the PI tag is chiptopi001, and that the IO Rate point on the home node is chiptopi001.

NT Nodes

1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the \WINNT directory. If both are specified, the PIPCSHARE entry takes precedence. Since the PIHOME directory is typically C:\PIPC, the full name of the iorates.dat file will typically be C:\PIPC\dat\iorates.dat.Add a line in the iorates.dat file of the form:chiptopi001, xwhere chiptopi001 is the name of the IO Rate Tag and x corresponds to the first instance of the /ec=x flag in the startup command file. x can be any number between 1 and 34 or between 51 and 200, inclusive. However, it is best to use an event counter, x, that is not equal to 1 because 1 is the default event counter for UniInt-based interfaces. To specify additional rate counters for additional copies of the interface, create additional IO Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x, should be unique for every interface instance on a computer.

2. Set the /ec=x flag on the startup command file of the interface to match the event counter in the iorates.dat file.

3. The interface must be stopped and restarted in order for the IO Rate tag to take effect. IORates will not be written to the tag until 10 minutes after the interface is started.

The 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook.

UNIX Nodes

1. Edit/Create a file called iorates.dat in the $PIHOME\dat directory. PIHOME is an environment variable that is set equal to the PI home directory name as discussed in the PI-API Installation Instructions manual. Add a line in the iorates.dat file of the form:chiptopi001, xwhere chiptopi001 is the name of the IO Rate Tag and x corresponds to the first instance of the /ec=x flag in the startup command file. x can be any number between 1 and 34 or between 51 and 200, inclusive. However, it is best to use an event counter, x, that is not equal to 1 because 1 is the default event counter for UniInt-based interfaces. To specify additional rate counters for additional copies of the interface, create additional IO Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x, should be unique for every interface instance on a computer.

2. Set the /ec=x flag on the startup command file of the interface to match the event counter in the iorates.dat file.


3. The I/O rates shared memory server and the I/O rates monitor program must be stopped and started for the changes to take effect. The easiest way to do this is to run the pistop and pistart command scripts with the following commands.sh $PIHOME/bin/pistopnohup sh $PIHOME/bin/pistart

One can determine that the shared memory server and the I/O rates monitor are running with the commands:ps –ef | grep ioshmsrv

ps –ef | grep iorates

The 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook.

Open VMS NodesIORates are discussed on page DA-59 of PI System Manual I.

To implement an IO Rate tag, perform the following steps:

1. Add a line to the PISysDat:IORates.dat file of the form:CHIPTOPI001, xwhere chiptopi001 is the name of the IO Rate tag for this copy of the interface and x corresponds to the event counter specified by the first instance of the /ec=x flag in the startup command file of the interface. x can be any number between 1 and 34 or between 51 and 200, inclusive. However, it is best to use an event counter, x, that is not equal to 1 because 1 is the default event counter for UniInt-based interfaces. The event counter, /ec=x, should be unique for each copy of the interface. Note that the PISysDat:IORates.dat file must be edited on the node where the interface is running. That is, if the interface is running on a PINet node, then the PISysDat:IORates.dat file on the PINet node must be edited, not the PISysDat:IORates.dat file on the home node.

2. Set the /ec=x flag on the startup command file of the interface to match the event counter in the PISysDat:IORates.dat file.

3. Stop and start the IORates process with the following commands so that the changes take effect. @PISysExe:stop iorates@PISysExe:iorates.com

The rate (events/minute) can be monitored with the PISysExe:IOMonitor.exe program or with another client program such as Process Book. The IOMonitor program is discussed on page DA-71 of PI System Manual I.


Startup Command FileThe CHIPtoPI interface on Windows has an ICU Control that will aid in configuring the CHIPtoPI interface startup command file:

The CHIPtoPI control for PI-ICU has four sections. A yellow text box indicates that an invalid value has been entered or that a required value has not been entered.

General

Pause before connecting to CHIPThis 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.

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

Update DBIsIn the Update DBIs every x hours text 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.


Startup Command File

Number of times to retry a failed DDP readIn the Number of times to retry a failed DDP read text 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 directory to the path where the request/response definition files are stored.

Debug LevelsThe Debug Levels flag 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.

FailoverA detailed discussion of failover can be found later in this manual in a section titled “Failover” on page 89.

Enable failoverIf checked, failover is to be enabled. The command line equivalent for NT/2000 is /fo=x, where x is the number associated with the APIOnline process discussed in the “Failover” section.

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 interface node may optionally be entered. The command line equivalent is /primary=x.

Secondary CHIP addressThis is required only on the primary interface node and is the CHIP address of the secondary node. The first text box is the highway number. The second text box is the device number. The CHIP address can be retrieved by running CHIP_UTIL on the secondary interface 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 run select option 6:

CHIP Local Utilities Menu 1 - FSLOG - CHIP Error Logging Program 2 - SMRY - CHIP Database Summary

66

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- 0The command line equivalents are /fosh=x and /fosd=x, respectively.

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=x, where x 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=x, where x 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=x, where x is the digital state.

Failover numberThe Failover number only applies to failover on Windows NT/2000. The failover number is the number assigned to APIOnline. The command line equivalent is /fo=x, where x is the failover number.

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.

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 /fo=asa, where x is the maximum number.



Error thresholdThe Error threshold is the number of 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 to check the connection to the Data Highway, and then failover if necessary. The command line equivalent is /fo9=x, where x is the number of error 9s.

Additional ArgumentsThe Additional Arguments section is provided for any other parameters that are not directly configurable from the CHIPtoPI ICU Control.

Command-line ParametersThere are several option parameters in chiptopi.bat (WinNT), chiptopi.sh (UNIX), and CHIPtoPI.com (VMS) that control the operation of the interface program. Some of the parameters are optional. The parameters are described in the table below:

Command-line Parameters

/h Running the interface from a command prompt with /h as the only parameter causes the interface to print its version and a list of parameters – essentially an on-line summary of this table.

/help or /? Running the interface from a command prompt with /help or /? as the only parameter causes UniInt to print its version, a list of UniInt Service configuration parameters, and a list of UniInt generic interface parameters.

/ddprr=x

optional, default:

/ddprr=1

The /ddprr= flag 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 flag is not specified, the default number of DDP read retries is one.

/hiway Enables Highway Outputs.

/file=fn This parameter is required if string data will be sent to PI 3 string tags from an interface running on VMS. It defines the file that will be FTP’ed to the PI 3 home node for use by the Batch File Interface. You will need to specify the logical and file name: /file=PIFTPDIR:STRTAGS.NEW. This needs to match up with the settings in the piftp.com file.

/sp=x(1.1.9.2)

Where x is in milliseconds. This tells the interface to pause x milliseconds before loading the CHIP DB points into the interface to allow for CHIP to startup fully. The default is not to pause on startup.

/udbi=x(2.0.8)

Update DBIs every x hours. X can be any number from 1 to 24. The default is to update DBIs once every 24 hours. (2.0.8)

/db=level(2.5.7.0)

The /db flag 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 switch. To turn on every debug switch specify:

68

/dbor /db=-1

To turn off all debug messaging, either remove the /db from the command line, or specify:/db=0

Note 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

Debug Switches Section of code that is debugged

0 No debug messages written

1 Initialization

2 Point adds, edits, and deletes

4 Inputs

8 Outputs

16 Failover

64 All on

128 Not used yet

256 Not used yet

UNIINT Settings

/dbuniint=level(uniint ver. 3.2.0)

The /dbuniint flag is used to set a debug level for debugging UniInt code. level is a 32-bit integer. Setting a particular bit in level to 1 turns on a particular debug switch. To turn on every debug switch specify:

/dbuniint=0xFFFF

Note that level can be specified as either a decimal number or a hexadecimal number. A 0x must precede hexadecimal numbers.


0x0002 Initialization

0x0004 Point addition (add_pt)

0x0008 Exit handler

0x0010 Sending data to PI (update_pi)

0x0020 The main control loop

0x0040 Point list creation (load_lists)

0x0080 Point edits

0x0100 IO Rate Points



0x0200 Services

/sn Tells the interface to ignore the exception specifications of the tag and put all the input events into the PI snapshot. By default, to reduce data traffic, the /sn flag is not used.

/ps=x

required

The /ps flag specifies the point source for the interface. x is not case sensitive and can be any single character. For example, /ps=P and /ps=p are equivalent.

The point source that is assigned with the /ps flag corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source.

/id=x The /id flag 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.

UniInt always uses the /id flag in the fashion described above. This interface also uses the /id flag to identify a particular interface copy number that corresponds to an integer value that is assigned to Location5. For this interface, one should use only numeric characters in the identifier. For example,

/id=1

Valid values are -1 to 99, inclusive. See discussion in section “Location5”.

/f=SSor/f=SS,SSor /f=HH:MM:SSor/f=HH:MM:SS,hh:mm:ss

Required for reading scan-based inputs

The /f flag defines the time period between scans in terms of hours (HH), minutes (MM), and seconds (SS). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), and seconds (ss). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds.

Each instance of the /f flag 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 flag 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) + offset

70

where n is an integer and the reference time is midnight on the day that the interface was started. In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class. This means that if the interface was started at 05:06:06, the first scan would be at 05:06:10, the second scan would be at 05:07:10, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined.

The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the interface is under a large load, then some scans may occur late or be skipped entirely. See the section called “Performance Point Configuration” on page 59 of this manual and “Performance Summaries” in UniInt End-User Interface to the PI System for more information.Wall Clock SchedulingScan classes that strictly adhere to wall clock scheduling are now possible. This feature is available for interfaces that run on NT and/or UNIX. Previously, wall clock scheduling was possible, but not across daylight savings time. For example, /f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a Daylight Savings Time change, the scan would occur either at 7 AM or 9 AM, depending upon the direction of the time shift. To schedule a scan once a day at 8 AM (even across daylight savings time), one should use /f=24:00:00,00:08:00,L. The ,L at the end of the scan class tells UniInt to use the new wall clock scheduling algorithm.

/host=host:port

optional for NT and UNIX

Not implemented for VMS interface nodes

The /host flag is used to specify the PI Home node. host is the IP address of the PI Sever node or the domain name of the PI Server node. port is the port number for TCP/IP communication. The port is always 5450 for a PI 3 Server and 545 for a PI 2 Server. It is recommended to explicitly define the host and port on the command line with the /host flag. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults.

Defaults:

The default port name and server name is specified in the pilogin.ini or piclient.ini file. The piclient.ini file is ignored if a pilogin.ini file is found. Refer to the PI-API Installation Instructions manual for more information on the piclient.ini and pilogin.ini files.

Examples:The interface is running on a PI-API node, the domain name of the PI 3 home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host flags would be:/host=marvin /host=marvin:5450 /host=206.79.198.30/host=206.79.198.30:5450



/stopstator/stopatat=digstate

default:/stopstat=shutdown

optional

If the /stopstat flag is present on the startup command line, then the digital state I/O Timeout will be written to each PI Point when the interface is stopped.

If /stopstat=digstate is present on the command line, then the digital state digstate will be written to each PI Point when the interface is stopped. For a PI 3 Server, digstate must be in the system digital state table. For a PI 2 Server, where there is only one digital state table available, digstate must simply be somewhere in the table. UniInt uses the first occurrence in the table.

If neither /stopstat nor /stopstat=digstate is specified on the command line, then no digital states will be written when the interface is shut down.

Examples:/stopstat=shutdown

The entire parameter is enclosed within double quotes when there is a space in digstate.

There is some debate as to the recommended usage of the /stopstat parameter. To many, the default digital state, I/O Timeout, implies that there is some communication problem with the interface, not that the interface has stopped. There is also a problem with /stopstat=shutdown because shutdown is written to PI tags when the PI Server is shut down. This makes it impossible to tell whether the shutdown digital state is from the interface shutting down or from PI shutting down. Unfortunately, there is no digital state that clearly indicates that an interface has been shut down. One solution is for the user to add an appropriate digital state, such as Inf Down, to the PI 3 system digital state table or the PI 2 digital state table. Editing the PI 2 digital state table is straightforward. Editing the PI 3 digital state table must be done using the piconfig utility. The piconfig utility is described in PI Data Archive for NT and UNIX.

/ec=x

optional

The first instance of the /ec flag on the command line is used to specify a counter number, x, for an I/O Rate point. If x is not specified, then the default event counter is 1. Also, if the /ec flag is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, each copy of the interface that is running without /ec=x explicitly defined will write to the same I/O Rate point. This means that one should either explicitly define an event counter other than 1 for each copy of the interface or one should not associate any I/O Rate points with event counter 1. Configuration of I/O Rate points is discussed in the section called “I/O Rate Tag Configuration.”

For interfaces that run on NT nodes, subsequent instances of the /ec flag may be used by specific interfaces to keep track of various input or output operations. Subsequent instances of the /ec flag 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. CHIPtoPI does not implement any additional event counters.

72

/sio

optional

The /sio flag stands for “suppress initial outputs.” The flag applies only for interfaces that support outputs. If the /sio flag 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 flag 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 flag is specified, outputs will only be written when they are explicitly triggered. See also the /hiway flag.

/tcq

optional

The /tcq flag stands for “Toggle Chip Questionable status.” If the /tcq flag 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. (2.9.0.5)

/q

optional for NT and UNIX

not implemented for interfaces on VMS PINet nodes

When the /q flag is present, snapshot updates and exceptions are queued before they are sent to the PI Server node.

CHIPtoPI uses Extended API mode behavior:

The maximum queue size is close to 4000 bytes. The queue is flushed between scans if it is not filled.

VMS Only Settings

/fs=x

optional, PINet only,default: /fs=,

The /fs flag is used to set the field separator in the files that are used for UniInt's automatic FTP mechanism for sending string tags from a PINet node to a PI 3 Server node.

The default field separator is a comma (,).

/usepinettime

optional, PINet only

UniInt v3.4.9

Assume local time is the same as server time. Calls to the PI home node for time will not be made.

Windows Only Settings

/rrdir=dir

optional, Windows only

The /rrdir= flag provides the default directory specification to use with request/response points that have a relative definition file name. The syntax of dir is specific to the operating system on which the interface is running and must be suitable for prepending to a relative file name:

dir must end with “/” or “\”.

Details on how this flag affects the interface can be found in the “PI Point Configuration” section under “Extended Descriptor”.

Failover Settings for Windows and VMS



/fo /fo=x

VMS: /fo enables failover. NT: /fo=x is required, where x is the number assigned to APIOnline. See the section entitled “Failover” on page 89 for more information on what number to user for x.

/fo9=x (2.7.2.0)

Not required. This flag 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 to see if its connection to the CHIP data highway is good.

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

/secn=x Required on both nodes in a failover setup. Name of partner node in a failover setup: /secn=dragon

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

/fds=x Required on both nodes in a failover setup. Name of the digital state from the failover tag’s digital state set that is assigned to current node as a flag for who is collecting. See the section entitled “Failover” on setting up the failover tag and the digital state set for this tag: /fds=wolverine

Failover Settings for Windows Only

/fosh=x(2.7.5.0)

NT Only: Required only on the primary node in a failover setup. This is the highway number of the secondary node: /fosh=1

/fosd=x(2.7.5.0)

NT Only: Required only on the primary node in a failover setup. This is the device number of the secondary node: /fosd=0

/foasa=x(2.7.5.0)

NT Only: Optional, and applies only to the primary node. This overrides the default setting of 40 stop attempts to be used by the primary when it attempts to stop the APIOnline process either on the primary or secondary node: /foasa=60

/fohm=x

optional

NT Only: Optional. This flag overrides the default setting of 60 seconds between checks to verify communication with the Data Highway. Valid range for x is 1 to 1800 seconds.

Failover Settings for VMS only

/fop=x VMS Only: Name of a failover output point that the primary node writes to and the secondary node reads. If the point on the CHIP device is not updating, the secondary node will start SCANNING. When the point starts updating, the primary node will start SCANNING and the secondary node will go back to STANDBY. This will prevent both nodes from SCANNING when the DECnet communication fails.

/fow=x VMS Only: minimum number of seconds between writing to the failover output point (/fop=x). Only used on primary node. Default is 1

74

/for=x VMS Only: minimum number of seconds between reading the failover point (/fop=x). Only used on secondary node. Default is 5

/foc=x VMS Only: Number of times the failover value has not changed to proclaim primary node is down. Only used on secondary node. Default is 2.

The following is a sample interface startup command file.chiptopi /ps=F /id=1 /host=localhost:5450

/f=00:00:10,21:00:05 /f=00:00:12,00:00:00


Interface Node Clock

NTThe correct settings for the time and time zone should be set in the Date/Time control panel. If local time participates in Daylight Savings, from the control panel, configure the time to be automatically adjusted for Daylight Savings Time. The correct local settings should be used even if the interface node runs in a different time zone than the PI Server node.

Make sure that the TZ environment variable is not defined. The currently defined environment variables can be listed by going to Start | Settings | Control Panel, double clicking on the system icon, and selecting the environment tab on the resulting dialog box. (On Windows 2000, select the Advanced tab, then click the Environment Variables button.) Also, make sure that the TZ variable is not defined in an autoexec.bat file. When the TZ variable is defined in an autoexec.bat file, the TZ variable may not appear as being defined in the System control panel even though the variable is defined. Admittedly, autoexec.bat files are not typically used on NT, but this does not prevent a rogue user from creating such a file and defining the TZ variable unbeknownst to the System Administrator.

UNIXThe correct time and time zone must be configured on the interface node. Also, the interface node should be configured to automatically adjust for daylight savings time for locations that use daylight savings time. The correct local settings should be used even if the interface node runs in a different time zone than the PI Server node.

VMSBy default, the system time of a PINet node is synchronized with the system time on the PI Server node once every hour by the PINETSYNC program. The behavior of the PINETSYNC program can be altered by editing the PINet:PINetSync1.com file. The synchronization interval can be changed, a time offset between the PINet node and the server node can be applied, and/or time synchronization can be disabled. The command-line parameters for implementing these changes are described in the PINet:PINetSync1.com file itself.

By default, the interface will also ask for the PI server time to adjust for time differences. This is done every 30 minutes. If the PI 3 server computer is offline(shutdown or off the network), this will cause the interface to hang for 5 minutes. The interface startup parameter /usepinettime will disable this.


Security

NT and UNIX If the home node is a PI 3 Server, the PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Data Archive. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Data Archive Manual.

If the home node is a PI 2 Server, the read/write permissions should be set appropriately in the PISysDat:PIServer.dat file on the PI 2 home node. For more information on setting permissions on PI 2, see the PIBuild:PIServer.txt file on the PI 2 home node.

If the interface cannot write data to a PI 2 or PI 3 Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. See “Appendix A: Error and Informational Messages” for additional information on error messages.

VMS If the interface runs on a PINet node and communicates to a PI 3 Server, make sure that the PI Firewall Database and the PI Proxy Database are configured so that the PINet node is allowed to write data to the PI Data Archive. For more information, see “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Data Archive manual.

If the interface runs on a PINet node and communicates to a PI 2 Server, make sure that the PINet node has read/write permission to the PI 2 Archive by checking the configuration in the PISysDat:PIServer.dat file on the PI 2 home node. For more information on setting permissions on PI 2, see the PIBuild.PIServer.txt file on the PI 2 Server.

If the interface cannot write data to a PI 2 or PI 3 Server owing to permission problems, error –10401 will be written to the PISysMgr:PIMesslog.txt file.


Starting / Stopping the Interface on NT

CHIPtoPI as an NT Service

The CHIPSERVICEThe CHIPtoPI interface can only be started after the CHIP software has been started. The CHIP on NT software supports NT 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. You use the CHIP chipserv utility to configure the CHIP software to run as a service:D:\CHIP\chipserv -install Account_string Password_stringwhere

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, Section on “INSTALLING, STARTING AND STOPPING CHIP AS A NT SERVICE”.

The CHIPtoPI ServiceTo register the CHIPtoPI service to execute from the executable's directory:c:\pi\interfaces\chiptopi\chiptopi –install –depend

“chipservice tcpip”to register CHIPtoPI as a manually-started service, orc:\pi\interfaces\chiptopi\chiptopi –install –auto –depend

“chipservice tcpip”to register the CHIPtoPI service to start automatically at NT startup. Both commands assume that CHIPtoPI is installed on a node without Bufserv. If Bufserv is installed as a service, tcpip in the above commands should be replaced with bufserv.

The CHIPtoPI interface service is now dependent on the CHIP service. If the CHIP service is stopped, the CHIPtoPI interface service will be stopped first. If the CHIPtoPI interface service is started and the CHIP service is not started, the CHIPtoPI interface service will not start successfully, but the CHIP service will be started. You will have to start the CHIPtoPI interface service again. You can set the CHIP service and the CHIPtoPI interface service to automatic. This way, the services will always be started in the correct order.


Starting, Stopping, Querying, and Removing the CHIPtoPI ServiceOther command line parameters are listed as:

-remove Remove the CHIPtoPI Service

-start Start the CHIPtoPI Service

-stop Gracefully stop the CHIPtoPI Service

-query Query the CHIPtoPI Service

-help Print usage statement

The -depend option is only valid with the -install action

CHIPtoPI Interactively, not as a ServiceIf you do not configure the software to run as a service, you can startup the system manually.

You can start the interface by typing:chiptopi.bat at the command prompt.


Starting / Stopping the Interface on UNIX This section describes starting and stopping the interface as a background process. See the UniInt End-User Document to run the interface as a foreground process or to install the interface to start with PI or PI-API. In the procedures below, interface number 1 is used as an example. For other copies of the interface, replace chiptopi1 with chiptopi# where # is the interface number. If you are working with the only copy of the interface, replace chiptopi1 with chiptopi.

Command-Line Syntax for Background ProcessesJobs that are run in the background remain in existence even after the user that has started the process has logged off of the system. The command line in the chiptopi1.sh startup command file should begin with nohup and end with &. For example:nohup chiptopi1 program_arguments > chiptopi1.log 2>&1 &The & at the end of the command line causes the job to be launched in the background. The nohup at the beginning of the command line causes hang-ups and quits to be ignored. HP-UX boxes are notorious for sending hang-up signals to jobs that a user has started when that user logs off. Always execute a background job with nohup, either by incorporating it into the startup command file of the interface or by typing nohup chiptopi1.sh or nohup sh chiptopi1.sh from the terminal. Unless the job is executed with nohup, the hang-up signal will cause the job to be terminated even if it is run in the background.

A job that is started with nohup will have its standard output and standard error redirected to the file nohup.out, unless the standard output is redirected to a different file name. On the command line above, the standard output is redirected with the > director to the file chiptopi.log.

The optional sequence 2>&1 causes the standard error to be redirected to standard output so that the standard error will also appear in chiptopi.log. System commands typically send error messages to the standard error. For example, the command:cat nonexistentfilefails with the error message “cat: cannot open nonexistent file: No such file or directory.” This error message is written to the standard error, which is normally seen on the screen.

Typically, messages that interfaces write to the standard output are also written to the $PHOME/dat/pimesslogfile. To avoid this duplication, the user can redirect the standard output to the null device, which discards the messages. For example:nohup chiptopi1 program_arguments > /dev/null &redirects the standard output to the null device. Initially, it is recommended to use the first command-line example, where the output is redirected to the chiptopi1.log file.


Terminating Background ProcessesFirst, obtain the process id (pid) of the background job. This is done as follows. First execute the command:ps –ef | grep chiptopiwhich produces output similar to:matzen 12788 12707 2 09:55:27 ttys1 0:00 chiptopi1 /ps=B …The second column is the pid of the process. That is, 12788 is the pid of the chiptopi1 interface in the example above.

The process is then stopped by:kill 12788The kill command sends the SIGTERM signal to the interface, causing the exit handler to be invoked.

Unless it cannot be avoided, do NOT kill the interface with kill –9 pid. The option -9 causes the SIGKILL signal to be sent to the interface. The exit handler cannot catch this signal. SIGKILL will immediately terminate the process.

Anomalous Background Job TerminationOn some platforms, processes that are started in the background will be terminated if one types “control-c” in the same window that the job was started in. If one closes the window in which the interface was started or if one logs off and logs back on, the user will not be able to accidentally terminate the job in this manner.


Starting / Stopping the Interface on VMS This section describes starting and stopping the interface as a detached process. See the UniInt End-User Document to run the interface interactively or to configure the interface to start and stop with PI or PINet.

Starting a Detached ProcessThe interface is started as a detached process with the chiptopidetach.com command file. Typically, the chiptopidetach.com file does not need to be edited, because the command-line parameters are edited in the associated chiptopi#.com file. However, in some cases it may be necessary to edit the chiptopidetach.com file to increase quotas such as the page file size. Detached processes continue running after the user who started the process logs off.

The following is an example of a chiptopidetach.com file.

$! CHIPtoPIDetach.com

$! chiptopidetach.com starts the CHIPtoPI interface as a detached process

$! by detaching the command file chiptopi.com.

$!

$! the following parameter must be passed:

$!

$!

$ if (f$search("pisysexe:chiptopi.com") .nes. "") then goto NextStep

$ goto BadFile

$!

$NextStep:

$ if (f$search("pisysexe:chiptopi.out") .nes. "") then -

purge/keep=3 pisysexe:chiptopi.out

$!

$run/detach/uic=[chip]/proc="CHIPtoPI"/priority=4 -

/input=pisysexe:chiptopi.com -

/output=pisysexe:chiptopi.out-

/working_set=1024/maximum_work=2048/extent=4096 -

/pagefile=100000/buffer=20480 sys$system:loginout

$ exit

$!


$BadFile:

$ write sys$output "File PISYSEXE:CHIPtoPI.COM does NOT Exist...Interface NOT Started"

$ exit

$! End of File

$

Assuming that the example command file is used to start the interface, the following command will start the interface as a detached process:@PISysExe:chiptopidetach

The name of the process will be “CHIPtoPI” as defined by the /proc flag to the run command in the above command file

The example chiptopidetach.com command file performs the following tasks in the order listed.

The command file checks whether the interface number is passed as a command-line parameter to chiptopidetach.com. If it is not passed, the command file will terminate with the error message:The Interface # must be passed.

chiptopidetach.com searches for the existence of the PISysExe:CHIPtoPI.com file, which is the file where the command-line parameters for the interface are set. If the file does not exist, the command file will terminate with the error message:chiptopi.com does not exist.

chiptopidetach.com searches for the existence of the PISysExe:chiptopi.out interface-specific log file. If the file exists, the command file executes the purge command to eliminate all but the last three versions of this file.

The CHIPtoPI1 process is started with the run command. Several actions are performed by the run command:

The name of the process is set to CHIPtoPI1 by the /proc flag.

The UIC of the process is set to the system account by the /uic flag.

The priority of the process is set to 4 by the /priority flag.

The input command file for the process is set to PISysExe:chiptopi.com by the /input flag.

The standard output from the interface is redirected to the PISysExe:chiptopi.out file by the /output flag.

The remaining parameters, /working_set, /maximum_work, /extent, /pagefile, and /buffer, are used to adjust the resources that are available to the interface.


StoppingTo stop the interface, issue the following command:@PISysExe:stop CHIPtoPI


Failover

General Failover OverviewThe failover configuration permits greater reliability through increased up-time. Failover requires compatible CHIP databases on the redundant nodes (except for the CHIP exception reporting parameters). Every CHIP point that is a PI input or output must be in both CHIP databases with the same database indexes (DBI's) or CHIP tag names.

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

A failover digital tag, specified by 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.

Both copies of the interface will pickup all CHIPtoPI tags and will scan them at their designated scan rate. However, only the interface that is currently SCANNING will send this data to PI. The STANDBY interface will not send its data.

Failover is handled similarly on OpenVMS nodes and Windows NT/2000 nodes. The following discussions address the differences of the two Failover schemes.

Microsoft Windows NT/2000 Failover OverviewThe failover logic uses one communication path to the redundant node. The path issues a Device Status request via the PROVOX highway to determine the health of the other CHIP device. In normal operation, the primary node is SCANNING and the secondary node is in STANDBY. When either link to the primary node fails, the secondary node switches to SCANNING. The primary node switches to STANDBY in the case where the pipe link is good but the Device Status request failed. When the failure condition ends, the secondary node switches back to STANDBY and the primary node switches to SCANNING.

OpenVMS Failover OverviewThe failover logic uses two communication paths to the redundant node. The first path is a link between the two interfaces programs that use DECnet task-to-task communication. The second path issues a Device Status request via the PROVOX highway to determine the health of the other CHIP device. In normal operation, the primary node is SCANNING and the secondary node is in STANDBY. When either link to the primary node fails, the secondary node switches to SCANNING. The primary node switches to STANDBY in the case where the DECnet link is good but


the Device Status request failed. When the failure condition ends, the secondary node switches back to STANDBY and the primary node switches to SCANNING.

When the interface on either node changes from SCANNING to STANDBY, the command procedure PISysExe:CHIPOffScan.com is executed as a detached process. This command procedure can be used to load a CHIP database with modified exception reporting parameters. It can also be used to stop or notify user applications that depend on CHIP data. When the interface changes from STANDBY to SCANNING, command procedure PISysExe:CHIPOnScan.com is executed. The output files for the detached processes have the same name as the command file but the extension is .out. The detached processes run at priority 4 with the UIC of the interface process and a process name of PI-CHIPOffScan or PI-CHIPOnScan.

With version 2.7.4 or higher, a third communication path has been added. A failover output tag is designated (command line /fop= parameter) that the primary node writes to and the secondary node reads. If the point on the CHIP device is not updating, the secondary node will start SCANNING. When the point starts updating, the primary node will start SCANNING and the secondary node will go back to STANDBY. This will prevent both nodes from SCANNING when the DECnet communication fails.

General Failover InformationThe following general information addresses both VMS and Windows failover.

Enabling Failover on All PlatformsTo configure the interface startup file to enable failover on VMS, specify /fo on the command line. To configure the interface startup file to enable failover on NT/2000, specify /fo=x on the command line, where x is the number discussed below in the NT specific section.

To configure the interface startup file to specify one node as primary (required), specify /primary=nodename on the command line of the primary node. On OpenVMS, this nodename is the DECnet node name (not the TCP/IP hostname); on WinNT/2000, this nodename is the TCP/IP hostname.

CHIPtoPI failover uses network objects on VMS and named pipes on NT/2000 to allow inter-process communication between the two failover nodes. Therefore, 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.

If an incorrect hostname or node name is specified, each interface will never successfully connect to its partner failover node. Failover is not initialized until the first successful connection between both the primary and secondary nodes, and each interface will continue to attempt to connect for the duration of its up-time. Failover will never be initiated until there has been a successful connection between the two nodes.

On VMS, you need to be able to set host between the two failover nodes; on NT/2000, you need to be able to ping or telnet between the two failover nodes.


Failover Tag (All Platforms)CHIPtoPI 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 to signify each of the two nodes in the failover cluster. For example, if the primary node is wolverine, and the secondary node is dragon, a failover tag, such as chipfailtag, needs to be created with wolverine and dragon as its digital states. Below is an example for creating this tag on a PI 2 home node, and an example for creating this tag on a PI 3 home node.

PI 2 Home NodeFirst, add the digital states representing the failover nodes to the Digital State Table.

Second, create the tag with PIDiff using the following structure file and data file.

Chipfotag.str:tag,1,1,12pointsource,1,14,1pointtype,1,17,1digstartcode,1,20,12dignumber,1,33,1typicalvalue,1,20,12compressing,1,36,3

Chipfotag.dat:1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890chipfailtag L D wolverine 1 0 0

PI 3 Home Node The following is an example PIConfig script that can be used to create 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


Failover

Telling the Interface About the Failover 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 its corresponding digital state number.

OpenVMS Failover

General RequirementsFailover requires either:

Two (2) PINet nodes

One (1) PINet node and one (1) PI 2 Home node.

Each must have Fisher-Rosemount CHIP installed and running.

Hardware Requirements Two VMS nodes that can be one of the following combinations:

o Two (2) VAXes

o Two (2) Alphas

o One (1) VAX and one (1) Alpha

Both VMS nodes must have a connection to the CHIP Data Highway with CHIP installed and running.

Software Requirements Both VMS nodes must have PINet installed (any version of PI/PINet,

preferably 2.0.9 or greater).

The PI/PINet versions do not have to be the same on these two PI/PINet failover nodes (e.g. one can be running 2.0.9, while the other is running PI/PINet 2.1.2).

Both VMS nodes must be running OpenVMS version 5.5-2 or later. The VMS versions do not have to be the same on the two failover nodes, as long as they are 5.5-2 or later.

Both VMS nodes must have DECnet running between them. (Each node must be able to set host to the other.)

92

Software Setup

Telling the Interface About the Failover OUTPUT TagWith version 2.7.4, you may specify an output point that the primary node will write to and the secondary node will read from.

Configure a PI output point to the Highway. This point is configured the same way as you would configure an output point to the Highway except the source tag field of the point will be ignored.

The point on the Highway needs to have a zero of 0 and a span of 100 or more. It is recommended that the point on the Highway be an AI (analog input) point and output to the PV. The point on the Highway will need to have the OFF SCAN parameter set to YES or the DDP 132 (REM OFS) set to 1.

For example, to create a failover output point to aipoint.pv on the Highway:

Instrument Tag :aipoint

Location : 1 = 0 2 = 41 3 = 1 4 = 1 5 = 1

Note: The /hiway flag to enable highway outputs is not required for the failover output point. 2) Set the flag on the primary and secondary startup command files to specify the PI output point.

To configure the interface startup file for the failover output tag, specify /fop=failover_output_tag on the command line. In the example below, this would be /fop=chipfailoutputtag

3) The primary node will be doing the outputs; the secondary node will be reading the point to verify that it is changing. The values being sent to the output point will increment from 1 to 100 and repeat.

4) On startup, if the primary cannot output to the point or the secondary node cannot read the point, error messages will be written.

5) If there is a problem detected and the secondary node decides that it should start scanning, it will not start scanning if the point on the highway is still being updated. If the value has not changed, the secondary node will start scanning.

6) Scanning will be switched to the primary node when it starts writing to the output point, and the secondary node sees the values being updated.

Example CHIPtoPI.COM file on Primary Node$!Location of the CHIPtoPI executable file$ pichip :== $pisysexe:chiptopi.exe$!$! Startup Parameters$ pichip /ps=J /ec=20 /f=00:00:10 /id=1 /stopstat /db=1- /fo /primary=casaba /secn=dragon /ft=chipfailtag

/fds=casaba-/fo9=2000 /fop=chipfailoutputtag$ exit


Failover

Example CHIPtoPI.COM file on Secondary Node$!Location of the CHIPtoPI executable file$ pichip :== $pisysexe:chiptopi.exe$!$! Startup Parameters$ pichip /ps=J /ec=20 /f=00:00:10 /id=1 /stopstat /db=1- /fo /secn=casaba /ft=chipfailtag /fds=dragon /fo9=2000- /fop=chipfailoutputtag$ exit

Windows NT/Windows 2000 Failover

General RequirementsFailover requires two PI-API nodes that have Data Highway access and form a Microsoft Cluster.

Hardware Requirements Two Windows NT/2000 nodes with hardware that appears on the Microsoft

Hardware Compatibility list (http://www.microsoft.com/hwtest/hcl/)

Both nodes must provide a connection to the CHIP Data Highway and have CHIP installed and running.

Software Requirements Both NT/2000 nodes must have the PI-API (version 1.2.3.1 or greater)

installed.

Both NT nodes must be running Microsoft Windows NT 4.0 Enterprise Edition or Windows 2000 Advanced Server.

Both NT/2000 nodes must have TCP/IP running between them.

Installation Checklist

1. API Buffering (Bufserv)If API Buffering is to be used with MSCS-PI Failover, Bufserv must be installed on both the primary and the secondary interface nodes before failover is setup. Buffering must be started before the interface starts, so the interface service must have a dependency on the Bufserv service. The Bufserv service must be run from the local Administrator account and must be setup to startup automatically on reboot. For more information about setting up API Buffering, please see the Bufserv documentation (Bufserv.doc).

If Bufserv is installed, but the service is missing, create the service with this command line:Bufserv.exe –install –auto

94

2. CHIPtoPI# ServiceThe CHIPtoPI service should be set to automatic, with a dependency on ChipService and a dependency on Bufserv, if API buffering is to be used. With API buffering:chiptopi –install –auto –depend “chipservice bufserv”

Without API buffering:chiptopi –install –auto –depend chipserviceThe 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 Applet.

3. APIOnline# The APIOnline service is configured to be dependent upon the interface process in its service properties and using a /proc=interface parameter in the apionline#.bat file, where interface stands for the name of the interface service which is using failover. The # in APIOnline#.bat is gotten from the CHIPtoPI startup file /fo=# setting. If the interface stops, APIOnline stops. Microsoft Cluster Server then attempts to start up 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 up on the former backup node, the backup interface will check and see that it is now a data collector. It will then start sending data to PI (the backup node is always scanning along with the Scanning node, but the backup node does not send data to PI). Following is an example apionline#.bat file using the /proc flag:

Apionline#.exe /proc=chiptopi

APIOnline must be installed as a service on both cluster nodes. The example below shows how to install APIOnline as a service and make it dependent upon the CHIPtoPI interface:APIOnline# -install -depend “CHIPtoPI”

This command must be run from the directory in which the APIOnline executable is installed. The next example shows how to remove the APIOnline service, if it is no longer needed:APIOnline# –remove

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

APIOnline must then be registered with the Cluster Administrator.

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


Failover

1. Run the Cluster Administrator:

96

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

Click on Next:

Do not specify any “Preferred owners.”


Failover

Click on Finish, and you will receive a confirmation dialog:

98

3. Add a new resource called APIOnline#. The APIOnline “Resource Type” should be set up as a Generic Service. The “Group” is the group just created in the previous steps:

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


Failover

The “Service name” is the APIOnline service, as specified above in the step titled “3. APIOnline#”. Specify no “Startup parameters”.

Specify no Registry Keys:

100

Click on Finish to create the resource. A confirmation dialog should appear:

Now the APIOnline# Resource should be listed under the CHIPtoPI# Failover Group:

4. Bring the new APIOnline resource online. To do this, highlight the new resource, right click, and then select Bring Online.


Failover

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

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

102

Advanced tab and modify the “Threshold” to be 1:

At this point, the node listed as “Owner” should be the node on which the APIOnline# service has been started automatically by the Cluster.

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 ConfigurationData Collecting PI-API Node – Processes Running

CHIPtoPI

APIOnline

Backup PI-API Node – Processes Running:

CHIPtoPI


Failover

Scenarios Covered1. Backup PI-API node goes down

No immediate impact but there is no backup PI-API node available

2. Scanning PI-API node goes down

Microsoft Cluster Server starts APIOnline on backup PI-API node

Backup interface now starts scanning on backup PI-API node

3. Data collecting interface either crashes or is stopped

APIOnline stops running on data collecting node

Microsoft Cluster Server starts APIOnline on backup PI-API node

Backup interface now starts scanning on backup PI-API node

Primary/Secondary Interface FailoverThe secondary interface assumes data collection when the primary node stops running or it directs the secondary interface to assume data collection by stopping its APIOnline service. The most common scenario for the primary interface to stop its APIOnline service is when it is unable to communicate to its DCS gateway. When the primary APIOnline service is stopped, Microsoft Cluster Server automatically 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 is then able to communicate with its DCS gateway, the primary node stops the APIOnline service on the secondary node. Microsoft Cluster Server then starts APIOnline on the primary node and the primary node assumes data collection.

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-API node.

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

CHIPtoPI Interface Software Setup for Failover

Example CHIPtoPI.BAT file on Primary Node:chiptopi /db /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 Node:chiptopi /db /ps=F /id=1 /host=strider /f=00:00:10 /ec=1

/fo=1 /secn=wolverine /ft=chipfailtag /fds=dragon /stopstat

104

Picking up CHIP Point Database ChangesThe 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, you must stop and restart the interface when the DBI numbers change in the CHIP database.


Appendix A: Error and Informational MessagesBelow is a list of potential errors from the CHIPtoPI interface.

Failover> FATAL ERROR -2147221164 - Cluster class not registeredThis message is only available if CHIPtoPI is being run with 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

communication failure for tag>xThe 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 NT 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 their Fisher-Rosemount CHIP support folks if these errors persist.

Fail to initialize Chip, err: 9469, 36/253or

CHIP internal operational status error: 44, Shared memory erroror

chip_util is unable to execute due to one of the above errorsor

Error Access Denied PID xx could not access the PID yy found in CH_Security.log

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 an NT service and the user's program is executing as an NT 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 (Start | Control Panel | Services) via the Services applet. Click on Startup…, then modify the section titled “Log On As” so that the “System account” option is selected.

DevDBIf extreme debug messaging is required, the /devdb=x command line option can be used, where x is as follows (2.7.0.0):

/devdb=level(2.5.7.0)

The /devdb flag 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 switch. To turn on every debug switch specify:

/devdbor /devdb=-1

To turn off all debug messaging, either remove /devdb from the command line, or specify:/devdb=0

Note 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


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


Appendix B: PI 2 PINet to PI 3 String Tag SupportSince the extended PI-API is not supported on VMS, string tags are supported on PINet via an FTP mechanism. That is, the interface writes data to a file. The file is transferred to the PI 3 Server node by an automated FTP script that runs as a detached process. On the PI 3 Server node, the file is processed by the batch file interface. The details of this process and the configuration that is necessary to set this up are discussed below.

Method of OperationThe name that the interface uses for the data file is of the form “NameID.new”. 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 flag on the startup command line. NameID is the same character string that identifies messages in the pipc.log file as belonging to a particular interface, except that UniInt removes any spaces and periods that may have appeared in the character string.

The file NameID.new is written to the currently active FTP buffer directory, which is determined by the definition of the system logical piftpdir. One can determine the currently active directory with the command$ sho logical PIFTPDIR

"PIFTPDIR" = "PIFTPBUF1" (LNM$SYSTEM_TABLE) 1 "PIFTPBUF1" = "PI$DISK:[FTP.BUF1]" (LNM$SYSTEM_TABLE)

The current active FTP directory can be either PI$DISK:[FTP.BUF1] or PI$DISK:[FTP.BUF2]. If piftpdir is not defined, then the current FTP directory will be set to PI$DISK:[FTP.BUF1] when the PI-FTP process starts.

Every minute the PI-FTP process checks to see if there are any files ending in .new in piftpdir. If there are, it renames the files so that the files end in .old and then copies all of the .old files to Strtags.srt. The files with the .old extension are then deleted. Renaming the files to the .old extension ensures that the data in Strtags.srt are in time order. Strtags.srt is then FTP’ed to the PI Server node. On the PI Server node the file is given a name of the form PIFTPYYYYMMDDHHMM.DAT, where YYYY is the year, MM is the month, DD is the day, HH is the hour, and MM is the minute. After the files are processed by the Batch File interface, the files are renamed to PIFTPYYYYMMDDHHMM.999. The .999 files are deleted by the Batch File interface after a user-configurable amount of time has expired.

After the data files are copied to Strtags.srt, the FTP script changes piftpdir from PI$DISK:[FTP.BUF1] to PI$DISK:[FTP.BUF2] or vice versa. If the FTP transfer is successful, the PI-FTP process will delete the Strtag.srt file. If the FTP transfer is unsuccessful, the Strtag.srt file will not be deleted. The PI-FTP process will continue trying to send the Strtag.srt file until it is successful. Meanwhile, the interface can continue to write NameID.new files to the current FTP directory.


After every successful or unsuccessful FTP transaction, the PI-FTP process sleeps 1 minute before it attempts to send new or old data again. It is recommended that the wait time be at least 10 times the elapsed time for an FTP transaction.

The data in NameID.new is ASCII text of the formpoint_identifier, pitime, value, statusThe field separator can be changed from a comma to any character with the /fs command-line argument. The point_identifier on the PINet node corresponds to the point number on the PI 3 Server node. The point_identifier is obtained by the interface with the pipt_pointid PI-API call. The pitime is PI 2 time for OpenVMS. In other words, pitime is the number of seconds since January 1, 1970 in the local time zone. The value is the string that is to be written to the PI point, and status is the current status of the point (0 is a good status).

Setup Instructructions1. Obtain the files for the automatic FTP mechanism from OSIsoft. These files are

piftp.compiftpdetach.compiftpstop.comCopy these files to the PINet directory.

2. Create the following directories.create /directory pi$disk:[ftp]create /directory pi$disk:[ftp.buf1]create /directory pi$disk:[ftp.buf2]

3. Set the HomeNode, UserName, and PassWord for the automatic FTP mechanism by editing the file piftp.com. This is described in more detail later on in this procedure.

4. Add the following line to PINet:SITESTART.COM.$@pisysexe:piftpdetach

5. Add the following line to PINet:[email protected]

6. Modify the startup command line of the interface if necessary. The /file flag is the only command-line argument that is associated with the automatic FTP file transfer mechanism.

7. Set up an FTP daemon on the PI 3 server node. FTP daemons normally come as a part of a UNIX system. If the PI 3 server is on an NT node, then an FTP daemon will probably need to be installed. FTP daemons on NT do not use NT security. A user name and password will need to be configured for the FTP daemon and a default login directory will need to be setup. These user names and passwords are in no way related to NT user names and passwords. They are configured via the FTP software, not the NT administrator.

8. Set up the Batch File interface on the PI 3 server node. The Batch File interface (BatchFL) is not shipped with the CHIPtoPI interface, so users wanting to scan string tags on a PINet node and send them to a PI 3 home node will need to contact OSIsoft Tech Support for information on downloading the Batch File interface. This interface can either be run on the PI 3 home node, or it can be run


on a PI-API node.

When you setup the FTP transfer, choose a directory to receive these files from the PINet node’s FTP. This directory will be where the Batch File interface is configured to read the files and is specified on the Batch File interface command line with the /pa command line option. Data files transferred from the PINet node to the PI 3 home node are named .dat. This is the mask you will need to use in setting up the Batch File interface. An example of a /pa definition is:/pa=d:\pipc\interfaces\batchfl\datafiles\*.dat.

Also, please note that the /fs command-line argument for the Batch File interface and the Uniint-based interface should be set to the same field separator.

For more details on setting up the Batch File interface, please see the Batch File documentation, which is available on our Interfaces web site:http://interfaces.osisoft.comand is distributed with the Batch File interface.

9. Configure PI points of point type string on the PI 3 server node. "FTPSTRINGTAG" must appear in the extended descriptor (ExDesc) of each PI point of type string. This is because the interface will be running on a PI 2 PINet node, and the PI-API on PI 2 cannot distinguish between PI points of type integer and PI points of type string. Unless "FTPSTRINGTAG" is found in the extended descriptor of a PI point of type string, the PI point will be assumed to be of type integer by the interface.

The Automatic FTP Script

Configuring the ScriptThe HomeNode, UserName, and PassWord variables must be set by editing the PINet:piftp.com file. The HomeNode is the domain name or IP address of the PI 3 server node. If the PI 3 server is on a UNIX machine, then the UserName/PassWord correspond to an actual username/password on the UNIX box. If the PI 3 server is an NT machine, then the UserName/PassWord correspond to a username/password that is configured from within the FTP software on the NT box. These user names and passwords are in no way related to NT user names and passwords.

The piftp.com script is given below.

$! PIFTP TO BATCHFL DRIVER FOR VMS$! OSI SOFTWARE, INC$!$! REVISION HISTORY$! 18-NOV-97 BSO V1.0 CREATED$! 24-Dec-98 HAO Modified for CHIPtoPI Interface$! 30-Jul-99 GWM Added TCPWare and Multinet support$! 06-Sep-99 GWM Merged with changed made by SDS$!$!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!$!MODIFY THE FOLLOWING PARAMETERS$!


http://interfaces.osisoft.com/

Appendix B: PI 2 PINET to PI 3 String Tag Support

$!$HomeNode := piserver$UserName := username$PassWord := password$!$!$!DO NOT MODIFY ANYTHING BELOW THIS LINE$!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!$SET NOON$SET NOVERIFY$!$! LOG STARTUP EVENT$PIMSG:==$pinet:writemesslog$PIMSG "PI FTP SCRIPT STARTING"$!$if (f$trnlnm("PI$DISK") .nes. "") THEN GOTO CHECKTCPWARE $PIMSG "PI$DISK LOGICAL NOT DEFINED...PERHAPS PINET IS NOT RUNNING...ABORT"$EXIT$!$!$CHECKTCPWARE:$ if (f$trnlnm("tcpware") .nes. "") $ then $ @TCPWARE:TCPWARE_COMMANDS.COM$ PIMSG "RUNNING TCPWARE:TCPWARE_COMMANDS.COM"$ endif$!$! CHANGE PIFTPCMD <> RUN FOR CLEAN EXIT$DEFINE/System/Nolog PIFTPCMD RUN$!$! BUF1 & BUF2 MUST BE ON PI$DISK TO SUPPORT FILE RENAME$DEFINE/System/Nolog PIFTPBUF1 PI$DISK:[FTP.BUF1]$DEFINE/System/Nolog PIFTPBUF2 PI$DISK:[FTP.BUF2]$!$IF (F$TRNLNM("PIFTPDIR") .NES. "") THEN GOTO SKIPINIT$DEFINE/System/Nolog PIFTPDIR PIFTPBUF1$!$SKIPINIT:$FTPPREV = %X00000001 ! init FTP previous status$!$!$START:$!$!Find Active/InActive Directory$BUFNEW=F$TRNLNM("PIFTPDIR")$IF ( BUFNEW .EQS. "PIFTPBUF1" ) THEN BUFOLD="PIFTPBUF2"$IF ( BUFNEW .EQS. "PIFTPBUF2" ) THEN BUFOLD="PIFTPBUF1"

$!$!

112

$!Check for data in old buffer$IF (F$SEARCH("''BUFOLD':*.SRT").EQS. "") THEN GOTO CHECKNEW$RESET = F$SEARCH("''BUFOLD':*.SRT;*") ! reset search context$! Change directory focus$ SET Default 'BUFOLD$ GOTO MAKEFTP$!$CHECKNEW:$!Check for data in new buffer$IF (F$SEARCH("''BUFNEW':*.NEW").EQS. "") THEN GOTO SLEEP$!Change directory focus$ SET Default 'BUFNEW$! Switch Buffers$ DEFINE/System/Nolog PIFTPDIR 'BUFOLD$ WAIT 00:00:01 ! in case file being created$!$! concatenate new files into a single sorted file$!$REORDER:$ IF (F$SEARCH("*.NEW;*") .NES. "")$ THEN RENAME *.NEW *.OLD ! order versions to sort by date$ GOTO REORDER$ ENDIF$ COPY/Nolog *.OLD;* STRTAGS.SRT$ DELETE/Nolog/Noconfirm *.OLD;*$!$MAKEFTP:$!$!Rename after FTP to prevent file open collisions$!$!012345678901234567890123$!yyyy-mm-dd hh:mm:ss.cc$tstr= f$cvtime(f$time())$!$!$yyyy = f$extract(0,4,tstr)$mm = f$extract(5,2,tstr)$dd = f$extract(8,2,tstr)$hh = f$extract(11,2,tstr)$mi = f$extract(14,2,tstr)$!$fname= "PIFTP"+yyyy+mm+dd+hh+mi+".DAT"$GOTO CREATESCRIPT$!$!$TRYFTP:[email protected]



$FTPSTAT = $STATUS$IF (FTPSTAT) $THEN $ DELETE/Nolog/Noconf *.SRT.*$ PURGE/Nolog/Noconf PIFTPSCRIPT.COM$ PURGE/keep=3/Nolog/Noconf PISYSEXE:PIFTP.TRANSCRIPT$ IF (FTPSTAT .NE. FTPPREV) THEN PIMSG "PIFTP SUCCESS, STATUS = ''FTPSTAT'"$ELSE$ PURGE/Nolog/Noconf PIFTPSCRIPT.COM$ PURGE/keep=3/Nolog/Noconf PISYSEXE:PIFTP.TRANSCRIPT$ IF (FTPSTAT .NE. FTPPREV) THEN PIMSG "PIFTP FAILURE, STATUS = ''FTPSTAT'"

$ENDIF$FTPPREV = FTPSTAT$!$!$SLEEP: $WAIT 00:01:00$IF (F$TRNLNM("PIFTPCMD") .EQS. "RUN") THEN GOTO START$PIMSG "PI FTP SCRIPT EXITING - PIFTPCMD <> RUN"$!$EXIT$!$! CREATE PIFTPSCRIPT FILE$CREATESCRIPT:$OPEN/WRITE/ERROR=OPEN_ERROR FTPC piftpscript.com$!$! DETERMINE THE FTP IMPLEMENTATION$ FTPTYPE = ""$!$ if (f$trnlnm("ucx$service") .nes. "") .or. - (f$trnlnm("tcpip$service") .nes. "") $ then $ WRITE FTPC "$ DEFINE SYS$OUTPUT PISYSEXE:PIFTP.TRANSCRIPT"$ WRITE FTPC "$ FTPCMD = ""$SYS$SYSTEM:UCX$FTP"""$ WRITE FTPC "$ FTPCMD" $ WRITE FTPC "open ''HomeNode'" $ WRITE FTPC "user ''UserName'" $ WRITE FTPC "''PassWord'" $ WRITE FTPC "asc" $ WRITE FTPC "put STRTAGS.SRT ''fname'" $ WRITE FTPC "quit" $ WRITE FTPC "$ EXIT $status"$ CLOSE FTPC$!$ FTPTYPE = "UCX"$ endif$!

114

$! TGV MultiNet.$ if (f$trnlnm("multinet") .nes. "") $ then$ WRITE FTPC "$ DEFINE SYS$OUTPUT PISYSEXE:PIFTP.TRANSCRIPT"$ WRITE FTPC "$ FTPCMD = ""MULTINET FTP"""$ WRITE FTPC "$ FTPCMD 'HomeNode' /user='UserName' /pass='PassWord'" $ WRITE FTPC "exit-on-error on" $ WRITE FTPC "TYPE ASCII" $ WRITE FTPC "put STRTAGS.SRT ''fname'" $ WRITE FTPC "quit" $ WRITE FTPC "$ EXIT $status"$ CLOSE FTPC$!$ FTPTYPE = "MULITNET"$ endif $!$! Process Software TCPWare$ if (f$trnlnm("tcpware") .nes. "") $ then $ WRITE FTPC "$ DEFINE SYS$OUTPUT PISYSEXE:PIFTP.TRANSCRIPT"$ WRITE FTPC "$SET NOON" $ WRITE FTPC "$FTP" $ WRITE FTPC "open ''HomeNode' ''Username' ''Password'"

$ WRITE FTPC "ERROR_EXIT %X10000010"$ WRITE FTPC "TYPE ASCII" $ WRITE FTPC "ERROR_EXIT %X10000020"$ WRITE FTPC "put STRTAGS.SRT ''fname'"

$ WRITE FTPC "ERROR_EXIT %X10000030"$ WRITE FTPC "exit" $ WRITE FTPC "$ EXIT $status"$ CLOSE FTPC$! $ FTPTYPE = "TCPWARE"$ endif$!$ IF (FTPTYPE .nes. "") THEN GOTO TRYFTP$ PIMSG "ERROR, PI FTP SCRIPT COULD NOT RESOLVE THE TCP/IP IMPLEMENATION TYPE"$ GOTO SLEEP$!$!$OPEN_ERROR:$PIMSG "ERROR OPENING PI$DISK:PIFTPSCRIPT.COM FILE"$GOTO SLEEP$!

$



The piftpdetach.com script is given below.

$! PIFTPDETACH.COM$! This file is used to start the PI FTP SERVER as a detached process.$! This file can be used in PiSysMgr:SiteStart.com$!=======================================================$!$ If (F$Search("PISysExe:piftp.out").nes."") then -

Purge/Keep=3 PISysExe:piftp.out$!$ run/detach/uic=[system]/process="PI-FTP"/priority=4 -

/input=pisysexe:piftp.com/output=pisysexe:piftp.out -

/working_set=512/maximum_work=1024/extent=5000 -

/pagefile=100000/buffer=32768 sys$system:loginout$ exit

Starting and Stopping the FTP ScriptThe automatic FTP script is called PINet:piftp.com. The FTP script is started by@pinet:piftpdetach.comOnce the detached process is started, the process "PI-FTP" should appear when the command "Sho Sys" is issued from a DCL prompt. The PI-FTP process can be launched before or after the interface.

The script is stopped by@pinet:piftpstop.comThe command procedure piftpstop.com does not directly stop the PI-FTP process. Instead, the command procedure changes the definition of the system process logical name piftpcmd from "run" to "exit". The PI-FTP process checks the definition piftpcmd once every minute to determine whether it should keep running or exit. Hence, the PI-FTP process could take up to 1 minute to exit.

Information and Error Messages from the FTP ScriptThe PI-FTP process writes messages to the PINet:piftp.out file and the PINet:PIMessLog.txt file. The messages that are written to the piftp.out file are usually not very useful.

116

The following are examples of messages that may appear in the PIMessLog.txt file.

6-SEP-1999 10:09:39.76PI FTP STARTING

6-SEP-1999 14:01:26.28PIFTP FAILURE, STATUS = %X1000028C

6-SEP-1999 14:21:22.30PIFTP SUCCESS, STATUS = %X00000001

6-SEP-1999 15:10:44.16PI FTP EXITING - PIFTPCMD <> RUN

The above messages indicate that the PI FTP process started at 10:09:39.76 and that it ran fine until 14:01:26.28. The process recovered at 14:21:22.30 and exited at 15:10:44. To determine the nature of the problem that occurred, one can look at the PINet:piftp.transcript file. The last 3 transcripts that occurred are kept.

The following is an example of an FTP transcript indicating successful FTP transfer.

vlc620.osisoft.com MultiNet FTP user process V4.0(118)Connection opened (Assuming 8-bit connections)< Jgaa's Fan Club FTP Service WAR-FTPD 1.65 Ready<Please enter your user name.[Attempting to log in as piftpserver]<User logged in, proceed.FTP>[Will exit when an error occurs]FTP>Type: Ascii (Non-Print), Structure: File, Mode: StreamFTP><Ready to receive "/PIFTP199909061458.CSV". Mode STREAM Type ASCII NO-PRINT.<Transfer finished successfully. Closing data connection.FTP><Goodbye. Control connection closed.

The following transcript indicates that the FTP script was told to log into an unknown node called PISERVER.

vlc620.osisoft.com MultiNet FTP user process V4.0(118)? Unknown host "PISERVER"FTP>[Will exit when an error occurs]FTP>? Unknown host "TYPE"%DCL-W-SKPDAT, image data (records not beginning with "$") ignored



The message %DCL-W-SKPDAT, image data (records not beginning with "$")

ignored"is meaningless. It appears at the end of every unsuccessful FTP transcript. The following transcript indicates that the FTP daemon is not running on the PI Server node. The connection was refused because there was no FTP daemon to accept a connection.

vlc620.osisoft.com MultiNet FTP user process V4.0(118)208.243.230.116: %MULTINET-F-ECONNREFUSED, Connection refusedFTP>[Will exit when an error occurs]FTP>? Unknown host "TYPE"%DCL-W-SKPDAT, image data (records not beginning with "$") ignored

Setting up PI Batch File Interface on the PI 3 Home Node The Batch File interface (BatchFL) is not shipped with the CHIPtoPI interface, so users wanting to scan string tags on a PINet and send them to a PI 3 home node will need to contact OSIsoft Tech Support for information on downloading the Batch File interface. This interface can either be run on the PI 3 home node, or it can be run on a PI-API node.

You will need to setup an FTP daemon (server) on the PI 3 home node to receive the data files from the PINet node. OSIsoft does not have a suggestion regarding which FTP server to use.

When you setup the FTP transfer, you will need to choose a directory to receive these files from the PINet node’s FTP. This directory will be where the Batch File interface is configured to read the files and is specified on the Batch File interface command line with the /pa command line option. Data files transferred from the PINet node to the PI 3 home node are named .csv. This is the mask you will need to use in setting up the Batch File interface. An example of a /pa definition is:/pa=d:\pipc\interfaces\batchfl\datafiles\*.csv

For details on setting up the Batch File interface, please see the Batch File documentation, which is available on our Interfaces web site:http://interfaces.osisoft.comand is distributed with the Batch File interface.

118

http://interfaces.osisoft.com/

Appendix C: Linking/Re-linking CHIPtoPI on VMS The interface program is linked during any PI System install or upgrade. You may have to relink the CHIP interface after installing a new release of the CHIP software. You may also have to relink if the CHIP logical names were not defined during the install or upgrade. To relink the CHIP interface, execute CHIPtoPILink.com with PIBuild as your default directory. If you have a version of CHIP older than version 3.0, a version of the interface which does not support all the features in this manual is linked. The PI install/upgrade procedure checks for CHIP:Link1.com to see if the CHIP version is 3.0 or later.


Appendix D: Installation of CHIPtoPI on VMS from a Separate Tape

The Fisher CHIPtoPI interface is now being shipped on CD-ROM. The enclosed CD-ROM contains the backup save set CHIPTOPI.BCK, which contains the PI-Fisher CHIP interface and its support files.

1. FTP the CHIPTOPI.BCK save set file and the REBLOCK files from your PC to your VMS machine.

2. Run REBLOCK on the save set or, on VMS nodes running VMS 6.0 or greater, use the VMS SET FILE command to reformat the file internally to the correct VMS save set standard block size of 32256. For more information on REBLOCK and the VMS SET FILE command, see “Appendix G: File Conversion Utilities for VMS Save Sets”.

3. Unpack the save set to a “safe” directory by:backup/verify/log chiptopi.bck/sav *.*

4. Copy the files contained in CHIPTOPI.BCK to PIBuild: and go to that directory.

5. Install the interface files with the command:@ CHIPTOPILink.comThe command file copies the files to the appropriate directories and links the interface executable. Files similar to the following are typically installed.

PIBuild directoryCHIPTOPI.OBJ Object file for the interface.UNIINT.OBJ Object file for the interface

CHIPTOPILINK.COM Command procedure for re-linking the executable.

PISysExe directoryCHIPTOPI.EXE Interface executable.

CHIPTOPI.COM Startup command file for interactive processes.

CHIPTOPIDETACH.COMStartup command file for detached processes (the command-line arguments are still defined in the CHIPTOPI.COM file).


Appendix E: Migrating from the PI-CHIP Interface to the CHIPtoPI Interface

The CHIPPTCONVERT UtilityOSIsoft provides the CHIPPTCONVERT utility to convert old VMS based PI-CHIP tags to run under the CHIPtoPI interface. All tags need to have a scan class specified in Location4 (see discussion below on CHIPtoPI scan classes), and two Fisher CHIP point types require further conversion (see discussion below on CHIP point types 31 and 100). CHIPPTCONVERT handles all these conversions. On the occasion that a CHIP tag cannot be converted programmatically, a message will be printed to the PISYSMGR:CHIPPTCONVERT.OUT file.

The CHIPPTCONVERT.BCK file that is provided with the CHIPtoPI interface is unpacked to the PISYSMGR directory with the CHIPPTCOVERT_INSTALL.COM file that is provided on the same tape. The following instructions on using the utility are also included in the save set in the CHIPPTCONVERTREADME.TXT file:

*********************************************************************This is the PI CHIP point conversion readme file.The conversion utility changes points in the PI point database from the point format used by the old VMS CHIP interface to the point format used by the new UniInt-based CHIP interface.

Caution - DO NOT EXECUTE THE POINT CONVERSION UTILITY TWICE!

*********************************************************************

*********************************************************************File list*********************************************************************

The CHIPPTCONVERT_INSTALL script should have created the following files in the PISYSMGR directory:

CHIPPTCONVERT.COMCHIPPTCONVERT.STRCHIPPTCONVERT.DATCHIPPTCONVERT.OBJCHIPPTCONVERT.EXECHIPPTCONVERTREADME.TXTCHIPPTCONVERTCLEANUP.COM


*********************************************************************Instructions for using the conversion utility*********************************************************************

1. Edit the PISYSMGR:CHIPPTCONVERT.DAT file and change the "-" character to the appropriate point source character for the CHIP interface. If you want to convert CHIP tags for one copy of the CHIP interface at a time, you can also change the Location5 = * to be Location5 = #, where # is 0 to 7, matching up with the interface number specified in the CHIP.COM interface startup file.

2. Start the point conversion utility with the command: @PISYSMGR:CHIPPTCONVERT.COMThe conversion utility reads in all CHIP tags and moves Location4 to the Extended Descriptor to fit the format needed by CHIPtoPI.

Ignore the warning message: %NONAME-W-NOMSG, Message number 000000003. After verifying that the points have been converted correctly, execute CHIPPTCONVERTCLEANUP.COM script to delete the files from the PISYSMGR directory to avoid accidental re-execution of the conversion utility. You can still re-install the conversion utility at a later date if you want to run the utility.

*********************************************************************What the conversion utility does*********************************************************************

The conversion utility reads in all CHIP tags, searching for tags with Location4 defined for DDP tags or with Location4 defining a bit. It then constructs the Extended Descriptor for those tags to contain DDP= or BIT= followed by the DDP number or bit number that was stored in Location4. It will then assign Location4=1, indicating the UniInt scan class for all CHIP tags.

If the Extended Descriptor is not blank, and the Instrument Tag is blank, the Extended Descriptor will be moved to the Instrument Tag field before the Extended Descriptor is overwritten. If both the Extended Descriptor and the Instrument Tag field are not empty, the tag will be rejected and not added to the new PIDIFF file. These tags will then need to be manually modified. A list of the tags that are not converted is written to the out file for the utility: PISYSMGR:CHIPPTCONVERT.OUT.

All converted tags are put into scan class 1, as defined in the startup command line for the new interface: /f=00:01:00 /f=00:00:10 /f=00:00:30It is up to the user to modify Location4 to move tags into different scan classes.

*********************************************************************Files created by the PISYSMGR:CHIPPTCONVERT.COM script*********************************************************************


PISYSMGR:CHIPPTCONVERTOLD.DATThis pidiff .dat file can be used with the structure file PISYSMGR:CHIPPTCONVERT.STR to convert the point database back to the old VMS CHIP interface point format.

PISYSMGR:CHIPPTCONVERTNEW.DATThis pidiff .dat file is used with the structure file PISYSMGR:CHIPPTCONVERT.STR to convert the point database from the old VMS CHIP point format to the point format for the new UniInt-based CHIPtoPI interface. The user does not need to explicitly run pidiff to perform the conversion because pidiff is executed by the @PISYSMGR:CHIPPTCONVERT.COM script.

PISYSMGR:CHIPPTCONVERT.OUTThis contains a list of the points that were not edited in the PI point database.

CHIPtoPI Scan ClassesThe CHIPtoPI Interface supports multiple scan classes, which are assigned to each point in the Location4 parameter. The scan classes are defined in the CHIPtoPI startup file (CHIPtoPI.COM on VMS, chiptopi.bat on NT, chiptopi.sh on HP-UX) in the following manner:/f=00:00:10,21:00:05 ! First scan class period and phase/f=00:00:12,00:00:00 ! Second scan class period and phaseThe first /f= parameter listed in the startup file is scan class 1, the second is scan class2, etc. In this example, to have a tag scan every 12 seconds, you need to define that tag’s Location4 to be 2.

CHIP Point type 31 and 100LCP Status Words

The PI-CHIP Interface currently uses Location4 for LCP Status Word reads to specify a single bit from the status word. To convert these tags for the CHIPtoPI interface, the status word bit needs to be moved from Location4 to the Extended Descriptor with the following syntax:

BIT=x, where x is the LCP status word bit to be extracted

DDP Highway Outputs

The PI-CHIP Interface currently uses Location4 for point type 100 DDP Highway Outputs. To convert these tags for the CHIPtoPI interface, the DDP occurrence number needs to be moved from Location4 to the Extended Descriptor with the following syntax:

DDP=x, where x is the occurrence number


Appendix F: Interface Distributions as Self-Extracting Executables

PI Interfaces are now being shipped on CD-ROM or are available for download via the OSIsoft FTP server. Either method provides a Windows NT/9x self-extracting executable zip file that contains zipped files for the platform on which your interface is intended to run.

1. Copy or move the distribution .exe file from CD-ROM or the OSIsoft FTP server to your PC (running Windows NT or Windows 9x).

2. Unpack the .exe file by clicking on it from Windows Explorer or by running the executable from the command prompt. You will be prompted for where to unzip the files. Be sure to unzip to a safe directory, so as not to over-write any existing configuration files.

NT Installation3. Move the distribution files to the correct directory, and follow the installation instructions in the section “Interface Installation on NT”.

UNIX Installation3. FTP the distribution files from your PC to your UNIX node, and follow the installation instructions in the section “Interface Installation on UNIX”.

VMS Installation3. FTP the interface .BCK save set file and the REBLOCK files from your PC to your VMS machine.

4. Run Reblock on the save set or, on VMS nodes running VMS 6.0 or greater, use the VMS SET FILE command to reformat the file internally to the correct VMS save set standard block size of 32256. For more information on Reblock and the VMS SET FILE command, see the section below “Appendix G: File Conversion Utilities for VMS Save Sets”.

5. Unpack the save set to a “safe” directory by:backup/verify/log savesetname.bck/sav *.*

6. Follow the installation instructions in the section “Interface Installation on VMS”.

Documentation UpdatesInterface manuals should now be, or will soon be, included in the interface distribution. For interface manual updates, you can view or download the latest documentation from our Support Web:


http://support.osisoft.com

After registering the first time, go to the PI Interfaces link and then view the spreadsheet from the Documentation link.


http://support.osisoft.com/

Appendix G: File Conversion Utilities for VMS Save Sets

There are two options for internally reformatting the interface VMS save set .bck files to the correct VMS save set standard block size of 32256. The internal block size gets restructured when FTP’ing files from non-VMS computers.

ReblockThis utility allows you to convert VMS save sets back to their original internal format after downloading them in binary mode from the FTP server to your VAX or Alpha.

In binary file transfer mode, FTP imposes a maximum record size of 512 bytes. Since the standard record length of a VMS save set is 32256 bytes, FTP breaks the records apart during the download. When you download the file, the record size is still 512 bytes.

REBLOCK reorganizes the file so that the standard VMS save set record format is restored. You can download executable versions of REBLOCK for both VAX/VMS and Alpha/VMS. A VMS executable has a record size of 512 bytes, so it is ready to use as soon as it is downloaded.

This utility is also available in the 'pub/reblock' directory of the FTP server at OSIsoft. It is offered without warranty.

Installing REBLOCKRun FTP and switch to binary mode using the command bin.

Move the correct executable to your VMS node via FTP: VAX/VMS : get reblock.exe reblock.exeAlpha/VMS: get reblock_alphavms.exe reblock.exeREBLOCK is ready to use.

Using REBLOCK1. Type RUN REBLOCK at the "$" prompt. You are prompted for a filename.Enter the name of the save set downloaded from the FTP server and hit return.

2. When REBLOCK has processed the file, the filename prompt reappears again.REBLOCK does NOT create a new file version; it reorganizes the existing file.

3. You may process other files, or type "\" to exit.

Sample Session on VMS node$ run reblockREBLOCK: Convert file to blocksize 32256Filename ("\" to exit): savesetname.bckFilename ("\" to exit): \


VMS Set File Command

VMS .BCK Save Set FileThere is a VMS command available with VMS 6.0 and later that will restore the correct block size of a save set after it has been downloaded by FTP:

$ Set File/attribute=(lrl:32256) savesetname.bck

SET FILE does the same thing as the REBLOCK program does, but from the operating system level.

VMS Save Set .A or .B FileIf you have downloaded a VMSInstal save set with a “.A” or a “.B” file extension that was not wrapped in a .bck file, and you have VMS 6.0 or later, you can recover the “.A” and “.B” VMSInstal save sets with the following command:

$ Set File/attribute=(lrl:9216) savesetname.A$ Set File/attribute=(lrl:9216) savesetname.BThis will re-order the VMSInstal save set to the non-standard block size required by VMSInstall.com


Appendix H: GNR2PI -- CHIPtoPI Point Creation Utility

The gnr2pi utility is not distributed with the interface and is only a helper utility that can be used to generate a PIConfig file. The gnr2pi utility runs on Windows NT-Intel. It generates either a PIConfig file or a PIDiff file that can be used to create CHIPtoPI tags. To request a copy of the gnr2pi utility, contact Tech Support.

Parameters for PIConfig OutputPI[C]onfig gnr_file piconfig_I/R_file piconfig_D_file pointsource interface_id# [D]BI/[T]agname

Parameters for PIDiff Output

PI[D]iff gnr_file pidiff_I/R_dat_file pidiff_I/R_str_file pidiff_D_dat_file pidiff_D_str_file pointsource interface_id# [D]BI/[T]agname

Help usage-h

Parameter List Option ExplanationsPI[D]iff/PI[C]onfig D creates a PIDiff file; C creates a PIConfig file

gnr_file CHIP .gnr file name, found in the CHIP directory

piconfig_I/F_file PIConfig file with Integer and Float tags that this utility generates

piconfig_D_file PIConfig file with Digital tags that this utility generates

pidiff_I/R_str_file PIDiff Structure file for I and R tags that this utility generates

pidiff_I/R_dat_file PIDiff Data file with I and R tags that this utility generates

pidiff_D_dat_file PIDiff Data file with D tags that this utility generates


pidiff_D_str_file PIDiff Structure file for D tags that this utility generates

pointsource PI Point Source character for these tags

interface_id# Number assigned to Interface (/id=) and Location5

[D]BI/[T]agname D means DBI will be placed in Location1; T means CHIP tag name will be used in Instrument Tag field

Optional [D]ebug D writes out extra debug flags. Ignored if not present

GNR2PI on Windows NTTo run the gnr2pi utility on a WindowsNT node, the user needs to modify the GNR2PI.BAT file to the correct Fisher-Rosemount gener file and to optionally modify the names of the data files that are to be created. The parameters are different for creating files for PIConfig or PIDiff.

Creating a PIConfig FileThe following is an example GNR2PI.BAT file command line to create a PIConfig file on a CHIP node that is to be transferred to a PI 3 home node and is then to be run to create CHIPtoPI points:gnr2pi C d:\chip\config.gnr chip_ir.dat chip_d.dat F 1 T

These tags are created from the config.gnr file found in the d:\chip directory. The chip_ir.dat file will contain the CHIPtoPI Integer and Real tags. The chip_d.dat file will contain the CHIPtoPI Digital tags. These tags will be created with PointSource F. The interface id number, found in Location5, will be 1, and they will use the CHIP tag name, instead of the CHIP DBI number, to reference the tags in the CHIP database.

Creating a PIDiff Filegnr2pi D d:\chip\config.gnr chip_ir.dat chip_ir.str chip_d.dat chip_d.str F 1 T


Revision HistoryDate Author Comments

May 95 JQD First Copy of Interface Manual Completed

Feb 97 JQD Updated for NT

24-Jul-97 HAO Updated for running CHIP and CHIPtoPI as services

10-Sep-97 HAO Updated for HP-UX

1-Dec-97 HAO Updated to 32 Unit Variables in CHIP type 10 (was 16)

5-Dec-97 HAO Updated to include new CHIP 5.0 8 & 16-bit statuses

10-Dec-97 HAO Updated to include Highway Output info

11-Dec-97 HAO Migrating points from old PI-CHIP to CHIPtoPI i/f

13-Apr-98 HAO Added Highway DDP and Activity Batch ID Inputs

15-Apr-98 HAO Added doc on /ver startup parameter

10-Jun-98 HAO Added column of recommended PI point types

15-Jun-98 HAO Added doc on CHIPPTCONVERT point conversion util for PI 2, old VMS CHIP points to new CHIPTOPI points.

10-Sep-98 HAO Added info on installing on VMS from diskette

02-Nov-98 HAO Added /sp=milliseconds to pause on startup (1.1.9.3)

01-Dec-98 HAO Added local CV type 31 outputs (1.1.9.4)

03-Dec98 HAO Added note about CHIP P4.3/P5.0 compatibility (1.2.0). Added Appendix D, modified Appendix E to match web.

14-Dec-98 HAO Fixed references to /ec (1.2.0)

24-Dec-98 HAO Added documentation on using PINET to PI 3 String Tag support; Auto FTP.

5-Jan-99 HAO Incremented version number to 2.0.4

27-Jan-99 HAO Added section on Batch File for PINet/PI3 string tags supt.

24-Feb-99 HAO Added Failover (2.0.6)

3-Mar-99 HAO Added changes noted by Merck (2.0.8)

11-Mar-99 HAO Added /udbi=x, Update DBIs every x hours. (2.0.9)Added FR Type 10, Activity Point DBI and Highway Address of Console Reads. (2.1.0)

14-Apr-99 HAO Added Appendix on Troubleshooting and on GNR2PI util. (2.1.0)

05-May-99 HAO CHIP Programming License is not needed on NT or UNIX. (2.1.0)

18-May-99 HAO Modified sections on Input versus Output point defs; added section on setting CHIP_SCOPE environmental variable.


(2.1.0)

21-Jul-99 HAO Added section on .dbg debug symbols file on NTI (2.1.3)

06-Oct-99 HAO Error 9 write I/O Timeout; error 8 write no error. (2.1.5)

15-Nov-99 HAO UserInt1 = 1 to convert CV5-CV8 to FP from % (2.1.8)

7-Dec-99 HAO Added note to ASCIIMSG and BATCHID pointing users to the section on CHIPtoPIFTP and BatchFile interface. (2.1.8, rev A)

28-Dec-99 HAO Modified PIFTP doc (was chiptopiftp) (2.1.8, rev B)

04-Jan-00 HAO Added NT Failover (2.5.0)

28-Jan-00 HAO Cleaned up Failover for VMS - Released (2.5.1)

06-Apr-00 HAO Added ability to read the first bit set to ON from the 8-bit statuses (2.5.4.0)

24-Apr-00 HAO Changed references to diskette to CD. (2.5.4.0, rev A)

01-May-00 HAO Added info on /db levels (2.5.7.0)

09-May-00 HAO Modified NT installation instructions to no longer refer to wait.exe and chipstart.bat (2.5.7.0, rev A)

02-Jun-00 HAO Modified GNR2PI doc to explain that this is not a released product. (2.5.7.0, rev B)

05-Jun-00 HAO Clarified the /stopstat explanation. (2.5.7.0, rev C)

03-Jul-00 HAO Clarified discussion of location5 and /id parameters (2.5.7.0, rev D)

25-Aug-00 HAB Modified Status Words (Type31) to allow users to specify up to bit 32 on PI3 systems. Added support for reading Type 31 User-defined integer (UDEF). (2.5.9.0)

14-Sep-00 HAB Added section on configuring IORates and Performance Points (2.5.9.0, rev A)

26-Sep-00 HAB Corrected reference from /fs to /file in PIFTP setup section. (2.5.9.0, rev B)

27-Sep-00 HAB Had removed reference to /fs in the Parameter & Description section of the manual (2.5.9.0, rev C)

29-Sep-00 HAB Added pictures of Failover config

10-Oct-00 HAB Added notes about Failover on NT/2000 not yet being supported. (2.7.0.0)

12-Oct-00 HAB Added note about “SuperCHIP” (2.7.0.0, doc rev A)

23-Oct-00 HAB Added section on PI-ICU user control (2.7.0.0, doc rev B)

01-Nov-00 HAB Added /devdb to troubleshooting section (2.7.0.0, doc rev C)

08-Nov-00 HAB Modified /db so that All On is 64, not 32 (2.7.0.0, doc rev D)

15-Nov-00 HAB Added section on CHIPDIA and chip_util (2.7.0.0, doc rev E)

134

30-Nov-00 HAB Negative ints scanned on ExtAPI platforms. Corrected to VMS file size references to 32256. (2.7.0.3)

15-Dec-00 HAB Added local Activity Point DBI (ATAG) output. (2.7.0.4)

02-Feb-01 HAB Converted to new format.

08-feb-01 JML Integrated with skeleton 1.04

06-Mar-01 HAB Updated version for distribution (2.7.1.0)

08-Mar-01 HAB Added CHIPtoPI ICU Control to Startup Command File section. Added ICU to Perf Points/IORates section.

24-Apr-01 HAB Added info on UNIX & SHLIB_PATH (2.7.1.0, doc rev A)

04-May-01 HAB Updated for 2.7.2.0 release.

17-May-01 JML Updated with skeleton version 1.08

08-Jun-01 HAB Updated with NT/2000 failover info – updated ICU (2.7.2.0 to 2.7.3.0, doc rev A)

3-Aug-01 MMG Updated with VMS failover using an output tag. Version 2.7.4.x

22-Aug-01 MMG Added more guidelines on creating the /fop point

05-Sep-01 HAB Updated ICUControl section (2.7.4.x, doc rev B)

25-Sep-01 MMG Added new VMS Failover switches. /fow /for /foc. Updated section on creating Highway point for VMS Failover.

28-Sep-01 HAB Added to NT failover section (2.7.5.0)

01-Oct-01 HAB Updated for new ICU Control (2.7.5.0, doc rev A)

01-Nov-01 MMG Updated with new uniint switch /usepinettime to disable getting the server time from a PI2 PINET node for time syncing.

15-Jan-02 HAB Point Status Mask (MVPSTMSK 1-16) for Type 21 and 31 (2.8.0.3)

06-Feb-02 HAB Set ‘Automatically Incorporates PI Point Attribute Changes’ to Yes instead of No (2.8.0.3, doc rev A)

30-Apr-02 HAB Added section to troubleshooting on FATAL ERROR –2147221164 (2.8.0.3, doc rev B)

11-Jun-02 HAB Corrected reference to PIFTP section. (2.8.0.3, doc rev C)

19-Aug-02 HAB Added chiponscan/chipoffscan section back (2.8.0.9)

31-Oct-02 LND 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-02 HAB Updated with issues located by LND (2.9.0.0, doc rev A)

11-Nov-02 LND Added principles of operation for request/response points; revised request/response point configuration.

19-Nov-02 HAB Added info on account for failover primary interface.


27-Jan-03 HAB Request/response features supported only on Windows (2.9.0.4)

28-Jan-03 HAB Updated the ICU Control section (2.9.0.4)

03-Feb-03 HAB Added /tcq flag (2.9.0.5)

08-Dec-03 HAB ASCIIMSG outputs are loc2=-21 (2.9.0.5, doc rev A)

15-Jan-04 HAB Clarified “Platforms” section to state: Windows (NT-Intel, Windows 2000, Windows XP) (2.9.0.5, doc rev B)

136

Documents

Fisher-Rosemount CHIP on Windows/VMS/HP-UXcdn.osisoft.com/interfaces/904/PI_CHIPtoPI_2.9.0.5-RevB.… · Web viewConnection Tool - Viewing the Local CHIP Database 23. CHIP_UTIL