Foxboro Batch Interface to the PI System

Foxboro Batch Interface to the PI System

Version 1.0.0.9

Revision A

How to Contact Us

OSIsoft, Inc.

777 Davis St., Suite 250

San Leandro, CA 94577 USA

Telephone

(01) 510-297-5800 (main phone)

(01) 510-357-8136 (fax)

(01) 510-297-5828 (support phone)

techsupport@osisoft.com

Houston, TX

Johnson City, TN

Mayfield Heights, OH

Phoenix, AZ

Savannah, GA

Seattle, WA

Yardley, PA

Worldwide Offices

OSIsoft Australia

Perth, Australia

Auckland, New Zealand

OSI Software GmbH

Altenstadt, Germany

OSI Software Asia Pte Ltd.

Singapore

OSIsoft Canada ULC

Montreal, Canada 

OSIsoft, Inc. Representative Office

Shanghai, People’s Republic of China 

OSIsoft Japan KK

Tokyo, Japan 

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

Mexico City, Mexico 

Sales Outlets and Distributors

· Brazil

· Middle East/North Africa

· Republic of South Africa

· Russia/Central Asia

· South America/Caribbean

· Southeast Asia

· South Korea

· Taiwan

WWW.OSISOFT.COM

OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.

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

Unpublished – rights reserved under the copyright laws of the United States.

© 2006 OSIsoft, Inc. PI_FoxBatch.doc

Table of Contents

1Introduction

2Reference Manuals

2Supported Features

4Diagram of Hardware Connection

5Principles of Operation

5Overview

6Startup

7Data Collection Modes

7Maintaining Connections to SQL Server and PI Server

8Gathering Performance Information

8Controlling Functionality without Stopping the Interface

9Installation Checklist

11Interface Installation

11Naming Conventions and Requirements

11Interface Directories

11PIHOME Directory Tree

11Interface Installation Directory

12Interface Installation Procedure

12Installing Interface as a Windows Service

12Installing Interface Service with PI ICU

14Installing Interface Service Manually

15SQL Server Configuration

23Batch Data Recovery

25Initialization File

31Sample PIFoxBatch.ini File

33Interface Performance Tags

35I/O Rate Tag Configuration

37Startup Command File

37Configuring the Interface with PI ICU

39foxbatch Interface Tab

56Command-line Parameters

63Sample PIFoxBatch.bat File

65Control File

68Sample PIFoxBatch_CONTROL.txt File

69Interface Node Clock

71Security

73Starting / Stopping the Interface

73Starting Interface as a Service

73Stopping Interface Running as a Service

73Starting Interface Interactively

75Buffering

77Appendix A: Error and Informational Messages

77Message Logs

77Messages

77Initialization or Startup Errors

80General Errors

81System Errors and PI Errors

83Revision History

Introduction

The OSIsoft’s PI Foxboro Batch (FoxBatch) Interface to the PI Data Archive collects batch data from the SQL Server-based data log on Foxboro IA Series DCS Batch Execution System (BES).

The flow of data is uni-directional; the data can only be read from a Foxboro IA BES and written to the PI Server. By design, the Interface does not edit or delete the source data. However, the Interface does create its own tables, copies source data into those tables and deletes data from them.

The PI Foxboro Batch Interface is a scan-based Interface and is designed to populate the PI Batch Database and the PI Module Database. The Interface requires two performance tags and, unlike most other PI Interfaces, there are no other tags associated with the Interface. The Interface does not use the PI API buffering service because the batch data is already buffered by the Foxboro IA BES historian database.

The Interface can run in three different modes:

1. Setup

2. RealTime (default)

3. Recovery

The Setup mode is used to setup the processing environment for the Interface and it must be used when the Interface is run for the first time or the settings in initialization file has been changed. If the Interface has not been run in the Setup mode, then the other two modes may not collect data.

The RealTime mode is the default mode of operation and the Recovery mode is designed to recover batch data provided the data is still in the SQL Server. The principal difference between RealTime and Recovery mode is that in the RealTime mode the Interface will process each data record to the PI Server as soon as it is retrieved from the SQL Server, whereas in the Recovery mode, the start and the end times of the entire batch must be known before comparison with the data in PI and sending any missing data to PI.

In Recovery mode, all open batches are processed only when there are no complete batches left to be processed. If the Interface is started in Recovery mode, it will change to RealTime mode as soon as it completes the recovery process. The Interface can also perform data integrity checks without updating the PI Server by running the Interface in Recovery mode along with the /noupdate switch.

The Interface is designed to handle connection losses either to the PI Server or to the SQL Server database. The Interface does not require either the SQL Server or the PI Server databases to be available at the time of the Interface startup. If the connection to the PI or SQL Server fails due to network interruption or server unavailability, the Interface will periodically try to reestablish the connection to the server. Once the Interface reconnects and has good communication to both databases, it will process all the data since the connection was lost.

Note: The PI FoxBatch Interface requires PI Server version 3.3 SR 2 or higher, PI SDK version 1.3.3.304 or higher, and MDAC version 2.6 or higher.

Reference ManualsOSIsoft

· PI Server manuals

· PI SDK User manual

Foxboro

· Foxboro IA Series DCS manual

Supported Features

Feature

Support

Part Number

PI-IN-FX-BA-NTI

* Platforms

Windows (2000, XP)

APS Connector

No

Point Builder Utility

No

ICU Control

Yes

PI Point Types

Integer

Sub-second Timestamps

Yes

Sub-second Scan Classes

No

Automatically Incorporates PI Point Attribute Changes

No

Exception Reporting

No

Outputs from PI

No

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

Scan-based

Supports Questionable Bit

No

Supports Multi-character PointSource

Yes

Maximum Point Count

No

* Uses PI SDK

Yes

PINet String Support

N/A

* Source of Timestamps

Device, Interface

* History Recovery

Yes

UniInt-based

No

Failover: UniInt-based / Other

No

* Vendor Software Required on PI Interface / PINet Node

Yes

Vendor Software Required on Foreign Device

No

Vendor Hardware Required

No

Additional PI Software Included with Interface

No

Device Point Types

N/A

* See paragraphs below for further explanation.

Platforms

The 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.

Uses PI SDK

The PI SDK and the PI API are bundled and must be installed on each PI Interface node. The PI FoxBatch Interface specifically makes PI SDK calls to access the PI Module Database and PI Batch Database. The Interface requires PI SDK version 1.3.3.304 or higher to be installed. The Interface uses PI API to log messages in the local pipc.log file. It does not require a PI API connection to the PI Server.

Source of Timestamps

Since each batch data record in the Foxboro IA BES history data log contains a timestamp, the PI FoxBatch Interface uses that timestamp for the batch records in PI. For the performance tags, the Interface uses the local system time at the time the value is being recorded.

History Recovery

The operation of the PI FoxBatch Interface may be interrupted without loss of data. While the Interface is offline, the data is being buffered on the SQL Server.

The Interface can recover data provided it is still available in the Foxboro IA BES history database. In order to perform history data recovery, the Interface must be run in Recovery mode. In this mode, the Interface can recover data for any time period specified by the user. The recovery time period can be set by the optional command line parameters /rst and /ret. If none of these parameters are specified, the Interface will recover all the data from the SQL Server. Note, the data recovery is also limited by other factors on the PI Server, like the date of creation of each PIUnit, the size of archives into which data is backfilled, etc. For more detailed information on the recovery process see section “Batch Data Recovery.”

Vendor Software Required

The Microsoft Data Access Components (MDAC) version 2.6 or higher must be installed on the PI Interface node. This Interface specifically uses the ActiveX Data Objects (ADO) driver from the MDAC collection to make data queries to the Foxboro IA BES SQL-based history database.

