PI_hbcxpi

Hartmann & Braun ContronicP/3/E-K via ConLink X Interface

to the PI System

Version 2.0.0.7

Revision C

How to Contact Us

OSIsoft, Inc.

777 Davis St., Suite 250

San Leandro, CA 94577 USA

Telephone

(01) 510-297-5800 (main phone)

(01) 510-357-8136 (fax)

(01) 510-297-5828 (support phone)

[email protected]

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

WWW.OSISOFT.COM

OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.

RESTRICTED RIGHTS LEGENDUse, 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.

© 2000-2004 OSIsoft, Inc. PI_HBCXPI.doc

http://WWW.OSISOFT.COM/

mailto:[email protected]

Table of Contents

Introduction....................................................................................................................1

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

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

Diagram of Hardware Connection................................................................................4

Principles of Operation.................................................................................................5

Data Acquisition...........................................................................................................5

Creating, Editing and Deleting PI Tags........................................................................6

Timeouts.......................................................................................................................6

Timestamps and Clock Synchronization......................................................................6

H&B Block Configuration File.......................................................................................7

Sample Block Configuration File..................................................................................8

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

Interface Installation on NT.........................................................................................11

Naming Conventions and Requirements....................................................................11

Interface Directories...................................................................................................11

Interface Files.............................................................................................................12

Interface Installation Procedure..................................................................................12

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

Interface Installation on VMS......................................................................................23

Naming Conventions and Requirements....................................................................23

Interface Installation Procedure..................................................................................23

Digital States................................................................................................................29

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

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

Point Attributes...........................................................................................................33

Output Points..............................................................................................................36

Performance Point Configuration...............................................................................39

Hartmann & Braun Contronic P/3/E-K via ConLink X Interface to the PI System iii

Configuring Performance Points with PI-ICU (NT-Intel).............................................39

Configuring Performance Points Manually.................................................................41

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

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

Configuring I/O Rate Tags with PI-ICU (NT-Intel).......................................................43

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

Startup Command File.................................................................................................47

Command-line Parameters.........................................................................................47

Sample Interface Startup File for NT..........................................................................58

Sample Interface Startup File for OpenVMS..............................................................59

Failover between a PI2 Home Node and a PINet Node.............................................59

Failover between two PINet Nodes............................................................................61

Failover between a PINet Node and a Windows Interface Node...............................65

Interface Node Clock...................................................................................................67

NT...............................................................................................................................67

VMS............................................................................................................................67

Security.........................................................................................................................69

NT...............................................................................................................................69

VMS............................................................................................................................69

Starting / Stopping the Interface on NT......................................................................71

Starting Interface as a Service...................................................................................71

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

Starting / Stopping the Interface on VMS...................................................................73

Starting a Detached Process......................................................................................73

Stopping the Interface................................................................................................75

Buffering on NT............................................................................................................77

Configuring Buffering with PI-ICU (NT-Intel)...............................................................77

Configuring Buffering Manually..................................................................................80

Example piclient.ini File..............................................................................................81

Failover.........................................................................................................................83

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

Message Logs............................................................................................................85

System Errors and PI Errors.......................................................................................85

Hartmann & Braun Contronic P/3/E-K via ConLink X Interface to the PI System iv

Appendix B: Dumping H&B Information for use with PIDIFF/PICONFIG.................87

Appendix C: Serial Port Configuration on VMS........................................................89

HUBCXSetTerm.com.................................................................................................89

HUBCXSTerm.com....................................................................................................90

Terminal Server Configuration under VMS.................................................................90

Type-ahead Buffers in VMS.......................................................................................92

Appendix D: Troubleshooting.....................................................................................95

Appendix E: Interface Control Program.....................................................................97

NT...............................................................................................................................97

VMS..........................................................................................................................101

Revision History...........................................................................................................105

Hartmann & Braun Contronic P/3/E-K via ConLink X Interface to the PI System v

Introduction

The Hartmann & Braun Contronic P/3/E-K via ConLink X Interface to the PI System (PI-ConLink X Interface) provides the bi-directional transfer of data between a Hartmann & Braun Contronic P, Contronic 3 or Contronic E-K Process Control System and the Plant Information (PI) System using the ConLink X protocol. The Interface itself runs on Windows NT Intel and OpenVMS (VAX, ALPHA), but can connect to any PI Server node.

The data transfer between the computer and the process control system takes place via an RS232 data interface. The H&B requirements are Contronic P/3/E-K Version 7.2 or 8.0 and one (or more) installed PCV02 boards.

With the ConLink X protocol, you can couple host computers with active Contronic P/3/E-K stations (central operator station, group operator station or coordinator station).

Starting with Version 2.x of the interface (available only on Windows) there is support for PI-AutoPointSync (PI-APS). The PI-AutoPointSync Connector for the Hartmann & Braun Contronic P/3/E-K via ConLink X Interface establishes a connection to the H&B ConLink X Interface in order to get configuration data that can be used to synchronize point database fields of existing tags with the corresponding fields in Contronic.

Reference Manuals

OSIsoft

UniInt End User Document

PI Data Archive Manual

PI-API Installation Instructions

Hartmann & Braun

MANNESMANN Hartmann & BraunService-Information 43/70-5187D-1 XAProzeßleitsystem Contronic P Contronic 3Conlink X

MANNESMANN Hartmann & BraunBedienungsanleitung 42/70-5195E Prozeßleitsystem Contronic P Contronic 3Programmier-Schnittstelle für Anwender (03/92)

Hartmann & Braun Contronic P/3/E-K via ConLink X Interface to the PI System 1

Supported Features

Feature Support

Part Number PI-IN-HB-CX-VAXPI-IN-HB-CX-AXPPI-IN-HB-CX-NTI

Platforms VAX/VMS / Alpha OpenVMS / Windows NT4 (Intel), Windows 2000, Windows XP

APS Connector Yes

PI Point Types R, I, D, float16, float32, int16, int32, digital

Sub-Second Timestamps No

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-Based

Maximum Point Count Contronic 7.2: 900 (30 Blocks x 30 slots)Contronic 8.0: 12000 (100 Blocks x 120 slots)

Uses PI-SDK No

PINet to PI 3 String Support No

* Source of Timestamps Interface Node

* History Recovery No

* Failover Yes

* UniInt-Based Yes

Vendor Software Required on PI-API / PINet Node

No

* Vendor Software Required on Foreign Device

Yes

* Vendor Hardware Required Yes

* Additional PI Software Included with Interface

No

* Device Point Types ANA, BIN, ZAE, (B16, REA)

* See paragraphs below for further explanation.

Source of Timestamps

All values are evaluated and sent to the archive using Operating System timestamps of the interface node.


Failover

See details in section Failover.

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-ConLink X 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 Hardware Required

A PCV02 Data Interface Board must be attached to Contronic.

Vendor Software Required

Contronic P/3/E-K Version 7.2 or 8.0

Device Point Types

The interface supports the following device point types:

Analog ANAbinary BINcounter ZAE(16 bit-word B16)(real number (32 bit) REA)

Only Contronic signals of type ANA, BIN and ZAE have been tested so far. Device Point Types B16 and REA have not yet been tested.


Introduction

Diagram of Hardware Connection

4

Principles of Operation

At startup, the Interface checks all command line parameters.

If one of them is out of range and cannot be filled with a default value, the interface generates an error message and stops.

If all parameters are correct, the interface runs the initialization part.

According to both the PI Point Configuration values (e.g. Point Type) and the H&B Block Configuration File, blocks are configured using tags with the same data-type scan class (location 4) and direction (location 5) to prepare for Contronic block operations. For entering the Contronic Tag Name/Selector into the H&B Block, the ConLink transfer mode MIBE is used (literally German “Meßstelle In Block Eintragen”, which translates to “Enter Tag Name Into Block”.Event counters are initialized and finally, a sign-up-for-updates operation is performed to identify changes in the PI Point Database. For more information about the configuration file, see “H&B Block Configuration File” on page 7.

Data Acquisition

Input

The interface performs block read-operations using the ConLink transfer mode BMML (literally German “Block Mit Meßstelle Lesen”, which translates to “Read Block With Tag”). Data are retrieved from Contronic on a regular basis, according to the scan class information stored in location 4 of the tag. Data are sent to PI using Exception Reporting.

If the Contronic System transfers an error marked value, then the tag will receive the Set to Bad digital state in PI.

So far, input from H&B tags of type ANA, BIN and ZAE could be tested on site.

Output

Output of data to Contronic is based on PI exceptions for interface output tags (Trigger Method 2) or, preferably, the related Source Tags (Trigger Method 1 (Recommended)) and is uploaded to Contronic whenever an input scan cycle (of whatever scan class) is performed. If it is necessary to update values in Contronic with 5-second accuracy, define a Scan-Class of at least 5 seconds (and at least 1 Input tag in that Scan Class). This does not mean that a write block is downloaded every 5 seconds. It means that if the value changes in PI it gets uploaded to Contronic within the next 5 seconds. The ConLink transfer method used to send data to Contronic is BMMS (literally German “Block Mit Meßstelle Schreiben”, which translates to “Write Block With Tag”).

The mechanism of using the source point field makes it possible that another tag which could be an input tag of any (and even the same) interface, can be the data source of an Output Tag. So far, output to H&B tags of type ANA, BIN and ZAE could be tested on site.


Creating, Editing and Deleting PI Tags

The interface periodically checks alterations of the point database and performs the necessary operations such as adding, editing and deleting tags.

Timeouts

The interface always checks for Life Signals. If the interface detects a broken link, all tags for this interface get a digital state of I/O Timeout.

Re-establishment of communication is reported in the log file.

Timestamps and Clock Synchronization

All values are evaluated and sent to the archive using Operating System timestamps of the interface node. On OpenVMS, it is possible to set the VMS time according to the Contronic time (see /tl=… and /sd=… startup switches). This feature is not implemented on NT.


H&B Block Configuration File

Data are read from and written to the Contronic system via spontaneous block transfer. Depending on the number of points to be maintained and their data type, a sufficient number of blocks of the appropriate data types and the data direction (Read or Write) must be pre-configured on the H&B Contronic side. For more information about SIGTYP, see “ExDesc”. As there is no way to get this configuration information directly from Contronic, it must be exchanged in a block configuration file, which is an ordinary ASCII text file.

The information in this file must exactly match the configuration in Contronic. Otherwise, block operations will fail. If, in accordance to changes in the point database, the configured tags no longer fit the prepared Contronic blocks, some blocks may require redefinition. To make the interface work correctly, you must stop and restart it after editing the configuration file according to the Contronic configuration changes.

Specify the full path to the configuration file on interface startup via parameter /cfgfile.

The interface kit has a template file specifying some analog and binary blocks. Besides configuration specification, the file contains usage hints.

Note: To increase interface performance, tags are not only considered according to their data type but also regarding the scan class. The interface passes tags into the same Contronic block if and only if they match in data type and scan class. Therefore some additional blocks may be necessary to process all tags. Consult your H&B specialist to configure a sufficient number of blocks of the appropriate data types.


Sample Block Configuration File

; This is an example for a Contronic block configuration file defining

; the data type of 5 blocks.

; The first column contains block number, the second contains blocktype

; and the third data direction.

; Specify comment lines by typing ; as first character.

; Add comments to lines containing data by appending ; and the comment.

; Blank lines are possible. The example shows Contronic block 0 and 1 being

; configured for containing analog data, block 2 for binary data.

; The user may edit this file according to his actual configuration in the H&B

; Contronic system.

00 ANA R; block 0 contains analog data

01 ANA R ; Semicolon not immediately after ANA possible

02 BIN R

;03 ANA R ; space or tab between block number and type ignored

04 ANA W ; a writeable analog block

05 BIN W ; a writeable binary block

;06 ANA R

; This is a further whole comment line within the data lines – ignored.

;07 BIN R

;8 ZAE R; 08 or 8 is the same.

;09 ANA R

;10 BIN R

;11 ZAE R

;12 ANA R

;13 BIN R; block contains binary data

;14 ZAE R

;15 ANA R

;16 BIN R

;17 ZAE R; block for counter values

;18 ANA R

;19 BIN R

;20 ZAE R

;21 ANA R

;22 BIN R

;23 ZAE R

;24 ANA R

;25 BIN R

;26 ZAE R

;27 ANA R

;28 BIN R

;29 ZAE R

; This is the end of the configuration file.


Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI-ConLink X 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. If the PI-ConLink X interface is to be installed on NT, install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API). This step is skipped for VMS.

