Novatech D/3 Interface to the PI System Documentation

NovaTech D/3®
Interface to the PI System

Version 4.30.0.12
Rev E

1

NovaTech D/3 Interface to the PI System

How to Contact Us

OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA94577USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)

Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors

• Brazil
• Middle East/North Africa
• Republic of South Africa
• Russia/Central Asia

/

• South America/Caribbean
• Southeast Asia
• South Korea
• Taiwan

OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Unpublished – rights reserved under the copyright laws of the United States.
D/3 is a registered trademark of NovaTech Process Solutions, LLC.
© 2002-2006 OSIsoft, Inc . PI_GSETID3.doc

1

NovaTech D/3 Interface to the PI System

Table of Contents

Introduction......

Reference Manuals......

Supported Features......

Diagram of Hardware Connection......

Principles of Operation

Installation Checklist

Interface Installation on Windows

Naming Conventions and Requirements......

Interface Directories......

The PIHOME Directory Tree......

Interface Installation Directory......

Interface Installation Procedure......

Installing the Interface as a Windows Service......

Installing the Interface Service with PI ICU......

Installing the Interface Service Manually......

Interface Installation on OpenVMS......

Naming Conventions and Requirements......

Interface Installation Procedure......

Linking the Interface on OpenVMS......

Object Files......

TID3.opt......

TID3Link.com......

PIBuild and PISysExe......

Digital States......

PointSource......

D/3 Point Configuration......

D/3 Versions 5.0 to 9.0-1......

D/3 Version 9.0-2 and Higher......

D/3 Point Lists......

D/3 Hardware Shutdown......

PI Point Configuration......

Point Attributes......

Tag......

PointSource......

PointType......

Location1......

Location2......

Location3......

Location4......

Location5......

InstrumentTag......

ExDesc......

Scan......

Shutdown......

Output Points......

Trigger Method 1 (Recommended)......

Trigger Method 2......

Performance Point Configuration......

Configuring Performance Points with PI ICU (Windows)......

Configuring Performance Points Manually......

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

Monitoring I/O Rates on the Interface Node......

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

Configuring I/O Rate Tags Manually......

Configuring the PI Point on the PI Server......

Configuration on the Interface Node......

Startup Command File......

Configuring the Interface with PI ICU......

General Parameters......

General Tab......

Other UniInt Parameters......

Command-Line Parameters......

Sample TID3.bat File......

UniInt Failover Configuration......

Introduction......

Failover Installation Checklist......

Startup Command File Configuration......

Sample Interface Startup Files......

PI ICU Configuration......

Data Source Failover Control Point Configuration......

Active ID......

Heartbeat......

Control Point Data Flow......

PI Failover Control Tag Configuration......

Active ID......

Heartbeat......

Interface State Tag......

Interface State Tag Configuration......

Digital State Configuration......

Importing Failover Digital Set to PI via PI SMT 3......

Messages......

Informational......

Errors......

Interface Node Clock......

Windows......

OpenVMS......

Security......

Windows......

OpenVMS......

Starting / Stopping the Interface on Windows......

Starting Interface as a Service......

Stopping Interface Running as a Service......

Starting / Stopping the Interface on OpenVMS......

Starting a Detached Process......

Stopping......

Buffering......

Configuring Buffering with PI ICU (Windows)......

Configuring Buffering Manually......

Example piclient.ini File......

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

Message Logs......

System Errors and PI Errors......

Appendix B: PINet to PI 3 String Tag Support......

Method of Operation......

Setup Instructions......

The Automatic FTP Script......

Configuring the Script......

Starting and Stopping the FTP Script......

Informational and Error Messages from the FTP Script

Appendix C: “Watchdog”......

Restart.com......

RestartDetach.com

Using the “Watchdog”

Startup......

Shutdown......

Revision History

1

NovaTech D/3 Interface to the PI System1

Introduction

The NovaTech D/3 Interface to the PI System, also known as the PI GSETID3 Interface provides two-way communication with a NovaTech D/3 distributed control system. The interface program reads the PI point database to determine which points to read from and write to the NovaTech Configurator/Display Control Modules (CDCM/DCM).

The interface runs on a DEC VAX or Alpha computer with the D/3 Database Access software from NovaTech. The D/3 Software must be version 5.0 or later. The interface also runs on Windows NT/2000/XP with DBA D/3 Software version 10.0, 10.1, 10.2, 11.2, or 12.1.