Diagram of Hardware Connection

Figure 1. Schematic of Hardware Configuration for PI Foxboro Batch Interface

The Foxboro IA Series DCS Batch Execution System (BES) is installed with an embedded SQL Server as the native data historian. By default, the SQL Server setup installs Microsoft Data Access Components (MDAC) on the same node as the SQL server. For example, SQL Server 2000 SP1 comes with MDAC version 2.6. MDAC suite contains ODBC, OLEDB and ADO drivers. The PI Foxboro Batch Interface uses the ADO driver to connect to SQL Server for data access. MDAC 2.6 or higher is also required on the Interface node. Typically, MDAC is installed with the operating system. If MDAC is not installed, it can be downloaded from Microsoft website.

The Interface connects to the PI Server through PI SDK. The Interface requires PI SDK 1.3.3.304 or higher to be installed on the same node as the Interface. The Interface may be installed either on the same node as the Sequel Server (SQL), PI Server or on a completely separate PI Interface 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 Foxboro BES vendor for recommendations as to installing third-party software, such as the PI Foxboro Batch Interface, on the same node as the SQL server. In the hardware configuration above where the Interface is installed on a separate PI Interface node, PI SDK and Microsoft MDAC are required to be installed on the Interface node.

Principles of OperationOverview

The PI Foxboro Batch Interface is designed to transfer batch data from the Foxboro IA Series DCS SQL Server-based data log to the PI Server Batch and Module databases. The Foxboro IA Series DCS Batch Execution System (BES) consists of various components and the SQL Server is one of them. The SQL Server is used to store the actions performed by the Foxboro IA Series DCS. The SQL Server contains multiple databases. The Foxboro BES is using only one specific database. In version 6.4 of the Foxboro BES, this database is named “BatchHistory.” The Interface is designed to connect only to the BatchHistory database (and not any other components on the BES or other databases on the SQL Server) and hence can collect data only from this database. Microsoft ADO driver for the SQL Server is used to communicate with the BatchHistory database.

The SQL Server has two tables that are of interest to this Interface. Those tables are named “BatchDetail,” “BatchIDLog.” However, the Interface does not always query data from these tables directly. The Interface creates three additional tables named “Backfill,” “Recovery” and “ActionCDOrder” and one trigger named “BatchDetailCopyToBackFill.” These names are configurable in the initialization file named PIFoxBatch.ini located in PIHOME\Interfaces\FoxBatch\. The purpose of the trigger is to copy data from the “BatchDetail” table to the “Backfill” table when the data is first written to the “BatchDetail” table. The Interface will then query the “BackFill” table at every scan. On successful data retrieval, it stores the data in the local data file named PIFoxBatch.bin and deletes the data from the “Backfill” table. Deleting the data from the “Backfill” table will guarantee that on the next scan the table will contain only new data. This method of data retrieval improves performance because we do not need to perform any complex queries on the SQL Server to identify new data. The local data file will be updated as the data is sent to PI. The Interface checks this file on every restart to see if there is any unprocessed data. The “Backfill” table is locked by the Interface while reading and deleting the data so that the trigger only caches the new data from the “BatchDetail” table without updating the “Backfill” table. Once the data is deleted from the “Backfill” table, the Interface will unlock the table and disconnect from the SQL server until the next scan.

The “Recovery” table is used during the batch history data recovery process. The Interface uses this table to filter and extract data from the “BatchDetail” table for the specified time period. This method of data extraction minimizes the data querying time to the SQL server and reduces the amount of data to be transferred over the network.

The purpose of the “ActionCDOrder” table is to filter and order the data during data query by the Interface. The reference to this table is used in all data queries performed by the Interface. Based on the retrieved data, the Interface creates the necessary PIModules and it adds PIBatches, PIUnitBatches and PISubBatches to PI Server. The PI SDK provides read and write access to the PI Server.

The Interface can run in three different modes: Setup, RealTime (default), and Recovery. All modes can be run either interactively or as a service. The Interface mode can be set through the command line switch /mode. The Interface requires the Setup mode be used when it is started for the first time or if there were changes made to the initialization file. In the Setup mode, the interface will not send any data to PI. Instead, the Interface checks the connection to the SQL Server. The Interface verifies that the two tables named “BatchDetail” and “BatchIDLog” exist on the SQL Server. The Interface also checks for the existence of the three tables named “Backfill,” “Recovery,” and “ActionCDOrder,” and the one trigger named “BatchDetailCopyToBackfill”; the interface creates them if they do not exist. These tables and the trigger are required for the Interface to collect data when run in either RealTime or Recovery mode. If the /noupdate switch is used in conjunction with the /mode=Setup, then the Interface will simply check the existence of the tables and will not create them if they do not exist. For details on the tables and trigger created on the SQL Server see the section “SQL Server Configuration.” The RealTime and Recovery modes are used to read the data from the SQL Server and send the data to PI. These two modes are explained in more detail later in this section.

Startup

On startup, the Interface checks the command-line parameters and reads additional parameters from the initialization file named PIFoxBatch.ini. If any of the required parameters or values is missing or invalid, the Interface will report the error to the local pipc.log file and terminate. Once the required startup parameters have been validated, the Interface will try to establish connection to the SQL server and perform initial testing on reading data from the SQL Server. The tests are: verifying existence of the required tables, making simple queries on each table, and verify existence of the trigger on “BatchDetail” table. If the Interface cannot connect to the SQL Server, it will attempt to reconnect at the frequency specified by the /retry switch. If any of the tests fail, then the Interface will report the error to the pipc.log log file and terminate.

The Interface will use the login information specified in the command-line parameters. If the login information is not specified, then the trust table on the SQL Server will be used. The login information is required to have read access rights to the “BatchDetail” and “BatchIDLog” tables. In the Setup mode the Interface requires read and write access to the BatchHistory database in order to create new Interface-specific tables and trigger. In the RealTime and Recovery modes of operation, the Interface requires read and write access to the “Backfill” and “Recovery” tables only.

If all the tests on the SQL Server are successful, the Interface will try to establish connection to the PI Server. The Interface will use the login information specified in the command-line parameters. If the login information is not provided, the trust table on the PI Server will be used. If the Interface cannot establish connection to the PI Server, it will attempt to reconnect at the frequency specified by the /retry switch. Once the connection to the PI Server is established, the Interface validates and initializes more startup parameters, like the /smp (Starting Module Path), that require connection to the PI Server for validation.

The connection to the PI server is established once and remains active while the Interface is running and processing data. However, the connection to the SQL Server is opened on every scan and closed as soon as the data is retrieved. It is recommended by Microsoft that the connection should be maintained only for the duration of the data query in order to reduce the load on the SQL server. Once the PI server startup validation is done, the Interface terminates if it is run in the Setup mode. If it is run in Recovery mode or RealTime mode, the Interface starts reading data from the SQL Server and sending it to PI.

Data Collection Modes

The RealTime mode is the default mode of operation. In this mode the Interface will process data for the PI Server as soon as it is retrieved from SQL Server. In order to increase performance of the Interface and to allow out-of-order data to be processed, PI batch data structures are cached in the local memory for the specified period of time. The default value is set to seven days. This value can be modified through the command-line parameter /keepbatches. On every start in RealTime mode, the Interface checks the data file PIFoxBatch.bin for any unprocessed data. The data file is located at PIHOME\Interfaces\FoxBatch\ directory and is processed first before retrieving data from the SQL Server. This file will contain data if the Interface was stopped while processing records from the SQL Server. After processing data from the file, the Interface retrieves data from the SQL Server based on a joint query to “Backfill, “BatchIDLog,” and “ActionCDOrder” tables and sends the data to PI.