2. Verify that PI-API has been installed. On VMS, verify that PI or PINet is running.

3. Install the interface. If on NT, use PI-ICU to configure the interface. If PI-APS Support is needed, configuring via PI-ICU is mandatory.

4. Define digital states.

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

6. Configure PI points. Location1 is the interface instance.Location2 is not used.Location3 is not used.Location4 is the scan class.Location5 is the direction of data transfer (0 for input tags, 1 for output tags).ExDesc is the signal type.InstrumentTag is the Contronic Tag name + Selector.

7. Configure performance points.

8. Configure I/O Rate tag.

9. Edit startup command file.Ask the DCS engineer for- Contronic type (needed for /contronic=[P|3|E)- Baud rate, bitcount, parity, stopbits, (NT only, needed for /baud)- Contronic Station number (needed for /station)- Contronic version (7.2 or 8.0, needed for /cv)

Ask the PI System Manager for- name of the serial port on the interface computer (needed for /port)

10. If on VMS, configure the serial port (direct or Terminal Server port). /baud is meaningless for VMS. In case of Terminal Server, you need the Terminal Server password.

11. On NT, set interface node clock. Not applicable for a VMS PINet Node.

12. Set up security.

13. Create the H&B Block Configuration File. Ask the DCS engineer for the block numbers configured, their data type and their data direction (Read or Write)


14. If on NT, start the interface without buffering. On VMS, just start the interface.

15. Verify data.

16. If on NT, stop interface, start buffering, start interface. (Not applicable for VMS.)


Interface Installation on NT

OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PI Server node. A PI Interface Node is any node other than the PI Server node where the PI Application Programming Interface (PI-API) 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 Interface 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 Interface Nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.

The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and 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 hubcx.exe and that the startup command file is called hubcx.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 hubcx1.exe and hubcx1.bat for interface number 1, hubcx2.exe and hubcx2.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 file that has the same root name.

Interface Directories

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 as the root of the PIHOME directory tree on the C: drive. OSIsoft recommends using \pipc as the root directory name. The PIHOME directory does not need to be on the C: drive.

Interface Installation DirectoryPlace all copies of the interface into a single directory. The suggested directory is:

PIHOME\interfaces\hubcx\

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

Interface Files

The following files reside in the PIHOME\interfaces\hubcx\ directory:

cppi.bat Interface Control Program bat filecppi.exe Interface Control Programhubcx.bat.new Interface startup command file templatehubcx.cfg.new H&B Block Configuration File templatePI_hubcx.doc This Interface Manualhubcx.exe Interface executablePI_hubcx_1.43.0.0.txt Release Notes

The .new extension should be removed if this is a new installation. During an upgrade, site-specific files are not overwritten. However, new versions of these files are provided (with the extension .new). These new files may have significant changes from the original versions. These files should be compared to the originals and changes incorporated as needed.

Interface Installation Procedure

You may receive the interface on CD, via mail or ftp, as a zipped file hubcx_<version>.zip, for example hubcx_1.43.0.0.zip, a self-extracting archive hubcx_<version>.exe, for example hubcx_1.43.0.0.exe or a Microsoft Windows Install setup kit.

Using Microsoft Windows Installer

The PI-ConLink X Interface setup program 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 PI-ConLink X Interface setup program will install the Windows Installer itself if necessary. To install, run the hubcx_x.x.x.x.exe installation kit. The kit prompts for the location to which the interface should be installed and will enter information into the registry.

Using a Zipped File

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. Copy the interface files from the installation media toPIHOME\interfaces\hubcx\. Create the directory if necessary.


2. If necessary, rename the command file so that it has the same root name of the executable.

3. Alter the command-line arguments in the .bat file as discussed in this manual.

4. Try to start the interface interactively with the command:

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

Installing the Interface as an NT Service

The PI-ConLink X Interface service can be created with the PI-Interface Configuration & Management Utility, or can be created manually.

Installing the Interface Service with PI-Interface Configuration UtilityThe PI-Interface Configuration & Management Utility (PI-ICU) provides a user interface for creating, editing, and deleting the interface service. For details, please refer to the PI-Interface Configuration Utility User Manual.



To start, run PI-ICU, and then choose Interface New… or click on the ‘New’ icon on the toolbar.

14

Next, click the ‘Browse’ button to navigate to the interface executable:



Click ‘Open’, then enter the Point Source character into the ‘Point Source’ field and click ‘Add’.

Afterwards, you should get this message:

Choose the interface type to be ‘Hartmann and Braun Contronic P E-K, ConLink X’. For this to happen, select ‘hbcxpi’ in the drop-down list. Create scan classes by clicking on the ‘Add a scan class’ button. Then click ‘Apply’. Your screen will look like this:

16

PI-ConLink X Interface-specific Startup Parameters

Note that currently, no interface-specific PI-ICU Control exists for the PI-ConLink X Interface. Nevertheless, configuration actions can be performed. However, the PI-ConLink X (not UniInt) specific arguments must be manually entered under the tab ‘hbcxpi’. For example:



Service Configuration

Service name

The Service to Add box shows the name of the current interface service. This service name is obtained from the interface executable.

Display name

The Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of the OSI suite of products.

Service Type

The Service Type indicates whether the interface service will start automatically or need to be started manually on reboot.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, interface services are set to start automatically.

Dependencies

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

list using the button. For example, if API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. To remove a

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

18

When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.

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

- Add button

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

- Remove button

To remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.

The full name of the service selected in the Installed services list is displayed below the Installed services list box.



Create

The Create button adds the displayed service with the specified Dependencies and with the specified Startup Type.

Remove

The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.

Start or Stop Service

To Start or Stop an interface service, use the Start button and a Stop button on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.

The status of the Interface service is indicated in the lower portion of the PI-ICU dialog.

Installing the Interface Service ManuallyOne can get help for installing the interface as a service at any time with the command:

hubcx.exe –help

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

NT Service Installation Commands on a PI Interface Node or a PI Server node with Bufserv implemented

Manual service hubcx.exe –install –depend “tcpip bufserv”

Automatic service hubcx.exe –install –auto –depend “tcpip bufserv”

NT Service Installation Commands on a PI Interface Node or a PI Server node without Bufserv implemented

Manual service hubcx.exe –install –depend tcpip

Automatic service hubcx.exe –install –auto –depend 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.

20

Status of the ICU

Status of the Interface Service

Service installed or uninstalled

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.


Interface Installation on VMS

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

In the installation procedure below, it is assumed that the interface executable is called hubcx.exe, the startup command file for interactive processes is called hubcx_01.com, and the startup command file for detached processes is called hubcxpidetach.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 startup command file, e.g. hubcx_01.com or hubcx_02.com, hubcx_03.com. 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 hubcx.exe file and one hubcxpidetach.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 files are hubcx_01.out, hubcx_02.out, hubcx_03.out and so on.

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

Interface Installation Procedure

Interface files are installed and linked automatically as part of PI or PINet installations. If the interface has been automatically installed, skip to the “Starting and Stopping the Interface” section, p. 73. Sometimes, however, an interface needs to be installed or upgraded separately from the PI or PINet installation. This procedure is frequently done when the available version of the interface is newer than that which is included 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

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

HUBCX.BCK Saveset containing the interface files.

PI_hubcx_1.43.0.0.TXT Release notes.

REBLOCK.README Readme file for REBLOCK.EXE.

REBLOCK.EXEThe interface backup saveset must be reblocked before the saveset can be unpacked. See the REBLOCK.README.

The following procedure is typical.

1. Transfer HUBCX.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. Run REBLOCK.EXE on the HUBCX.BCK file. Reblock corrects the block size of the HUBCX.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): hubcx.bck

Filename (“\” to exit): \


The block size can also be corrected with a DCL command. The result is equivalent to the one achieved with REBLOCK.

Syntax:

$ SET FILE/ATTRIB=LRL:32256 hubcx.bck

3. Copy HUBCX.BCK to the PIBuild: directory and unpack the save set.

$ copy hubcx.bck PIBuild:$ set def PIBuild$ backup/log hubcx.bck/save *%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCX.OBJ;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXCP.HLP;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXCP.OBJ;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXCPC.OBJ;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXDEVICE.OBJ;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXDRV.OBJ;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXFAILOVER_FUNCTIONS.OBJ;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXPIDETACH.COM;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXPILINK.COM;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXPISTART.COM;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXPISTOP.COM;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXSETTERM.COM;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXSTERM.COM;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCXUNIINT.OBJ;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCX_01.CFG;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCX_01.COM;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCX_02.CFG;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCX_02.COM;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCX_03.CFG;1%BACKUP-S-CREATED, created DKB0:[PIBUILD]HUBCX_03.COM;1

$

4. Install the interface files with the command:

$ @hubcxpilinkcreating PISysExe:HUBCX.EXE ...creating PISysExe:HUBCXCP.EXE ...creating Help library PIResources:HUBCXCP.HLB ...copying command files to PISysExe: ...copying cfg files to PISysDat: ...done$

5. The following files are installed during the above procedure:

PIBuild DirectoryHUBCX.OBJ Object file for the Interface

HUBCXCP.HLP Control program Help file

HUBCXCP.OBJ Object file for the Interface Control Program

HUBCXCPC.OBJ Object file for the Interface Control Program

HUBCXDEVICE.OBJ Object file for the Interface

HUBCXDRV.OBJ Object file for the Interface