Note: Please contact OSIsoft if you need to run with a version of D/3 software other than one of those listed above.
The interface can run on the various versions of Windows, but is limited to the versions on which the DBA D/3 software runs.

The PI System can run on the same computer as the D/3 software. The PI system can also run on another computer with the D/3 computer as a PI Interface node. In this way, it is possible to have several D/3 systems on different computers communicating with a PI System.

Reference Manuals

OSIsoft

• UniInt End User Document
• PI Data Archive Manual
• PI API Installation Instructions

Vendor

Consult the following NovaTech documentation for more information on D/3 software:

• D/3 Database Access User’s Guide (UG1.0007.V6.2C)
• D/3 PCM Database Fields Reference Manual, (RM1.0008.V6.2C)

Supported Features

Feature / Support
Part Number / PI-IN-GSE-D3-AXP
PI-IN-GSE-D3-VAX
PI-IN-GSE-D3DB-NTI
* Platforms / VMS / Alpha VMS /
NTI (4.0 / 2000 / XP)
APS Connector / No
PointBuilder Utility / No
ICU Control / Yes
PI Point Types / Real / digital / integer / float 32 / float 16 / string
Sub-second Timestamps / No
Sub-second Scan Classes / No
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / Yes
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based
Supports Questionable Bit / No
Supports Multi-character PointSource / No
Maximum Point Count / Unlimited
Uses PI SDK / No
PINet to PI 3 String Support / Yes
* Source of Timestamps / PI Server
History Recovery / No
* Failover / UniInt Failover (phase 1)
Server-Level Failover / No
* UniInt-based / Yes
* Vendor Software Required on PI API / PINet Node / Yes
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
* Additional PI Software Included with Interface / Yes (on OpenVMS)
* Device Point Types / See below

* See paragraphs below for further explanation.

Platforms

The Interface is designed to run onWindows XP, Windows 2000, and Windows NT 4.0 SP6aoperating systems. Because it is dependent on vendor software, newer platforms may not yet be supported.

Source of Timestamps

All input data uses the PI server as its source of timestamp.

UniInt-based

UniInt 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 GSETID3 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 UniIntsupplied 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.

UniInt Failover Support

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

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

Vendor Software Required

D/3 Database Access (DBA) software from NovaTech is required on the interface node. On OpenVMS the D/3 Software must be version 5.0 or later. The interface runs on Windows NT/2000/XP with DBA version 10.0, 10.1, 10.2, 11.2, or 12.1.

Additional PI Software

The PI GSETID3 interface supports input of strings on all platforms when sending data to PI 3. The BatchFile interface is required to input strings from interfaces running on a VAX. The BatchFile interface must run on Windows or UNIX.

Device Point Types