The Recovery mode is designed to recover batch history data, provided the data is available on the SQL Server. The Interface determines the recovery time period based on the optional command-line parameters: Recovery Start Time /rst and Recovery End Time /ret. If the /rst switch is not specified, the Interface will perform recovery from the first record in the “BatchDetail” table. If the /ret switch is not specified, the Interface will perform recovery until the last record in the BatchDetail table. If neither of these parameters is specified, the Interface will perform data recovery for all records in the BatchDetail table. For example, consider that the /rst switch is not specified and the /ret switch is specified. In this case, the Interface will perform the data recovery from the first record in “BatchDetail” table until the end time specified with /ret switch. The Interface uses “Recovery” table on the SQL Server to create a filtered subset of data from the “BatchDetail” table. Then it retrieves data from the SQL Server based on joint query to “Recovery”, “BatchIDLog” and “ActionCDOrder” tables. The Recovery mode operates differently from the RealTime mode in that the start and the end times of the entire batch must be known before comparing with the data in PI and sending any missing data to PI. In Recovery mode, all open batches are processed only when there are no complete batches left to be processed. The Interface can also perform history data integrity checks without updating the PI Server database. This mode can be set by specifying an optional command line switch /noupdate in conjunction with the switch /mode=Recovery. When the Recovery mode processing is complete, the Interface automatically switches to the RealTime mode. For more detailed explanation on Recovery mode see section on “Batch Data Recovery”. The Interface can be forced to a Recovery mode while running through the mode command in the Control file. For more detailed information see section “Changing parameters while the Interface is running.” See the “Batch Data Recovery” section for more details.

Maintaining Connections to SQL Server and PI Server

The Interface is designed to detect and recover from connection loss to either the SQL Server or the PI Server or both. If the connection is lost during processing, the Interface will suspend all actions until the PI and SQL Servers are available for communications. The Interface will try to reconnect every /retry seconds until the /retry timeout is reached. Connection to the SQL or the PI Server could be lost for various reasons including broken physical network, SQL Server shutdown, PI Server or required Server’s subsystem shutdown, PI Server backup, etc. The Interface will log the errors to the local pipc.log file.

Interface shutdown and restart will not result in data loss. All data is buffered on the SQL Server and in the local binary file. If the Interface is interrupted and it did not finish processing data from SQL server to the PI Server, it will save any unprocessed data to the local binary data file. On each start, the Interface will check the binary file for any unprocessed data. If there is data in binary file, the Interface will process it first.

Gathering Performance Information

Each running instance of the PI FoxBatch Interface requires two performance tags. One tag, FoxBatch__ProcessedRecords, is used to reflect the “processing rate” of the Interface. It is updated with the number of records processed by the Interface per scan frequency. The other tag, FoxBatch__ErrorCount, is used to monitor “data processing quality” by reporting the total number of errors. If the tags are not found, the Interface will automatically create new ones.

Controlling Functionality without Stopping the Interface

The PI FoxBatch Interface is designed to change interface settings via a Control File while the interface is running. Some of the commands are useful for gathering more information than usual; others may be used to adjust initial interface settings.

Installation Checklist

For those users who are familiar with running PI Interfaces, this checklist helps get the Interface running. If not familiar with PI Interfaces, return to this section after reading the manual in detail.

1. Install the PI-Interface Configuration Utility, which installs the PI SDK and PI API.

2. Verify that the PI API and PI SDK have been installed.

3. Install the PI Foxboro Batch Interface.

4. Verify and update the initialization file PIFoxBatch.ini to match existing setup of SQL Server database.

5. Use the PI ICU utility to configure each instance of the Interface. Set the Interface mode to Setup. This mode is used to test and setup the working environment for each instance of the Interface. If only testing is desired, enable flag /noupdate.

6. Run the Interface interactively from the ICU Control or by double-clicking on the batch file generated by the PI ICU utility for the specific instance of the Interface. It is located in PIHOME\Interfaces\FoxBatch\ directory. If the Interface is run without the /noupdate flag enabled, it will test connections to the PI and SQL Servers and will test and create necessary tables and trigger on SQL server.

7. Verify results of testing in the local log file pipc.log.

8. Configure the Interface using the PI ICU utility to be run in mode=RealTime or mode=Recovery.

9. Set Interface node clock.

10. Setup security.

11. Start the Interface. Buffering is not required, since this Interface does not use buffering service. If the Interface is started in Recovery mode, it will automatically switch to RealTime as soon as the recovery process is complete.

12. Optionally create the Control file.

13. Verify data.

Interface Installation

OSIsoft 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 machine resources. The primary function of the PI Server is to archive data and service clients that request data.

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

The procedure is different if an Interface is installed on the PI Server node. The typical procedure is to install the PI Server as an automatic service and install the Interface as an automatic service dependent on the PI Update Manager and the PI Network Manager services.

Naming Conventions and Requirements

In the installation procedure below, it is assumed that the name of the Interface executable is PIFoxBatch.exe and that the startup command file is called PIFoxBatch.bat.

When Configuring the Interface Manually

When 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, PIFoxBatch1.exe and PIFoxBatch1.bat would typically be used for Interface number 1, PIFoxBatch2.exe and PIFoxBatch2.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. The service looks for its command-line parameters in a file that has the same root name.

Interface Directories

PIHOME Directory Tree

The PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the %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 may not be on the C: drive.

Interface Installation Directory

Place all copies of the Interface into a single directory. The suggested directory is:

PIHOME\Interfaces\FoxBatch\

Replace PIHOME with the corresponding entry in the pipc.ini file.

Interface Installation Procedure

The PI Foxboro Batch Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard feature of Windows 2000 and greater operating systems. When running on Windows NT 4.0 systems, the PI Foxboro Batch Interface setup program will install the Windows Installer if necessary. To install, run the FoxBatch_x.x.x.x.exe installation kit.

Installing Interface as a Windows Service

The PI Foxboro Batch Interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.

Installing Interface Service with PI ICU

The PI Interface Configuration Utility provides a user Interface for creating, editing, and deleting the Interface service:

Service Configuration

Service name

The Service name box shows the name of the current Interface service. This service name is obtained from the Interface executable.

ID

This is the service id used to distinguish multiple instances of the same Interface using the same executable.

Display name

The 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 OSIsoft suite of products.

Log on as

The 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.

Password

If 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 Password

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

Startup Type

The 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.

Dependencies

The 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.

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.

- Add Button

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

- Remove Button

To 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.

Create

The 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 Service

To 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 Interface Service Manually

Help for installing the Interface as a service is available at any time with the command:PIFoxBatch.exe –help

Change to the directory where the PIFoxBatch.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 Nodewithout Bufserv implemented

Manual service

PIFoxBatch.exe –install –depend tcpip

Automatic service

PIFoxBatch.exe –install –auto –depend tcpip

*Automatic service with service id

PIFoxBatch.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.

SQL Server Configuration

In order to retrieve data from the SQL Server history database, the Interface uses five tables: “BatchDetail,” “BatchIDLog,” “Backfill,” “Recovery” and “ActionCDOrder.” The first two tables are part of the Foxboro IA Batch Execution System (BES), while the remaining three tables are created and used by the Interface. These tables are used to optimize data retrieval from SQL Server. In addition to these tables, the SQL Server must have a trigger named “BatchDetailCopyToBackfill”. The three tables and the trigger are created or updated by the Interface when it is started with the command line switch /mode=SETUP or they can be created or updated manually.

BatchDetail Table