HUBCXFAILOVER_FUNCTIONS.OBJ Object file for the Interface


Interface Installation on VMS

HUBCXPIDETACH.COMStartup command file for detached processes (the command-line arguments are still defined in e.g. the HUBCX_01.COM file).

HUBCXPILINK.COM Command procedure for (re-) linking the executable.

HUBCXPISTART.COM Command procedure starting all interfaces

HUBCXPISTOP.COM Command procedure stopping all interfaces

HUBCXSETTERM.COM Command procedure for setup of all LAT ports

HUBCXSTERM.COM Command procedure for setup of one LAT port

HUBCXUNIINT.OBJ Object file for the interface

HUBCX_01.CFG Template for H&B Configuration File (Interf.ace #1)

HUBCX_01.COM Startup command file (interactive, Interface #1)





PISysExe DirectoryHUBCX.EXE Interface executable.

HUBCXCP.EXE Interface Control Program

HUBCXPISTART.COM Command procedure starting all interfaces

HUBCXPISTOP.COM Command procedure stopping all interfaces

HUBCXSETTERM.COM Command procedure for setup of all LAT ports

HUBCXSTERM.COM Command procedure for setup of one LAT port




HUBCXPIDETACH.COMStartup command file for detached processes (the command-line arguments are still defined in e.g. the HUBCX_01.COM file).

PISysDat DirectoryHUBCXCP.HLB Control program Help library




26

To re-link to the Contronic interface, execute@PIBuild:HUBCXPILink.com

All files are moved to their target directories.Make sure PI is running when you perform the link procedure.

You can create an entry in PISysMgr:SiteSpecificLink.com to guarantee automatic interface re-linking when re-linking PI.

Note: If command files or configuration files are site-specific, they are not overwritten/updated.


Digital States

For more information regarding Digital States, refer to the Data Archive Manuals.

PI 2 Home Node

Digital states are defined by running the Digtl Stat display from the PI menu. The states must be contiguous for each status type and may be anywhere within the Digital State Table outside of the range 193 – 320, which is reserved for OSIsoft. The digital states need to be defined prior to point configuration. The digital state sets described in the PI 3 sections below should be entered into the PI 2 Digital State Table.

For more information, see the DA manual.

PI 3 Home Node

Digital State Sets

PI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Data Archive Manual for Windows NT and Unix manual.

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

System Digital State Set

Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state Set to Bad to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients.


PointSource

The 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 H to identify points that belong to the PI-ConLink X Interface. To implement this, one would set the PointSource attribute to H for every PI Point that is configured for the PI-ConLink X Interface. Then, if one uses /ps=H on the startup-command line of the PI-ConLink X Interface, the PI-ConLink X Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of H. Before an interface loads a point, the interface 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 Attributes

If 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=H and /ps=h 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 H is not defined in the PI 2 point source table, a point with a point source of H 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 1 0 0 1 0

Maximum 20000000 0 0 255 1


5. Select “Save” from the menu.

PI 3 Server Nodes

No 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 Configuration

The PI point is the basic building block for controlling data flow to and from the PI Data Archive. A single point is configured for each measurement value that needs to be archived. Use the point attributes below to define what data to transfer.

Point Attributes

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.

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 additional information, see the /ps command-line argument and the “Point Source” section.

PointTypeTypically, 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.

PI 2 Server Nodes

Scaled 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 Nodes

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

Refer to the description of ExDesc for a list of possible PI Point Type – Contronic Data Type combinations.

Zero, SpanThe values should be the same as the corresponding fields in Contronic. The ASCII output in the interface output file (in Debug level 1) contains Contronic information about lower and upper limits for the H&B tags. You can use these values to configure the PI tags via PIDIFF or PIConfig.

Location1Location1 indicates to which copy of the interface the point belongs. Only one interface for each serial port is supported.


Location2Not used.

Location3Not used.

Location4

Scan-Based Inputs

For interfaces that support scan-based collection of data, Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the /f flag in the section called “Startup Command File”.

Trigger-Based Inputs, Unsolicited-Inputs, and Output Points

Location4 should be set to zero for these points.

Scan-Classes are available for Inputs. Outputs are scheduled whenever an Input Scan is performed.

Location5Location5 indicates the direction of data transfer.

Input: 0 (PI tag gets values from Contronic)

Output: 1 (Value of the PI tag will be written to Contronic)

InstrumentTagThe InstrumentTag attribute contains the Contronic tag name and Selector. They have the following length:

Contronic P: 18 Bytes

Contronic 3: 24 Bytes

Contronic E-K: 24 Bytes

Example: P73434/VXA

where P73434 is the Contronic Tag Name, VXA is the selector, separated from the tag name by a slash (/).


ExDescExDesc, the Extended Descriptor, is used to store information about the Hartmann & Braun data type of the tag.

SIGTYP=datatype

Possible Contronic data types and corresponding valid PI point types are:

Valid PI Point Type Contronic Data Type

Description Availability

float ANA analog Contronic V 7.2 or higher

float BIN binary Contronic V 7.2 or higher

float / integer / digital ZAE counter Contronic V 7.2 or higher

float / integer / digital B16 16 bit Contronic V 8.0 – not tested yet

float / integer / digital REA real Contronic V 8.0 – not tested yet

Example: SIGTYP=ANA

Only data types ANA, BIN and ZAE have been tested so far.

Performance Points

For UniInt-based interfaces, the extended descriptor is checked for the string “PERFORMANCE_POINT”. If this character string is found, UniInt treats this point as a performance point. See the section called “Performance Points.”

Trigger-Based Inputs

For trigger-based input points, a separate trigger point must be configured. An input point is associated with a trigger point by entering a case-insensitive string in the extended descriptor (ExDesc) PI point attribute of the input point of the form:

keyword=trigger_tag_name

where keyword is replaced by “event” or “trig” and trigger_tag_name is replaced by the name of the trigger point. There should be no spaces in the string. UniInt automatically assumes that an input point is trigger-based instead of scan-based when the keyword=trigger_tag_name string is found in the extended descriptor attribute.

An input is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous Snapshot value to trigger an input, but the timestamp of the new value must be greater than (more recent than) or equal to the timestamp of the previous value. This is different than the trigger mechanism for output points. For output points, the timestamp of the trigger value must be greater than (not greater than or equal to) the timestamp of the previous value.

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


PI Point Configuration

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.

Shutdown

PI 2 Server Nodes

The Shutdown attribute is not used if the server node is a PI 2 system. For information on configuring shutdown events for PI 2, see Data Archive (DA) section 4.2.3 of PI System Manual I.

PI 3 Server Nodes

The shutdown attribute is used only if the server node is a PI 3 system.

The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Data Archive for NT and UNIX.

Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the /stopstat=Shutdown command-line argument is specified.

One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Data Archive for NT and UNIX.

Bufserv

It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.

Output Points

Output points control the flow of data from the PI Data Archive to the Contronic.

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

36

Trigger Method 1 (Recommended)For trigger method 1, a separate trigger point must be configured. The output point must have the same point source as the interface. The trigger point can be associated with any point source, including the point source of the interface. Also, the point type of the trigger point does not need to be the same as the point type of the output point.

The output point is associated with the trigger point by setting the SourceTag attribute of the output point equal to the tag name of the trigger point. An output is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous value that was sent to the Snapshot to trigger an output, but the timestamp of the new value must be more recent than the previous value. If no error is indicated, then the value that was sent to the trigger point is also written to the output point. If the output is unsuccessful, then an appropriate digital state that is indicative of the failure is usually written to the output point. If an error is not indicated, the output still may not have succeeded because the interface may not be able to tell with certainty that an output has failed.

Trigger Method 2For trigger method 2, a separate trigger point is not configured. To trigger an output, write a new value to the Snapshot of the output point itself. The new value does not need to be different than the previous value to trigger an output, but the timestamp of the new value must be more recent than the previous value.

Trigger method 2 may be easier to configure than trigger method 1, but trigger method 2 has a significant disadvantage. If the output is unsuccessful, there is no tag to receive a digital state that is indicative of the failure, which is very important for troubleshooting.


Performance Point Configuration

One can configure performance points to monitor the amount of time in seconds that an interface takes 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 completion time is recorded to millisecond resolution

Configuring Performance Points with PI-ICU (NT-Intel)

The PI-Interface Configuration & Management Utility (PI-ICU) provides a user interface for creating and managing Performance Points.

Create

To create a Performance Point, right mouse click the line belonging to the tag to be created, and select Create.

Delete

To delete a Performance Point, right mouse click the line belonging to the tag to be deleted, and select Delete.

Correct

If the “Status” of a point is marked “Incorrect”, the point configuration can be automatically corrected by ICU by right mouse clicking on the line belonging to the tag to be corrected, and selecting Correct. The Performance Points are created with the


following PI attribute values. If ICU detects that a Performance Point is not defined with the following, it will be marked Incorrect:

Attribute Details

Tag Tag name that appears in the list box

Point Source Point Source for tags for this interface, as specified on the first tab

Compressing Off

Excmax 0

Descriptor Interface name + “ Scan Class # Performance Point”

Rename

To rename a Performance Point, right mouse click the line belonging to the tag to be renamed, and select “Rename”.

Status

The Status column in the Performance Points table indicates whether the Performance Point exists for the scan class in column 2.

Created – Indicates that the Performance Point does exist

Not Created – Indicates that the Performance Point does not exist

Deleted – Indicates that a Performance Point existed, but was just deleted by the user

Scan Class

The Scan Class column indicates which scan class the Performance Point in the Tagname column belongs to. There will be one scan class in the Scan Class column for each scan class listed in the Scan Classes combo box on the Uniint Parameters tab.

Tagname

The Tagname column holds the Performance Point tag name.

Snapshot

The Snapshot column holds the snapshot value of each Performance Point that exists in PI. The Snapshot column is updated when the Performance Points/Counters tab is clicked, and when the interface is first loaded.


Configuring Performance Points Manually

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

1. Set the extended descriptor to:PERFORMANCE_POINTor to:PERFORMANCE_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 Configuration

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

Monitoring I/O Rates on the Interface Node

For NT and UNIX nodes, the 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook. For Open VMS nodes, the rate (events/minute) can be monitored with the PISysExe:IOMonitor.exe program or with another client program such as Process Book. The IOMonitor program is discussed on page DA-71 of PI System Manual I.

Configuring I/O Rate Tags with PI-ICU (NT-Intel)

The PI-Interface Configuration & Management Utility (PI-ICU) provides a user interface for creating and managing IORates Tags.

PI-ICU currently allows for one I/O Rate tag to be configured for each copy of the interface that is in use. Some interfaces allow for multiple I/O Rates tags.

Enable IORates for this Interface

The Enable IORates for this interface check box enables or disables IORates for the current interface. To disable IORates for the selected interface, uncheck this box. To enable IORates for the selected interface, check this box.

Tag Status

The Tag Status column indicates whether the IORates tag exists in PI. The possible states are:

Created – This status indicates that the tag exist in PI

Not Created – This status indicates that the tag does not yet exist in PI

Deleted – This status indicates that the tag has just been deleted

Unknown – This status indicates that the ICU is not able to access the PI Server


In File

The In File column indicates whether the IORates tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are:

Yes – This status indicates that the tag name and event counter are in the IORates.dat file

No – This status indicates that the tag name and event counter are not in the IORates.dat file

Event Counter

The Event Counter correlates a tag specified in the iorates.dat file with this copy of the interface. The command line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file.

Tagname

The tag name listed under the Tagname column is the name of the IORates tag.

Snapshot

The Snapshot column holds the snapshot value of the IORates tag, if the IORates tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the interface is first loaded.

Right Mouse Button Menu Options

Create

Create the suggested IORates tag with the tag name indicated in the Tagname column.

Delete

Delete the IORates tag listed in the Tagname column.

Rename

Allows the user to specify a new name for the IORates tag listed in the Tagname column.

Add to File

Adds the tag to the IORates.dat file with the event counter listed in the Event Counter Column.

Search

Allows the user to search the PI Server for a previously defined IORates tag.

Configuring I/O Rate Tags Manually

There are two configuration steps.

Configuring the PI Point on the PI Server

PI 2 Server Nodes

A listing of the I/O Rate Tags that are currently being monitored can be obtained with the command:


@PISysDat:IOMonitor.com

Create an I/O Rate Tag using one of the existing I/O Rate Tags as a template.

PI 3 Server Nodes

Create an I/O Rate Tag with the following point attribute values.

Attribute Value

PointSource L

PointType float32

Compressing 0

ExcDev 0

Configuration on the Interface NodeFor the following examples, assume that the name of the PI tag is sy.io.hubcx, and that the name of the I/O Rate on the home node is sy.io.hubcx.

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:

sy.io.hubcx, x

where sy.io.hubcx is the name of the I/O 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 2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x, should be unique for each copy of the interface.

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

The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started.

Open VMS Nodes

I/O Rates are discussed on page DA-59 of PI System Manual I.

To implement an I/O Rate tag, perform the following steps:

1. Add a line to the PISysDat:IORates.dat file of the form:


I/O Rate Tag Configuration

sy.io.hubcx, x

where hubcx is an abbreviation for 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. If your PI Home Node is a PI2 system, choose a tag name that complies with the tag name syntax in your system (fixed positions of delimiters like “:” and “.”). 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: 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 I/O Rates process with the following commands so that the changes take effect:

@PISysExe:stop iorates

@PISysExe:iorates.com

46

Startup Command File

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

Notes for NT

For NT, command file names have a .bat extension. The NT continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of flags is unlimited, and the maximum length of each flag is 1024 characters.

The PI-Interface Configuration & Management Utility (PI-ICU) provides a tool for configuring the Interface startup command file. See PI-ConLink X Interface-specific Startup Parameters for more details.

Notes for Command-line Arguments Marked with “PI-APS, NT only”

There are a few command line switches that are only needed for PI-APS. The APS Connector needs specific information in order to update the PI Point Database for existing tags for a particular interface copy, based on configuration changes in Contronic. In addition, special information is needed in order to create new tags for this interface. The PI-APS Connector for the ConLink X Interface obtains this information from the Module Database of the PI Server the interface talks to. So, upon interface configuration via PI-ICU (PI-ICU is mandatory here), these parameters are just stored in the Module Database. The interface itself does not evaluate the APS related command line arguments.

Notes for VMS

For VMS, command file names have a .com extension. The VMS continuation character (-) allows one to use multiple lines in the command file. However, the maximum number of characters in a single or multi-line command is 256 characters. That is, adding continuation characters may make the command file easier to read, but they do not extend the 256-character limitation. The 256-character limitation can be overcome by putting the arguments in a separate argument file. See the /arg file command-line parameter in The UniInt End User Document for details.

Note: The UniInt End User Document includes details about other command line parameters, which may be useful.

Command-line Parameters

Parameter Description

/in=x

Required

The interface number is specified here. It corresponds to Location 1 of a tag.

/contronic=[P|3|E]

Required

This parameter is used to specify the Contronic Type. Valid arguments are P, 3 and E.



/cfgfile=<path>

Required

H&B Block Configuration File. Enter the complete path and filename. If multiple copies of the interface are run, a different configuration file can be specified for each.

Example: /cfgfile=c:\pipc\interfaces\hubcx\hubcx.cfg

/port=x

Required

Name of the serial port on the PI Interface Node that is connected to the PCV02 card.

Examples:Windows NT: /port=COM1VMS: /port=LTA200:

/port=TTA0:

/baud=x

Required for NTNot used for VMS

On NT, you must pass baud rate, bit count, parity and number of stop bits to the interface.On VMS, those settings must be configured via the SET TERMINAL command for the serial port used by the interface, e.g. TTA0:. If you use a Terminal server port, e.g. LTA200: you must login to the Terminal Server and define and set the port. See Appendix C: Serial Port Configuration on VMS for details. The /baud startup switch has no meaning if the interface runs on VMS.

In either case the values you specify must match those set up in the PCV02 card. If you are uncertain about the values, see your Hartmann & Braun specialist and have him print out the current settings. Here is an example:

---------------------------------------------------------------------------------------------------------------------------------------

--------

*-**-**-**-* 1*2**3**4* GRAFIK – LOOP – TREND – ALARM – L-EB – T-EB -??- * 28.08-10:36:22-CLEAR*<<SW>>SYSTEMDIALOG KANAELE STATION: 11 28.08.1997 10:35NAME: KNL-2 V24 PROT.KNL 1HWCH : 2KANALNUMMER : 2 LINIE :A KANALNUMMER :* LINIE :BGERAETETYP :CONLINKEINSTELLUNG :SW BAUD : 9600 PARITY :ODD DATEN : 8 STOP : 2 BOXEN : 2INPUT CONTROL :5E00 AKTIV :N OUTPUT CONTROL:1F00 AKTIV :N BLOCK :N BLOCK :N HALT :N HALT :N EBENE :* EBENE :*

>> RETURN DARSTELLEN SPEICHERN DEFEKT ZURUECK WEITER

KILL

---------------------------------------------------------------------------------------------------------------------------------------

--------

The syntax is /baud=[baud/bitcount/parity/stopbits]. The standard values configured at PCV02 fit to /baud=[9600/8/1/1].

Valid values are:baud: 9600, 19200bitcount: 8parity: 0 (even), 1 (odd), 2 (no)stopbits: 0 (1 stop bit), 1 (2 stop bits)

/station=x

Required

Contronic station number



/output=<path>

Required

Interface output file.

Example: /output=c:\pipc\interfaces\hubcx\hubcx.log

/deb=x

Optional

Optional Interface-specific debug level (0 … 6), default 0. Greater values result in more output (sent to the interface output file), which can be very helpful in tracking down errors. Values greater than 1 should only be used in problem situations. Especially level 6, which forces dumping every telegram sent and received, will produce an extremely big log file if enabled for more than a few minutes. Debug level 1 forces the interface to print H&B configuration information (lower and upper limits, description) on startup, in addition to the normal startup messages. Therefore it’s harmless to permanently have /deb=1 in the interface startup command file.

/cv=x

OptionalDefault: 8.0

Contronic Version number. This information is required because the different Contronic versions have different limits regarding the number of blocks as well as regarding the number of slots per block.

Examples:

/cv=7.2/cv=8.0 (Default)

/sd=x

OptionalDefault: 300

VMS only. Synchronization difference. See also /tlMax delta time in seconds to synchronize. Default: 300This value specifies the maximum corrected difference (in seconds) between the Contronic time and the system time of the computer where the interface runs on. Smaller differences result in automatic synchronization of the Host system time to the Contronic time. This has an advantage if the Contronic system is radio clock controlled. It is not possible to change the Contronic system time from the Interface.

/tl=x

OptionalDefault: 1

VMS only. Time level. See also /sdTime level, default: 1.Parameter /tl is used in order to control time synchronization. A value of 0 means no synchronization between the PI Interface Node’s VMS system time and Contronic time. Specify a value of 1 to initiate a cyclic check of the time difference. The PI Interface Node’s VMS time is set to Contronic time if necessary.




/lb=x

OptionalDefault: -1

Last block. Number of Blocks to clean on startup, default: -1.Use this parameter only if you definitely want to clear all Contronic blocks up to block number n on interface startup. Specify the highest Contronic block number here you are actually using.This will cause x m (x times m) slot cleanups, where m is the number of possible entries in one block (e.g. m=120 for Contronic version 8.0). Clearing a block can take a VERY long time (about 10 minutes for 6 blocks). But it can become necessary if the number of measuring points entered into a block and the number of transferred values for this block do no longer match (important for write-enabled blocks). This can occur after unexpected interface abort. If the parameter is omitted or out of range, the default value –1 (no block clearing) is used.

/sendiotimeout=[Y|N]

OptionalDefault: Y

In case of connection problems to Contronic, the interface writes the digital state I/O Timeout to its tags. This behavior can be changed via /sendiotimeout=N. This feature can be used to avoid intermittent breaks in the data due to temporary but recurring connection problems that are known to vanish after a short time. However, it is better to find the cause of such interruptions instead of masking them out.

/ifo=[ON|OFF]

OptionalDefault: OFF

FailoverYou can enable or disable automatic interface failover via this parameter. If set to ON, it will enable failover, given that the other required failover parameters are ok. Setting this parameter to OFF will disable failover, regardless of the other failover settings.

The default is /ifo=OFF

/ift=tagname

Required if failover is wanted.

FailoverThis is the name of the interface failover tag. It must be a valid PI tag of type Integer. The interface will check this tag very frequently. See Chapter “Failover” for details. If this switch is missing or points to a non-existing tag, the interface will disable failover, regardless of /ifo.

/mast=[ON|OFF]


FailoverMaster switch. If, in failover mode, two copies of the interface are started, the one with /mast=ON will actually collect data. The interface with /mast=OFF will enter stand-by mode.

/irv=x


FailoverInterface Run Value. The interface will collect data as long as it finds x in the interface failover tag. The standby interface will start to collect data as soon as it finds the standby interface’s /irv= value in the failover tag.

/ifv=x


FailoverInterface Fail Value. When the active interface exits, it will write the FailValue into the failover tag. If there is a stand-by interface, whose RunValue is equal to active interface’s FailValue, then that interface will start to collect data.

50


/ifd=x

OptionalDefault: 0

FailoverInterface failover digital state. It is possible to give a Digital state to all interface tags if automatic failover happened. The state must be passed as a negative number. In case of a PI3 Home Node, the state must be part of the System Digital Set. Make sure the position this state points to is filled with a reasonable string.The default value is 0, meaning that no digital state will be sent in case of failover.

/mft=x

OptionalDefault: 30

FailoverMaxFailTime (seconds). The active interface is permanently updating the failover tag’s snapshot with its Run Value and the current timestamp. The inactive interface, besides checking for the Run Value, also checks whether the snapshot timestamp is changing. If the snapshot timestamp does not change, the inactive interface takes over after having waited for an amount of time given in /mft. For example, /mft=30, which is the default, means that the inactive interface will accept an unchanging timestamp of the failover tag for about 30 seconds. Then it will take over. It is recommended to specify a value that is at least twice as big as the value for /lfs (see below). Otherwise you may switch over unintentionally.

/lfs=x

OptionalDefault: 15

FailoverSend rate (seconds) for failover life signal. Number of seconds between successive updates of the interface failover tag with the active interface’s Run Value. Depending on the speed of the network connection, it can be very important to restrict the frequency of sending the life signal. In the following scenario, we assume that the original Stand-by interface on the PI Home Node has taken over data collection, (e.g. because the Master interface had failed) but now the situation has improved and the Master interface on the PINet Node has been restarted. When the Master interface tries to regain control, due to its Master status, it sends its own Run Value to the failover tag. As it is sent from a PINet Node, this may take a while, and the value may arrive delayed on the Home Node. The value for /lfs must be adjusted to your network speed to ensure that the (possibly delayed) snapshot from the Net Node makes it through to the Home node BEFORE the active interface is updating the failover tag with its life signal again. If the active interface updates the failover tag before the value from the Master interface arrives, then the value from the Net Node will be an (old) out of order event. It will not go to the Home Node’s snapshot but “underneath” it, directly into the archive (if archiving is “on” for the failover tag). The consequence: The active interface, repeatedly checking the snapshot of the failover tag, will not get knowledge about the change and will not shut down as expected. The Master interface, on the other hand, starts up and you may end up having 2 interfaces operating in parallel on the same set of tags, with unpredictable results.

By default, the active interface sends its life signal every 15 seconds.




/apsdata=<path>

Required

PI-APS, NT onlyPath to the H&B Contronic Short Documentation file (Kurzdoku). The information in this file is used by the APS Connector to create new tags. It will be stored in the Module Database of the host PI Server, which therefore must be 3.3 or higher.Example:

/apsdata=c:\pipc\interfaces\hubcx\aps\ec4kurzdoku.txt

/ana_sel=sel1,sel2,…

OptionalDefault: VXA

PI-APS, NT onlyList of selectors that the APS Connector will append to the Analog signal names found in the Contronic Short Documentation (Kurzdoku). It will be stored in the Module Database of the host PI Server, which therefore must be version 3.3 or higher.Example:

/ana_sel=VXA,VXW,VXY

/bin_sel=sel1,sel2,…


PI-APS, NT onlyList of selectors that the APS Connector will append to the Binary signal names found in the Contronic Short Documentation (Kurzdoku). It will be stored in the Module Database of the host PI Server, which therefore must be version 3.3 or higher.Example:

/bin_sel=VXA,R0,R1,F1

/zae_sel=sel1,sel2,…


PI-APS, NT onlyList of selectors that the APS Connector will append to the Counter signal names found in the Contronic Short Documentation (Kurzdoku). It will be stored in the Module Database of the host PI Server, which therefore must be version 3.3 or higher.Example:

/zae_sel=VXA

/tagprefix

OptionalDefault: no prefix

PI-APS, NT onlyOptional prefix that the APS Connector puts in front of the H&B tag name/selector when suggesting a tag name to be created by PI-APS. The prefix will be applied to all new tags created by PI-APS based on the KKS found in the Contronic Short Documentation (Kurzdoku). It will be stored in the Module Database of the host PI Server, which therefore must be version 3.3 or higher.Example:

/tagprefix=EC

52


/defaultscanclass

OptionalDefault: 1

PI-APS, NT onlyOptional specification for a preferred scan class for new tags created by PI-APS, based on the Contronic Short Documentation (Kurzdoku). By default, all new tags will have Location4=1. The parameter will be stored in the Module Database of the host PI Server, which therefore must be version 3.3 or higher.Example:

/defaultscanclass=3

/kks_start

OptionalDefault: 8

PI-APS, NT onlyStart position of the KKS field in the Contronic Short Documentation (Kurzdoku). PI-APS needs this information to extract the KKS name when creating new tags. The KKS will be used for the tag name and the InstrumentTag name. The parameter will be stored in the Module Database of the host PI Server, which therefore must be version 3.3 or higher.Example:

/kks_start=8

/kks_len

OptionalDefault: 18

PI-APS, NT onlyLength of the KKS field in the Contronic Short Documentation (Kurzdoku). PI-APS needs this information to extract the KKS name when creating new tags. The KKS will be used for the tag name and the InstrumentTag name. The parameter will be stored in the Module Database of the host PI Server, which therefore must be version 3.3 or higher.Example:

/kks_len=18

/longtext_start

OptionalDefault: 40

PI-APS, NT onlyStart position of the Longtext field in the Contronic Short Documentation (Kurzdoku). PI-APS needs this information to extract the Longtext when creating new tags. The Longtext will be used for the Descriptor in PI. The parameter will be stored in the Module Database of the host PI Server, which therefore must be version 3.3 or higher.Example:

/longtext_start=40

/longtext_len

OptionalDefault: 28

PI-APS, NT onlyLength of the Longtext field in the Contronic Short Documentation (Kurzdoku). PI-APS needs this information to extract the Longtext when creating new tags. The Longtext will be used for the Descriptor in PI. The parameter will be stored in the Module Database of the host PI Server, which therefore must be version 3.3 or higher.Example:

/longtext_len=18




/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

Optional, recommended

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. See the section called “Error and Informational Messages” for more information, page 83.

For this interface, one should use only numeric characters in the identifier. For example,

/id=1

/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

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.

54


The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the interface is under a large load, then some scans may occur late or be skipped entirely. See the section called “Performance Point Configuration” for more information on skipped or missed scans.

Sub-second Scan Classes

One can also specify sub-second scan classes on the command line such as

/f=0.5 /f=0.1

where the scanning frequency associated with the first scan class is 0.5 seconds and the scanning frequency associated with the second scan class is 0.1 seconds.

Similarly, sub-second scan classes with sub-second offsets can be defined, such as

/f=0.5,0.2 /f=1,0

Wall Clock Scheduling

Scan 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

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 Interface 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/stopstat=digstate

Default:/stopstat=”Intf shut”

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=”Intf shut”

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

56


/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,” p. 43.

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. One must consult the interface-specific documentation to see whether subsequent instances of the /ec flag have any effect. 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.

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




/q

Optional for NT

Not implemented for interfaces on VMS nodes

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

Extended API mode behavior:

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

Non-Extended API mode behavior:

The maximum queue size is 255 bytes for a PI 3 Server and 36 bytes for a PI 2 Server. For example, if the interface is running on a UNIX node and is communicating to a PI 2 Server, then the maximum queue size is 36. The queue is flushed between scans if it is not filled.

When the /q flag is specified in non-extended API mode, the PI-API sends integer values as 16-bit integers instead of 32-bit integers. Therefore, integer points will be limited to values between 0 and 32767. Values higher than 32767 need to be sent to floating-point PI tags.

Sample Interface Startup File for NT

The following is an example file hubcx.bat, failover not configured:

start “CONTRONIC-P Interface” HUBCX ^/ps=H ^/f=00:00:05 ^/f=00:01:00 ^/f=00:10:00 ^/in=1 ^/id=1 ^/deb=0 ^/host=mypi3server:5450 ^/port=COM1 ^/cv=7.2 ^/contronic=P ^/station=1 ^/baud=[19200/8/1/1] ^/cfgfile=c:\pipc\interfaces\hubcx\hubcx.cfg ^/output=c:\pipc\interfaces\hubcx\hubcx.log

58

Sample Interface Startup File for OpenVMS

The following is an example file hubcx_xx.com, failover not configured:

$ ! HUBCX_xx.com BB 10-apr-1997$ ! Enhanced error handling KP 26-Jul-2000$ !==================================================================$ ! Run HUBCX-xx as a process.$$ say := write sys$output$ start:$ laststatus = $STATUS$ if (laststatus .ne. %X00030001) then - say “Last value of $STATUS: “,laststatus,”, “,f$message(laststatus)$ if ((laststatus .eq. 2) .or. (laststatus .eq. 1)) then goto stop$ on error then goto start$ HUBCX :== $pisysexe:hubcx$ HUBCX - “/ps=H” - /f=00:00:15 - /f=00:01:00 - /f=00:10:00 - /in=02 - /ec=23 - /deb=0 - /db - /tl=0 - /lb=-1 - “/port=TTA3:” - /cv=7.2 - “/contronic=P” - /station=2 - /cfgfile=pisysdat:hubcx_03.cfg$$ goto start$ stop:$ say “Exiting command file”$ exit

Failover between a PI2 Home Node and a PINet Node

The following two example startup files cover a failover scenario. Note that they both share the same PointSource and interface number because they service the same tags. However, they might talk through different serial ports (two different PCV02 cards attached to the same Contronic). Each instance writes messages to its own output file. Each copy has its own cfg file, but with identical block configuration information.

The first file belongs to the “Master” interface (/mast=on), which becomes active if both interfaces are started. If the secondary interface has taken over for failover reasons, and the master interface has reconnected to Contronic, the master interface will resume operation and the secondary interface will switch to standby mode.

In this example, it is assumed that the master interface runs on a PINet Node whereas the secondary interface (equipped with /mast=off) runs on a PI2 Home Node. This makes sense because data collection should happen distributed whenever possible. As soon as both interface nodes are available, the interface on the PINet Node should take precedence over the one running on the Home Node.



Interface 1: PINet Node

$ ! HUBCX_xx.com BB 10-apr-1997$ ! Enhanced error handling KP 26-Jul-2000$ !==================================================================$ ! Run HUBCX-xx as a process.$$ say := write sys$output$ start:$ laststatus = $STATUS$ if (laststatus .ne. %X00030001) then - say “Last value of $STATUS: “,laststatus,”, “,f$message(laststatus)$ if ((laststatus .eq. 2) .or. (laststatus .eq. 1)) then goto stop$ on error then goto start$ HUBCX :== $pisysexe:hubcx$ HUBCX - “/ps=H” - /f=00:00:15 - /f=00:01:00 - /f=00:10:00 - /in=01 - /ec=22 - /deb=0 - /db - /tl=0 - /lb=-1 - “/port=TTA1:” - /cv=7.2 - “/contronic=P” - /station=1 - /cfgfile=pisysdat:hubcx_01.cfg - /ifo=on - /ift=s2:in.ex - /mast=on - /irv=0 - /ifv=1 - /ifd=64 $$ goto start$ stop:$ say “Exiting command file”$ exit

The second file has /mast=off. Note that its “interface run value” /irv is equal to the “interface fail value” /ifv of its counterpart and vice versa.

60

Interface 2: PI2 Home Node

$ ! HUBCX_xx.com BB 10-apr-1997$ ! Enhanced error handling KP 26-Jul-2000$ !==================================================================$ ! Run HUBCX-xx as a process.$$ say := write sys$output$ start:$ laststatus = $STATUS$ if (laststatus .ne. %X00030001) then - say “Last value of $STATUS: “,laststatus,”, “,f$message(laststatus)$ if ((laststatus .eq. 2) .or. (laststatus .eq. 1)) then goto stop$ on error then goto start$ HUBCX :== $pisysexe:hubcx$ HUBCX - “/ps=H” - /f=00:00:15 - /f=00:01:00 - /f=00:10:00 - /in=01 - /ec=22 - /deb=0 - /db - /tl=0 - /lb=-1 - “/port=TTA2:” - /cv=7.2 - “/contronic=P” - /station=1 - /cfgfile=pisysdat:hubcx_02.cfg - /ifo=on - /ift=s2:in.ex - /mast=off - /irv=1 - /ifv=0 - /ifd=64 $$ goto start$ stop:$ say “Exiting command file”$ exit

Failover between two PINet Nodes

Note: In this case, both PINet nodes will be running against the same PI3 Home Node

It is possible to have /mast=off in both interfaces’ startup files. This simply means that none of the interfaces will try to regain control upon restart. Each one will just start, but then wait until the other one fails. With one /mast=on in place, the interface being the master will take over, regardless of the other interface working properly.

Remark for VMS PINet Nodes

VMS PINet Nodes, among other tables, maintain a local copy of the snapshot of each tag. Once data for a tag has been collected locally by an application running on this PINet Node, a request to read the snapshot for this tag will be sent to the local snapshot table. Should another program, running on another node (e.g. an interface running on the



Home Node or another PINet Node) update the tag, then the local interface will not detect snapshot changes caused by those remote programs. In order to make this possible the nolocal utility must be run on the PINet Node that has to be made aware of snapshot changes caused by remote sources. This program, when run, will return the following message:

$ run pinet:nolocal No data being collected locally$

In practice, this means that a PINet Node interface that was previously feeding the failover tag due to successful operation, and which went down for some reason, will detect a ‘stale’ failover tag after restart. The reason for this is that the interface only reads the local snapshot. Information that another interface has taken over in the meantime and is updating the failover tag’s snapshot does not make it to the PINet Node. Therefore, it is best to put the run pinet:nolocal command into the startup command file of interfaces that run on a PINet Node and which do not have /mast=on set. Here is an example of a pair of command files designed for 2 PINet Nodes, both running against a PI3 Home Node. None of the PINet Node interfaces is meant to be master. Note the $ run pinet:nolocal line incorporated in the command files.

62

Interface 1: PINet Node 1

$ ! HUBCX_xx.com BB 10-apr-1997$ ! Enhanced error handling KP 26-Jul-2000$ !===================================================================$ ! Run HUBCX-xx as a process.$$ say := write sys$output$ start:$ laststatus = $STATUS$ if (laststatus .ne. %X00030001) then - say “Last value of $STATUS: “,laststatus,”, “,f$message(laststatus)$ if ((laststatus .eq. 2) .or. (laststatus .eq. 1)) then goto stop$ on error then goto start$ run pinet:nolocal$ HUBCX :== $pisysexe:hubcx$ HUBCX - “/ps=H” - /f=00:00:15 - /f=00:01:00 - /f=00:10:00 - /in=01 - /ec=22 - /deb=0 - /db - /tl=0 - /lb=-1 - “/port=TTA1:” - /cv=7.2 - “/contronic=P” - /station=1 - /cfgfile=pisysdat:hubcx_01.cfg - /ifo=on - /ift=s2:in.ex - /mast=off - /irv=0 - /ifv=1 - /ifd=64$$ goto start$ stop:$ say “Exiting command file”$ exit



Interface 2: PINet Node 2


64

Failover between a PINet Node and a Windows Interface Node

Failover is not limited to one OS platform. One interface can run on VMS while the other runs on a Windows platform.

Interface 1: PINet Node




Interface 2: Windows Interface Node

start “CONTRONIC-P Interface” HUBCX ^/ps=H ^/f=00:00:05 ^/f=00:01:00 ^/f=00:10:00 ^/in=1 ^/id=1 ^/deb=0 ^/host=klauspc:5450 ^/port=COM1 ^/cv=7.2 ^/contronic=P ^/station=1 ^/baud=[19200/8/1/1] ^/cfgfile=c:\pipc\interfaces\hubcx\hubcx.cfg ^/output=c:\pipc\interfaces\hubcx\hubcx.log ^/ifo=on ^/ift=s2:in.ex ^/mast=off ^/irv=1 ^/ifv=0 ^/ifd=64

66

Interface Node Clock

NT

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

VMS

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


Security

NT

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.Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.

If the 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 3 Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging, p.85.

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 (or the PI Trust Table, respectively) are configured so that the PINet node is allowed to write data to the Archive. For more information, see “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Data Archive manual. For PI 3.3 or higher, see “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.

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 PI3 Server owing to permission problems, error –10401 will be written to the PISysMgr:PIMesslog.txt file.


Starting / Stopping the Interface on NT

This section describes starting and stopping the interface once it has been installed as a service. See the UniInt End User Document to run the interface interactively.

Starting Interface as a Service

If the interface was installed a service, it can be started from PI-ICU, the services control panel or with the command:

hubcx.exe –start

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

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

Stopping Interface Running as a Service

If the interface was installed a service, it can be stopped at any time from PI-ICU, the services control panel or with the command:

hubcx.exe –stop

The service can be removed by:

hubcx.exe –remove

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

The shutdown procedure closes all assigned communication channels. It may take a while.


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.

Starting a Detached Process

Log in as user SYSTEM and enter this command:

$ @PISysExe:HUBCXPISTART

The interface is started as a detached process with the hubcxpidetach.com command file. Typically, the hubcxpidetach.com file does not need to be edited, because the command-line parameters are edited in the associated hubcx_xx.com file, e.g. hubcx_01.com. However, in some cases it may be necessary to edit the hubcxpidetach.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 hubcxpidetach.com file.

$ ! HUBCXPIDetach.com KP 23-Jul-2003$ !=================================================================$ ! Run HUBCXPI as a detached process. Parameters are:$ !$ ! P1 = n Interface number$ !$ !$ !=================================================================$ !$ if („’’P1’“ .eqs. „“) then goto BadParameter$!$ if (f$search(„PISysExe:hubcx_0’’P1’.com“) .nes. „“) then goto Next$ goto BadFile$!$ Next:$ If (F$Search(„PISysExe:hubcx_0’’P1’.out“).nes.““) then - Purge/Nolog/Keep=30 PISysExe:hubcx_0’P1’.out$!$ Run/Detach/UIC=[SYSTEM]/Process=“HUBCXPI-‚’P1’“/extent=5000 - /Input=PISysExe:hubcx_0’P1’.com /Output=PISysExe:hubcx_0’P1’.out - /working=2000/page_file=100000/maximum_working=6000/extent=10000 - /buffer=64000/file_limit=128/job_table=4096 - Sys$System:LogInOut$ exit$ BadParameter:$ write sys$output „The Interface number Must Be Passed“$ exit$!$ BadFile:$ write sys$output „PISysExe:hubcx_0’’P1’.com does NOT Exist...“$ exit$! End of File$


Assuming that the example command file is used to start the interface, the following command will start instance 1 of the interface as a detached process:

@PISysExe: hubcxpidetach 1

The name of the process will be “HUBCXPI-1” as defined by the /Process flag to the run command in the above command file

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

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

The Interface number must be passed.

2. hubcxpidetach.com searches for the existence of the PISysExe:hubcx_01.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:

PISysExe:hubcx_01.com does NOT Exist...

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

4. The HUBCXPI-1 process is started with the run command. Several actions are performed by the run command:

The name of the process is set to HUBCXPI-1 by the /Process flag.

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

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

The standard output from the interface is redirected to the PISysExe:hubcx_01.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.


All interfaces can be started via

@pisysexe:hubcxpistart

The following file PISysExe:hubcxpistart.com would start 3 copies of the PI-Conlink X Interface:

$ ! HUBCXPIStart.com BB 10-apr-1997$ !!===============================================================$ !$ @pisysexe:hubcxpidetach 1$ @pisysexe:hubcxpidetach 2$ @pisysexe:hubcxpidetach 3$ !

To automate startup on OpenVMS, you may edit PISysMgr:SiteStart.com . Insert the line:

@PISysExe:hubcxpistart

Stopping the Interface

To stop the interface, issue the following command:

@PISysExe:stop HUBCXPI-1

Where 1 is the instance number of the process.

Alternatively, to shutdown e.g. Interface 1 (according to the /in=… startup switch), you can use the control program. Enter the commands:

$ run pisysexe:hubcxcp

HUBCXpi> shutdown /id=1

HUBCXpi> exit

$

To stop all interfaces, enter

$ @PISysExe:HUBCXPISTOP

which might look as follows:

$! HUBCXPIStop.com BB 10-apr-1997$!=================================================$!$ run pisysexe:hubcxcpshutdown /id=1shutdown /id=2shutdown /id=3$ exit


Buffering on NT

For complete information on buffering, please refer to the PI-API Manual.

PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI-API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.

Configuring Buffering with PI-ICU (NT-Intel)

Buffering is enabled through the PI-Interface Configuration Utility’s Tools>API Buffering… menu. Unless buffering is explicitly enabled, the PI-API will not buffer data, sending data directly to the home node.

The API Buffering… dialog allows the user to view and configure the parameters associated with the API Buffering (bufserv) process. The user can start and stop the API Buffering process from the Service tab:

Service Tab

The Service tab allows for some API Buffering service configuration. For further configuration changes, use the Services applet.

Service Name

The Service name displays the name of the API Buffering Service.

Display Name

The Display name displays the full name associated with the API Buffering service.


Log On As

Log on as indicates the Windows user account under which the API Buffering service is setup to start automatically on reboot, or manually. To modify the user account or password under which bufserv runs, use the Microsoft Windows “Services” applet.

Dependencies

The Dependencies lists the Windows services on which the API Buffering service is dependent.

Service Startup Type

The Startup Type indicates whether the API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, the API Buffering service is set to start automatically.

Start / Stop Service

The Start / Stop buttons allow for the API Buffering service to be started and stopped.

After a change is made to any of the settings on the Settings tab, the Save button must be clicked, and then the service must be stopped and restarted for the changes to be picked up by bufserv.

Settings Tab

The Settings tab allows for configuration of the 7 configurable settings used by API Buffering. Default values are used if no other value is provided.


Enable API Buffering

Enables the API Buffering feature.

Maximum File Size

Maximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000.

The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Send Rate

Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000.


Primary Memory Buffer Size

Primary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Secondary Memory Buffer Size

Secondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Max Transfer Objects

Max transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.


Pause Rate

When buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000.


Retry Rate

When the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.



Buffering on NT

Max Theoretical Send Rate

This is the theoretical max send rate is calculated like this:max = MAXTRANSFEROBJS / SENDRATE * 1000Default value is 5000.

There are no additional steps needed to install buffering after installing the PI-API. The delivered PI-API library supports both buffered and un-buffered calls.

Configuring Buffering Manually

Buffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI-API will not buffer data, sending data directly to the home node.

There are no additional steps needed to install buffering after installing the PI-API. The delivered PI-API library supports both buffered and un-buffered calls.

Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI-API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.

Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under Windows NT. This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows) to the desired values.

The following settings are available for buffering configuration:

Keywords Values Default Description

BUFFERING 0,1 0 Turn off/on buffering. OFF = 0, ON = 1,

PAUSERATE 0 – 2,000,000 2 When buffers are empty the buffering process will wait for this long before attempting to send more data to the home node (seconds)

RETRYRATE 0 – 2,000,000 120 When the buffering process discovers the home node is unavailable it will wait this long before attempting to reconnect (seconds)

MAXFILESIZE 1 – 2,000,000 100,000 Maximum buffer file size before buffering fails and discards events. (Kbytes)

MAXTRANSFEROBJS

1 – 2,000,000 500 Maximum number of events to send between each SENDRATE pause.

BUF1SIZE 64 – 2,000,000

32768 Primary memory buffer size. (bytes)

BUF2SIZE 64 – 2,000,000

32768 Secondary memory buffer size. (bytes)

SENDRATE 0 – 2,000,000 100 The time to wait between sending up to MAXTRANSFEROBJS to the server

80

(milliseconds)

In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define the default PI server and an optional time offset change that may occur between the client and server.

Keywords Values Default Description

PIHOMENODE string none Default server for UNIX. Not applicable for this interface. Windows default server is in pilogin.ini

DSTMISMATCH 0 – 2,000,000 0 The time that the server and client local time offset is allowed to jump. Typically, 3600 if the nodes are in time zones whose DST rules differ (seconds)

Example piclient.ini File

On Windows NT the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a connection before retrying.

On NT a piclient.ini file might look like:

[APIBUFFER]

BUFFERING=1

MAXFILESIZE=100000

; The PI-API connection routines have a 1 minute default timeout.

RETRYRATE=600


Failover

It is possible to configure automatic failover for the interface. Failover in this context means having 2 copies of the same interface, running on 2 different nodes. One of the nodes can be the PI Home Node. It is not required that the 2 interfaces are running on the same operating system platform. The failover information is exchanged via an ordinary PI Integer tag. The PI system can run on any operating system platform supported by OSIsoft. However, if one the interfaces runs on the Home node, the restrictions according to the supported platforms for this interface apply.

The idea is that both interfaces are being started in parallel, but only the one that has been given the “Master” status (via interface startup parameter /mast) actually starts collecting data. The other one stays in one of the failover routines and waits for “ignition”. It periodically reads the failover tag to determine whether or not it should wake up and take over data collection. The “WaitIgnition” function keeps the inactive interface in an endless loop. The interface will exit from this loop and start “normal” interface operation, if one of the following conditions is fulfilled:a) the interface finds its own runvalue in the failover tagb) the timestamp of the failover tag’s snapshot value has not been updated for a time period longer than specified via the /MFT command line argument, indicating that the active interface is down.

