PI Batch Generator (PIBaGen)Interface to the PI System
Version 2.0.5.1
Revision A
Copyright © 2000-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
- Perth, Australia
Auckland, New Zealand
- Altenstadt,Germany
- Singapore
- Montreal, Canada
- Calgary, Canada
- Shanghai, People’s Republic of China
- Tokyo, Japan
- Mexico City, Mexico
- 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 I(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Table of Contents
Terminology
Introduction
Reference Manuals
Supported Features
Data Flow Diagram
Principles of Operation
Interface Configuration
PIUnit configuration
PIBatch configuration
PISubBatch Configuration
Recovery Option
Migrating the Configuration from Version 1.x to 2.x
Installation Checklist
Data Collection Steps
Verify PI SDK Version
Interface Installation
Naming Conventions and Requirements
Interface Directories
The PIHOME Directory Tree
Interface Installation Directory
Interface Installation Procedure
Installing Interface as a Windows Service
Installing Interface Service Manually
PI Batch Generator Plug-in for SMT Installation
Run the Batch Generator Plug-In
Interface Configuration
Configuration Module Name
Interface Debug Messages
Analysis Delay
PIBaGen Status Tag
Retry Timeout
Maximum events in EventPipe
Maximum Stop Time
Add PIModules and PIUnits
PIUnitBatch Configuration
Active Point (Required)
ActivePoint Behavior
Step
Pulse
Continuous
Strings Indicating Zeroth State
Unit Batch ID Point (Optional)
Product Name Point (Optional)
Procedure Name Point (Optional)
Evaluation Delay
Recovery Options
Recovery Time
PIUnit Debug Messages
PIBatch Configuration
PIBatch Index Point (Optional)
PIBatch Search Time
PIBatch Product Point (Optional)
PIBatch Recipe Point (Optional)
PISubBatch Configuration
Add New SubBatch
SubBatch Active Point (Required)
ActivePoint Behavior
Step
Pulse
Continuous
Strings Indicating Zeroth State
SubBatch Name
Use ActivePoint Value
Use SubBatch Title
Use this PI Point Value
PIHeading Set
Register/Unregister PIUnits
Migrate PIBaGen 1.x PIUnits to PIBaGen 2.x PIUnits
Startup Command File
Command-line Parameters
Sample PIBaGen.bat File
Security
Windows
Starting / Stopping the Interface on Windows
Starting Interface as a Service
Stopping Interface Running as a Service
Starting Interface Interactively
Stopping Interface Running Interactively
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 Logs
Messages
System Errors and PI Errors
Appendix B: Migration from PIBaGen 1.x to PIBaGen 2.x.x.x
Migration Using ‘Migration Utility’
Migrating PIUnits Manually
Migrating PIUnits without SubBatches
Migrating PIUnits with SubBatches
Appendix C: Running PIBaGen Remotely
Appendix D: Backfilling Batch Data
Revision History
PI Batch Generator (PIBaGen) Interface to the PI System1
Terminology
In order 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 in order 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.
PI Batch Generator (PIBaGen) Interface to the PI System1
Introduction
The PI Batch Generator Interface (PIBaGen) collects data from the PI Server (fromthe PI Data Archive and the PI Module Database), generates batch data and writes the batch data to the PIServer in the PI Batch Database. PIBaGen is used when there is no native interface to generate and store batch data in the PI System. PIBaGen automatically generates PIUnitBatches, PIBatches and PISubBatchesfor each PIUnit[1]that is configured and registered. Thegenerated batch information can be accessed using tools like PI BatchView and PI Batch Database Editor.This interface is not UniInt based and does not support any Failover.It only populates the PI Batch Database based on PI Events and does populates only one PI Point which represents the status of the interface.
This interface can connect only to the primary node within a PI Server Collective. The connection is made with “Required Primary” option meaning that the connection will not failover to a secondary node. It is not possible to run this version of this interface against a secondary node. It is also not possible to run this version of the interface on the secondary node even if it is meant to connect to the primary node.
CAUTION:This manual is for PIBaGen 2.0.4.0 release only. Although this release is capable of running from a remote node, it is HIGHLY RECOMMENDED to run the interface only on the PI Server node. If run remotely, there is a potential for lost batch data. Please read Appendix C: Running PIBaGen Remotelyfor details.
DO NOT run multiple copies of the interface against the same PI Server. Since both copies will be attempting to create batch data on the same units, the results are unpredictable. It really depends on which copy of the interface will be able to create a batch object first on the server. It is unpredictable to find out which copy will be the first one.
For compatibility with PIBaGen 1.x please read Appendix B: Migration from PIBaGen 1.x to PIBaGen 2.x.x.x. PISubBatch configuration for PIBaGen 1.x is not compatible with PISubBatch configuration for PIBaGen 2.0. The PIUnits monitored by PIBaGen 1.x interface need to be migrated for PIBaGen 2.x to monitor those PIUnits. A migration utility is provided with the Batch Generator Plug-in for SMT.
A PIUnit represents a piece of equipment in which a product is processed in batches.The PIAliases of the PIUnit define the PIPoints associated with the equipment. Each time a product is processed through a PIUnit, a PIUnitBatch is created.Since there can be only one batch processed in a piece of equipment at any time, there can be only one PIUnitBatch associated with a PIUnit at any time.
A PIUnitBatch is the data object that encapsulates one ISA S88 concept of a batch. Here is the definition from S88:
“The material that is being produced or that has been produced by a single execution of a batch process.”
PIBaGen recognizes the start and end of the processing in a PIUnit, and therefore the start and end of the PIUnitBatch, by changes in values of a PI Point known as “Active Point.”Starting a PIUnitBatch includes writing the start time and other properties of PIUnitBatch likeBatch ID, procedure name, product name etc., to the PI Batch Database. PIBaGen optionally also adds the PIUnitBatch to the collection of PIUnitBatches under an object called PIBatch. The PIBatch encapsulates the following ISA S88 batch definition:
“An Entity that represents the production of a material at any point in the process.”
A PIBatch is used to record the production of a specific “Batch”; in practice this usually involves one or more PIUnitBatches in one or more PIUnits (one or more pieces of equipment). A PIBatch allows collecting related PIUnitBatches. All the PIBatches and properties associated with PIBatches,like Product Name, Batch Recipe, etc., are stored in the PI Batch Database.
The PISubBatch information is also written to the PI Batch Database by the PIBaGen interface. A PISubBatch is a definable portion of a PIUnitBatchand is always associated with a PIUnitBatch. The start and end time for each of these definable portions is determined by a separate Active Point called “SubBatch Active Point.”Examples of S88 Sub-batches are Operationsand Phases. Every PISubBatch has a name, a PIHeading and a collection of PISubBatches associated with it. The PISubBatch collection allows for a hierarchy of PISubBatches.
Specifying the PIPoints for Active Points and all other properties of PIBatches, PIUnitBatches and PISubBatches is called the “PIUnit Configuration.”PIUnit configurationis stored as PIAliases and PIPropertiesin the PI Module Database. The creation and configuration of the PIUnit is done using the PIBatch Generator Plug-in for PI SMT (SMT version 3.1.2.2 or higher and plug-in version 3.1.2.3 or higher).
PIBaGen can run on the PI Severor on a remote machine (not recommended for this version; read the section on “Running the Interface Remotely” for details) and works with the PI Module Database SDK and PI Batch Database SDK.
Reference Manuals
OSIsoft
All OSIsoft Manuals and Help files are available in the Download Center.
- PI Server Manuals, including:
PI Server Installation Guide for information on installation of the PI Batch Database and PIBaGen (if installed along with the PI Server installation)
Introduction to PI Server System Management for introductory information.
PI Server System Management Guide, for information on Batch Database Security.
Auditing the PI Server for information on logging Batch Database and SDK object changes
- PI SDK User Manual and Help file, for information on PI Batch objects and programmatically writing or editing batches and on the PI Module Database.
- PI System Management Tools (PI SMT) online Help files, for information on using the PI Batch Generator plug-in and Batch Database plug-in
- Batch Database Support of the PI Batch Subsystem, for information how the PI Batch Subsystem data can be supported through PI Batch Database and PI SDK, the impact on existing batch applications, and for techniques to move to the PI Batch Database.
- PI BatchView User Manual, for information on viewing batches using the BatchView software.
- Batch and Event Framing for Process Analysis – Course Materials
Supported Features
Feature / Support* Platforms / NTI (2000SP3 & SP4, XP, 2003, Vista and 2008 Server)
APS Connector / No
Point Builder Utility / No
ICU Control / No
PI Point Types / Populates only one string type PIPoint
Sub-second Timestamps / Yes
Sub-second Scan Classes / No
Automatically Incorporates PIPoint Attribute Changes / Not Applicable
Exception Reporting / No
Outputs from PI / No
Inputs to PI: Scan-based / Unsolicited / Event Tags / Event Based Batch Data Generation
Supports Questionable Bit / No
Supports Multi-character PointSource / PointSource Not Required
Maximum Point Count / Not Applicable
* Uses PI SDK / Yes
PINet String Support / No
* Source of Timestamps / PI Event Timestamp
* History Recovery / Yes
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / No
No
Yes
* Failover / No
* Vendor Software Required on PI Interface Node / PINet Node / No
* Vendor Software Required on Foreign Device / No
* Vendor Hardware Required / No
* Additional PI Software Included with Interface / Yes
* Device Point Types / Not Applicable
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.
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 access PIPoints, PI Module Database and PI Batch Database.
Source of Timestamps
The source for the timestamp is the PI Event timestamp. The events that trigger batch data are coming from the PI Server. Those events carry their own timestamp. That timestamp is determined by the interface that collects data for that PIPoint.
History Recovery
The interface is capable of history recovery. History recovery is based on the archive events and the recovery options set through the Batch Generator Plug-in.
Health Tags
Although this interface is not UniInt based, it does have some support for health tags. The health tags it supports are DeviceStatus with ExDesc = [UI_DEVSTAT] and HeartBeat with ExDesc= [UI_HEARTBEAT]. These two tags will be created on the PIServer only if they do not exist. The heartbeat tag is the primary tag used to determine if the interface is running. If the value of the heartbeat tag is updating, then the interface is running. The update interval is 1 second. The value written to the heartbeat tag increments from a value starting at 1, increments to a value of 15 and then restarts at 1. The heartbeat tag will stop updating if the interface is shut down or if the interface is in a deadlock situation.
SetDeviceStatus
The device status tag stores communication information about the interface. This tag will be evaluated only while the heartbeat tag is updating. The device status tag is a string type PI point. During normal shutdown of the interface, the string text of “4 | Intf Shutdown” will be written to this tag.
The update values and meaning of this tag are as follows.
- “Good”– This means that the interface is able to connect to all devices for the given tag configuration of the interface. A value of “Good” does not mean that all tags are receiving good values, but it is a good indication that there are no hardware or network problems.
- “1 | Starting”– The interface will remain in this status until it has successfully collected data from its first scan. Interfaces that collect data infrequently may stay in this status for a long time.
- “4 | Intf Shutdown”– the interface is shutting down and going offline.
- “5|Retrying”– Retrying PI Server Connection. The PI Server is offline or down. Retrying the PI Server connection.
- “5|MDB Unavailable”– Module database unavailable to write. PI Server is on line but unable to write to the module database. The Server may have failed over or is being backed up or there is another problem. The interface will recheck every 30 seconds to see if this problem is resolved.
- “5|Server is in Backup mode”– Server in Backup mode and cannot insert data. Generic Requested Item was Not Found. The PI Server might be in a backup mode. The interface will recheck every 30 seconds to see if this problem is resolved.
Additional PI Software