Simca-Batch On-Line
Interface to the PI System
Version 2.1.2.x
Revision A
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com
OSIsoft Australia • Perth, Australia
OSIsoft Europe GmbH • Altenstadt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoft Canada ULC • Montreal & Calgary, Canada
OSIsoft, LLC 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
OSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil
Copyright: © 2001-2010 OSIsoft, LLC. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 04/2010
Table of Contents
Terminology v
Interface Specific Terms v
General Terms v
Chapter 1. Introduction 1
A Terminology Note 1
Reference Manuals 2
Supported Features 2
Chapter 2. Principles of Operation 5
Modified Point Names 5
Chapter 3. Installation Checklist 7
Chapter 4. Interface Installation 9
Interface Directories 9
PIHOME Directory Tree 9
PIHOME64 Directory Tree 9
Interface Installation Directory 10
Interface Installation Procedure 10
Chapter 5. Startup Parameters 11
PISimBOL.ini Parameters 11
PISimBatchOL_FilterFile.ini Parameters 11
Sample PISimBOL.ini File 13
Sample Filter.ini File 13
Chapter 6. Interface Node Clock 15
Windows 15
Chapter 7. Security 17
Windows 17
Chapter 8. Buffering 19
Chapter 9. Interface Diagnostics Configuration 21
Scan Class Performance Points 21
Performance Counters Points 21
Interface Health Monitoring Points 21
I/O Rate Point 21
Interface Status Point 21
Appendix A. Error and Informational Messages 23
Message Logs 23
Messages 23
System Errors and PI Errors 24
Appendix B. Technical Support and Resources 25
Before You Call or Write for Help 25
Help Desk and Telephone Support 25
Search Support 26
Email-based Technical Support 26
Online Technical Support 26
Remote Access 27
On-site Service 27
Knowledge Center 27
Upgrades 27
Appendix C. Revision History 29
Simca-Batch On-Line Interface to the PI System v
Terminology
To understand this interface manual, you should be familiar with the terminology used in this document.
Interface Specific Terms
Node
In Umetrics terminology a Node is a PI Unit. In the Simca system a node will return batches that are related to the node or PIUnit. A virtual or filter node is a node that will return batches that relate to a query.
General Terms
Buffering
Buffering refers to an Interface Node’s ability to store temporarily the data that interfaces collect and to forward these data to the appropriate PI Servers.
N-Way Buffering
If you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering to multiple PI Server however it does not guarantee identical archive records since point compressions specs could be different between PI Servers. With this in mind, OSIsoft recommends that you run PIBufss instead.)
ICU
ICU refers to the PI Interface Configuration Utility. The ICU is the primary application that you use to configure PI interface programs. You must install the ICU on the same computer on which an interface runs. A single copy of the ICU manages all of the interfaces on a particular computer.
You can configure an interface by editing a startup command file. However, OSIsoft discourages this approach. Instead, OSIsoft strongly recommends that you use the ICU for interface management tasks.
ICU Control
An ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common to all interfaces, an ICU Control implements interface-specific behavior. Most PI interfaces have an associated ICU Control.
Interface Node
An Interface Node is a computer on which
· the PI API and/or PI SDK are installed, and
· PI Server programs are not installed.
PI API
The PI API is a library of functions that allow applications to communicate and exchange data with the PI Server. All PI interfaces use the PI API.
PI Collective
A PI Collective is two or more replicated PI Servers that collect data concurrently. Collectives are part of the High Availability environment. When the primary PI Server in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI clients.
PIHOME
PIHOME refers to the directory that is the common location for PI 32-bit client applications.
On a 32-bit Operating system
A typical PIHOME is C:\Program Files\PIPC.
On a 64-Bit Operating system
A typical PIHOME is C:\Program Files (x86)\PIPC.
PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME.
For example, files for the Modbus Ethernet Interface are in C:\ProgramFiles\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory. For example, ICU files in [PIHOME]\ICU.
PIHOME64
PIHOME64 will be found only on a 64-bit Operating System and refers to the directory that is the common location for PI 64-bit client applications.
A typical PIHOME64 is C:\Program File\PIPC.
PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME64.
For example, files for a 64-bit Modbus Ethernet Interface would be found in C:\ProgramFiles\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory. For example, ICU files in [PIHOME64]\ICU.
PI SDK
The PI SDK is a library of functions that allow applications to communicate and exchange data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of the PI SDK.
PI Server Node
A PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node.
PI SMT
PI SMT refers to PI System Management Tools. PI SMT is the program that you use for configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs on either a PI Server Node or a PI Interface Node.
Pipc.log
The pipc.log file is the file to which OSIsoft applications write informational and error messages. When a PI interface runs, it writes to the pipc.log file. The ICU allows easy access to the pipc.log.
Point
The PI point is the basic building block for controlling data flow to and from the PI Server. For a given timestamp, a PI point holds a single value.
A PI point does not necessarily correspond to a “point” on the foreign device. For example, a single “point” on the foreign device can consist of a set point, a process value, an alarm limit, and a discrete value. These four pieces of information require four separate PI points.
Service
A Service is a Windows program that runs without user interaction. A Service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.
The ICU allows you to configure a PI interface to run as a Service.
Tag (Input Tag and Output Tag)
The tag attribute of a PI point is the name of the PI point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms “tag” and “point” interchangeably.
Interfaces read values from a device and write these values to an Input Tag. Interfaces use an Output Tag to write a value to the device.
Simca-Batch On-Line Interface to the PI System 27
Chapter 1. Introduction
The PI SimBatchOL Interface provides connectivity between one or more PI servers and a single Simca-Batch On-line Data Server. The PI SimBatchOL Interface comes in two flavors a Windows 32-bit DLL or a Windows 64-bit DLL which satisfies the Simca-Batch On-Line External Database API requirements. The file PISimBatchOL.dll is for use with SBOL version 3.1.0.1 or greater.
Note: This interface is different from other PI interfaces in that it is the Simca-Batch OnLine which makes calls to the commands contained in the interface dll to exchange data with the PI system.
Note: The value of [PIHOME] variable for the 32-bit interface will depend on whether the interface is being installed on a 32-bit Operating System (C:\ProgramFiles\PIPC) or a 64-bit Operating system (C:\ProgramFiles(x86)\PIPC).
The value of [PIHOME64] variable for the 64-bit interface will be C:\ProgramFiles\PIPC on the 64-bit Operating system.
In this documentation [PIHOME] will be used to represent the value for either [PIHOME] or [PIHOME64]. The value of [PIHOME] is the directory which is the common location for PI client applications.
This interface requires the following software be installed on the same machine as the interface:
· PI SDK version 1.3.4 or greater
The interface is only compatible with PI3 servers.
Both inputs to and outputs from PI are supported. Although the direction of data flow is bi-directional in nature, the primary purpose of this interface is to provide PI data to the Simca-Batch On-Line Server instead of providing external process data to PI.
It will operate with the Module DB and Batch DB of the PI Server 3.3.0 and higher.
A Terminology Note
This document refers to Servers and Points, Umetrics applications refer to Nodes and Tags.
When the Umetrics application refers to Nodes they refer to the Server and PIUnits.
When the Umetrics application refers to Tags they are Points
Reference Manuals
OSIsoft
· PI Server manuals
· PI SDK Installation Instructions
· PI SDK 64 Installation Instructions
Umetrics
· Application Installation Instructions
Supported Features
Feature / Support /Part Number / PI-IN-SIM-BO-NT
PI-IN-SIM-BO-X64
* Platforms / 32-bit Interface / 64-bit Interface
Windows XP
32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / Yes
Windows 2003 Server
32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / Yes
Windows Vista
32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / Yes
Windows 2008
32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / Yes
Windows 2008 R2
64-bit OS / Yes (Emulation Mode) / Yes
Windows 7
32-bit OS / Yes / No
64-bit OS / Yes (Emulation Mode) / Yes
APS Connector / No
Point Builder Utility / No
ICU Control / No
PI Point Types / Float16, Float32, Float64, Int16, Int32, and Digital
Sub-second Timestamps / No
Sub-second Scan Classes / No
Automatically Incorporates PIPoint Attribute Changes / No
Exception Reporting / Only uses snapshot
Outputs from PI / Yes
Inputs to PI: Scan-based / Unsolicited / Event Tags
Supports Questionable Bit / No
Supports Multi-character PointSource / No
Maximum Point Count / No
* Uses PI SDK / Yes
PINet String Support / N/A
* Source of Timestamps / See description below
History Recovery / No
UniInt-based
* Disconnected Startup
* SetDeviceStatus / No
No
No
Failover / No
* Vendor Software Required on PI Interface Node / PINet Node / Yes
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
Additional PI Software Included with Interface / No
Device Point Types / NONE
Serial-Based Interface / No
* See available paragraphs below for further explanation.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating systems and their associated service packs.
Uses PI SDK
The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface specifically makes PI SDK calls to create PI Points, access PI Module Database, PI Batch Database, and / or Questionable Bits.
The 32-bit version of the PISIMBOL Interface installs 32-bit PI SDK.
The 64-bit version of the PISIMBOL Interface installs both the 32 and 64 bit versions of the PISDK; this is done to utilize the 32-bit AboutPI-SDK.exe on the 64-bit Operating System installations.
Source of Timestamps
The client application provides timestamps for input data. PI provides timestamps for output data, but the client application may or may not use them.
Vendor Software Required
This interface is implemented as a DLL and thus loaded by the client application at run-time.
Simca-Batch On-Line Interface to the PI System 27
Chapter 2. Principles of Operation
This Interface performs as an adapter between the requirements of the Umetrics Simca-Batch On-Line External Database API and the PI SDK.
It permits a Umetrics client application to:
· Query for information about the connected server and the available analog and digital points on the server.
· Read and write point snapshot data for multiple analog and digital points to and from one PI3 server.
· Read archive data for multiple analog and digital points from one PI3 server.
· Read batch data from the PI Batch DB.
Modified Point Names
Another restriction of Umetrics applications is that the colon character “:” is reserved and cannot be used in server or point names. Umetrics Simca-Batch On-Line automatically replaces colon characters “:” with the period character “.”. For instance, the point name “BA:Active.1” would display in the Umetrics Simca-Batch On-Line as “BA.ACTIVE.1”.
Thus, any point name will appear within the Umetrics application with colons replaced by periods.
It is unlikely, but possible, that these conversions result in two or more points having identical names and it will be necessary to make point names unique for correct operation.