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. |Worldwide Offices |
|777 Davis St., Suite 250 |OSIsoft Australia |
|San Leandro, CA 94577 USA |Perth, Australia |
| |Auckland, New Zealand |
|Telephone |OSI Software GmbH |
|(01) 510-297-5800 (main phone) |Altenstadt, Germany |
|(01) 510-357-8136 (fax) |OSI Software Asia Pte Ltd. |
|(01) 510-297-5828 (support phone) |Singapore |
| |OSIsoft Canada ULC |
|techsupport@ |Montreal, Canada |
| |OSIsoft, Inc. Representative Office |
|Houston, TX |Shanghai, People’s Republic of China |
|Johnson City, TN |OSIsoft Japan KK |
|Mayfield Heights, OH |Tokyo, Japan |
|Phoenix, AZ |OSIsoft Mexico S. De R.L. De C.V. |
|Savannah, GA |Mexico City, Mexico |
|Seattle, WA | |
|Yardley, PA | |
|Sales Outlets and Distributors |
|Brazil |South America/Caribbean |
|Middle East/North Africa |Southeast Asia |
|Republic of South Africa |South Korea |
|Russia/Central Asia |Taiwan |
| |
|WWW. |
|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 LEGEND |
|Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the |
|Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 |
| |
|Unpublished – rights reserved under the copyright laws of the United States. |
| |
|© 2006 OSIsoft, Inc. |
|PI_FoxBatch.doc |
Table of Contents
Introduction 1
Reference Manuals 2
Supported Features 2
Diagram of Hardware Connection 4
Principles of Operation 5
Overview 5
Startup 6
Data Collection Modes 7
Maintaining Connections to SQL Server and PI Server 7
Gathering Performance Information 8
Controlling Functionality without Stopping the Interface 8
Installation Checklist 9
Interface Installation 11
Naming Conventions and Requirements 11
Interface Directories 11
PIHOME Directory Tree 11
Interface Installation Directory 11
Interface Installation Procedure 12
Installing Interface as a Windows Service 12
Installing Interface Service with PI ICU 12
Installing Interface Service Manually 14
SQL Server Configuration 15
Batch Data Recovery 23
Initialization File 25
Sample PIFoxBatch.ini File 31
Interface Performance Tags 33
I/O Rate Tag Configuration 35
Startup Command File 37
Configuring the Interface with PI ICU 37
foxbatch Interface Tab 39
Command-line Parameters 56
Sample PIFoxBatch.bat File 63
Control File 65
Sample PIFoxBatch_CONTROL.txt File 68
Interface Node Clock 69
Security 71
Starting / Stopping the Interface 73
Starting Interface as a Service 73
Stopping Interface Running as a Service 73
Starting Interface Interactively 73
Buffering 75
Appendix A: Error and Informational Messages 77
Message Logs 77
Messages 77
Initialization or Startup Errors 77
General Errors 80
System Errors and PI Errors 81
Revision History 83
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 Manuals
OSIsoft
• 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
[pic]
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 Operation
Overview
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:
[pic]
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 [pic] 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.
[pic] - Add Button
To add a dependency from the list of Installed services, select the dependency name, and click the Add button.
[pic] - 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 [pic] and a Stop button [pic] 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.
[pic]
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 Node |
|without Bufserv implemented |
|Manual service |PIFoxBatch.exe –install –depend tcpip |
|Automatic service |PIFoxBatch.exe –install –auto –depend tcpip |
|*Automatic service with service|PIFoxBatch.exe –serviceid X –install –auto –depend tcpip |
|id | |
*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
[pic]
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
[pic]
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
[pic]
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
[pic]
Figure 6. ActionCDOrder table sample data records
[pic]
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= |This parameter is used to identify the column in the BatchIDLog |
|Required |table which will provide the Batch name. |
|Operation= |This parameter is used to identify the column in the BatchDetail|
|Required |table which will provide the Operation name. |
|Order= |This parameter is used to identify the column in the |
|Required |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= |This parameter is used to identify the column in the BatchDetail|
|Required |table which will provide the Phase name. |
|PhaseInstance= |This parameter is used to identify the column in the BatchDetail|
|Required |table which will provide the Phase Instance ID. |
|Product= |This parameter is used to identify the column in the BatchIDLog |
|Required |table which will provide the Product name for Batches and |
| |UnitBatches. |
|Recipe= |This parameter is used to identify the column in the BatchIDLog |
|Required |table which will provide the Recipe name for Batches and |
| |Procedure name for UnitBatches. |
|RecipeVersion= |This parameter is used to identify the column in the BatchIDLog |
|Required |table which will provide the Recipe version for Batches. |
|Timestamp= |This parameter is used to identify the column in the BatchDetail|
|Required |table which will serve as the data timestamp source. |
|UniqueID= |This parameter is used to identify the column in the BatchDetail|
|Required |and BatchIDLog tables, which allows binding of the BatchDetail |
| |and the BatchIDLog tables. |
|Unit= |This parameter is used to identify the column in the BatchDetail|
|Required |table which will serve as the source for the equipment unit |
| |names. |
|UnitBatch= |This parameter is used to identify the column in the BatchIDLog |
|Required |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= |This parameter is used to identify which “Action_CD” code(s) in |
|Required |BatchDetail table will be used to trigger the start of the PI |
| |Batch. |
| |Example: batchstart=210 |
|batchend= |This parameter is used to identify which “Action_CD” code(s) in |
|Required |BatchDetail table will be used to trigger the end of the PI |
| |Batch. |
| |Example: batchend=211 |
|unitbatchstart= |This parameter is used to identify which “Action_CD” code(s) in |
|Required |BatchDetail table will be used to trigger the start of the PI |
| |UnitBatch. |
| |Example: unitbatchstart=210 |
|unitbatchend= |This parameter is used to identify which “Action_CD” code(s) in |
|Required |BatchDetail table will be used to trigger the end of the PI |
| |UnitBatch. |
| |Example: unitbatchend=211 |
|operationstart= |This parameter is used to identify which “Action_CD” code(s) in |
|Required |BatchDetail table will be used to trigger the start of the |
| |Operation. |
| |Example: operationstart=227 |
|operationend= |This parameter is used to identify which “Action_CD” code(s) in |
|Required |BatchDetail table will be used to trigger the end of the |
| |Operation. |
| |Example: operationend=233,234 |
|phasestart= |This parameter is used to identify which “Action_CD” code(s) in |
|Required |BatchDetail table will be used to trigger the start of the Phase.|
| |Example: phasestart=227 |
|phaseend= |This parameter is used to identify which “Action_CD” code(s) in |
|Required |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= |This parameter is used to identify which “Action_CD” code(s) in |
|Optional |BatchDetail table will be used to trigger the Phase State RUN |
|Required: if one is defined, all of them have to be|under the specific Phase. |
|defined. |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= |This parameter is used to identify which “Action_CD” code(s) in |
|Optional |BatchDetail table will be used to trigger the Phase State HELD |
|Required: if one is defined, all of them have to be|under the specific Phase. |
|defined. |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= |This parameter is used to identify which “Action_CD” code(s) in |
|Optional |BatchDetail table will be used to create the zero duration PI |
|Required: if one is defined, all of them have to be|Phase State DONE under the specific PI Phase object. |
|defined. |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= |This parameter is used to identify which “Action_CD” code(s) in |
|Optional |BatchDetail table will be used create the zero duration PI Phase |
|Required: if one is defined, all of them have to be|State ABORTED under the specific PI Phase object. |
|defined. |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:
[pic]
“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:
[pic]
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.
[pic]
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.
[pic]
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.
FoxBatch
Connection Settings
[pic]
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 [pic] button. The path to the file to be edited is displayed to the left of the [pic] button.
[pic]
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
[pic]
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
[pic]
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
[pic]
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
[pic]
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
[pic]
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.
[pic]
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.
[pic]
Cancel Button
To exit the “Initialization File Editor” without saving click on the “Cancel” button.
General / Timeouts
[pic]
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
[pic]
Picking this option will cause the interface to perform real time scan based data processing (/MODE=Realtime, default mode).
Recovery Mode
[pic]
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
[pic]
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 [pic] next to the date. The time can be entered manually, by using the arrow keys on each field or by using the spin buttons [pic] next to the time.
[pic]
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
[pic]
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 [pic] 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
[pic]
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.
[pic]
Runtime Data
Checking any of the three check boxes in this section enables the Dump to Path\FileName text box.
[pic]
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 [pic] 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
[pic]
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.
[pic]
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 |The Add Recipe Version /arv flag is used to append Recipe version to the |
|Optional |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 |The Combine Phase Name and Id /cpind flag is used to combine phase names |
|Optional |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=# |The /db=[##] parameter specifies the Interface debug logging message |
|Optional |level. There are three levels that may be assigned: |
|Default: /db=0 |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 |The /host parameter is used to specify the PI Home node. Host is the IP |
|Required |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 |The /id parameter is used to specify the Interface unique identifier. |
|Required |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= |The /keepbatches parameter is used to set the new time frame of how long |
|Optional |the Interface has to cache the closed batches in the local node memory. |
|Default: 7 | |
|/maxstoptime= |The /maxstoptime parameter is used to set the maximum time allowed for the|
|Optional |Interface to properly shutdown. The value must be given in seconds. If the|
|Default: 120 |Interface shutdown process takes longer than the specified time, the |
| |Interface will be forced to terminate immediately. |
|/mode= |The /mode parameter is used to set the running mode of the Interface. |
|Optional |There are three available modes: |
|Default: RealTime |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 |The /noupdate flag is used to disable any PI Server data updates while the|
|Optional |Interface is run in the Recovery mode. It can be used to verify batch data|
|Default: Send data to PI |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= |The /PIPswd parameter is used to explicitly specify the user password in |
|Optional |order to establish the connection to the PI Server. If this parameter is |
|Default: Use Trust Table |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= |The /PIUser parameter is used to explicitly specify the user name in order|
|Optional |to establish a connection to the PI Server. If this parameter is not |
|Default: Use Trust Table |specified, the Interface will attempt to use the trust table. |
|/PIConnTO= |This parameter is used to change the current PI Connection TimeOut |
|Optional |property. By default the Interface uses the local system settings. |
|/PIDATO= |This parameter is used to change the current PI Data Access TimeOut |
|Optional |property. . By default the Interface uses the local system settings. |
|/printtofile= |The /printtofile parameter is used to write log messages to an alternative|
|Optional |file, which would contain only messages specific to this Interface. The |
|Default: Messages are sent to the |file name should be given as a full path file name. |
|pipc.log. |Example: /printtofile= |
| |c:\pipc\interfaces\FoxBatch\Intf.log |
|/ps=x |The /ps parameter specifies the Point Source for the Interface. X is not |
|Required |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= |The Recovery End Time /ret parameter is used to set the target end time of|
|Required only for /mode=Recovery |the history data recovery process. |
|Default: None |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 formats: |
| |hh:mm:ss |
| |hh:mm:ss am/pm |
| |where |
| |hh – hours, mm – minutes, ss – seconds |
| |Examples: |
| |ret = 2005-09-29 19:12:01 |
| |ret = 29-sep-2005 7:12:01 pm |
|/retry= |The /retry parameter is used to set the time delay used by the Interface |
|Optional |between the retries, to establish a broken connection to the SQL or PI |
|Default: 60 |Server. |
|/retryTO= |The Retry TimeOut /retryTO parameter is used to set the timeout of the |
|Optional |retry parameter value. The default value is set to 0 (infinity). |
|Default: 0 | |
|/rst= |The Recovery Start Time /rst parameter is used to set the target start |
|Required only for /mode=Recovery |time of the history data recovery process. |
|Default: None |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 formats: |
| |hh:mm:ss |
| |hh:mm:ss am/pm |
| |where |
| |hh – hours, mm – minutes, ss – seconds |
| |Examples: |
| |rst = 2005-09-13 14:12:01 |
| |rst = 13-sep-2005 2:12:01 pm |
|/scan= |The /scan parameter defines the time period between Interface scans in |
|Required |terms of seconds. |
| |Example: |
| |/scan=30 |
| |If the scanning frequency is set to 30 seconds, the Interface will attempt|
| |to query and process data every 30 seconds. Although, scan may be skipped |
| |if an abundance of data is processed. |
|/singlerun |The /singlerun parameter is used to stop the Interface as soon as the |
|Optional |first batch of SQL data is processed. It must be used only when the |
| |Interface is ran interactively. |
|/skipunits= |The /skipunits parameter specifies the list of units for which all |
|Optional |batch-related data from SQL Server should be ignored. For each record, the|
| |Interface will check the unit name against the listed unit names. If there|
| |is a match, the Interface will not process the record. 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 flag. |
| |Example: |
| |Without space in the unit names: /skipunits=C301,FX124 |
| |With the space in the unit names: /skipunits=”C301,FX 124” |
|/smp=”PI Module Path” |The Start Module Path /smp parameter is used to set an alternate PI Module|
|Optional |path. It can be used to set custom module hierarchy under which the units |
|Default: Root level |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: |
| |\\\\ |
| |e.g. |
| |/smp=\\MyEnterprise\MyPlant\ |
| |The PI server is not specified in this syntax, since this is known from |
| |the /host parameter. |
|/smpasr |The Set Missing Product as Recipe /smpasr flag is used to set missing |
|Optional |product values as recipe values in each record read from the SQL Server |
| |history database. |
|/source=[name/IP] |The /source flag is used to specify the SQL Home node. Source is the IP |
|Required |address of the SQL Sever node or the domain name of the SQL Server node. |
| |The /source flag must be explicitly defined on command line. |
| |Examples: |
| |/source=foxtest |
| |/source=206.79.198.32 |
|/SQLConnTO= |The /SQLConnTO parameter is used to change the current SQL Connection |
|Optional |TimeOut property. |
|Default: /SQLConnTO=60 | |
|/SQLDATO= |The /SQLDATO parameter is used to change the current SQL Data Access |
|Optional |TimeOut property. .. |
|Default: /SQLDATO=300 | |
|/SQLPswd= |The /SQLPswd parameter is used to specify the user password in order to |
|Optional |establish the connection to the SQL Server. If this parameter is not |
|Default: Use the Trust Table |specified, the Interface will try to use the trust table. |
| |Note: The /SQLPswd parameter must be used in conjunction with the /SQLUser|
| |parameter. |
|/SQLUser= |The /SQLUser parameter is used to specify the user name in order to |
|Optional |establish the connection to the SQL Server. If this parameter is not |
|Default: Use the Trust Table |specified, the Interface will try to use the trust table. |
Sample PIFoxBatch.bat File
REM=======================================================================
REM
REM PIFoxBatch.bat
REM
REM Sample startup file for the PI FoxBatch Interface to the PI System
REM
REM=======================================================================
REM
REM OSIsoft strongly recommends using the PI ICU to modify startup files.
REM
REM Sample command line
REM
PIFoxBatch.exe ^
/smp="\\Foxboro\Year2006" ^
/mode=realtime ^
/smpasr ^
/ps=FB ^
/id=11 ^
/host=localhost ^
/source=localhost ^
/sqluser=test ^
/sqlpswd=test ^
/scan=15 ^
/db=0 ^
/printtofile="c:\Foxboro\messages.log" ^
/retry=10 ^
/keepbatches=7 ^
/maxstoptime=125
REM
REM End of sample PIFoxBatch.bat File
Control File
Each running instance of the Interface has its own Control file, PIFoxBatch__Control.txt.It is created automatically when the interface is started. If the control file already exists prior to interface startup, it is going to be reset by the interface while booting. This file is used to change Interface settings 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.
The Control file commands can be entered through the ICU Control Utility or manually while the interface is running. The available set of commands is shown in (Table 8). The Control file commands have the following syntax: command=value. There should be only one command per line. The commands and values are not case sensitive. Some of the command-line parameters are the same as in the section “Startup Command File.”
Table 8.Control file commands and values
|Command and Value |Description |
|batchlist=file |This command is used to print the batch data structures currently cached in |
| |the local node memory to the file. The value for this command is the word |
| |“file” |
| |Note: This command must be used in conjunction with the command: |
| |file=. |
|db=# |This command is used to set the new debug level for message printing to the |
|Same as in |local log file pipc.log. |
|startup command file. | |
|file= |This command is used to set the file used for output of Interface runtime |
| |data. |
| |Note: File name should contain the full path to the file when the Interface |
| |is run as a service. |
| |Example: |
| |file=C:\PIPC\Interfaces\FoxBatch\output.txt |
|keepbatches= |This command is used to set the new time window on how long the Interface has|
|Default: |to cache the closed batches in the local node memory. The default value is 7 |
|keepbatches=7 |days. |
|mode=Recovery |This command switches the Interface in the Recovery mode. |
| |Note: The Interface will switch to the RealTime mode when the recovery |
| |process is complete. |
|notfoundrecords=file |This command is used to print records to the file for which the Interface |
| |failed to find PI batch objects in the local node memory. Generally, these |
| |records are associated with setting the end time for the PI batch objects. |
| |The main reason for these records to exist is the original data on the SQL |
| |server is not time and action ordered, i.e. the record containing the batch |
| |object end time may appear before the record with the start time. These |
| |records are maintained in the memory for the time period set by the command |
| |line switch /keepbatches=. The value for this command is the word |
| |“file” |
| |Note: This command must be used in conjunction with the command: |
| |file=. |
|noupdate=true |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. |
|PIConnTO= |This command is used to change the current PI Connection TimeOut property. By|
|Default: |default the Interface uses the local SDK connection timeout value. |
|PIConnTO= | |
|PIDATO= |This command is used to change the current PI Data Access TimeOut property. .|
|Default: |By default the Interface uses the local SDK data access timeout. |
|PIConnTO= | |
|ret= |This command is used to set the target end time of the history data recovery |
|Same as in |process. |
|startup command file. |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. |
|retry= |This command will change the time delay, used by the Interface, in order to |
|Same as in |reestablish broken connection to the SQL/PI Server. The default value is set|
|startup command file. |to 60 seconds. |
|Default: | |
|Retry=60 | |
|retryTO= |This command is used to set the timeout of the retry command. The default the|
|Default: |value is set to 0 (timeout is not set). |
|retryTO=0 | |
|rst= |This command is used to set the target start time of the history data |
|Same as in |recovery process. |
|startup command file. |Note: This command must be used in conjunction with the mode=recovery |
| |command. |
|scan= |This command allows setting the time period between the Interface scans. The |
|Same as in |default value is 60 seconds. |
|startup command file. | |
|Default: | |
|Scan=60 | |
|SQLConnTO= |This command is used to change the current SQL Connection TimeOut property. |
|Same as in |The default value is 60 seconds. |
|startup command file. | |
|Default: | |
|SQLConnTO=60 | |
|SQLDATO= |This command is used to change the current SQL Data Access TimeOut property. |
|Same as in |In the literature this property is also referred to the Command Timeout. The |
|startup command file. |default value is 300 seconds. |
|Default: | |
|SQLDATO=300 | |
|unitList=file |This command is used to print unit list to the file currently known to the |
| |Interface. The value for this command is the word “file” |
| |Note: This command must be used in conjunction with the command: |
| |file=. |
Sample PIFoxBatch_CONTROL.txt File
db = 1
keepbatches = 10
mode = recovery
rst = 2005-09-13 2:43:05 pm
ret = 2005-09-29 7:12:01 pm
noupdate = true
file = “c:\foxbatch\runtime.txt”
batchlist = file
unitlist = file
notfoundrecords = file
PIConnTo = 25
PIDATO = 75
Retry = 12
RetryTO = 250
Scan = 120
SQLConnTO = 15
SQLDATO = 60
Interface Node Clock
Make certain 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 PI Interface node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,
[pic]
In addition, make certain the TZ environment variable is not defined. All of the currently defined environment variables may be viewed by opening a Command Prompt window and typing set.
C:> set
Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.
Security
The 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: 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 Server, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for information on error messaging.
PI Server v3.3 and Higher
Security Configuration using piconfig
For 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,PIUser
a_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 Editor
The 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.2
For 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,proxyaccount
piapimachine,piadmin
@quit
In place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.
Starting / Stopping the Interface
This section describes starting and stopping the Interface once it has been installed as a service. See the UniInt End User Document to run the Interface interactively.
[pic]
Starting Interface as a Service
If the Interface was installed as a service, it may be started from PI ICU, the services control panel or with the command:
FoxBatch.exe –start
To start the Interface service with PI ICU, use the [pic] button on the PI ICU toolbar.
A message will inform the user of the status of the Interface service. Even if the message indicates the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons. One typical reason is the service is not able to find the command-line arguments in the associated .bat file. Verify 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 Service
If the Interface was installed as a service, it may be stopped at any time from PI ICU, the services control panel or with the command:
FoxBatch.exe –stop
The service can be removed by:
FoxBatch.exe –remove
To stop the Interface service with PI ICU, use the [pic] button on the PI ICU toolbar.
Starting Interface Interactively
The Interface can be started interactively by executing the batch file from the command prompt. Verify the executable path in the batch file is correct before running the Interface interactively.
Buffering
This interface does not use Buffering because the batch data is already buffered by the Foxboro IA BES historian database.
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. 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 Logs
The messages are logged in the local node log file PIHOME\dat\pipc.log and optionally in the additional log file specified by the command-line parameter /printtofile.
Messages are written to log files at the following events:
• When the Interface starts many informational messages are written to the log. These include the version of the Interface, the version of PI SDK, the version of the PI Server, and the command-line parameters used.
• As the Interface processes batch-related data, messages are sent to the log if there are any problems with data retrieval from the SQL Server or data processing to the PI Server.
• If the /db is used on the command line, then various informational messages are written to the log file.
Messages
The PI Foxboro Batch Interface logs all errors while processing data from SQL Server to the PI Module and PI Batch databases. In addition, there are various debug level messages which may be logged using the /db= switch in the Interface startup file. By default the debug level is set to 0. This means that only errors will be reported in the log files. By setting the debug level to 1, in addition to error messages, the Interface will report the result of each significant processing operation. By setting debug level to 2, the Interface will log the detailed report on each action performed by the Interface. For example, SQL server data query expression and its result, the result of batch creation would be logged.
Initialization or Startup Errors
Generally, 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 exist (since many of the initial parameters need to be synchronized – checked or created with or on the PI server).
"main_controlloop: STARTUP ERROR: Failed to initialize COM Library"
This error is a Windows specific error. It means that the Interface failed to initialize COM Library. Please consult with Microsoft support to resolve this error.
"Foxbatch.exe: parse_argument_file: Error, Failed to open argument file: "
This error means that the Interface failed to find the batch file associated with the specific Interface instance. Make sure that the batch file is consistent with the serviceid of the Interface. For example, if the service id is set as serviceid 4, the batch file must be named PIFoxBatch4.bat.
"parse_argfile_line: Error, Found open quote (\") without closing quote on command line...abort"
This error means that one of the command line parameters in the startup batch file has only one opening quote without matching closing quote. Check the batch file for missing quotes.
"… Memory allocation error, …"
Errors containing the message above generally mean that the Interface node is out of memory. Release some memory by closing unused applications.
"ERROR, the interface CAN NOT be started as a SERVICE with mode=SETUP. The available interface modes while running as a SERVICE are: REALTIME, RECOVERY"
The Interface was started as a service in the Setup mode. This mode is only available when the Interface is run interactively. Solution: Adjust startup command line parameters for this instance of the Interface. The available modes are: RealTime, Recovery.
"read_ini_file: Unable to locate Initialization file: "
Verify that initialization file named exists in the Interface directory.
"read_ini_file: Unable to open Initialization file in READ MODE: "
Check the access properties of the initialization file named .
"[MISSING REQUIRED COMMAND LINE PARAMETERS] : "
There are missing required command line parameters. Check startup command line parameters in the Interface’s batch file PIFoxBatch.bat located in PIHOME\Interfaces\FoxBatch\ directory.
"Error: the source name/(IP address) is an empty string"
Check that the command line switch /source contain a value.
"Error: the source Name/IP must start with character/number"
Check the syntax of the provided value for the command line switch /source.
"Error: the source Name/IP must end with character/number"
Check the syntax of the provided value for the command line switch /source.
"Error: invalid character in the source name/IP"
Check the syntax of the provided value for the command line switch /source.
"Error: the source IP address is not valid, must contain only digits"
Check the syntax of the provided value for the command line switch /source.
"Error: the source IP address is not valid, symbol cannot be used as IP address port separator, valid port separator for source IP is "
Check the syntax of the provided value for the command line switch /source. The port must be separated from the IP address by a comma.
"Error: the source IP address is not valid, symbol cannot be used more than once"
Check the syntax of the provided value for the command line switch /source.
"Error: the source IP address is not valid, it must contain 4 fields"
Check the value for the command line switch /source. The Interface failed to identify 4 fields of IP address in source value.
"[MISSING INI FILE PARAMETERS] : "
There are missing initialization file parameters. Check the initialization file PIFoxbatch.ini located in the PIHOME\Interfaces\FoxBatch\ directory.
"[MISSING BATCH LOGIC VALUES] : "
There are missing initialization file parameters. Check the initialization file PIFoxbatch.ini located in the PIHOME\Interfaces\FoxBatch\ directory.
"… Failed, COM Error [error number] : "
Errors containing the message above are COM generated errors. These errors can occur on data queuing from SQL server as well as during processing of data to the PI Server. Refer to PI SDK reference manual in order to resolve such errors.
"Error: Failed to Generate ActionCDOrder table entries"
The Interface failed to create internal ordered ActionCD list based on provided information in the initialization file. As result, it can not create/ update the ActionCDOrder table on SQL server. Check the initialization file for proper syntax.
"netsafe:: GetDigitalStates: Error, Failed to retrieve the ‘System’ StateSet, …"
The Interface failed to retrieve SYSTEM digital state set. Refer to the concomitant COM error for detailed description.
"netsafe:: GetDigitalStates: Error, Failed to retrieve ‘…’ DigitalState"
The Interface failed to retrieve the specific digital state from the PI Server. Contact OSIsoft’s Tech Support to resolve this error.
"netsafe::FindCreateStatusTags: Error while searching for performance tag"
The Interface failed to retrieve the performance tag from the PI Server. Refer to the concomitant COM error for detailed description.
"netsafe::FindCreateStatusTags: Error while searching for performance tag"
The Interface failed to retrieve the performance tag from the PI Server. Refer to the concomitant COM error for detailed description.
"netsafe::FindCreateStatusTags: ERROR, failed to Add object to pNmValues collection"
The Interface failed to add performance tag. Refer to the concomitant COM error for detailed description.
"UnitList::SetRootModule: Error, Starting Module Path MUST start with \\"
Check the value of the command line switch /smp.
"UnitList::SetRootModule: Error, Failed to find module: "
The Interface failed to locate one of the modules specified by the command line switch /smp. Make sure the user module path exists on PI Server. Check the value of the command line switch /smp.
"… Retry timeout is reached, the interface will shutdown"
The errors containing the message above are associated with the lost connection to the SQL/PI server. Check the connection to the SQL/PI server. Set a greater value for the command line parameter /retryTO. Setting it to 0 (default) will disable the retry timeout.
"Execute_query: Error, failed to execute"
Contact OSIsoft’s technical support to resolve this error.
"check_SDK_version: Error: Too many fields in SDK Version"
Contact OSIsoft’s technical support to resolve this error.
"set_PISDK_GUID: Error, the interface failed to identify itself to the PI Server, appID = NULL, Terminating"
Contact OSIsoft’s technical support to resolve this error.
"Error, Failed to Get/Add PIHeading Set for PIFoxBatch interface, terminating"
Contact OSIsoft’s technical support to resolve this error.
"UnitList::SetRootModule: Error, The root pointer = NULL"
Contact OSIsoft’s technical support to resolve this error.
General Errors
"ReadCommandFile: ERROR, Unable to read command file: , REASON: No reading privileges"
The control file can not be read. Check the control file read access attribute.
"ReadCommandFile: ERROR, Unable to reset command file: , REASON: No writing privileges"
The control file can not be reset. Check the control file write access attribute.
"link::RemoveChildren: Failed to cleanup, some objects still remain in the memory"
Contact OSIsoft’s technical support to resolve this error.
"RecordList::ReadFromBinaryFile: Error, DATA file can not be read, the interface does not have reading rights"
Check the read attributes of the binary file, named as it is provided in the message.
"RecordList::ReadFromBinaryFile: Error, DATA file can not be read, the interface does not have reading rights"
Check the read attributes of the binary file, named as it is provided in the message.
"RecordList::ReadFromBinaryFile: Error, Failed to read data from binary file "
The binary data file is corrupted. Contact the OSIsoft’s technical support to resolve this error.
"RecordList::SaveToBinaryFile: Error, unable to save DATA file , the interface does not have write"
Check the write attributes of the binary file, named as it is provided in the message.
"… = NULL …"
The errors containing the above substring are associated with bad memory pointers. Contact OSIsoft’s technical support to resolve this error.
"… was not cleaned properly …"
The errors containing the above substring are associated with incorrect releasing of memory. Contact OSIsoft’s technical support to resolve this error.
"RecordList::TimeFromStringToUTC: Failed to convert timestring […] to UTC time, Error: …"
Invalid or unsupported SQL data time format. Contact OSIsoft’s technical support to resolve this error.
"link::FindDataOnPIServer: (BatchDB level=0) Error, GetItem() returns NULL"
Contact OSIsoft’s technical support to resolve this error.
"link::FindDataOnPIServer: (BatchDB level=1) Error, failed to add PIUnit to local unit list, terminating"
Refer to the concomitant error message for more details.
"link::FindDataOnPIServer: (BatchDB level>1) Error, trying to access PI Subbatches information from higher level than UnitBath"
Contact OSIsoft’s technical support to resolve this error.
"link::FindDataOnPIServer_ModuleDB: Error, this function must be called only from BatchList tree leve (0), terminating"
Contact OSIsoft’s technical support to resolve this error.
"link::FindDataOnPIServer_ModuleDB: Error, the Root module path is NULL, terminating"
Contact OSIsoft’s technical support to resolve this error.
"link::FindDataOnPIServer_ModuleDB: Development error, wrong level to add UnitBatch"
Contact OSIsoft’s technical support to resolve this error.
"link::RemoveClosedBatches: Error, failed to properly release memory"
Contact OSIsoft’s technical support to resolve this error.
"link::AnalyzeRecoveryData: Error, Failed to get PI Object or start/end time while searching for …"
Refer to the concomitant error message for more details.
System Errors and PI Errors
System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.
Error Descriptions on Windows
On Windows, descriptions of system and PI errors can be obtained with the pidiag utility:
Windows: \PI\adm\pidiag –e error_number
Revision History
|Date |Author |Comments |
|14-Apr-2006 |IDATSKOV |Created the user manual. |
|22-May-2006 |Chrys |Rearranged manual |
|23-Jun-2006 |MKelly |Added section on ICU Control, updated the TOC. |
|27-Jun-2006 |IDatskov |Modified the SQL screenshots |
|5-Jul-2006 |Janelle |Version 1.0.0.9, Revision A: fixed headers and footers; |
| | |fixed spelling errors, grammar errors; fixed formatting in |
| | |ICU Control section. Added section for Buffering and I/O |
| | |Rates. |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
-----------------------
Service installed or uninstalled
Status of the Interface Service
Status of the ICU
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related download
Related searches
- calculator with the pi button
- how to cleanse the lymphatic system naturally
- batch file to run powershell command
- batch file to run powershell script
- batch file to run powershell as admin
- windows batch files to rename files
- batch file to rename multiple files
- batch file to close program
- batch file to run ps1
- batch xlsx to xls converter
- windows batch write to file
- batch write to file