The active interface, on the other hand, permanently writes its own identifier into the failover tag to indicate that it is alive. Whenever the active interface detects a broken link to the DCS, it writes the number of the stand-by interface to the failover tag, herewith hands over the direction and exits. It is possible for the customer to modify the interface start script to restart the interface automatically after an exit, if he so wishes.

Note:A timeout of the failover tag’s snapshot (see b) above) will happen, if

1. The active interface has stopped

or

2. There is a network disconnection between the PI Home Node and the PINet Node (or NT Interface node, respectively)

Explanation for Situation 1

If the snapshot of the failover tag does not update due to a stop of the master interface, then the stand-by interface will take over data collection. If the master interface is restarted, it stops its counterpart and regains control. Only one interface runs at a time. Everything is ok.

Explanation for Situation 2

The second case, i.e. network problems between the PI Home node and the PINet Node/NT PI Interface Node is not covered by this failover concept. If the snapshot of the failover tag does not update due to a network problem, then the stand-by interface will start. The master interface, however, will continue to run. Both interfaces collect data. As there is no connection to the PI Home node, data will be buffered. When the network connection between the nodes is re-established, buffered data will be flushed, causing many (depending on the duration of disruption) duplicate events in PI as data for the tags have already been collected by the failover interface.


If you detect a broken network link between the PI Home Node and the PINet Node/NT Interface Node you should execute the following steps (before you re-establish the connection) to avoid duplicate archive events:

Stop the PINet node if on VMS. Stop the interface and bufserv if on NT.

On a VMS PINet Node, delete the file Pisysdat:eventq.dat. This step deletes all buffered data collected by the PINet node since disruption, including buffered data from other interfaces! If on NT, delete pipc\dat\APIBUF.DAT.

Reconnect the PINet node/NT Interface Node.

If on VMS, start the PINet node (@pinet:pinetstart.com). The master interface on the PINet node stops the failover interface and starts data collection.

On NT, start the interface, which will start bufserv (if so configured).

If you do not delete the pisysdat:eventq.dat (VMS) or APIBUF.DAT (NT) many error messages will be generated by pisn_sendexceptions while flushing buffered data to the archive.

It is not possible to provide an automatic reaction for the case that only the communication between the PI Home node and the VMS PINet node/NT Interface Node fails because one cannot tell WHY a snapshot is not updating. For this case a user action is always required.

To avoid data loss by deleting the buffer file pisysdat:eventq.dat in case of connection failure between PI Home node and PINet node it is recommended that you only run interfaces with failover processes running on another PINet Node or the PI Home Node.


Appendix A:Error and Informational Messages

There are interface messages in three locations:

The PI message log. The interface puts its error and information messages in this file except for messages from fatal errors that prevented the interface from starting up.

