Event File Interface to the PI System -...

Event FileInterface to the PI System

Version 3.8.7.0

Copyright © 2002-2009 OSIsoft, Inc.

OSIsoft, Inc. 777 Davis St., Suite 250San Leandro, CA 94577 USA(01) 510-297-5800 (main phone)(01) 510-357-8136 (fax) (01) 510-297-5828 (support phone) http://[email protected], TX Johnson City, TN Longview, TX Mayfield Heights, OHPhiladelphia, PAPhoenix, AZ Savannah, GA

OSIsoft AustraliaPerth, Australia

OSI Software GmbH Altenstadt, Germany

OSIsoft Asia Pte Ltd.Singapore

OSIsoft Canada ULCMontreal, CanadaCalgary, Canada

OSIsoft, Inc. Representative OfficeShanghai, People’s Republic of China

OSIsoft Japan KKTokyo, Japan

OSIsoft Mexico S. De R.L. De C.V.Mexico City, Mexico

OSIsoft do Brasil Sistemas Ltda.Sao Paulo, Brazil

Sales Outlets/DistributorsMiddle East/North AfricaRepublic of South AfricaRussia/Central Asia

South America/CaribbeanSoutheast AsiaSouth Korea Taiwan

www.osisoft.comAll rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, Inc.

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

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph I(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

iii

http://www.osisoft.com/

mailto:[email protected]

http://techsupport.osisoft.com/

Table of Contents

Terminology...................................................................................................................viiIntroduction......................................................................................................................1

Reference Manuals........................................................................................................1

Supported Features........................................................................................................1

Diagram of Hardware Connection..................................................................................5

Principles of Operation...................................................................................................7Event Journals................................................................................................................7

Syntax Variations in Batch Execution Systems..............................................................7

Processed Event Journals............................................................................................10

Definition of ‘Batch’.......................................................................................................10

Recipe Model vs. Equipment Model.............................................................................10

Methodology.................................................................................................................11

PIBatch.....................................................................................................................12

PIUnitBatch...............................................................................................................12

PISubBatch...............................................................................................................13

Sub-PISubBatch.......................................................................................................13

Determining ProductID.............................................................................................14

Phase-Level Only Recipes.......................................................................................14

Arbitration Events Unavailable.....................................................................................14

PI Point and Unit Creation............................................................................................15

Foreign Language Support...........................................................................................16

Event Logging...............................................................................................................16

Unit specific Tags.........................................................................................................18

Merging EVT Files into a Single PIBatch.....................................................................19

Merging Parallel PIUnitBatches into a Single PIUnitBatch in the Same Event File......22

Using /rsm Switch.........................................................................................................24

Lost Connections to PI Server and PI Archive Backup Issues.....................................25

Questionable Files........................................................................................................25

Reprocessing Questionable Files.................................................................................26

Event Based Time Ordered Processing.......................................................................26

Event File Interface to the PI System iii

Dealing with Irrelevant Units.........................................................................................28

Dealing with Irrelevant Phases.....................................................................................28

Example Event File Journal..........................................................................................29

Installation Checklist.....................................................................................................31Data Collection Steps...................................................................................................31

Interface Diagnostics....................................................................................................32

Interface Installation......................................................................................................33Naming Conventions and Requirements......................................................................33

Interface Directories.....................................................................................................33

The PIHOME Directory Tree.....................................................................................33

Interface Installation Directory..................................................................................34

Interface Installation Procedure....................................................................................34

Installing the Interface as a Windows Service..............................................................34

Installing the Interface Service with the PI ICU........................................................34

Installing the Interface Service Manually..................................................................36

Digital States..................................................................................................................39PointSource....................................................................................................................41PI Point Configuration...................................................................................................43

Interface-specific Points...............................................................................................43

Point Attributes.............................................................................................................43

Tag............................................................................................................................43

PointSource..............................................................................................................44

PointType..................................................................................................................44

Location1..................................................................................................................44

Location2..................................................................................................................44

Location3..................................................................................................................45

Location4..................................................................................................................45

Location5..................................................................................................................45

InstrumentTag...........................................................................................................45

ExDesc.....................................................................................................................46

Scan..........................................................................................................................46

Shutdown..................................................................................................................47

Startup Command File...................................................................................................49Configuring the Interface with PI ICU...........................................................................49

evtintf Interface page....................................................................................................51

Event File Interface to the PI System iv

Command-line Parameters..........................................................................................59

Sample EVTIntf.bat File................................................................................................81

Interface Node Clock.....................................................................................................83Security...........................................................................................................................85Starting / Stopping the Interface..................................................................................87

Starting Interface as a Service.....................................................................................87

Stopping Interface Running as a Service.....................................................................87

Buffering.........................................................................................................................89Interface Diagnostics Configuration............................................................................91

Scan Class Performance Points...................................................................................91

Performance Counters Points......................................................................................92

Interface Health Monitoring Points...............................................................................96

I/O Rate Point.............................................................................................................103

Interface Status Point.................................................................................................104

Appendix A: Error and Informational Messages.......................................................107Message Logs............................................................................................................107

Messages...................................................................................................................107

Questionable Batches................................................................................................111

System Errors and PI Errors......................................................................................112

Appendix B: PI SDK Options......................................................................................113Appendix C: BES Configuration Requirements........................................................115

Introduction.................................................................................................................115

Background.............................................................................................................115

Objectives...............................................................................................................115

Principles of Operation...............................................................................................115

Principles of the PI Server Batch Database...........................................................115

Principles of the PI EVTIntf Interface......................................................................116

Recommendations for BES Recipes and Equipment Models....................................117

Appendix D: Event File Directory Sync Utility..........................................................121Introduction.................................................................................................................121


Utility Installation Procedure.......................................................................................121

Installing the Utility as an NT Service.........................................................................122

Startup Command File................................................................................................122

Command-line Parameters.....................................................................................122

Event File Interface to the PI System v

Table of Contents

Sample EVTSync.bat File.......................................................................................123

Starting / Stopping the Utility......................................................................................123

Starting the Utility Service.......................................................................................123

Stopping the Utility Service.....................................................................................123

Conclusions................................................................................................................123

Appendix E: EVT Cleaning Utility...............................................................................125Introduction.................................................................................................................125


Analyzing Data Contents in PI................................................................................126

Deleting Data from PI............................................................................................126

Updating Data in PI................................................................................................126

Foreign Language Support.....................................................................................127

Utility Installation Procedure.......................................................................................127

Starting the EVT Cleaning Utility Application..........................................................127

Stopping the EVT Cleaning Utility Application........................................................127

Startup Command File................................................................................................127

Required Command-line Parameters.....................................................................127

Optional Command-line Parameters......................................................................129

Sample EVTCleaningUtility.bat File........................................................................140

Revision History.............................................................................................................141

vi

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

ICUICU refers to the PI Interface Configuration Utility. The ICU is the primary application that you use in order to configure and run PI interface programs. You must install the ICU on the same computer on which an interface runs. A single copy of the ICU manages all of the interfaces on a particular computer.

You can configure and run an interface by editing a startup command file. However, OSIsoft discourages this approach. Instead, OSIsoft strongly recommends that you use the ICU for interface management tasks.

ICU ControlAn ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common to all interfaces, an ICU Control implements interface-specific behavior. Most PI interfaces have an associated ICU Control.

Interface NodeAn Interface Node is a computer on which

the PI API and/or PI SDK are installed, and

PI Server programs are not installed.

PI APIThe PI API is a library of functions that allow applications to communicate and exchange data with the PI Server. All PI interfaces use the PI API.

PIHOMEPIHOME refers to the directory that is the common location for PI client applications. A typical PIHOME is C:\Program Files\PIPC. PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME. For example, files for the Modbus Ethernet Interface are in C:\Program Files\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME directory. For example, ICU files in [PIHOME]\ICU.

PI SDKThe PI SDK is a library of functions that allow applications to communicate and exchange data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of the PI SDK.

PI Server NodeA PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node.

Event File Interface to the PI System vii

Terminology

PI SMTPI SMT refers to PI System Management Tools. PI SMT is the program that you use for configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs on either a PI Server Node or a PI Interface Node.

pipc.logThe pipc.log file is the file to which OSIsoft applications write informational and error messages. While a PI interface runs, it writes to the pipc.log file. The ICU allows easy access to the pipc.log.

PointThe PI point is the basic building block for controlling data flow to and from the PI Server. For a given timestamp, a PI point holds a single value.

A PI point does not necessarily correspond to a “point” on the foreign device. For example, a single “point” on the foreign device can consist of a set point, a process value, an alarm limit, and a discrete value. These four pieces of information require four separate PI points.

ServiceA Service is a Windows program that runs without user interaction. A Service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.

The ICU allows you to configure a PI interface to run as a Service.

Tag (Input Tag and Output Tag)The tag attribute of a PI point is the name of the PI point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms “tag” and “point” interchangeably.

Interfaces read values from a device and write these values to an Input Tag. Interfaces use an Output Tag to write a value to the device.

viii

IntroductionThe Event File interface to the PI Data Archive gathers information from event journal files (.evt files), which are generated by batch execution systems (BESs) based upon Sequencia’s OpenBatch product. Examples of these batch systems include Rockwell Software’s RSBatch 5.0 (formerly Sequencia’s OpenBatch 5.0), Emerson’s DeltaV Batch Executive, Honeywell’s Total Plant Batch 2.2, and Intellution’s iBatch 4.1.30.

Note: This interface requires PI Server version 3.3 SR 2 or higher and the PI SDK version 1.2.0.180 or higher.

Since the event journal file is a flat ASCII file, data can only be written to the PI system. Outputs back to the BES are not allowed within the scope of this interface.

An Arbitration event occurs whenever a batch takes ownership of a physical unit or equipment module. Several batch recipe execution systems (or batch execution systems, BESes) such as Sequencia’s OpenBatch previous to version 4.0.0.81 and all licensed variants based on those versions, generate event journals, but do not list Arbitration events. The interface can be configured to account for this. However, depending upon the methods used for recipe execution, the start and end times of PI Batch Database objects (e.g. PIUnitBatches and PISubBatches) are only approximate due to the bracketed timeframe that is used without Arbitration events.

Reference ManualsOSIsoft

PI Data Archive Manual

PI API Installation Instructions

UniInt Interface User Manual

VendorThe user is advised to review the pertinent documentation regarding the particular BES that they are using. In addition, the user is also advised to maintain familiarity with the contents and format of the Event File journal such that appropriate options and features of the interface may be properly chosen.

Supported FeaturesFeature Support

Part Number PI-IN-OS-BEFM3-NT

* Platforms Windows 2000/XP/2003 (NT4 not supported)

APS Connector No

Point Builder Utility No

ICU Control Yes

PI Point Types real / digital / integer / float32 / float16 / string

Event File Interface to the PI System 1

Feature Support

Sub-second Timestamps Yes

Sub-second Scan Classes No

Automatically Incorporates PI Point Attribute Changes

Yes

Exception Reporting No

Outputs from PI No

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

Event and Scan-based

Supports Questionable Bit No

Supports Multi-character PointSource Yes

Maximum Point Count None

* Uses PI SDK Yes

PINet String Support N/A

* Source of Timestamps Device

* History Recovery Yes

* UniInt-based Disconnected Startup* SetDeviceStatus

Yes NoYes

Failover No

Vendor Software Required on PI Interface Node / PINet Node

No

* Vendor Software Required on Foreign Device

Yes

Vendor Hardware Required No

Additional PI Software Included with Interface

No

* Device Point Types String Only

Serial-Based Interface No

*See paragraphs below for further explanation.

PlatformsThe Interface is designed to run on the above mentioned Microsoft Windows operating systems. Because it is dependent on vendor software, newer platforms may not yet be supported. Please contact OSIsoft Technical Support for more information.

Use PI SDKThe PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface specifically makes PI SDK calls to create PI Points, access PI Module Database, and PI Batch Database.


Source of TimestampsSince each record in the event journal file contains a timestamp and the interface itself is solely scan-based, use of the time at record processing could introduce inherent latency with respect to establishing the event time. Thus, the timestamp accompanying the record is used as the source of the timestamp for the data to be placed into the PI system.

History RecoveryThe operation of the interface may be interrupted without loss of data as long as the event files continue to be generated properly by the batch execution system. The interface monitors the specified directory where the event journal files are located. It then processes any new files or ones which have received new entries since it last checked the directory.

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

The UniInt Interface User Manual is a supplement to this manual.

SetDeviceStatusThe EVT Interface is built with UNIINT 4.3.2.8. Performance has been improved on tag loading during interface startup. New functionality has been added to support non-output health tags. The Health tag with the point attribute Exdesc = [UI_DEVSTAT], is used to represent the status of the source device. The following events can be written into the tag:

a) “Good” – the interface is properly communicating and reading data from the folders containing Event file journals and position files associated with them.

b) “2 | Connected/No Data | No *.evt files in monitored directory” – the interface is properly communicating with the folders containing Event File Journals and position files associated with them. This message shows that there are no active Event Journal Files.

c) The following list of events represents the failure to communicate with either the Event Journal file directory or Position directory, or failure to read data from the Event Journal File:

“3 | 1 devices(s) in error | Monitored Directory does not exist”

“3 | 1 devices(s) in error | Monitored directory not found”

“3 | 1 devices(s) in error | Position file directory not found”

“3 | 1 devices(s) in error | Failed to get monitored directory snapshot”

Please refer to the UniInt Interface User Manual.doc file for more information on how to configure health points.


Introduction

Vendor Software RequiredThe BES and its accompanying support software are required for proper operation of the Event File interface.

Device Point TypesSince the event journal file is a flat ASCII file, all data contained within it is of string ASCII type. The interface attempts to coerce the string data into numerical equivalents where possible. If automatic point creation is used, the interface will attempt to coerce data into 32-bit floating point format if necessary.

4

Diagram of Hardware ConnectionFigure 1. Schematic of Recommended Hardware and Software Configuration for Event File Interface

The interface may either be installed on the same node as the batch execution system (BES) or the PI Server or on a completely separate node. Due to load balancing considerations, OSIsoft does not recommend that the interface be installed on the same node as the PI Server. Contact the vendor of your BES for recommendations as to installing third-party software, such as the Event File Interface, on the same node as the BES.


Principles of OperationThis section contains relevant information to help the user better understand some of the primary logic of the Event File interface.

Event JournalsEvent journals are files that are generated by a batch execution system. These files contain a log of events that occur during the execution of a recipe. The following is a partial list as an example of the types of events that are recorded in an event journal:

Arbitration (of units and equipment modules) Recipe Values System Messages State Changes Owner Changes Reports Param Download Verification Scale Factors Batch Deletions State Commands

Users can select which of these message types will be saved by the interface. Because event messages are stored as strings in the PI Batch Database, specifying fewer types of messages to be stored may have a significant impact on the performance of both the PI Server and any client retrieving the data from the PI Server.

Syntax Variations in Batch Execution SystemsContrary to popular belief, the syntax used in event journals between BES types has enough variance to warrant that the customer must be aware that such differences exist. Different BESes use slightly different syntax and event types. To date, there are 36 known types of events that occur in event journals.

# Event Type Present in which BES

1 Active Binding iBatch

2 Active Step Change All

3 Active Step Change Commencing All

4 Arbitration Honeywell, RSBatch (OpenBatch)

5 Batch Deletion All

6 Bind All

7 Comment All

8 Creation Bind All

9 Event File Name All

10 Formula Header All



11 Mode Change All

12 Mode Command All

13 Operator Prompt All

14 Owner Change All

15 Param Download Verified All

16 Phase Link Permissive Received All

17 Phase Link Permissive Sent All

18 Phase Logic Arbitration All

19 Prompt All

20 Prompt Response All

21 Recipe Arbitration DeltaV

22 Recipe Data All

23 Recipe Data Changed All

24 Recipe Header All

25 Recipe Value All

26 Recipe Value Change All

27 Report All

28 Scale Factor All

29 State Change All

30 State Command All

31 Step Activity All

32 System Message All

38 Equipment Prompt DeltaV 8.3+

39 Equipment Selection DeltaV 8.3+

40 Phase Batch Request DeltaV 8.3+

41 Unit Alias Binding DeltaV 8.3+

42 Unit Verified RSBatch

43 Attribute Change RSBatch

44 Transition Control DeltaV 9.3+

45 Automatic Removal RSBatch

46 ControlStep START RSBatch

47 ControlStep STOP RSBatch

48 Instruction Complete RSBatch

49 Material Bound RSBatch

50 Material Tracking RSBatch



51 Material Unbound RSBatch

52 Promise Event RSBatch

53 Report Parameter Deviation RSBatch

54 Signature Request Cancelled RSBatch, TotalPlantBatch

55 Signature Request Completed RSBatch, TotalPlantBatch

56 Signature Request Created RSBatch, TotalPlantBatch

57 Step Reactivation RSBatch

58 Step Reactivation Request RSBatch

59 Successful Signoff RSBatch, TotalPlantBatch

60 Unsuccessful Signoff RSBatch, TotalPlantBatch

That is, the physical equipment arbitration events vary from BES implementation to BES implementation. This highlights the fact that while OSIsoft attempts to implement a set of common logical rules across all implementations, this is not possible in all situations.

The syntax from various vendors’ versions of the event journal varies slightly. Given these variations, the user generally must specify their BES type using the (/bestype command-line switch). In particular, delimiters between the recipe hierarchy levels and the formatting of individual event records may vary as a function of the BES type. The interface expects that each record in the event file will contain at least 14 tab-delimited columns (15 columns for DeltaV 8.3+) and that the first 14/15 columns contain the following information in the following order:

Column1: Timestamp (either LclTime or GMTTime)Column2: BatchIDColumn3: RecipeColumn4: DescriptColumn5: EventColumn6: PvalueColumn7: EUColumn8: AreaColumn9: ProcCellColumn10: UnitColumn11: PhaseColumn12: PhaseDescColumn13: UserIDColumn14: UniqueIDColumn15: Comment (DeltaV only)

All columns after the 15th can be stored in PI, but are not currently used by the interface to trigger any additional logic.

Processed Event JournalsOnce the interface processes an event file successfully, the interface renames the file to *.999. This is necessary to keep track of the processed files. However, some times renaming the file may not be a viable solution. There are two ways of resolving this issue. First, the /rdt (Rename Delay Time) switch in the interface command line will delay the


Principles of Operation

renaming of the file by specified time after it finishes processing the file. The second option is to use the PI Event File Directory Sync Utility (See Appendix C) to copy the original files to the directory monitored by the interface. This utility will sync the original and destination directories at a specified frequency. Read Appendix C before using this utility.

Definition of ‘Batch’A single event journal is generated per execution of a recipe. The term ‘batch’ will be used to indicate the material produced by a single execution of a recipe. In other words, each event file will represent a distinct batch. If the merge switch is used, one batch represents multiple event files. Please refer to “Merging Event Files into one PIBatch” section on how the merge works.

Recipe Model vs. Equipment ModelTwo distinct yet related models are used to describe batch processes. These are the Recipe Model and the Equipment Model. Diagrams depicting hierarchical structures, in particular those for an S88-compliant hierarchical structure, of these models are shown in Figures 2 and 3. The Equipment Model describes the physical equipment necessary to create a batch while the Recipe Model describes the procedures, which are performed during the execution of a recipe. There is no intrinsic or direct relationship between the levels of the Equipment Model and the Recipe Model. With the exception of Arbitration events, journal files contain only Recipe Model event information.

It should be noted that within S88, the use of procedures and unit procedures is optional. A recipe may be defined consisting of only operations and phases.

Figure 2. Recipe Model hierarchy

Figure 3. Equipment Model hierarchy

10

Procedure

Unit Procedure

Operation

Phase

Process Cell

Unit

Equipment Module

Control Module

Area

The Event File interface uses S88 terminology and hierarchy as framework to attempt to collate and store information in a structured manner within the PI Module and Batch databases.

The Event File interface makes the assumption that a unit procedure maps directly to a PI UnitBatch. This assumption implies that only a single unit procedure can be active in a unit at any given time for the event file interface to be able to process the file and populate the BDB objects. This lays a fundamental restriction on the configuration of recipes that may be run by the BES, if the Event File interface is to be used to process the resultant event journals and populate the BDB in a meaningful manner. In the cases where the recipe contains more than one active unit procedure for a given unit, the Event File interface should be run with merge switch for entering that data into the PI server. Please refer to “Merging Event Files into one PIBatch” section on how the merge works.

MethodologyThe PI Module Database is used to organize and store batch data. Further discussion of this database can be found in the PI 3.3 Data Archive Manual and the PI SDK tutorial documentation. This interface creates PIBatch, PIUnitBatch, PISubBatch, and Sub-PISubBatch objects within the PI Batch Database to represent the recipe procedures, unit procedures, operations, and phases, respectively. Each of the objects created in the PI Batch Database will possess the following properties in common:

Name batch ID start time end time

Note that, in a PIBatch the name is stored in the Recipe property and in a PIUnitBatch the Procedure property is used to store the name of the corresponding recipe level. Each object in the PI Batch Database represents a specific level of the Recipe Model. However, the relationship between the PI Batch Database and the Recipe Model is complicated by the possibility of building a recipe without the procedure or unit procedure levels. In cases where the highest recipe level is an operation (i.e. neither procedure nor unit procedure levels are defined), PIBatch and PIUnitBatch objects must still be created by the interface. However, the PIBatch and PIUnitBatch will not have names assigned to them.

PIBatchA PIBatch will be created for each event journal processed. All messages within an event journal will be recorded in the PIProperties collection of a PIBatch. The structure of the



PIProperties collection will be organized to reflect the hierarchy of the Recipe Model described by the journal file. First, the record is parsed into its individual fields. Then, the event is checked to see if it is to be recorded in PI. If the event is to be stored (i.e. not excluded, see /exc option), then the event string (all fields except the batch-id and recipe hierarchy) are saved as the value of the PI Property of the event, which is in itself a member of the PI Property hierarchy under the appropriate recipe level. The field names are known from the first line of the event file and are saved for reference in the base level of the PIProperties collection for the batch. The event’s timestamp and event type identifies the event.

A PIBatch represents the collection of procedures within the recipe. Each PIBatch will contain a collection of associated PIUnitBatches (which correspond to the Unit Procedures in the recipe).

The system messages “Beginning Of BATCH” and “End Of BATCH” will be used to mark the start and end times of a PIBatch respectively.

If no Procedure level for the recipe exists, the interface will still create a PIBatch object whose start and end times are triggered by the “Beginning Of BATCH” and “End Of BATCH” messages.

The PIProperties collection for the batch is revised under three conditions:

