PI Batch File Interface
Batch File
Interface to the PI System
Version 2.11.1.0
Revision B
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 |OSIsoft Software GmbH |
|(01) 510-297-5800 (main phone) |Altenstadt, Germany |
|(01) 510-357-8136 (fax) |OSIsoft 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. |
| |
|© 1996-2008 OSIsoft, Inc. PI_BatchFL.doc |
Table of Contents
Introduction 1
Reference Manuals 1
Supported Features 1
Diagram of Hardware Connection 3
Principles of Operation 5
Installation Checklist 7
Interface Installation on Windows 9
Naming Conventions and Requirements 9
Interface Directories 9
The PIHOME Directory Tree 9
Interface Installation Directory 10
Interface Installation Procedure 10
Installing Interface as a Windows Service 11
Installing Interface Service with PI Interface Configuration Utility 11
Installing Interface Service Manually 14
Digital States 15
PointSource 17
PI Point Configuration 19
Point Attributes 19
Tag 19
PointSource 19
PointType 19
Location1 20
Location2 20
Location3 20
Location4 20
Location5 20
InstrumentTag 20
ExDesc 21
Scan 21
UserReal1 21
Shutdown 21
Performance Point Configuration 23
I/O Rate Tag Configuration 25
Monitoring I/O Rates on the Interface Node 25
Configuring I/O Rate Tags with PI ICU (Windows) 25
Configuring IORates Tags Manually 27
Configuring the PI Point on the PI Server 27
Configuration on the Interface Node 27
Data File Format 29
Data Files 29
Startup Command File 33
Configuring the Interface with PI ICU 33
batchfl Interface page 35
Command-line Parameters 39
Informational Parameters 43
Sample batchfl.bat File 44
Interface Node Clock 45
Security 47
Windows 47
Starting / Stopping the Interface on Windows 49
Starting Interface as a Service 49
Stopping Interface Running as a Service 49
Buffering 51
Which Buffering Application to Use 51
How Buffering Works 52
Buffering and PI Server Security 52
Enabling Buffering on an Interface Node with the ICU 53
Choose Buffer Type 53
Buffering Settings 54
Buffered Servers 57
Installing Buffering as a Service 59
Appendix A: Error and Informational Messages 65
Message Logs 65
System Errors and PI Errors 65
Revision History 67
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 User Manual
Supported Features
|Feature |Support |
|Part Number |PI-IN-BF-LAB-NTI |
|*Platforms |NTI (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 |
|Disconnected Startup |No |
|SetDeviceStatus |No |
|Failover |No |
|Vendor Software Required on PI Interface Node |No |
|Vendor Software Required on DCS System |No |
|Vendor Hardware Required |No |
|Additional PI Software Included with Interface |No |
|Serial Based Interface |No |
*See paragraphs below for further explanation.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating systems. 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
[pic]
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 /lb and /ex are passed, /lb takes precedence.
The maximum tag name size is 255 characters. The maximum string value size is 1024 characters. If a PI Tag name 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 parameter is 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 30 seconds, 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= startup parameter is set, the interface will make PI SDK calls to create the 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 Digital State Set used. The interface supports Digital, Int16, Int32, Float16, Float32, Float64 and String type points.
If the PointType is digital then the Digital State 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.
1. Install the PI Interface Configuration Utility (which installs PI SDK and PI API)
2. Verify that the PI API is installed.
3. Install the Batch File Interface.
4. Create any needed digital states.
5. Choose a point source.
6. Configure PI Points.
Location1 is not used.
Location2 is not used.
Location3 is not used.
Location4 is 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.
7. Configure I/O Rate Tag (for details see the section titled “I/O Rate Tag Configuration”).
8. Configure the interface using the PI ICU utility or edit startup command file manual. It is recommended to use PI ICU whenever possible.
9. Set interface node clock
10. Set up security.
11. Create a test input file.
12. Start the interface without buffering.
13. Verify data.
Interface Installation on Windows
OSIsoft recommends that interfaces be installed on PI API nodes instead of directly on the PI Server node. A PI API 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 Installation 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 back up.
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 PIHOME directory 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 2000 and greater operating systems. When running on Windows NT 4.0 systems, the PI 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 Interface as a Windows Service
The Batch File Interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.
Installing Interface Service with PI Interface Configuration Utility
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.
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. For example, if 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 [pic] button, and the service name will be removed from the Dependencies list.
When the 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 interface service will not run.
Note: Please see the PI Log and Windows Event Logger for messages that may indicate the cause for any service 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.
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.
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
The toolbar contains a Start button [pic] and a Stop button [pic]. 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:
BATCHFL.exe –help
Open a Windows command prompt window and change to the directory where the BATCHFL1.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 |
|with Bufserv implemented |
|Manual service |BatchFL.exe –install –depend “tcpip bufserv” |
|Automatic service |BatchFL.exe –install –auto –depend “tcpip bufserv” |
|*Automatic service with service|BatchFL.exe –serviceid X –install –auto –depend “tcpip bufserv” |
|id | |
|Windows Service Installation Commands on a PI Interface Node or a PI Server Node |
|without Bufserv implemented |
|Manual service |BatchFL.exe –install –depend tcpip |
|Automatic service |BatchFL.exe –install –auto –depend tcpip |
|*Automatic service with service|BatchFL.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) or parameter found in the interface .bat file.
Check the Microsoft Windows Services control panel to verify that the service was added successfully. The services control panel can be used at any time to change the interface from an automatic service to a manual service or vice versa.
Digital States
For more information regarding Digital States, refer to the PI Data Archive Manuals.
Digital State Sets
PI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server Reference Guide manual.
An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.
System Digital State Set
Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state bad input to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients.
PointSource
The PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For example, one may choose the letter B to identify points that belong to the Batch File Interface. To implement this, one would set the PointSource attribute to B for every PI Point that is configured for the Batch File Interface. Then, if one uses /ps=B on the startup-command line of the Batch File Interface, the Batch File Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of B. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the /ps parameter.
Case-sensitivity for PointSource Attributes
In all cases, the point source character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=B and /ps=b are equivalent. One only needs to be careful with the case of the PointSource during point definition, and only if the interface will be running on a PINet node communicating to a PI 3 Server.
Reserved Point Sources
Several subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface.
Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the PI Data Archive. A single point is configured for each measurement value that needs to be archived.
Configuration of these points is discussed below.
Point Attributes
Tag
A tag is a label or name for a point. Any tag name can be used in accordance to the normal PI point naming conventions.
Length
The length of the Tag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
|PI API |PI Server |Maximum Length |
|1.6 or higher |3.4.370.x or higher |255 |
|1.6 or higher |Below 3.4.370.x |255 |
|Below 1.6 |3.4.370.x or higher |255 |
|Below 1.6 |Below 3.4.370.x |255 |
PointSource
The PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface.
Note: The Batch File Interface processes tags with any point source unless the /PS command line parameter is used in the startup file.
A point source must be specified on the command line when running the interface in alias mode /AS=x.
PointType
Typically, DCS point types do not need to correspond to PI point types. For example, integer values from a DCS can be sent to floating point or digital PI tags. Similarly, a floating-point value from the DCS can be sent to integer or digital PI tags, although the values will be truncated.
Windows Interface Node Connected to a PI 3 Server Node
Float16, float32, float64, int16, int32, digital, and string point types are supported on PI 3 Servers. For more information on the individual point types, see PI Server Reference Guide. The interface requires PI Server 3.2. SR1 or greater and PI API version 1.3.0 or greater for String values to be replaced.
Location1
Not used by this interface.
Location2
Not used by this interface.
Location3
Not used by this interface.
Location4
Not used by this interface.
Location5
Not used by this interface.
InstrumentTag
Length
The length of the InstrumentTag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
|PI API |PI Server |Maximum Length |
|1.6 or higher |3.4.370.x or higher |32 |
|1.6 or higher |Below 3.4.370.x |32 |
|Below 1.6 |3.4.370.x or higher |32 |
|Below 1.6 |Below 3.4.370.x |32 |
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 InstrumentTag (I) of the points with the specified point source. 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.
ExDesc
Length
The length of the Extended Descriptor field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
|PI API |PI Server |Maximum Length |
|1.6 or higher |3.4.370.x or higher |80 |
|1.6 or higher |Below 3.4.370.x |80 |
|Below 1.6 |3.4.370.x or higher |80 |
|Below 1.6 |Below 3.4.370.x |80 |
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. 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.
Scan
The Scan attribute is not used.
UserReal1
With Batch File Interface version 2.6 or higher, scaling can be performed on the data. If /sc is in the startup .bat 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.
Shutdown
It is undesirable to write shutdown events 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, allowing continuous data collection when the server is down for maintenance, upgrades, backups, and unexpected failures.
The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Server System Management Guide.
To disable SHUTDOWN events from being written to PI when PI is restarted, set the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Server System Management Guide.
Bufserv
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 back up.
If bufserv is running, data files will continue to be processed when the connection to the PI Server is down, but will stop processing data files when BatchFL needs information from the PI Server. The most likely information needed would be translating strings to digital codes for digital tags.
Since bufserv is not necessary for this interface, OSIsoft recommends that it is not used.
Performance Point Configuration
This Interface does not support Performance Points.
I/O Rate Tag Configuration
An I/O Rate point can be configured to receive 10-minute averages of the total number of exceptions per minute that are sent to PI by the interface. An exception is a value that has passed the exception specifications for a given PI point. Since 10-minute averages are taken, the first average is not written to PI until 10 minutes after the interface has started. One I/O Rate tag can be configured for each copy of the interface that is in use.
Monitoring I/O Rates on the Interface Node
The 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook.
Configuring I/O Rate Tags with PI ICU (Windows)
The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and managing I/O Rate Tags.
[pic]
PI ICU currently allows for one I/O Rate tag to be configured for each copy of the interface that is in use. Some interfaces allow for multiple I/O Rate tags.
Enable IORates for this Interface
The Enable IORates for this interface check box enables or disables IORates for the current interface. To disable IORates for the selected interface, uncheck this box. To enable IORates for the selected interface, check this box.
Tag Status
The Tag Status column indicates whether the IORates tag exists in PI. The possible states are:
• Created – This status indicates that the tag exist in PI
• Not Created – This status indicates that the tag does not yet exist in PI
• Deleted – This status indicates that the tag has just been deleted
• Unknown – This status indicates that the ICU is not able to access the PI Server
In File
The In File column indicates whether the IORates tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are:
• Yes – This status indicates that the tag name and event counter are in the IORates.dat file
• No – This status indicates that the tag name and event counter are not in the IORates.dat file
Event Counter
The Event Counter correlates a tag specified in the iorates.dat file with this copy of the interface. The command line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the IORates tag.
Snapshot
The Snapshot column holds the snapshot value of the IORates tag, if the IORates tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the interface is first loaded.
Button Menu Options
Create
Create the suggested I/O Rates point with the tag name indicated in the Tagname column.
Delete
Delete the I/O Rate point listed in the Tagname column.
Reset
Change the value in the Tagname text box back to the default value.
Rename
Allow the user to specify a new name for the I/O Rate point listed in the Tagname column.
Add to File
Add the I/O Rate point and the event counter number to the IORates.dat file.
Search [pic]
Allow the user to search the PI Server a previously defined I/O Rate points.
Update Snapshot [pic]
Allow the user to refresh the snapshot value.
Configuring IORates Tags Manually
There are two configuration steps for configuring an IORates tag manually.
1. Configuring the PI Point on the PI Server
2. Configuration on the Interface Node
Configuring the PI Point on the PI Server
Create an I/O Rate Tag with the following point attribute values.
|Attribute |Value |
|PointSource |L |
|PointType |float32 |
|Compressing |0 |
|ExcDev |0 |
The default settings can be used for the remaining PI Point attributes.
When Compressing is set to Zero, the I/O Rate Tag acts like a heartbeat tag for the interface, which can be examined easily in PI ProcessBook with markers turned on. If a value is not written to the I/O Rate Tag every 10 minutes, there is problem with the interface communication.
Configuration on the Interface Node
For the following examples, assume that the name of the PI tag is batfile001, and that the name of the I/O Rate on the home node is batfile001.
1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the %windir% directory. If both are specified, the PIPCSHARE entry takes precedence.
Since the PIHOME directory is typically C:\PIPC, the full name of the iorates.dat file will typically be C:\PIPC\dat\iorates.dat.
Add a line in the iorates.dat file of the form:
batfile001, x
where batfile001 is the name of the I/O Rate Tag and x corresponds to the /ec=x parameter in the startup command file. X can be any number between 1 and 34 or between 51 and 200, inclusive. However, it is best to use an event counter, x, that is not equal to 1 because 1 is the default event counter for the interface.
To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x, should be unique for each copy of the interface.
2. Set the /ec=x parameter on the startup command file of the interface to match the event counter in the iorates.dat file.
3. The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started.
Data File Format
Data Files
The Batch File Data records consist of PI Tagname or Alias, timestamp, and value. Optionally, there can be a digital ordinal number in the fourth field and a questionable bit in the fifth field.
There are several configuration options for the data file format. These are described in detail below. Edit the batchfl.bat file to configure the format.
The data file cannot be larger than 2GB due to the limitations of the call to open the data file for processing.
Field One – Required
The first field may use any one of the 3 possibilities below. It will be consistent in each data file for each instance of the interface.
Tag Name
This is the PI Tag.
Point Number
The PI point number can be used instead of a tagname by using the command line parameter /tn.
Alias
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. 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.
Delimiter – Required
The delimiter between the fields defaults to a comma ‘,’ Passing a command line parameter of /fs= can change this.
Field Two – Required
The time of the data may be either in absolute time or in seconds since 1970 in local time.
Time Stamp
The time stamp is in the form dd-mmm-yyyy hh:mm:ss or dd-mmm-yy hh:mm:ss (two-character year). When connected to a PI 3.1 or higher server, the timestamp can have sub-second data. E.g.: dd-mmm-yyyy hh:mm:ss.nnnn.
Seconds Since 1970
By passing a command line parameter of /ts, the number of seconds since 1970 in local time will be expected in the time field. This can also be a sub-second time. Ex: 90009009.1255
Seconds Since 1970 (UTC)
By passing a command line parameter of /tsu, the number of seconds since 1970 in UTC time will be expected in the time field. This can also be a sub-second time. Ex: 90009009.1255
Field Three – Required
The value field can be any appropriate numeric type, a digital state string, or a string for string type points available on PI 3 servers.
Note: The numeric type can be an exponential expression (without spaces).
Field Four – Optional
There can be a digital ordinal number (0,1,2,,,) in the fourth field. A value in the ordinal field will take precedence over any value in the value field according to the rules below.
• Ordinal values of 0 through X for non-digital points will result in the system digital state corresponding to the negative of the ordinal being written to the points. However, a value of 0 for Real or Integer type points is not valid and will be ignored.
• Ordinal values of 0 through X for Digital points specify the offset into the point’s digital state set that will be written to the point.
• Ordinal values of –1 through –X specify the system digital state to be written to the point.
Field Five – Optional
A questionable bit is in the fifth field. 1 for questionable bit being set, 0 for not set. Questionable indicates that there is some reason to doubt the accuracy of the value. The functions in the extended PI_API give programmers access to these parameters through a separate parameter labeled parameters.
Example File
The following is an example of a data file:
au1311.01,29-May-1998 07 :00 :25.21,234.3,,1
au1321.01,29-May-1998 08 :00 :26.1,2.3,,1
au1331.01,29-May-1998 08 :30 :00,34.3,,1
au1301.01,29-May-1998 07:30:00,BAD DATA
au1302.01,29-May-1998 07:00:50,ON,1,0
au1303.01,29-May-1998 07:00:00,OFF
au1304.01,29-May-1998 17:00:00,RUNNING
au1305.01,29-May-1998 17:00:00,Value has exceeded high limit
Startup Command File
Command-line parameters can begin with a / or with a -. For example, the /ps=M and –ps=M command-line parameters are equivalent.
Command file names have a .bat extension. The Windows continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters.
Note: The PI ICU BatchFL Control is the preferred method of managing the startup file on Windows. The information below may be used as a more detailed reference.
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 (BatchFL.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file. The procedure below describes the necessary steps for using PI ICU to configure the Batch File Interface.
From the PI ICU menu, select Interface, then NewWindows Interface Instance from EXE..., and then Browse to the BatchFL.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 batchfl. If not, use the drop-down box to change the Interface Type to be batchfl.
Click on Apply to enable the PI ICU to manage this copy of the Batch File Interface.
[pic]
The next step is to make selections in the interface-specific tab (i.e. “batchfl”) that allow you to enter values for the startup parameters that are particular to the Batch File Interface.
[pic]
Since the Batch File Interface is not a UniInt-based interface, the UniInt, Perf Points, and Perf Counters tabs are grayed out.
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 batchfl 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.
batchfl Interface page
Since the startup file of the Batch File Interface is maintained automatically by the PI ICU, use the batchfl 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.
batchfl
[pic]
The batchfl control for PI ICU has five sections. Yellow indicates that an invalid value has been entered, or that a required value has not been entered.
Data Files
Path
Specifies the path pointing to the directory where the Batch File Interface data files can be found. (/PA=path + mask)
Mask
Specifies the data file mask. Processed files will have 999 added to the file name. Do not make data files with 999 at the end of the name. They will be ignored and purged.
NOTE: The interface will process data files that match the first 3 characters after the dot. For example a mask of *.dat will return all data files with a .dat , .dat_ , .datxxx.
Purge Files Older Than
Specifies the age of processed data files to be deleted. In this example, processed data files older than 2 days are deleted. (/PU=xxx)
Pause time between files
Specifies the number of seconds to pause between processing files. This can be used to throttle the rate that the data files get processed. (/SL=xxx)
Input Data File Format
Field Separator
Specifies the field separator between tagname and timestamp, and timestamp and value. This is an optional parameter. If not specified a comma(‘,’) is used. (/FS=x)
Use Alias Tag
Alias tag in point field instead of PI tag name. Looks in the PI tag’s extended descriptor or instrument tag field for matches with the alias tag in the data.
E indicates extended descriptor has alias tag name
I indicates instrument tag field has alias tag name.
Anything else will cause the interface to HALT after writing an error message. (/AS=E or I)
Use Tag Number Instead of Name
Specifies that the data line has a tag number instead of the tagname. If not specified, the tagname is used. (/TN)
Timestamps
PI string time format
Data files specify timestamps in standard PI Time format: dd-mmm-yy hh:mm:ss. No command line parameter is required, as this is the default behavior.
Seconds since 1970 (local time)
Data files specify timestamps in number of seconds since 1970 (local time) in time field instead of time string. (/TS)
Seconds since 1970 (UTC time)
Data files specify timestamps in number of seconds since 1970 in UTC time in time field instead of time string. (/TSU)
Data Handling
Replace Existing PI Archive Events
Uses putlabvalue so data can be replaced. Default is putsnapshot. Extended API supported so string tags and sub-second timestamps are supported. (/LB)
Note: PI 3.2 SR1 server or higher and PI API 1.3.0 or higher are required to support string tags and sub-second timestamps.
Perform Exception Reporting
Uses pisendexceptions instead of putsnapshotsx. Supports extended API, so string tags and sub-second timestamps are supported. (/EX)
Note: PI 3.2 SR1 server or higher and PI API 1.3.0 or higher are required to support string tags and sub-second timestamps.
Enable Data Scaling (userreal1)
With version 2.6 or higher, scaling can be performed on the data. If you put a /sc in the startup .bat 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. (/SC)
Allow out-of-order data
This switch will allow out of order data and is overridden by the /LB switch. (/OO)
Read Before Overwrite
This mode of operation will do an archive read first to see if the value exists to determine if piar_putvalue is used to replace the value or pisn_putsnapshot is no value is to be replaced. This will only generate an audit event when a value is replaced. (/RBO)
Remove leading/trailing blanks from string values
The mode of operation will remove any leading or trailing blanks from string type values before sending the string to PI.
Adjust Timestamps By
Specifies the number of minutes to adjust the timestamp, i.e.: 60 will add 60 minutes to the timestamp in the data file. –60 will subtract 60 minutes from the timestamp in the data file. (/TA=+-xxx)
Enable Point Creation
When the interface read a data line and cannot find the PI Point, the interface will make the PI SDK calls to create the point. 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 Digital State Set used. The interface supports Digital, Int16, Int32, Float16, Float32, Float64 and String type points.
If the PointType is digital then the Digital State 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. (/PT=PointType)
Debug Flags
Debug Enabled
The Debug Enabled check box is used to turn on debug messaging. (/DB)
Verbose Debug Enabled
The Verbose Debug Enabled check box is used to turn on verbose and detailed debug messaging. (/DEV)
Additional Parameters
The Additional Parameter section is provided for any new command line parameters which the ICU does not currently support. Any command line parameters enter here must be separated by a blank and any arguments to a command line parameter that contains imbedded blanks must be enclosed in double quotes.
Command-line Parameters
|Parameter |Description |
|/as=E or I |Alias tag in point field instead of PI tag name. Looks in the PI tag’s Extended |
|Optional |Descriptor or InstrumentTag field for matches with the alias tag in the data. |
| |E indicates extended descriptor has alias tag name. |
| |I indicates instrument tag field has alias tag name. |
| |Anything else will cause the interface to HALT after writing an error message. |
|/db |Specifies that debug messages be written to the log files. |
|Optional | |
|/dev |Specifies that more detailed debug messages should be written to the log file. |
|Optional | |
|/ds= digstate |To be used with the /pt parameter. |
|Optional |If the PointType is digital then the Digital State 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. |
|/ec |The /ec parameter on the command line is used to specify a counter number, x, for an |
|or |I/O Rate point. If x is not specified, then the default event counter is 1. Also, if |
|/ec=x |the /ec parameter is not specified at all, there is still a default event counter of 1|
|Optional |associated with the interface. If there is an I/O Rate point that is associated with |
| |an event counter of 1, each copy of the interface that is running without /ec=x |
| |explicitly defined will write to the same I/O Rate point. This means that one should |
| |either explicitly define an event counter other than 1 for each copy of the interface |
| |or one should not associate any I/O Rate points with event counter 1. Configuration of|
| |I/O Rate points is discussed in the section called “I/O Rate Tag Configuration.” |
|/ex |Use pisendexceptions instead of putsnapshotsx. Supports extended API, so string tags |
|Optional |and sub-second timestamps are supported. Out of order data is rejected and error |
| |messages written in this mode. If a /lb or a /ex is not passed, the default is |
| |putsnapshot and out of order data will be rejected and error messages will be written |
| |to the pipc.log file unless the /oo parameter is entered. |
| |Note: PI 3.2 SR1 server or higher and PI API 1.3.0 or higher are required to support |
| |string tags and sub-second timestamps. |
|/f=SS |The /f parameter specifies the cycle time, in seconds for the checking for data files.|
|Required | |
|/fs=x |The /fs parameter specifies the field separator between tagname and timestamp, and |
|Optional, |timestamp and value. This is an optional parameter. If not specified a comma (‘,’) is |
|default: |used. |
|/fs=, | |
|/host=host:port |The /host parameter is used to specify the PI Home node. Host is the IP address of |
|Required |the PI Sever node or the domain name of the PI Server node. Port is the port number |
| |for TCP/IP communication. The port is always 5450 for a PI 3 Server. It is recommended|
| |to explicitly define the host and port on the command line with the /host parameter. |
| |Nevertheless, if either the host or port is not specified, the interface will attempt |
| |to use defaults. |
| |Defaults: |
| |The default port name and server name is specified in the pilogin.ini or piclient.ini |
| |file. The piclient.ini file is ignored if a pilogin.ini file is found. Refer to the PI|
| |API Installation Instructions manual for more information on the piclient.ini and |
| |pilogin.ini files. |
| |Examples: |
| |The interface is running on an API node, the domain name of the PI 3 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 identifier. For example, |
|Optional |/id=int1 |
| |The interface identifier is a string that is no longer than 9 characters in length. |
| |The interface concatenates this string to the header that is used to identify error |
| |messages as belonging to a particular interface. |
| |No identifier will be used if the /id= is not passed. |
|/lb |Use putlabvalue so data can be replaced. Default is putsnapshot. Extended API is |
|Optional |supported so string tags and sub-second timestamps are supported. Out of order data is|
| |accepted in this mode. If a /lb or a /ex is not passed, the default is putsnapshot |
| |and out of order data will be rejected and error messages will be written , unless |
| |the /oo parameter is entered. |
| |Note: PI 3.2 SR1 server or higher and PI API 1.3.0 or higher are required to support |
| |string tags and sub-second timestamps. |
|/maxstoptime= |When a Windows service is stopped, the service control manager spawns a new thread for|
|stoptime |the exit handler. The exit handler sets the “keep going” parameter for the interface |
|Optional |to false and then waits a maximum of stoptime seconds for the main thread to reach a |
| |safe exit point before the exit handler continues with its cleanup operations. By |
| |default, stoptime is 120 seconds. If stoptime seconds are exceeded, the exit handler |
| |will continue with its cleanup operations and then force the interface to exit. |
|/oo |Enable data to be entered out of order. Default is not to allow out-of-order data. |
|Optional |/lb will allow out of order data regardless of whether the /oo parameter is passed. |
|/pa=x:\x\x\mask |/pa=x:\x\x\mask specifies the full path to the data files and mask. i.e.: |
|Required |/pa=d:\datafiles\*.dat |
| |If the path has a space in it, put double quotes at the beginning and end of the |
| |parameter. i.e.: “/pa=d:\program files\batchfl\data\*.dat” |
| |Processed files will have 999 added to the file name. Do not make data files with 999 |
| |at the end of the name. They will be ignored and purged. |
|/ps=x |The /ps parameter specifies the point source for the interface. X is not case |
|Optional |sensitive and can be any single character. For example, /ps=L and /ps=l are |
| |equivalent. |
| |The point source that is assigned with the /ps parameter corresponds to the |
| |PointSource attribute of individual PI Points. The interface will attempt to send data|
| |only those PI points with the appropriate point source. It is not a required |
| |parameter, but recommended. |
|/pt= |When the interface read a data line and cannot find the PI Point, the interface will |
|Optional |make the PI SDK calls to create the point. 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 Digital State Set used. The interface supports Digital, Int16, Int32, Float16, |
| |Float32, Float64 and String type points. |
| |If the PointType is digital then the Digital State 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. |
|/pu=-xx |Specifies the age of processed data files to be deleted. Ex: /pu=-2d data files older |
|Optional |than 2 days are deleted. |
|/rb |This mode of operation will remove leading and trailing blanks for String type values.|
|Optional | |
|/rbo |This mode of operation will do an archive read first to see if the value exists to |
|Optional |determine if piar_putvalue is used to replace the value or pisn_putsnapshot if no |
| |value is to be replaced. This will only generate an audit event when a value is |
| |replaced. |
|/sc |With Batch File Interface version 2.6 or higher, scaling can be performed on the data.|
|Optional |If /sc is in the startup .bat 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 equals 0.0. |
|/sl=xx |Specifies the number of seconds to pause between processing files. This can be used to|
|Optional |throttle the rate that the data files get processed. |
|/stopstat |If the /stopstat parameter is present on the startup command line, then the |
|or |digital state Intf Shut will be written to each PI Point when the interface is |
|/stopstat= |stopped. |
|digstate |If /stopstat=digstate is present on the command line, then the digital state, |
|default: |digstate, will be written to each PI Point when the interface is stopped. For a PI 3 |
|/stopstat= |Server, digstate must be in the system digital state table. |
|”Intf Shut” |If neither /stopstat nor /stopstat=digstate is specified on the command line, then no |
|Optional |digital states will be written when the interface is shut down. |
| |Examples: |
| |/stopstat=”Intf Shut” |
| |The entire parameter is enclosed within double quotes when there is a space in |
| |digstate. |
|/ta=xx |Specifies the number of minutes to adjust the timestamp, i.e.: /ta=60 will add |
|Optional |60 minutes to the timestamp in the data file. /ta=-60 will subtract 60 minutes from |
| |the timestamp in the data file. |
|/tn |Specifies that the data line has a tag number instead of the tagname. If not |
|Optional |specified, the tagname is used. |
|/ts |Use number of seconds since 1970 (local time) in time field instead of time string. |
|Optional | |
|/tsu |Use number of seconds since 1970 (UTC) in time field instead of time string. |
|Optional | |
Informational Parameters
These are command-line parameters that must appear on the command line by themselves. Interface execution terminates immediately after these tasks are performed.
|Parameter |Description |
|/h |Print a summary of command line options supported by the interface. |
|Optional | |
|/help |In addition to printing the summary of command line options from the /h flag, print a |
|Optional |summary of command-line options for installing, removing, and starting a Windows |
| |service. |
|/? |On Windows, /? is the same as the /help flag. |
|Optional |On all other platforms /? is the same as /h. |
|/v |Print the version of the PI API and the interface |
|Optional | |
Sample batchfl.bat File
The following is a manually generated Windows sample startup file.
REM ================================================================
REM BatchFL.bat.new
REM
REM Sample startup file for the Batch File Interface to the PI System
REM
REM OSIsoft strongly recommends using PI ICU to modify startup files.
REM ================================================================
REM
REM
REM Sample command line
REM ================================================================
batchfl /f=15 /pa=d:\batchfl\dat\*.dat /pu=-1d /ps=B /host=XXXXXX:5450
REM
REM end of BatchFL.bat
Interface Node Clock
Make sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,
[pic]
In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,
C:> set
Make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.
Security
Windows
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 that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.
See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.
If the interface cannot write data to the PI Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Server, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.
PI Server v3.3 and 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 on Windows
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 a service, it can be started from PI ICU, the services control panel or with the command:
BatchFL.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 the status of the interface service. Even if the message indicates that the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons, and one typical reason is that the service is not able to find the command-line parameters in the associated .bat file. Verify that the root name of the .bat file and the .exe file are the same, and that the .bat file and the .exe file are in the same directory. Further troubleshooting of services might require consulting the pipc.log file, Windows Event Viewer, or other sources of log messages. See the section “Appendix A: Error and Informational Messages,” for additional information.
Stopping Interface Running as a Service
If the interface was installed a service, it can be stopped at any time from PI ICU, the services control panel or with the command:
BatchFL.exe –stop
The service can be removed by:
BatchFL.exe –remove
To stop the interface service with PI ICU, use the [pic] button on the PI ICU toolbar.
Buffering
Buffering refers to an Interface Node's ability to temporarily store the data that interfaces collect and to forward these data to the appropriate PI Servers. OSIsoft strongly recommends that you enable buffering on your Interface Nodes. Otherwise, if the Interface Node stops communicating with the PI Server, you lose the data that your interfaces collect.
The PI SDK installation kit installs two buffering applications: the PI Buffer Subsystem (PIBufss) and the PI API Buffer Server (Bufserv). PIBufss and Bufserv are mutually exclusive; that is, on a particular computer, you can run only one of them at any given time.
If you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering, but OSIsoft recommends that you run PIBufss instead.)
Which Buffering Application to Use
You should use PIBufss whenever possible because it offers better throughput than Bufserv. In addition, if the interfaces on an Interface Node are sending data to a PI Collective, PIBufss guarantees identical data in the archive records of all the PI Servers that are part of that collective.
You can use PIBufss only under the following conditions:
• the PI Server version is at least 3.4.375.x; and
• all of the interfaces running on the Interface Node send data to the same PI Server or to the same PI Collective.
If any of the following scenarios apply, you must use Bufserv:
• the PI Server version is earlier than 3.4.375.x; or
• the Interface node runs multiple interfaces, and these interfaces send data to multiple PI Servers that are not part of a single PI Collective.
If an Interface Node runs multiple interfaces, and these interfaces send data to two or more PI Collectives, then neither PIBufss nor Bufserv is appropriate. The reason is that PIBufss and Bufserv can buffer data only to a single collective. If you need to buffer to more than one PI Collective, you need to use two or more Interface Nodes to run your interfaces.
It is technically possible to run Bufserv on the PI Server Node. However, OSIsoft does not recommend this configuration.
How Buffering Works
A complete technical description of PIBufss and Bufserv is beyond the scope of this document. However, the following paragraphs provide some insights on how buffering works.
When an Interface Node has Buffering enabled, the buffering application (PIBufss or Bufserv) connects to the PI Server. It also creates shared memory storage.
When an interface program makes a PI API function call that writes data to the PI Server (for example, pisn_sendexceptionqx()), the PI API checks whether buffering is enabled. If it is, these data writing functions do not send the interface data to the PI Server. Instead, they write the data to the shared memory storage that the buffering application created.
The buffering application (either Bufserv or PIBufss) in turn
• reads the data in shared memory, and
• if a connection to the PI Server exists, sends the data to the PI Server; or
• if there is no connection to the PI Server, continues to store the data in shared memory (if shared memory storage is available) or writes the data to disk (if shared memory storage is full).
When the buffering application re-establishes connection to the PI Server, it writes to the PI Server the interface data contained in both shared memory storage and disk.
(Before sending data to the PI Server, PIBufss performs further tasks such data validation and data compression, but the description of these tasks is beyond the scope of this document.)
When PIBufss writes interface data to disk, it writes to multiple files. The names of these buffering files are PIBUFQ_*.DAT.
When Bufserv writes interface data to disk, it writes to a single file. The name of its buffering file is APIBUF.DAT.
As a previous paragraph indicates, PIBufss and Bufserv create shared memory storage at startup. These memory buffers must be large enough to accommodate the data that an interface collects during a single scan. Otherwise, the interface may fail to write all its collected data to the memory buffers, resulting in data loss. The buffering configuration section of this chapter provides guidelines for sizing these memory buffers.
When buffering is enabled, it affects the entire Interface Node. That is, you do not have a scenario whereby the buffering application buffers data for one interface running on an Interface Node but not for another interface running on the same Interface Node.
Buffering and PI Server Security
After you enable buffering, it is the buffering application—and not the interface program—that writes data to the PI Server. If the PI Server's trust table contains a trust entry that allows all applications on an Interface Node to write data, then the buffering application is able write data to the PI Server.
However, if the PI Server contains an interface-specific PI Trust entry that allows a particular interface program to write data, you must have a PI Trust entry specific to buffering. The following are the appropriate entries for the Application Name field of a PI Trust entry:
|Buffering Application |Application Name field for PI Trust |
|PI Buffer Subsystem |PIBufss.exe |
|PI API Buffer Server |APIBE (if the PI API is using 4 character process names) |
| |APIBUF (if the PI API is using 8 character process names) |
To use a process name greater than 4 characters in length for a trust application name, use the LONGAPPNAME=1 in the PIClient.ini file.
Enabling Buffering on an Interface Node with the ICU
The ICU allows you to select either PIBufss or Bufserv as the buffering application for your Interface Node. Run the ICU and select Tools > Buffering.
Choose Buffer Type
[pic]
To select PIBufss as the buffering application, choose Enable buffering with PI Buffer Subsystem.
To select Bufserv as the buffering application, choose Enable buffering with API Buffer Server.
If a warning message such as the following appears, click Yes.
[pic]
Buffering Settings
There are a number of settings that affect the operation of PIBuffss and Bufserv. The Buffering Settings section allows you to set these parameters. If you do not enter values for these parameters, PIBuffss and Bufserv use default values.
PIBufss
For PIBuffss, the paragraphs below describe the settings that may require user intervention. Please contact OSIsoft Technical Support for assistance in further optimizing these and all remaining settings.
[pic]
Primary and Secondary Memory Buffer Size (Bytes)
This is a key parameter for buffering performance. The sum of these two memory buffer sizes must be large enough to accommodate the data that an interface collects during a single scan. A typical event with a Float32 point type requires about 25 bytes. If an interface writes data to 5,000 points, it can potentially send 125,000 bytes (25 * 5000) of data in one scan. As a result, the size of each memory buffer should be 62,500 bytes.
The default value of these memory buffers is 32,768 bytes.
Send rate (milliseconds)
Send rate is the time in milliseconds that PIBufss waits between sending up to the Maximum transfer objects (described below) to the PI Server. The default value is 100. The valid range is 0 to 2,000,000.
Maximum transfer objects
Maximum transfer objects is the maximum number of events that PIBufss sends between each Send rate pause. The default value is 500. The valid range is 1 to 2,000,000.
Event Queue File Size (MBytes)
This is the size of the event queue files. PIBufss stores the buffered data to these files. The default value is 32. The range is 8 to 131072 (8 to 128 Gbytes). Please see the section entitled, “Queue File Sizing” in the pibufss.chm file for details on how to appropriately size the event queue files.
Event Queue Path
This is the location of the event queue file. The default value is [PIHOME]\DAT.
For optimal performance and reliability, OSIsoft recommends that you place the PIBufss event queue files on a different drive/controller from the system drive and the drive with the Windows paging file. (By default, these two drives are the same.)
Bufserv
For Bufserv, the paragraphs below describe the settings that may require user intervention. Please contact OSIsoft Technical Support for assistance in further optimizing these and all remaining settings.
[pic]
Maximum buffer file size (KB)
This is the maximum size of the buffer file ([PIHOME]\DAT\APIBUF.DAT). When Bufserv cannot communicate with the PI Server, it writes and appends data to this file. When the buffer file reaches this maximum size, Bufserv discards data.
The default value is 2,000,000 KB, which is about 2 GB. The range is from 1 to 2,000,000.
Primary and Secondary Memory Buffer Size (Bytes)
This is a key parameter for buffering performance. The sum of these two memory buffer sizes must be large enough to accommodate the data that an interface collects during a single scan. A typical event with a Float32 point type requires about 25 bytes. If an interface writes data to 5,000 points, it can potentially send 125,000 bytes (25 * 5000) of data in one scan. As a result, the size of each memory buffer should be 62,500 bytes.
The default value of these memory buffers is 32,768 bytes.
Send rate (milliseconds)
Send rate is the time in milliseconds that Bufserv waits between sending up to the Maximum transfer objects (described below) to the PI Server. The default value is 100. The valid range is 0 to 2,000,000.
Maximum transfer objects
Max transfer objects is the maximum number of events that Buferv sends between each Send rate pause. The default value is 500. The valid range is 1 to 2,000,000.
Buffered Servers
The Buffered Servers section allows you to define the PI Servers or PI Collective that the buffering application writes data.
PIBufss
PIBufss buffers data only to a single PI Server or a PI Collective. Select the PI Server or the PI Collective from the Buffering to collective/server drop down list box.
The following screen shows that PIBufss is configured to write data to a standalone PI Server named starlight. Notice that the Replicate data to all collective member nodes check box is disabled because this PI Server is not part of a collective. (PIBufss automatically detects whether a PI Server is part of a collective.)
[pic]
The following screen shows that PIBufss is configured to write data to a PI Collective named admiral. By default, PIBufss replicates data to all collective members. That is, it provides n-way buffering.
You can override this option by not checking the Replicate data to all collective member nodes check box. Then, uncheck (or check) the PI Server collective members as desired.
[pic]
Bufserv
Bufserv buffers data to a standalone PI Server, or to multiple standalone PI Servers. (If you want to buffer to multiple PI Servers that are part of a PI Collective, you should use PIBufss.)
If the PI Server to which you want Buferv to buffer data is not in the Server list, enter its name in the Add a server box and click the Add Server button. This PI Server name must be identical to the API Hostname entry:
[pic]
The following screen shows that Bufserv is configured to write to a standalone PI Server named etamp390. You use this configuration when all the interfaces on the Interface Node write data to etamp390.
[pic]
The following screen shows that Bufserv is configured to write to two standalone PI Servers, one named etamp390 and the other one named starlight. You use this configuration when some of the interfaces on the Interface Node write data to etamp390 and some write to starlight.
[pic]
Installing Buffering as a Service
Both the PIBufss and Bufserv applications run as a Service.
PI Buffer Subsystem Service
Use the PI Buffer Subsystem Service page to configure PIBufss as a Service. This page also allows you to start and stop the PIBufss service.
PIBufss does not require the logon rights of the local administrator account. It is sufficient to use the LocalSystem account instead. Although the screen below shows asterisks for the LocalSystem password, this account does not have a password.
[pic]
[pic]
API Buffer Server Service
Use the API Buffer Server Service page to configure Bufserv as a Service. This page also allows you to start and stop the Bufserv Service
Bufserv version 1.6 and later does not require the logon rights of the local administrator account. It is sufficient to use the LocalSystem account instead. Although the screen below shows asterisks for the LocalSystem password, this account does not have a password.
[pic]
Appendix A:
Error and Informational Messages
A string NameID is pre-pended to error messages written to the message log. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id parameter on the startup command line.
Message Logs
The location of the message log depends upon the platform on which the interface is running. See the UniInt End User Document for more information.
Messages are written to PIHOME\dat\pipc.log at the following times.
• When the interface starts many informational messages are written to the log. These include the version of the interface, the version of UniInt, the command-line parameters used, and the number of points.
• As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.
• If the /db is used on the command line, then various informational messages are written to the log file.
• For invalid parameters and defaults used.
• The number of points found for the BATCHFL interface.
• When a file has not been processed for more than 24 hours.
• When a file has been processed and the last file that has been processed was done more than 24 hours ago.
• When more than one point is found for a record.
• When a Digital state is not found.
• When a PI Point is not found for data.
• For an error when putting a Lab Value in the archive.
• = message written with data record and file name.
They are only written to BATCHFL.out for data errors. One message per data file is written to the PI message log with the number of data errors found and the name of the data file.
If the PI Point is not found, only one error message is written in BATCHFL.out.
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:
\PI\adm\pidiag –e error_number
Revision History
|Date |Author |Comments |
|05-Jun-96 |MGrace |Initial draft |
|23-July-96 |MGrace |Revised for NT platform |
|12-Sep-96 |MGrace |Revised for Unix platforms |
|23-Sep-96 |JZeilenga |Added tar –xv command for UNIX platforms |
|21-Nov-96 |MGrace |Revised for running as a NT service |
|25-Jun-97 |SRG |Minor formatting changes. |
|11-Dec-97 |MGrace |Combine vms and nt/unix documents and update nt/unix part to |
| | |version 1.5 |
|14-Feb-98 |JZeilenga |Added info for installing VMS interface from tape |
|17-Jul-98 |MGrace |Add /lb startup parameter for nt/unix. Change installation for NT |
| | |to use new service install commands. Version 1.6.6 |
|23-Oct-98 |MGrace |Add new startup parameters for NT/UNIX. Version 1.8.x |
|7-Dec-98 |MGrace |Add /tsu startup parameter |
|23-Jul-99 |MGrace |Version 2.1.0 on NT or UNIX for new API calls that support |
| | |replacing string data and sub-second data with the /lb parameter. |
|29-Feb-00 |MGrace |New features for alias tag (match extended descriptor or |
| | |Instrument tag field) for NT or Unix Version 2.3 |
|6-Mar-00 |MGrace |Support extended API call for exception reporting /ex. |
|2-May-00 |CGoodell |Standardize format |
|9-June-00 |MGrace |Add description for /sl parameter and adding lanworkstation as a |
| | |dependency for when data is on a mapped drive. NT/Unix version |
| | |2.4.x |
|18-Sept-00 |JMP |Updated manual to skeleton 1.02 |
|10-Oct-00 |JMP |Updated manual to skeleton 1.03; eliminated index |
|17-Nov-00 |MGrace |Updated manual for nt/unix version 2.6 or higher. Added a /sc to |
| | |allow for scaling data |
|21-Nov-00 |MGrace |Update manual for nt/unix version 2.7 or higher. Added a /id= |
| | |parameter for putting in error messages for identifying what |
| | |interface the messages are coming from. |
|8-Dec-00 |MGrace |Add description about how out of order data is rejected |
|6-Mar-01 |MGrace |Take out comma in install lanworkstation dependency |
|04-Jul-01 |HBeeson |Added BatchFL ICU Control section. |
|22-Aug-01 |MGrace |Clean up, clear up what is in VMS version. Fix startup table. Add|
| | |/oo startup parameter. |
|22-Aug-01 |CGoodell |Formatting |
|05-Sep-01 |HBeeson |Updated section on ICU Control |
|25-Sep-01 |CGoodell |Continued reformatting; skeleton 1.09 |
|4-Oct-01 |MGrace |Fixed typo in point source section |
|12-Feb-02 |MGrace |Fix section on starting as a service and accessing a mapped drive.|
| | |Need to depend on workstation, not lanworkstation. |
|26-Aug-02 |MGrace |Add /stopstat and /maxstoptime parameters to NT/UNIX startup |
| | |section |
|06-Sep-02 |HBeeson |Updated with info the Wise setup kit, updated sections on PI ICU |
| | |for IORates, PerfPoints, Service Config (2.8.x, doc rev D) |
|18-Sep-02 |CGoodell |Fixed headers & footers, and title for printing |
|20-Sep-02 |MGrace |Add /pa=x parameter to chart of startup params |
|13-Jun-03 |CGoodell |Changed the versions; fixed footers |
|03-Dec-03 |HBeeson |Added a note on multiple instances to the ICU control section |
|4-Feb-05 |MGrace |Add MPK comments |
|10-Mar-05 |MGrace |Pli#7653OSI8 -> limitations for the mask. |
| | |Pli# 6955OSI8 -> note about exponential expressions supported. |
|11-Mar-05 |MGrace |Add /rb startup parameter. |
|18-Apr-05 |MKelly |Change Copyright page for dates and company name. Added three |
| | |missing support features from latest skeleton manual, Add section |
| | |in point sources about PINet and PI 3 having to use uppercase |
| | |point source character. Updated I/O Rates section. Updated ICU |
| | |section with new screen shots for updated ICU. |
|25-Apr-05 |CGoodell |Version 2.10.1.0 Rev I: Title page only includes NT because all |
| | |others are on maintenance. |
|18-Aug-06 |MGrace | Update version number and batchfl.bat example |
|23-Aug-06 |Janelle |Version 2.10.2.0 Rev A: Updated manual to skeleton 2.5.2. Fixed |
| | |headers and footers; alphabetized command line parameters table; |
| | |formatting changes. Removed references to UNIX and VAX because |
| | |those versions of the interface are now only on maintenance; |
| | |updated hardware diagram. |
|29-Aug-06 |MKelly |Version 2.10.2.0 Rev B: Fixed headers and footer, page setup |
| | |margins, corrected filenames and other minor formatting. |
|6-Sep-06 |MGrace |Version 2.10.2.0 Rev C: Add /v /h /help information |
|6-Dec-06 |MGrace |Update the principles of operation to include point creation. |
| | |Update the table to say PI SDK is used when point creation is |
| | |enabled. |
|7-Nov-07 |MGrace |Version 2.10.2.0 Rev D: The /f parameter description was changed |
| | |during the release procedure to use the UniInt behavior of the /f |
| | |parameter. This interface is not UniInt based. The /f parameter |
| | |only supports seconds. |
|4-Apr-08 |MGrace |Version 2.11.1.0: |
| | |Pli# 13635OSI8 data file size is limited to 2GB |
| | |Pli# 16960OSI8 Support service id |
|9-Apr-08 |Janelle |Version 2.11.1.0, Revision A: updated headers, removed NT 4 as |
| | |supported operating system, updated IORates section, update ICU |
| | |control screen shots |
|30-Jul-08 |MGrace |Version 2.11.1.0, Revision B: Put in the buffering section from |
| | |the Interface skeleton. This interface should use buffering due |
| | |to potential data loss before the interface discovers the PI |
| | |Server connection is down. |
-----------------------
Status of the ICU
Service installed or uninstalled
Status of the Interface Service
................
................
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 searches
- windows batch file environment variable
- batch file user input variable
- batch file get input
- batch file environment variables path
- batch file ask for user input
- batch file commands user input
- batch file prompt input
- batch file ask for input
- batch file programming
- batch file input
- windows 10 batch file commands
- batch file tutorial pdf