Uniint End User

Bailey semAPI
Interface to the PI System

NT Version 1.3.6

VMS Version 1.2 – 2.1.2

Document Revision F

1

UniInt End-User Interface to the PI System

How to Contact Us

Phone / (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web /
Mail / OSIsoft, Inc.
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721
OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand

Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI_basemapi.doc

 1997- 2004 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577

1

UniInt End-User Interface to the PI System

Table of Contents

Introduction

Reference Manuals

Supported Features

Diagram of Hardware Connection

Principles of Operation

Installation Checklist

NT

VMS

Interface Installation on NT

Naming Conventions and Requirements

Interface Directories

The PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing the Interface as an NT Service

Installing the Interface Service with PI-Interface Configuration Utility

Installing the Interface Service Manually

Interface Installation on VMS

Naming Conventions and Requirements

Interface Installation Procedure

Testing Connection to ICI

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Scan

SourceTag

Shutdown

Output Points

Trigger Method 1 (Recommended)

Trigger Method 2

Bailey Point Types

Supported Input Point Types (Bailey Data to PI)

Output Point Types (PI Data to Bailey)

Detailed Description of Bailey Point Types

Tag Configuration from Bailey Database

Performance Point Configuration

I/O Rate Tag Configuration

Monitoring I/O Rates on the Interface Node

Configuring the PI Point on the PI Server

Configuring on the Interface Node

Startup Command File

PI-ICU Control

Behavior

Data Retrieval

Failover

Debug

Data Handling

Additional Arguments

Command-line Parameters

Interface Node Clock

NT

VMS

Security

NT

VMS

Starting / Stopping the Interface on NT

Starting Interface as a Service

Stopping Interface Running as a Service

Starting / Stopping the Interface on VMS

Starting a Detached Process

Stopping

Buffering

Restrictions and Other Information

Exclusive Control of ICU Device

Interface and semAPI Version Compatibility

OSM01 Not Recommended

semAPI 1.2 Disconnection Problems

Timeout in the Middle of the Connect Point Command

Adaptec 2940 U SCSI, 50-pin Card with the ICI03

Install the semAPI Device Driver as a Service

Invalid Security Device Present

Appendix A: Error and Informational Messages

Message Logs

Messages

System Errors and PI Errors

Revision History

1

Bailey semAPI Interface to the PI System1

Introduction

The PI-Bailey semAPI interface provides bi-directional data transfer between a PI system and a Bailey Infi90 instrument system. The interface runs on Windows NT-Intel PC, DEC VAX and DEC Alpha computers.

This interface was developed to take advantage of Bailey's semAPI library. The semAPI software handles all of the Bailey communications protocol and thereby makes it possible for the PI interface to communicate to Bailey ICI modules via a variety of transport methods (serial, Ethernet, and SCSI).

Note:Currently, interface version 1.3 and greater is compatible with semAPI version 2.0 and greater. Interface version 1.2 is compatible with semAPI version 1.2. For version compatibility and other semAPI issues, see the restriction section at the end of the manual.

Communication using the semAPI software requires that the customer purchase the Bailey semAPI software and computer interface module as well as the PI interface software.

The interface works with the following Bailey computer interface modules:

• INICI03, INFI-NET to Computer Interface.
• HNCC, Harmony Network Communications Coupler

The INICI03 supports serial and SCSI connection to the host computer. The module supports a maximum of 30,000 points. Each instance of the interface connects to one computer interface module.

Reference Manuals

OSIsoft

• UniInt3x End User Document
• PI Data Archive Manual
• PI-API Installation Instructions

Vendor

• SemAPI Instruction Manual
• Function Code Application Manual

Supported Features

Feature / Support
Part Number / PI-IN-BA-SEMAP-AXP
PI-IN-BA-SEMAP-NTI
PI-IN-BA-SEMAP-VAX
Platforms / VMS/Alpha VMS /
NTI (4.0 / 2000)
PI Point Types / PI 3: Float32 / Float16 / Digital / Int16 / Int32
PI 2: R / I / D
Sub-second Timestamps / No
Sub-second Scan Classes / No
Automatically Incorporates PI Point Attribute Changes / Yes
*Exception Reporting / Done by Bailey System
Outputs from PI / Yes
Inputs to PI: Scan-based / Unsolicited / Event Tags / Unsolicited
Maximum Point Count / 30,000
Uses PI-SDK / No
PINet to PI 3 String Support / Yes
* Source of Timestamps / PI server
History Recovery / No
* Failover / Yes
* Uniint-based / Yes
Vendor Software Required on PI Interface Node / No
* Vendor Software Required on Foreign Device / Yes
* Vendor Hardware Required / Yes
Additional PI Software Included with Interface / No

* See paragraphs below for further explanation.

Exception Reporting

The Bailey System sends data to the PI interface by exception. Hence, by default, the interface does not apply the PI tag’s exception reporting on top of the Bailey events.

Source of Timestamps

The interface keeps tracks of the current time of the PI server. It applies that time to the timestamp of the exception-based event sent from Bailey.

Failover

The interface supports failover to provide redundant data collection on both VMS platform and on Windows NT platform. The failover setup involves two instances of the interface, one in primary data collection mode and one in secondary or standby data collection mode. Each interface communicates to a separate ICI module. The secondary interface would monitor the ICI module status of the primary interface. If the primary ICI module is not in execute mode, the secondary interface will start collecting data. When the primary ICI module comes back on-line, the secondary interface would go back to standby mode.

Since the failover mechanism depends on the ICI module, you should not set the ICI watch dog timer to 0 for the primary interface. Otherwise, the ICI module will continue to be in execute mode even if the primary interface stops communicating to the ICI module.

When installing the interface in failover setup, you should test the failover configuration by stopping the primary interface program and verifying that the secondary interface picks up data collection. If the secondary interface cannot read the module status of the primary ICI module within five minutes of the interface startup, the interface program will terminate, assuming the PCU address provided by the command file is incorrect. This safety check is designed to avoid having both instances of the interface collecting data at the same time.

UniInt-based

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

The UniInt End User Document is a supplement to this manual.

Vendor Software Required

The interface needs the Bailey semAPI Runtime, Supervisory Control, or Development Kit to be installed on the interface node.

Vendor Hardware Required

The interface connects to ICI03 via SCSI or serial connection.

Diagram of Hardware Connection

1

Bailey semAPI Interface to the PI System1

Principles of Operation

The PI-Bailey semAPI interface supports the major Bailey point types for reading data from the Bailey Infi90. It also supports data output to the Bailey Infi90 system via the Analog and Digital Report functions.

All data read by the interface come from the Bailey system as exception reports. Bailey generates an exception report whenever the value or the status changes, or when a specific amount of time has elapsed since the last report (exception maximum time). Data is output to Bailey with any change in the related value or the event time in PI.

The most common network topology used by the interface is peer-to-peer. With this approach, the interface process and semAPI software reside on the same computer. The computer is physically connected via serial, SCSI or Ethernet cable to a Bailey communications module, which is connected to the Bailey Infi90 network.

At startup, the interface retrieves all the PI tags for the specified point source and processes only those tags with matching ICI number. The interface builds the tags into a sequential list keyed by list index position.

The interface attempts to initiate communication with the Bailey communications modules via calls to Bailey semAPI libraries. These, in turn, establish a device driver process to talk to the Bailey communications module. The Bailey device driver handles physical and low-level protocol communication.

Via the semAPI call, the interface then establishes the tags in the Bailey communications module point table. After all points are established and connected, the interface enters the data collection phase.

The interface keeps reading exception data from the Bailey communications module until the maximum number of exceptions specified in the interface startup parameters have been reached or ten read exception calls have been made.

The interface checks for output events to be processed. Whenever output tags are triggered within PI, data will be sent to the Bailey system.

If more than two minutes have been passed since the last PI point database check, the interface will check for point database changes. Tags are added, modified, or deleted from the interface if necessary.

When the interface encounters ten consecutive communication errors with the ICI, the interface will attempt to clear the error by going through the error recovery procedure. The error recovery starts with disconnecting from the semAPI. Then the interface goes back to the startup phase of the operation, as described in the beginning of the manual. This auto error recovery feature normally clears problems caused by line noise. However, hardware failure will still require human intervention.

Note: Since the ICI point table can only buffer one exception for each point, it is possible for the interface to miss exception reports for Bailey tags that are changing values too rapidly. For example, if the control engineer has configured an RCM to reset itself after the operator has set the RCM to the ‘on’ state, the PCU module will generate two exception reports within a second. Most likely, the interface will not be able to catch the first exception report before it is over-written by the second exception on the ICI module.

1

Bailey semAPI Interface to the PI System1

Installation Checklist

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

NT

1. Install Bailey semAPI software as per Bailey Document E96-827-1, installation section.
2. Define a logical ICI for each ICI module with the program ICICONF.
3. After configuring the logical ICI, always test the communication to the ICI using the TALK90 program. TALK90 is an important communication trouble shooting tool. If TALK90 is having a problem communicating to the ICI module, the PI interface cannot be expected to function properly. At least execute command 100(connect to ICI) and 19(restart ICI). Other commands to try are 43 (read time) and 84 (establish import point). Command 84 is on the second page of commands.
4. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
5. Verify that the PI-API has been installed.
6. Install the interface.
7. Define digital states for digital tags.
8. Choose a point source. If PI 2 home node, create the point source.
9. Configure PI points.
   Location1 is the interface instance (Use the logical ICI number).
   Location2 for inputs is Loop Number * 256 + PCU Number
   for outputs is the CIU index.
   Location3 for inputs is Module Number
   for outputs is always 1.
   Location4 for inputs is the Block Number
   for outputs is always 1.
   Location5 is the Bailey point type.
   ExDesc uses /BLY=x for extended attributes.
   InstrumentTag is not used.
10. Performance points are not applicable.
11. Configure I/O Rate tag.
12. Use the PI-ICU to edit the startup command file.
13. Set interface node clock.
14. Set up security.
15. Start the interface without buffering.
16. Verify data.
17. Stop interface, start buffering, start interface.

VMS

1. Install Bailey semAPI software as per Bailey Document E96-827-1. Link the programs DEVICE, ICICONF and TALK90. The link procedure will put the executables in the directory defined by ICI$EXE.
2. Define a logical ICI for each ICI module with the program ICICONF. The program will prompt for information about the type of connection between the semAPI software and the Bailey ICI.
   The ICI Network type is the network protocol between the ICI client(the PI interface in this case) and the semAPI software. If the interface is running in the same computer as the semAPI, then use “local” for the network type. The ICI physical properties describe the connection between the ICI module and the semAPI interface. The physical ICI is normally the port name connecting to the ICI module.
3. After configuration of the logical ICI, always test the communication to the ICI using the TALK90 program. TALK90 is an important communication trouble shooting tool. If TALK90 is having problem communicating to the ICI module, the PI interface cannot be expected to function properly. At least execute command 100(connect to ICI) and 19(restart ICI). Other commands to try are 43 (read time) and 84 (establish import point). Command 84 is on the second page of commands.
4. The semAPI installation procedure creates a user account called [ICI]. The [ICI] is created with quota sufficiently large enough to run the semAPI applications. Since the PI interface is normally run under the [system] account, make sure the [system] account quotas are at least as large as those in the [ICI] account, specially the BYTLM, ENQLM, FILLM and PGFLQUO quotas.
5. The PI-Bailey semAPI interface is installed as part of the PI/PINet installation. Install it, if necessary.
6. Define digital states for digital tags.
7. Choose a point source. If PI 2 home node, create the point source.
8. Configure PI points.
   Location1 is the interface instance (Use the logical ICI number).
   Location2 for inputs is Loop Number * 256 + PCU Number
   for outputs is the CIU index.
   Location3 for inputs is Module Number
   for outputs is always 1.
   Location4 for inputs is the Block Number
   for outputs is always 1.
   Location5 is the Bailey point type.
   ExDesc uses /BLY=x for extended attributes.
   InstrumentTag is not used.
9. Performance points are not applicable.
10. Configure I/O Rate tag.
11. Set up security.
12. Start the interface.
13. Verify data.

1

Bailey semAPI Interface to the PI System1

Interface Installation on NT

OSI recommends that interfaces be installed on API nodes instead of directly on the PIServer node. An API node is any node other than the PI Server node where the PIApplication Programming Interface (PI-API) has been installed (see the PIAPIInstallation Instructions manual). With this approach, the PI Server need not compete with interfaces for CPU time. The primary function of the PI Server is to archive data and to service clients that request data.

After the interface has been installed and tested, Bufserv should be enabled on the APInode (once again, see the PI-API Installation Instructions manual). Bufserv is distributed with the PI-API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.

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

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