1. When the batch is first started (i.e. the “Beginning Of BATCH” system message is received), 2. When the batch ends (i.e. the “End Of BATCH” system message is received, and 3. When the file is processed after each scan class. This is done to minimize the number of times that PIBatch’s PIProperties collection is modified. The user is allowed to specify that specific events types can be stored in string tags for more immediate access through PI client tools.

PIUnitBatchA PIUnitBatch is created for each unit procedure defined in a journal file. The start and end times of a PIUnitBatch are intended to reflect the onset and completion of physical processing within a unit. The start time is determined by either the time of the “Unit Acquired” Arbitration event or the System Message event “Unit Procedure Started,” whichever event occurs last. In other words, the unit procedure must “start” and the unit must be acquired before the start time of the PIUnitBatch is assigned. The end time for a PIUnitBatch is determined by the time of the “Unit Released” Arbitration event or the System Message “Unit Procedure Finished,” whichever event occurs first. In other words, the unit procedure must “finish” or the physical unit must be released for the end time to be assigned.

If no unit procedure is defined for the recipe (i.e. the operation level of the recipe is the highest level), a PIUnitBatch object is still created. The start time is determined by either the time of the “Unit Acquired” Arbitration event or the System Message event “Operation Started,” whichever event occurs last. The end time for a PIUnitBatch is determined by the time of the “Unit Released” Arbitration event or the System Message “Operation Finished,” whichever event occurs first. The Procedure Name property is same as the Operation name and the 12atched property is same as the 12atched in the event journal.

12

PISubBatchA PISubBatch will be created for each operation found within a journal file. The start and end times of a PISubBatch will be determined by the System Messages “Operation Started” and “Operation Finished” respectively. If the recipe is an Operation Level recipe, the logic is analogous to that used with the PIUnitBatch, the start and end times of a PISubBatch will be determined by unit acquisition/release and the System Messages “Operation Started” and “Operation Finished.” Each PISubBatch will be added to the PISubBatches collection of the PIUnitBatch.

Sub-PISubBatchA Sub-PISubBatch will be created for each phase defined within a journal file. The start time for Sub-PISubBatch will be set by the state change events “RUNNING”, “STARTING”, “RESTARTING”, “DOWNLOADING”, “UPLOADING” or “UNKNOWN STATE”, whichever occurs first for that Sub-PISubBatch. The end time for Sub-PISubBatch will be set by the state change events “COMPLETE”, “STOPPED” or “ABORTED” which ever occurs first. If “COMPLETE”, “STOPPED” or “ABORTED” event occurs without a start time event change, then a zero second Sub-PISubBatch is created. All other state change events do not modify a Sub-PISubBatch start or end time. Each Sub-PISubBatch will be added to the PISubBatches collection of the parent PISubBatch.

In some cases, the name of the instance of the phase class that is running is not easily linked to the equipment module or phase that has been defined. In this case, the interface can be configured to combine equipment and recipe names (/cern). The interface then stores the Sub-PISubBatch name as a combination of both the equipment and recipe phase names.

By default, the Interface creates an additional PI SubBatch level. This corresponds to the S88 Phase State. When a State Change is detected for a phase, the previous PI SubBatch phase state object is closed, if it exists, and if the S88 state is anything other than “IDLE”, “READY”, “ABORTED”, “STOPPED” or “COMPLETE,” then the interface creates a PI SubBatch named after the S88 state and with a start time corresponding to time of the State Change event. This feature can be disabled by using the /sps (suppress phase state) command parameter.

Starting with the version 3.8.6.4, the interface can create an additional PI SubBatch level – Phase Step. This feature is enabled with the use of the optional switch /ras=<start, end> (Report As Step). The Phase Steps are created beneath the active Phase State PI SubBatch. The Phase Step name and start/stop events are coming from the “Descript” column. The triggering event is “Report”. The Phase Steps will not create the higher level PI Batches, UnitBatches and SubBatches, if the parent Phase is not found. If the Phase Step was not closed by the appropriate closing event, it will be closed by the end of the parent Operaion level PI SubBatch. 0-duration Phase Steps are ignored. Multiple sequential Start/End events are ignored except the first one.

Determining ProductIDThe Event File contains the Product ID information. This information is stored as the Pvalue in the row that contains the description “Product Code”. Typically this is a Recipe Header event. However, if there is some other description instead of “Product Code”, then the language translation file can be used to change the description value that the



interface looks for. For example, if the “Product Value” is used in the Event File, then the language translation file can be set so that “Product Value” is same as “Product Code”.

The /product switch can also be used to specify the ProudctID. When this switch is specified with a value, the interface uses this value as the ProductID only if the Event File does not contain product information or if the value in the Event File is “UNDEFINED” (case insensitive). This switch is available only with version 3.7.0.15 and greater.

The same ProductID will be used for a PIBatch and a PIUnitBatch within the same Event File.

Phase-Level Only RecipesPhase-level only recipes are not supported with the EVT interface, due to the fact that phase-level recipes do not necessarily contain unit-level arbitration information. Since the user actions with respect to the unit level arbitration are not found in the event journal when a phase-level recipe is run and such information is vital in properly placing the data into PI, phase-level recipe event files are not supported in this interface.

When the interface encounters a phase-level recipe, it will create a PI Batch with the standard start and end times. However, no PI UnitBatch or PI SubBatches will be created for that event file. The PI Properties for the PI Batch and any event string tags required by the application set up will be created and used normally.

Arbitration Events UnavailableThe behavior described above is the default behavior of the interface. However, if the batch execution system does not generate Arbitration events, the user may select the option “Arbitration events unavailable” (/aeu). (This parameter would likely be used with older versions of the BESs from Sequencia, Rockwell, Intellution, Fisher DeltaV, or Honeywell.) With this option chosen, the start time of PIUnitBatches will be determined by the later of either “Unit Procedure Started” and the start of a sublevel (Operation or Phase) event in that unit. The end time of PIUnitBatches will be determined by the earlier of the “Unit Procedure Finished” message and end of the last sublevel in that unit. If no unit procedures have been defined (i.e. operation is the highest recipe level), the start of the first phase will mark the start time of the PIUnitBatch, PISubBatch and the first Sub-PISubBatch. The end of the last phase (as determined by the presence of the “Operation Finished” system message) will mark the end time of the PIUnitBatch, PISubBatch, and that last Sub-PISubBatch. In this case, the PIUnitBatch and PISubBatch will have the same start and end times.

Note that if Arbitration events are unavailable, the triggering of the PIUnitBatches from the Event File is only imprecisely bracketed by the Unit Procedure Started/Finished events and the start/end of the sublevels of the recipe. The Arbitration event is the most explicit method of determining the allocation of a physical unit to a given instance of a recipe.

PI Point and Unit CreationThe interface will perform automated unit creation within PI. PI Units (PIModules with the IsUnit flag set to true) are created when they are first encountered in an event file. A known units list is maintained so that the interface knows which units need to be created. The interface can prefix the PI Modules, including the unit name, with a BES identifier to

14

avoid confusion with similarly named units in other trains (/besname=<BES ID> switch).

The interface will create PI Modules for both the Area and Processing Cell specified in the event journal. By default, the placement of these modules is at the root level of the Module DB. The user can define a separate starting point by using the (/smp switch). The structure of the PI module hierarchy that is utilized by the interface is depicted in Figure 4.

<Area><ProcCell>

<Unit> [Alias Collection] Status Phases

<PhaseName><EventType> [Alias Collection]

Figure 4: Interface Generated PI Module DB Structure

Item/names in the angled brackets (<>) are placeholders for names that are specified in the event file. Aliases are created at the <Unit> and <EventType> levels. The unit level aliases can be suppressed with the /sula switch.

Points are created by the interface when first encountered. The aliases for the unit to the points are created once the unit definition is completed. The naming convention for created points are <unitname>(<phase>):<descript>-<eventtype>. The interface allows two switches that will disable the automatic point and unit creation features. These are the /spc (Suppress Point Creation) and /suc (Suppress Unit Creation) switches. PIAlias creation is suppressed when unit creation is suppressed. In case of a language file used to translate the <eventtype>, the /uen (Use English Names) allows using only the English Name for the <eventtype> rather than using the language used in the file. See the section on Interface Operation for more detail on these switches.

Since it is not possible to generally determine if a unit name change in the batch execution system corresponds to the creation of a new unit or merely an edit to the name (i.e. whether point history associated with a particular unit should be maintained), the interface is unable to determine the users motive a priori and must assume a default behavior. In this case, the interface assumes that a new name is a completely separate unit. If this is not the desired behavior, then the user should disable unit creation (using the /suc switch). The user will then be required to edit the Module Database, incorporating into the Module Database any changes made on the BES.

Foreign Language SupportThe Event File interface supports languages other than English by providing for the use of a look-up table for the various event types that trigger specific events in the interface. Note that this is not necessarily all of the events that are possible in the event journal, only a select few are required: those, which are primarily used to trigger the start and end times of the PI Batch objects. However, if a user intends to base an action (such as excluding an event type from being saved in the PI Properties or trying to specify an event type for logging to a string tag), then the translation of that event must be supplied. A sample language string file, containing the syntax and events necessary for the interface is included with the interface distribution. This file is used only when the “/langpath=<path>” switch is used. If the switch is not used, then the default



language of English is assumed. If /uen switch is used, the language translation is still done for comparison, but the event type used in naming tags, aliases, and modules will be in English.

Event LoggingBesides the creation and population of PI Batch DB objects, there are 3 methods by which the specific events from EVT file can be saved into the PI system. These 3 methods are:

1. The interface can store the individual events to the PI Properties hierarchy of the PI Batch.

2. The interface can store each event type to a separate string tag for each event.

3. The interface can create new tags (and link them to a unit with a PI Alias) when it encounters numeric or string data that it can store in the PI database when Event Types “Report”, “Param Download Verified”, “Recipe Value”, “Owner Change” and “Prompt” are encountered.

These three functions are separate actions triggered independently under different sets of criteria. If a given event fulfills the separate criteria (they are not mutually exclusive), then each of the actions will be triggered in turn.

PI Batch PI Properties CollectionThe PIProperties collection of the PI Batch object is revised each time new events are detected. When revised, the PI Properties collection has all known events in the event journal placed hierarchically into the collection. The type of events that are saved can be moderated by use of the “/exc=<event type>” switch. It is not generally recommended that the user store all of the events in the event file in the PI Properties, since a number of the events are used to trigger logic and therefore, would be saved in a redundant manner. In addition, the saving of all of the event records in the PI Batch can lead to object bloat, which will affect performance of the PI server in accessing the PI Batch object (both in saving additional information and retrieving it for display).

The format of the event that is stored in the PI Batch PI Properties hierarchy contains all of the fields in the EVT file except the Batch ID and recipe hierarchy fields (generally columns 2 and 3 in the event record). These are not stored since the Batch ID is already in the PI Batch object and the recipe hierarchy is known from the position of the property in the PI Properties hierarchy. All columns of the PI Properties value are separated by the pipe (“|”) delimiter.

String Tag PoolIf the user wishes to be informed of a particular event type each time the event is encountered, they may specify an event type which the interface will specifically target and place all events of that type into a string tag upon detection of the event in an event journal. The interface keeps a pool of string tags specifically for this purpose. Use of this feature is specified with the “/logtotag=<event type>” switch. The event trigger types are specified at startup and therefore known at runtime, when a new event journal is detected the interface will set aside enough string tags to log the specified events. The names of the string tags and their event types are stored in the PI Properties collection of the PIBatch object under the “Recipe Messages->Event Tags” PI Property. Use of the point pool allows for efficient use of the points, while avoiding potentially confusing overlaps of timeframes for concurrent batches. Since the interface stores the

16

events in PI Batch PI Properties collection by default, it is not necessarily recommended that user store many event types to string tags.

The format of the string saved in the string tag differs from the string saved in the PI Properties collection. This is due to the fact that the event is stored at a particular time, but its position in the recipe hierarchy is not necessarily known. As such, all of the fields in the EVT record are saved in the event except the timestamp (which is known from the timestamp of the event in the archive) and the Batch ID (which is known from the PI Batch object which points to this string tag for the PI Batch’s active timeframe). Like the string format of the PI Properties, the string tag event has all of its EVT column values separated by the pipe (“|”) delimiter.

Specific Point GenerationIf a numeric or string value is encountered as the Pvalue for one of the given in the table below five different event types, then the interface will attempt to create a point to record that data. By default, the interface creates tags for all five event types. Starting with version 3.8.5.1, the interface has an option of creating tags for only specified event types. This feature can be enabled by using the command line switch /recipetags and providing the list of event types.

# Event Type

14 Owner Change

15 Param Download Verified

19 Prompt

25 Recipe Value

27 Report

The point type for such points is determined by the data type of Pvalue the first time the interface encounters that event on a unit for a phase. The point is not created until the event has a value. If the first value is string type and second value is numeric for the same event in the same phase on the same unit, a string type point is created and both values are stored as string values. However, if the first value is numeric and the second value is string, then a float32 point is created, the first value is recorded but the second value is not recorded. If such a situation is anticipated, it is recommended to manually create string tags for that event (see section on PI Point Configuration for more details). An optional switch /cost will create only string type points irrespective of the data type. This switch will only apply to new points created by the interface and does not impact data collection on already existing points. Every point created by the interface has a tag name defined by <unitname>(<phase>):<descript>-<eventtype>. If any of those parameters change, for example the same phase is run on a different unit, then a new tag will be created and the point type will again depend on the Pvalue. If the resulting tag name contains invalid characters, then the tag will be named “EVT_InvalidTagName_” appended by the point creation time in UTC seconds. A log message indicates if such a point is created and the name of that point can be changed manually to any suitable tag name at any time. Point creation can be suppressed with the /spc switch. PI Aliases are generated automatically if the interface creates a specific point. The PI Aliases definitions are triggered off of the point creation actions. If point creation is suppressed, interface does not generate the PIAliases. The PI Aliases at the <Unit> level may be suppressed using the /sula switch. The PI Aliases at the <Event Type> level are always generated. If the /uen switch is used, then only the <eventtype> in the tag name and alias



name will be in English and the <unitname>(<phase>):<descript> will be in the same language as recorded in the Event file.

Unit specific TagsThe PIUnit Activity, the BatchID, Product and Procedure Name for each PIUnit can be stored in PIPoints. The information stored in these tags is redundant and is already stored as part of the PIUnitBatch but the PIPoints can be configured only if they are required for other tag based analysis. These PIPoints are not required to process the event files. The unit status tag must be an integer tag and the other three must be string tags. A value of 1 is written to the unit status tag when a PIUnitBatch is started in that PIUnit. A value of 0 is written to the unit status tag when a PIUnitBatch ends on that PIUnit. The timestamps of those values match the start and end times of the PIUnitBatch in the PI Batch Database.

The BatchID, Product and Procedure Name are written to the corresponding tags with the timestamp same as the PIUnitBatch start time. When the PIUnitBatch is completed, a value “Inactive” is written to those tags.

The /unittags=<event type list> switch determines which of the above tags will be populated. If those tags do not exist, they are created by the interface and a PIAlias is added at the unit level. If point creation is suppressed, the interface does not create the PIPoints and it does not add any PIAliases. The PIAlias creation at the unit level can be suppressed using the /sula switch. If /spc switch is used, then the tags are not created but if the tags already exist, they will be collect data.

The following table is a summary of the PIPoint attributes and the logged values based on the unit activity.

PIPoint for: Location2 attribute

PI Point pointtype

At the start of PIUnitBatch

At the end of PIUnitBatch

BatchID 34 String <Batch ID name> Inactive

Product 35 String <Product name> Inactive

Procedure 36 String <Procedure Name> Inactive

PIUnit Activity 37 Integer 1 0

Merging EVT Files into a Single PIBatchVersion 3.5.0.11 and greater has the feature of merging multiple event files into one single PIBatch. This feature is enabled by using the /merge switch in the command line parameters. The /merge switch cannot be used in conjunction with the /mup switch. The interface will not start up if both switches are used. Event files with the same BatchID will be merged into one PIBatch. When a new file is processed, the interface searches the PIBatch Database to find a PIBatch with BatchID as the search criteria. The/pmt switch (required when /merge is used) specifies the duration in days before and after the start time of the new event file that the interface should search the PIBatch Database. If there is no existing PIBatch in the search time with a match for the BatchID, then a new PIBatch with the appropriate BatchID, Product and Recipe is created. If there is an

18

existing PIBatch then the new event file will be merged with this PIBatch even if the Product and Recipe of the new event file do not match those of the already existing PIBatch. The start time and end time of the existing PIBatch are modified to reflect the total duration of the two event files. The /bidm, /bidf, /bidd and /bidchar parameters are optional and allows the interface to use a substring of the actual BatchID in the event file as the BatchID for the PIBatch. See the section on “Using /BIDM, /BIDD, /BIDF and/BIDCHAR Switches” for details on how this switch works. When event files are merged and there are overlapping Unit Procedures on a PIUnit in those event files, then only one PIUnitBatch represents the overlapping Unit Procedures. The start time and end time for the PIUnitBatch span the entire duration of all the overlapping Unit Procedures. However, the Product and Procedure Name properties of the PIUnitBatch come from the event file that first created the PIUnitBatch. If there are overlapping Operations with the same name, they are not merged into one Operation. There will be two Operations with the same name and probably with different start times. Since Operation level is never merged, the phases will never merge as well.

Event Logging When Event Files Are MergedWhen the PIBatches are merged, the same set of string pool tags are used to record events from all the merged event files. Also, the same tags are used for Param Download Verified, Report, Prompt, Recipe Value and Owner Change events. The PIProperties in the PIBatch will have a name in the format “EventRowNo_filename” where RowNo is the Row number from the event file and filename is the name of the event file. Please read the section on “Event Logging” above for details on how the events are stored.

Additional Events Logged to the String TagsAdditional events can be logged to the string tags in the string tag pool at the start of every Operation. This feature is enabled by the /aspe switch. If /aspe=10 is specified, then additional events are added to the string tag for the “Formula Header”. Additional “Formula Header” events switch is valid only when the “Formula Header” is being logged to a string tag. In other words, the /aspe=10 is valid only when /logtotag includes the value 10. If /aspe=33 is specified, then additional string tag is allocated for the BatchID to store the Original BatchID (if a substring is used). If /aspe=10,33 then additional events for both Forumla Header and BatchID are stored in the string tags. These additional events are added at the start time of every Operation executed under each of the merged PIBatches. For additional “Formula Header” events, the value is a concatenation of Operation Name from the event file, the string “Formula Name”, the string “Formula Header”, formula name from the file, Area Column, Proc Cell Column, Unit Column, Phase Column, Phase Description Column, UserID column and UniqueID column that correspond to the event that triggers the start of the operation in the event file. All the values are separated by “|”. Note that only formula name is stored at Operation level and not all the events for “Formula Header”. The “BatchID” string tag stores events with every value being concatenation of BatchID substring used for the PIBatch, Original BatchID as in the “BatchID” column in the event file, Operation Name from the event file, Area Column, Proc Cell Column, Unit Column and the word “BatchID”. All the values are separated by “|”.

Using /BIDM, /BIDF, /BIDD and /BIDCHAR SwitchesEither /bidf (BatchID Fixed format) or /bidd (BatchID Dynamic format) or /bidchar (BatchID CHARacters) or /bidm (BatchID Mask) switch is used to obtain a new BatchID, which is a substring of the value in the BatchID column in the event file. The switches /bidf, /bidd and /bidchar can be specified simultaneously and will be



replaced internally by /bidm switch. The /bidf takes four values in the format /bidf=n:c:p:a where n represents a fixed number of contiguous digits in the desired BatchID, c represents the number of contiguous characters embedded in the substring to be extracted, p represents the starting position of the characters with respect to the contiguous digits and a represents the anchor point for the varying digit count. N must have a value specified if /bidf=n:c:p:a is used but c, p and a take default value of zero. A substring from the BatchID column in the event file is determined based on these criteria. If there is no match, then the complete string in the BatchID column of the event file is used as the BatchID for the PIBatch. If there are multiple matches, the first substring is used as the BatchID for the PIBatch. If the number of contiguous digits could vary, then the /bidd switch allows a dynamic count. The /bidd is used in conjunction with/bidf=n:c:p:a. When/bidd is used, a BatchID with the minimum number (n) of digits is searched. If there is no match then the interface searches for n+1 contiguous digits and so on until a match is found or the length of the BatchID string is reached. If there is no match, then the complete string in the BatchID column of the event file is used as the BatchID for the PIBatch. If more than one match is found then the first substring is used. If there are characters embedded within the substring, then in the dynamic format it is necessary to specify whether the digit count should be increased before or after the characters. The anchor value a serves this purpose. The /bidchar takes one value which represents the number of characters from the beginning of the string in BatchID column that are used as the actual BatchID. The /bidm takes a list of BatchID masks, where the order of importance depends on the the position of the mask in the list. The mask can consist of an array of valid symbols and wildcards. The following table represents available wildcards which can be specified within the BatchID mask.

Wildcard Description

# Single digit numerical value, 0-9

@ Single alpha character, a-z, A-Z

? Any single symbol

! Repeat the previous mask symbol

* Any set of symbols

Example for /bidf to extract a substring from the BatchID column in the event file:

Let’s say that the BatchID column in the event file is lot30112 / 90dev123 / 12345stp / ld567.

If /bidf=5:0:0:0 (or /bidm=#####) means that there are 5 contiguous digits and no characters in the substring. Since there are two matches, the first substring is used and the result will be 30112.

If /bidf=6:0:0:0 (or /bidm=######) means that there are 6 contiguous digits and no characters in the substring and there is no match for this and the complete string lot30112 / 90dev123 / 12345stp is used as the BatchID.

If /bidf=3:0:0:0 (or /bidm=###) means that there are 3 contiguous digits and no characters in the substring. Since there are two matches, the first substring is used and the result will be 123.

If /bidf=5:3:1:0 (or /bidm=@@@#####) means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the first digit. Hence the resulting BatchID will be lot30112.

20

If /bidf=5:3:3:0 (or /bidm=##@@@###) means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the third digit. Hence the resulting BatchID will be 90dev123.

If /bidf=5:3:6:0 (or /bidm=#####@@@) means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the sixth digit (in this case it means at the end of the 5 digit number). Hence the resulting BatchID will be 12345stp.

Example for /bidd in conjunction with /bidf to extract a substring from the BatchID column in the event file:

Let’s say that the BatchID column in the event file is lot30112 / 90dev124 / 12345stp / ld567 / 201num54.

If /bidf=3:0:0:0 means that there are 3 contiguous digits, no characters in the substring and batchID dynamic is used. Since there are multiple matches, the first substring is used and the result will be 30112.

If /bidf=4:0:0:0 means that there are 4 contiguous digits and no characters in the substring. There is no match for 4 contiguous digits. Hence the search continues for a 5 contiguous digits. Since there are two matches, the first substring is used and the result will be 30112. Note that without the /bidd switch, the BatchID would be the entire string.

If /bidf=5:0:0:0 means that there are 5 contiguous digits and no characters in the substring. Since there are two matches, the first substring is used and the result will be 30112.

If /bidf=6:0:0:0 means that there are 6 contiguous digits and no characters in the substring. There is no match for 6 contiguous digits. Hence the search continues for a 7 contiguous digits. There is no match for 7 contiguous digits. Hence the search continues for 8 contiguous digits and so on but there is never a match for more than 5 contiguous digits. Therefore the complete string lot30112 / 90dev124 / 12345stp / ld567 / 201num54 is used as the BatchID.

If /bidf=5:3:1:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the first digit. The resulting BatchID will be lot30112.

If /bidf=5:3:6:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the sixth digit (in this case it means at the end of the 5 digit number). Hence the resulting BatchID will be 12345stp.

If /bidf=4:3:3:0 means that there are 4 contiguous digits with 3 contiguous characters and the characters are placed before the third digit. There is no match for the given criteria. So, the number of contiguous digits for the substring is increased to 5. Since the number of digits is increased, the position of the characters becomes ambiguous because the increased digit can be either before or after the three characters. This means the two possibilities are 90dev124 and 201num54. The last value in the switch specifies where the increased digit should be added. A value of zero (as in this case) means the number of digits to the left of the characters is fixed and hence the result will be 90dev124. If /bidf=4:3:3:1 is used, the result would be 201num54.

If /bidf=4:3:3:1 means that there are 4 contiguous digits with 3 contiguous characters and the characters are placed before the third digit. There is no match for the given criteria. So, the number of contiguous digits for the substring is increased to 5. Since the number of digits is increased, the position of the characters becomes ambiguous because the increased digit can be either before or after the three characters. This means the two



possibilities are 90dev124 and 201num54. The last value in the switch specifies where the increased digit should be added. A value of one (as in this case) means the number of digits to the right of the characters is fixed and hence the result will be 201num54. If /bidf=4:3:3:0 is used, the result would be 90dev124.

Example for /bidchar to extract a substring from the BatchID column in the event file:

Let’s say that the BatchID column in the event file is 30112SIP

If /bidchar=5 (or /bidm=?????) means the PIBatch BatchID will be 30112.

If /bidchar=10 (or /bidm=??????????) means that the PIBatch BatchID will be 30112SIP because there are less than 10 characters in the actual string itself.

Merging Parallel PIUnitBatches into a Single PIUnitBatch in the Same Event File

Version 3.7.0.15 and greater has the feature of merging parallel PIUnitBatches into one PIUnitBatch on any PIUnit. The parallel PIUnitBatches should be in the same Event File. To merge parallel PIUnitBatches on the same PIUnit coming from different Event Files, read about using the /merge switch in the section “Merging EVT Files into a Single PIBatch”.

This feature is enabled by using the /mup switch in the command line parameters. The /mup switch cannot be used in conjunction with the /merge or the /mmm switch. The interface will not start up if /mup is specified in the command line parameters along /merge or /mmm.

For each unit, the event file contains two Recipe Arbitration Events and two System Messages that trigger start and end of a PIUnitBatch. The Recipe Arbitration events are “Resource Acquired by recipe” and “Resource Released by recipe” or their equivalents. The System Messages are “Unit Procedure Started” and “Unit Procedure Finished” for S88 Procedure level recipe or Unit Procedure level recipe and “Operation Started” and “Operation Finished” for S88 Operation level recipe.

A PIUnitBatch is started on the PIUnit when both “Resource Acquired by recipe” and “Unit Procedure Started” (“Operation Started” for Operation Level recipe) are true. The PIUnitBatch is closed when either “Resource Released by recipe” or “Unit Procedure Finished’ (or “Operation Finished” for Operation Level recipe) occurs. However, for recipes with parallel Unit Procedure on the same unit, there will be no event to stop the PIUnitBatch. When the /mup switch is not used, the interface will treat a new “Unit Procedure Started” (“Operation Started” for Operation Level recipe) event as the trigger for stopping the running PIUnitBatch as well as for starting a new PIUnitBatch. With the /mup switch, the interface keeps the running PIUnitBatch open. The PIUnitBatch will be closed only after the “Unit Procedure Finished” (“Operation Finished” for Operation Level recipe) appears as many times as the “Unit Procedure Started” (“Operation Started” for Operation Level recipe) on that unit or when the resource is released by the recipe.

The interface keeps track of the number of times the System Message event occurs in the event file for each unit through an internal counter. When the /mup switch is used, the first PIUnitBatch is created when both “Resource Acquired” and “Unit Procedure Started” (“Operation Started” for Operation Level recipe) are true for a unit. From that point forward, whenever the interface encounters a ”Unit Procedure Started” (“Operation Started” for Operation Level recipe) for that unit, a counter is incremented by one.

22

Whenever the interface encounters “Unit Procedure Finished” (“Operation Finished” for Operation Level recipe), the counter is decremented by one. In order to close the PIUnitBatch, the interface requires one of the following to happen:

1) “Resource Released by recipe” event occurs for that unit in the same event file meaning that this recipe releases the unit. In other words, the Recipe Arbitration events are describing the actual physical ownership of the specific unit by the BES and can close PIUnitBatch by releasing the resource regardless of System Messages.

2) “Resource Acquired by recipe” event occurs for this unit again within the same event file. This situation is rare but can happen when different recipes exchange physical control of the unit. In this case, the running PIUnitBatch is closed, the counter reset to zero and the PIUnitBatch will be started when the next System Message event occurs.

3) “Unit Procedure Finished” event occurs and the counter maintained by the interface equals zero. This means that there are equal number of System Messages to start and stop the PIUnitBatch for that unit within that event file.

4) “Resource Acquired by recipe” event occurs for this unit in a different event file. This situation can happen when another recipe takes physical control of the unit. In this case, the running PIUnitBatch is closed but the counter is not reset to zero and the PIUnitBatch will be started if and when the next “Resource Acquired by recipe” event occurs in the event file.

5) “End of Batch” event occurs. If there is a PIUnitBatch still running, it will be closed when the PIBatch is closed. This happens if the System Messages to close the PIUnitBatch are missing in the event file

For Operation Level recipes, the Operations are also merged along with the PIUnitBatches.

When /mup is used, only the first procedure name is recorded for the merged PIUnitBatches. It is possible that under merged PIUnitBatches, there could be more than one Operation with the same name. In order to distinguish these Operations, the Operation names are modified with the following syntax,

<new operation name> = <unit procedure name><separator><original operation name>

The <separator> is a user defined sequence of characters used to separate the <unit procedure name> and <operation name>. By default the <separator> is a double space. The user defined <separator> value can be passed as a value for the /mup switch, for example, /mup=”__”.

In the following examples assume <unit procedure name> = UP_TEST:1 and <original operation name> = OP_TEST:1:1

Example 1: The /mup switch is used without value.

<new operation name> = UP_TEST:1 OP_TEST:1:1

Example 2: The /mup=”__” switch is used with user defined separator, passed as value

<new operation name> = UP_TEST:1___OP_TEST:1:1

The <separator> cannot contain any of the following characters:

‘ ? | ` “



Using /rsm SwitchThe Reset System Message (/rsm) switch resets the System Message flag for a unit when the Recipe Arbitration event “Resource Released by recipe” occurs. It means that if the Recipe Arbitration event was used to close the active PIUnitBatch, the interface would require both event types to be present in order to start a new PIUnitBatch. The /rsm switch can be used in conjunction with the /mup switch. In this case, the /rsm switch will also reset the system message counter to zero on active unit.

For example, assume that there is an active PIUnitBatch. Let the next event that the interface encounters be the Recipe Arbitration event – “Resource Released by recipe”. The interface will close the active PIUnitBatch irrespective of whether the /mup switch is used or not. Let the next event be the Recipe Arbitration event –“Resource Acquired by recipe”.

If the /rsm switch is not used, then the interface will start a new PIUnitBatch. In addition, if the /mup switch is used, it would keep the count of System Message events from previously closed unit batch.

If the /rsm switch is used, the interface would not start a new PIUnitBatch. Instead, it will wait for a new System Message event –“Unit Procedure Started” (“Operation Started” for Operation Level recipe) to occur for that unit to start a new PIUnitBatch.

Lost Connections to PI Server and PI Archive Backup IssuesThe event file interface mostly writes to PI Batch Database through PI SDK. Since there is no buffering for batch data, any lost connections or during PI Server backup, the interface fails to write the batch data. Earlier versions of this interface would simply print an error message and mark the file questionable. Version 3.6.0.10 and higher has the ability to detect the reason for failure to write batch data to the PI Server and in case the cause is determined to be either lost connections to the PI Server or if the PI Archive is in backup state, then the interface waits until the error is resolved and retires adding or editing the batch record. The interface tries to reconnect every 30 seconds but prints the error message only every 15 minutes if the connection is still not re-established. The retry time delay can be specified through the optional command line parameter /rtd (Retry Time Delay). The default retry time is 60 seconds. It is also possible to specify the timeout delay on the failed SDK calls through the optional command line parameter /rto (Retry TimeOut). The default value is set to infinity (/rto=0). In order to prevent data lose due to extended disconnection period, it is recommended not to use the /rto switch. Starting with EVT interface version 3.8.6.4, the /retrytimeout switch is obsolete.

Questionable FilesThe event file delineates a complex data structure. The concept of a hierarchical PI Batch and its children (and children’s children) creates a very complex set of relationships between the various objects in the Batch database (BDB). Given the complexity of the data structure and the potential actions that an operator may take in the execution of a recipe, the interface may encounter a sequence of events in the event journal that does not conform to the logic delineated above and cannot create the required objects based on the known information in the file.

24

When a file is deemed to have questionable event sequences, the interface must continue to operate without manual intervention, but must also inform the user that a problem has occurred. The interface attempts to process all files using the logic outlined above to create the required BDB objects. However, when the interface encounters a file that does not conform to the specifications outlined above, it stops processing that particular file and marks the corresponding PI Batch and PI UnitBatch “questionable”. In these cases, the interface has encountered a file, whose event format or order cannot be processed properly. See Appendix A, for more information concerning the specific actions that the interface takes when it encounters a “questionable” file. Appendix A also delineates the actions that the user is required to take in those circumstances.

Appendix D describes the EVT Cleaning Utility that helps in preparing any Event file for reprocessing. Since a questionable file leaves the batch partially populated, it is best to remove the partial data from PI and reprocess the file. The EVT Cleaning Utility makes it easier to remove the partial data. The tool can also run in a mode where it analyzes the file and the data in PI and report the missing information.

Reprocessing Questionable FilesEvent files that are marked questionable can be reprocessed by the event file interface. However, certain steps are required before renaming the file to .evt. Identify the cause for each file to be marked questionable. Rectify the problem that resulted in the questionable file. If the problem cannot be rectified, the interface will mark the file questionable again after reprocessing. Stop the event file interface. Copy all questionable files to a separate folder and rename them to .del extension. Use the path to this folder in the /path parameter for the EVT Cleaning Utility (Appendix D). The /ps, /id /host, /smp and /bestype must be the same for the EVT Cleaning Utility and the event file interface that created the questionable files. Set the /mode=delete for the EVT Cleaning Utitliyt. Run the EVT Cleaning Utility. The utility will remove the partially created batch data and partially filled PI tags for those files and rename the files to .cln. Rename these files to .evt and move them to a separate folder. This folder MUST be different from the folder that is used for regular processing of the event files. Edit the interface start up parameters to point the /path to this new folder and /pospath to a different folder from the one used by the interface for normal processing. Alternately, a separate instance of the event file interface can be set up with the same command line parameters as the first instance of the interface except for the /path and /pospath. Also, use the /rme switch before starting the interface. Run the event file interface with the above settings to reprocess all the files. All files that are successfully processed will be renamed to .999. Now, copy these files back to the original directory for event files where the questionable files are located. The questionable files can be deleted. Alternately, the questionable files can be renamed to .999. Stop this instance of the interface. Reset the command line parameters to point to the original folder for event files and .pos files and restart the event file interface to continue with the processing of current files.

If files need to be reprocessed before being marked questionable, then follow the above steps. Before restarting the event file interface in normal operation mode, replace the old .pos corresponding to the event file with the one created during reprocessing.



Event Based Time Ordered ProcessingStarting with the version 3.8.4.6, the EVT interface is capable of processing EVT files based on the timestamps of each row within each EVT file, rather than processing EVT files based on names. On each scan, the interface performs a preliminary evt directory scan in order to create a time ordered processing queue of all active evt files based on the current position’s timestamp within each file. It then scans each EVT file for the end position. This strategy allows creating a fixed time frame common to all EVT files. The interface will then read data, in the time frame, in time order. Any processing delays due to network losses, server unavailability, slow scan rates, and non 26talian26se26l file naming, can be handled gracefully by this approach. This feature can be enabled by specifying the switch /etop (Event Time Ordered Processing). Note, this feature will be disabled, if it is used in conjuction with the recovery mode switch /rme. The following figure illustrates how the interface will process data with and without the /etop switch.

There are four EVT files starting at different times and containing data written sequentially by Batch Execution System. The vertical axis is the file time, where the t1 is the earliest time and the t11 is the latest time. Prior to version 3.8.4.6 the interface would read each file until the end before switching to the next file. Without the /etop switch the file processing sequence is given in the table below and based on the alphabetical naming of the EVT files.

Order File Name

Data Segments [start time – end time] written by the BES in parallel EVT files

t1 – t2 t2 – t3 t3 – t4 t4 – t5 t5 – t6 t6 – t7 t7 – t8 t8 – t9 t9 – t10

t10 – t11

1 File 1 X X X X

2 File 2 X X X

3 File 3 X X

4 File 4 X

With the /etop switch, the EVT interface will process all data segments in time order as it is illustrated in the table below

26

Order File Name

Data Segments [start time – end time] written by the BES in parallel EVT files

t1 – t2 t2 – t3 t3 – t4 t4 – t5 t5 – t6 t6 – t7 t7 – t8 t8 – t9 t9 – t10

t10 – t11

1 File 1 X

2 File 3 X

3 File 1 X

4 File 2 X

5 File 1 X

6 File 3 X

7 File 2 X

8 File 4 X

9 File 1 X

10 File 2 X

Dealing with Irrelevant UnitsIt is sometimes possible to use “virtual” or “dummy” units in a recipe that do not exist physically but aid in control transfer between recipes. In such cases, there could be overlapping PIUnitBatches on these “dummy” units which could lead to a questionable file. These units can be excluded from processing the file by using the switch /skipunits. The switch contains the list of all units the interface should not evaluate. Everything related to this unit is not processed into PI Batch Database or PI Points. The interface looks for the value in the “Pvalue” and “UNIT” columns in each row. If any of those values match any of the units in the /skipunits list, the interface will simply move to the next line the Event File. The unit name comparision is not case sensitive and the interface does not compare the “AREA” or “ProcCell” values. Multiple unit names can be specified with a comma separator. If there is a space in the unit name, use double quotes for the entire switch. This switch is available only with version 3.7.0.15 and greater. Starting with version 3.8.5.1, unit masks can be specified as valid units. The following table represents available wildcards which can be specified within the unit name mask.




? Any single symbol



Example: /skipunits=unit1,unit2 or /skipunits=”unit 1,unit 2”



Dealing with Irrelevant PhasesIt is sometimes possible to use “virtual” or “dummy” phases or some phases are of no interest. These phases can be excluded from processing the file by using the switch /skipphases. The switch contains the list of all phases the interface should not evaluate. Everything related to this phase is not processed into PI Batch Database or PI Points. The interface looks for the value in the “Phase” and “Recipe” columns in each row. If any of those values match any of the phases in the /skipphases list, the interface will simply move to the next line the Event File. The phase name comparision is not case sensitive and instance number independent. Multiple phase names can be specified with a comma separator. If there is a space in the phase name, use double quotes for the entire switch. This switch is available only with version 3.8.4.8 and greater. Starting with version 3.8.5.1, phase masks can be specified as valid phases. The following table represents available wildcards which can be specified within the phase name mask.




? Any single symbol



Example: /skipphases=phase_1,ph*2 or /skipphases=”phase_1, ph*2”

Example Event File JournalAn annotated journal file is shown in Figure 4. For clarity, the entire journal file has not been shown. Those fields that have been excluded do not significantly affect the logic used by the interface to process the event journal. The last column shown in Figure 4 describes the actions taken by the interface in response to each message listed in the journal file.

Figure 5: Abbreviated Example EVT file demonstrating interface actions pertaining to PIModule and PIBatch object creation

LclTime Descript Event Pvalue EU Action Taken by Interface

2000.05.17 14:06:17 Event File Name

\\OBATCH\JOURNALS\15.evt New event file detected.

2000.05.17 14:06:17 Author Recipe Header PR1Upauthor

Interface waiting for “Beginning of Batch.”

2000.05.17 14:06:17

Product Description Recipe Header

PR1UPProcedureDescription

2000.05.17 14:06:17

PR1UPPROCDESCRIPT System Message

Beginning Of BATCH Procedure

PIBatch object created. Start time assigned to PIBatch.

2000.05.17 14:06:30

Procedure Started. System Message 0

28

LclTime Descript Event Pvalue EU Action Taken by Interface

2000.05.17 14:06:30 Step Activated Step Activity UP2OPS:1

Unit Procedure

PIUnitBatch created to represent the unit procedure.

2000.05.17 14:06:30

Unit Procedure Started System Message 0

2000.05.17 14:06:30 Unit Acquired Arbitration SOL_DELIV_1

Start time assigned to PIUnitBatch.

2000.05.17 14:06:30 Step Activated Step Activity OP1PHASE:1 Operation

PISubBatch created to represent the operation.

2000.05.17 14:06:30

Operation Started System Message 0

Start time assigned to PISubBatch.

2000.05.17 14:06:30

Equip. Module Acquired Arbitration

S1_TEMPERATURE1

2000.05.17 14:06:30 Step Activated Step Activity

SX_TEMPERATURE:1 Phase

Sub-PISubBatch created to represent the phase.

2000.05.17 14:06:32 State Changed: State Change RUNNING

Start time assigned to Sub-PISubBatch.

2000.05.17 14:07:06 State Changed: State Change COMPLETE

End time assigned to the Sub-PISubBatch.

2000.05.17 14:07:07

Equip. Module Released Arbitration

S1_TEMPERATURE1

2000.05.17 14:07:07

Operation Finished System Message 0

End time assigned to the PISubBatch.

2000.05.17 14:07:45 Unit Released Arbitration SOL_DELIV_1

End time assigned to the PIUnitBatch.

2000.05.17 14:07:45

Unit Procedure Finished System Message 0

2000.05.17 14:09:05

Procedure Finished. System Message 0

2000.05.17 14:09:05

PR1UPPROCDESCRIPT System Message End Of BATCH Procedure

End time assigned to the PIBatch.


Installation ChecklistIf you are familiar with running PI data collection interface programs, this checklist helps you get the Interface running. If you are not familiar with PI interfaces, return to this section after reading the rest of the manual in detail.

This checklist summarizes the steps for installing this Interface. You need not perform a given task if you have already done so as part of the installation of another interface. For example, you only have to configure one instance of Buffering for every interface that runs on an Interface Node.

The Data Collection Steps below are required. Interface Diagnostics are optional.

Data Collection Steps1. Confirm that you can use PI SMT to configure the PI Server. You need not run PI

SMT on the same computer on which you run this Interface.

2. If you are running the Interface on an Interface Node, edit the PI Server’s Trust Table to allow the Interface to write data.

3. Run the installation kit for PI Interface Configuration Utility (ICU) on the interface node. This kit runs the PI SDK installation kit, which installs both the PI API and the PI SDK.

4. Run the installation kit for this Interface.

5. If you are running the Interface on an Interface Node, check the computer’s time zone properties. An improper time zone configuration can cause the PI Server to reject the data that this Interface writes.

6. Run the ICU and configure a new instance of this Interface. Essential startup parameters for this Interface are

Point Source

Interface ID

PI Server

Path to EVT journal files

Path to position files

Batch Executive System type

7. Location1 is the interface instance.Location2 is the point type.Location4 is the scan class, typically this is set to 1 for the Event File interface.ExDesc contains the variable name and phase name.InstrumentTag is the unit.

8. Start the Interface interactively and confirm its successful connection to the PI Server without buffering.

9. Confirm that the Interface collects data successfully.


10. Configure the Interface to run as a Service. Confirm that the Interface runs properly as a Service.

11. Restart the Interface Node and confirm that the Interface and the buffering application restart.

Interface Diagnostics1. Configure Scan Class Performance points.

2. Configure Performance Counter points.

3. Install the PI Performance Monitor Interface (Full Version only) on the Interface Node.

4. Configure UniInt Health Monitoring points

5. Configure the I/O Rate point.

6. Install and configure the Interface Status Utility on the PI Server Node.

7. Configure the Interface Status point.


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

Note: Buffering is not recommended with the PI Event File interface. This is due to the fact that this interface reads flat ASCII files, which are already effectively buffered. Once a file is processed, it is renamed by the interface to ensure that it is not reprocessed. Since the file is not renamed until processing is finished, the interface may pick up where it left off when processing is interrupted.

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

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

Naming Conventions and RequirementsIn the installation procedure below, it is assumed that the name of the interface executable is EVTIntf.exe and that the startup command file is called EVTIntf.bat.

When Configuring the Interface ManuallyWhen configuring the interface manually 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, EVTIntf1.exe and EVTIntf1.bat would typically be used for interface number 1, EVTIntf2.exe and EVTIntf2.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 parameters in a file that has the same root name.

Interface Directories

The PIHOME Directory TreeThe 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 %windir% directory. A typical pipc.ini file contains the following lines:[PIPC]PIHOME=C:\PIPC


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

Interface Installation DirectoryThe interface install kit will automatically install the interface to:PIHOME\Interfaces\EVTIntf\PIHOME is defined in the pipc.ini file.

Interface Installation ProcedureThe PI EVTIntf interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000. To install, run the EVTIntf_x.x.x.x.exe installation kit.

Installing the Interface as a Windows ServiceThe PI EVTIntf interface service can be created with the PI Interface Configuration Utility, or can be created manually.

Installing the Interface Service with the PI ICUThe PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service:

Service ConfigurationService NameThe Service to Add box shows the name of the current interface service. This service name is obtained from the interface executable.


IDThis is the service id used to distinguish multiple instances of the same interface using the same executable.

Display NameThe Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI ” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI ” be appended to the beginning of the interface to indicate that the service is part of the OSI suite of products.

Log on asThe Log on as text box shows the current “Log on as” Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show “LocalSystem.” Users may specify a different Windows User account for the service to use.

PasswordIf a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password.

Confirm PasswordIf a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.

Startup TypeThe Startup Type indicates whether the interface service will start automatically or needs to be started manually on reboot.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, interface services are set to start automatically.

DependenciesThe Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependent should be moved into the Dependencies

list using the button. For example, if PI API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. To remove a

service from the list of dependencies, use the button, and the service name will be removed from the “Dependencies” list.

When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.

Note: Please see the PI Log and Operating System Event Logger for messages that may indicate the cause for any server not running as expected.


Interface Installation

- Add ButtonTo add a dependency from the list of Installed services, select the dependency name, and click the Add button.

- Remove ButtonTo remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.

The full name of the service selected in the Installed services list is displayed below the Installed services list box.

CreateThe Create button adds the displayed service with the specified Dependencies and with the specified Startup Type.

Remove The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.

Start or Stop ServiceTo Start or Stop an interface service, use the Start button and a Stop button on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.

The status of the Interface service is indicated in the lower portion of the PI ICU dialog.

Installing the Interface Service ManuallyHelp for installing the interface as a service is available at any time with the command:EVTIntf.exe –help

Change to the directory where the EVTIntf1.exe executable is located. Then, consult the following table to determine the appropriate service installation command.

Windows Service Installation Commands on a PI Interface Node or a PI Server Nodewith Bufserv implemented

Manual service EVTIntf.exe –install –depend “tcpip bufserv”

Automatic service EVTIntf.exe –install –auto –depend “tcpip bufserv”

*Automatic service with service id

EVTIntf.exe –serviceid X –install –auto –depend “tcpip bufserv”

Windows Service Installation Commands on a PI Interface Node or a PI Server Nodewithout Bufserv implemented

Manual service EVTIntf.exe –install –depend tcpip

36

Status of the ICU Status of the

Interface Service

Service installed or uninstalled

Automatic service EVTIntf.exe –install –auto –depend tcpip

*Automatic service with service id

EVTIntf.exe –serviceid X –install –auto –depend tcpip

*When specifying service id, the user must include an id number. It is suggested that this number correspond to the interface id (/id) parameter found in the interface .bat file.

Check the Microsoft Windows services control panel to verify that the service was added successfully. The services control panel can be used at any time to change the interface from an automatic service to a manual service or vice versa.


Digital StatesFor more information regarding Digital States, refer to the PI Server documentation.

Digital State SetsPI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.

An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.

System Digital State SetSimilar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state bad input to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients. Digital States 193-320 are reserved for OSIsoft applications.


PointSourceThe PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For example, the string EV may be used to identify points that belong to the EVT Interface. To implement this, the PointSource attribute would be set to EV for every PI Point that is configured for the EVTIntf Interface. Then, if /ps=EV is used on the startup command-line of the EVTIntf Interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of EV. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the /ps parameter.

Case-sensitivity for PointSource AttributesThe PointSource character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=P and /ps=p are equivalent.

Reserved Point SourcesSeveral subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface.

Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.


PI Point ConfigurationThe PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each measurement value that needs to be archived.

Interface-specific PointsProcess parameters are often specified in event files. These parameters are typically more easily viewed as a graphical trend. Points may be built to specify which events are to be captured and stored in PI. The point attributes described in the following section are used to specify the event type, unit name, event description, and engineering units of the event to be captured. For this version of the interface, only five events can be captured in specific points and those events are “Report”, “Param Download Verified”, “Recipe Value”, “Owner Change” and “Prompt”. For all other events, they should be sent to the PIProperties in a PIBatch or to the string tag pool. Points for string tag pool are automatically created by the interface. Remember to add a PIAlias to the Phase level module and the PIUnit for the manually created points because the interface does not create PIAliases for such points.

Point AttributesUse the point attributes below to define the PI Point configuration for the Interface, including specifically what data to transfer.

TagThe Tag attribute (or tagname) is the name for a point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI documentation uses the terms “tag” and “point” interchangeably.

Follow these rules for naming PI points:

The name must be unique on the PI Server.

The first character must be alphanumeric, the underscore (_), or the percent sign (%).

Control characters such as linefeeds or tabs are illegal.

The following characters also are illegal: * ’ ? ; { } [ ] | \ ` ‘ “

LengthDepending on the version of the PI API and the PI Server, this Interface supports tags whose length is at most 255 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.

PI API PI Server Maximum Length

1.6 or higher 3.4.370.x or higher 1023


1.6 or higher Below 3.4.370.x 255

Below 1.6 3.4.370.x or higher 255

Below 1.6 Below 3.4.370.x 255

If the PI Server version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and you want to use a maximum tag length of 1023, you need to enable the PI SDK. See Appendix B for information.

PointSourceThe PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line parameter and the “PointSource” section.

PointTypeTypically, device point types do not need to correspond to PI point types. For example, integer values from a device can be sent to floating point or digital PI tags. Similarly, a floating-point value from the device can be sent to integer or digital PI tags, although the values will be truncated.

The Event File interface supports float16, float32, int16, int32, and string tag types for data.

Location1Location1 is used to specify the instance of the interface that the point is linked to. The interface will check for the use of the “/id=x” switch, where n specifies the instance of the interface used. Location1 for the point must be x for the interface to recognize the point. Note that x must be a non-negative integer value.

Location2Location2 is used to specify the type of event, which the point is linked to. The following five values are allowed:

Location 2 Type of Event

1 Param Download Verified

2 Recipe Value

3 Report

4 Prompt

5 Owner Change

34 PIUnitBatch BatchID

35 PIUnitBatch Product

36 PIUnitBatch Recipe

37 PIUnit Activity


Location3Location 3 should be set to 2 for all string tags that collect data for the five specific events mentioned above and for the health tags used to monitor the 45talian45s. For numeric tags, location 3 is insignificant and can be left at the default value. The interface differentiates specific event string tags from string tag pool tags from the value of Location3.

Location4Scan-based InputsFor interfaces that support scan-based collection of data, Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the /f flag in the section called “The Startup Command File”.

Trigger-based Inputs, Unsolicited Inputs, and Output PointsLocation 4 should be set to zero for these points.

Location5Location5 is not used by this interface.

InstrumentTagLengthDepending on the version of the PI API and the PI Server, this Interface supports an InstrumentTag attribute whose length is at most 32 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.





Below 1.6 Below 3.4.370.x 32

If the PI Server version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and you want to use a maximum InstrumentTag length of 1023, you need to enable the PI SDK. See Appendix B for information.

ExDescLengthDepending on the version of the PI API and the PI Server, this Interface supports an Extended Descriptor attribute whose length is at most 32 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.



PI Point Configuration




Below 1.6 Below 3.4.370.x 80

If the PI Server version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and you want to use a maximum InstrumentTag length of 1023, you need to enable the PI SDK. See Appendix B for information.

Variable NameThe extended descriptor is used to specify the ‘Descript’ text of the event.

For example, a Recipe Value event may specify SP_JACKET_MASTER_TEMP_SETPOINT in the Descript column of the event file. To specify this Descript text, the ExDesc would contain the following:

descript=”SP_JACKET_MASTER_TEMP_SETPOINT”

PhaseThe extended descriptor is also used to specify the ‘Phase’ text of the event.

For example, a Recipe Value event may specify PHASE1 in the Phase column of the event file. To specify this Descript text, the ExDesc would contain the following:

phase=”PHASE1”

Note: the “phase” and “descript” keywords are currently case-sensitive and must be specified for a given point. However, they may be specified in any order.

Performance PointsFor UniInt-based interfaces, the extended descriptor is checked for the string “PERFORMANCE_POINT”. If this character string is found, UniInt treats this point as a performance point. See the section called “Performance Counters Points.”

Scan The Scan attribute has the default value of 1, indicating that the Interface should collect data for the point. Setting the Scan attribute to 0 turns data collection off. If the Scan attribute is 0 when the interface starts, the Interface writes SCAN OFF to the point. If the user changes the Scan attribute from 1 to 0 while the interface is running, the Interface also writes SCAN OFF.

There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.

ShutdownThe Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which

46

means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Server manuals.

Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the /stopstat=Shutdown command-line argument is specified.

SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.

BufservBufserv should not be used with this interface.


Startup Command FileCommand-line parameters can begin with a / or with a -. For example, the /ps=E and –ps=E command-line parameters are equivalent.

For Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters.

Configuring the Interface with PI ICUNote: PI ICU requires PI 3.3 or greater.

The PI Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the interface is configured by the PI ICU, the batch file of the interface (EVTIntf.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file. The procedure below describes the necessary steps for using PI ICU to configure the PI EVTIntf Interface.

From the PI ICU menu, select Interface, New Windows Interface Instance from Exe…, and then Browse to the EVTIntf.exe executable file. Then, enter values for the Host PI System, Point Source and Interface ID# and Service ID if available. A window such as the following results:

“Interface name as displayed in the ICU (optional)” will have PI- pre-pended to this name and it will be the display name in the services menu.

Click on Add.

You should then see a display such as the following:


Startup Command File

Note that in this example the Host PI System is localhost, which means that the interface will be configured to communicate with the local PI Server. However, if you want the interface to communicate with a remote PI Server, you can do this by selecting ‘Connections…’ item from PI ICU menu and make it your default server. If you do not see the remote node in the list of servers, you can add that in.

Once you add the interface to PI ICU, near the top of the main PI ICU screen, the Interface Type should be evtintf. If not, use the drop-down box to change the Interface Type to be evtintf.

Click on Apply to enable the PI ICU to manage this copy of the PI EVTIntf Interface.

The next step is to make selections in the interface-specific tab (i.e. “evtintf”) that allow you to enter values for the startup parameters that are particular to the PI EVTIntf Interface.

50

Since the PI EVTIntf Interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt tab. This tab allows the user to access UniInt features through the PI ICU and to make changes to the behavior of the interface.

If you want to set up the interface as a Windows Service, you can do that by using the Service tab. This tab allows you to configure the interface to run as a service as well as to start and stop the interface. You can also run the interface interactively from the PI ICU. To do that go to menu, select the Interface item and then Start Interactive.

For more detailed information on how to use the above-mentioned and other PI ICU tabs and selections, please refer to the PI Interface Configuration Utility User Manual. In the next section we will describe the selections that are available from the evtintf tab. After you have made your selections on the PI ICU GUI, you will need to press the Apply button in order for PI ICU to make these changes to the interface’s startup file.

The PI EVTIntf ICU Control for PI ICU has six tabs, each of which has a number of separate sections. A yellow text box indicates that an invalid value has been entered, or that a required value has not been entered.

Within the following descriptions, the command line switches are listed with the sections. The user is advised to check the section on “Command-line Parameters” for more detailed information concerning the behavioral consequences of selecting or specifying a given option.

evtintf Interface pageSince the startup file of the PI EVTIntf Interface is maintained automatically by the PI ICU, you should use the evtintf tab to configure the startup parameters and not make changes in the file manually.



General OptionsThe event journal file (/path) and position files directory (/pospath) paths are required for the interface configuration.

Interface debugging (/db=#) can be enabled, but is optional.

The automatic creation of points (/spc), units (/suc), phase states (/sps) or unit-level aliases (/sula) can all be suppressed by checking the appropriate box in the “Suppression Parameters” section of the General Options Tab. The create only string tags (/spc) can also be seen under this section.

An optional starting module path (/smp=<module path>) can be specified in the “Module Path” section. The syntax for specifying the starting module path is as follows: \\<RootModule>\<SubModule>\<…>. For example,

\\pea_soup\pea_soup1\The ellipsis (…) button pulls up a dialog that aids the user in selecting a specified module path.

52

General Options cont.

The Keep Trailing Instance ID (/ktinid=####) specifies at which level of batch hierarchy the interface should keep the trailing instance id. The passed value must be a four digit binary number. Digits represent batch levels and should be specified in the following order: Procedure, Unit Procedure, Operation Name, and Phase Name.

The Unit Tags (/unittags=#[,#,…]) parameter specifies the PIUnitBatch properties which will be logged into PIPoints. Checking the required boxes will cause the interface to write events into the specific tags.

The EVT File Processing Mode section has three processing modes. RealTime (Alphabetical,default), RealTime (Event Time Ordered) (/etop) and Recovery (/rme) which allows for the insertion and backfilling of PI Batch in the past. By default, recover mode is not enabled and is NOT RECOMMENDED under normal runtime conditions. See the command-line parameters section for more details.

The Create only Recipe Tags, Modules, Units and Aliases (/nodata) is to only create recipe tags, modules, units and aliases. When this parameter is used the interface will not write any batch data or populate tags with events on the PI Server. The main purpose is to preprocess EVT files, such that older archives can be reprocessed and backfilled.

The Formula Name As Product Code (/fnapc) parameter allows the interface to use the “Formula Name” instead of the “Product Code” Pvalue as the PI Batch product name. If “Formula Name” Pvalue field is blank, the original “Product Code” Pvalue field is used to retrieve the product name.

The Product (/product=”product name”) parameter allows a value to be used for ProductID attributes of the PIBatch and PIUnitBatches. This parameter is effective only when the event file does not contain a product value or if the value in the event file is equal to “UNDEFINED”.

The rename delay time (sec) (/rdt=#)configures a rename delay time in which the interface will wait after registering the “End Of Batch” system message which normally triggers the closing of the event file object in memory and renaming of the file.



The Reset System Messages (/rsm) parameter resets the System Message flag for a unit when the Recipe Arbitration event “Resource Related by recipe” occurs. See the command-line parameters section for more details.

The Skip Phases (/skipphases=<phaselist>) parameter specifies the list of phases for which all events in the event file should be ignored.

The Skip Units (/skipunits=<unitlist>) parameter specifies the list of units for which all events in the event file should be ignored.

Application Options

The foreign language translation file path (/langpath) can be set in the “Foreign Language Translation” section. Use of the “Edit translation file” button will pull up a separate dialog that allows for the configuration of the phrases that need translation for the interface to operate properly. This dialog has two tabs for General and Event specific phrases that must be translated. The (/uen) switch will allow creating tags, aliases, and modules only using English name for EventTypes even though a translation file is used.

The numerical conversion settings (/ns) can be specified from the drop down list. The default setting is “English_United States”. From the dropdown list, select the “Local Windows Settings” if the settings should be based on the local Windows settings. Select the appropriate language if the settings must be different from the local windows settings. Select the “blank” option to set it to default.

54

and



The Report Event As Phase Step (/ras=<start, stop>) parameter allows the interface to use the “Report” event to create Phase Steps under active Phase States. The Phase Step name and start/stop events are obtained from the “Descript” column.

The “Application Parameters” section allows the specification of certain operational behaviors of the interface. The BES Type (/bestype=”bestype”), BES Identifier (/besname=”BESName”), Combine equipment and recipe name (/cern), arbitration event unavailable (/aeu), unit procedure merge mode (/mmm), retry time for failed PI connection (/rtd=#) and Retry timeout (SDK calls to PI Server) (/rto=#) options can all be specified here.

Event ExclusionsEvent exclusions (/exc) options can be specified on the Batch Properties tab. Use of event exclusions is highly recommended, not all events are relevant to the user and the performance of PI and the PI EVTIntf interface can be greatly compromised by making the interface store many events (such as Step Activities, State Changes or Arbitration events) that are of less general relevance to user for exception tracking or are stored in PI in another manner (such as the start and end times of the various PI Batch DB objects).

56

Event Logging to Strip Pool Tags and Recipe TagsEvent logging (/logtotag=#[,#,#,…]) and Recipe Tag logging (/recipetags=#[,#,#,…])options can be specified on the Event Logging tab.

EVT File Merging

The Merge EVT Files (/merge) should be checked to merge multiple event files into one PIBatch. The merge is based on 57atched. The PIBatch Merge Time (/pmt) is required when /merge is specified. In addition to merging event files into one PIBatch, additional events can be logged to string tags. The Formula Name and the Original BatchID (if the BatchID is a substring of the value in the event files) can be logged to string tags at the start time of every Operation. A separate tag is allocated for the BatchID but for the Formula Name, the string tag allocated for the Formula Header is used. Hence, it is necessary to select “Formula Header” in the “Event Logging” section for the “Formula Header with Formula Name” under “Additional String Pool Events” to be enabled.



The Batch ID Mask (/bidm=<mask list>) is used to obtain a new BatchID, which is a substring of the value in the BatchID column in the event file. The /bidm takes a list of masks as the input value. Each BatchID mask can consist of any array of valid symbols and wildcards. See the /bidm command line parameter in the Command-line Parameterssection.

The “# of character to strip from BatchID Col.” (/bidchar) is an optional setting while merging event files into one PIBatch. This switch allows the interface to strip the number of characters entered from the BatchID column in the event file and use them as the BatchID for the PIBatch. Either the (/bidchar) or (/bidf) parameter can be used to create a BatchID for the PIBatch but not both.

The “Use BatchID Fixed Format” (/bidf) is an optional setting while merging event files into one PIBatch. This switch allows the interface to look for a substring in the BatchID column value in the event files to be used as the BatchID for the PIBatch. The /bidf setting specifies the number of digits, characters and the postion of those digits and characters with respect to each other in the substring. For details on how these settings work and what values to use, see the section titled “Using /BIDF or /BIDD switches”. The /bidd switch is enabled by checking the “BatchID Dynamic Flag”.

Additional ParametersIf the interface-specific control cannot be accessed for any reason by the PI ICU (e.g., the control is not installed) or if the interface-specific control does not contain a particular switch (e.g., the version of the control for some reason is not synchronized with the interface version) additional parameters may be specified in the “Additional parameters” section of the control. This ensures a minimal level of forward compatibility for the control with future versions of the interface and PI ICU. The user should not place parameters here that can be configured elsewhere in the control.

Note: The UniInt Interface User Manual includes details about other command line parameters, which may be useful.

58

Command-line ParametersThis is a listing of the command-line parameters and their specific behaviors with respect to the PI EVTIntf interface. This section gives more detailed information concerning the parameters that may be specified when configuring the interface (such as with the PI ICU).

Parameter Description

/aeuOptional

The /aeu switch specifies that Arbitration Events are Unavailable in the event journal files. When this switch is used, the logic by which the interface resolves the start and end times for various PIBatch objects is altered. This switch should only be used with Batch Execution Systems which are based on Sequencia’s OpenBatch system 4.0.0.75 and earlier.

/aspe=[10,33]Optional

The /aspe=[10,33] switch allows logging Additional String Pool Events to string tags for Formula Header (with more values for Formula Name) and also allocates a string tag for BatchID. This switch is valid only when /merge switch is used. An additional event is added to these tags at the start time of each Operation. The BatchID string tag stores the Original BatchID when a substring of the BatchID column value in the event file is used to merge event files into one PIBatch. Use /aspe=10 if only Formula Name should be logged. /aspe=10 is valid only if /logtotag has the value 10 included. Use /aspe=33 if only the BatchID should be logged. Use /aspe=10,33 to log both of them.

/besname=”BESName”Optional

The /besname flag specifies the string that the application will pre-fix to each Area, Processing Cell, and Unit PI Module that the interface creates. Since the name of the PI Unit created using this option is different than one that is created not using the option, points for that unit are distinguishable. The besname is separated from the rest of the name by a colon (‘:’). The default is to not include a prefix for any string for Area, Processing Cell or Unit names.

/bestype=”bestype”Optional

The /bestype flag specifies the BES application that is generating the event files. Because each of the specific vendor implementations can have subtle differences, this argument may be required. The valid arguments are: OpenBatch (Sequencia) TotalPlantBatch (Honeywell) iBatch (Intellution) RSBatch (Rockwell) DeltaV (Emerson)The vendor name should not be included in the argument (i.e. only “DeltaV” or “iBatch” is used).The default, if the argument is not used, is “OpenBatch.”




/bidchar=nOptional

The first n characters are stripped from the value in BatchID column and used as the BatchID for the PIBatch. If n is larger than the BatchID column value, then the entire the complete string is used as the BatchID for the PIBatch. This switch is effective only if /merge is.

/biddOptional

The /bidd (BatchID Dynamic format) switch is used used in conjunction with /bidf=n[:c:p:a]. When/bidd is used, a BatchID with the minimum number (n) of digits is searched. If there is no match then the interface searches for n+1 contiguous digits and so on until a match is found or the length of the BatchID string is reached. If there is no match, then the complete string in the BatchID column of the event file is used as the BatchID for the PIBatch. If more than one match is found then the first substring is used. If there are characters embedded within the substring, then in the dynamic format it is necessary to specify whether the digit count should be increased before or after the characters. The anchor value a serves this purpose. Example for /bidd in conjunction with /bidf to extract a substring from the BatchID column in the event file:Let’s say that the BatchID column in the event file is lot30112 / 90dev124 / 12345stp / ld567 / 201num54. If /bidf=3:0:0:0 means that there are 3 contiguous digits and no characters in the substring. Since there are multiple matches, the first substring is used and the result will be 124. If /bidf=4:0:0:0 means that there are 4 contiguous digits and no characters in the substring. There is no match for 4 contiguous digits. Hence the search continues for a 5 contiguous digits. Since there are two matches, the first substring is used and the result will be 30112. Note that without the /bidd switch, the BatchID would be the entire string.If /bidf=5:0:0:0 means that there are 5 contiguous digits and no characters in the substring. Since there are two matches, the first substring is used and the result will be 30112. If /bidf=6:0:0:0 means that there are 6 contiguous digits and no characters in the substring. There is no match for 6 contiguous digits. Hence the search continues for a 7 contiguous digits. There is no match for 7 contiguous digits. Hence the search continues for 8 contiguous digits and so on but there is never a match for more than 5 contiguous digits. Therefore the complete string lot30112 / 90dev124 / 12345stp / ld567 / 201num54 is used as the BatchID. If /bidf=5:3:1:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the first digit. The resulting BatchID will be lot30112. If /bidf=5:3:6:0 means that there are 5 contiguous digits

60


with 3 contiguous characters and the characters are placed before the sixth digit (in this case it means at the end of the 5 digit number). Hence the resulting BatchID will be 12345stp. If /bidf=4:3:3:0 means that there are 4 contiguous digits with 3 contiguous characters and the characters are placed before the third digit. There is no match for the given criteria. So, the number of contiguous digits for the substring is increased to 5. Since the number of digits is increased, the position of the characters becomes ambiguous because the increased digit can be either before or after the three characters. This means the two possibilities are 90dev124 and 201num54. The last value in the switch specifies where the increased digit should be added. A value of zero (as in this case) means the number of digits to the left of the characters is fixed and hence the result will be 90dev124. If /bidf=4:3:3:1 is used, the result would be 201num54.If /bidf=4:3:3:1 means that there are 4 contiguous digits with 3 contiguous characters and the characters are placed before the third digit. There is no match for the given criteria. So, the number of contiguous digits for the substring is increased to 5. Since the number of digits is increased, the position of the characters becomes ambiguous because the increased digit can be either before or after the three characters. This means the two possibilities are 90dev124 and 201num54. The last value in the switch specifies where the increased digit should be added. A value of one (as in this case) means the number of digits to the right of the characters is fixed and hence the result will be 201num54. If /bidf=4:3:3:0 is used, the result would be 90dev124.

/bidf=n[:c:p:a]Optional

The /bidf (BatchID Fixed format) switch is used to obtain a new BatchID, which is a substring of the value in the BatchID column in the event file. The /bidf takes four values in the format /bidf=n:c:p:a where n represents a fixed number (greater than zero) of contiguous digits in the desired BatchID, c represents the number of contiguous characters embedded in the substring to be extracted, p represents the starting position of the characters with respect to the contiguous digits and a represents the anchor point for the varying digit count. N must have a value greater than zero specified if /bidf=n:c:p:a is used but c, p and a take default value of zero. A substring from the BatchID column in the event file is determined based on these criteria. If there is no match, then the complete string in the BatchID column of the event file is used as the BatchID for the PIBatch. If there are multiple matches, the first substring is used as the BatchID for the PIBatch. If the number of contiguous digits could vary, then the /bidd switch must also be used in conjunction with /bidf. Example for /bidf to extract a substring from the BatchID




column in the event file:Let’s say that the BatchID column in the event file is lot30112 / 90dev123 / 12345stp / ld567. If /bidf=5:0:0:0 means that there are 5 contiguous digits and no characters in the substring. Since there are two matches, the first substring is used and the result will be 30112. If /bidf=6:0:0:0 means that there are 6 contiguous digits and no characters in the substring and there is no match for this and the complete string lot30112 / 90dev123 / 12345stp is used as the BatchID. If /bidf=3:0:0:0 means that there are 3 contiguous digits and no characters in the substring. Since there are two matches, the first substring is used and the result will be 123. If /bidf=5:3:1:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the first digit. Hence the resulting BatchID will be lot30112. If /bidf=5:3:3:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the third digit. Hence the resulting BatchID will be 90dev123. If /bidf=5:3:6:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the sixth digit (in this case it means at the end of the 5 digit number). Hence the resulting BatchID will be 12345stp.

/bidm=<mask list>Optional

The /bidm switch (Batch ID Mask) is used to obtain a new BatchID, which is a substring of the value in the BatchID column in the event file. The /bidm takes a list of masks as the input value. Each BatchID mask can consist of an array of valid symbols and wildcards. The following wildcards are supported the interface:# - single digit numerical value (0-9)@ - single alpha character (a-z, A-Z)? – any single valid symbol! – repeat previous BatchID mask symbol

- any array of ? symbols.

Example:Let’s say that the BatchID column in the event file is lot30112 / 90dev123 / 12345stp / ld567. The /bidm=”#####” will result in new BatchID 30112.The /bidm=”##@!” will result in new BatchID 90dev.The /bidm=”*##@!” will result in new BatchID lot30112 / 90dev.The /bidm=”@@@@, #8dev4, #!” will result in new BatchID 30112. Since the first and second masks could not be found, third mask is used instead.

62


Note: This switch replaces /bidf, /bidd and /bidchar.

/cernOptional

The /cern switch (Combine Equipment and Recipe Names) is used when the user wishes to have the interface name its Sub-PI SubBatches as a combination of the name of a phase in the recipe structure (name of instance of the class of a phase) and the class name of the phase (which appears in the “Phase” column of the *.evt file. The default value is not to combine names, only the user specified instance name (in the “Recipe” column) is used.

/costOptional

The/cost switch will Create Only String Type points for the events irrespective of what data type is encountered. This applies only to new points created by the interface and is not applicable if /spc is used.

/db[=##]Optional

The /db[=##] switch specifies the interface debug logging message level. The various levels that may be assigned are as follows: 0 – Log all messages (LOG_ALL) 1 – Log all runtime messages (LOG_DEBUG) 2 – Log additional informational messages (LOG_LOW) 3 – Log minor errors (issues arising from optional switch use) (LOG_MEDIUM) 4 – Log major errors (LOG_HIGH) 5 – Log critical/fatal errors (LOG_CRITICAL)Log level zero (0) is the most verbose setting, while level five (5) reports the least detail (it logs only those error messages that are fatal to interface operation). The default logging level is 3 (LOG_MEDIUM), to log errors only. When testing the interface, it may be necessary to use a more verbose setting (0,1, or 2).

/ec=#Optional

The first instance of the /ec parameter on the command-line is used to specify a counter number, #, for an I/O Rate point. If # is not specified, then the default event counter is 1. Also, if the /ec parameter is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, each copy of the interface that is running without /ec=# explicitly defined will write to the same I/O Rate point. This means either explicitly defining an event counter other than 1 for each copy of the interface or not associating any I/O Rate points with event counter 1. Configuration of I/O Rate points is discussed in the section called “I/O Rate Tag Configuration.”For interfaces that run on Windows nodes, subsequent instances of the /ec parameter may be used by specific interfaces to keep track of various input or output operations. Subsequent instances of the /ec parameter can be of the form /ec*, where * is any ASCII character




sequence. For example, /ecinput=10, /ecoutput=11, and /ec=12 are legitimate choices for the second, third, and fourth event counter strings.

/etopOptional

The /etop (Event Time Ordered Processing) switch informs the interface to process EVT files in time order, based on the current position’s timestamp within each file, rather than processing files based on filenamesNote: This feature will be disabled, if it is used in conjunction with the switch /rme (Recovery Mode Enabled).

/exc[=#,#,…]Optional

The /exc switch informs the interface of the type of events which are excluded (i.e. not saved) in the PIProperties of the PIBatch Object. Event types are designated by number and are specified as follows:1 = Active Binding2 = Active Step Change 3 = Active Step Change Commencing4 = Arbitration5 = Batch Deletion6 = Bind7 = Comment8 = Creation Bind9 = Event File Name10 = Formula Header11 = Mode Change12 = Mode Command13 = Operator Prompt14 = Owner Change15 = Param Download Verified16 = Phase Link Permissive Received17 = Phase Link Permissive Sent

29 = Phase Logic Arbitration 19 = Prompt20 = Prompt Response21 = Recipe Arbitration22 = Recipe Data23 = Recipe Data Changed24 = Recipe Header25 = Recipe Value26 = Recipe Value Change27 = Report28 = Scale Factor29 = State Change30 = State Command31 = Step Activity32 = System Message38 = Equipment Prompt39 = Equipment Selection40 = Phase Batch Request41 = Unit Alias Binding42 = Unit Verified43 = Attribute Change44 = Transition Control

64

Parameter Description45 = Automatic Removal46 = ControlStep START47 = ControlStep STOP48 = Instruction Complete49 = Material Bound50 = Material Tracking51 = Material Unbound52 = Promise Event53 = Report Parameter Deviation54 = Signature Request Cancelled55 = Signature Request Completed56 = Signature Request Created 57 = Step Reactivation58 = Step Reactivation Request59 = Successful Signoff60 = Unsuccessful SignoffFor example, /exc=1,3,4,5,11would specify that the interface would not place Active Binding, Active Step Change Commencing, Arbitration, Batch Deletion, and Mode Change events in the PIProperties of the PIBatch object.If the /exc is specified with no argument, then no events are placed in the PIProperties.




/f=SS.##or/f=SS.##,SS.##or /f=HH:MM:SS.##or/f=HH:MM:SS.##,hh:mm:ss.##

Required for reading scan-based inputs

The /f parameter defines the time period between scans in terms of hours (HH), minutes (MM), seconds (SS) and sub-seconds (##). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), seconds (ss) and sub-seconds (##). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds. Each instance of the /f parameter on the command-line defines a scan class for the interface. There is no limit to the number of scan classes that can be defined. The first occurrence of the /f parameter on the command-line defines the first scan class of the interface; the second occurrence defines the second scan class, and so on. PI Points are associated with a particular scan class via the Location4 PI Point attribute. For example, all PI Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values at the frequency specified by the second scan class, and so on. Two scan classes are defined in the following example:/f=00:01:00,00:00:05 /f=00:00:07or, equivalently:/f=60,5 /f=7The first scan class has a scanning frequency of 1 minute with an offset of 5 seconds, and the second scan class has a scanning frequency of 7 seconds. When an offset is specified, the scans occur at discrete moments in time according to the formula:scan times = (reference time) + n(frequency) + offsetwhere n is an integer and the reference time is midnight on the day that the interface was started. In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class. This means that if the interface was started at 05:06:06, the first scan would be at 05:07:05, the second scan would be at 05:08:05, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined.The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the interface is under a large load, then some scans may occur late or be skipped entirely. See the section called Performance Point Configuration for more information on skipped or missed scans.

66


Sub-second Scan ClassesSub-second scan classes can be defined on the command-line, such as/f=0.5 /f=00:00:00.1where the scanning frequency associated with the first scan class is 0.5 seconds and the scanning frequency associated with the second scan class is 0.1 of a second.Similarly, sub-second scan classes with sub-second offsets can be defined, such as/f=0.5,0.2 /f=1,0Wall Clock Scheduling

Scan classes that strictly adhere to wall clock scheduling are now possible. This feature is available for interfaces that run on Windows and/or UNIX. Previously, wall clock scheduling was possible, but not across daylight saving time. For example, /f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a Daylight Saving Time change, the scan would occur either at 7 AM or 9 AM, depending upon the direction of the time shift. To schedule a scan once a day at 8 AM (even across daylight saving time), use /f=24:00:00,00:08:00,L. The ,L at the end of the scan class tells UniInt to use the new wall clock scheduling algorithm.

/fnapcOptional

The /fnapc switch (Formula Name As Product Code) allows to use “Formula Name” instead of “Product Code” Pvalue as PI Batch product name. If “Formula Name” Pvalue field is blank, original “Product Code” Pvalue field is used to retrieve product name.

/host=host:portRequired

The /host parameter is used to specify the PI Home node. Host is the IP address of the PI Sever node or the domain name of the PI Server node. Port is the port number for TCP/IP communication. The port is always 5450. It is recommended to explicitly define the host and port on the command-line with the /host parameter. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults. Examples:The interface is running on a PI Interface Node, the domain name of the PI home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host parameters would be:/host=marvin /host=marvin:5450 /host=206.79.198.30/host=206.79.198.30:5450




/id=xHighly Recommended

The /id parameter is used to specify the interface identifier. The interface identifier is a string that is no longer than 9 characters in length. UniInt concatenates this string to the header that is used to identify error messages as belonging to a particular interface. See the section called Appendix A:Error and Informational Messages for more information.UniInt always uses the /id parameter in the fashion described above. This interface also uses the /id parameter to identify a particular interface copy number that corresponds to an integer value that is assigned to one of the Location code point attributes, most frequently Location1. For this interface, use only numeric characters in the identifier. For example,/id=1

/ktinid=####Optional

The Keep Trailing Instance Id switch specifies at which levels of batch hierarchy the interface should keep the trailing instance id. The passed value must be a four digit binary number. Digits represent batch levels and should be specified in the following order: Procedure, Unit Procedure, Operation, and Phase. In order to keep the instance trailing id, the specific digit should be set to 1, otherwise to 0. Exampe:The Recipe column contains the following value:P_TEST\\UP_TEST\\OP_TEST:1-1\\PH001:1-1Without the switch, the interface will read the Procedure name as P_TEST, Unit Procedure name as UP_TEST,Operation name as OP_TEST:1,Phase name as PH001:1,With the switch /ktinid=0001, the interface will keep the trailing instance id for Phase name as PH001:1-1

/langpath[=<foreign language translation path and file>] Optional

The /langpath flag specifies the directory and file where the interface should look to find the language translations for the logic triggering events. If this switch is not used, then the interface assumes that the default language of English is to be used. If a path and file is not specified, then the interface looks for the event translations in the c:\winnt\langfile.ini file. If that file is not found, and the switch is specified, then an error is generated and the interface will not start.

68


/logtotag=#[,#,…]Optional

The /logtotag=#[,#,…] switch specifies which events messages will be logged to a string tag. See section Event Logging for more information concerning this behavior. The syntax for the switch is similar to that for the /exc=[#,#,…] switch. However, the user must specify at least one event type, there is no default event that is logged to a string tag.For example, /logtotag=1,3,4,5,11would specify that the interface would place Active Binding, Active Step Change Commencing, Arbitration, Batch Deletion, and Mode Change events in separate string tags when those events are found in the event journal.

/mergeOptional

The /merge switch allows the interface to merge multiple event files with same BatchID into one PIBatch. If there are overlapping Unit Procedures on any Units within the merged event files, the Unit Procedures will be merged into one PIUnitBatch. The /pmt switch must be specified along with the /merge switch.Note: Only one switch out of three (/mmm, /merge, /mup) is allowed to be used as command line parameter. The interface will not start up if any two of these switches are specified in the command line parameters..

/mmmOptional

The /mmm switch specifies that the interface will attempt to compare and merge the current unit batch with the previous one. This merge will only occur when (in addition to this switch being present) the unit, unit procedure name, and batch id match between the old and new unit procedures (this is most common with Manual Mode intervention, where the BES often has to reallocate resources after the being placed back into Auto mode). This switch is recommend, (and required for the interface, if manual mode intervention is standard operating procedure with respect to BES operation).Note: Only one switch out of three (/mmm, /merge, /mup) is allowed to be used as command line parameter. The interface will not start up if any two of these switches are specified in the command line parameters.




/mupOr/mup=<separator>Optional

The Merge Unit Procedures (/mup) switch is used to merge parallel PIUnitBatches into one PIUnitBatch on any PIUnit. The parallel PIUnitBatches should be in the same Event File. The merging will be based on number of occurrences of System Message events for each unit in the same Event file. Since there could be Operations with same name in the merged PIUnitBatches, the Operation names are modified with the following syntax:<new operation name> = <unit procedure name> <separator> <original operation name>The <separator> is the value specified through this switch. If no value is specified, then a double space will be used as the separator.Example 1: no separator specified (/mup) <new operation name> = “UP_TEST:1 OP_TEST:1:1”Example 2: A separator is specified. (/mup=”__”) <new operation name> = “UP_TEST:1___OP_TEST:1:1”In case of Operation Level recipes, the Operations are also merged along with the PIUnitBatches. For more details on how this switch works, read the section titled “Merging Parallel PIUnitBatches into a Single PIUnitBatch in the Same Event File“.Note: Only one switch out of three (/mmm, /merge, /mup) is allowed to be used as command line parameter. The interface will not start up if any two of these switches are specified in the command line parameters.

/nodataOptional

This switch is used to create only recipe tags, modules, units and aliases. With this switch enabled, the interface will not write any batch data or populate tags with events on the PI Server. The main purpose of this switch is to preprocess EVT files, such that older archives can be reprocessed and backfilled.

70


/ns=[lang]Optional

The /ns (Numeric Settings) switch allows the interface to perform proper numerical conversions based on the “Regional and Language Options” setting on local system or based on user defined language. This switch is particularly useful when the numerical conventions differ (example a comma is used instead of a decimal etc) from the default settings.If the switch is not used, then the default settings of “English_UnitedStates” is used.If the switch is used without any language specification, i.e. /ns, then the interface will use “Regional and Language Options” settings specified on the Windows machine where the interface is running. If the language specification is passed as a value (/ns=lang), then the interface will use that value as internal regional/language setting to perform numerical conversions regardless of local system “Regional and Language Options” setting. If the switch contains invalid language, .i.e /ns=<invalid language>, then the interface will exit.The language can be passed by type as it is specified below or by its abbreviation.Language types (abbreviations): 71talian 71talian-simplified (chs) 71talian-traditional (cht)71tali (csy) 71talia (dan) 71talian, dutch-belgian (nlb) dutch (nld) 71talian71se, 71talian-aus (ena) 71talian71, 71talian-can (enc) 71talian 71talian-nz (enz) 71talian-uk (uk) 71talian71, 71talian71-english, 71talian-american, 71talian-us, 71talian-usa, (enu) (us) (usa) finnish (fin) 71talia-belgian (frb) 71talia-canadian (frc) 71talia (fra) 71talia-swiss (frs) german-swiss, swiss (des) german (deu) gegerman-austrian (dea) greek (ell)71talian71s (hun) 71talian71s (isl) 71talian (ita) 71talian-swiss (its) 71talian71 (jpn) 71talia (kor) 71talian71s-bokmal (nor)71talian71s



Parameter Description72talian72s-nynorsk (non) polish (plk) 72talian72se-brazilian (ptb) 72talian72se (ptg) 72talian (rus) 72talia (sky) 72talian (esp) 72talian-mexican (esm) 72talian-modern (esn) 72talian (sve) 72talian (trk)Examples:/ns - will set the interface to use the local Windows language/regional settings/ns=72talian /ns=itaBoth switches will set the interface to use Italian language/regional settings.

/path=<event journal path>Required

The /path flag specifies the directory where the interface should look to find the event journal files.

/pmt=#Required with /merge switch

The /pmt PIBatch Merge Time switch specifies the merge time in days. When a new event file is processed, the interface searches the PI Batch Database for existing PIBatches that match the BatchID of the new event file. The /pmt limits the time range in which the interface will perform this search. The search is limited to # days before the start of the new event file and # days after the start of the new event file. For Batches with identical BatchIDs to be merged. Typically # represents the maximum total duration of all the event files that might be merged. Example:If there are 3 batches and each batch is 1 day long and if the idle period between each batch is also 1 day then /pmt=5 will merge all three event files into one PIBatch.

/pospath=<position file path>Required

The /pospath flag specifies the directory where the interface should store its position (*.pos) files for recovery purposes.

/product=”product name”Optional

The /product switch will allow a value to be used for ProductID attributes of the PIBatch and PIUnitBatches. This switch will be effective only when the event file does not contain a product value or if the value in the event file is equal to “UNDEFINED”.

72


/ps=xRequired

The /ps parameter specifies the point source for the interface. X is not case sensitive and can be any multiple character string. For example, /ps=P and /ps=p are equivalent. The point source that is assigned with the /ps parameter corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source.

/ras=<start, stop>Optional

The /ras Report As Step switch allows to use the “Report” event to create Phase Steps under active Phase States. The Phase Step name and start/stop events are obtained from the “Descript” column. Note: if the Phase Step left open, it is going to be closed by the end of the parent operation, and not by the end of parent phase or phase state.Example: /ras=”-STRT, -STOP”Event – Report: Descipt Column: TEST123-STRT-B. Triggers the start of the Phase Step “TEST123” under the currently active Phase State.Event – Report: Descipt Column: TEST123-STOP-B. Sets an end time on the Phase Step “TEST123”, if it can be found and regardless of what is the active Phase State.

/rdt=#Optional(version 3.0.0.36 and greater)

The /rdt=# switch configures a Rename Delay Time in which the interface will wait after registering the “End Of BATCH” system message which normally triggers the closing of the event file object in memory and renaming of the file. # is the number of seconds to delay. The default value for the rename delay is 0 seconds.




/recipetags=#[,#,…]Optional

The /recipetags=#[,#,…] parameter specifies which events messages will be logged to a recipe tag (also defined as specific tag). The syntax for the parameter is similar to that for the /logtotag=[#,#,…] parameter. However, the user must specify at least one event type, there is no default event that is logged to a recipe tag.Note: By specifying this parameter in the command line, the default behavior of creating 5 different event types is disabled.Available event types:14 – Owner Change15 – Param Download Verified19 – Prompt25 – RecipeValue27 – ReportFor example, /recipetags=14,25would specify that the interface would create tags only for the Owner Change and Recipe Value events found in the event journal.

/retrytimeout=#Optional, obsolete

The /retrytimeout switch specifies the timeout, specified in minutes, for retrying a failed attempt to write data to PI. This timeout is effective only for generic errors and not errors that clearly indicate lost connection to the PI Sever of any of PI Subsystems are not available. Note: This switch is OBSOLETE.

74


/rmeOptional(version 3.1.0.42 and greater)

The /rme (Recovery Mode Enabled) feature allows for the insertion and backfilling of PI Batch in the past. Use of this switch causes the Event File Interface to read the file normally, but to create PI UnitBatches with a 1 second duration (since record of the start event of the unit procedure does not contain any information about the termination of the unit procedure).As such, the PI UnitBatch is created and then when the end time is properly triggered (i.e. the Unit Procedure ends or the physical unit is released) the interface will edit the unit batch with the correct end time. Note: this is a true edit. The PI Audit Database, if enabled, will show that this PI UnitBatch has been edited. Also, the status of the PI Batches and PI UnitBatches that are populated in this mode will have their statuses listed as “Recovered.”By default, recovery mode is not enabled. This switch is not recommended under normal runtime conditions for two (2) main reasons: 1) all PI UnitBatches will show a 1 second duration with all PI visualization clients and PI batchDB search results until they completed; 2) all PI UnitBatches created with recovery mode on will be shown to be edited in to the PI Audit DB. Note, the interface cannot create PI Points or PI Modules in archives that are not the primary archive. As such, the use of this switch will not enable the insertion of data that requires PI Point or PI Module creation for a past timeframe in a non-primary archive. The target archive must already be aware of PI Points and PI Modules that are to reference the data.

/rsmOptional

The Reset System Message (/rsm) switch resets the System Message flag for a unit when the Recipe Arbitration event “Resource Released by recipe” occurs. It means that if the Recipe Arbitration event was used to close the active PIUnitBatch, the interface would require both event types to be present in order to start a new PIUnitBatch. The /rsm switch can be used in conjunction with the /mup switch. In this case, the /rsm switch will also reset the system message counter to zero on active unit.

/rtd=#Optional

The /rtd (Retry Time Delay) switch specifies the retry time delay, in seconds, for retrying a failed SDK attempt to write data to PI. The default retry delay is set to 60 seconds.

/rto=#Optional

The /rto (Retry TimeOut) switch specifies the timeout, in seconds, for retrying a failed SDK attempt to write data to PI. The default timeout is set to 0 seconds (infinity). In order to prevent data loses, it is recommended NOT to use the retry timeout switch.




/skipphases=<phase list>Optional

The /skipphases switch specifies the list of phases for which all events in the event file should be ignored. This interface will check for the value in the “PHASE” column and the “Recipe” column in the Event File and if one of those two values equals one of the phases in this list, the interface will skip processing that row. The interface solely depends on the phase name without instance numbers. The name comparison is not case sensitive. Multiple phase names can be specified with a comma separator. If there is a space in the phase name list, use double quotes for the entire switch. This switch is available only with version 3.8.4.8 and greater.Note: with interface version 3.8.5.1, phase masks are allowed as valid phase specifiers. The following wildcards are supported in masks by the interface:# - single digit numerical value (0-9)@ - single alpha character (a-z, A-Z)? – any single valid symbol! – repeat previous BatchID mask symbol


Example: /skipphases=phase_1,ph*2 or /skipunits=”phase_1, ph*2”The following phases: PH_TEST:1-1, PH_ABORT:2-2 should be ignored by the interface. The switch will have the following form: /skipphases=”PH_TEST, PH*ORT“

/skipunits=<unitlist>Optional

The /skipunits switch specifies the list of units for which all events in the event file should be ignored. This interface will check for the value in the “UNIT” column and the “PVAL” column in the Event File and if one of those two values equals one of the units in this list, the interface will skip processing that row. The interface solely depends on the unit name (and not on the Area or ProcCell values in the Event File) and the name comparison is not case sensitive. Multiple unit names can be specified with a comma separator. If there is a space in the unit name, use double quotes for the entire switch. This switch is available only with version 3.7.0.15 and greater.Note: with interface version 3.8.5.1, unit masks are allowed as valid unit specifiers. The following wildcards are supported in masks by the interface:# - single digit numerical value (0-9)@ - single alpha character (a-z, A-Z)? – any single valid symbol! – repeat previous BatchID mask symbol


Example: /skipunits=unit_1,u*2 or /skipunits=”unit_1, u*2”

76


/smp=”PI Module Path”Optional

The /smp switch designates an alternate PI Module path to start looking for a particular Area->ProcessingCell->Unit hierarchy. If this option is not specified (i.e. the default) is to begin at the root level of the PI ModuleDB. A path must be specified. This path is of the syntax: \\<RootModule>\<SubModule>\<…>e.g. \\MyEnterprise\MyPlant\The PI server is not specified in this syntax, since that is already known from the /host switch.

/spcOptional

The /spc (Suppress Point Creation) switch suppresses the automatic creation of points and aliases by the interface. This switch will not stop the interface from creating its global string tag pool points or the interface and PI Unit status points.

/spsOptional

The /sps (Suppress Phase State) switch suppresses the automatic creation of the phase state PI subbatch by the interface.

/stopstator/stopstat=digstateDefault:/stopstat=”Intf Shut”Optional

If the /stopstat parameter is present on the startup command line, then the digital state Intf Shut will be written to each PI Point when the interface is stopped. If /stopstat=digstate is present on the command line, then the digital state, digstate, will be written to each PI Point when the interface is stopped. For a PI 3 Server, digstate must be in the system digital state table. For a PI 2 Server, where there is only one digital state table available, digstate must simply be somewhere in the table. UniInt uses the first occurrence in the table.If neither /stopstat nor /stopstat=digstate is specified on the command line, then no digital states will be written when the interface is shut down.Examples:/stopstat=shutdown/stopstat=”Intf Shut” The entire digstate value should be enclosed within double quotes when there is a space in digstate.

/sucOptional

The /suc (Suppress Unit Creation) switch suppresses the automatic creation of units and aliases in the interface.

/sulaOptional

The /sula (Suppress Unit Level Alias) switch allows the user to stop the interface from creating aliases at the base unit level. This switch does not stop the interface from creating the aliases at the PhaseName sub PI Module level.




/tagpool=<threshold>Optional

This switch is used to specify a custom threshold value for the stringpool tags. On each PIBatch start, if the stringpool tag pool does not contain sufficient tag count (number of currently available tags is below threshold), the interface will create additional sets of stringpool tags with the count set to twice the threshold value. The default threshold is set to 25 tags.Example: /tagpool=30Assume there are a total of 50 stringpool tags, and 12 event types are logged into these tags for each batch. There are 4 batches running in parallel, which implies that all 4 batches are using 48 stringpool tags in total. Then a fifth parallel batch starts and requests 12 stringpool tags. In the pool, there are only 2 tags currently available, this condition will trigger the interface to create an additional set of 60 stringpool tags.

/tf=<time format>Optional

This switch is used to specify an EVT file event timestamp format. The following characters are allowed in time format switch value:yy, yyyy - Year, 2 or 4 digitsM, MM - Month, short/long number MMM, MMMM - Month, short/long named, dd - Day, short/long numberh, hh - Hour, short/long numberm, mm - Minute, short/long numbers, ss - Seconds, short/long number0 – 000000 - Fraction of second, show trailing zeros# - ###### - Fraction of second, no trailing zeros

Example: /tf=”YYYY/MM/dd hh:mm:ss.000”

/uenOptional

The /uen switch Uses English Names for <eventype> in a point name, alias name and PIModule name even when a language file is used to translate EventType. All other parameters, <unitname>(<phase>):<descript>, used in point name will still remain in the same language as shown in the Event file.

78


/unittags=#[,#,…]Optional

The /unittags=#[,#,…] switch specifies the PIUnitBatch properties which will be logged into PIPoints. The switch can have one or more values separated by a comma. The following set of tags is available for each unit:

1) BatchID tag (Loc2=34, point type=string). The events written into the tag are <BatchID name> at the beginning of the PIUnitBatch and “Inactive” at the end of the PIUnitBatch

2) Product tag (Loc2=35, point type=string). The events written into the tag are < Product name > at the beginning of the PIUnitBatch and “Inactive” at the end of the PIUnitBatch

3) Procedure Name tag (Loc2=36, point type=string). The events written into the tag are <Procedure Name name> at the beginning of the PIUnitBatch and “Inactive” at the end of the PIUnitBatch

4) Unit Activity tag (Loc2=37, point type=integer). The events written to the tag are 1 at the beginning of the PIUnitBatch and 0 at the end of the PIUnitBatch

Example, /unittags=34,37will log the BatchID and the unit activity values



Sample EVTIntf.bat FileThe following is an example file:REM======================================================================== REMREM EVTINTF.batREMREM Sample startup file for the Event File Interface to the PI SystemREMREM========================================================================REM REM OSIsoft strongly recommends using the PI ICU to modify startup files.REMREM Sample command lineREM

evtintf.exe ^/pospath=d:\pipc\interfaces\evtintf\posfiles\ ^ /PATH=\\BatchServer\Journals\ ^/HOST=XXXXXX:5450 ^/PS=EVTIntf ^/ID=1 ^/EC=11 ^/bestype=DeltaV ^/exc ^/logtotag=32 ^/f=00:00:30

REMREM end of EVTINTF.bat

80

Interface Node ClockMake sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,

In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,

C:> set

Make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Advanced Tab and then the Environment Variables button, and remove TZ from the list of environment variables.


SecurityThe PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. 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 the PI Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.

PI Server v3.3 and HigherSecurity configuration using piconfigFor PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:C:\PI\adm> piconfig@table pitrust@mode create@istr Trust,IPAddr,NetMask,PIUsera_trust_name,192.168.100.11,255.255.255.255,piadmin@quit

For the above,

Trust: An arbitrary name for the trust table entry; in the above example,

a_trust_name

IPAddr: the IP Address of the computer running the Interface; in the above example,

192.168.100.11

NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr

PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user

Security Configuring using Trust EditorThe Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table.

See the PI System Management chapter in the PI Server manual for more details on security configuration.

PI Server v3.2For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:C:\PI\adm> piconfig@table pi_gen,piproxy


@mode create@istr host,proxyaccountpiapimachine,piadmin@quitIn place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.


Starting / Stopping the InterfaceThis section describes starting and stopping the interface once it has been installed as a service. See the UniInt Interface User Manual to run the interface interactively.

Starting Interface as a ServiceIf the interface was installed a service, it can be started from PI ICU, the services control panel or with the command:EVTIntf.exe –start

To start the interface service with PI ICU, use the button on the PI ICU toolbar.

A message will inform the user of the the status of the interface service. Even if the message indicates that the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons, and one typical reason is that the service is not able to find the command-line parameters in the associated .bat file. Verify that the root name of the .bat file and the .exe file are the same, and that the .bat file and the .exe file are in the same directory. Further troubleshooting of services might require consulting the pipc.log file, Windows Event Viewer, or other sources of log messages. See the section “Appendix A: Error and Informational Messages,” for additional information.

Stopping Interface Running as a ServiceIf the interface was installed a service, it can be stopped at any time from PI ICU, the services control panel or with the command:EVTIntf.exe –stopThe service can be removed by:EVTIntf.exe –remove

To stop the interface service with PI ICU, use the button on the PI ICU toolbar.


BufferingThis Interface is not compatible with OSIsoft’s standard buffering mechanisms, PI API Buffer Server (Bufserv) and the PI Buffer Subsystem (PIBufss). Instead, the Interface sends data directly to the archive.


Interface Diagnostics ConfigurationThe Interface Point Configuration chapter provides information on building PI points for collecting data from the device. This chapter describes the configuration of points related to interface diagnostics.

The procedure for configuring interface diagnostics is not specific to this Interface. Thus, for simplicity, the instructions and screenshots that follow refer to an interface named Generic. In actuality, OSIsoft does not offer an interface called Generic.

Some of the points that follow refer to a “performance summary interval”. This interval is 8 hours by default. You can change this parameter via the Scan performance summary box in the UniInt – Debug parameter category pane:

Scan Class Performance PointsA Scan Class Performance Point measures the amount of time (in seconds) that this Interface takes to complete a scan. The Interface writes this scan completion time to millisecond resolution. Scan completion times close to 0 indicate that the Interface is performing optimally. Conversely, long scan completion times indicate an increased risk of missed or skipped scans. To prevent missed or skipped scans, you should distribute the data collection points among several scan classes.

You configure one Scan Class Performance Point for each Scan Class in this Interface. From the ICU, select this Interface from the Interface drop-down list and click UniInt-Performance Points in the parameter category pane:


Right click the row for a particular Scan Class # to bring up the context menu:

Click Create to create the Scan Class Performance Point for that particular row. Click Create All to create all the Scan Class Performance Points.

You need not restart the Interface for it to write values to the Scan Class Performance Points.

To see the current values (snapshots) of the Scan Class Performance Points, right click and select Refresh Snapshots.

Performance Counters PointsWhen running as a Service, this Interface exposes performance data via Windows Performance Counters. Such data include:

the amount of time that the Interface has been running;

the number of points the Interface has added to its point list; and

the rate at which the Interface is collecting data.

90

OSIsoft’s PI Performance Monitor Interface is capable of reading these performance values and writing them to PI points. Please see the Performance Monitor Interface to the PI System for more information.

If there is no PI Performance Monitor Interface is installed as a Service on the same computer running this Interface, you cannot use the ICU to create this Interface’s Performance Counters Points:

After installing the PI Performance Monitor Interface as a service, select this Interface from the Interface drop-down list, click Performance Counters in the parameter categories pane, and right click on a row containing a Performance Counters Point to bring up the context menu:


Click Create to create the Performance Counters Point for that particular row. Click Create All to create all the Performance Counters Points.

To see the current values (snapshots) of the Performance Counters Points, right click and select Refresh Snapshots.

The PI Performance Monitor Interface – and not this Interface – is responsible for updating the values for the Performance Counters Points. So, make sure that the PI Performance Monitor Interface is running correctly.

Up_timeThe up_time Performance Counters Point indicates the amount of time (in seconds) that this Interface has been running.

Io_ratesThe io_rates Performance Counters Point indicates the rate (in event per second) at which this Interface writes data to its input tags.

Log_file_msg_countThe log_file_msg_count Performance Counters Point indicates the number of messages that the Interface has written to pipc.log.

pts_edited_in_interfaceThe pts_edited_in_interface Performance Counters Point indicates the number of point edits the Interface has detected. The Interface detects edits only for those points whose PointSource attribute matches its Point Source parameter and whose Location1 attribute matches its Interface ID parameter.

92

Pts_added_to_interfaceThe pts_added_to_interface Performance Counters Point indicates the number of point added the Interface has added to its point list.

Pts_removed_from_interfaceThe pts_removed_from_interface Performance Counters Point indicates the number of point added the Interface has removed from its point list.

Point_countA point_count Performance Counters Point is available for each Scan Class of this Interface. The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1(Scan Class 1).point_count refers to Scan Class 1, “(Scan Class 2)” refers to Scan Class 2, and so on. The tag containing “_Total” refers to the sum of all Scan Classes.

This point indicates the number of tags per Scan Classes.

Scan_timeA scan_time Performance Counters Point is available for each Scan Class of this Interface. The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1(Scan Class 1).scan_time refers to Scan Class 1, “(Scan Class 2)” refers to Scan Class 2, and so on.

The scan_time Performance Counters Point indicates the number of milliseconds the Interface takes to read data from the device and fill in the values for the tags. This point is similar to the [UI_SCINCANTIME] Health Point.

Sched_scans_%missedA sched_scans_%missed Performance Counters Point is available for each Scan Class of this Interface. The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1(Scan Class 1).sched_scans_%missed refers to Scan Class 1, “(Scan Class 2)” refers to Scan Class 2, and so on. The tag containing “_Total” refers to the sum of all Scan Classes.

The sched_scans_%missed Performance Counters Point indicates the percentage of scans the Interface missed since startup. A missed scan occurs if the Interface performs the scan one second later than scheduled.

Sched_scans_%skippedA sched_scans_%skipped Performance Counters Point is available for each Scan Class of this Interface. The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1(Scan Class 1).sched_scans_%skipped refers to Scan Class 1, “(Scan Class 2)” refers to Scan Class 2, and so on. The tag containing “_Total” refers to the sum of all Scan Classes.

The sched_scans_%skipped Performance Counters Point indicates the percentage of scans the Interface skipped since startup. A skipped scan is a scan that occurs at least one scan period after its scheduled time.

Sched_scans_this_intervalA sched_scans_this_interval Performance Counters Point is available for each Scan Class of this Interface. The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, sy.perf.etamp390.E1(Scan Class


1).sched_scans_this_interval refers to Scan Class 1, “(Scan Class 2)” refers to Scan Class 2, and so on. The tag containing “_Total” refers to the sum of all Scan Classes.

The sched_scans_this_interval Performance Counters Point indicates the number of scans that the Interface performed per performance summary interval.

Interface Health Monitoring PointsInterface Health Monitoring Points provide information about the health of this Interface. To use the ICU to configure these points, select this Interface from the Interface drop-down list and click Health Points from the parameter category pane:

Right click the row for a particular Health Point to bring up the context menu:

Click Create to create the Health Point for that particular row. Click Create All to create all the Health Points.

94

You need to restart the Interface for it to write values to the [UI_IF_INFO] Health Point only. Other Health Points do not require an interface restart.

To see the current values (snapshots) of the Health Points, right click and select Refresh Snapshots.

For some of the Health Points described subsequently, the Interface updates their values at each performance summary interval (typically, 8 hours).

[UI_IF_INFO]The [UI_IF_INFO] Health Point is the Interface Information Point. This point provides information for all interfaces that connect to a PI Server. The value of this point is a string that indicates:

the node name on which an interface is running;

the IP address on which an interface is running;

an interface’s executable name;

an interface’s Point Source parameter;

an interface’s Interface ID parameter;

an interface’s Scan Classes;

the number of points in an interface’s point list;

the number of messages to pipc.log that an interface has written; and

the number of seconds that an interface has been running.

An example value for the Interface Information Point is:etamp390 | 192.168.8.72 | ModbusE.exe | MODBUSE | ID 1 | 3 Scan Classes: 5; 60; 120 | Points 0 | Message Count 31 | Up Time 0

This Interface updates the value of the Interface Information Point every 30 minutes. Please consult the “Interface Health Points” section of the UniInt Interface User Manual for details on changing this update frequency.

[UI_HEARTBEAT]The [UI_HEARTBEAT] Health Point indicates whether the Interface is currently running. The value of this point is an integer that increments continuously from 1 to 15. After reaching 15, the value resets to 1.

The fastest scan class frequency determines the frequency at which the Interface updates this point:

Fastest Scan Frequency Update frequencyLess than 1 second 1 second

Between 1 and 60 seconds, inclusive

Scan frequency

More than 60 seconds 60 seconds

If the value of the [UI_HEARTBEAT] Health Point is not changing, then this Interface is in an unresponsive state.

[UI_DEVSTAT][[The following is interface specific]]


The [UI_DEVSTAT] Health Point provides an indication of the connection status between the Interface and the PLC(s) or PLC gateway. The possible values for this string point are:

“1 | Starting” – The Interface remains in this state until it has successfully collected data from its first scan.

“Good” – This value indicates that the Interface is able to connect to all of the devices referenced in the Interface’s point configuration. A value of “Good” does not mean that all tags are receiving good values, but it is a good indication that there are no hardware or network problems.

“4 | Intf Shutdown” – The Interface has shut down.

“5 | | 192.168.9.77 DISCONNECTED” – This value indicates that the Interface cannot establish the TCP/IP connection to 192.168.9.77. A possible cause is that there is a network problem. Another reason is that a tag is improperly configured; specifically, it refers to an incorrect IP address. However, after you have verified that your tag configuration is correct, this value is a good indication of network problems.

If the Interface cannot establish communication to multiple IP addresses, the value of this point contains these addresses. For example, “5 | | 172.16.10.10,172.16.10.11 DISCONNECTED”

“5 | | 1 Device IN EXCEPTION” – This value indicates that the PLC or PLC gateway returned an Exception Response of 4, 10, or 11. (Appendix A, “Troubleshooting” contains a list of Exception Responses.) The connection to the IP Address associated with the device is valid. However, the target device is either in severe error, unreachable, or unresponsive for some reason. You must look in the pipc.log file to determine the particular exception response and to determine the particular device and IP Address.

If there are disconnected IP Addresses as well as devices in exception, the Interface appends the “IN EXCEPTION” string to the “DISCONNECTED” error string.

“5 | | 6 IP Addresses DISCONNECTED or with devices IN EXCEPTION” – The Interface writes this value when the message associated with a “5 | | ... DISCONNECTED” or “5 | | ... IN EXCEPTION” exceeds 200 bytes. This error message reports only the number of IP addresses that are disconnected or the number of devices that return EXCEPTION response of 4, 10, or 11. You must retrieve detailed error information from the pipc.log.

The Interface updates this point whenever the connection status between the Interface and the PLC(s) or PLC gateway changes.

[UI_SCINFO]The [UI_SCINFO] Health Point provides scan class information. The value of this point is a string that indicates

the number of scan classes;

the update frequency of the [UI_HEARTBEAT] Health Point; and

the scan class frequencies

An example value for the [UI_SCINFO] Health Point is:

96

3 | 5 | 5 | 60 | 120

The Interface updates the value of this point at startup and at each performance summary interval.

[UI_IORATE]The [UI_IORATE] Health Point indicates the sum of

1. the number of scan-based input values the Interface collects before it performs exception reporting; and

2. the number of event-based input values the Interface collects before it performs exception reporting; and

3. the number of values that the Interface writes to output tags that have a SourceTag.

The Interface updates this point at the same frequency as the [UI_HEARTBEAT] point’s. The value of this [UI_IORATE] Health Point may be zero. A stale timestamp for this point indicates that this Interface has stopped collecting data.

[UI_MSGCOUNT]The [UI_MSGCOUNT] Health Point tracks the number of messages that the Interface has written to the pipc.log file since start-up. In general, a large number for this point indicates that the Interface is encountering problems. You should investigate the cause of these problems by looking in pipc.log.

The Interface updates the value of this point every 60 seconds. While the Interface is running, the value of this point never decreases.

[UI_OUTPUTRATE]After performing an output to the device, this Interface writes the output value to the output tag if the tag has a SourceTag. The [UI_OUTPUTRATE] Health Point tracks the number of these values. If there are no output tags for this Interface, it writes the System Digital State No Result to this Health Point.

The Interface updates this point at the same frequency as the [UI_HEARTBEAT] point’s. The Interface resets the value of this point to zero at each performance summary interval.

[UI_OUTPUTBVRATE]The [UI_OUTPUTBVRATE] Health Point tracks the number of System Digital State values that the Interface writes to output tags that have a SourceTag. If there are no output tags for this Interface, it writes the System Digital State No Result to this Health Point.


[UI_TRIGGERRATE]The [UI_TRIGGERRATE] Health Point tracks the number of values that the Interface writes to event-based input tags. If there are no event-based input tags for this Interface, it writes the System Digital State No Result to this Health Point.



[UI_TRIGGERBVRATE]The [UI_TRIGGERRATE] Health Point tracks the number of System Digital State values that the Interface writes to event-based input tags. If there are no event-based input tags for this Interface, it writes the System Digital State No Result to this Health Point.


[UI_SCPOINTCOUNT]You can create a [UI_SCPOINTCOUNT] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Point Count.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.

This Health Point monitors the number of tags in a Scan Class.

The Interface updates a [UI_SCPOINTCOUNT] Health Point when it performs the associated scan.

Although the ICU allows you to create the point with the suffix “.sc0”, this point is not applicable to this Interface.

[UI_SCIORATE]You can create a [UI_SCIORATE] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class IO Rate.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.

A particular Scan Class’s [UI_SCIORATE] point indicates the number of values that the Interface has collected. If the current value of this point is between zero and the corresponding [UI_SCPOINTCOUNT] point, inclusive, then the Interface executed the scan successfully. If a [UI_SCIORATE] point stops updating, then this condition indicates that an error has occurred and the tags for the scan class are no longer receiving new data.

The Interface updates the value of a [UI_SCIORATE] point after the completion of the associated scan.


[UI_SCBVRATE]You can create a [UI_SCBVRATE] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Bad Value Rate.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.

A particular Scan Class’s [UI_SCBVRATE] point indicates the number System Digital State values that the Interface has collected.

The Interface updates the value of a [UI_SCBVRATE] point after the completion of the associated scan.


98

[UI_SCSKIPPED]You can create a [UI_SCSKIPPED] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Scans Skipped.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.

A particular Scan Class’s [UI_SCSKIPPED] point tracks the number of scans that the Interface was not able to perform before the scan time elapsed and before the Interface performed the next scheduled scan.The Interface updates the value of this point each time it skips a scan. The value represents the total number of skipped scans since the previous performance summary interval. The Interface resets the value of this point to zero at each performance summary interval.

Although there is no “Scan Class 0”, the ICU allows you to create the point with the suffix “.sc0”. This point monitors the total skipped scans for all of the Interface’s Scan Classes.

[UI_SCSCANCOUNT]You can create a [UI_SCSCANCOUNT] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Scan Count.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.

A particular Scan Class’s [UI_ SCSCANCOUNT] point tracks the number of scans that the Interface has performed.The Interface updates the value of this point at the completion of the associated scan. The Interface resets the value to zero at each performance summary interval.

Although there is no “Scan Class 0”, the ICU allows you to create the point with the suffix “.sc0”. This point indicates the total number of scans the Interface has performed for all of its Scan Classes.

[UI_SCINSCANTIME]You can create a [UI_SCINSCANTIME] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Scan Time.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.

A particular Scan Class’s [UI_ SCINSCANTIME] point represents the amount of time (in milliseconds) the Interface takes to read data from the device, fill in the values for the tags, and send the values to the PI Server.The Interface updates the value of this point at the completion of the associated scan.

[UI_SCINDEVSCANTIME]You can create a [UI_SCINDEVSCANTIME] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Device Scan Time.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.


A particular Scan Class’s [UI_ SCINDEVSCANTIME] point represents the amount of time (in milliseconds) the Interface takes to read data from the device and fill in the values for the tags.

The value of a [UI_ SCINDEVSCANTIME] point is a fraction of the corresponding [UI_SCINSCANTIME] point value. You can use these numbers to determine the percentage of time the Interface spends communicating with the device compared with the percentage of time communicating with the PI Server.

If the [UI_SCSKIPPED] value is increasing, the [UI_SCINSCANTIME] points along with the [UI_SCINSCANTIME] points can help identify where the delay is occurring: whether the reason is communication with the device, communication with the PI Server, or elsewhere.

The Interface updates the value of this point at the completion of the associated scan.

I/O Rate PointAn I/O Rate point measures the rate at which the Interface writes data to its input tags. The value of an I/O Rate point represents a 10-minute average of the total number of values per minute that the Interface sends to the PI Server.

When the Interface starts, it writes 0 to the I/O Rate point. After running for ten minutes, the Interface writes the I/O Rate value. The Interface continues to write a value every 10 minutes. When the Interface stops, it writes 0.

The ICU allows you to create one I/O Rate point for each copy of this Interface. Select this Interface from the Interface drop-down list, click IO Rate in the parameter category pane, and check Enable IORates for this Interface.

As the preceding picture shows, the ICU suggests an Event Counter number and a Tagname for the I/O Rate Point. Click the Save button to save the settings and create the I/O Rate point. Click the Apply button to apply the changes to this copy of the Interface.

You need to restart the Interface in order for it to write a value to the newly created I/O Rate point. Restart the Interface by clicking the Restart button:

100

(The reason you need to restart the Interface is that the PointSource attribute of an I/O Rate point is Lab.)

To confirm that the Interface recognizes the I/O Rate Point, look in the pipc.log for a message such as:PI-ModBus 1> IORATE: tag sy.io.etamp390.ModbusE1 configured.

To see the I/O Rate point’s current value (snapshot), click the Refresh snapshot button:

Interface Status PointThe PI Interface Status Utility (ISU) alerts you when an interface is not currently writing data to the PI Server. This situation commonly occurs if

the monitored interface is running on an Interface Node, but the Interface Node cannot communicate with the PI Server; or

the monitored interface is not running, but it failed to write at shutdown a System state such as Intf Shut.

The ISU works by periodically looking at the timestamp of a Watchdog Tag. The Watchdog Tag is a tag whose value a monitored interface (such as this Interface) frequently updates. The Watchdog Tag has its excdev, excmin, and excmax point attributes set to 0. So, a non-changing timestamp for the Watchdog Tag indicates that the monitored interface is not writing data.

Please see the Interface Status Interface to the PI System for complete information on using the ISU. PI Interface Status runs only on a PI Server Node.

If you have used the ICU to configure the PI Interface Status Utility on the PI Server Node, the ICU allows you to create the appropriate ISU point. Select this Interface from the Interface drop-down list and click Interface Status in the parameter category pane. Right click on the ISU tag definition window to bring up the context menu:


Click Create to create the ISU tag.

Use the Tag Search button to select a Watchdog Tag. (Recall that the Watchdog Tag is one of the points for which this Interface collects data.)

Select a Scan frequency from the drop-down list box. This Scan frequency is the interval at which the ISU monitors the Watchdog Tag. For optimal performance, choose a Scan frequency that is less frequent than the majority of the scan rates for this Interface’s points. For example, if this Interface scans most of its points every 30 seconds, choose a Scan frequency of 60 seconds. If this Interface scans most of its points every second, choose a Scan frequency of 10 seconds.

If the Tag Status indicates that the ISU tag is Incorrect, right click to enable the context menu and select Correct.

The PI Interface Status Utility – and not this Interface – is responsible for updating the ISU tag. So, make sure that the PI Interface Status Utility is running correctly.

102

Appendix A:Error and Informational Messages

A string NameID is pre-pended to error messages written to the message log. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id flag on the startup command line.

Message LogsThe location of the message log depends upon the platform on which the interface is running. See the UniInt Interface User Manual for more information.

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 version of UniInt, the command-line parameters used, and the number of points.

As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.

If the /db is used on the command line, then various informational messages are written to the log file.

MessagesThe Event File interface logs all unit, alias, and point creation attempts for system management and auditing purposes. In addition, there are various debug level messages which may be logged using the /db=<level> switch in the interface startup file. See the section on Interface Operation for more detail on this switch.

Initialization or Startup ErrorsGenerally, these errors will stop the interface from starting up – it is normal behavior for the interface to exit since in many cases the proper startup state of the interface cannot be achieved (or determined) when these errors occur. Generally, speaking if an interface initialization error occurs, the user should check to ensure that communications between the PI server and interface node are existent (since many of the initial parameters need to be synchronized – checked or created with or on the PI server).

“Monitored Directory not found. Check use of /path=<MonDir> switch.”User should check that the account under which the interface is running has access to the directory in question. Access can be denied to due to either network access (remember that the interface will likely run under a different account as a service versus that when run interactively) or file permissions. The latter is more likely with local path specifications; the former with paths specified over a LAN or mapped drive.

“Position File Directory not found. Check use of /pospath=<POSDir> switch. Exiting.”It is recommended that the temporary position files be kept in a local drive, and therefore, the most likely culprit is that either a) the directory does not exist (the interface does not


automatically create the directory) or b) that the file permissions on it are such that the interface cannot access the directory.

“Failed to create EVT Interface S88 Hierarchy heading set”This error implies that the interface could not find or create the required PI HeadingSet. The user should ensure that the interface node has the proper permissions on the PI server to be allowed to create objects in the PI Module DB. Otherwise, the user can manually create this PI HeadingSet. The headingset name should be “EVT Interface S88 Hierarchy” and it must contain the following PI Headings in this order (1-5): “Procedure”, “Unit Procedure”, “Operation”, “Phase”, “Phase State”.

“Failed to create PI UnitBatch status digital state set”Means that the digital state set for the general PI UnitBatch status digital state set used in marking a PI UnitBatch questionable was not allowed. Check to ensure that the interface node is allowed permissions on the PI server to create this set. Or is must be created manually. The set name is “UnitBatchStatus” with the first state of “Good” and at least one other state “Questionable”.

“Fatal Error Initializing PI Module and Batch DBs [Number]: <Description>”The user should check the PI server is running and is PI 3.3 or later (to ensure the presence of the Module DB on the PI server). Ensure that the PI SDK is running on that interface node (it should be since, another error is likely to be generated before this on if the PI SDK is not present when the interface starts) and attempt to connect with another PI Module DB application on the same interface node (e.g. the PI Module Database Editor). Without access to a PI server’s Module and Batch databases, the interface cannot operate.

“Failed to create EVT Interface Status Point”The interface failed to create the required interface status point. Ensure that permissions to write to the PI Point database are allowed for the interface node. The user can create this point manually if necessary. The tagname must be “EVTIntf<IntfID>_Status” with pointtype “String”. The user must also specify the pointsource, interface ID (location1) and a scan class (location4).

“Failed to create <various interface specific> Object”The interface failed to create one of its internal objects (“Directory”, “Log”, “Global String Pool”, “Rules”, “Action” or “Unit Collection”). These errors are always fatal and will cause the interface to exit. If any of these objects fail to create, it is likely that the interface executable is corrupted and the user should attempt to repair or uninstall and reinstall the interface.

Runtime ErrorsGenerally, PI EVTIntf errors are triggered by some action that the interface takes while interacting with the PI Server. Therefore, most (if not all) PI EVTIntf Errors will contain a variable portion of the message which is returned from either the PI Server or the underlying PI SDK layers. PI server specific portions of messages will generally contain a negative five-digit number (e.g. –10401 or –15001). These numbers are often followed by a description. However, these error numbers can also be looked up using the following command line commands:

pidiag –e <error number>or:


pilogsrv –e <error number>PI SDK numbers are generally eight-digit hexadecimal numbers (e.g. 0x000403a0). Again specific descriptions for the error are generally appended to the error message, but can also be obtained by using the “Error Lookup” function in the AboutPI-SDK.exe application installed when the PI SDK is installed.

“Call getting Module DB modules list failed, Error: <#>: <description>”Module database pointer is no longer valid. Check that PI server is still running. The interface node can be purposefully disconnected from the PI server to attempt to reinitialize the Module DB pointer. Otherwise, the interface may need to be restarted to reinitialize this pointer.

“[Area | Processing Cell] Module <Name> Not Found and Module Creation Suppressed (/suc)”User has not created the correct module hierarchy for the interface to use and has suppressed PI Unit/PI Module creation. Therefore, the interface cannot create the required PI Batch objects since it cannot specify the correct linkages to the Module DB. The user will likely need to:

Stop the interface,

Correct the Module DB hierarchy,

Delete the intermediate *.pos files for the affected event files (all those that use the modified portion of the hierarchy)

Delete the PI Batches (if any in the PI Batch DB using, for example, the PI Module Database Editor).

Restart the interface.

“Error attempting to create Unit <UnitName>”Interface encountered an error while attempting to create the local unit definition. If this message appears in conjunction with another error that has a PI SDK then this message is likely to be due to that. Resolve the PI SDK error and this message should no longer appear. The nature of the PI SDK error is variable, but common potential types are connection (data or connection timeouts), permissions (on either the PI SDK or PI server sides) or illegal characters in names.

“Error Removing PI UnitBatch (<UPName>), Error: <#>: <description>”This error appears when the interface encounters a PI UnitBatch that has a 0-second duration. Since PI cannot have more than one PI UnitBatch present in a given Unit at a given time, the presence of the 0-second duration PI UnitBatch will not allow the insertion of a new PI UnitBatch at this time. The user will likely have to manually remove the PI UnitBatch to get the interface to continue. Check interface node permissions to ensure that it can write to the PI server’s Module and Batch DBs.

“Error [Adding | Closing] [PI-UnitBatch | Operation level PI-SubBatch] (<Name>), Error: <#>: <description>”Check interface node permissions to ensure that it can write to the PI server’s Module and Batch DBs. The interface encountered a situation where it was either not allowed to make a new BatchDB object or close out an old one.



“Error Prepping Operation Level PI-SubBatch (<OPName>) for Insertion, Error: <#>: <description>”The interface encountered an error while trying to retrieve a PI Heading from the “EVT Interface S88 Hierarchy” PI HeadingSet. Check to ensure that the PI server has this PI HeadingSet and its five required PI Headings.

“Error Finding PI-UnitBatch SubBatches (<UPName>), Error: <#>: <description>”

or

“Error retrieving Phases sub-PIModule for PI-Unit (<UnitName>), Error: <#>: <description>”

or

“Failed to get SubBatches List for UnitBatch <UPName> on Unit <UnitName>, Error: <#>: <description>”

or

“Phase <Name> not found, Error: <#>: <description>”or

“Phase <Name> not Found. Cannot insert phase state: <State>.”Or

“Failed to create SubBatch <Name> in UnitBatch <UPName> for Unit <UnitName> SubBatches List, Error: <#>: <description>”

or

“Error Adding Phase Level PI-SubBatch (<Name>), Error: <#>: <description>”

or

“Error getting heading set for PI-SubBatch (<Name>), Error: <#>: <description>”

or

“Error Setting Phase <Name> end time, Error: <#>: <description>”Check interface node permissions to ensure that it can read from the PI server’s Batch DB. The interface encountered a situation where it was not allowed to access a PI Batch DB object or that object was not present. The specific error number and description will contain the differentiation of these situations.

“Error Adding Phase <PhaseName> to Unit <UnitName> Phases Module: <description>”Check interface node permissions to ensure that it can write to the PI server’s Module DB. The interface encountered a situation where it was either not allowed to make a new PI Module object. Also check the current hierarchy to ensure that the PI Unit in questions still exists.

“Point Creation Failed for <tagname>”The interface failed an attempt to create a PI Point. Generally, this will be accompanied by another message with a PI SDK error. Check PI SDK connection to PI server.

106

Resolve the situation according to the circumstances specified by the PI SDK error (e.g. permissions, connection issues, etc.).

“File <filename> contains ambiguous event order. Suspending processing on BatchID <#>.”The file has encountered a situation in the event file that requires that it mark the resultant PI Batch (and possibly PI UnitBatch) questionable. See the following section in this appendix on “Questionable Batches”.

“There are already two PIUnitBatches on the PIUnit <unitname> that overlap with the unitbatch in the file <filename>. This file might be marked questionable”This is an informational message. This message is written when the /merge switch is used. When the /merge switch is used, the interface searches for existing PIUnitBatches to check for any overlaps. If only one PIUnitBatch exists, the files are merged. If there is more than one PIBatch that exists, then the interface cannot merge the three PIUnitBatches into one. Therefore it shows this message in advance.

Questionable BatchesThe “questionable” flag is the generic error state method. It exists as an error trap for support and maintainance reasons. The “questionable” flag on a batch is only activated when interface encounters an error that it cannot recover from. The conditions under which this arises are, generally, when the file does not conform to the logic that is outlined in the Principles of Operation section, and therefore, the interface cannot (or has not) created the proper set of BDB objects that current event requires for whatever actions it is to take.

At this time, a batch and unitbatch (if any are active) are marked “questionable”, the interface stops processing the file, the “Unprocessed Files” performance counter in the interface is incremented by 1, and the name of the event file that had its processing halted is posted to the Interface status tag (generally named “EVTIntf#_status”, where # is the interface id value). The PI Batch is marked questionable by the introduction of a PI Property into the PI Properties collection. A “Status” property is introduced and a subPI Property with “Questionable” as its name and the timestamp of the event as its value. The PI UnitBatch is marked questionable by having its status point put into the digital state “Questionable”.

Note, the interface automatically creates the status PIPoint, PIAlias, and “Status” subPIModule for the PI Unit, when the unit is created. If the unit creation is (or the unit was created by an early beta version of the interface), then the status PIPoint, PIAlias, and subPIModule will need to be created manually.

When the batch is marked “questionable”, the interface will not start processing the file again ever. The PI Batch is closed when the “End Of BATCH” System Message Event appears in the Event Journal. The interface will attempt to close any open PI UunitBatches and PI SubBatches that are still open in the context of the PI Batch.

The user needs to resolve the conflict in the file, or on the PI server (dependent on the error) and reprocess the file or input the data manually. Note, that to have the interface reprocess that file, the user will need to remove all traces of that PI Batch (and its PI UnitBatch collection) from the BDB. The EVT Cleaning Utility helps in removing all traces of that PIBatch. See Appendix D for more details. In addition, since the interface cannot back fill, if there have been files that have been subsequently processed by that



interface that use the same PI Units, the user will be unable to have the interface process the file. Reprocessing the file must be done manually, in this case.

The “questionable” state on a given PI Batch should not affect any other file being processed by the interface. The next file that uses that PI Unit should not see a problem. When the next UP starts up in that unit (in a different file) it should mark the status “good” for the PIUnitBatchStatus flag and then continue processing the file.

System Errors and PI ErrorsSystem errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.

Error Descriptions On Windows, descriptions of system and PI errors can be obtained with the pidiag utility:\PI\adm\pidiag –e error_number

108

Appendix B: PI SDK OptionsTo access the PI SDK settings for this Interface, select this Interface from the Interface drop-down list and click UniInt – PI SDK in the parameter category pane.

Disable PI SDKSelect Disable PI SDK to tell the Interface not to use the PI SDK. The command line equivalent for this option is –pisdk=0.

Use the Interface’s default settingThis selection has no effect on whether the Interface uses the PI SDK. However, you must not choose this option if you want to run the Interface in Disconnected Startup mode.

Enable PI SDKSelect Enable PI SDK to tell the Interface to use the PI SDK. Choose this option if the PI Server version is earlier than 3.4.370.x or the PI API is earlier than 1.6.0.2, and you want to use extended lengths for the Tag, Descriptor, ExDesc, InstrumentTag, or PointSource point attributes. The maximum lengths for these attributes are:

Attribute Enable the Interface to use the PI SDK

PI Server earlier than 3.4.370.x or PI API earlier than 1.6.0.2, without

the use of the PI SDK

Tag 1023 255

Descriptor 1023 26

ExDesc 1023 80

InstrumentTag 1023 32

PointSource 1023 1

However, if you want to run the Interface in Disconnected Startup mode, you must not choose this option.

The command line equivalent for this option is /pisdk=1.


Appendix C:BES Configuration RequirementsIntroduction

BackgroundThe PI EVTIntf interface reads event files, interprets their contents, and builds the corresponding objects in the PI Server Batch Database (BatchDB). In order for this process to work, each event file must contain specific recipe events in a predictable order.

Note: The PI EVTIntf interface is not appropriate for all types of recipes generated by a Batch Execution System. It is designed for recipes that constrain a unit to run a single unit procedure at a time.

This document is meant to be informative enough for the potential user to make the assessment that the interface is appropriate for their environment; it does not delineate the low-level technical aspects of the event file or Batch Execution System (BES) logic.

ObjectivesThe goals of this document are two-fold. Firstly, to outline the event file interface logic and PI Server Batch Database objects. Secondly, to make recommendations regarding recipe configuration and BES operations that are compatible with the PI EVTIntf interface logic.


Principles of the PI Server Batch DatabaseThe PI Batch Database has three hierarchical objects for the purposes of the PI EVTIntf interface: the PI Batch, PI UnitBatch, and PI SubBatch. All three of these objects have a start and end time property that designates the timeframe in which they are “active”.

The PI Batch is an object that is meant to correlate to a Batch (for instance a single execution of a recipe). The PI Batch has one main feature with respect to the PI EVTIntf interface: it has a collection of PI UnitBatches. The PI Batch is not tied to a specific piece of equipment.

The PI UnitBatch object has three primary properties. These are a parent PI Batch, a PI SubBatches collection, and a single unit. The PI UnitBatch rigidly enforces the S88 stricture that only one PI UnitBatch may be present in a unit at any given time.

The PI SubBatch is an object that contains only four user properties: a Name, a PIHeading (which allows it to alias a user configurable title), a parent (which may be a PI SubBatch or a PI UnitBatch) and a PI SubBatches collection. PI SubBatches are hierarchical (i.e. each PI SubBatch has its own PI SubBatches collection, of which each PI SubBatch in the collection has its own PI SubBatches collection and so on). They are also only creatable from within a PI UnitBatch (i.e. all PI SubBatch hierarchies start with a PI UnitBatch at the top level).

For more detailed information on the PI Batch Database and its objects, consult the document “PI SDK Tutorial” Chapters 3 and 4.


Principles of the PI EVTIntf Interface The PI EVTIntf interface makes the following assertions about the connections between the S88 recipe hierarchy and the PI Batch Database (BatchDB).

Each instance of a recipe loaded on to the BES batch list is a PI Batch. Generally, the highest level of a recipe possible is the Procedure.

Each Unit Procedure is a PI UnitBatch

Each Operation is a PI SubBatch with a PI UnitBatch as parent

Each Phase is a PI SubBatch with a PI SubBatch as a parent

The PI EVTIntf interface populates the BatchDB objects based on certain events in the event journals.

PI BatchFor example, the PI Batch start and end times are populated by the System Message events “Beginning Of BATCH” and “End Of BATCH”, respectively.

PI UnitBatchThe PI UnitBatch start and end times are based on a combination of events. Since the PI UnitBatch is tied to a piece of equipment, a unit procedure must start in the recipe and the equipment specified must be acquired. When both of these criteria are fulfilled (i.e. the latter of the two events being found) the PI UnitBatch is created and its start time property populated. When either of these criteria ceases to be true (i.e. either the unit procedure ends or the equipment is released), the PI UnitBatch is ended.

PI SubBatch: Operation LevelPI SubBatches that correspond to an operation in the recipe must also fulfill two criteria with logic similar to that for PI UnitBatches. That is, the equipment must be acquired and the operation must become active in the recipe for the appropriate PI SubBatch to be started. When either criterion ceases to be true, the PI SubBatch is ended. In the case of an Operation level recipe, a PI UnitBatch is created as a placeholder for the Operation level PI SubBatch.

PI SubBatch: Phase LevelFor a PI SubBatch corresponding to a phase, the start time and end times are populated by the phase state. Since phases are not necessarily under the auspice of the BES directly (they are calls into the phase logic on either the DCS or through another mechanism), the only thing that is specified is the state. The first receipt of an “active” BES phase (a superset of the allowable S88 states) state (e.g. RUNNING, DOWNLOADING, UPLOADING, STARTING, RESTARTING) will start the PI SubBatch and the receipt of a “terminal” state (e.g. COMPLETE, STOPPED, ABORTED) will end it.

While some BESes allow for the linking of recipes into a campaign, the PI EVTIntf Interface does not currently link or group PI Batches in any way. PI Batches with the same BatchID are allowed and do not conflict with the normal operation of the PI EVTIntf interface or PI BatchDB.

For a more detailed account of the logic that the PI EVTIntf Interface uses, refer to the Principles of Operation section in the PI EVTIntf Interface manual.


Recommendations for BES Recipes and Equipment ModelsThe following page shows three figures depicting various types of recipes that can be configured and run on a BES. Figure 1 is a sequential flow control (SFC) diagram that shows a simple procedure that consists of one unit procedure that houses two parallel operations. Each operation consists of two sequential phases. This type of recipe can be processed by the PI EVTIntf interface. Since the interface will attempt to create two parallel PI SubBatches, which is allowed, the running of this recipe can be represented in PI without any issues. Recipes that contain concurrent unit procedures in different units are also allowed.Figure 1: This recipe configuration is allowed as long as the unit that UP_A runs on is not configured

to allow more than one simultaneous owner (see Figure 2).

Figures 2 and 3 are SFC diagrams that depict the two types of recipes that can be created on some BESes and that cannot be processed by the interface and, therefore, are not supported. These two types of recipes are:

If the maximum number of owners allowed for a unit is greater than one (Figure 2)

If multiple parallel unit procedures are configured and any one of those unit procedures requires that the arbitration of the unit occurs before the unit procedure starts (Figure 3)

These two types of recipes would result in the creation of PI UnitBatches that violate the S88 requirement of only one Unit Procedure active in a given unit at a given time. If the equipment (units) or recipes are configured in either of the above two situations, then the PI EVTIntf interface is not appropriate for that system.

Figure 2: An SFC diagram portraying two parallel procedure level recipes, each containing a single unit procedure.


UP_A

Procedure

PHS_B

PHS_A

Operation(OP_B)

OP_A OP_B

Unit Procedure(UP_A)

Appendix C:BES Configuration Requirements

This recipe configuration is not allowed under the following conditions: a) UP_A and UP_B use the same unit; and b) unit is allowed to have multiple owners; and c) Recipes 1 and 2 are run concurrently. Note, this equipment configuration is not possible on all BESes.

Figure 3: This figure depicts an SFC diagram consisting of a procedure level recipe that has parallel unit procedures.

This recipe configuration is not allowed under the following circumstances: a) UP_A and UP_B use the same unit; and b) UP_A and/or UP_B are configured to acquire the unit before the start of the unit

114

UP_A UP_B

Procedure

PHS_B

PHS_A

Operation(OP_A)

OP_A

Unit Procedure(UP_B)

UP_B

Recipe 2(Proc_2)

UP_A

Recipe 1(Proc_1)

procedure. Note, this recipe configuration may not be possible on all BESes.

Note that not all BESes can be configured to make these types of recipes or equipment configurations. For example, it is known that the DeltaV Batch Executive allows for the configuration of multiple owners for a unit, while this is not possible on any version of Sequencia’s OpenBatch or on Rockwell’s RSBatch version 5.0 or lower.

There is no workaround for equipment or units that are configured to allow more than one concurrent owner (Figure 2). This situation can lead to multiple batches/recipes simultaneously acquiring a given piece of equipment and using it, since the interface is unaware of the interaction between recipes (i.e event files). Ultimately, this is equivalent to having multiple PI UnitBatches simultaneously active in a given unit, which cannot be represented in the PI BatchDB.

Often, it is possible to adapt recipes with concurrent unit procedures on the same unit (Figure 3) to contain concurrent operations instead (similar to what is depicted in Figure 1). Recipes with concurrent operations (or phases) can be processed by the PI EVTIntf interface accurately. In the case of multiple concurrent owners for a unit, the only solution is to modify the equipment model to restrict the number of owners of a unit to one. This is the recommended method for resolving the issue of multiple unit owners. Recipe modifications may also be required in addition to the equipment model modifications.


Appendix D:Event File Directory Sync UtilityIntroduction

The Event File interface to the PI system operates by reading in data from event journal files generated by a batch execution system and sending the data to PI. Once the interface has finished processing a file, it renames the original file with a new extension. However, there are some circumstances where it may be undesirable to rename event journal files. For example, there may be other programs on the system which require that the file names remain unchanged.

The Event File Directory Sync utility has been designed for use in these scenarios. The utility continually monitors a source directory for new files. If any new files are detected, the utility copies the files to a destination directory. The Event File interface is then able to process and rename files in the destination directory without modifying the original files in the source directory.

Principles of OperationThe utility takes a source path and a destination path as parameters, along with an optional scan rate parameter. On each scan, the utility scans for all files with the extension .evt in the source path and compares that list with all files with the extensions .999 and .que in the destination path. Any .evt files which do not have a corresponding .999 or .que file are copied from the source path to the destination path. If a matching .evt file is found in the destination path, the source file is copied over only if the file sizes differ.

For a file to be copied successfully, the full path to either the source filename or destination filename cannot exceed 259 characters. In addition, neither the source path nor the destination path can exceed 252 characters.

CAUTION

It is critical that the processed .999 and .que files are not deleted until after the corresponding .evt files are deleted. If a .999 file is deleted before its associated .evt file, the .evt file will be copied into the destination directory again, and the EVT File Interface will send duplicate batch information to PI.

Utility Installation Procedure1. Copy the interface files from the installation media to a directory on the interface

node, for example, C:\PIPC\Interfaces\EVTIntf\. Create the directory if necessary.

2. Create a .bat command file with the same root name of the executable.

3. Alter the command-line parameters in the .bat file as discussed in this manual.


4. Try to start the utility interactively with the command file. For example:EVTSync.bat

If the utility cannot be started interactively, it will not be able to start as a service. It is easier to debug interactively started processes because error messages are echoed directly to the screen. Once the utility is successfully running interactively, try to run it as a service by following the instructions below. To stop the utility once it has been started interactively, hit CTRL-C.

Multiple copies of the utility can run on the same system. In order to run multiple copies as services, each copy of the executable must have a unique name, with a matching .bat file in the same directory.

Installing the Utility as an NT ServiceChange to the directory where the EVTSync.exe executable is located. Then run the utility with the –install switch:

EVTSync.exe –install

Check the Microsoft Windows services control panel to verify that the service was added successfully. Use the services control panel to change the utility from a manual service to an automatic service or vice versa.

Startup Command FileCommand-line parameters can begin with a / or with a -. For example, the /dest=C:\data and –dest=C:\data command-line parameters are equivalent.

Command file names have a .bat extension. The continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte).

Command-line ParametersParameter Description/dest=<path> Full path to destination directory./rate=# Optional rate in seconds to scan source and destination directory.

Default scan rate is 30 seconds. This parameter must be an integer value.

/src=<path> Full path to source directory.


Sample EVTSync.bat FileThe following is an example file:REM======================================================================== REMREM EVTSync.batREMREM Sample startup file for the Event File Directory Sync UtilityREMREM========================================================================REM REM Sample command lineREM

EVTSync.exe ^/src=\\hostname\journals ^/dest=\\BatchServer\Journals

REMREM end of EVTSync.bat

Starting / Stopping the Utility

Starting the Utility ServiceIf the interface was installed a service, it can be started from the services control panel or with the command:net start EVTSyncA message will be echoed to the screen informing the user whether or not the utility has been successfully started as a service. Even if the message indicates that the service started successfully, make sure that the service is still running by checking in the services control panel. There are several reasons that a service may immediately terminate after startup. One is that the service may not be able to find the command-line parameters in the associated .bat file. For this to succeed, the root name of the .bat file and the .exe file must be the same, and the .bat file and the .exe file must be in the same directory. If the service terminates prematurely for whatever reason, no error messages will be echoed to the screen. The user must consult the pipc.log file for error messages.

Stopping the Utility ServiceIf the interface was installed a service, it can be stopped at any time from the services control panel or with the command:net stop EVTSyncThe service can be removed with:

evtsync.exe –remove

ConclusionsThe Event File interface processes event files from a BES to create and populate PI BatchDB objects. The interface is not appropriate for all recipe types. In particular, recipes that contain concurrent unit procedures or that run in units that allow more than one simultaneous owner may not be accurately processed by the interface. However, recipes that contain concurrent operations or phases can be accurately processed by the


Appendix D:Event File Directory Sync Utility

interface. Recipes that contain concurrent unit procedures in different units are also allowed.

120

Appendix E:EVT Cleaning UtilityIntroduction

The Event File Cleaning Utility (EVTCleaningUtility.exe) is designed to analyze, remove and/or update data in a PI Server based on any given event file. It is a standalone utility and is intended to be used as a standard command line application.

This utility can

1. be used to compare the data in PI with any event file processed by the interface and report any missing information

2. be used to update any string tags or recipe tags that have missing events.

3. be used to remove PI Batch objects, events from string tags and recipe tags, and PI Properties from PIBatch corresponding to any given event file.

4. It will remove duplicate events in the tags and duplicate batch data as well. The removal capability is useful before reprocessing a file that is marked questionable.

Principles of OperationOn startup, the Event File Cleaning Utility locates the monitored directory specified by command line parameter /path. The utility reads the first file with extension .del in the monitored directory. The utility then identifies the corresponding data (PIBatch, PIUnitBatches, PISubBatches, string and recipe events and PIProperties) recorded on the PI Server. It is important to specify the same /ps and /id values for this utility as they were specified for the event file interface that processed these event files. If the command line parameter /mode=stat is specified, the utility checks for the existence of the data in PI and reports existing and missing information in PI. In this mode the extension for the processed files will remain unchanged and the data in PI is not modified. If the command line parameter /mode=delete is specified, the utility will remove all the identified data from the PI Server. If there are multiple instances of the same data, those instances will also be deleted. This mode is useful in cleaning data in PI that results from a partially processed questionable event file. If the command line parameter /mode=update is specified, the utility will perform analysis of data integrity for the recipe and string tags and updates any missing events in those tags. The utility will not add any batch objects, tags or modules. If the file is successfully processed, the extension is changed to .cln. The utility will continue processing all files with .del extension in the monitored directory. After the last file is processed, the utility will exit. The utility will create logs in the “LOG” directory under the /path, which is created automatically if it does not exist. The “0_CLEANING.log” file contains a summary of all files processed and one log file is created for each event file processed. The individual log files have the same name as the event file processed but with .log extension. If the utility is run multiple times, any existing “0_CLEANING.log” file is renamed and a new “0_CLEANING.log” file is created. However, the individual log files are overwritten. The /print switch dictates the amount of information written to the log files.


WARNING: Each subsequent execution of EVT Cleaning Utility on the same files will result in complete rewrite of individual file logs with most current results.

Analyzing Data Contents in PIIn order to perform data analysis on the PI Archive, the command line parameter for mode must be set to /mode=stat. The utility will perform full analysis of the PI Archive data based on the data from monitored EVT files. In this mode the utility will analyze data on different levels of the PI Batch Database, such as Batches, UnitBatches, Operations and Phases. It will also analyze the events for recipe and string tags by comparing the PI Archive data to the EVT file data. On completion it will provide a report of existing and missing data. Each processed file will have its own log with results. The processed file extension will not be changed.

Deleting Data from PITo start the Event File Cleaning Utility in cleaning mode, the command line parameter for mode must be set to /mode=delete. In this mode the utility will find existing data in PI as expected from reading the event file. It will then remove from the PI Server all the data that corresponds to the event file. The cleaning process includes removal of Batches, UnitBatches, Operations, Recipe Tag Events, String Tag Events and PIProperties events, as well as their duplicates, resulted by improper event file processing by the interface. This utility DOES NOT delete any PIPoints. It DOES NOT alter the PI Module Database. The events are deleted only if the time stamps and the values are an exact match to the information in the event file. The Batch, UnitBatch, and Operation objects are deleted from the PI Archive only if the start time, end time, and properties are same as the information in the event file. The extension of a successfully processed file will be changed to “.cln”

WARNING: In the delete mode “/mode=delete” there is NO user confirmation message prior to removing the data. The user interaction to specify the delete mode and to name the files as .del is considered as enough intent to delete the data.

Updating Data in PIIn order to perform data update on the PI Archive, the command line parameter for mode must be set to /mode=update. The utility will perform update of the existing recipe and string tags with missing events ONLY. No tags will be added, the PI Batch and PI Module Databases will remain unchanged. The extension of successfully processed file will be changed to “.cln”

Foreign Language SupportThe EVT Cleaning Utility supports languages other than English through the use of a language translation file. A sample language translation file for an Italian version event files is included with the interface distribution. The complete path to this file is specified by the /langpath parameter. If the switch is not used, then the default language of English is assumed.


Utility Installation Procedure1. Copy the interface files from the installation media to a directory on the interface

node, for example, C:\PIPC\Interfaces\EVTIntf\. Create the directory if necessary.

2. Create a .bat command file with the same root name as the executable.

3. Alter the command-line parameters in the .bat file as discussed in this manual.

4. Start the utility interactively with the command file. For example:EVTCleaningUtility.bat

The utility runs only interactively. Multiple copies of the utility can run on the same system. In order to run multiple copies, each copy of the executable must have a unique name, with a matching .bat file in the same directory.

Starting the EVT Cleaning Utility ApplicationCopy the desired event files to be processed by this utility into a folder other than the folder monitored by the event file interface. The path to this folder must be specified as the /path switch in the command line parameters. Change the extension of the files to “.del”. The Event File Cleaning Utility will not process files with any other extensions. After the files are processed and if there are no errors, the extensions of the files will be changed to “.cln”. In case of errors, the extension will not be changed and the utility can be used to process these files again without affecting the data on the PI Server. The Utility will process multiple .del files in the same run. The Event File Cleaning Utility can be started from a command line prompt by typing the name of the .bat file.

Stopping the EVT Cleaning Utility ApplicationThe utility will stop automatically after processing the last .del file.

Startup Command FileCommand-line parameters must begin with a / For example, the /mode=update. Command file names have a “.bat” extension. The continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). In order to pass monitoring directory, which contains spaces, use double quotes around the full path. For example

