Simca-Batch On-Line
Interface to the PI System

Version 2.1.2.0
Revision A

Copyright © 2001-2009 OSIsoft, Inc.

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


Houston, TX
Johnson City, TN
Longview, TX
Mayfield Heights, OH
Philadelphia, PA
Phoenix, AZ
Savannah, GA
Yardley, PA
/ OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSIsoft Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
Calgary, 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
OSIsoft do Brasil Sistemas Ltda.
Sao Paulo, Brazil
Sales Outlets/Distributors
Middle East/North Africa
Republic of South Africa
Russia/Central Asia / South America/Caribbean
Southeast Asia
South KoreaTaiwan

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, Inc.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, PI Datalink, IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI ManualLogger, PI ProfileView, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, Inc. All other trademarks or trade names used herein are the property of their respective owners.

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

Simca-Batch On-Line Interface to the PI System1

Table of Contents

Terminology

Introduction

A Terminology Note

Reference Manuals

Supported Features

Principles of Operation

Modified Point Names

Installation Checklist

Interface Installation

Interface Directories

PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

PISBOL.ini Parameters

PISimBatchOL_FilterFile.ini Parameters

Digital States

Interface Node Clock

Security

Buffering

Interface Diagnostics Configuration

Scan Class Performance Points

Performance Counters Points

Interface Health Monitoring Points

I/O Rate Point

Interface Status Point

Appendix A: Error and Informational Messages

Message Log

Messages

Appendix B: PI SDK Options

Appendix C: Version 1.x.x.x

Introduction

A Terminology Note

Reference Manuals

Supported Features

Principles of Operation

Tags and Batch Ids

Truncated Server and Point Names

Modified Server and Point Names

Installation Checklist

Interface Installation

Interface Directories

Interface Installation Procedure

PISBOL.ini Parameters

Error and Informational Messages

Message Logs

Debug Messages

Error and Informational Messages

Revision History

Simca-Batch On-Line Interface to the PI System1

Terminology

To understand this interface manual, you should be familiar with the terminology used in this document.

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 and run 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 and run 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 client applications. A typical PIHOME is C:\Program Files\PIPC. PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME. For example, files for the Modbus Ethernet Interface are in C:\Program Files\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME directory. For example, ICU files in [PIHOME]\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. While 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 System1

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 consists of a Windows 32-bit DLL which satisfies the Simca-Batch On-Line External Database API requirements. The file PISimBatchOL.dll is for version 2.x.x.x of this interface and will only work with SBOL version 3.1.0.1 or greater. The file simapi.dll is for version 1.x.x.x of this interface and will work with SBOL versions 1 and 2. See Appendix C for version 1.x.x.x information.

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.

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 API Installationmanual
  • PI SDK Installation Instructions
Umetrics
  • Application Installation Instructions

Supported Features

Feature / Support
Part Number / PI-IN-SIM-BO-NT
* Platforms / Windows 2000 SP3 & SP4 / XP / Server 2003
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 / See below
Supports Questionable Bit / No
Supports Multi-character PointSource / No
Maximum Point Count / None
* Uses PI SDK / Yes
PINet String Support / N/A
* Source of Timestamps / Client Application
* 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
* Serial-Based Interface / No

* See 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.

Inputs to PI: Scan-Based / Unsolicited / Event Tags

The data transfer between the PI server and the Simca-Batch On-Line client application is executed whenever the client application calls the PI SDK functions for data reading and writing.

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.

Uses PI SDK

The PI SDK and the PI API are bundled together and must be installed on each PI Interface node.

Vendor Software Required on PI Interface Node / PINet Node

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 System1

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.

Simca-Batch On-Line Interface to the PI System1

Installation Checklist

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

  1. Verify that the PI SDKhas been installed. A PI Server is also required if the interface is running on the PI Home Node.
  2. Install the interface.
  3. Configure the PISBOL.ini file. A sample PISBOL.ini file called PISBOL.ini.sam is distributed with the interface.

