BatchFile
Interface to the PI System
Version 2.10.2.0
Revision D
1
UniInt End-User Interface to the PI System
How to Contact Us
OSIsoft, Inc.777 Davis St., Suite 250
San Leandro, CA94577USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSIsoft Software GmbH
Altenstadt,Germany
OSIsoft Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors
- Brazil
- Middle East/North Africa
- Republic of South Africa
- Russia/Central Asia
- South America/Caribbean
- Southeast Asia
- South Korea
- Taiwan
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.
© 1996-2006 OSIsoft, Inc. PI_BatchFL.doc
1
UniInt End-User Interface to the PI System
Table of Contents
Introduction
Reference Manuals
Supported Features
Diagram of Hardware Connection
Principles of Operation
Installation Checklist
Interface Installation on Windows
Naming Conventions and Requirements
Interface Directories
The PIHOME Directory Tree
Interface Installation Directory
Interface Installation Procedure
Installing the Interface as a Windows Service
Installing the Interface Service with PI ICU
Installing the Interface Service Manually
Digital States
PointSource
PI Point Configuration
Point Attributes
Tag
PointSource
PointType
Location1
Location2
Location3
Location4
Location5
InstrumentTag
ExDesc
Scan
UserReal1
Shutdown
Performance Point Configuration
I/O Rate Tag Configuration
Monitoring I/O Rates on the Interface Node
Configuring I/O Rate Tags with PI ICU (Windows)
Configuring IORates Tags Manually
Configuring the PI Point on the PI Server
Configuration on the Interface Node
Data File Format
Data Files
Startup Command File
Configuring the Interface with PI ICU
batchfl Interface Tab
Command-line Parameters
Informational Parameters
Sample batchfl.bat File
Interface Node Clock
Security
Windows
Starting / Stopping the Interface on Windows
Starting Interface as a Service
Stopping Interface Running as a Service
Buffering
Appendix A: Error and Informational Messages
Message Logs
System Errors and PI Errors
Revision History
1
Batch File Interface to the PI System1
Introduction
The Batch File Interface reads data from comma-delimited ASCII files and sends the data to a Plant Information (PI) System. Basically, the files include the PI tagname, timestamp, and data value. Other formats are described later in this manual. The interface requires the PI API so it may run on a PI API node or a PI Home node.
This document applies to Windows platforms.
Reference Manuals
OSIsoft
- PI Data Archive Manual
- PI API Installation Instructions
- PI ICU UserManual
- UniInt End User Document
Supported Features
Feature / SupportPart Number / PI-IN-BF-LAB-NTI
*Platforms / NTI (4, 2000, XP, 2003)
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / Float16 / Float32 / Float64 / Int16 / Int32 / Digital / String
Sub-second Timestamps / Yes
Sub-second Scan Classes / No
Automatically Incorporates PI Point Attribute Changes / Yes –only when /as is passed
Exception Reporting / Yes –only when /ex is passed
Outputs from PI / No
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based
Supports Questionable Bit / Yes
Supports Multi-character PointSource / No
Maximum Point Count / Unlimited
*Uses PI SDK / Yes-only when /pt is passed
PINet String Support / No
* Source of Timestamps / Vendor
History Recovery / No
UniInt-based / No
Failover / No
Vendor Software Required on PI InterfaceNode / No
Vendor Software Required on DCS System / No
Vendor Hardware Required / No
Additional PI Software Included with Interface / No
*See paragraphs below for further explanation.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater. No service packs are required.
Uses PI SDK
The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface does not specifically make PI SDK calls unless /pt is passed in for point creation.
Source of Timestamps
Each line of the input file includes the timestamp for the given data value.
Diagram of Hardware Connection
1
Batch File Interface to the PI System1
Principles of Operation
The Batch File Interface reads ASCII files of the format described in the Data Files section.
The oldest data files are read first. The last modified time is read to determine the oldest file. Data in the files is read from the top, so older data should be at the top.
If communication fails to the PI Server, the interface will stop reading data files and the files will queue. The interface will try to re-connect every 30 seconds. When the connection is back, the data files will be processed. The record that was being read at the time of a communication failure will be reprocessed once communication has resumed.
Extended PI API calls for string tag support and sub-second data support are used by default if the PI server is at version PI 3.1 or higher. The command line parameters /lb for piar_putvalue and /ex for pisn_sendexceptionqx support the extended PI API calls if the PI server is PI 3.2 SR1 or higher and PI API 1.3.0 or higher. If both /lband /ex are passed, /lb takes precedence.
The maximum tagname size is 255 characters. The maximum string value size is 1024characters. If a PI Tagname does not exist, a single error message will be written to the log file.
With the Windows interface version 1.9 or higher, data that is out of order will be rejected and an error message written. The exception to this is if the interface is started in the /lb mode where data can be replaced or if the /oo parameteris passed to allow out of order events.
When using the Alias Tag command line parameter(/as=E or I), the data file will have an Alias Tagname instead of a PI tagname or PI tag number. The interface will search for the alias tag in the Extended Descriptor (E) or Instrument Tag (I) of the points with the specified point source. If the /as is used, a point source must be specified (/ps=x). The interface will HALT if anything other than an E or an I is passed. The strings in the extended descriptor or instrument tag field and the alias tag field in the data line are not case sensitive. All strings are converted to upper case before being used.
The interface supports checking for point updates when running in alias mode. It is imperative that the user passes a unique point source when in this mode. A maximum of 25 points will be processed for point updates and is done after all files are scanned.
With interface version 2.6 or higher, scaling can be performed on the data. If you put a /sc in the startup file, the userreal1 point attribute will be read and the value will be multiplied by the value in the data file. This is only for integer and real type points. No scaling will be done if the userreal1 value is equal 0.0.
Connection Establishment and Connection Recovery to PI
The interface establishes the initial connection to PI and reconnects to PI in the event that the connection is lost. If the interface is started while the PI Server is down, the interface will try to establish a connection until the PI Server is up.
Point Updates
If the interface is running in alias mode (/as), a list of tags with the specified pointsource is maintained along with the InstrumentTag or Extended Descriptor. The interface is notified when a PI point is added, deleted, or edited. It is imperative that the user passes a unique point source when in this mode.
The interface will only process 25 point updates at a time. If more than 25 points are added, edited, or deleted at one time, the interface will process the first 25 points, wait 30seconds, process the next 25 points, and so on. Once all points have been processed, the interface will resume checking for updates every 2 minutes.
If the interface is not running in alias mode, point updates have little effect on the interface. The interface will put data into PI for those PI tags that exist at the time the file is read and that have the correct point source (if the point source is used).
Point Creation
When the /pt=<PIPointTypestartup parameter is set, the interface will make PI-SDK calls to createthe PI Point if the point in the data line does not exist
Each instance of the interface will only be able to create one type of point, so multiple instances will need to be run. One for each point type required. Digital type points will also required an instance for each DigitalState Set used. The interface supports Digital, Int16, Int32, Float16, Float32, Float64 and String type points.
If the PointType is digital then the DigitalState set name to be used with these new points will have to be specified on the startup command line. The /DS=DigitalSetName is the switch for this purpose. The DigitalSetName will have to be one of the digital set names found on the PI home node that the interface is communicating with.
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps get the Interface running. If the user is unfamiliar with PI interfaces, he/she should return to this section after reading the rest of the manual in detail.
- Install the PI Interface Configuration Utility (which installs PI SDK and PI API)
- Verify that the PI API is installed.
- Install the Batch File Interface.
- Create any needed digital states.
- Choose a point source.
- Configure PI Points.
Location1is not used.
Location2is not used.
Location3is not used.
Location4is not used.
Location5 is not used.
ExDesc is used to define an Alias for a tag name. Either ExDesc or InstrumentTag can be used.
InstrumentTag is used to define an Alias for a tag name. Either ExDesc or InstrumentTag can be used. - Configure I/O Rate Tag (for details see the section titled “I/O Rate Tag Configuration”).
- Configure the interface using the PI ICU utility or edit startup command file manual. It is recommended to use PI ICU whenever possible.
- Set interface node clock
- Set up security.
- Create a test input file.
- Start the interface without buffering.
- Verify data.
1
Batch File Interface to the PI System1
Interface Installation on Windows
OSIsoft recommends that interfaces be installed on PI API nodes instead of directly on the PIServer node. A PI API node is any node other than the PI Server node where the PIApplication Programming Interface (PI API) has been installed (see the PI APIInstallation Instructions manual). With this approach, the PI Server need not compete with interfaces for system resources. The primary function of the PI Server is to archive data and to service clients that request data.
Bufserv is not needed for this interface. The interface will stop scanning data files when the connection to the PI server is down. The interface will start scanning the data files once the connection is backup.
In most cases, interfaces on PI Interface Nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.
The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and install the interface as an automatic service that depends on the PI Update Manager and PI Network Manager services. This typical scenario assumes that Bufserv is not enabled on the PI Server node.
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface executable is BatchFL.exe and that the startup command file is called BatchFL.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, BatchFL1.exe and BatchFL1.bat would typically be used for interface number 1, BatchFL2.exe and BatchFL2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line parameters in a file that has the same root name.
Interface Directories
The PIHOME Directory 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 PIHOMEdirectory does not need to be on the C: drive.
Interface Installation Directory
The interface is installed to:
PIHOME\Interfaces\BatchFL\
Where PIHOME is the corresponding entry in the pipc.ini file.
Interface Installation Procedure
The PI Batch File Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000and greater operating systems. When running on Windows NT 4.0 systems, thePI Batch File setup program will install the Windows Installer itself if necessary. To install, run the BatchFl_x.x.x.x.exe installation kit.
Run PI ICU to configure the interface, or alter the command-line parameters in the .bat file as discussed in this manual.
Try to start the interface interactively with the command:
BatchFL.bat
If the interface cannot be started interactively; the interface will not be able to run as a service either. It is easier to debug interactively started processes because error messages are echoed directly to the screen. Once the interface is successfully running interactively, one can try to run it as a service by following the instructions below.
Installing the Interface as a Windows Service
The Batch File Interface service can be created with the PI Interface Configuration Utility, or can be created manually.
Installing the Interface Service with PI ICU
The PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service:
Multiple Instances
In order to configure multiple copies of the Batch File Interface, the BATCHFL.EXE executable must be copied to a new name, such as BATCHFL1.EXE, and then a new instance may be created. This is because the Batch File Interface is not UniInt-based, and does not support service IDs.
Service Configuration
Service Name
The Service to Add 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 need to be started manually on reboot.
- If the Auto option is selected, the service will be installed to start automatically when the machine reboots.
- If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.
- If the Disabled option is selected, the service will not start at all.
Generally, interface services are set to start automatically.
Dependencies
The Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependent should be moved into the Dependencies list using the button. For example, if PI API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. To remove a service from the list of dependencies, use the button, and the service name will be removed from the “Dependencies” list.