/path=”c:\Program Files\Test EVT”

Required Command-line Parameters


/bestype=”bestype”Required

The /bestype flag specifies the BES application that is generating the event files. Because each of the specific vendor implementations can have subtle differences, this argument may be required. The valid arguments are: OpenBatch (Sequencia) TotalPlantBatch (Honeywell) iBatch (Intellution) RSBatch (Rockwell)


Appendix E:EVT Cleaning Utility

Parameter Description DeltaV (Emerson)The vendor name should not be included in the argument (i.e. only “DeltaV” or “iBatch” is used).

/host=host:portRequired

The /host flag is used to specify the PI Home node. Host is the IP address of the PI Sever node or the domain name of the PI Server node. Port is the port number for TCP/IP communication. The port is always 5450 for a PI 3 Server. It is recommended to explicitly define the host and port on the command line with the /host flag. If only the domain name is supplied as a parameter, the port can be neglected.Examples:/host=marvin /host=marvin:5450 /host=206.79.198.30/host=206.79.198.30:5450

/id=xRequired

The /id flag must be same as the interface id specified for the instance of the event file interface that is used to process the event file. If the correct id is not used, then the utility will fail to find the PI tags.

/mode=<mode type>Required

The /mode flag specifies the cleaning utility mode of operation.Delete = delete data from PIUpdate = update data in PIStat = analyze data in PI