The interface output file. All fatal error messages are copied to this file. The interface also copies selected messages and (if debug is on) debug information to this file.

The Interface Window (Windows NT).

Errors related to tag values are also reported if you assign the tag a BAD INPUT state. This happens, if the status of a value derived from Contronic is BAD.

Input tags can also get an I/O Timeout status if the interface detects connection problems.

A string NameID is pre-pended to error messages written to the message log. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id flag on the startup command line.

Message Logs

The location of the message log depends upon the platform on which the interface is running. See the UniInt End User Document for more information.

Messages are written to PIHOME\dat\pipc.log at the following times.

When the interface starts many informational messages are written to the log. These include the version of the interface, the version of UniInt, the command-line parameters used, and the number of points.

As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.

If the /deb is used on the command line, then various informational messages are written to the log file.

System Errors and PI Errors

System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.

Error Descriptions on NT and Unix

On NT, descriptions of system and PI errors can be obtained with the pidiag utility:

\PI\adm\pidiag –e error_number


Appendix B:Dumping H&B Information for use with PIDIFF/PICONFIG

When you run the interface in detached mode, you create an interface output file. During initialization, the program gets H&B informational data such as:

Short and long descriptions of the measuring point

Start and end of the measuring scale.

With these values, you can complete your tag configuration. With analog values, you can