AI / CAL / CB / DED / DEV
AI_ALMCT / CAL_VAHI / CB_AFLG / DED_DIVL / DEV_ALMCT
AI_CRIT / CAL_VALO / CB_FLG / DED_DIVS / DEV_CMD
AI_CURAL / CAL_VAVL / CB_FLG1 / DED_VEVL / DEV_DFLG
AI_DEAD / CAL_VAVS / CB_FLG2 / DEV_FLG
AI_DEV / CAL_VBVL / CB_INVL / DEV_MODE
AI_DVLIM / CAL_VBVS / CB_INVS / DEV_STAT
AI_FLG / CAL_VCVL / CB_LOUT / DEV_TMP0
AI_HHLIM / CAL_VCVS / CB_OTHI / DEV_TMP1
AI_HLIM / CAL_VDVL / CB_OTLO
AI_INVL / CAL_VDVS / CB_OTRT
AI_INVS / CAL_VEVL / CB_OTVL
AI_LLIM / CAL_VEVS / CB_OTVS
AI_LLLIM / CAL_VFVL
AI_MEAS / CAL_VFVS
AI_RLIM
DGR / DIN / DOT / FAN / INT
DGR_ALMCT / DIN_ALMCT / DOT_ALMCT / FAN_OVL1 / INT_ETIM
DGR_FLG / DIN_FLG / DOT_FLG / FAN_OVS1 / INT_K
DGR_VAL / DIN_VAL / DOT_VAL / FAN_LO1 / INT_TOT
FAN_OVL2
FAN_OVS2
FAN_LO2
IOS / LIM / LLG / MF / PID
IOS_I0VL / LIM_HIVL / LLG_KVL / MF_FCHI / PID_GNVL
IOS_I0VS / LIM_HIVS / LLG_KVS / MF_FCLO / PID_GNVS
IOS_I1VL / LIM_LOVL / LLG_LDVL / MF_FCORR / PID_GPAC
IOS_I1VS / LIM_LOVS / LLG_LDVS / MF_FLVL / PID_INISP
IOS_TGVL / LIM_OHVL / LLG_LGVL / MF_FLVS / PID_LERR
IOS_TGVS / LIM_OHVS / LLG_LGVS / MF_K1VL / PID_LLDR
IOS_TG / LIM_OLVL / LLG_LI / MF_K1VS / PID_LMEA
LIM_OLVS / MF_K2VL / PID_MESP
MF_K2VS / PID_MEVL
MF_PRVL / PID_MEVS
MF_PRVS / PID_MEZE
MF_PTVL / PID_RAVL
MF_PTVS / PID_RAVS
MF_TCVL / PID_REVL
MF_TCVS / PID_REVS
MF_TMVL / PID_SPHI
MF_TMVS / PID_SPINT
PID_SPLO
PID_SPRT
PID_SPVL
PID_SPVS
PRF / RMP / RB / SAV / SEL
PRF_FDSP / RMP_ICVL / RB_IBHI / SAV_I0HI / SEL_I0HI
PRF_FDVL / RMP_ICVS / RB_IBLO / SAV_I0LO / SEL_I0LO
PRF_FDVS / RB_IBVL / SAV_I0VL / SEL_I0VL
PRF_FDZE / RB_IBVS / SAV_I0VS / SEL_I0VS
PRF_GNVL / RB_INTRT / SAV_I1VL / SEL_I1VL
PRF_GNVS / RB_OBHI / SAV_I1VS / SEL_I1VS
PRF_GPAC / RB_OBLO / SAV_I2VL / SEL_I2VL
PRF_INISP / RB_OBVL / SAV_I2VS / SEL_I2VS
PRF_LBIAS / RB_OBVS / SAV_I3VL
PRF_LERR / RB_RAMP / SAV_I3VS
PRF_LFDBK / RB_RSAF / SAV_I4VL
PRF_LMEA / RB_RTHI / SAV_I4VS
PRF_MESP / RB_RTLO / SAV_I5VL
PRF_MEVL / RB_RTVL / SAV_I5VS
PRF_MEVS / RB_RTVS / SAV_NAVG
PRF_MEZE / SAV_NCOL
PRF_OTSP
PRF_OTZE
PRF_RAVL
PRF_RAVS
PRF_REVL
PRF_REVS
PRF_SPHI
PRF_SPINT
PRF_SPLO
PRF_SPRT
PRF_SPVL
PRF_SPVS
PRF_FDSP
PRF_FDVL
XBR
XBR_CPVL
XBR_HISPEC
XBR_LCPKV
XBR_LCPVL
XBR_LOSPEC
XBR_LRNGV
XBR_LXBRV
XBR_RLCL
XBR_RMAX
XBR_RMIN
XBR_RNGV
XBR_RTARG
XBR_RUCL
XBR_STDDEV
XBR_XBALM
XBR_XBRV
XBR_XLCL
XBR_XTARG
XBR_XUCL

Diagram of Hardware Connection

1

NovaTech D/3 Interface to the PI System1

Principles of Operation

At startup the interface loads all the PI points with the designated point source and interface number. As each point is loaded a call is made to the D/3 system to verify the existence of the point in the DBA. GLF calls are used for continuous points and get_vseq is used for sequence points.

The startup command line controls whether the Sequence Database is accessible or exists. If the interface should not attempt to read the Sequence Database and Sequence Database PI points should be rejected, the command line should include /noseq.

Once the PI points are loaded, the interface periodically reads data from the D/3 or outputs data on event. The interface can request or send up to 255 points of the same D/3 database block type at the same time for collection of continuous data. There is a dilemma with this grouping, though: it is more efficient to group the requests, but the D/3 does not return error information point-by-point. This means that if the request fails all the tags would be considered BAD INPUT. The interface allows for two options when such an error occurs:

1. The interface can go on to individually requesting data for each of the points and eventually determine the point or points in error. These points are then added to a list to revisit at a later time, about thirty minutes later. This waiting period allows the user to change points in the D/3 without having to cycle the interface. If on the second pass the GLF call still returns an error for the D/3 point, the PI point is removed from the interface. The interface attempts to add the PI point again when the interface is restarted or if a non-essential PI point attribute is changed.
2. The user may want the interface to handle the GLF errors by stopping the interface automatically. In this case, use /KS or /KS=0 as a command-line parameter.