The BatchDetail table contains the events which are the results from the actions performed by the Foxboro IA Batch Execution System. The information from this table is used to generate batch data in the PI Batch Database, such as PIBatches, PIUnitBatches and PISubBatches (Operations, Phases, and Phase States). It is also used to create modules in the PI Module database representing the actual equipment. An example of BatchDetail table properties is shown in (Figure 2) and consists of 11 columns in the following order:

Figure 2. SQL Server BatchDetail table properties

The Interface is using only a few columns from this table. These columns and its descriptions are provided in table 1. All other columns are not used by the Interface, although the use of other columns is configurable through the initialization file PIFoxBatch.ini.

Table 1. BatchDetail table columns used by the Interface

Column Name

Description

Batch_Log_ID

This is the batch unique identifier. It is used to bind together BatchDetail and BatchIDLog tables in order to retrieve complete batch data of a specific record

DateTime

This column serves as the source of the record’s timestamp.

UnitOrConnection

It specifies the equipment unit on which the action was performed

Operation_ID

It provides the name of the operation.

Phase_ID

It provides the phase name.

Phase_Instance_ID

It provides unique identifiers for each phase. The Interface has an optional switch - Combine Phase Name and ID (/cpnid) which will allow combining “Phase_ID” and “Phase_Instance_ID” column values in order to create a unique phase name.

Action_CD

It describes which action has been executed on the Foxboro Batch Execution System.

The following list is an example of actions from the “Action_CD” column which triggers the PI Foxboro Batch Interface to process data into the PI Server.

Table 2. Action_CD codes

Code

Code Description

Action Performed by the Interface

210

Allocate

Check and start new PIBatch.

Check and start new PIUnitBatch.

211

Release

Close PIUnitBatch and any open underlying PISubBatches (Operations and Phases).

Close PIBatch (if there are no open PIUnitBatches).

227

Phase set Start

Check and start new PIBatch if necessary

Check and start new PIUnitBatch if necessary

Check and start new Operation if necessary

Start new Phase

233

Phase received Aborted

Close Phase

Close Operation (if there are no open Phases)

234

Phase received Done

Close Phase

Close Operation (if there are no open Phases)

BatchIDLog Table

The BatchIDLog contains information related to Batch and UnitBatch properties, such as Batch_ID, Product, Recipe, and Recipe Version. An example of a BatchIDLog table is shown in (Figure 3) and consists of 17 columns in the following order:

Figure 3. Foxboro Batch IA BES BatchIDLog table properties

The PI Foxboro Batch Interface requires only five columns from this table. These columns and their descriptions are provided in table 4 below.

Table 4. BatchIDLog table columns used by the Interface

Column Name

Column Description

Batch_Log_ID

This is the batch unique identifier. It is used to bind together BatchDetail and BatchIDLog tables in order to retrieve complete batch data of a specific record.

Lot_ID

It provides the name for a specific Batch.

Batch_ID

It provides the name for the specific UnitBatch.

Product_ID

It provides the Product name and is used to create and properly identify Batches and UnitBatches. In some cases the Product name can be blank based on the setup of Foxboro Batch execution system. The Interface has an optional switch /smpasr, which is used to set missing Product name as Recipe name.

Recipe_ID

It provides the Recipe name for Batches, and provides the Procedure name for UnitBatches.

Recipe_Version

It provides the Recipe version. The Recipe version can be appended to the Recipe name when the optional switch /arv is used.

Backfill Table

The Backfill table has the same properties as the BatchDetail table. This table is created and used solely by the Interface. The purpose of the table is to reduce the Interface’s interference with the BatchDetail table which is populated by the Foxboro IA BES. It also significantly reduces the Interface’s data querying time on the SQL server. With addition of the table, the PI Foxboro Batch Interface creates a trigger on the BatchDetail table. The purpose of the trigger is to create a copy of any new incoming data to the BatchDetail table, and to put it into the Backfill table. This way, the Interface has to query only the Backfill table without interfering with BatchDetail table. An example of the trigger is shown in (Figure 4) below.

Figure 4.BatchDetail trigger expression

After each successful data retrieval from the Backfill table, the Interface stores data in a local binary file and removes all accounted data from the Backfill table. On the next scan, the Interface queries the Backfill table for new unprocessed data delivered by the trigger on the BatchDetail table.

Recovery Table

The “Recovery” table has the same properties as the “BatchDetail” table. This table is created and solely used by the Interface. The purpose of the table is to create a filtered and ordered subset of original history data from the “BatchDetail” table. It is used instead of the “Backfill” table when the Interface is running in the Recovery mode. Performing data filtering and ordering directly on the SQL Server reduces the data transfer volume and increases the overall performance of the Interface by transferring only a small subset of the original history data from the SQL Server. When the Interface completes the recovery process and switches to RealTime mode, it starts reading data from the “Backfill” table. The “Backfill” table might contain a subset of data which was already processed in the Recovery mode. The Interface will identify that and it will not create any duplicate batch objects on the PI Server.

ActionCDOrder Table

The data in the BatchDetail table is NOT time or executed action ordered. It contains additional non-batch related data which is not processed by the Interface. The purpose of the ActionCDOrder table is to reduce data transfer by filtering and ordering the source data directly on the SQL server. The Interface performs partial ordering of source data when it is run in the RealTime mode, since it has only the knowledge of the current data in the “Backfill” table. The ActionCDOrder table is created and solely used by the Interface. This table can be created manually or by the Interface. Examples of ActionCD table properties and sample data entries are shown in (Figure.5 and 6).

Figure 5. ActionCDOrder table properties

Figure 6. ActionCDOrder table sample data records

Batch Data Recovery

The PI FoxBatch Interface has an option of performing history recovery of batch data to PI Server Batch and Module Databases provided the original data is available in the SQL Server database. In order to initiate the recovery process the Interface must be switched to the recovery mode. This can be achieved on Interface startup by setting mode to /mode=RECOVERY through the command line parameters, or while the Interface is running, by editing the Control file with addition of the command: mode=RECOVERY. Note, the Interface will not respond to commands until the Control file is saved. In order to recover data for specific time period, there are two additional switches available. The first switch: Recovery Start Time (/rst) is used to set the target recovery start time. The Interface will retrieve complete data for running batches at that time as well as for batches that started later. For example, if the switch is set to /rst=2005-05-16 14:00:05, and if there is 1 running batch at that time then the Interface will search for the actual start time of the running batch on SQL server and retrieve the data from its actual start time, for example 2005-05-12 11:00:12. The second switch: Recovery End Time (/ret) is used to set the target recovery end time. The Interface will retrieve complete data for running batches at that time as well as for batches that ended earlier. For example, if the switch is set to /ret=2005-05-18 22:00:03, and if there is 1 running batch at that time then the Interface will search for the actual end time of this batch, for example: 2005-05-21 5:21:14, on SQL Server and will retrieve data up to its actual end time. These switches are not essential and may be used either separately, together or not used at all. Note, if these switches are not specified, the Interface will perform complete batch data recovery based on all records in the BatchDetail table. The possible combinations of how these switches may be used, in order to perform batch data recovery, are shown in (Table 4).

Table 4. Batch Data recovery switch combinations

Recovery Switches

Performed Action

/mode=RECOVERY

/rst=…

/ret=…

X

Recover batch history data based on all available data in BatchDetail table

X

X

Recover batch history data from the specified Recovery Start Time until now.

X

X

Recover batch history data from first record in BatchDetail table until the specified Recovery End Time

X

X

X

Recover batch history data for the specified time range.

The Interface has an option of checking data integrity without adding or editing data on the PI Server. This can be achieved by running the Interface in Recovery mode with an optional command line flag /noupdate. With this flag, the Interface will only report any missing or incorrect batch related data in the PI Module and PI Batch databases to local log file pipc.log. Note, performing data check on an empty PI archive will force the Interface to write a large amount of missing data messages to pipc.log.

