BatchFile NT
Interface to the PI System

Version 2.10.1.0

RevI

1

UniInt End-User Interface to the PI System

How to Contact Us

Phone / (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web /
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P O Box 8256
Symonds Street
Auckland 1035 New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721

Unpublished – rights reserved under the copyright laws of the United States.
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

Trademark statement—PI is a registered trademark of OSIsoft, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI_BatchFl.doc

 1999 – 2005 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577

1

UniInt End-User Interface to the PI System

Table of Contents

Introduction

Reference Manuals

Supported Features

Principles of Operation

Installation Checklist

Interface Installation on NT

Naming Conventions and Requirements

Interface Directories

The PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing the Interface as an NT Service

Installing the Interface Service with PI-Interface Configuration Utility

Installing the Interface Service Manually

Interface Installation on UNIX

Naming Conventions and Requirements

Interface Directories

The PIHOME Directory

Interface Installation Directory

Interface Installation Procedure

Interface Installation on VMS

Naming Conventions and Requirements

Interface Installation Procedure

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Scan

UserReal1

Shutdown

I/O Rate Tag Configuration

Monitoring I/O Rates on the Interface Node

Configuring I/O Rate Tags with PI-ICU (NT-Intel)

Configuring IORates Tags Manually

Configuring the PI Point on the PI Server

Configuration on the Interface Node

Data File Format

NT and UNIX Data Files

Startup Command File

Configuring the Interface with PI-ICU

batchfl Interface Tab

Command-line Parameters for NT and UNIX

Sample batchfl.com File for NT

Sample batchfl.sh File for Unix

Command-line Parameters for VMS

Sample BatchFL.com File for VMS

Interface Node Clock

NT

UNIX

VMS

Security

NT and UNIX

VMS

Starting / Stopping the Interface on NT

Starting / Stopping the Interface with PI-ICU

Starting / Stopping the Interface Manually

Starting Interface as a Service

Stopping Interface Running as a Service

Starting / Stopping the Interface on UNIX

Command-Line Syntax for Background Processes

Terminating Background Processes

Anomalous Background Job Termination

Starting / Stopping the Interface on VMS

Starting a Detached Process

Stopping the Interface

Appendix A: Error and Informational Messages

Message Logs

System Errors and PI Errors

Revision History

1

BatchFileNT, VAX and UNIX Interface to the PI System1

Introduction

The BatchFile 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 NT, UNIX and VMS platforms.

Reference Manuals

OSIsoft
  • PI Data Archive Manual
  • PI-API Installation Instructions
  • PI-ICUUserManual
  • UniInt End User Document

Supported Features

Feature / Support
Part Number / PI-IN-BF-LAB-AIX
PI-IN-BF-LAB-AXP
PI-IN-BF-LAB-DUX
PI-IN-BF-LAB-HP
PI-IN-BF-LAB-NTA
PI-IN-BF-LAB-NTI
PI-IN-BF-LAB-SOL
PI-IN-BF-LAB-VAX
Platforms / AIX / DUX / VAX VMS / Alpha VMS / NTI (4, 2000, XP) / NTA / SOL2
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / Float16 / Float32 / Float64 / Int16 / Int32 / Digital / String
Sub-second Timestamps / Yes – NT/UNIX only
Sub-second Scan Classes / No
Automatically Incorporates PI Point Attribute Changes / Yes – NT/UNIX only when /as is passed
Exception Reporting / Yes – NT/UNIX only when /ex is passed
Outputs from PI / No
History Recovery / No
Failover / No
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based
UniInt-based / No
Maximum Point Count / Unlimited
Uses PI-SDK / No
* Source of Timestamps / Vendor
Vendor Software Required on PI API / PINet node / 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.
Source of Timestamps

Each line of the input file includes the timestamp for the given data value.

1

BatchFileNT, VAX and UNIX 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.

For NT and UNIX versions, 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.

For VMS (VAX / Alpha), only putlabvalue (piar_putvalue) is used.

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 NT/Unix 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 argument is passed to allow out of order events.

On NT and UNIX, when using the Alias Tag command line argument (/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 ExtendedDescriptor. 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).

1

BatchFileNT, VAX and UNIX Interface to the PI System1

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps you get the BatchFile interface running. If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual in detail.

  1. Verify that the PI-API is installed. (On VMS, the PI-API is part of the PI Home node or of PINet.)
  2. Install the BatchFile interface.
  3. Create any needed digital states.
  4. Choose a point source. If PI 2 home node, create the point source.
  5. Configure PI Points.
  6. Configure I/O Rate Tag (for details see the section titled “I/O Rate Tag Configuration”).
  7. Edit startup command file or use the PI-ICU to configure the startup of the interface (for details, see the section titled “Startup Command File”).
  8. Set up security.
  9. Create a test input file.
  10. Start the interface without buffering.
  11. Verify data.

1

BatchFileNT, VAX and UNIX Interface to the PI System1

Interface Installation on NT

OSI 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 PIAPIInstallation 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. Bufserv may be used.

In most cases, interfaces on PI-API nodes should be installed as automatic services, except during the initial testing period, during which it is recommended that you run the interface interactively to simplify troubleshooting. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.

The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and interfaces as manual services that are launched by site-specific command files when the PI Server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI Server by site-specific command files. This typical scenario assumes that Bufserv is not enabled on the PI Server node.

The Batch File interface on Windows NT-Intel setup program for interface version 2.8.7 and later uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000. When running on Windows NT 4.0 systems, the Batch File setup program will install the Windows Installer itself if necessary. To install, run the BatchFL_x.x.x.exe installation kit.

Naming Conventions and Requirements

It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run unless using PI-ICU to configure the interface.. For example, one would typically use batchfl1.exe and batchfl1.bat 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 arguments 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 WinNT 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. OSI 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

To install, run the BatchFL_x.x.x.x.exe installation kit.

Run PI-ICU to configure the interface, or alter the command-line arguments 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, one will not be able to run the interface as a service. 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 an NT 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-Interface Configuration Utility

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

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

Log on as

This text box is available only when the service does not yet exist. It allows users to set what user account the interface service will use when they first create the interface service. If this text box is left blank when the service is created, then LocalSystem is used.

To edit the username after the service has been created, users need to use the Services Applet.

Password

This text box is available only when the service does not yet exist. If the username specified in the Log on as text box requires a password, this field is where the password should be typed. If no password is required, this field can remain blank.

To edit the password after the service has been created, users need to use the Services Applet.

Service Startup Type

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

Interface Dependencies

The Installed Services list is a list of the services currently installed on this machine. Services upon which this Interface is dependant should be moved into the Interface Dependencies list using the “Add>” 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. Often interface services also depend on a vendor program.

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

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

Add

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

Remove

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

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

Create or Remove Interface Service
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.