UniInt Failover

This interface supports UniInt failover. Refer to the “UniInt Failover Configuration” section of this document for configuring the interface for failover.

1

NovaTech D/3 Interface to the PI System1

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps get the PI GSETID3 interface running. If unfamiliar with PI interfaces, return to this section after reading the rest of the manual in detail.

Windows

1. Install the PI Interface Configuration Utility (which installs the PI SDK and PI API)
2. Verify that the PI API has been installed.
3. Install the interface.
4. Define digital states.
5. Choose a point source. If installing on a PI 2 home node, create the point source.
6. Configure PI points.
7. Configure performance points.
8. Configure I/O Rate tag.
9. Use the PI ICU to configurethe startup command file, TID3.bat.
10. Set interface node clock.
11. Set up security.
12. Start the interface without buffering.
13. Verify data.
14. Stop interface, start buffering, start interface.
15. Configure UniInt Failover. Refer to the UniInt Failover Configurationsection of this manual for details relating to configuring the interface for failover.

1

NovaTech D/3 Interface to the PI System1

OpenVMS

1. Check the hardware.
2. Install NovaTech D/3 Software.
3. Make sure that the D/3 logical D3$INCLUDE is defined.
4. Make sure that the D/3 logical D3EXE is defined.
5. Rename one of the object files to tid3.obj.
6. Edit TID3.opt.
7. Link the interface by executing tid3link.com.
8. Define the necessary digital states.
9. Choose a point source. If PI 2 home node, create the point source.
10. Configure the PI tags.
11. Configure performance points.
12. Configure I/O Rate tag.
13. Edit startup command file, TID3.com and TID3detach.com.
14. Set up security.
15. Test the FTP mechanism for PINet to PI 3 string support. See Appendix B for more information.
16. Edit the D3SET:SiteStartUp.com file. Add a new line for the interface as follows: @PISysExe:RestartDetach tid3
17. Edit the SiteStop.com file. Add 2 new lines for the interface as follows:

@PISysExe:Stop TID3_r

@PISysExe:Stop TID3

or

@PISysExe:TID3Stop

1. Start the interface.
2. Verify data.
3. Edit the D3SET:SiteStartUp.com file. Add a new line for the interface as follows: @PISysExe:RestartDetach tid3
4. Edit the SiteStop.com file. Add 2 new lines for the interface as follows:

@PISysExe:Stop TID3_r

@PISysExe:Stop TID3

or

@PISysExe:TID3Stop

1

NovaTech D/3 Interface to the PI System1

Interface Installation on Windows

OSIsoft recommends that interfaces be installed on PI API nodes instead of directly on the PIServer node. A PI API node is any node other than the PI Server node where the PIApplication Programming Interface (PI API) has been installed (see the PI APIInstallation Instructions manual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PIServer 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 APInode (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.

Naming Conventions and Requirements

In the installation procedure below, it is assumed that the name of the interface executable is TID3.exe and that the startup command file is called tid3.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 tid31.exe and tid31.bat for interface number 1, tid32.exe and tid32.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line parameters in a file that has the same root name.

Interface Directories

The PIHOME Directory Tree

The PIHOME directory tree is defined by the PIHOME entry in the pipc.iniconfiguration file. This pipc.ini file is an ASCII text file, which is located in the %windir%directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on the C: drive. OSIsoft recommends using \pipc as the root directory name. The PIHOMEdirectory does not need to be on the C: drive.

Interface Installation Directory

Place all copies of the interface into a single directory. The suggested directory is:

PIHOME\Interfaces\TID3\

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

Interface Installation Procedure

The PI GSETID3Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000and greater operating systems. When running on Windows NT 4.0 systems, thePI GSETID3 setup program will install the Windows Installer itself if necessary. To install, run the GSETID3_x.x.x.x.exe installation kit.

In the installation procedure below, assume that interface number 1 is being installed and that all copies of the interface will be installed in the same directory.

1. Use the PI ICU program to configure the interface’s .bat file based on the discussions found in this manual.
2. Try to start the interface interactively with the command:
   TID3.bat
   If the interface cannot be started interactively, one will not be able to run the interface 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.

Note:When installing the interface from the installation kit, it is important to choose the correct D/3 version because only the corresponding TID3.exe will be installed.