/path=<path to del files>Required

The /path flag provides the cleaning utility with the path to the folder where the .del are located.

/ps=xRequired

The /ps flag must be same as the pointsource specified for the event file interface that is used to process the event file. If the correct pointsource is not used, then the utility will fail to find the PI tags.

Optional Command-line Parameters


?help

man

These flags are used to display usage screen.

124


/aeuOptional

The /aeu switch specifies that Arbitration Events are Unavailable in the event journal files. When this switch is used, the logic by which the utility resolves the start and end times for various PIBatch objects is altered. This switch should only be used with Batch Execution Systems which are based on Sequencia’s OpenBatch system 4.0.0.75 and earlier.

/aliasesOptional

The /aliases switch allows the Utility to analyse or update the PI Aliases at module and phase levels. This switch is useful only when running the utility in Stat or Update modes.

/aspe=[10,33]Optional

The /aspe=[10,33] switch allows the Utility to analyse Additional String Pool Events in Formula Header (10) stringpool tag (with more values for Formula Name) and also in BatchID stringpool tag (33), if any of them exist.. This switch is valid only when /merge switch is used. This switch is useful only when running the utility in Stat or Update modes. In Delete mode, the utility will automatically compare these events.

/besname=”BESName”Optional

The /besname flag specifies the string that the application will prefix to each Area, Processing Cell, and Unit PI Module that the interface creates. Since the name of the PI Unit created using this option is different than one that is created not using this option, points for that unit are distinguishable. The besname is separated from the rest of the name by a colon (‘:’). The default is to not include a prefix for any string for Area, Processing Cell or Unit names.