Ensure that the PI servers specified in the PISBOL.ini file are in the Known Servers Table for PI SDK. Otherwise, the PI servers cannot be connected from Umetrics applications. The PI servers can be added to the Known Servers Table via the AboutPI SDK program delivered with the PI SDK. Refer to the PI SDK manual for details. Furthermore, if a password is required for the PI user while connecting to a PI Server with AboutPI SDK, a trust entry for the node running the interface and the PI user should be added to the PITrust table on the PI Server. Refer to the PI Server manual for details about the PITrust table

Simca-Batch On-Line Interface to the PI System1

Interface Installation

OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PIServer node. A PI Interface Node is any node other than the PI Server node where the PIApplication Programming Interface (PI API) has been installed (see the PI APImanual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PIServer is to archive data and to service clients that request data.

Interface Directories

PIHOME Directory Tree

The PIHOME directory tree is defined by the PIHOME entry in the pipc.iniconfiguration file. This pipc.ini file is an ASCII text file, which is located in the %windir%directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\pipc

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

Interface Installation Directory

The interface install kit will automatically install the interface to:

PIHOME\Interfaces\SimBatchOL\

PIHOME is defined in the pipc.ini file.

Interface Installation Procedure

The PI Simca-Batch On-Line Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000and greater operating systems. When running on Windows NT 4.0 systems, the PI Simca-Batch On-Line setup program will install the Windows Installer itself if necessary. To install from CD, run the setup.exe file. To install from the web distribution kit, run SimBatchOL_x.x.x.x.exe

Installing or Upgrading the Interface

If the interface is being installed as a replacement for an earlier version of the interface:

  1. Shut down all Umetrics applications and services using the interface [PISimBatchOL.dll] to be replaced.
  2. Run the SimBatchOL_x.x.x.x.exe file downloaded from the OSIsoft support web site or the setup.exe on the CD. This will place the new version of PISimBatchOL.dll into the interface directory. The copy of the PISBOL.ini file used by the previous interface version should be in the same directory as the new PISimBatchOL.dll.
  3. Restart the Umetrics applications and services.

Install as Part of a Umetrics Product

If the interface is being installed as part of an installation of an Umetrics product:

  1. When the Umetrics installation prompts for the location of PISimBatchOL.dll, provide the location of the interface.
  2. Create a PISBOL.ini file in the same directory that the PISimBatchOL.dll is copied. See the section below for details. A sample PISBOL.ini file called PISBOL.ini.sam is installed by the setup kit.

PISBOL.ini Parameters

The ini file contains multiple lines of the format key=value. There are no spaces permitted either side of “=” character. Key = value is incorrect.

Key / Value
Debug=x / Only the first character of the value is read and this must be a ‘t’, ‘T’ or ‘1’ to turn debugging on. Any other character will result in no debugging information.
Debugging should generally be set to off.
Server=name / The value is the name of one PI server from which to obtain point data.
If server parameter does not exist the default server will be used.
Trim=x / Only the first character of the value is read and this must be a ‘t’, ‘T’ or ‘1’ to turn trim on. Any other character will result in no trimming.
Trim on will trim white space from all string event values. This is used to resolve an issue with white space in batch id events.
batchtimeoffset=x / simapi2_nodeGetBatchTimes call sometime misses a currently executing PIUnitBatch, even though it exist in PI. When a batch end time is before the timeHint simapi2_nodeGetBatchTimes will not find that batch. Configure value so timeHint = timeHint - x to resolve issue. X is the number of seconds to subtract from the time hint for the batch search time. By default 1 second is subtracted.
singleapartment=x / A value of t ( or T or 1 ) will call the PISDK call in a single apartment thread ( STA). The calling routines must be single threaded that is only one single thread will be allowed to call any routines in the interface DLL. A value of f ( or F or 0 ) will call the PISDK in Multiple threaded apartments. The calling routines may be multithreaded. The default value is f ( or F or 0) for multithreaded.
filterfilename=filename.ini / The value of the filename will be the file that the Umetrics system will get the values of the virtual Nodes. These nodes will filter the batch search by product,recipe,procedure.

PISimBatchOL_FilterFile.ini Parameters

This file will have the parameters that allow the SimBOL system to create virtual Nodes. These Virtual Nodes will allow the SimBOL system to filter batch searches for product, recipe,procedure. PIBatchFilter will filter PIBatch searches, PIUnitBatchFilter will filter PIUnitBatch searches.