Derive zero and span from the scale limits or

Make tag names more meaningful by inserting H&B point descriptions into the pi tag descriptor field (all point types).

Extract the corresponding lines from the above mentioned output file and create a PIDIFF/PICONFIG data file for each point type. To perform the database alterations properly, see the PI manual concerning PIDIFF/PICONFIG. The interface may keep running while you make changes to the point database.

Note that /deb=1 is required to dump the H&B information into the interface output file.


Appendix C:Serial Port Configuration on VMS

Before you start the PI-ConLink X Interface(s), please configure the corresponding serial port(s). The following files are part of the interface installation kit. Edit them according to your needs and then execute them.

HUBCXSetTerm.com

$ ! HUBCXSetTerm.com MJ 03/24/93$ !========================================================================$ !$ ! This file creates and sets up the LAT ports for the H&B interfaces.$ ! Execute this procedure during system startup.$ ¡$ ¡ @PISysExe:HUBCXSTerm Lta100: ts01 port_1$ ¡ @PISysExe:HUBCXSTerm Lta200: ts01 port_2$ ! @PISysExe:HUBCXSTerm Lta300: ts01 port_3$ !$ Exit


HUBCXSTerm.com

$ ! HUBCXSTerm.com MJ 03/24/93$ !========================================================================$ !$ ! This file creates and sets up the LAT port for one H&B interface.$ ! P1 is the terminal name.$ ! P2 is the terminal server name.

$ ! P3 is the terminal server port name

$ ! Execute this procedure during system startup.

$ !

$ Say := write sys$output

$ Latcp = “$LATCP”

$ !

$ ! Determine the Device to Create

$ !

$ Termname = P1

$ If (Termname .eqs. “”) then inquire Termname “Terminal”

$ Server = P2

$ If (Server .eqs. “”) then inquire Server “Server”

$ Port = P3

$ If (Port .eqs. “”) then inquire Port “Server Port”

$ !

$ If (f$getdvi(Termname,”EXISTS”)) Then goto Device_Exists

$ Latcp Create Port ‘Termname’

$ Latcp Set Port ‘Termname’ /Node=’Server’ / Port=’Port’


$ !

$DEVICE_EXISTS:

$ !

$ ! Setup Terminal Characteristics

$ !

$ wait 0:0:5

$ Set term/perm -

/NoTTsync -

/Speed=9600/Noautobaud -

/NoEcho/EightBit/Parity=even -

/Pasthru/Altypeahd -

/NoModem/NoDisconnect -

/Nointeractive/NoBroadcast -

/NoScope/NoWrap -

‘Termname’

$ set prot=(w:rw)/dev ‘Termname’

$ !Show Term ‘Termname’

$ Exit

Terminal Server Configuration under VMS

If you use a Terminal Server to connect to the H&B Contronic system, it will be necessary to configure the ports you are using. Below, you can find an example for an NCP session that was performed to set the correct values for

character size (to enable 8 bit transfer)

flow control (to prevent XON/XOFF characters from having any meaning)

stop bits

speed (Baud rate)

(Enter help at the Local> prompt for information on how to configure other important parameters.)

$ set default sys$system:

$ mc ncp

NCP>connect node ts01

Console connected (press CTRL/D when finished)

#<enter terminal server password (network)

Network Access SW V1.5 for DS700-08 (BL95D-34)

Copyright 1995, Digital Equipment Corporation – All Rights Reserved

Please type HELP if you need assistance

Enter username> <Username>

Local> set privilege

Password> <enter terminal server password (local)Local> define port 2 character size 8 flow control disable stop bits dynamic speed 9600

Local> set port 2 character size 8 flow control disable stop bits dynamic speed 9600

Local> show port 2

Port 2: Server: TS01

Character Size: 8 Input Speed: 9600

Flow Control: None Output Speed: 9600

Parity: Odd Modem Control: Disabled