/bidchar=nOptional

The first n characters are stripped from the value in BatchID column and used as the BatchID for the PIBatch. If n is larger than the BatchID column value, then the complete string is used as the BatchID for the PIBatch. This switch is effective only if /merge is used.

/biddOptional, must be used only if /bidf is used

The /bidd (BatchID Dynamic format) switch is used used in conjunction with /bidf=n[:c:p:a]. When/bidd is used, a BatchID with the minimum number (n) of digits is searched. If there is no match then the interface searches for n+1 contiguous digits and so on until a match is found or the length of the BatchID string is reached. If there is no match, then the complete string in the BatchID column of the event file is used as the BatchID for the PIBatch. If more than one match is found then the first substring is used. If there are characters embedded within the substring, then in the dynamic format it is necessary to specify whether the digit count should be increased before or after the characters. The anchor value a serves this purpose. Example for /bidd in conjunction with /bidf to extract a substring from the BatchID column in the event file:Let’s say that the BatchID column in the event file is lot30112 / 90dev124 / 12345stp / ld567 / 201num54.




If /bidf=3:0:0:0 means that there are 3 contiguous digits and no characters in the substring. Since there are multiple matches, the first substring is used and the result will be 124. If /bidf=4:0:0:0 means that there are 4 contiguous digits and no characters in the substring. There is no match for 4 contiguous digits. Hence the search continues for a 5 contiguous digits. Since there are two matches, the first substring is used and the result will be 30112. Note that without the /bidd switch, the BatchID would be the entire string.If /bidf=5:0:0:0 means that there are 5 contiguous digits and no characters in the substring. Since there are two matches, the first substring is used and the result will be 30112. If /bidf=6:0:0:0 means that there are 6 contiguous digits and no characters in the substring. There is no match for 6 contiguous digits. Hence the search continues for a 7 contiguous digits. There is no match for 7 contiguous digits. Hence the search continues for 8 contiguous digits and so on but there is never a match for more than 5 contiguous digits. Therefore the complete string lot30112 / 90dev124 / 12345stp / ld567 / 201num54 is used as the BatchID. If /bidf=5:3:1:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the first digit. The resulting BatchID will be lot30112. If /bidf=5:3:6:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the sixth digit (in this case it means at the end of the 5 digit number). Hence the resulting BatchID will be 12345stp. If /bidf=4:3:3:0 means that there are 4 contiguous digits with 3 contiguous characters and the characters are placed before the third digit. There is no match for the given criteria. So, the number of contiguous digits for the substring is increased to 5. Since the number of digits is increased, the position of the characters becomes ambiguous because the increased digit can be either before or after the three characters. This means the two possibilities are 90dev124 and 201num54. The last value in the switch specifies where the increased digit should be added. A value of zero (as in this case) means the number of digits to the left of the characters is fixed and hence the result will be 90dev124. If /bidf=4:3:3:1 is used, the result would be 201num54.If /bidf=4:3:3:1 means that there are 4 contiguous digits with 3 contiguous characters and the characters are placed before the third digit. There is no match for the given criteria. So, the number of contiguous digits for the substring is increased to 5. Since the number of digits is increased, the position of the characters becomes

