PI Batch Generator (PIBaGen) Interface to the PI System
Version 2.0.0.9 Rev E How to Contact Us
Phone (510) 297-5800 (main number) (510) 297-5828 (technical support) Fax (510) 352-2349 E-mail [email protected] World Wide http://www.osisoft.com Web Mail OSIsoft OSI Software, Ltd P.O. Box 727 P O Box 8256 San Leandro, CA 94577-0427 Symonds Street USA Auckland 1035 New Zealand
OSI Software GmbH OSI Software, Asia Pte Ltd Hauptstrae 30 152 Beach Road D-63674 Altenstadt 1 #09-06 Gateway East Deutschland Singapore, 189721
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. HP-UX 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_087a3ca6a70557c162a6713cf5df18f7.doc
2000-2004 OSI Software, Inc. All rights reserved 777 Davis Street, Suite 250, San Leandro, CA 94577 Table of Contents
Introduction...... 1 Reference Manuals...... 2 Supported Features...... 2 Data Flow Diagram...... 3
Principles of Operation...... 5
Installation Checklist...... 9
Verify PI-SDK Version...... 11
Interface Installation...... 13 Naming Conventions and Requirements...... 13 Interface Directories...... 13 The PIHOME Directory Tree...... 13 Interface Installation Directory...... 13 Installing the Interface as an NT Service...... 13 Installing the Interface Service Manually...... 14
PIBaGen Configuration Tool Installation...... 15
Run the PIBaGenCfg Tool...... 17
Interface Configuration...... 19 Configuration Module Name...... 19 Interface Debug Messages...... 19
Add PIModules and PIUnits...... 21
PIUnitBatch Configuration...... 23 Active Point (Required)...... 23 ActivePoint Behavior...... 24 Unit Batch ID Point (Optional)...... 24 Product Name Point (Optional)...... 24 Procedure Name Point (Optional)...... 25 Evaluation Delay...... 25 Recovery Options...... 25
PI Batch Generator (PIBaGen) Interface to the PI System iii Table of Contents
Recovery Time...... 26 PIUnit Debug Messages...... 26
PIBatch Configuration...... 27 PIBatch Index Point (Optional)...... 27 PIBatch Search Time...... 28 PIBatch Product Point (Optional)...... 28 PIBatch Recipe Point (Optional)...... 29
PISubBatch Configuration...... 31 Add New SubBatch...... 31 SubBatch Active Point (Required)...... 31 ActivePoint Behavior...... 32 SubBatch Name...... 32 Use ActivePoint Value...... 33 Use SubBatch Title...... 33 Use this PI Point Value...... 33 PIHeading Set...... 33
Register/Unregister PIUnits...... 35
Migration of PIBaGen 1.x PIUnits to PIBaGen 2.x PIUnits...... 37
Startup Command File...... 39 Command-Line Parameters...... 39 Sample PIBaGen.bat File...... 39
Security...... 41
Starting / Stopping the Interface...... 43 Starting Interface as a Service...... 43 Starting Interface Interactively...... 43 Stopping Interface Running as a Service...... 43 Stopping Interface Running Interactively...... 43
Appendix A: Migration from PIBaGen 1.x to PIBaGen 2.x.x.x...... 45 Migration using ‘Migration Utility’...... 45 Migrating the PIUnits manually...... 46 Migration of PIUnits without SubBatches...... 46 PIUnits with SubBatches...... 46
Appendix B: Running the Interface Remotely...... 53
iv Appendix C: Backfilling Batch Data...... 55
Appendix D: Error and Informational Messages...... 57 Message Logs...... 57 Messages...... 57 System Errors and PI Errors...... 69
PI Batch Generator (PIBaGen) Interface to the PI System v Introduction
The PI Batch Generator Interface (PIBaGen) collects data from the PI Server (from the 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 PISubBatches for each PIUnit1 that is configured and registered. The generated batch information can be accessed using tools like PI BatchView and PI Module Database Editor.
CAUTION: This manual is for PIBaGen 2.0.0.9 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 B on “Running the Interface Remotely” for 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 A on ‘Migration from PIBaGen 1.x to PIBaGen 2.0’. 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 PIBaGen Configuration Tool.
A PIUnit represents a piece of equipment in which a product is processed in batches. The PIAliases of the PIUnit define the PI Points 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 like Batch 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:
1 This document will use the term PIUnit to refer to PIModules, with the property “IsPIUnit” set to true. PI Batch Generator (PIBaGen) Interface to the PI System 1 Introduction
“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 PIUnitBatch and 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 Operations and 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 PI Points for Active Points and all other properties of PIBatches, PIUnitBatches and PISubBatches is called the “PIUnit Configuration.” PIUnit configuration is stored as PIAliases and PIProperties in the PI Module Database. The creation and configuration of the PIUnit is done using the PIBaGen Configuration Tool (PIBaGenCfg). PIBaGen can run on the PI Sever or 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 PI Server manuals PI-SDK manual PI-SMT 3 manual PI BaGenCfg Plug-In to the PI-System Management Tools Supported Features
Feature Support Platforms NTI (4.0, 2000, XP) PI Point Types Does not use PI Points Sub-second Timestamps Yes PI Modules Yes Uses PI-SDK Yes * Source of Timestamps PI Event timestamp * History Recovery Yes Failover No UniInt-Based No * See paragraphs below for further explanation.
2 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 PI Point.
History Recovery The interface is capable of history recovery. History recovery is based on the archive events.
Additional PI Software The following PI Software must be installed to configure PIUnits that can be monitored by the interface. The additional software can be installed either on the machine with the interface or on a remote machine. PI-System Management Tools Host version 3.0.0.2 or higher PI Batch Generator Configuration Plug-in to PI-SMT version 2.0.0.9 or higher
Data Flow Diagram e s a b a t a e v i D
h h c c r t a A
B a
t PIBaGen Interface I a P D
I P
PI Module Database
Figure 1: Data flow diagram
PI Batch Generator (PIBaGen) Interface to the PI System 3 Principles of Operation
Unlike most of the interfaces developed by OSIsoft, the PIBaGen interface (PIBaGen) does not require any PI Points, instead, it requires PIUnits. A PIUnit is a specialized PI Module with the IsPIUnit property set to True. PIUnitBatches and PISubBatches can be generated only against a PIUnit. A PIUnit can be created either using the PI Module Database Editor, the PIBaGen Configuration Tool (PIBaGenCfg) or programmatically with the PI-SDK. The PIAliases under the PIUnit define the time series data associated with the PIUnit. The PIUnits and the interface are configured using PIBaGenCfg. The configuration is stored as PIAliases and PIProperties in sub-modules under the PIUnit. The PIBaGen Configuration Tool (PIBaGenCfg) is used to create and configure PIUnits. PIBaGenCfg can also be used for the PIBaGen interface configuration and to view PIModule Database on different PIServers at the same time. A PIUnit is monitored by the PIBaGen interface only if the PIUnit is ‘Registered’. A PIUnit can be Registered or Unregistered at any time using PIBaGenCfg. This is similar to turning the SCAN option ON or OFF for a traditional PI Point. The interface configuration has only two attributes, Configuration Module Name and Interface Debug messages. For each PIUnit configured for the PIBaGen interface, a sub-module with the name specified in Configuration Module Name is created and the PIUnit configuration is stored in this sub-module. Turning debug messages ON will send more interface-specific messages to the log file. Both these attributes are saved in the PI Module Database on the PI Server that the interface services. PIUnit configuration involves PIUnitBatch Configuration, PIBatch Configuration, and PISubBatch Configuration. The PIUnitBatch Configuration means setting up the PI Points and the attributes necessary to create PIUnitBatches. The PI Points should be specified for Active Point, Unit Batch ID, Product Name, and Procedure Name. The events in Active Point indicate the start and stop of a PIUnitBatch and therefore it is necessary for the creation of PIUnitBatches. The other PIUnitBatch attributes that can be configured are Active Point behavior, PIBatch/PIUnitBatch/PISubBatch recovery option, Recovery time, Evaluation Delay for PIUnitBatches, Merge Consecutive and PIUnit- specific Debug messages. There attributes will take default values if they are not specified. The entire configuration information is saved as PIAliases and PIProperties in the Configuration module Name sub-module under the PIUnit. A PIUnitBatch is created at a transition in the Active Point depending on the Active Point Behavior option. If the Step option is selected, the currently running PIUnitBatch (if any) is stopped and a new PIUnitBatch is created at every transition except when the transition is to the 0th state (or value 0 for an integer type or a string indicating 0th state). When the transition is to the 0th state, the running PIUnitBatch is stopped, but a new PIUnitBatch is not created. If the Pulse option is selected, a new PIUnitBatch is created only on a transition from the 0th state. A running PIUnitBatch is stopped only on a transition to the 0th state and any other transitions are ignored. If the Include zeroth state (Continuous) option is selected, PIUnitBatches are generated at every transition, including to and from zeroth state. The Active Point pointtype can be Integer, Digital or String. However, for a String type, the string or strings indicating the zeroth state must be specified. If the Evaluation Delay is specified, the PIUnitBatch is added after the evaluation delay elapses or at the end of the unitbatch, PI Batch Generator (PIBaGen) Interface to the PI System 4 whichever comes first. If the Evaluate at the end of each unitbatch option is selected, the PIUnitBatch is added after the end of unitbatch event is received from the active point. In all these cases, the start time of a PIUnitBatch is still the same as the actual start event time, but the other properties (Unit Batch ID, Product Name, Procedure Name, PIBatch name, PIBatch Product name and PIBatch recipe name) are evaluated at the time when the PIUnitBatch is actually added (PIUnitBatch start time plus evaluation delay). When Merge Consecutive is turned ON, consecutive PIUnitBatches that have the same PIBatch name, PIBatch product name, PIBatch recipe name and UnitBatch ID will be merged. The PIBatch configuration includes specifying PIBatch Index point, PIBatch Product Name point and PIBatch Recipe Name point and PIBatch Search Time. The PIBatch Index point does not act as the active point for PIBatches. In other words, transitions in PIBatch Index point do not generate PIBatches. When a new PIUnitBatch starts and if the PIBatch Index point is defined for that PIUnit, the value of the PIBatch Index point is determined at the PIUnitBatch start time (plus evaluation delay). This value is the name of the PIBatch to which the new PIUnitBatch belongs. If there is no value for the PIBatch Index point at that particular time, then the new PIUnitBatch does not belong to any PIBatch. If there is a value for the PIBatch Index point, then the interface will first search the PI Batch Database for PIBatches with same PIBatch name, PIBatch product name and PIBatch recipe name that are active between (PIUnitBatch start time + Evaluation Delay – PIBatch Search Time) and (PIUnitBatch start time + Evaluation Delay + PIBatch Search Time). If the search results in more than one PIBatch, then the PIUnitBatch is added to the PIBatch selected by the following set of rules. 1. If there is only one running PIBatch in the search period, then that PIBatch is selected irrespective of the start time of the PIBatch. 2. If there is more than one running PIBatch, then the one that has the start time between (PIUnitbatch start time + Evaluation delay - PIBatchSearchTime) and (PIUnitbatch start time + Evaluation delay + PIBatchSearchTime) is selected. If there is more than one running PIBatch in this range, then the one with the latest start time is selected. 3. If there is no running PIBatch but the search results in PIBatches, then the one that has start time between (PIUnitbatch start time + Evaluation delay - PIBatchSearchTime) and (PIUnitbatch start time + Evaluation delay + PIBatchSearchTime) is selected. If there is more than one PIBatch with start time in this range, the one with the latest start time is selected. 4. If there is no running PIBatch but the search results in PIBatches and there is no PIBatch that has start time between (PIUnitbatch start time + Evaluation delay - PIBatchSearchTime) and (PIUnitbatch start time + Evaluation delay + PIBatchSearchTime) then the one that has the latest start time is selected. 5. If no PIBatch is found with the search criteria, then a new PIBatch is added. The PIBatch Search Time can be seen as the approximate duration of the PIBatch to which the PIUnitBatches in this PIUnit belong. A PIBatch ends when all the PIUnitBatches in its PIUnitBatches collection end. It is re-opened if a new running PIUnitBatch is added. The PIBatch configuration is also stored as PIAliases and PIProperties in the Configuration module name sub-module under the PIUnit. The PISubBatch Configuration involves creating the SubBatch hierarchy. The important nomenclature to understand the PISubBatch configuration is defined here.
PI Batch Generator (PIBaGen) Interface to the PI System 5 Principles of Operation
. SubBatch: Represents one item in the SubBatch Hierarchy. Each SubBatch has its own ‘SubBatch Active Point’ which acts as a trigger for PISubBatches. Each SubBatch does not necessarily represent only one PISubBatch. The number of PISubBatches will depend on the ‘SubBatch Active Point’ and the ‘Active Point Behavior’ chosen for that SubBatch. . SubBatch Title: This is the name given to represent a SubBatch in the hierarchy. Two SubBatches at the same level cannot have the same SubBatch Title. . SubBatch Hierarchy: This is the tree-like structure to represent all the SubBatches. Each SubBatch can have only one parent SubBatch but can have many child SubBatches. . SubBatch Level: Represents the depth in the hierarchy where the SubBatch belongs. The first Level is the topmost level and all the SubBatches at the first level do not have a parent SubBatch. Each SubBatch defined in the hierarchy requires a SubBatch Title and SubBatch Active Point. The SubBatch Active Point can be of integer, digital or string PointType. Active Point Behavior option should also be specified. This option behaves exactly as explained above for PIUnitBatch Active Point. A PISubBatch is started if the SubBatch Active Point indicates a start and if the parent PISubBatch (or PIUnitBatch if it is a first level SubBatch) is running. However, a PISubBatch does not end if a parent PISubBatch ends. The end of a PISubBatch is determined either by the SubBatch Active Point or by the end of the PIUnitBatch to which the PISubBatch belongs. The name for the PISubBatch can be simply the SubBatch Title or the value of the active point itself or a separate PI Point can be specified whose value at the start time of the PISubBatch will be used. PISubBatch Configuration also involves setting an optional PIHeading set for the entire SubBatch hierarchy. A PIHeading Set consists of PIHeadings. A PIHeading is a collective name for the PISubBatches at the same level. Therefore, all the PISubBatches at the first level in the hierarchy are referred to by the PIHeading at Level 1 in the PIHeading Set. Recovery of the batch objects -- PIBatches, PIUnitBatches and PISubBatches depends on the Recovery option and Recovery Time. If the Do not recover anything option is selected, then the interface does not recover any of the PIBatch objects. If there is any running PIUnitBatch on that particular PIUnit when the interface is started, then the interface ends that PIUnitBatch, the PIBatch it belongs to and all of its running PISubBatches. If the Recover only PIBatches and PIUnitBatches option is selected, all the PIUnitBatches and the associated PIBatches are recovered but the PISubBatches are not recovered. If the Recover all PIBatch objects is selected, PIBatches, PIUnitBatches and PISubBatches are recovered. During recovery, if there is a running PIUnitBatch, the recovery starts from the start time of that running PIUnitBatch irrespective of the Recovery Time specified. If there is no running PIUnitBatch, the interface searches for PIUnitBatches on the PIUnit up to Recovery Time into the past. If the search finds PIUnitBatches within that period, recovery is done from the end time of the last PIUnitBatch. If there are no PIUnitBatches in the search results, then recovery is done for Recovery Time into the past. If the recovery time is earlier than the primary archive, read Appendix C for details on backfilling data for those PIUnits.
Note: If there is a running PIUnitBatch and if it has PISubBatches (running or not), they are removed and recreated during recovery. This occurs only on the PIUnitBatch that is running and if it has subbatches at the time of recovery. When the interface is running, it
6 monitors the snapshot updates for new events. But during recovery, the interface retrieves data from the archive. Therefore there is a potential for missing PISubBatches if some of the PISubBatch events are not archived. This situation can be avoided by having appropriate settings for compression and exception on the Active Points for the SubBatches. Debugging can be turned ON for individual PIUnits. This is helpful for troubleshooting. Additional messages specific to the PIUnit are sent to the log file if the debugging is turned ON. Since it generates large number of messages, it is not recommended to turn this ON unless it is absolutely necessary. The configuration required for PI Batch Generator Interface 2.x is slightly different from the configuration required for PI Batch Generator Interface 1.x version. For this reason, a migration utility is provided with PIBaGenCfg. This utility can be launched from the toolbar menu of PI Batch Generator Configuration Tool. After selecting the PIUnits to be migrated, the migration utility converts the configuration so that the batch data is generated on those PIUnits just like PIBaGen 1.x was generating batch data with one exception. The recovery done by PIBaGen 1.x interface was only for PIBatches and PIUnitBatches. However, when the PIUnit is migrated, the recovery option is set so that PIBatches, PIUnitBatches and PISubBatches are recovered.
PI Batch Generator (PIBaGen) Interface to the PI System 7 Installation Checklist
For those users who are familiar with PIBaGen, this checklist helps you get the interface running quickly. If you are not familiar with PI interfaces or with the PIBaGen interface, you should return to this section after reading the rest of the manual in detail. 1. Verify that PI-SDK has been installed and it is version 1.3.1 Build 237 or greater. 2. Install the interface and Configuration tool. 3. Run PIBaGen Configuration Tool (PIBaGenCfg) version 2.0.0.9 or higher, which is a plug-in to PI-SMT 3.0. 4. Select a PIServer. Specify the interface configuration on the ‘Interface’ page. The ‘Configuration Module Name’ is the name of the sub-module added under each PIUnit in which the configuration is stored. If the Debug is turned ON, additional interface specific messages will be sent to the log file. 5. Add a PIUnit. A PIUnit is added in two steps. First a PIModule is added and it is then converted to PIUnit. This step can be done only when the ‘Module Database Tree’ view is used for PIBaGenCfg. 6. As part of the ‘PIUnitBatch Configuration’ on the ‘PIUnitBatches’ page, specify the PI Points for ‘Active Point’ (required), Unit Batch ID, Product Name and Procedure Name. 7. As part of the ‘PIBatch Configuration’ specify the PI Points for PIBatch Index, PIBatch Product Name and PIBatch Recipe Name. Also configure the ‘PIBatch Search Time’. PIBatches can be configured only if an existing PI Point is specified for the PIUnitBatch Active Point. 8. As part of the ‘PISubBatch Configuration’, create the SubBatch hierarchy on the ‘PISubBatches’ page. For each SubBatch defined, specify the PI Point for ‘SubBatch Active Point’ (required). Also select the ‘Active Point Behavior’ and ‘SubBatch Name’ options. If these options are not specified, the default values are used. A PIHeading set can be set from the list of available PIHeading sets shown at the bottom of the ‘SubBatches’ page. 9. Save the configuration by clicking on the ‘Save’ button. 10. Register the PIUnit. Registering a PIUnit is like turning the SCAN option ON for a traditional PI Point. A PIUnit can be Registered or Unregistered at any time. The interface will monitor only those PIUnits that are registered. 11. Repeat steps 4 to 9 for all the PIUnits. 12. Select the PI Server node and launch the migration utility. Migrate the PIUnits to be monitored by PIBaGen 2.x interface. 13. The file PIBaGen.dat_new should be renamed to PIBaGen.dat. Edit the start up command file. The file should contain the argument \host=servername where servername is the name of the server against which this interface runs. 14. Run the PIBaGen interface as a service on the PIServer selected. 15. Check the log file for any error messages.
Note: This interface does not make use of the PI-Interface Configuration Utility (PI-ICU) or bufserv.
PI Batch Generator (PIBaGen) Interface to the PI System 8 Verify PI-SDK Version
Verify that PI-SDK version 1.3.1 Build 237 or greater is installed. Typically this can be verified by opening PIHOME/PISDK/AboutPI-SDK.exe. The dialog box mentions the version and the build.
PI Batch Generator (PIBaGen) Interface to the PI System 9 Interface Installation
OSIsoft recommends that this version of the interface be installed on a PI Server node. The installation kit will install PIBaGen2.0.0.9 in the PIHome\interfaces\PIBaGen folder. The interface will be installed as a service. 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. Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface executable is PIBaGen.exe and that the startup command file is called PIBaGen.bat. It is not recommended that multiple copies of the interface run against the same server. However, multiple copies of the interface can run on the same machine each monitoring a different PI Server. 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 PIBaGen1.exe and PIBaGen1.bat for interface number 1, PIBaGen2.exe and PIBaGen2.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 Tree The 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 Directory Place all copies of the interface into a single directory. The suggested directory is: PIHOME\interfaces\PIBaGen\ Replace PIHOME with the corresponding entry in the pipc.ini file. Installing the Interface as an NT Service
Note: This interface does not make use of the PI-Interface Configuration Utility (PI-ICU) or bufserv.
PI Batch Generator (PIBaGen) Interface to the PI System 10 Installing the Interface Service Manually One can get help for installing the interface as a service at any time with the command: PIBaGen.exe –help Change to the directory where the PIBaGen.exe executable is located. Then, consult the following table to determine the appropriate service installation command.
NT Service Installation Commands on a PI Server node Manual service PIBaGen.exe –install –depend “tcpip pinetmgr” Automatic service PIBaGen.exe –install –auto –depend “tcpip pinetmgr” NT Service Installation Commands on a PI Interface Node Manual service PIBaGen.exe –install –depend tcpip
Automatic service PIBaGen.exe –install –auto –depend tcpip
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.
PI Batch Generator (PIBaGen) Interface to the PI System 11 PIBaGen Configuration Tool Installation
The PIBaGen Configuration Tool is used to create and configure PIUnits. PIBaGenCfg can also be used for the PIBaGen interface configuration and to view the PIModule Database on different PI Servers at the same time. It is a plug-in for PI-SMT 3.0.0.2 or greater. See the PI BaGenCfg Plug-In to the PI-System Management Tools manual for complete installation information.
PI Batch Generator (PIBaGen) Interface to the PI System 12 Run the PIBaGenCfg Tool
The PIBaGenCfg Tool can be started by going to Start Menu All Programs PI System and clicking on PI System Management Tools. Select the PIBaGenCfg node under the PIBaGen node on the tree on the left side of the host. Select the PIServer from the list of PIServers on the top left side of the PI SMT host. If the required server is not listed, it can be added from the File menu and clicking on Connections. On startup the Registered Units only view is displayed showing the selected servers and the list of registered PIUnits on those servers. Clicking on MDB View will load the PI Module Database for all the checked servers.
Figure 2: PIBaGen Configuration Tool: ‘Registered Units Only’ view
PI Batch Generator (PIBaGen) Interface to the PI System 13 Run the PIBaGenCfg Tool
Figure 3: PIBaGen Configuration Tool: “MDB View”
14 Interface Configuration
Select the PI Server node from either the Registered Units only view or MDB View. The interface configuration page will show up on the right side as shown in Figure 2. Configuration Module Name
Enter the Configuration Module Name. This attribute is the name of the sub-module created under each PIUnit in which the PIUnit configuration required for the PIBaGen interface to monitor this PIUnit is stored. Make sure that this is unique to the PIBaGen interface. Without the configuration module name, none of the PIUnits can be configured for the PIBaGen interface. Typically, this name is either “PIBaGen” or “PI-BaGen.” Interface Debug Messages
Turning this option ON will print additional interface-specific messages. Turning this option OFF will still send error messages to log file. Turn this option ON for trouble- shooting.
PI Batch Generator (PIBaGen) Interface to the PI System 15 Add PIModules and PIUnits
PIModules and PIUnits can be added from the PIBaGenCfg tool only in the MDB View. However, they cannot be deleted from within PIBaGenCfg. Select a PIModule node or PI Server node under which a new PIModule needs to be added and click the New Module button. Right click on the module node and select Convert to PIUnit to make the PIModule a PIUnit. A PIUnit can be converted back to PIModule by selecting the Convert to PIModule on the right click menu.
Figure 4: Add new PIUnit
PI Batch Generator (PIBaGen) Interface to the PI System 16 PIUnitBatch Configuration
The first part of configuring a PIUnit for generating batch data is the ‘PIUnitBatch Configuration’. This specifies all the necessary information to generate PIUnitBatches on the PIUnit. Select the PIUnit to be configured and click on ‘PIUnitBatches’ tab on the right side. The ‘PIUnitBatch Configuration’ is shown in Figure 5 below.
Figure 5: ‘PIUnitBatch’ configuration page Active Point (Required)
‘Active Point’ is the PI Point that determines the start and end of a PIUnitBatch. The PI Point can be of integer, digital or string type. It is required to specify an ‘Active Point’ to start generating PIUnitBatches. If this attribute is not specified or the PI Point does not exist then the PIUnitBatches and therefore the PIBatches and PISubBatches are not generated.
PI Batch Generator (PIBaGen) Interface to the PI System 17 PIUnitBatch Configuration
ActivePoint Behavior
ActivePoint Behavior option determines the way the transitions in ‘Active Point’ values are interpreted. There are three possible ways the start and end of a PIUnitBatch can be determined. They are ‘Pulse’, ‘Step’ and ‘Include zeroth state (Continuous)’. The default value is ‘Step’.
Step Step type behavior of ‘Active Point’ means that all transitions result in ending the currently running PIUnitBatch and starting a new PIUnitBatch except when the transition is to the 0th state (or value 0 for integer type or the string that indicates zeroth sate). If the transition is to the 0th state, the current PIUnitBatch is stopped but a new PIUnitBatch is not started.
Pulse Pulse type behavior of ‘Active Point’ means that only transition from 0th state (or value 0 for integer type or the string that indicates zeroth sate) to any other state is considered as start of a PIUnitBatch and transition from any other state to 0th state is considered as the end of existing PIUnitBatch. All other transitions are ignored.
Continuous Continuous type behavior of ‘Active Point’ means that all transitions result in ending the current PIUnitBatch and starting a new PIUnitBatch. This option is available only when Step is selected.
Strings Indicating Zeroth State For string type active points, if Step or Pulse option is selected, the string or strings indicating the zeroth state must also be specified. These strings are case-sensitive and they should be separated by a comma. For example if the strings ‘Inactive’, ‘Off’ and an empty string indicate a zeroth state, then this parameter should be Inactive, ,Off. The space between the two commas is interpreted as an empty string. Double quotes are not required. If this string is not specified, then a Pulse or Step for a string type active point is equivalent to a Continuous type. Unit Batch ID Point (Optional)
Unit Batch ID Point specifies the PI Point whose value determines the Unit Batch ID for the PIUnitBatches generated on the selected PIUnit. The Unit Batch ID does not have to be unique. If a valid PI Point for this attribute is not specified, the Unit Batch ID for a PIUnitBatch generated would be empty. Product Name Point (Optional)
Product Name Point specifies the PI Point whose value determines the Product name for the PIUnitBatches generated on the selected PIUnit. The Product name does not have to be unique. If a valid PI Point for this attribute is not specified, the Product name for a PIUnitBatch generated would be empty.
18 Procedure Name Point (Optional)
Procedure Name Point specifies the PI Point whose value determines the Procedure name for the PIUnitBatches generated on the selected PIUnit. The Procedure name does not have to be unique. If a valid PI Point for this attribute is not specified, the Procedure name for a PIUnitBatch generated would be empty. Evaluation Delay
Evaluation Delay specifies the time that the interface should wait before it evaluates the values from the PI Points specified above. The PIUnitBatch starts at the time the ‘Active Point’ indicates the start of the PIUnitBatch. However, other attributes of PIUnitBatch - Unit Batch ID, Product Name, Procedure Name, PIBatch, PIBatch Product Name and PIBatch Recipe Name are evaluated after waiting for the number of seconds specified in ‘Evaluation Delay’. If a PIUnitBatch end event is received while the interface is waiting for the evaluation delay to elapse, the PIUnitBatch properties are evaluated at the end event time and the PIUnitBatch is started and stopped. If the option ‘Evaluate at the end of each UnitBatch’ is checked, then the attributes are evaluated at the end of the PIUnitBatch and the Evaluation Delay value specified is ignored. The default value for Evaluation Delay is zero. Recovery Options
This option specifies if the PIUnitBatches, PIBatches and/or PISubBatches are recovered for each PIUnit in case the interface is shutdown and restarted. The default option ‘Recover all PIBatch objects’ recovers PIBatches, PIUnitBatches and PISubBatches on the selected PIUnit. The ‘Recover only PIBatches and PIUnitBatches’ option recovers only the PIBatches and PIUnitBatches on the selected PIUnit. The PISubBatches are not recovered. The ‘Do not recover anything’ option will not recover any PIUnitBatches and PISubBatches on the selected PIUnit. During recovery, if there is a running PIUnitBatch, the recovery starts from the start time of that running PIUnitBatch irrespective of the ‘Recovery Time’ specified. If there is no running PIUnitBatch, the interface searches for PIUnitBatches on the PIUnit up to ‘Recovery Time’ into the past. If the search finds PIUnitBatches within that period, recovery is done from the end time of the last PIUnitBatch. If there are no PIUnitBatches in the search results, then recovery is done for ‘Recovery Time’ into the past. This option helps in reducing the time it takes to recover if the recovery for that PIUnit is deemed not important.
Note: If PISubBatches are recovered, the PISubBatches on the running PIUnitBatch are removed and recreated based on the Archive Events. Since the interface depends on snapshot events during real-time operation and looks at archive events during recovery, it is possible that some of the subbatches that are generated during real-time operation might be missing after recovery. This condition occurs only under limited circumstances. If there is a running PIUnitBatch at the time of recovery and if that PIUnitBatch has PISubBatches (running or not), those PISubBatches are removed during recovery. If the start events for those subbatches were not archived, then those PISubBatches will be missing after recovery. This occurs only for that one PIUnitBatch. This situation can be avoided by setting the compression parameters on the Active Point for the SubBatches such that all the start and stop events for the PISubBatches are archived.
PI Batch Generator (PIBaGen) Interface to the PI System 19 PIUnitBatch Configuration
Recovery Time
‘Recovery Time’ is the time into the past starting from current time that the interface should attempt to recover events for each PIUnit. When the interface is shutdown for a certain period of time and restarted, it will attempt to recover batches occurred during the shutdown period. The recovery is done by checking the archived values for the Active Points. ‘Recovery Time’ is the time that the interface looks back into the past from the restart time of the interface for the archived events. Some batch data may not be generated if the ‘Recovery Time’ is shorter than the shutdown period. During recovery, if there is a running PIUnitBatch, the recovery starts from the start time of that running PIUnitBatch irrespective of the ‘Recovery Time’ specified. If there is no running PIUnitBatch, the interface searches for PIUnitBatches on the PIUnit up to ‘Recovery Time’ into the past. If the search finds PIUnitBatches within that period, recovery is done from the end time of the last PIUnitBatch. If there are no PIUnitBatches in the search results, then recovery is done for ‘Recovery Time’ into the past. For example, if the ‘Recovery Time’ is 4 days, and if the shutdown period is less than 4 days and the last PIUnitBatch on a PIUnit was 2 days ago, then the recovery for that PIUnit is done only for the past 2 days. In this case, the recovery for each PIUnit depends on when the last PIUnitBatch started. If the shutdown period is 7 days, then PIBaGen will recover batch data only for the past 4 days. There will be no batch recovery for the first 3 days of the shutdown period. This option helps in reducing the time it takes to recover if the shutdown time is long and recovery during the entire shutdown time is not critical. The default recovery time is 4 days. PIUnit Debug Messages
Turning this option ON will print additional PIUnit specific messages. Turning this option OFF will still send error messages to log file. Turn this option ‘ON’ for trouble shooting.
20 PIBatch Configuration
Select the PIUnit to be configured and select the ‘PIBatches’ tab on the configuration tool. This specifies all the necessary information to generate PIUnitBatches on the PIUnit. The ‘PIBatch Configuration’ is available only if the active point for the PIUnitBatches is an existing PI Point.
Figure 6: ‘PIBatch Configuration’ page PIBatch Index Point (Optional)
The PIBatch Index Point specifies the PI Point whose value determines the name of the PIBatch to which the PIUnitBatch generated would belong. A valid PI Point for this attribute serves as the source for the PIBatch name. The point does not act as ‘Active Point’ for the PIBatches, in other words, transitions in this PI Point will not trigger start and stop of PIBatches. A PIBatch is started only when a PIUnitBatch is started and ends when all the running PIUnitBatches in that PIBatch end. If a new PIUnitBatch is added after the PIBatch ends, the end time is updated with the new PIUnitBatch end time. When a PIUnitBatch starts, the value of the PIBatch Index Point is used as name of the PIBatch as one of the search criteria for PIBatches. If there are no matching PIBatches within the PI Batch Generator (PIBaGen) Interface to the PI System 21 PIBatch Configuration
‘PIBatch Search Time’, a new PIBatch is created. If a valid PI Point is not specified for this attribute, the PIUnitBatch does not belong to any PIBatch. Read ‘PIBatch Search Time’ for more details on how PIBatches are generated. PIBatch Search Time
The PIBatch Search Time is the time into the past and future (during recovery) from the unit batch start time that the interface searches the PI Batch Database for PIBatches when a PIUnitBatch starts. If there is a value for the PIBatch Index point at the PIUnitBatch start time (plus evaluation delay), then the interface will first search the PI Batch Database for a PIBatch with the PIBatch name same as the PIBatch Index point value, PIBatch product name and PIBatch recipe name within the time period (PIUnitBatch start time + Evaluation Delay – PIBatch Search Time) and (PIUnitBatch start time + Evaluation Delay + PIBatch Search Time). If a PIBatch with the search criteria is found in the PI Batch Database, then the PIUnitBatch will be added to the PIUnitBatches collection in that PIBatch or else a new PIBatch will be created. If the search results in more than one PIBatch, then the following rules are used to select the PIBatch. 1. If there is only one running PIBatch in the search period, then that PIBatch is selected irrespective of the start time of the PIBatch. 2. If there is more than one running PIBatch, then the one that has the start time between (PIUnitbatch start time + Evaluation delay - PIBatchSearchTime) and (PIUnitbatch start time + Evaluation delay + PIBatchSearchTime) is selected. If there is more than one running PIBatch in this range, then the one with the latest start time is selected. 3. If there is no running PIBatch but the search results in PIBatches, then the one that has start time between (PIUnitbatch start time + Evaluation delay - PIBatchSearchTime) and (PIUnitbatch start time + Evaluation delay + PIBatchSearchTime) is selected. If there is more than one PIBatch with start time in this range, the one with the latest start time is selected. 4. If there is no running PIBatch but the search results in PIBatches and there is no PIBatch that has start time between (PIUnitbatch start time + Evaluation delay - PIBatchSearchTime) and (PIUnitbatch start time + Evaluation delay + PIBatchSearchTime) then the one that has the latest start time is selected. 5. If no PIBatch is found with the search criteria, then a new PIBatch is added. The ‘PIBatch Search Time’ can be seen as the approximate duration of the PIBatch to which the PIUnitBatches in this PIUnit belong. The default value is 4 hrs. It is recommended that this value be slightly greater than one batch duration and less than twice the duration of a typical batch. If the search time is large and if the PIBatch IDs are not unique, then there is a possibility of having multiple results during the search and the PIUnitBatch may not end up in the right PIBatch. PIBatch Product Point (Optional)
The PIBatch Product Point specifies the PI Point whose value determines the PIBatch Product name. This could be different from the Product name of PIUnitBatches. It is possible to have intermediate products on the PIUnitBatches and therefore separate names for PIUnitBatches and PIBatches is necessary. If a valid PI Point for this attribute is not specified, the PIBatch Product name would be empty.
22 PIBatch Recipe Point (Optional)
The PIBatch Recipe Point specifies the PI Point whose value determines the PIBatch Recipe name. This refers to the Recipe used to make the batch. If a valid PI Point for this attribute is not specified, the PIBatch Product name would be empty.
PI Batch Generator (PIBaGen) Interface to the PI System 23 PISubBatch Configuration
The ‘PISubBatch Configuration’ specifies the necessary PI Points and attributes to generate PISubBatches. Select the PIUnit to be configured and select the ‘SubBatches’ tab. Add New SubBatch
Select the parent level and click on the ‘New’ button to define a new SubBatch. Enter the SubBatch Title.
Figure 7: ‘PISubBatch Configuration’ page SubBatch Active Point (Required)
‘SubBatch Active Point’ is the PI Point that determines the start and end of a PISubBatch. The ‘SubBatch Active Point’ can be set either by typing a PI Point name or by using the tag search button. The PI Point can be of integer, digital or string type. It is required to specify a ‘SubBatch Active Point’ to start generating PISubBatches. If this attribute is not specified or the PI Point does not exist then the PISubBatch and its child PISubBatches are not generated. Along with the ‘SubBatch Active Point’, the ‘Active Point Behavior’ PI Batch Generator (PIBaGen) Interface to the PI System 24 option for the selected SubBatch determines how PISubBatches are generated under a PIUnitBatch. A PISubBatch starts only if the parent PISubBatch is running. The first levels of PISubBatches start only if the PIUnitBatch is running. A PISubBatch ends if either the ‘SubBatch Active Point’ indicates the end or if the PIUnitBatch ends and does not necessarily end if the parent PISubBatch ends. ActivePoint Behavior
The ActivePoint Behavior option determines the way the transitions in ‘SubBatch Active Point’ values are interpreted. There are three possible ways the start and end of a PISubBatch can be determined. They are ‘Pulse’, ‘Step’ and ‘Include zeroth state (Continuous)’. The default value is ‘Step’.
Step Step type behavior of ‘Active Point’ means that all transitions result in ending the currently running PIUnitBatch and starting a new PISubBatch except when the transition is to the 0th state (or value 0 for integer type or the string that indicates zeroth sate). If the transition is to the 0th state, the current PISubBatch is stopped but a new PISubBatch is not started.
Pulse Pulse type behavior of ‘Active Point’ means that only transition from 0th state (or value 0 for integer type or the string that indicates the 0th state) to any other state is considered as start of a PISubBatch and transition from any other state to 0th state is considered as the end of existing PISubBatch. All other transitions are ignored.
Continuous Continuous type behavior of ‘Active Point’ means that all transitions result in ending the current PISubBatch and starting a new PISubBatch. This option is available only when Step is selected.
Strings Indicating Zeroth State For string type active points, if Step or Pulse option is selected, the string or strings indicating the 0th state must also be specified. These strings are case-sensitive and they should be separated by a comma. For example if the strings ‘Inactive’, ‘Off’ and an empty string indicate a 0th state, then this parameter should be Inactive, ,Off. The space between the two commas is interpreted as an empty string. Double quotes are not required. If this string is not specified, then a Pulse or Step for a string type active point is equivalent to a Continuous type. SubBatch Name
When a PISubBatch is added, the name of the PISubBatch is obtained either from a PI Point that is configured in the ‘SubBatch Name’ section or it is the same as the SubBatch Title. A PISubBatch cannot be created without a name. Therefore, if a separate PI Point is specified then it should be a valid PI Point and that PI Point should have good values at the start time of the PISubBatch.
PI Batch Generator (PIBaGen) Interface to the PI System 25 PI SubBatch Configuration
Use ActivePoint Value Selecting this option will result in using the value of the ActivePoint for the SubBatch at the start time of the SubBatch as the name of the new PISubBatch.
Use SubBatch Title Selecting this option will result in using the SubBatch Title (the name used to represent this SubBatch in the SubBatch hierarchy) as the name of the new PISubBatch.
Use this PI Point Value Selecting this option will result in using the value of the specified PI Point for the SubBatch at the start time of the SubBatch as the name of the new PISubBatch. PIHeading Set
A PIHeading Set can be selected from the available PIHeading Sets in the PIHeading Set combo box. A PIHeading Set is optional and provides a collective name for each level of PISubBatches defined in the SubBatch Hierarchy. For example, according to the S88 standards, the first level of PISubBatches is called ‘Operations’ and the second level is called ‘Phases’. To provide flexibility in naming these levels, PIHeading Sets are used. A PIHeading Set consists of PIHeadings and a level corresponding to the PIHeading. There can be only one PIHeading at each level. Therefore, if a PIHeading Set consisting of PIHeadings called ‘Operations’, ‘Phases’ and ‘Steps’ at levels 1, 2, and 3 respectively is specified for a particular PIUnit, it means that all the PISubBatches defined at the first level are Operations, all the PISubBatches defined at the second level (does not matter which PISubBatch is their parent PISubBatch) are Phases and all the PISubBatches defined at third level are Steps. If there is no PIHeading Set specified or if there is no corresponding PIHeading for any level, this attribute of the PIHeading Set is left empty.
26 Register/Unregister PIUnits
The interface will not monitor a PIUnit and generate batch data if the PIUnit is not registered. Registering a PIUnit is like turning the SCAN option ON for a PI Point. A PIUnit can be registered or unregistered at any time. Select the PIUnit to be registered and click on the ‘Register’ button. To un-register a PIUnit, select the PIUnit and click on the ‘Unregister button’.
PI Batch Generator (PIBaGen) Interface to the PI System 27 Migration of PIBaGen 1.x PIUnits to PIBaGen 2.x PIUnits
The configuration required for PIBaGen 1.x interface is different from the configuration required for PIBaGen 2.x interface. The difference is mainly in the SubBatch configuration. A migration tool is provided with the PIBaGenCfg that automatically converts the configuration. Once the configuration is converted, the PIUnit cannot be monitored correctly by PIBaGen 1.x. However, the migration utility will backup PIBaGen 1.x configuration so that the PIUnit can be reverted back to PIBaGen 1.x manually. See Appendix A: Migration from PIBaGen 1.x to PIBaGen 2.x.x.x for more details on how to migrate the configuration manually and how to use the Migration Utility.
PI Batch Generator (PIBaGen) Interface to the PI System 28 Startup Command File
The file PIBaGen.dat_new will be installed during initially. Edit this file and rename it to PIBaGen.dat or edit the existing PIBaGen.dat file. Command-line arguments can begin with a / or with a -. For example, the /ps=M and –ps=M command-line arguments are equivalent. 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.
Note: This interface does not make use of the PI-Interface Configuration Utility (PI-ICU) or bufserv. Command-Line Parameters
The command line parameters should be specified in the PIBaGen.dat file.
Parameter Description /host=servername Servername is the name of the PI Server that this interface Required monitors. The interface will not start up if the PI Server is not known. / Specified in seconds, this is the time the interface will wait after a maxstoptime=seco second interrupt message (Ctrl+C) before the interface forces an nds exit. This parameter is used when the interface is run in the interactive optional mode. The default value is 120 seconds. Sample PIBaGen.bat File
The following is an example file: rem PIBaGen.bat rem rem Sample start up file for PI Batch Generator Interface rem version 2.x.x.x rem rem Required Parameter rem -host=servername Name of the PI Server that the rem interface monitors rem Optional Parameter rem -maxstoptime=seconds Maximum time the interface should rem wait before forcing an exit while running in rem interactive mode. Default value is 120 seconds rem rem Sample command line .\PIBaGen.exe /host=localhost /maxstoptime=120
PI Batch Generator (PIBaGen) Interface to the PI System 29 Security
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 Server manuals. 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 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. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.
PI Batch Generator (PIBaGen) Interface to the PI System 30 Starting / Stopping the Interface
This section describes starting and stopping the interface once it has been installed. Starting Interface as a Service
If the interface was installed as a service, it can be started with the command: PIBaGen.exe –start Starting Interface Interactively
The interface can be started interactively by opening (double clicking) the PIBaGen.dat file. Stopping Interface Running as a Service
If the interface was installed as a service, it can be stopped at any time with the command: PIBaGen.exe –stop The service can be removed by: PIBaGen.exe –remove Stopping Interface Running Interactively
If the interface was running interactively, it can be stopped by sending an exit signal (Ctrl+C) in the command window.
PI Batch Generator (PIBaGen) Interface to the PI System 31 Appendix A: Migration from PIBaGen 1.x to PIBaGen 2.x.x.x
This section outlines the steps to migrate a PIUnit that is monitored by PIBaGen 1.x to PIBaGen 2.x.x.x. There are two methods to migrate the configuration. The first and recommended method is to use the ‘Migration Utility’ provided with the PI Batch Generator Configuration Tool. The second method is manually changing the configuration. Both these methods are described below. The migration utility preserves the PIBaGen 1.x configuration; meaning that PIBaGen 2.x will generate batch data on the migrated PIUnits just like PIBaGen 1.x was generating batch data with one exception. The migrated PIUnit recovery option will be set to recover PIBatches, PIUnitBatches and PISubBatches. Migration using ‘Migration Utility’
The migration utility can be launched by selecting a server node and clicking on the ‘Migration’’ ( ) button on the toolbar for the PI Batch Generator Configuration Tool. A new window called ‘Migration Chart’ will be displayed if there are any PIPoints belonging to PIBaGen 1.x on that PI Server and if they are not yet migrated. If the ‘userint1’ attribute for a PIPoint belonging to PIBaGen 1.x is set to 1, it is considered that the corresponding PIUnit is already migrated and is not loaded into the Migration Chart. The migration utility sets the ‘userint1’ to 1 during the migration process. Only those PIUnits that do not have the error ( ) sign next to the configuration point can be migrated. If there is an error sign, the ‘Migration Status’ column explains why the PIUnit cannot be migrated. Please see the Appendix D for common errors that arise before and during migration. While the selected PIUnits are migrated, the migration utility follows these steps for each PIUnit: 1. Rename the configuration module used by PI-BaGen 1.x to ‘PIBaGen 1.x Configuration–Migrated’. 2. If the renaming process is successful, the PIUnit is considered to be migrated and ‘userint1’ for the PIBaGen 1.x PIPoint is set to 1. 3. A new module is then added under the PIUnit with the name as ‘Configuration Module Name’. 4. All the PIUnitBatch and PISubBatch configuration is then copied to the newly added ‘Configuration Module’. 5. If PISubBatches are configured in PIBaGen 1.x, then each PIAlias in each PIModule under ‘SubBatchSupport’ module represents one SubBatch in PIBaGen 2.x configuration. Therefore, one PIModule with the name format as ‘H:P’ is added, where ‘H’ stands for the PIHeading name and ‘P’ stands for the PIPoint name (data source for that PIAlias). The same PIPoint is also used for deriving the PISubBatch name. 6. The ‘ActivePoint Behavior’ is set to ‘Continuous’ because the ‘Step’ behavior for SubBatches in PIBaGen 1.x is now behaved like the new ‘Continuous’ option. 7. The PIUnit is registered if the corresponding PIBaGen 1.x PIPoint had the ‘Scan’ attribute set to 1. In such a case, the PIPoint ‘Scan’ attribute is set to zero after registering the PIUnit. PI Batch Generator (PIBaGen) Interface to the PI System 32 8. If there are any errors during the migration process, the corresponding row is highlighted and the error messages are shown at the bottom of the ‘Migration Chart’ and are also sent to the log file. If the migration is successful, the ‘Migration Status’ column shows ‘Migration Completed’. Migrating the PIUnits manually
There is no real advantage of manual migration of the PIUnits. However, here are the steps incase there is an unforeseen problem encountered by the ‘Migration Utility’. Migration of PIUnits without SubBatches
If the PIUnit is configured only for PIUnitBatches and PIBatches and not for PISubBatches there is no need for any change in configuration. Follow these simple steps: 1) Turn the Scan option ‘Off’ for the corresponding PIPoint with point source ‘U’. Set the ‘userint1’ attribute set to 1 for this PIPoint. Repeat this step for all the PIUnits to be migrated. 2) Stop PIBaGen 1.x. Start PIBaGen 1.x. After this step PIBaGen 1.x will stop monitoring the PIUnits being migrated. 3) In PIBaGen configuration tool 2.0.0.9 or greater (as a PI-SMT 3.0.0.2 plug-in) select ‘MDB View’, select the PIUnits to be migrated and click on ‘Register’ button. 4) Start PIBaGen 2.x.x.x. PIUnits with SubBatches
If the PIUnit is configured for PISubBatches, it is necessary to reconfigure the SubBatches. There is no need to make changes to configuration for PIUnitBatches and PIBatches. While performing the steps below, some PIModules under the PIUnit configuration module will be deleted and new ones added. This implies that PIBaGen 1.x can no longer generate SubBatches on the migrated units. If PIBaGen 1.x configuration is to be preserved, then first go to the PI-MDB Editor, find the ‘PI-BaGen’ (or the module with the name specified as configuration module name) sub-module under the PIUnit, right click on that module, copy the module, right click on the PIUnit and click on ‘Paste’ (NOT ‘Insert’). There should now be a sub-module with the name ‘Copy of PI-BaGen’. Right-click on this module, select ‘Edit’ and re-name the module to ‘PIBaGen 1.x Configuration’. This module can be referred in future if there are any configuration problems for PIBaGen 2.x.x.x. 1) Turn the Scan option ‘Off’ for the corresponding PIPoint with point source ‘U’. Set the ‘userint1’ attribute set to 1. Repeat this step for all the PIUnits to be migrated. 2) Stop PIBaGen 1.x. Start PIBaGen 1.x. After this step PIBaGen 1.x will stop monitoring the PIUnits being migrated. 3) In PIBaGen configuration tool 2.0.0.9 or greater (as a PI-SMT 3.0.0.2 plug-in) select ‘MDB View’, select the PIUnit to be migrated 4) Select the PISubBatches tab page. This page will display the various subbatches already defined but the ‘ActivePoint’ will be missing and other attributes will take default values. To start SubBatch configuration afresh (without migration), select each of the nodes under ‘SubBatch Hieararchy’ and click on the ‘Delete’ button and ‘Save’ the changes. Then add new SubBatches as described earlier in this manual. To PI Batch Generator (PIBaGen) Interface to the PI System 33 Appendix A: Migration from PIBaGen 1.x to PIBaGen 2.x.x.x
migrate the SubBatch definitions, add and delete the SubBatches to reflect the desired SubBatch hierarchy. For each SubBatch, define the ‘Active Point’, ‘Active Point behavior’ and ‘SubBatch Name’ options. Click the ‘Save’ button to save the changes. For example, consider a PIUnit configured on PIBaGen 1.x for subbatches as shown in Figure 8 through Figure 10 and has the following settings. PIHeading Set ‘S88SubBatches’ is used and it has three levels: Operations – Level 1, Phases – Level 2, Steps – Level 3 Operations level has one active point – BaGen:Op.1 Phases level has three active points – BaGen:PHASE1.1, BaGen:PHASE2.1, BaGen:PHASE3.1 Steps level has three active points – BaGen:STEP1.1, BaGen:STEP2.1, BaGen:STEP3.1
Figure 8: PIBaGen 1.x configuration for Operations with one active point
34 Figure 9: PIBaGen 1.x configuration for Phases with three active points
PI Batch Generator (PIBaGen) Interface to the PI System 35 Appendix A: Migration from PIBaGen 1.x to PIBaGen 2.x.x.x
Figure 10: PIBaGen 1.x configuration for Steps with three active points
Upon selecting this PIUnit in PIBaGenCfg 2.0 and selecting the ‘PISubBatches’ tab it would look as shown in Figure 11. The Operations (and so does the Phases and Steps) configuration is not recognized by the new configuration tool.
36 Figure 11: SubBatch configuration on PIBaGenCfg 2.0 before making changes for migration
Select ‘Operations’ and select the Active point as ‘BaGen:Op.1’. In order to keep the same active point behavior as in PIBaGen 1.x, check the box for ‘Include zeroth state (Continuous)’. If the ‘Continuous’ behavior is not desired, other options can be selected as well. In order to keep the same SubBatch naming as in PIBaGen 1.x, select ‘Use ActivePoint value’ as the ‘SubBatch Name’ option. The configuration would look as shown in Figure 12.
PI Batch Generator (PIBaGen) Interface to the PI System 37 Appendix A: Migration from PIBaGen 1.x to PIBaGen 2.x.x.x
Figure 12: SubBatch configuration on PIBaGenCfg 2.0 after making changes for migration on the first level
If the ‘Phases’ actually belong under ‘Operations’, that is if they are at the second level in the hierarchy, then select the ‘Operations’ node and click on ‘New’ button. Enter the name ‘Phase1’ or any other name that can be used for the subbatches represented by the active point ‘BaGen:Phase1.1’. Set the ActivePoint to ‘BaGen:Phase1.1’. In order to keep the same active point behavior as in PIBaGen 1.x, check the box for ‘Include 0th state (Continuous)’. If the ‘Continuous’ behavior is not desired, other options can be selected as well. In order to keep the same SubBatch naming as in PIBaGen 1.x, select ‘Use ActivePoint value’ as the ‘SubBatch Name’ option. Repeat the above step for each of the Phases. If any of the Phases’ active points actually represents SubBatches at the first level, then select ‘SubBatch Hierarchy’ node and then add the new SubBatch. Depending on under which phase each of the Steps belong, select that node and click on ‘New’ button, enter the SubBatch title and add the active point and set other attributes as described for Phase1. Now, select ‘Phases’ SubBatch at the first level and delete it by clicking on the ‘Delete’ button. Select the ‘Steps’ SubBatch at the first level and delete it.
38 Click the ‘Save’ button to save the configuration. The final configuration should look as shown in Figure 13.
Figure 13: SubBatch configuration on PIBaGenCfg 2.0 after making changes for migration on all levels
The configuration shown in Figure 13 is only one possible combination of SubBatch hierarchy. It is possible to have all Steps under Phase1 and no steps under Phase2 and Phase3 or many other combinations. It is this increasing number of combinations that makes it difficult to perform auto migration and requires user intervention. 5) Once the configuration is saved, ‘Register’ the PIUnit 6) Repeat steps 3 to 5 for all the PIUnits to be migrated. 7) Start PIBaGen 2.0
PI Batch Generator (PIBaGen) Interface to the PI System 39 Appendix B: Running the Interface Remotely
This section explains why it is not recommended to run the interface remotely for the version 2.0.0.9 release. This interface signs up for updates on PI-Module Database and for snapshot values for Active points through event pipes in PI-SDK. This feature allows the interface to read the changes in Module Database while it is running and without having to restart. However, if there is a lost connection to the remote server due to network or other issues (any reason other than PI Server shutdown), upon re-establishing the connection, the event pipe starts getting the new events but it misses the events that occurred during the lost connection. This results in possible missing PIUnitBatches or PISubBatches. Work is in progress to resolve this issue.
PI Batch Generator (PIBaGen) Interface to the PI System 40 Appendix C: Backfilling Batch Data
This section explains how to backfill batch data for a specific PIUnit. This version of the interface is not capable of filling holes in batch data. In other words, if there is batch data on a PIUnit for the last 3 days and there is missing batch data before those 3 days, the interface cannot backfill data for that time period. It is only capable of recovering batch data from the time of the most recent PIUnitBatch on the PIUnit to the current time. If there is a running PIUnitBatch on the PIUnit, the batch data beyond the start time of the running PIUnitBatch cannot be recovered using this interface. If the most recent PIUnitBatch is closed, then batch data can be recovered only from the end time of that PIUnitBatch. If there are no PIUnitBatches on that PIUnit, recovery can be done up to the start time of the primary archive. This limitation is because when the first PIUnitBatch is added on a PIUnit, a PIUnitBatch storage PIPoint is created and this PIPoint does not have a primary record in the older archives. If a PIUnitBatch was previously added and deleted, then the PIUnitBatch storage PIPoint for this PIUnit already exists and in such a case, the batch data can be backfilled until the start time of the archive when that PIUnitBatch storage PIPoint was originally created. The following steps should be performed to backfill data on a PIUnit that does not have PIUnitBatches. 1) If the PIUnit exists, make sure it is not monitored by the interface. (Unregister the PIUnit and check that the interface stopped monitoring the PIUnit.) The alternative is to stop the interface, but it is not necessary. 2) If the PIUnit does not exist, create the PIUnit. On a PI 3.4 server proceed to Step 5. 3) If the PIUnitBatch storage PIPoint for this PIUnit already exists (i.e., if PIUnitBatches were previously added and removed), then proceed to Step 5. 4) Add a PIUnitBatch, using PI-MDB Editor, with the start time later than the start time of the primary archive. Using PI-MDB editor, delete the just added PIUnitBatch. This step will create the necessary PIUnitBatch storage PIPoint. Perform this step when it cannot be determined if the PIUnitBatch storage PIPoint exists. 5) Repeat steps 1 to 4 for all the PIUnits that need to be backfilled. 6) A PIBatch storage PIPoint is added when the first PIBatch is added to the PI Batch Database. If there was no PIBatch ever added to the PIBatch Database, then using PI- MDB Editor, add and remove a PIBatch that has the start time later than the start time of the primary archive. This step will create the necessary PIBatch storage PIPoint. Perform this step when it cannot be determined if the PIBatch storage PIPoint exists. 7) Reprocess the archives to create primary records for the newly added storage PIPoints. All the archives that cover the time span for backfilling batch data need to be reprocessed. See PI Server System Management Guide for details on reprocessing archives. 8) Open the PIBaGen Configuration Tool plug-in in PI-SMT. Select the PIUnit of interest and set the Recovery Option to either Recover all PIBatch Objects or Recover only PIBatches and PIUnitBatches. Also, the Recovery Time should be set to a value that covers the entire recovery period for that PIUnit. Save the changes to the configuration. 9) Register the PIUnit. PI Batch Generator (PIBaGen) Interface to the PI System 41 Appendix C: Backfilling Batch Data
10) Repeat steps 8 and 9 for all the PIUnits that need to be backfilled. 11) Start the interface if it is not already running.
42 Appendix D: Error and Informational Messages
A string PIBaGen-servername,where servername is the name of the PI Server monitored by the interface, is pre-pended to error messages written to the message log. Message Logs
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 command-line parameters used, and the PIUnits registered. As the interface loads these PI Points, messages are sent to the log if there are any problems with the configuration of the points.
If the debugging is turned ON for the interface or individual PIUnits, then various informational messages are written to the log file. Messages
Memory allocation error This message occurs when the interface is unable to allocate any memory. The interface should be stopped and the system should be checked for what is causing the memory allocation error.
Failed to open argument file The interface failed to open the argument file “PIBaGen.dat”. Check if such a file exits in the same folder as the PIBaGen.exe file, and if the user has the rights to open and read this file.
Fatal error: PI Server name is not specified The command line argument in PIBaGen.dat file does not have the server name specified. The parameter /host= should be followed by a server name.
Fatal error: \host parameter is not specified in the command line The command line argument in PIBaGen.dat file does not have the /host parameter specified. This argument is required for the interface to know the PI Server to which it should connect.
Fatal Error in CoInitializing This error implies that there is a problem initializing a COM thread. The reasons for this could be outside of the scope of the interface. Please check with the system administrator on how to resolve this issue.
PI Batch Generator (PIBaGen) Interface to the PI System 43 Appendix D: Error and Informational Messages
Fatal Error instantiating PISDK. Interface was not able to instantiate PISDK. Check if PISDK is installed on this machine and if it is installed does the user id under which this interface is running should be able to access (run) PISDK.
Fatal Error: PISDK is not installed or cannot be accessed on this machine Interface was not able to instantiate PISDK. Check if PISDK is installed on this machine and if it is installed does the user id under which this interface is running should be able to access (run) PISDK.
Fatal Error: Could not get the PISDK Version information. Interface was not able to check the version of PISDK. It is important for the interface to verify the PISDK version. Open ‘About PISDK’ in PIPC/PISDK directory and check for the version. If the version is accessible and it is greater or equal to than the minimum version requirement specified in this document, then re-install PISDK and try again.
Fatal Error: PISDK Version should be greater than versionnumber The interface requires PISDK with minimum version ‘versionnumber’. The currently installed PISDK does not meet this requirement. Upgrade PI-SDK to the minimum version.
Error establishing PI-API connection to servername. Interface will check once every minute for a connection The interface was unable to open an API connection to the PI Server ‘servername’. Check if the PI Server is running and all it’s subsystems are running. Also check if the network cable is properly connected. Check if the user id used to connect to the PI Server is (default piuser) has PITrust set up.
Error establishing connection to servername The interface was unable to open an API connection to the PI Server ‘servername’. Check if the PI Server is running and all it’s subsystems are running. Also check if the network cable is properly connected. Check if the user id used to connect to the PI Server is (default piuser) has PITrust set up.
Fatal Error: Could not find the PIServer servername in the list of known servers. Attempted to add the server failed While opening a PI-SDK connection to the PI-Server, the interface looks at the known servers table to find the PI Server ‘servername’. If this is not found, it adds the ‘servername’ to the list of known servers. However, this attempt failed. Check the PI- SDK and try to add the server to the list of known servers and restart the interface.
Interface could not open a connection to the Server servername . Interface will check every one minute for a connection The interface was unable to open an SDK connection to the PI Server ‘servername’. Check if the PI Server is running and all it’s subsystems are running. Also check if the network cable is properly connected. Check if the user id used to connect to the PI Server is (default piuser) has PITrust set up.
44 Fatal error: Interface cannot instantiate PIPtCollection This error is possible mainly due to memory allocation problems or other system related issues.
Error in instantiating PIPt object This error is possible mainly due to memory allocation problems or other system related issues.
Error in instantiating PIUB object for the PIUnit PIUnitname This error is possible mainly due to memory allocation problems or other system related issues.
Error in instantiating PISB object This error is possible mainly due to memory allocation problems or other system related issues.
Fatal error: PI Module Database could not be accessed on the PIServer Interface was unable to access the PI-Module Database on the PI Server. Check that PI- MDB is installed on the PI Server and the user id used by the interface (default piuser) has the right privileges to access PI-MDB.
Could not find the module %OSI/PIBaGen. Interface is waiting for this module to be added The PIModule ‘PIBaGen’ under ‘%OSI’ PIModule is necessary for the interface to run. Open the configuration tool (PIBaGenCfg in SMT 3.0) and select the PI Server node on the ‘Registered Units’ view. On the ‘Interface’ page on the right side, add the ‘Configuration Module Name’ and set the debug settings and click the ‘Save’ button. This should create the necessary module.
Error in finding "Registered Units" PIProperty under %OSI\\PIBaGen module This means that there are no registered PIUnits on the PI Server. Open the configuration tool and register a PIUnit.
Could not retrieve the PIUnit for PIUnitname .Interface cannot monitor this unit This error occurs commonly if the PIUnit was deleted after it was registered. If the PIUnit exists and the error still occurs, then check the version of PI-SDK that the configuration tool is using and the version that the interface is running. Make sure they are the same.
The registered unit PIUnitname is not a PIUnit. Interface is not monitoring this unit The registered PIUnit is not a PIUnit anymore. A PIModule is considered a PIUnit if it has the ‘IsPIUnit’ flag set to true. Open the configuration tool, select the PIModule in question, unregister it, convert the PIModule to PIUnit (by right clicking on the PIModule) and register the PIUnit.
Could not find the Configuration sub-module configmodulename. PIUnit is probably not configured for unitbatches Every PIUnit has a sub-module whose name is the ‘Configuration Module Name’ set in interface configuration page. This sub-module is essential for the interface to monitor the
PI Batch Generator (PIBaGen) Interface to the PI System 45 Appendix D: Error and Informational Messages
PIUnit. It is possible that the interface is registered but no other parameters are set. Open the configuration tool, select the PIUnit, on the ‘PIUnitBatches’ page on the right side, add the ‘ActivePoint’, ‘UnitBatch ID point’ etc and click ‘Save’.
Error opening Module Database EventPipe on the PI Server servername There is an error in signing up for events in PI Module Database. Check the version of PI-SDK. Does it meet the minimum requirement? If not, upgrade PI-SDK. If it does, re- install PI-SDK. Also check for the privileges that the user id used by the interface.
Not monitoring the PIUnit PIUnitname Interface is not monitoring the PIUnit with the name ‘PIUnitname’. The reason for this is typically printed above this message. Check if the ‘AcitvePoint’ for this PIUnit is valid and of the type Integer, digital or String. This error could also arise if there is memory allocation problem while loading this PIUnit.
Invalid Active Point The ‘ActivePoint’ for UnitBatches of SubBatches does not exist on the interface. Either add such a PI Point or change the ‘ActivePoint’
Invalid Active Point type. Only digital,integer and string type points are allowed for an activepoint Check if the ‘AcitvePoint’ for this PIUnit is valid and of the type Integer, digital or String. Float and blob type PI Points are not acceptable as ‘ActivePoints’.
Could not retrieve the PI Point in the Alias PIAliasname The PI Point stored in the Alias ‘PIAliasname’ is not found. It might have been deleted. Check the messages preceding this message in the log file to see which PIUnit or SubBatch this message relates to.
Interface will not assign PIHeadings for SubBatches PIHeading Set is not defined for the SubBatch Hieararchy. PIHeading set is optional to create SubBatches. This message is informational and the interface will continue to generate subbatches even if this message is seen.
Error accessing sub-modules under SubBatchSupport SubBatches are stored under the ‘SubBatchSupport’ module. The interface cannot access these modules. Check the permissions for the user id used by the interface.
Not monitoring SubBatchName The interface is not monitoring the SubBatch that it is attempting to load. Check the messages preceding this message in the log file to determine why it is not monitoring. The most common reason is if the ‘ActivePoint’ for the SubBatch is not configured.
Not monitoring SubBatchName because the parent PIUnit is not being monitored The interface is not monitoring the SubBatch ‘SubBatchName’ because the parent PIUnit is not being monitored. Check the PIUnit messages to determine why the PIUnit is not monitored. Most common reason is if the ‘ActivePoint’ for PIUnitBatches is not configured.
46 Not monitoring SubBatchName and it's children The interface is not monitoring the SubBatch ‘SubBatchName’ . Check the messages preceding this message in the log file to see why this SubBatch is not monitored. The most common reason is if the ‘ActivePoint’ for the SubBatch is not configured. If this SubBatch is not monitored, then all it’s child SubBatches are also not monitored.
Not monitoring SubBatchname under the PIUnit PIUnitname The interface is not monitoring the SubBatch that it is attempting to load. Check the messages preceding this message in the log file to determine why it is not monitoring. The most common reason is if the ‘ActivePoint’ for the SubBatch is not configured.
Error accessing PIModule from a PIModule collectoin. A PIModule contains a collection of PIModules. The interface cannot access these PIModules. This error occurs when the interface sees that there are subbatches defined for a PIUnit but it is unable to access the modules that represent those subbatches. Check the permissions for the user id used by the interface. Since this message can occur at any level in the SubBatch hierarchy, check the messages preceding this message in the message log to determine which sub-modules are not accessible. Possible reason is if those subbatches were deleted after the interface starts loading that PIUnit.
If any recovered events for subbatches on the PIUnit PIUnitname are not evaluated yet, they will be evaluated after the next event for the unitbatch During recovery, the interface tries to recover events in chronological order. If some of the events (typically the most recent events in the archive) cannot be evaluated until a new current event is observed. Such events are not evaluated during recovery but are left pending until a new real-time event is observed.
Error in retrieving the subbatches for the last unitbatch. Some subbatches might be left running The interface could see that there are PISubBatches on a PIUnitBatch but it is not able to retrieve those PISubBatches from the PI Server. The interface attempts to do this while closing a running PIUnitBatch (and thereby closing the running PISubBatches). If this error occurs there will be PISubBatches that are running until stopped by means outside of the interface.
Error in retrieving the PIBatch for the last unitbatch unitbatchid for the PIUnit PIUnitname The interface cannot retrieve the PIBatch to which the PIUnitBatch ‘unitbatchid’ on the PIUnit PIUnitname belongs to. This will result in not being able to update the endtime for the PIBatch when the PIUnitBatch ends. Check the PI-BatchDatabase and see why this PIBatch cannot be accessed. This error might be possible if the PIBatch is deleted but the reference to this PIBatch in the PIUnitBatch is not properly deleted.
Error while looking for archive values for the PI Point with PointID pointid During recovery, the interface looks at archived events for the ‘Active Points’. There was an error trying to retrieve the archive events for this PI Point. Check that the archive subsystem is online, that the archives are registered and accessible. Check the permissions for the user id used by the interface. The user id should have the permissions to read data for the point with the ‘pointid’. This error might also occur if the value returned by the archive is not readable (which is rare). PI Batch Generator (PIBaGen) Interface to the PI System 47 Appendix D: Error and Informational Messages
Error in retrieving the subbatches for the unitbatch with BatchID: UnitBatchID The interface could see that there are PISubBatches on a PIUnitBatch but it is not able to retrieve those PISubBatches from the PI Server. The interface attempts to do this while removing PISubBatches from a PIUnitBatch during recovery. If this error occurs, there might be duplicate PISubBatches on that PIUnitBatch. Try to access those PISubBatches through other means (SDK, BatchView, MDB Editor etc) and if they are able to access, then check the permissions for the userid.
Removing all the SubBatches in the unitbatch with BatchID UnitBatchID This is an informational message. During recovery of PISubBatches, the interface first deletes all the PISubBatches under a running PIUnitBatch. This is necessary to avoid duplicate PISubBatches during recovery. The interface recreates these PISubBatches. If these PISubBatches are not created, it means that the events corresponding to the start of the PISubBatches are not archived. In order to avoid such situations, the ‘ActivePoints’ for the SubBatches should have compression settings such that all the start and stop events for the PISubBatches should be archived.
These SubBatches will be recovered. This is an informational message. During recovery of PISubBatches, the interface first deletes all the PISubBatches under a running PIUnitBatch. This is necessary to avoid duplicate PISubBatches during recovery. The interface recreates these PISubBatches. If these PISubBatches are not created, it means that the events corresponding to the start of the PISubBatches are not archived. In order to avoid such situations, the ‘ActivePoints’ for the SubBatches should have compression settings such that all the start and stop events for the PISubBatches should be archived.
Error in resetting endtime for the PIBatch batchid The interface could not reset the end time for a PIBatch. The reason for this could be that the end time is either too far into the future (due to time difference in the server and interface node) or if the user id does not have proper rights to modify the PIBatch end time. The result of this error will be that there will be PIBatches with incorrect end time.
Error finding PIUnitBatches for the PIBatch batchid The interface could not access the PIUnitBatches collection for a PIBatch. The reason could be access rights for the user id that the interface uses to connect to the server. It could also be that the PIBatch ‘batchid’ has been deleted after the interface accessed the PIBatch.
Error while removing event at time from the recovered event list. The interface keeps a list of pending events. After the pending event is evaluated, it is removed from that list. This is a system error and needs more investigation to understand why this error occurred. Restarting the interface might resolve this issue.
Unknown error while removing event at time from the recovered event list The interface keeps a list of pending events. After the pending event is evaluated, it is removed from that list. This is a system error and needs more investigation to understand why this error occurred. Restarting the interface might resolve this issue.
48 Non COM Error while removing event at time from the recovered event list The interface keeps a list of pending events. After the pending event is evaluated, it is removed from that list. This is a system error and needs more investigation to understand why this error occurred. Restarting the interface might resolve this issue.
Error in removing events from the subbatch SubBatchName under the PIUnit PIUnitName The interface keeps a list of pending events. After the pending event is evaluated, it is removed from that list. This is a system error and needs more investigation to understand why this error occurred. Restarting the interface might resolve this issue.
Non COM Error in removing events from the subbatch SubBatchName under the PIUnit PIUnitName The interface keeps a list of pending events. After the pending event is evaluated, it is removed from that list. This is a system error and needs more investigation to understand why this error occurred. Restarting the interface might resolve this issue.
Error while searching for PIUnitBatches on the PIUnit PIUnitname The interface is unable to search for PIUnitBatches on the PIUnit named ‘PIUnitname’ during recovery. Search for PIUnitBatches on this unit for the last ‘Recovery Time’ into the past using other tools like MDB Editor, BatchView etc. If that fails too, then it should be either a PI-SDK error or PI Server error. If they are successful, check the privileges the user running the interface has on PIModule Database. The result of this error is that there might be additional errors when trying to create a PIUnitBatch while there is a running PIUnitBatch on this PIUnit.
Could not access the subbatches The interface could see PISubBatches under a PIUnitBatch but it is not able to access those PISubBatches. Either those PISubBatches are deleted after the interface sees them or the user running the interface does not have the right privileges.
Could not set the end time for the subbatch SubBatchname The SubBatch end time is not set either because the PISubBatch has been deleted after the interface created the PISubBatch or the user does not have the right privileges.
This event value is same as the previously evaluated event value... ignoring this event This message is informational. The event being evaluated has the same value as the previously evaluated event. This does not mean that this event is same as the previous event, it means the event is same as the event that was previously processed by the interface for that PIUnit or SubBatch. For example, if the setting is ‘Pulse’ and most recently evaluated value is ‘1’ and the next value is ‘2’, then the interface ignores the value ‘2’ without evaluating it. If ‘2’ is followed by ‘1’ then it is considered as same as the previously evaluated event.
This Event has a bad value ... ignoring this event This message is informational. The event being evaluated has a bad value. It either has a System digital state (like Shutdown, I/O timeout etc) or it has a value that cannot be recognized by PI. PI Batch Generator (PIBaGen) Interface to the PI System 49 Appendix D: Error and Informational Messages
This event has occured before the Last Evaluated Event ... ignoring this event This message is informational. The event being evaluated has a timestamp that is earlier than the previously evaluated event. In other words, this is an out of order event and there is no direct way of interpreting out of order events with respect to generating batch data. Hence this event will be ignored.
UnitBatch (with Batch ID: batchid) already in progress. This event is ignored This message is informational. The event being evaluated indicates a start of PIUnitBatch. However, the ‘ActivePoint Behavior’ is set to Pulse and there is a PIUnitBatch that is already running. Hence this event is ignored.
Another UnitBatch start event is waiting for evaluation delay to elapse. This start event is ignored This message is informational. The event being evaluated indicates a start of PIUnitBatch. However, the ‘ActivePoint Behavior’ is set to Pulse and there was a start event and the interface is waiting for the evaluation delay to elapse. Hence this event is ignored.
This event has occured before the Last Evaluated Event for the Parent... ignoring this event This message is informational. The event being evaluated for a SubBatch has a timestamp that is earlier than the previously evaluated event for the parent. In other words, this is an out of order event with respect to the parent and there is no direct way of interpreting out of order events while generating batch data. Hence this event will be ignored.
There is a running SubBatch (with the name SubBatchname) This event is ignored This message is informational. The event being evaluated indicates a start of PISubBatch. However, the ‘ActivePoint Behavior’ is set to Pulse and there is a PISubBatch that is already running. Hence this event is ignored.
The parent SubBatch/UnitBatch is not active. This event will be evaluated after the parent starts This message is informational. The event being evaluated indicates start of a PISubBatch. However, there is no active parent (PISubBatch or PIUnitBatch, whichever is the parent) and therefore this event is listed as pending and it will be evaluated after the parent event is evaluated.
This event is waiting for a parent event to be evaluated This message is informational. The event being evaluated indicates start of a PISubBatch. However, there is an event for the parent with same or earlier timestamp. Hence the interface will wait until the parent event is evaluated to find out what this event means. This is a common occurrence when the same event triggers the parent and child or when the child event is received by the interface before the parent event.
Error in resetting the end time for the unitbatch with Batch ID batchid The interface could not reset the end time of the previous PIUnitBatch while trying to merge two PIUnitBatches. The error could occur if that PIUnitBatch with ‘batchid’ is
50 deleted or the user running the interface does not have the proper rights to modify the end time. This will result in not merging the two consecutive PIUnitBatches.
Could not start a new unitbatch on the PIUnit PIUnitname The interface could not start a new PIUnitBatch on the PIUnit ‘PIUnitname’. The error could occur if that PIUnit is deleted or the user running the interface does not have the proper rights to add PIUnitBatches. The error could also be because there is already a running PIUnitBatch or the rule that ‘There can be only one PIUnitBatch on a PIUnit at any given time’ might be violated. One complex situation in which this can occur is when the PIUnit represents a unit migrated from the Batch SubSystem. If the ‘Effective Date’ is not properly set, there can be running or active PIUnitBatches on the PIUnit but are not retrieved by PIUnitBatch search. Additional error message might give more details.
Either PI base subsystem or PI Archive subsystem is offline. The interface will check every 30 seconds. The interface identified that either the PI Archive or PIBase subsystem is unavailable. This is identified when the interface attempts to write or read a value from PI. If there are no new events while these subsystems were down, then this message will not appear. Check the service control manager to see if these subsystems are running. If not, restart the subsystems. If both these subsystems are still running and this error is observed, try to restart the interface.
Archive is not mounted. The interface will check every 30 seconds. The interface identified that an archive is not mounted. This is identified when the interface attempts to write or read a value from PI. If there are no new events while these subsystems were down, then this message will not appear. Check to see if there is a registered archive for the time period of interest. Interface will continue after the archive is mounted again. This error will also occur when the interface attempts to write batch data during archive backup. In this case, the interface will continue to generate data after the backup is complete and archive is available again.
Could not set the procedure name for the unitbatch (batchid) on the PIUnit PIUnitname The procedure name might have invalid characters. Check PI-SDK manual for invalid characters (if any) for the procedure name. It might also be that the user running the interface does not have the right privileges.
Error in stopping the UnitBatch with BatchID batchid The PIUnitBatch might have been deleted or the user running the interface does not have the right privileges. Use other tools like BatchView to see if the PIUnitBatch exists.
UnitBatch with BatchID batchid does not belong to any PIBatch Either PIBatches are not configured (PIBatch Index point) is not specified or the PIBatch Index point does not have a value or the value is not good. Check the archive for the value of PIBatch Index point at (PIUnitBatch start time + Evaluation Delay). It might also occur if the PIUnitBatch could not be inserted into the PIUnitBatch collection of the PIBatch.
PI Batch Generator (PIBaGen) Interface to the PI System 51 Appendix D: Error and Informational Messages
Error inserting the PIUnitBatch unitbatchid in the PIBatch batchid This error might occur if either the PIUnitBatch or the PIBatch was deleted or the user running the interface does not have proper rights to make the changes to PI Batch Database.
The UnitBatchID value does not contain a proper string. The PIUnitBatch on the PIUnit PIUnitName will not have UnitBatch ID The interface looks for values in UnitBatch ID Point for the PIUnitBatch ID. If that point does not contain a proper value then the PIUnitBatch will not have an ID. However, the interface will create the PIUnitBatch. Check the UnitBatch ID point values in the archive at the evaluation time (PIUnitBatch start time + Evaluation Delay) to determine what is wrong with that value.
The BatchIndex Point for the PIUnit PIUnitname does not contain a proper value. Check the archive for the value of PIBatch Index point at PIUnitBatch evaluation time (PIUnitBatch start time + Evaluation Delay).
Error in adding a SubBatch with the name SubBatchname under the PIUnit PIUnitname The interface could not start a new PISubBatch on the PIUnit ‘PIUnitname’. The error could occur if that PIUnitBatch is deleted or the user running the interface does not have the proper rights to add PISubBatches. The error could also be because the PISubBatch name has some illegal characters. Check the PI-SDK to see what the illegal characters are for a PISubBatch name.
Error in stopping the SubBatch SubBatchname under the PIUnit PIUnitname The interface could not stop a SubBatch on the PIUnit ‘PIUnitname’. The error could occur if that PISubBatch is deleted or the user running the interface does not have the proper rights to modify PISubBatches.
The newly added module is not of interest This is an informational message and it is generated when a new module has been added to the PI Module Database and the interface recognized this change but realizes that the new module is not of interest.
Reference to registered PIUnits was deleted. Interface will stop monitoring all the registered PIUnits Reference to all the registered PIUnits is maintained in the PI Module Database. This reference is lost. Open the configuration tool and refresh the list of registered PIUnits and if that list says that there are no registered units, that confirms this change. Re-register all the PIUnits. This error occurs even when the module ‘PIBaGen’ under %OSI has been deleted or renamed.
Connection to the PIServer servername is lost... Waiting for connection This error occurs when the interface tries to write to/ read from the PI Serve and if the connection to the PIServer is lost. When this error occurs, the interface suspends action and waits for the connection to be re-established. A message is printed in regular intervals to indicate that the interface is still attempting to connect to the server. Check 52 the connection using other PI tools. If other PI tools can connect, wait for few minutes to allow the interface to realize that the connection is re-established. If that doesn’t seem to be the cause for error, check the user privileges to connect to the PI Server.
PI ModuleDatabase on the server servername is not available. PIArchive or PIBase subsystem might be shutdown. Waitinf for PIModule Database to be available... This error occurs when either the PI Base Subsystem or PI Archive is unavailable. The interface tests this condition by performing a PIUnitBatchSearch on the PIModule Database on that PI server. If there are other reasons for that UnitBatch search to fail, this error will still occur and other error messages should indicate the actual reason. When this error occurs, the interface suspends action and waits for the PI Module Database to be available again. A message is printed in regular intervals to indicate that the interface is still attempting to reach the PI-MDB. Check the connection using other PI tools. If other PI tools can connect, wait for few minutes to allow the interface to realize that the PI-MDB is available. If that doesn’t seem to be the cause for error, check the user privileges to connect to the PI Server.
Error is [-2147220214]: Failed to add item to server database.[-11008] Attempted to Add Event With Invalid Data Type This error commonly occurs while adding a PIUnitBatch to a PIUnit. The most common scenario for this error is during “backfilling” the batches. If the PIUnit was created after the primary archive start time and if the recovery is attempted from a time before the primary archive start time this error occurs. For example, if the primary archive start time is 26-Jan-04 10:01:56 AM and the PIUnit is created on 27-Jan-04 03:15:00 PM, and if the recovery time is ‘2’ days, then all the attempts to add PIUnitBatches on this PIUnit until 26-Jan-04 10:01:56 AM will fail with the above error. The solution is to reprocess the old archives (just like it is done for backfilling data to a PI Point) and then attempt recovery. Error is [-2147220214]: Failed to add item to server database.[-102] Record Not Found (Empty) This error commonly occurs while backfilling PIUnitBatches. If the archive that includes the start time of the PIUnitBatch is not the primary archive and if it was shifted prior to creation of the PIUnit then the interface fails to add a PIUnitBatch for this PIUnit. The solution is to reprocess the old archives (just like it is done for backfilling data to a PI Point) and then attempt backfilling. There is no online Archive for the target time. The interface will check every 30 seconds. This error commonly occurs when an archive is not available for the PIUnitBatch or PIBatch start time. Either there is no archive for this time period or the archive is not registered. Make sure that there is an archive available for that time period. Cannot Migrate: Error Retrieving the PIUnit The PIUnit cannot be found at the specified location. Check the path in the ‘ExDesc’ attribute for the PIBaGen 1.x PIPoint. Cannot Migrate: Invalid Module Path Path in ExDesc does not start with \\. Modify the ‘ExDesc’ for the corresponding PIPoint. Cannot Migrate: PIModule is not a PIUnit
PI Batch Generator (PIBaGen) Interface to the PI System 53 Appendix D: Error and Informational Messages
PIModule does not have IsPIUnit set to true. IsPIUnit should be set to true for the interface to generate batch data. Cannot Migrate: Configuration module not found PIUnit is probably not configured for PIBaGen 1.x. Configure this PIUnit for PIBaGen 2.x. There is no need to migrate this PIUnit. Cannot Migrate: Already has SubBatch Hierarchy PIUnit has second level SubBatches already defined. This PIUnit is probably migrated. Use PIBaGenCfg 2.x to make configuration changes. Cannot Migrate: Does not contain PIBaGen1.x configuration This PIUnit has SubBatch configuration that is not compatible with PIBaGen 1.x. This PIUnit is probably migrated. Use PIBaGenCfg 2.x to make configuration changes. Migration completed but with errors: See below for details There were errors while migrating. Check the Error Messages box at the bottom of the ‘Migration Chart’. Error Registering the Unit PIUnit was migrated but not registered. Register again using PIBaGenCfg. Error changing attributes for configuration point Error setting either the ‘Scan’ to zero or ‘userint1’ to 1 for the configuration point. Use DataLink or PointBuilder to change those two parameters for that PIPoint. Error renaming configmodulename configuration module to "PIBaGen 1.x Configuration-Migrated" There is an error renaming the PIBaGen 1.x configuration module. Check if a PIModule named ‘PIBaGen 1.x Configuration-Migrated’ doesn’t exist already. If it did, probably the PIUnit is already migrated. Change the ‘userint1’ attribute to 1 for the corresponding PIPoint. 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 Descriptions of system and PI errors can be obtained with the pidiag utility: \PI\adm\pidiag –e error_number
54 Revision History
Date Author Comments 12-Oct-2000 JHP Written 29-Aug-2002 SG Rewrote the manual based on the previous version. 02-Dec-2002 SG Manual for version 2.0 before coding 21-Feb-2003 SG Made minor corrections in the manual 23-Oct-2003 SG Updated the document after development 23-Jan-2003 SG Updated for Beta release 28-Jan-04 CG 2.0.0.6 beta Rev A: Formatted to interface skeleton; fixed headers & footers; enhanced the security section; added comments that the interface doesn’t make use of the PI-ICU or bufserv. 01-Apr-04 SG Updated for version 2.0.0.9 02-Apr-04 CG Rev A: Fixed headers; fixed some typos 05-Apr-04 SG Added a section on backfilling batch data 08-Apr-04 CG Rev C: Fixed section breaks, headers & footers, TOC 08-Apr-04 SG Rev D: Added a section on required additional PI Software 08-Apr-04 CG Rev E: Fixed section break and updated TOC
PI Batch Generator (PIBaGen) Interface to the PI System 55