Initialization File

The Initialization file: PIFoxBatch.ini is used to specify the Foxboro IA Series SQL Server configuration. Each instance of the Interface should have its own initialization file. The Interface requires this information in order to connect to the SQL server and to properly generate data queries on the SQL Server. It also requires the proper Foxboro BES batch logic definition, which would trigger the start and end of PI Batch, UnitBatch, Operation, and Phase objects.

SQL PARAMETER SYNTAX

· If there are multiple values to enter for Batch Logic, use a comma (,) to separate Action CD codes.

Example: phaseend = 233, 234

· If the names of tables or the names of columns contain space(s) use the square brackets to enclose the name. Square brackets can be used around all names as well.

Examples: Backfill = [Test Table]

Backfill = [Test_Table_2]

· The ownership of the tables can be specified in the name of the tables.

Example: Backfill = dbo.TestTable or [dbo].[TestTable]

SQL DATABASE NAME

The Interface requires the database name to be provided in order to establish the connection to the SQL Server. The database name can be specified through the initialization file parameter: database.

SQL TABLE NAMES

The Interface requires table names be provided. There are two tables populated by Foxboro BES. These tables have to be defined through parameters: BatchDetail, BatchIDLog, respectively. There are three tables which will be used solely by the Interface. These tables have to be defined through the parameters: ActionCDOrder, Backfill, Recovery. These tables will be created automatically by the Interface, when it is run in Setup mode.

SQL BatchDetail TABLE TRIGGER

The Interface requires the trigger name be provided. The trigger is used to copy new data from the SQL Server BatchDetail table into the Backfill table. The trigger can be created automatically when the Interface is run in the Setup mode. The trigger name can be specified through the parameter: trigger.

SQL COLUMN DEFINITIONS

The Foxboro Batch Interface requires column definitions in order to properly generate SQL Server data queries. The list of SQL column related parameters, which must be specified in the initialization file, is shown in (Table 3). Note: The Backfill and the Recovery tables are identical to the BatchDetail table. In (Table 5) the table name: BatchDetail can be substituted by either Backfill (RealTime mode) or Recovery (Recovery mode), depending on the running mode of the Interface.

Table 5. SQL Server column related parameters

Parameter

Description

ActionCD=

This parameter is used to identify the column in the BatchDetail and in the ActionCDOrder tables which describes which action has been executed on the Foxboro BES

Lot=

Required

This parameter is used to identify the column in the BatchIDLog table which will provide the Batch name.

Operation=

Required

This parameter is used to identify the column in the BatchDetail table which will provide the Operation name.

Order=

Required

This parameter is used to identify the column in the ActionCDOrder table which will provide the logical ordering of actions executed on Foxboro BES. An example of ordering logic would be:

· batch start

· unitbatch start

· operation start

· phase start

· phase end

· operation end

· unitbatch end

· batch end

Note: The ordering logic is used during the data querying on SQL server, since the original data is not executed action ordered, i.e. the end of phase may appear after the unitbatch is closed.

Phase=

Required

This parameter is used to identify the column in the BatchDetail table which will provide the Phase name.

PhaseInstance=

Required

This parameter is used to identify the column in the BatchDetail table which will provide the Phase Instance ID.

Product=

Required

This parameter is used to identify the column in the BatchIDLog table which will provide the Product name for Batches and UnitBatches.

Recipe=

Required

This parameter is used to identify the column in the BatchIDLog table which will provide the Recipe name for Batches and Procedure name for UnitBatches.

RecipeVersion=

Required

This parameter is used to identify the column in the BatchIDLog table which will provide the Recipe version for Batches.

Timestamp=

Required

This parameter is used to identify the column in the BatchDetail table which will serve as the data timestamp source.

UniqueID=

Required

This parameter is used to identify the column in the BatchDetail and BatchIDLog tables, which allows binding of the BatchDetail and the BatchIDLog tables.

Unit=

Required

This parameter is used to identify the column in the BatchDetail table which will serve as the source for the equipment unit names.

UnitBatch=

Required

This parameter is used to identify the column in the BatchIDLog table which will provide the UnitBatch name.

BATCH LOGIC

The Interface requires Batch Logic be provided. The logic must be defined by properly identifying which “Action_CD” codes will trigger start and end of PI Batch, UnitBatch, Operation, and Phase objects. There may be several “Action_CD” codes which will trigger the start or end of the above objects. These codes must be listed on the same line and separated by a comma. The list of required start/end parameters is shown in (Table 6).

Table 6. Foxboro Batch Logic parameters

Parameter

Description

batchstart=

Required

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the start of the PI Batch.

Example: batchstart=210

batchend=

Required

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the end of the PI Batch.

Example: batchend=211

unitbatchstart=

Required

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the start of the PI UnitBatch.

Example: unitbatchstart=210

unitbatchend=

Required

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the end of the PI UnitBatch.

Example: unitbatchend=211

operationstart=

Required

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the start of the Operation.

Example: operationstart=227

operationend=

Required

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the end of the Operation.

Example: operationend=233,234

phasestart=

Required

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the start of the Phase.

Example: phasestart=227

phaseend=

Required

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the end of the Phase.

Example: phaseend=233,234

Note: The “Action_CD” codes which trigger the start/end of the Batch and the UnitBatch, or the start/end of Operation and Phase may be the same. The initialization may contain other text information. The Interface is looking only for equal signs and exact match of the expression on the left side of the equal sign. The parameters are not case sensitive.

PHASE STATES

The Phase States are optional, but if one Phase State is defined, all Phase States must be defined. The states are sequential and depend on the start of the others. The logic must be defined by properly identifying which “Action_CD” codes will trigger start of Phase State objects. There may be several “Action_CD” codes which will trigger the start of the Phase State objects. These codes must be listed on the same line and separated by a comma. The list of Phase State parameters required by the Interface is shown in (Table 7).

Table 7. Foxboro Phase State triggers

Parameter

Description

staterun=

Optional

Required: if one is defined, all of them have to be defined.

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the Phase State RUN under the specific Phase.

Note 1: The Phase States are sequential. The Action_CD code assigned to this parameter will be used to close currently opened Phase State.

Note 2: The Interface requires either all four state parameters to be specified or none. In case the state parameters are not specified, the Interface will not create any phase states.

Example: staterun=228

stateheld=

Optional

Required: if one is defined, all of them have to be defined.

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the Phase State HELD under the specific Phase.

Note 1: The Phase States are sequential. The Action_CD code assigned to this parameter will be used to close currently opened Phase State.

Note 2: The Interface requires either all four state parameters to be specified or none. In case the state parameters are not specified, the Interface will not create any Phase States.

Example: stateheld=230

statedone=

Optional

Required: if one is defined, all of them have to be defined.

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to create the zero duration PI Phase State DONE under the specific PI Phase object.

Note 1: The PI Phase States are sequential. The Action_CD code assigned to this parameter will be used to close currently opened PI Phase State.

Note 2: The Interface requires either all four state parameters to be specified or none. In case if the state parameters are not specified, the Interface will not create any phase states.

Example: phaseend=234

stateaborted=

Optional

Required: if one is defined, all of them have to be defined.

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used create the zero duration PI Phase State ABORTED under the specific PI Phase object.

Note 1: The PI Phase States are sequential. The Action_CD code assigned to this parameter will be used to close currently opened PI Phase State.

Note 2: The Interface requires either all four state parameters to be specified or none. In case if the state parameters are not specified, the Interface will not create any phase states.

Example: stateaborted=233