126


ambiguous because the increased digit can be either before or after the three characters. This means the two possibilities are 90dev124 and 201num54. The last value in the switch specifies where the increased digit should be added. A value of one (as in this case) means the number of digits to the right of the characters is fixed and hence the result will be 201num54. If /bidf=4:3:3:0 is used, the result would be 90dev124.

/bidf=n[:c:p:a]Optional

The /bidf (BatchID Fixed format) switch is used to obtain a new BatchID, which is a substring of the value in the BatchID column in the event file. The /bidf takes four values in the format /bidf=n:c:p:a where n represents a fixed number (greater than zero) of contiguous digits in the desired BatchID, c represents the number of contiguous characters embedded in the substring to be extracted, p represents the starting position of the characters with respect to the contiguous digits and a represents the anchor point for the varying digit count. N must have a value greater than zero specified if /bidf=n:c:p:a is used but c, p and a take default value of zero. A substring from the BatchID column in the event file is determined based on these criteria. If there is no match, then the complete string in the BatchID column of the event file is used as the BatchID for the PIBatch. If there are multiple matches, the first substring is used as the BatchID for the PIBatch. If the number of contiguous digits could vary, then the /bidd switch must also be used in conjunction with /bidf. Example for /bidf to extract a substring from the BatchID column in the event file:Let’s say that the BatchID column in the event file is lot30112 / 90dev123 / 12345stp / ld567. If /bidf=5:0:0:0 means that there are 5 contiguous digits and no characters in the substring. Since there are two matches, the first substring is used and the result will be 30112. If /bidf=6:0:0:0 means that there are 6 contiguous digits and no characters in the substring and there is no match for this and the complete string lot30112 / 90dev123 / 12345stp is used as the BatchID. If /bidf=3:0:0:0 means that there are 3 contiguous digits and no characters in the substring. Since there are two matches, the first substring is used and the result will be 123. If /bidf=5:3:1:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the first digit. Hence the resulting BatchID will be lot30112. If /bidf=5:3:3:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the third digit. Hence the resulting BatchID will be 90dev123.