Stop Bits: Dynamic


Appendix C: Serial Port Configuration on VMS

Access: Remote Local Switch: None

Backwards Switch: None Name: PORT_2

Break: Local Session Limit: 1

Forwards Switch: None Type: Ansi

Default Protocol: LAT Default Menu: None

Preferred Service: None

Authorized Groups: 0

(Current) Groups: 0

Enabled Characteristics:

Local>CTRL/D

NCP>exit

92

Examples for Terminal Settings in VMSBelow, there are two examples for terminal settings. Note, that for a direct port like TTA0:, “Commsync” must be enabled in order to ignore XON/XOFF characters which might be legal parts of the exchanged telegrams. For Terminal Server ports, disable XON/XOFF via … FLOW CONTROL DISABLED … as described above. In this case, “Commsync” does not apply.

$ SHOW TERMINAL TTA0:Terminal: TTA0: DeviceType: Unknown Owner: No Owner Input: 19200 Lffill: 0 Width: 80 Parity: Odd Output: 19200 Crfill: 0 Page: 24 Terminate on parity errors

Terminal Characteristics:Passall No Echo Type_ahead No EscapeNo Hostsync No Ttsync Lowercase No TabNo Wrap Hardcopy No Remote EightbitNo Broadcast No Readsync No Form FulldupNo Modem No Local_echo No Autobaud No HangupNo Brdcstmbx No DMA Altypeahd Set_speedCommsync Line Editing Overstrike editing No FallbackNo Dialup No Secure server No Disconnect PasthruNo Syspassword No SIXEL Graphics No Soft Characters No Printer PortNumeric Keypad No ANSI_CRT No Regis No Block_modeNo Advanced_video No Edit_mode No DEC_CRT No DEC_CRT2No DEC_CRT3 No DEC_CRT4 No DEC_CRT5 No Ansi_ColorVMS Style Input

$ SHOW TERMINAL LTA200:

Terminal: LTA200: DeviceType: Unknown Owner: HUBCXPI-2 Username: HROLFSLAT Server/Port: TS01/PORT2

Input: 19200 Lffill: 0 Width: 80 Parity: Odd Output: 19200 Crfill: 0 Page: 24 Terminate on parity errors

Terminal Characteristics:

Passall No Echo Typeahead No Escape No Hostsync No Ttsync Lowercase No Tab No Wrap Hardcopy No Remote Eightbit No Broadcast No Readsync No Form Fulldup No Modem No Localecho No Autobaud Hangup No Brdcstmbx No DMA Altypeahd Setspeed No Commsync Line Editing Overstrike editing No Fallback No Dialup No Secure server No Disconnect Pasthru No Syspassword No SIXEL Graphics No Soft Characters No Printer Port Numeric Keypad No ANSICRT No Regis No Blockmode No Advancedvideo No Editmode No DECCRT No DECCRT2 No DECCRT3 No DECCRT4 No DECCRT5 No AnsiColor VMS Style Input$

Type-ahead Buffers in VMS

The Type-Ahead buffer and the Alternate Type-Ahead buffer must be set to a size of at least 1024. The following lines explain how to do this.

Login as User “SYSTEM” and show the actual sizes by:


Appendix C: Serial Port Configuration on VMS

$ set default sys$system:$ run sysgenSYSGEN> SHOW/TTYParameters in use: ActiveParameter Name Current Default Min. Max. Unit Dynamic-------------- ------- ------- ------- ------- ---- -------TTY_SCANDELTA 10000000 10000000 100000 -1 100Ns TTY_DIALTYPE 0 0 0 255 Bit-Encode TTY_SPEED 15 15 1 17 Special TTY_RSPEED 0 0 0 17 Special TTY_PARITY 24 24 0 255 Special TTY_BUF 80 80 0 511 Characters TTY_DEFCHAR 402657952 402657952 0 -1 Bit-Encode TTY_DEFCHAR2 4098 4098 0 -1 Bit-Encode TTY_TYPAHDSZ 78 78 0 32767 Bytes TTY_ALTYPAHD 200 200 0 32767 Bytes TTY_ALTALARM 64 64 0 -1 Bytes TTY_DMASIZE 64 64 0 -1 Bytes DTTY_PROT 65520 65520 0 -1 Protection TTY_OWNER 65540 65540 0 -1 UIC TTY_CLASSNAME “TT” “TT” “AA” “ZZ” Ascii TTY_SILOTIME 8 8 0 255 Ms TTY_TIMEOUT 900 900 0 -1 Seconds DTTY_AUTOCHAR 7 7 0 255 Character DSYSGEN> EXIT

Change settings to 1024:

As TTY_TYPAHDSZ and TTY_ALTYPAHD are NOT marked with “D” in the “Dynamic” column, a modified value cannot take effect while the system is running. A reboot of the computer will be necessary.

$ edit modparams.dat

Insert the following lines at the end of the file:

TTY_TYPAHDSZ=1024

TTY_ALTYPAHD=1024

Save the file. Then

$ @sys$update:autogen getdata reboot nofeedback

94

Appendix D:Troubleshooting

It may happen, although you configured everything correctly, that the interface does not connect to the Contronic system. Your Interface output file might look like this:

. . .

Thu Aug 28 10:10:18 1997

HBCXPI-uni_dhi> -W-: Connect Error – (file handle), status: -2

MSR> I/O Timeout

Thu Aug 28 10:10:21 1997 Synchronize (line check) failed

Thu Aug 28 10:10:23 1997


MSR> I/O Timeout


Thu Aug 28 10:10:29 1997


MSR> I/O Timeout


Thu Aug 28 10:10:34 1997


MSR> I/O Timeout


Thu Aug 28 10:10:39 1997


MSR> I/O Timeout


Thu Aug 28 10:10:45 1997


MSR> I/O Timeout

. . .

In this case, consider resetting the Contronic station. Consult your local H&B specialist who can do this for you.


Appendix E:Interface Control Program

NT

The name of the Interface Control Program is cppi.exe.

The Interface Control Program can be used to:

Shut down the interface

Change the debug level while the interface is running, mainly used for troubleshooting purposes by forcing more messages to go into the interface log file (usually done on OSIsoft TechSupport recommendation only)

Monitor interface operation

Please note that the Interface Control Program is limited to serial ports COM1 … COM4.

The Interface Control Program is invoked by executing cppi.bat, either from a Command Window or by double-clicking on cppi.bat in the Windows Explorer. The contents of cppi.bat are:

cppi hubcx

Upon executing cppi.bat the following window appears:


‘Connect to Interface’ TabIf the PI-ConLink X Interface is running, when selecting the radio button next to the COM port the interface is using and clicking ‘Apply’, the picture should look as follows:

In order to change the Debug level, click on the spin buttons next to the ‘Debug Level’ text box. The changed number goes into effect immediately and is reflected in the ‘Status’ text above.


You can shut down the interface by clicking the ‘INTERFACE SHUTDOWN’ button. In the ‘Status’ line you will first see “Shutdown in progress”, then “Disconnected”. Press ‘Close’ to exit the Control Program.


Appendix E: Interface Control Program

‘I/O Monitor’ TabThis window lets you display some statistical information. You can choose to update the information on a regular basis, by specifying an Update Frequency, or you can update the screen manually.

100

‘Message Log’ TabIn the ‘Message Log’ window, you can view the current interface log file contents. Toggle ‘Display Messages’ and ‘Scroll’ ON or OFF according to your needs.

VMS

The name of the Interface Control Program is PISysExe:hubcxcp.exe.

The Interface Control Program can be used to

Shut down the interface

Change the debug level while the interface is running, mainly used for troubleshooting purposes by forcing more messages to go into the interface log file (usually done on OSIsoft TechSupport recommendation only)

The Interface Control Program is invoked by

$ run PISysExe:hubcxcp

The following commands and command qualifiers are supported (Information can be retrieved via the HELP command):


H&B Contronic P/E-K to PI Interface (via ConLink X)

Control Program

Version 1.05

HUBCXpi>help

Information available:

EXIT SET SHUTDOWN

Topic? Exit

EXIT


Appendix E: Interface Control Program

EXIT the Control Program.

Topic? Set

SET

The current version allows you to set the DEBUG level.

Additional information available:

DEBUG

SET Subtopic? Debug

SET

DEBUG

Sets the interface to DEBUG mode. Additional information is sent to

the interface output file


Command_Qualifiers

/OFF /ON /LEVEL=n

SET DEBUG Subtopic? /off

SET

DEBUG

/OFF

Disables DEBUG mode. This is the default mode.

SET DEBUG Subtopic? /on

SET

DEBUG

/ON

Enables DEBUG mode. The DEBUG level must be specified in addition.

SET DEBUG Subtopic? /level

SET

DEBUG

/LEVEL=n

Specifies the DEBUG level. The amount of additional output depends on n.

Higher values for n result in more interface output.

Format:

SET DEBUG /ON /LEVEL=n

SET DEBUG Subtopic?

SET Subtopic?

Topic? Shutdown

SHUTDOWN

Performs an orderly SHUTDOWN for the interface.

Note: Do not use the VMS STOP command.


Command_Qualifiers

/TIMEOUT=n /ID=n

SHUTDOWN Subtopic? /timeout

SHUTDOWN

/TIMEOUT=n

Time (in seconds) to wait before the interface will be shut down.

The default value for n is 30.

Format:

102

SHUTDOWN /TIMEOUT=20

SHUTDOWN Subtopic? /id

SHUTDOWN

/ID=n

Identification of the interface instance to shut down (interface number)

Format:

SHUTDOWN /ID=2

SHUTDOWN Subtopic?

Topic?

HUBCXpi>exit

Example for Increasing the Debug Level and Interface Shutdown


H&B Contronic P/E-K to PI Interface (via ConLink X)

Control Program

Version 1.05

HUBCXpi>set debug/on/level=5

HUBCXpi>shutdown/id=1

Interface HBCXPI-1 is running . . .

SHUTDOWN OK for Interface HBCXPI-1

HUBCXpi>exit


Revision History

Date Author Comments

Aug 1996 BB Written

May 1998 KP Added information about Failover

Nov 1998 KP Revised, minor modification in description of /baud

Nov 1998 KP Supported features: Correct PINet to “yes”Replaced “Contronic P” with “Contronic” in a couple of places because the information is valid for Contronic E-K as well

Jan 1999 KP Revised after test of failover functionality

Mar 1999 KP Clarified failover concept

25-Jul-03 KP Re-written according to Interface Manual Skeleton Version 1.11.

07-Apr-04 KP Added description of PI-APS-specific command line parameters

08-Apr-04 CG Version 2.0.0.7 Rev A: reformatted; made some clarifications; changed some headings; fixed section headers & footers

19-Sep-06 Janelle Version 2.0.0.7 Rev B: updated Supported Features table to include APS connector; updated How to Contact Us page

17-Dec-07 Janelle Version 2.0.0.7 Rev C: turned off track changes, made final


Documents

PI_hbcxpi