Note: The initialization file may contain other text information. The Interface is looking only for equal signs and exact match of the expression on the left side of the equal sign. The parameters are not case sensitive.

Sample PIFoxBatch.ini File

[BATCH LOGIC]

batchstart = 210

batchend = 211

unitbatchstart = 210

unitbatchend = 211

operationstart = 227

operationend = 233, 234

phasestart = 227

phaseend = 233, 234

[PHASE STATES]

staterun = 228

stateheld = 230

stateaborted = 233

statedone = 234

[SQL BatchDetail TABLE TRIGGER]

trigger = BatchDetailCopyToBackfill

[SQL SERVER DATABASE NAME]

database = batchhistory

[SQL SERVER TABLE NAMES]

BatchDetail = [dbo].[BatchDetail]

BatchIDLog = [dbo].[BatchIDLog]

ActionCDOrder = [dbo].[ActionCDOrder]

Backfill = [dbo].[Backfill]

Recovery = [dbo].[Recovery]

[SQL COLUMN DEFINITIONS]

ActionCD = [Action_CD]

Lot = [Lot_ID]

Operation = [Operation_ID]

Order = [Order]

Phase = [Phase_ID]

PhaseInstance = [Phase_Instance_ID]

Product = [Product_ID]

Recipe = [Recipe_ID]

Recipe_Version = [Recipe_Version]

Timestamp = [DateTime]

UniqueID = [Batch_Log_ID]

Unit = [UnitOrConnection]

UnitBatch = [Batch_ID]

Interface Performance Tags

Each running instance of the PI Foxboro Batch Interface has two performance tags. These tags are defined as Integers. The Interface loads the performance tags based on the attributes: PointSource, Location1 (Interface id) and Location2 (tag type). If Location2 attribute equals 1, the tag is used to reflect the “processing rate” of the Interface. It is updated with the number of records processed by the Interface per scan frequency which is set by the command-line parameter /scan. It is not dependent on how much time the Interface requires to process data from each scan. If the Location2 attribute equals 2, it is used to monitor data processing quality by reporting the total number of errors. Under normal circumstances, the reported value should be zero. This performance tag can be reset to zero only by restarting the Interface. If there are errors reported, please refer to local log file, pipc.log, for error descriptions. Performance tags are updated with each scan, regardless of data volume. If the tags are not found, the Interface will automatically create new Performance tags based on the Point Source /ps and Interface id /id provided in command line parameters at startup. The names of the performance tags will be FoxBatch__ProcessedRecords with Location2=1 and FoxBatch__ErrorCount with Location2=2.

Note: The PI FoxBatch Interface does not use any other PI tags.

I/O Rate Tag Configuration

This Interface does not support I/O Rate tags.

Startup Command File

Command-line arguments can begin with a /. For example, /ps=M.

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 flags is unlimited, and the maximum length of each flag is 1024 characters.

Configuring the Interface with PI ICU