If /bidf=5:3:6:0 means that there are 5 contiguous digits with 3 contiguous characters and the characters are placed before the sixth digit (in this case it means at the end of the 5 digit number). Hence the resulting BatchID will be 12345stp.

/bidm=<mask list>Optional

The /bidm switch (Batch ID Mask) is used to obtain a new BatchID, which is a substring of the value in the BatchID column in the event file. The /bidm takes a list of masks as the input value. Each BatchID mask can consist of an array of valid symbols and wildcards. The following wildcards are supported the interface:# - single digit numerical value (0-9)@ - single alpha character (a-z, A-Z)? – any single valid symbol! – repeat previous BatchID mask symbol


Example:Let’s say that the BatchID column in the event file is lot30112 / 90dev123 / 12345stp / ld567. The /bidm=”#####” will result in new BatchID 30112.The /bidm=”##@!” will result in new BatchID 90dev.The /bidm=”*##@!” will result in new BatchID lot30112 / 90dev.The /bidm=”@@@@, #8dev4, #!” will result in new BatchID 30112. Since the first and second masks could not be found, third mask is used instead.Note: This switch replaces /bidf, /bidd and /bidchar.

/cernOptional

The /cern switch (Combine Equipment and Recipe Names) is used when the user wishes to have the utility look for Sub-PI SubBatches as a combination of the name of a phase in the recipe structure (name of instance of the class of a phase) and the class name of the phase (which appears in the “Phase” column of the *.evt file. The default value is not to combine names, only the user specified instance name (in the “Recipe” column) is used.

/fnapcOptional

The /fnapc switch (Formula Name As Product Code) allows to use “Formula Name” instead of “Product Code” Pvalue as PI Batch product name. If “Formula Name” Pvalue field is blank, original “Product Code” Pvalue field is used to retrieve product name.

/langpath[=<foreign language translation path and file>] Optional

The /langpath flag specifies the directory and file where the utility should look to find the language translations for the logic triggering events. If this switch is not used, then the utility assumes a default language of English is to be used. If that file is not found, and the switch is specified, then an error is generated and the interface will not start.

128


/logtotag=#[,#,…]Optional

The /logtotag=#[,#,…] switch specifies which events messages will be logged to a string tag. This switch can be used to speed up the cleaning utility. By default the utility creates all possible stringpool tags while reading the EVT file. This switch can reduce memory usage and increase processing of stringpool tags.

/ktinid=####Optional

The Keep Trailing Instance Id switch specifies at which levels of batch hierarchy the interface should keep the trailing instance id. The passed value must be a four digit binary number. Digits represent batch levels and should be specified in the following order: Procedure, Unit Procedure, Operation, and Phase. In order to keep the instance trailing id, the specific digit should be set to 1, otherwise to 0. Exampe:The Recipe column contains the following value:P_TEST\\UP_TEST\\OP_TEST:1-1\\PH001:1-1Without the switch, the interface will read the Procedure as P_TEST, Unit Procedure name as UP_TEST, Operation name as OP_TEST:1,Phase name as PH001:1,With the switch /ktinid=0001, the interface will keep the trailing instance id for Phase name as PH001:1-1

/mergeOptional

The /merge switch allows the utility to process merged batches and unitbatches created by multiple event files with the same BatchID into one PIBatch. The /pmt switch must be specified along with the /merge switch.

/mmmOptional

The /mmm switch specifies that the utility will attempt to compare and merge the current unit batch with the previous one. This merge will only occur when (in addition to this switch being present) the unit, unit procedure name, and batch id match between the old and new unit procedures (this is most common with Manual Mode intervention, where the BES often has to reallocate resources after the being placed back into Auto mode). This switch is recommend if it is used by the event file interface .




/mupOr/mup=<separator>Optional

The Merge Unit Procedures (/mup) switch is used to merge parallel PIUnitBatches into one PIUnitBatch on any PIUnit. The parallel PIUnitBatches should be in the same Event File. The merging will be based on number of occurrences of System Message events for each unit in the same Event file. Since there could be Operations with same name in the merged PIUnitBatches, the Operation names are modified with the following syntax:<new operation name> = <unit procedure name> <separator> <original operation name>The <separator> is the value specified through this switch. If no value is specified, then a double space will be used as the separator.Example 1: no separator specified (/mup) <new operation name> = “UP_TEST:1 OP_TEST:1:1”Example 2: A separator is specified. (/mup=”__”) <new operation name> = “UP_TEST:1___OP_TEST:1:1”In case of Operation Level recipes, the Operations are also merged along with the PIUnitBatches. For more details on how this switch works, read the section titled “Merging Parallel PIUnitBatches into a Single PIUnitBatch in the Same Event File“.Note: Only one switch out of three (/mmm, /merge, /mup) is allowed to be used as command line parameter. The interface will not start up if any two of these switches are specified in the command line parameters.

/nocolorOptional

The /nocolor switch disables color coded print out on the screen.

/nocacheOptional

The /nocache switch disables Recipe Tag attributes caching. It results in much slower performance but less memory usage.

/ns=[lang]Optional

The /ns (Numeric Settings) switch allows the interface to perform proper numerical conversions based on the “Regional and Language Options” setting on local system or based on user defined language. This switch is particularly useful when the numerical conventions differ (example a comma is used instead of a decimal etc) from the default settings.If the switch is not used, then the default settings of “English_UnitedStates” is used.If the switch is used without any language specification, i.e. /ns, then the interface will use “Regional and Language Options” settings specified on the Windows machine where the interface is running. If the language specification is passed as a value (/ns=lang), then the interface will use that value as internal regional/language

130


setting to perform numerical conversions regardless of local system “Regional and Language Options” setting. If the switch contains invalid language, .i.e /ns=<invalid language>, then the interface will exit.The language can be passed by type as it is specified below or by its abbreviation.Language types (abbreviations): 131talian 131talian-simplified (chs) 131talian-traditional (cht)131tali (csy) 131talia (dan) 131talian, dutch-belgian (nlb) dutch (nld) 131talian131se, 131talian-aus (ena) 131talian131, 131talian-can (enc) 131talian 131talian-nz (enz) 131talian-uk (uk) 131talian131, 131talian131-english, 131talian-american, 131talian-us, 131talian-usa, (enu) (us) (usa) finnish (fin) 131talia-belgian (frb) 131talia-canadian (frc) 131talia (fra) 131talia-swiss (frs) german-swiss, swiss (des) german (deu) gegerman-austrian (dea) greek (ell)131talian131s (hun) 131talian131s (isl) 131talian (ita) 131talian-swiss (its) 131talian131 (jpn) 131talia (kor) 131talian131s-bokmal (nor)131talian131s131talian131s-nynorsk (non) polish (plk) 131talian131se-brazilian (ptb) 131talian131se (ptg) 131talian (rus) 131talia (sky) 131talian (esp) 131talian-mexican (esm) 131talian-modern (esn) 131talian (sve) 131talian (trk)Examples:/ns - will set the interface to use the local Windows language/regional settings/ns=131talian




/ns=itaBoth switches will set the interface to use Italian language/regional settings.

/pdlOptional

The /pdl switch allows the utility to not work with a Procedure or Unit Procedure level files that have Arbitration messages and phases but do not contain “Unit Procedure Started” messages.

/pmt=xRequired with /merge switch

The /pmt PIBatch Merge Time switch specifies the merge time in days. When a new event file is processed, the utility searches the PI Batch Database for existing PIBatches that match the BatchID of the new event file. The /pmt limits the time range in which the interface will perform this search. The search is limited to x days before the start of the new event file and x days after the start of the new event file for Batches with identical BatchIDs to be merged. Typically x represents the maximum total duration of all the event files that might be merged. Example:If there are 3 batches and each batch is 1 day long and if the idle period between each batch is also 1 day then /pmt=5 will merge all three event files into one PIBatch.

/print=[1,2,3]Optional

The /print flag specifies the level of print out on the screen and to the file. Values: 1 = Basic printing on the screen and to the log files. Display process bars on time consuming operations.2 = Detailed printout on the screen and in the file, excluding printing of archived events.3 = Full details printed on the screen and to the log files.Default: /print=1

/pswd=<password>Required with /user flag

The /pswd flag specifies Password for the user which has to be used on connection to PI ServerDefault: <blank>

132


/recipetags=#[,#,…]Optional

The /recipetags=#[,#,…] switch specifies which events messages will be logged to a recipe tag (also defined as specific tag). The syntax for the switch is similar to that for the /logtotag=[#,#,…] switch. However, the user must specify at least one event type; there is no default event that is logged to a recipe tag.Note: By specifying this switch in command line, the default behavior of creating 5 different event types is disabled.Available event types:14 – Owner Change15 – Param Download Verified

29 – Prompt25 – RecipeValue27 – ReportFor example, /recipetags=14,25would specify that the interface would create tags only for the Owner Change and Recipe Value events found in the event journal.

/rsmOptional

The Reset System Message (/rsm) switch resets the System Message flag for a unit when the Recipe Arbitration event “Resource Released by recipe” occurs. It means that if the Recipe Arbitration event was used to close the active PIUnitBatch, the interface would require both event types to be present in order to start a new PIUnitBatch. The /rsm switch can be used in conjunction with the /mup switch. In this case, the /rsm switch will also reset the system message counter to zero on active unit.




/skipphases=<phase list>Optional

The /skipphases switch specifies the list of phases for which all events in the event file should be ignored. This interface will check for the value in the “PHASE” column and the “Recipe” column in the Event File and if one of those two values equals one of the phases in this list, the interface will skip processing that row. The interface solely depends on the phase name without instance numbers. The name comparison is not case sensitive. Multiple phase names can be specified with a comma separator. If there is a space in the phase name list, use double quotes for the entire switch. This switch is available only with version 3.8.4.8 and greater.Note: with interface version 3.8.5.1, phase masks are allowed as valid phase specifiers. The following wildcards are supported in masks by the interface:# - single digit numerical value (0-9)@ - single alpha character (a-z, A-Z)? – any single valid symbol! – repeat previous BatchID mask symbol


Example: /skipphases=phase_1,ph*2 or /skipunits=”phase_1, ph*2”The following phases: PH_TEST:1-1, PH_ABORT:2-2 should be ignored by the interface. The switch will have the following form: /skipphases=”PH_TEST, PH*ORT“

/skipunits=<unitlist>Optional

The /skipunits switch specifies the list of units for which all events in the event file should be ignored. This interface will check for the value in the “UNIT” column and the “PVAL” column in the Event File and if one of those two values equals one of the units in this list, the interface will skip processing that row. The interface solely depends on the unit name (and not on the Area or ProcCell values in the Event File) and the name comparison is not case sensitive. Multiple unit names can be specified with a comma separator. If there is a space in the unit name, use double quotes for the entire switch. This switch is available only with version 3.7.0.15 and greater.Note: with interface version 3.8.5.1, unit masks are allowed as valid unit specifiers. The following wildcards are supported in masks by the interface:# - single digit numerical value (0-9)@ - single alpha character (a-z, A-Z)? – any single valid symbol! – repeat previous BatchID mask symbol


Example: /skipunits=unit_1,u*2 or /skipunits=”unit_1, u*2”

134


/smp=”PI Module Path”Optional

The /smp switch designates an alternate PI Module path to start looking for a particular Area->ProcessingCell->Unit hierarchy. If this option is not specified (i.e. the default) it is to begin at the root level of the PI ModuleDB. A path must be specified. This path is of the syntax: \\<RootModule>\<SubModule>\<…>e.g. \\MyEnterprise\MyPlant\The PI server is not specified in this syntax, since that is already known from the /host switch.

/tf=<time format>Optional

This switch is used to specify an EVT file event timestamp format. The following characters are allowed in time format switch value:yy, yyyy - Year, 2 or 4 digitsM, MM - Month, short/long number MMM, MMMM - Month, short/long named, dd - Day, short/long numberh, hh - Hour, short/long numberm, mm - Minute, short/long numbers, ss - Seconds, short/long number0 – 000000 - Fraction of second, show trailing zeros# - ###### - Fraction of second, no trailing zeros

Example: /tf=”YYYY/MM/dd hh:mm:ss.000”

/unittags=#[,#,…]Optional

The /unittags=#[,#,…] switch specifies the PIUnitBatch properties which will be logged into PIPoints. The switch can have one or more values separated by a comma. The following set of tags is available for each unit:

5) BatchID tag (Loc2=34, point type=string). The events written into the tag are <BatchID name> at the beginning of the PIUnitBatch and “Inactive” at the end of the PIUnitBatch

6) Product tag (Loc2=35, point type=string). The events written into the tag are < Product name > at the beginning of the PIUnitBatch and “Inactive” at the end of the PIUnitBatch

7) Procedure Name tag (Loc2=36, point type=string). The events written into the tag are <Procedure Name name> at the beginning of the PIUnitBatch and “Inactive” at the end of the PIUnitBatch

8) Unit Status tag (Loc2=37, point type=integer). The events written




to the tag are 1 at the beginning of the PIUnitBatch and 0 at the end of the PIUnitBatch

Example, /unittags=34,37will log the BatchID and the unit activity values

/user=<user name>Optional

The /user flag specifies the User Name which the Utility has to use in order to obtain access to PI Server.Default: /user=piadmin

Sample EVTCleaningUtility.bat FileThe following is an example file:REM=========================================================================REMREM EVTCleaningUtility.bat REMREM Sample startup file for the EVT Cleaning UtilityREMREM=========================================================================REM REM Sample command lineREM

EVTCleaningUtility.exe ^/print=3 ^/mode=stat ^/aliases ^/PATH=\\BatchServer\Journals\ ^/HOST=XXXXXX:5450 ^/PS=EV ^/ID=1 ^/bestype=DeltaV ^/exc ^/logtotag=32 ^/f=00:00:30

REMREM end of EVTCleaningUtility.bat

136

Revision History

Date Author Comments

14-Aug-03 DCO Updated documentation for 3.1.0.42 release.

08-Apr-04 DCO Added reference to DeltaV Batch in introduction.

27-May-04 SGODASI Changed the version number. Added information about string type tags for specific events. Added Appendix C.

08-Jun-04 CG Version 3.2.0.1 Rev B: Removed extra spacing; fixed copyright; added note about not using buffering; removed version # on section header of sync utility

22-Jul-04 SGODASI Version 3.3.0.2 Rev A: Added two new switches (/cost) and (/uen). Updated the figures for ICU control.

22-Jul-04 CG Version 3.3.0.2 Rev: Added that the new switches are optional.

13-Oct-04 Mkelly Fixed headers and Footers

04-Mar-05 SGODASI Changed version number

9-Mar-05 Mkelly Added new screenshots for the ICU Control section.

13-May-05 SGODASI Added new switches (/merge and /ns). Added new screenshots for the new ICU Control.

16-May-05 Mkelly Added arguments to some of the command line parameters in the sample batch file which were missing. Made manual Final.

3-Jun-05 Mkelly Saved manual as Final after version number was changed.

7-Jul-05 SGODASI Added information about EVT Cleaning Utility (Appendix D), section on reprocessing questionable event files, added two new switches (/retrytimeout and /bidchar)

8-Jul-05 Mkelly Added new screenshots for ICU section. Modified Appendix D. Fixed headers and footer and added section breaks where necessary. Updated TOC.

11-Jul-05 Mkelly Fixed sample batch file for new EVT Cleaning Utility. Made manual Final.

30-Nov-05 IDATSKOV & SGODASI

Version 3.7. Added four new switches (/mup,/product, /skipunits and /rsm) and the corresponding sections under Principles of Operation.

16-Dec-05 SGODASI Updated Appendix D for cleaning utility



16-Jun-06 IDATSKOV Added new switch /unittags and updated the sample startup files for both, the interface and the Cleaning Utility.

28-Jun-06 Mkelly Updated the ICU screenshots in the command-line parameters section, updated the How to Contact Us page.

30-Jun-06 IDATSKOV Updated the EVT interface manual using skeleton version 2.5.2

18-Jul-06 Mkelly Version 3.7.0.15-3.8.1.6 Rev A; Fixed section breaks, updated headers and footer, apply Interface Skeleton Manual.dot template, and minor other formatting items.

30-Oct-06 Idatskov Version 3.8.4.6 Added new section: Event Time Ordered Processing, added four new switches (/etop, /nodata, /tagpool, /ktinid)

2-Nov-06 Mkelly Version 3.8.4.6 Rev A; Updated ICU Control section with new screenshot showing the new command line parameters and event types. Rebuilt TOC.

7-Dec-06 Idatskov Version 3.8.4.7 Rev A: Added two more parameters /bidm (BatchID Mask) and /skipphases to both the interface and the EVTCleaning utility.

21-Dec-06 Idatskov Version 3.8.5.1: Added one more parameter, /recipetags. Added support for allowing masks to be used in switches /skipunits and /skipphases.

21-Dec-06 Janelle Version 3.8.5.1, Revision A: added a note in the ICU control section detailing which new parameters are not currently supported by the ICU control.

8-Feb-07 Idatskov Version 3.8.5.4, Updated version number

8-Feb-07 Mkelly Version 3.8.5.4, Revision A: Fixed minor formatting, updated the name of the UniInt Interface User Manual.doc.

9-Feb-07 Janelle Version 3.8.5.4, Revision B: fixed formatting in introduction paragraph, updated name of UniInt End User document to UniInt Interface User Manual, updated /ps documentation in startup command file parameters table.

12-Feb-07 Janelle Version 3.8.5.4, Revision C: added more information regarding the use of SetDeviceStatus in the introduction of the manual.

02-Jun-07 Idatskov Added paragraph in Sub-PISubBatch section. Added 3 new switches /rtd, /rto, /ras=<start,end>

14-Jun-07 Idatskov Added new switch /fnapc (Formula Name As Product Code).



29-Jun-07 Mkelly Version 3.8.6.4 Rev A: Updated ICU Control screen shots and descriptions. Corrected formatting in tables.

02-May-08 Idatskov Version 3.8.6.6, Updated version number

06-May-08 Janelle Version 3.8.6.6, Revision A: updated to skeleton 3.0.1

11-Nov-08 Idatskov Version 3.8.6.8, Updated version number

4-Dec-2008 Janelle Version 3.8.6.8, Revision A: updated installation checklist to use the same order for diagnostic tags as is later described in the manual.

8-Dec-2008 Mkelly Version 3.8.6.8, Revision B: fixed page number for terminology section and updated TOC.

1-Jul-2009 Idatskov Version 3.8.6.9, Added new switch /tf.

12-Aug-2009 Mkelly Version 3.8.6.9, Revision A; Fixed headers and footers, rebuilt TOC, corrected other minor formatting.

29-Aug-2012 EPaolino Version 3.8.7,0; Changed Version Number


Event File Interface to the PI System -...

Documents

Transcript of Event File Interface to the PI System -...