Note: 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 (PIFoxBatch.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file and the module database. The procedure below describes the necessary steps for using PI ICU to configure the PI FoxBatch Interface.

From the PI ICU menu, select Interface, then New Windows Interface Instance from EXE..., and then Browse to the PIFoxBatch.exe executable file. Then, enter values for Point Source and Interface ID#. 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.

The following display should appear:

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, to configure the interface to communicate with a remote PI Server, select ‘Interface => Connections…’ item from PI ICU menu and make it the default server. If the remote node is not present in the list of servers, it can be added.

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

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

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

Since the PI FoxBatch Interface is not a UniInt-based interface, the UniInt tab is grayed out, as well as the Perf Points and Perf Counters tabs.

To set up the interface as a Windows Service, use the Service tab. This tab allows configuration of the interface to run as a service as well as to starting and stopping of the interface. The interface can also be run 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. The next section describes the selections that are available from the foxbatch tab. Once selections have been made on the PI ICU GUI, press the Apply button in order for PI ICU to make these changes to the interface’s startup file.

foxbatch Interface Tab

Since the startup file of the PI FoxBatch Interface is maintained automatically by the PI ICU, use the foxbatch tab to configure the startup parameters and do not make changes in the file manually. The following is the description of interface configuration parameters used in the PI ICU Control and corresponding manual parameters.

FoxBatchConnection Settings

SQL Source Node IP Address or SQL Source Node HostName

These boxes are used to specify IP address or HostName of the SQL Server. Use the option button to choose either the SQL Source Node IP Address or SQL Source Node HostName. This is a required command line parameter and is specific by (/SOURCE=).

PI User ID

Check this box and then enter the PI Server username to use when making a connection. This is an optional command line parameter and is specified by (/PIUSER=).

PI Password

Check this box and then enter the PI Server user’s password to use when making a connection. This is an optional command line parameter and is specified by (/PIPSWD=).

SQL User ID

Check this box and then enter the SQL Server username to use when making a connection. This is an optional command line parameter and is specified by (/SQLUSER=).

SQL Password

Check this box and then enter the SQL Server user’s password to use when making a connection. This is an optional command line parameter and is specified by (/SQLPSWD=).

Scan Interval (sec)

Enter the scan interval (in seconds) that defines the time period between interface scans. This is an optional command line parameter and is specified by (/SCAN=#, default=60)

Edit INI file

The interface requires the user to enter SQL Server setup information. This can be achieved by clicking on the button. The path to the file to be edited is displayed to the left of the button.

All fields in yellow on this form are required and none of the setting will be saved until all fields are specified. The table owners are optional. In the following description the table owner will be denoted as optional by being enclosed in square brakets and the table names as being required in angle brackets. If the table owner is used the entry in the INI file will separate the table owner from the table name with a period.

The table entries are saved in the INI file in the following format:

[owner].[tablename]

The square brackets here are used as quotes to make sure if the owner or tablename has embedded spaces that they get passed to SQL correctly.

DATABASE NAME

DataBase Name

The interface requires the database name be provided in order to establish the connection to the SQL Server. It is specified with (database=).

TABLES

BatchDetail

The interface requires table names be provided. There are two tables populated by Foxboro BES. The first is specified by (BatchDetail=[owner].).

BatchDetail Trigger

The interface requires the trigger name be provided. The trigger is used to copy new data from the SQL Server BatchDetail table into the Backfill table. The trigger can be created automatically when the interface is run in the Setup mode. It is specified by (trigger=).

BatchIDLog

This is the second table populated by Foxboro BES. It is specified by (BatchIDLog=[owner].).

Backfill

There are three tables used soley by the interface, this is the first and is specified by (Backfill=[owner].).

Recovery

The second table used soley for the interface is specified by (Recovery=[owner].).

ActionCDOrder

The last table used soley for the interface is specified by (ActionCDOrder=[owner].).

BATCH LOGIC

Batch Start Codes

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the start of the PI Batch (batchstart=).

Batch End Codes

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the end of the PI Batch (batchend=).

Unit Batch Start Codes

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the start of the PI UnitBatch (unitbatchstart=).

Unit Batch End Codes

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the end of the PI UnitBatch (unitbatchend=).

Operation Start Codes

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the start of the Operation (operationstart=).

Operation End Codes

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the end of the Operation. (Operationend=).

Phase Start Codes

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the start of the Phase (phasestart=).

Phase End Codes

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the start of the Phase (phaseend=).

Phase State – Check box

Phase States are optional and can be enabled by checking the box next to Phase State label in Batch Logic section. Note, the Phase States are sequential, i.e. start of new state closes the previous state. The interface requires all Phase State fields to be filled if Phase State box is checked.

Phase State - RUN

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the Phase State RUN under the specific Phase. The “Action_CD code assigned to this parameter will be used to close the currently opened Phase State (staterun=).

Phase State - HELD

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to trigger the Phase State HELD under the specific Phase. . (stateheld=).

Phase State - ABORTED

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to create the zero duration Phase State ABORTED under the specific PI Phase object (stateaborted=).

Phase State - DONE

This parameter is used to identify which “Action_CD” code(s) in BatchDetail table will be used to create the zero duration Phase State DONE under the specific PI Phase object (statedone=).

COLUMN DEFINITIONS

ActionCD

This parameter is used to identify the column in the BatchDetail and in the ActionCDOrder tables which describes which action has been executed on the Foxboro BES (ActionCD=).

Order

This parameter is used to identify the column in the ActionCDOrder table which will provide the logical ordering of actions executed on Foxboro BES (Order=).

Product

This parameter is used to identify the column in the BatchIDLog table which will provide the Product name for Batches and UnitBatches (Product=)

Recipe

This parameter is used to identify the column in the BatchIDLog table which will provide the Recipe name for Batches and Procedure name for UnitBatches. (Recipe=).

RecipeVersion

This parameter is used to identify the column in the BatchIDLog table which will provide the Recipe version for Batches (RecipeVersion=).

Timestamp

This parameter is used to identify the column in the BatchDetail table which will serve as the data timestamp source (Timestamp=).

UniqueID

This parameter is used to identify the column in the BatchDetail and BatchIDLog tables, which allows binding of the BatchDetail and The BatchIDLog tables (UniqueID=).

Lot

This parameter is used to identify the column in the BatchIDLog table which will provide the Batch name (Lot=).

UnitBatch

This parameter is used to identify the column in the BatchIDLog table which will provide the UnitBatch name (UnitBatch=).

Unit

This parameter is used to identify the column in the BatchDetail table which will serve as the source for the equipment names (Unit=).

Operation

This parameter is used to identify the column in the BatchDetail table which will provide the Operations name (Operation=).

Phase

This parameter is used to identify the column in the BatchDetail table which will provide the Phase name (Phase=).

PhaseInstance

This parameter is used to identify the column in the BatchDetail table which will provide the Phase Instance ID (PhaseInstance=).

Command Buttons

Save Button

Once all the fields in yellow are filled in properly click on the “Save” button to save them to the ini file. If there are no errors then the following dialog box will appear indicating that it has saved the values to the specific location.

If any fields are still yellow when the “Save” button is clicked a dialog box similar to the one below will appear telling the user what field is in error. Once the OK button is click, the user is returned to the form so that corrections may be made.

Cancel Button

To exit the “Initialization File Editor” without saving click on the “Cancel” button.

General / Timeouts

Add Recipe Version

Checking this box will cause the interface to append the Recipe version to the Recipe name (/ARV).

Combine Phase Name and ID

Checking this box will cause the interface combine phase names and unique phase ID’s together (/CPNID).

Set Missing Product as Recipe

Checking this box will cause the interface to set missing product values as recipe values in each record read from the SQL Server history database (/SMPASR).

Modes

Realtime Mode

Picking this option will cause the interface to perform real time scan based data processing (/MODE=Realtime, default mode).

Recovery Mode

Picking this option will make the Data Recovery choice visible. In this mode the interface performs the batch data recovery on the PI Server provided the original data is available in the SQL Server history database. The recovery mode operated differently from the RealTime mode in that the start and the end times of the entire batch must be known before comparing with the data in PI and sending any missing data to PI. In recovery mode, all open batches are processed only when there are not complete batches left to be processed. The interface will switch to RealTime mode once the recovery process is completed (/MODE=Recovery).

Setup Mode

In this mode the Interface will test the connection to the SQL and the PI Servers, it will test basic SQL Server data reading and create, if missing, the Interface specific tables and trigger will be created. In order to perform testing without creating tables, check the box “Disable PI Server Data Updates” (/noupdate) in conjunction with “Setup Mode” (/mode=Setup). Note, in this mode the Interface must be run interactively. The Interface must be run in this mode for every change to the initialization file PIFoxBatch.ini in order to update the Interface specific tables with the new data. (/MODE=Setup)

Data Recovery

The data recovery items are only available if the Recovery Mode has been selected.

The dates can be entered manually, by using the arrow keys on each field or by using the drop down calendar. The calendar can be displayed by pressing the drop down button next to the date. The time can be entered manually, by using the arrow keys on each field or by using the spin buttons next to the time.

Start Time

Checking this box will allow the user to enter a start time for the data recovery. (/RST=)

End Time

Checking this box will allow the user to enter a end time for the data recovery. (/RET=)

Disable PI Server Data Updates

Checking this box disables any PI Server data updates while the interface is in Recovery mode. It can be used to verify batch data integrity and quality on the PI Server without adding or modifying missing or incorrect batch data. It is also used to disable table and trigger creation on SQL server while the interface is run in the setup mode. (/NOUPDATES)

General / Timeouts (cont.)

PI Connection Timeout (sec)

Checking this box will allow the current PI Connection TimeOut property to be changed by entering a new value in the box. (/PICONNTO=)

PI Data Access Timeout (sec)

Checking this box will allow the current PI Data Access TimeOut property to be changed by entering a new value in the box. (/PIDATO=)

SQL Connection Timeout (sec)

Use this box to change the current SQL ConnectionTimeOut property. (/SQLCONNTO=, Default:60)

SQL Data Access Timeout (sec)

Use this box to change the current SQL Data Access TimeOut property. (/SQLDATO=, Default:300)

Retry Timeout (sec)

Use this box to set the timeout for the retry parameter value. (/RETRYTO=, Default:0 (infinity))

Retry Interval (sec)

Use this box to set the time delay used by the interface between the retries, to reestablish a broken connection to the SQL/PI Server. (/RETRY=)

Keep Batches (days)

Use this box to set the new time frame of how long the interface has to cache the closed batches in the local node memory. (/KEEPBATCHES=, Default=7)

Maximum Time for Shutdown (sec)

Use this box to set the maximum time allowed for the interface to properly shutdown. If the interface shutdown process takes longer that the specified time, then the interface will be forced to terminate immediatley. (/MAXSTOPTIME=, Default:120)

Optional / Debug

Alternative Log FileSpec

Check this box to enter the location and name of an alternative file to be used to write log message to. The filespec maybe entered manually or the browse button can be used to search for the directory and file. (/PRINTTOFILE=)

Alternative Module Database Path

Check this box to set an alternate PI Module path. It can be used to set custom module hierarchy under which the units will be stored. By default the interface will add units at the root level of the PI ModuleDB. The PI Module Path has the following syntax:

\\\\<...>

(/SMP=)

Units to Ignore from SQL

Check this box enter a list of units for which all batch releated data from the SQL Server should be ignored. 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 argument. (/SKIPUNITS=)

Debug Settings

Log only errors

Checking this box will cause the interface to log only errors. (/DB=0, Default)

Log errors, warnings and major success messages

Checking this box will cause the interface to log all errors, warning and major success messages. (/DB=1)

Log all messages

Checking this box will cause the interface to log all messages. (/DB=2)

Control File

Each running instance of the interface has it own Control file: PIFoxBatch__Control.txt. This file is used to change some interface settings while the interface is running. The available commands are found on this tab. The commands are not case sensitive and most of the commands are the same as the command line parameters found above. In the following section only the changes/differences from the General/Timeout tab will be elaborated.

Perform data recovery

Checking this box adds the command mode=recovery to the control file when saving it. It also enables the Start Time, End Time and Disable PI Server Data Updates check boxes. These fields all work the same as describe earlier for the General / Timeouts Recovery mode.

Runtime Data

Checking any of the three check boxes in this section enables the Dump to Path\FileName text box.

Dump to Path\Filename

This command is used to set the file used for output of the interface runtime data. The filespec maybe entered manually or the browse button can be used to search for the directory and file. If the full path and filename are not totally visible in the text box use the cursor to hover over the text box and the full path and filename will be visible as a tooltip. (File=).

Note: The filename should contain the full path to the file when the interface is run as a service.

List of cached Batches

This command is used to print the batch data structures currently cached in the local node’s memory to the file. The value for this command is the word “file” (BatchList=file).

List of known units

This command is used to print the batch data structures currently cached in the local node’s memory to the file. The value for this command is the word “file” (UnitList=file).

List of NotFound Records

This command is used to print the batch data structures currently cached in the local node’s memory to the file. The value for this command is the word “file” (NotFoundRecords=file).

Debug Setting and other fields

All the debug setting and other fields are the same as the Command Line parameters found on the Connection Settings, General/Timeout, and the Optional/Debug tabs.

Save Control File

Use this button to save the settings that have been entered on the page. Once this has been clicked the PIFoxBatch__Control.txt file will be written and a dialog box indicating the file has been saved will appear.

One the user clicks the ok button all the entries on this screen will be reset back to blank or unchecked. The only one that will be picked will be the default setting for the debug which is “Log only errors”.

Command-line Parameters

Parameter

Description

/arv

Optional

The Add Recipe Version /arv flag is used to append Recipe version to the Recipe name.

Example:

The “Recipe_ID” column in SQL Server BatchIDLog table contains the value: “Test” and the associated “Recipe_Version” column contains the value: “25”. The Recipe name recorded in PI will be “Test_25”

/cpnid

Optional

The Combine Phase Name and Id /cpind flag is used to combine phase names and unique phase ID’s.

Example:

The “Phase_ID” column in SQL Server BatchDetail table contains the value: “VENT_ON” and the associated “Phase_Instance_ID” column contains the value: “1ABCDEFGHI”. The Phase name recorded in PI will be “VENT_ON__1ABCDEFGHI”

/db=#

Optional

Default: /db=0

The /db=[##] parameter specifies the Interface debug logging message level. There are three levels that may be assigned:

0 – Log only errors

1 – Log errors, warnings and major success messages

2 – Log ALL messages.

Log level two (2) is the most verbose setting; while level zero (0) reports the least detail (it logs only error messages). The default logging level is 0, to log errors only. When testing the Interface, it may be necessary to use a more verbose setting (1 or 2).

/host=host:port

Required

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=x

Required

The /id parameter is used to specify the Interface unique identifier.

This Interface uses the /id flag to identify a particular Interface copy number that corresponds to an integer value assigned to the Location1 point attribute of the performance tags. For this Interface, use only numeric characters in the identifier. The Interface will use this flag to look up and create, if missing, performance tags.

Example:

/id=2

/keepbatches=

Optional

Default: 7

The /keepbatches parameter is used to set the new time frame of how long the Interface has to cache the closed batches in the local node memory.

/maxstoptime=

Optional

Default: 120

The /maxstoptime parameter is used to set the maximum time allowed for the Interface to properly shutdown. The value must be given in seconds. If the Interface shutdown process takes longer than the specified time, the Interface will be forced to terminate immediately.

/mode=

Optional

Default: RealTime

The /mode parameter is used to set the running mode of the Interface. There are three available modes:

Setup – The Interface will test connection to the SQL and the PI Servers, it will test basic SQL Server data reading and create, if missing, the Interface specific tables and trigger. In order to perform testing without creating tables, use the optional flag /noupdate in conjunction with /mode=Setup. Note, in this mode the Interface must be run interactively. The Interface must be run in this mode on every change in initialization file PIFoxBatch.ini in order to update the Interface specific tables with the new data.

RealTime – (default mode) The Interface performs real time scan based data processing. Each SQL record with batch related data is processed directly to the PI Server.

Recovery – The Interface will perform the batch data recovery on the PI Server provided the original data is available in the SQL Server history database. The Recovery mode operates differently from the RealTime mode in that the start and the end times of the entire batch must be known before comparing with the data in PI and sending any missing data to PI. In Recovery mode, all open batches are processed only when there are no complete batches left to be processed.

Note: When the Interface is run in the Recovery mode, it will perform complete recovery from the first record in BatchDetail table till present. In order to perform recovery on specific time period, please use parameters /rst and /ret. These parameters may be used together or separately. In order to analyze PI batch data integrity without updating data use the optional /noupdate flag in conjunction with /mode=Recovery.

Note: The Interface will switch to the RealTime mode when the Recovery process is complete.

Recovery mode examples:

Recovery from first record until present: /mode=recovery

Recovery from known start time until present: /mode=recovery /rst=”2005-03-15 14:53:01”

Recovery from known start time until known end time: /mode=recovery /rst=”2005-03015 14:53:01” /ret=”2005-03-19 22:10:11”

Recovery from first record until known end time: /mode=recovery /ret=”2005-03-19 22:10:11”

Analyze batch data integrity from known start until known end time: /mode=recovery /noupdate /rst=”2005-03015 14:53:01” /ret=”2005-03-19 22:10:11”

/noupdate

Optional

Default: Send data to PI

The /noupdate flag is used to disable any PI Server data updates while the Interface is run in the Recovery mode. It can be used to verify batch data integrity and quality on the PI Server without adding or modifying missing or incorrect batch data.

It is also used to disable table and trigger creation on SQL Server while the Interface is run in the Setup mode.

/PIPswd=

Optional

Default: Use Trust Table

The /PIPswd parameter is used to explicitly specify the user password in order to establish the connection to the PI Server. If this parameter is not specified, the Interface will try to use the trust table.

Note: The /PIPswd parameter must be used in conjunction with the /PIUser parameter.

/PIUser=

Optional

Default: Use Trust Table

The /PIUser parameter is used to explicitly specify the user name in order to establish a connection to the PI Server. If this parameter is not specified, the Interface will attempt to use the trust table.

/PIConnTO=

Optional

This parameter is used to change the current PI Connection TimeOut property. By default the Interface uses the local system settings.

/PIDATO=

Optional

This parameter is used to change the current PI Data Access TimeOut property. . By default the Interface uses the local system settings.

/printtofile=

Optional

Default: Messages are sent to the pipc.log.

The /printtofile parameter is used to write log messages to an alternative file, which would contain only messages specific to this Interface. The file name should be given as a full path file name.

Example: /printtofile=c:\pipc\interfaces\FoxBatch\Intf.log

/ps=x

Required

The /ps parameter specifies the Point Source for the Interface. X is not case sensitive and can be any single or multiple characters. For example, /ps=P and /ps=p are equivalent.

The point source that is assigned with the /ps flag corresponds to the PointSource attribute of the individual performance tag. The Interface will use this flag only to look up and to create, if missing, performance tags.

/ret=

Required only for /mode=Recovery

Default: None

The Recovery End Time /ret parameter is used to set the target end time of the history data recovery process.

Note: This command must be used in conjunction with the mode=recovery command. If the specified datetime is invalid, the Interface will switch to RealTime mode.

The SQL Server accepts the following DATE formats:

yyyy-mm-dd

yyyy/mm/dd

yyyy.mm.dd

mm-dd-yyyy

mm/dd/yyyy

mm.dd.yyyy

dd-mmm-yyyy

dd/mmm/yyyy

dd.mmm.yyyy

dd mmm yyyy

where

dd – day number (1-31)

mm – month number (1-12)

yyyy – four digit year, i.e. 2006

mmm - abbreviation of the month, i.e: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec

The SQL Server accepts the following TIME