PI Batch File Interface (NT, VAX and UNIX)
BatchFile NT
Interface to the PI System
Version 2.10.1.0
Rev I
How to Contact Us
|Phone |(510) 297-5800 (main number) |
| |(510) 297-5828 (technical support) |
|Fax |(510) 357-8136 |
|E-mail |techsupport@ |
|World Wide Web | |
|Mail |OSIsoft |OSI Software, Ltd |
| |P.O. Box 727 |P O Box 8256 |
| |San Leandro, CA 94577-0427 |Symonds Street |
| |USA |Auckland 1035 New Zealand |
| | | |
| |OSI Software GmbH |OSI Software, Asia Pte Ltd |
| |Hauptstra(e 30 |152 Beach Road |
| |D-63674 Altenstadt 1 |#09-06 Gateway East |
| |Deutschland |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. HP-UX 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
Table of Contents
Introduction 1
Reference Manuals 1
Supported Features 1
Principles of Operation 3
Installation Checklist 5
Interface Installation on NT 7
Naming Conventions and Requirements 7
Interface Directories 7
The PIHOME Directory Tree 7
Interface Installation Directory 8
Interface Installation Procedure 8
Installing the Interface as an NT Service 8
Installing the Interface Service with PI-Interface Configuration Utility 8
Installing the Interface Service Manually 11
Interface Installation on UNIX 13
Naming Conventions and Requirements 13
Interface Directories 13
The PIHOME Directory 13
Interface Installation Directory 14
Interface Installation Procedure 14
Interface Installation on VMS 15
Naming Conventions and Requirements 15
Interface Installation Procedure 15
Digital States 17
PointSource 19
PI Point Configuration 21
Point Attributes 21
Tag 21
PointSource 21
PointType 21
Location1 21
Location2 21
Location3 22
Location4 22
Location5 22
InstrumentTag 22
ExDesc 22
Scan 22
UserReal1 22
Shutdown 22
I/O Rate Tag Configuration 25
Monitoring I/O Rates on the Interface Node 25
Configuring I/O Rate Tags with PI-ICU (NT-Intel) 25
Configuring IORates Tags Manually 26
Configuring the PI Point on the PI Server 27
Configuration on the Interface Node 27
Data File Format 31
NT and UNIX Data Files 31
Startup Command File 35
Configuring the Interface with PI-ICU 35
batchfl Interface Tab 37
Command-line Parameters for NT and UNIX 41
Sample File for NT 45
Sample batchfl.sh File for Unix 46
Command-line Parameters for VMS 48
Sample File for VMS 48
Interface Node Clock 49
NT 49
UNIX 49
VMS 49
Security 51
NT and UNIX 51
VMS 51
Starting / Stopping the Interface on NT 53
Starting / Stopping the Interface with PI-ICU 53
Starting / Stopping the Interface Manually 53
Starting Interface as a Service 53
Stopping Interface Running as a Service 54
Starting / Stopping the Interface on UNIX 55
Command-Line Syntax for Background Processes 55
Terminating Background Processes 55
Anomalous Background Job Termination 56
Starting / Stopping the Interface on VMS 57
Starting a Detached Process 57
Stopping the Interface 59
Appendix A: Error and Informational Messages 61
Message Logs 61
System Errors and PI Errors 61
Revision History 63
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.
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 /lb and /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 1024 characters. 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 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).
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.
Interface Installation on NT
OSI 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. 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 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
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:
[pic]
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 [pic]
To add a dependency from the list of Installed Services, select the dependency name, and click the Add button.
Remove [pic]
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.
Start or Stop Service
To Start or Stop the interface service, use the Start button [pic] and the Stop button [pic] on the toolbar at the top of the PI-ICU. 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 the Interface Service Manually
If PI-ICU is not used to configure and control the interface service, the following describes the steps to manually configure and control the interface service.
Change to the directory where the batchfl1.exe executable is located. Then, consult the following table to determine the appropriate service installation command.
|NT Service Installation Commands on a PI-API node or a PI Server node |
|without Bufserv implemented |
|Manual service |Batchfl1.exe –install –depend tcpip |
|Automatic service |Batchfl1.exe –install –auto –depend tcpip |
|Interface reading from a mapped drive |
|Manual service |batchfl –install –depend “tcpip workstation” |
|Automatic service |batchfl –install –auto –depend “tcpip workstation” |
When the interface is installed as a service on the PI Server node and when Bufserv is not implemented, a dependency on the PI network manager is not necessary because the interface will repeatedly attempt to connect to the PI Server until it is successful.
Check the Microsoft Windows NT services control panel to verify that the service was added successfully. One can use the services control panel at any time to change the interface from an automatic service to a manual service or vice versa.
Interface Installation on UNIX
One of the first issues that must be resolved is where the interface should be installed. Should the interface be installed on the PI Server node or on a remote PI-API node? OSIsoft recommends that the interface be installed on a remote PI-API node. The primary function of the server node is to archive data and to service the clients that request that data. The PI Server should not need to compete with interfaces for the machine’s resources. If the interface is installed on a remote PI-API node, then the PI-API must be installed on that node before the interface is installed. Refer to the PI-API Installation Instructions manual.
If the interface is installed on the PI Server node, the advantage of using Bufserv is diminished because it is no longer needed to protect against network failures. Bufserv would still allow data to be collected when the PI Server is brought down for routine maintenance, but one must weigh this advantage against the additional load that Bufserv incurs on the server. Typically, users do not choose to run Bufserv on the PI Server node. If Bufserv is used on the server node, one must make sure that Bufserv is started before any interfaces by the startup script for PI.
If the interface is installed on a server node, the interface should be configured to start and stop in conjunction with the PI Server. If the interface is installed on a PI-API node, then the interface should be configured to start and stop with the PI-API. Site-specific scripts can be edited for this purpose, as described in the installation procedure below. The PI Server and the PI-API, in turn, can be configured to start and stop automatically when the system is shut down or rebooted. Procedures for automatic startup and shutdown of PI or the PI-API are platform specific. The automation procedures are discussed in the PI System Management chapter of the PI Data Archive manual.
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.sh.
Note: UNIX does not enforce file-naming conventions, and it is possible that the file name extensions for the actual interface executable and command files are different than .exe and .sh, or it is possible that the file extensions are eliminated entirely.
In order to run multiple copies of the interface from the same directory, it is necessary to rename the executable and the command file. It is customary to use batchfl1.exe and batchfl1.sh for interface number 1, batchfl2.exe and batchfl2.sh for interface number 2, and so on.
Interface Directories
The PIHOME Directory
PIHOME is an environment variable that points to the base directory where the PI-API is installed. The setting of environment variables is discussed in the PI-API Installation Instructions manual.
Interface Installation Directory
There are two conventions for the installation directory. The first convention is to place all copies of the interface into a single directory. If this convention is followed, it is recommended to place batchfl1, batchfl2, batchfl3, etc., in the directory:
$PIHOME\interfaces\batchfl\
The second convention is to create a separate interface directory for each copy of the interface. If this convention is followed, it is recommended to place batchfl1, batchfl2, batchfl3, etc., in the directories:
$PIHOME\interfaces\batchfl1\
$PIHOME\interfaces\batchfl2\
$PIHOME\interfaces\batchfl3\
and so on.
Create the installation directories as necessary.
Interface Installation Procedure
In the installation procedure below, it is assumed that interface number 1 is being installed and that all copies of the interface will be installed in the same directory. To install another copy of the interface, repeat the following procedure with batchfl# used in place of batchfl1, where # is the interface number between 1 and 99.
1. Copy the interface files to $PIHOME\interfaces\batchfl\. Create the directory if necessary.
2. If necessary, rename the executable and command files to batchfl1.exe and batchfl1.sh. The executable and command file should have the same root name.
3. Alter the command-line arguments in the batchfl1.sh file as discussed in the section “Startup Command File.”
4. Try to start the interface as a foreground process. Follow the instructions in the next two sections to configure the command file and start the interface. It is advantageous to begin with foreground processes because the procedure for starting and stopping foreground processes is easier than for background processes. Once the interface is successfully running as a foreground process, one can try to run the interface in the background by following the appropriate instructions in the section “Starting and Stopping the Interface.”
Interface Installation on VMS
One of the first issues that must be resolved is where the interface should be installed. Should the interface be installed on the PI Server node or on a remote PINet node? OSIsoft recommends that the interface be installed on a PINet node. The primary function of the server node is to archive data and to service clients that request data. The PI Server should not need to compete with interfaces for the machine’s resources. Refer to the PI 2.x Installation and Upgrade Handbook for installation instructions.
A PINet node can communicate to either a PI 2 Server or a PI 3 Server. If the interface runs on a PI 2 Server, the interface can only communicate to that PI 2 Server.
On a PINet node, PISysExe, PISysMgr, and PISysDat are all aliases for the PINet directory, and PIBuild is an alias for the PINetBuild directory.
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the interface executable is called batchfl.exe, the startup command file for interactive processes is called , and the startup command file for detached processes is called .
Install the interface executable and command files in the PISysExe directory. If multiple instances of the interface must be run as interactive or detached processes, create multiply copies of the file. For this purpose, it is customary to copy the file to for instance 1, to for instance 2, and so on. The individual command files then need to be edited separately as appropriate.
Regardless of how many instances of the interface are running as interactive or detached processes, only one batchfl.exe file and one file are needed.
When the interface is run as a detached process, interface-specific log files are created in the PISysExe directory. The interface log files are .out, .log, or .txt. The log files typically have names similar to batchfl1.out, batchfl2.out, and so on.
Note: The interface will always write error and informational messages to the PISysMgr:PIMessLog.txt file.
Interface Installation Procedure
Interface files are installed and linked automatically as part of PI or PINet installations. If the interface has been automatically installed, skip to the “Starting / Stopping the Interface” section. Sometimes, however, an interface needs to be installed or upgraded separately from the PI or PINet installation. This procedure is frequently done when the available version of the interface is newer than that which is included with the PI or PINet distribution.
Interface files for VMS-based interfaces are now distributed on CD-ROM readable by NT or Windows machines. The appropriate files must be transferred over the network to the VMS node. The following files are distributed.
|Distribution Files |
|batchfl.DOC |Interface manual (Microsoft Word Document). The interface-specific |
| |installation procedure is in this manual. |
|Batchfl.BCK |Saveset containing the interface files. |
|Batchfl_version#.TXT |Release notes. |
|REBLOCK.README |Readme file for REBLOCK.EXE. |
|REBLOCK.EXE |The interface backup saveset must be reblocked before the saveset can be |
| |unpacked. See the REBLOCK.README. |
The following procedure is typical.
1. Transfer batchfl.BCK and REBLOCK.EXE to the VMS node by some sort of binary file transfer mechanism. For example, one could use binary ftp. Copy the files to a safe directory, one that will not be overwritten during an upgrade of PI or PINet.
2. Run REBLOCK.EXE on the batchfl.BCK file. Reblock corrects the block size of the batchfl.BCK file, which is altered during the binary file transfer. Binary file transfer does not affect the block size of the reblock executable itself. An example reblock session is given below.
|$ run reblock |
|REBLOCK: Convert file to blocksize 32256 |
| |
|Filename (“\” to exit): batchfl.bck |
|Filename (“\” to exit): \ |
3. Unpack the saveset by using the backup command:
backup/log/verify batchfl.bck/sav *.*
4. Install the interface files with the command:
@batchfllink
The command file links the interface executable. Files similar to the following are typically installed.
|PIBuild Directory |
|batchfl.OBJ |Object file for the interface. |
| |Command procedure for linking the executable. |
|PISysExe Directory |
|batchfl.EXE |Interface executable. |
| |Startup command file for interactive processes. |
| |Startup command file for detached processes (the command-line |
| |arguments are still defined in the file). |
Digital States
For more information regarding Digital States, refer to the PI Data Archive Manuals.
PI 2 Home Node
Digital states are defined by running the Digtl Stat display from the PI menu. The states must be contiguous for each status type and may be anywhere within the Digital State Table outside of the range 193 – 320, which is reserved for OSIsoft. The digital states need to be defined prior to point configuration. The digital state sets described in the PI 3 sections below should be entered into the PI 2 Digital State Table.
For more information, see the DA manual.
PI 3 Home Node
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 Data Archive Manual for Windows NT and Unix 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 argument.
Case-sensitivity for PointSource Attributes
If the interface is running on a PINet node and the Server node is a PI 3 system, use a capital letter (or a case-insensitive character such as a number, a question mark, etc.) for the PointSource attribute when defining points. For all other scenarios, one does not need to be careful with the case of the PointSource.
In all cases, the point source character that is supplied with the /ps command-line argument 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.
PI 2 Server Nodes
The following point source characters are reserved on PI 2 systems and cannot be used as the point source character for an interface: C, ?, @, Q, T. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.
Before a PI point with a given point source can be created, the point source character must be added to the PI 2 point source table. For example, if point source B is not defined in the PI 2 point source table, a point with a point source of B cannot be created. This prevents the user from accidentally creating a point with an incorrect point source character.
Defining a Point Source Character in the PI 2 Point Source Table
1. Enter PI by typing the following command from a VMS command prompt:
@pisysexe:pi
2. Select the PointSrc option from the menu.
3. Select New from the menu.
4. Assign a point source next to the Code: field. Also, assign minimum and maximum values for the Location1 to Location5 attributes.
| |Location1 |Location2 |Location3 |Location4 |Location5 |
|Minimum |-20000000 |-20000000 |-20000000 |-20000000 |-20000000 |
|Maximum |20000000 |20000000 |20000000 |20000000 |20000000 |
5. Select “Save” from the menu.
PI 3 Server Nodes
No point source table exists on a PI 3 Server, which means that points can be immediately created on PI 3 with any point source character. Several subsystems and applications that ship with PI 3 are associated with default point source characters. The Totalizer Subsystem uses the point source character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Either do not use these point source characters or change the default point source characters for these applications. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of Lab. Therefore, it would be confusing to use Lab as the point source character for 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.
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.
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.
PI 2 Server Nodes
Scaled real, full-precision real, integer, and digital point types are supported on PI 2 Servers. For more information on the individual point types, refer to the Data Archive (DA) section of PI System Manual I.
UNIX or NT 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 Data Archive for NT and UNIX. For String values to be replaced, you must have a PI Server 3.2 SR1 or higher and PI-API version 1.3.0 or higher.
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
For a PI 2 server, the instrument tag attribute is limited to 32 characters. For a PI 3 server, the instrument tag is limited to 32 characters.
When using the Alias Tag command line argument (/as = E or I) on NT or UNIX, 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
This is the extended descriptor attribute. For a PI 2 server, the extended descriptor is limited to 80 characters. For a PI 3 server, the extended descriptor is limited to 80 characters.
When using the Alias Tag command line argument (/as = E or I) on NT and UNIX, 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 version 2.6 or higher on NT and UNIX, 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.
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.
PI 2 Server Nodes
The Shutdown attribute is not used if the server node is a PI 2 system. For information on configuring shutdown events for PI 2, see Data Archive (DA) section 4.2.3 of PI System Manual I.
PI 3 Server Nodes
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 Data Archive for NT and UNIX.
To disable SHUTDOWN events from being written to PI when PI is restarted, set the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the PI Shutdown Subsystem 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 Data Archive for NT and UNIX.
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 backup.
If you do have bufserv running, data files will continue to be processed when the connection to the PIServer is down, but will stop processing data files when batchfl needs information from the PIServer. The most likely information needed would be translating strings to digital codes for digital tags.
Since bufserv is not necessary for this interface, it is not recommended that you use it.
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
For NT and UNIX nodes, the 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook. For Open VMS nodes, the rate (events/minute) can be monitored with the PISysExe:IOMonitor.exe program or with another client program such as Process Book. The IOMonitor program is discussed on page DA-71 of PI System Manual I.
Configuring I/O Rate Tags with PI-ICU (NT-Intel)
The PI-Interface Configuration Utility (PI-ICU) provides a user interface for creating and managing IORates Tags. This can only be done on PI 3.3 and above home nodes.
[pic]
The right mouse menu provides options for creating, deleting, renaming, and searching for an existing IORates Tag.
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.
Right Mouse Button Menu Options
Create
Create the suggested IORates tag with the tag name indicated in the Tagname column.
Delete
Delete the IORates tag listed in the Tagname column.
Rename
Allows the user to specify a new name for the IORates tag listed in the Tagname column.
Add to File
Adds the tag to the IORates.dat file with the event counter listed in the Event Counter Column.
Search
Allows the user to search the PI Server for a previously defined IORates tag.
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
PI 2 Server Nodes
A listing of the I/O Rate Tags that are currently being monitored can be found in the file PISysDat:IORates.dat or they can be obtained with the command:
@PISysDat:
Create an I/O Rate Tag using one of the existing I/O Rate Tags as a template.
PI 3 Server Nodes
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.
NT Nodes
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 \WinNT 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 flag 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 flag 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.
UNIX Nodes
1. Edit/Create a file called iorates.dat in the $PIHOME\dat directory. PIHOME is an environment variable that is set equal to the PI home directory name as discussed in the PI-API Installation Instructions manual.
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 flag 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 flag on the startup command file of the interface to match the event counter in the iorates.dat file.
3. The I/O Rate shared memory server and the I/O Rate monitor program must be stopped and started for the changes to take effect. The easiest way to do this is to run the pistop and pistart command scripts with the following commands:
sh $PIHOME/bin/pistop
nohup sh $PIHOME/bin/pistart
One can determine that the shared memory server and the I/O Rate monitor are running with the commands:
Ps –ef | grep ioshmsrv
Ps –ef | grep iorates
Open VMS Nodes
I/O Rates are discussed on page DA-59 of PI System Manual I.
To implement an I/O Rate tag, perform the following steps.
1. Add a line to the PISysDat:IORates.dat file of the form:
batfile001, x
where x corresponds to the event counter specified in the startup command file of the interface. 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. The event counter should be unique for each copy of the interface. The PISysDat:IORates.dat file must be edited on the node where the interface is running. That is, if the interface is running on a PINet node, then the PISysDat:IORates.dat file on the PINet node must be edited, not the PISysDat:IORates.dat file on the home node.
2. Set the event counter number in the startup command file of the interface to match the event counter in the PISysDat:IORates.dat file.
3. Stop and start the I/O Rates process with the following commands so that the changes take effect:
@PISysExe:stop iorates
@PISysExe:
1. Data File Format
NT and UNIX Data Files
The BatchFile 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 options for the data file format described in the section Startup for NT and UNIX. Edit the batchfl.bat file for NT or batchfl.sh file for UNIX to configure the format.
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 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. 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 flags through a separate argument labeled flags.
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 arguments can begin with a / or with a -. For example, the /ps=M and –ps=M command-line arguments are equivalent.
Notes for NT
For NT, command file names have a .bat extension. The NT 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 flags is unlimited, and the maximum length of each flag is 1024 characters.
Note: The PI-ICU BatchFL Control is the preferred method of managing the startup file on NT. The information below may be used as a more detailed reference.
Notes for UNIX
For UNIX, command file names typically have a .sh extension, but UNIX does not enforce file-naming conventions. The backslash (\) continuation character allows one to use multiple lines for the startup command. There is no limit to the command-line length and there is no limit to the number or length of the command line parameters.
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 BatchFile Interface.
From the PI-ICU menu, select Interface, New, 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.
You should then see a display such as the following:
[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, if you want the interface to communicate with a remote PI Server, you can do this by selecting ‘Connections…’ item from PI-ICU menu and make it your default server. If you do not see the remote node in the list of servers, you can add that in.
Once you add the interface 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 BatchFile 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 BatchFile Interface.
[pic]
Since the BatchFile Interface is not a UniInt-based interface, the Uniint, Perf Points, and Perf Counters tabs are grayed out.
If you want to set up the interface as a Windows Service, you can do that by using the Service tab. This tab allows you to configure the interface to run as a service as well as to start and stop the interface. You can also run the interface 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. In the next section we will describe the selections that are available from the batchfl tab. After you have made your selections on the PI-ICU GUI, you will need to press the Apply button in order for PI-ICU to make these changes to the interface’s startup file.
Batchfl Interface Tab
Since the startup file of the BatchFile Interface is maintained automatically by the PI-ICU, you should use the batchfl tab to configure the startup parameters and 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 (/PA=path + mask)
Specifies the path pointing to the directory where the Batch File interface data files can be found.
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 (/PU=xxx)
Specifies the age of processed data files to be deleted. In this example, processed data files older than 2 days are deleted.
Pause time between files (/SL=xxx)
Specifies the number of seconds to pause between processing files. This can be used to throttle the rate that the data files get processed.
Input Data File Format
Field Separator (/FS=x)
Specifies the field separator between tagname and timestamp, and timestamp and value. This is an optional parameter. If not specified a comma(‘,’) is used.
Use Alias Tag (/AS=E or I)
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.
Use Tag Number Instead of Name (/TN)
Specifies that the data line has a tag number instead of the tagname. If not specified, the tagname is used.
Timestamps
• PI string time format
Data files specify timestamps in standard PI Time format: dd-mm-yy hh:mm:ss. No command line parameter is required, as this is the default behavior.
• Seconds since 1970 (local time) (/TS)
Data files specify timestamps in number of seconds since 1970 (local time) in time field instead of time string.
• Seconds since 1970 (UTC time) (/TSU)
Data files specify timestamps in number of seconds since 1970 in UTC time in time field instead of time string.
Data Handling
Replace Existing PI Archive Events (/LB)
Uses putlabvalue so data can be replaced. Default is putsnapshot. Extended API supported so string tags and sub-second timestamps are supported.
Note: You must have a PI 3.2 SR1 or higher server and PI-API 1.3.0 or higher to support string tags and sub-second timestamps.
Perform Exception Reporting (/EX)
Uses pisendexceptions instead of putsnapshotsx. Supports extended API, so string tags and sub-second timestamps are supported.
Note: You must have a PI 3.2 SR1 or higher server and PI-API 1.3.0 or higher to support string tags and sub-second timestamps.
Enable Data Scaling (userreal1) (/SC)
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.
Allow out-of-order data (/OO)
This switch will allow out of order data and is overridden by the /LB switch.
Read Before Overwrite (/RBO)
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.
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 (/TA=+-xxx)
Specifies the number of minutes to adjust the timestamp, ie: 60 will add 60 minutes to the timestamp in the data file. –60 will subtract 60 minutes from the timestamp in the data file.
Enable Point Creation (/PT=PointType)
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.
Debug Flags
Debug Enabled (/DB)
The Debug Enabled check box is used to turn on debug messaging.
Verbose Debug Enabled (/DEV)
The Verbose Debug Enabled check box is used to turn on verbose and detailed debug messaging.
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 for NT and UNIX
|Parameter |Description |
|/ps=x |The /ps flag specifies the point source for the interface. X is not case sensitive and|
|Optional |can be any single character. For example, /ps=L and /ps=l are equivalent. |
| |The point source that is assigned with the /ps flag 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. |
|/f=SS |The /f flag specifies the cycle time, in seconds for the checking for data files. |
|Required | |
|/host=host:port |The /host flag is used to specify the PI Home node. Host is the IP address of the PI |
|Optional |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, and 545 for a PI 2 |
| |Server. It is recommended to explicitly define the host and port on the command line |
| |with the /host flag. 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 flags would be: |
| |/host=marvin |
| |/host=marvin:5450 |
| |/host=206.79.198.30 |
| |/host=206.79.198.30:5450 |
|/pa=x:\x\x\mask |/pa=x:\x\x\mask specifies the full path to the data files and mask. Ie: |
|Required |/pa=d:\datafiles\*.dat |
| |If the path has a space in it, put double quotes at the beginning and end of the |
| |parameter. Ie: “/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. |
| |Note: For Unix, the data file mask only supports asterisk (*) |
|/ec |The /ec flag on the command line is used to specify a counter number, x, for an I/O |
|or |Rate point. If x is not specified, then the default event counter is 1. Also, if the |
|/ec=x |/ec flag 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,” page |
| |25. |
|/fs=x |The /fs flag 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=, | |
|/id=x |The /id flag 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. |
|/pu=-xx |Specifies the age of processed data files to be deleted. Ex: /pu=-2d data files older |
|Optional |than 2 days are deleted. |
|/tn |Specifies that the data line has a tag number instead of the tagname. If not |
|Optional |specified, the tagname is used. |
|/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: You must have a PI 3.2 SR1 or higher server and PI-API 1.3.0 or higher to |
| |support string tags and sub-second timestamps. |
|/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 | |
|/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: You must have a PI 3.2 SR1 or higher server and PI-API 1.3.0 or higher to |
| |support string tags and sub-second timestamps. |
|/as=E or I |Alias tag in point field instead of PI tag name. Looks in the PI tag’s extended |
|Optional |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. |
|/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. |
|/sc |With version 2.6 or higher, scaling can be performed on the data. If you put a /sc in|
|Optional |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. |
|/ta=xx |Specifies the number of minutes to adjust the timestamp, ie: /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. |
|/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 flag is passed. |
|/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. |
|/pt= PiPointType |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. |
|/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. |
|/rb |This mode of operation will remove leading and trailing blanks for String type values.|
|Optional | |
|/stopstat |If the /stopstat flag is present on the startup command line, then the digital state |
|or |Intf Shut will be written to each PI Point when the interface is stopped. |
|/stopatat= |If /stopstat=digstate is present on the command line, then the digital state, |
|digstate |digstate, will be written to each PI Point when the interface is stopped. For a PI 3 |
|default: |Server, digstate must be in the system digital state table. For a PI 2 Server, where |
|/stopstat= |there is only one digital state table available, digstate must simply be somewhere in |
|”intf shut” |the table. The interface uses the first occurrence in the table. |
|Optional |If neither /stopstat nor /stopstat=digstate is specified on the command line, then no |
| |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. |
|/maxstoptime=stoptime |When an NT service is stopped, the service control manager spawns a new thread for the|
|Optional for NT |exit handler. The exit handler sets the “keep going” flag for the interface to false |
|not implemented for UNIX or |and then waits a maximum of stoptime seconds for the main thread to reach a safe exit |
|VMS |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. |
|/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 | |
Sample File for NT
The following is a manually generated NT sample startup file.
REM batchfl.bat
REM ============================================================================
REM This is a sample startup file to start the PI BatchFl interface.
REM You will need to modify the parameters for your interface.
REM
REM ----------------------------------------------------------------------------
REM this command procedure passes required /default parameters to
REM process batchfl.
REM
REM Required command-line parameters:
REM
REM /pa=path\mask - path and mask to data files
REM /f=ss - frequency in seconds to check for new data files
REM
REM Optional command-line parameters:
REM
REM /ps=c - point source character. Default is none.
REM /host=host:port - name of PI home node. Default is localhost:5450
REM /ec=# - I/O Rate counter
REM /fs=c - character to separate fields in data line.
REM default is “/fs=,” comma.
REM /id=x - a string identifier that is no longer than 9
REM characters in length. The interface concatenates
REM this string to the header that is used in error
REM messages. This will help identify which interface
REM the error messages are coming from. No identifier
REM will be use if the /id= is not passed.
REM /pu=xx - relative purge time to delete processed data files
REM (-Xh,-Xd,-Xm) (Default = -2d)
REM /tn - read point number instead of tag name in data line.
REM default is read tag name.
REM /lb - use putlabvalue instead of putsnapshot. Allows data
REM to be replaced default is to use putsnapshot.
REM /ts - time field is number of seconds since 1970 instead
REM of time string
REM /tsu - time field is number of seconds since 1970 in UTC
REM time.
REM /ex - use pi send exception instead of putsnapshots
REM /as=E or I - alias tag in point field instead of pi point.
REM E for alias tag in extended descriptor
REM I for alias tag in instrument tag field.
REM /sl=# - specify the number of seconds to pause between
REM processing files.
REM /sc scaling will be performed on the data. The
REM UserReal1 point attribute will be read and the value
REM will be multiplied by the value in the data file.
REM This is only for integer and real type points. No
REM scaling will be done if the UserReal1 value is equal
REM 0.0.
REM /ta=## - adjust the timestamp by + or – XX number of minutes.
REM /oo - enable data to be enterd out of order. Default is
REM not to allow out of order data. /lb will allow out
REM of order data regardless.
REM /rbo - This mode of operation will do an archive read first
REM to see if the value exists to determine if
REM piar_putvalue is used to replace the value or
REM pisn_putsnapshot if no value is to be replaced.
REM This will only generate an audit event when a value
REM is replaced.
REM /pt=pointtype - When the interface reads a data line and cannot find
REM the PI Point, the interface will make the PI-SDK
REM calls to create the point. Each instance of the
REM interface will only be able to create one type of
REM point, so multiple instances will need to be run.
REM One for each point type required. Digital type
REM points will also require an instance for each
REM Digital State Set used. The interface supports
REM Digital, Int16, Int32, Float16, Float32, Float64 and
REM String type points. If the PointType is digital then
REM the Digital State set name to be used with these new
REM points will have to be specified on the startup
REM command line. The /DS=DigitalSetName is the switch
REM for this purpose. The DigitalSetName will have to
REM be one of the digital set names found on the PI home
REM node that the interface is communicating with.
REM /ds=digstate - To be used with the /pt parameter.
REM If the PointType is digital then the Digital State
REM set name to be used with these new points will have
REM to be specified on the startup command line. The
REM /DS=DigitalSetName is the switch for this purpose.
REM The DigitalSetName will have to be one of the
REM digital set names found on the PI home node that the
REM interface is communicating with.
REM /rb - This mode of operation will remove leading and
REM trailing blanks for String type values.
REM /db - turns on additional debug messages
REM /dev - turns on more detailed debug messages
REM
REM run string needs a space between parameters, no spaces within
REM parameters unless double quote surround the argument.
REM
REM ======================================================================
..\interfaces\batchfl\batchfl /f=15 /pa=d:\batchfl\dat\*.dat /pu=-1d ^
/ps=B /host=dragon:5450
REM
REM end of batchfl.bat
Sample batchfl.sh File for Unix
The following is a UNIX example:
#
# @(#)batchfl.sh 1.0 07/29/96
#
#
# This command procedure passes required, default parameters to
# process batchfl.
#
#
# Required command-line parameters
# /f=ss Frequency in seconds to check for new data files
# /pa=path\mask Path and mask to data files
#
# Optional command-line parameters
# /ps=c Point source character. Default is none.
# /host=host:port Name of PI home node:port number
# Default is localhost:5450
# For a PI2 server, port is 545,
# For a PI3 server, port is 5450
# /ec=# I/O Rate counter
# /fs=c A character to separate fields in data line.
# Default is comma
# /id=x A character 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 use # if the /id= is not passed.
# /pu=xx Relative purge time to delete processed data
# files (-Xh,-Xd,-Xm) (Default = -2d)
# /tn Read point number instead of tag name in data line.
# Default is read tag name.
# /lb Use putlabvalue instead of putsnapshot. Allows data # to be replaced. Default is to use putsnapshot.
# /ts Time field is number of seconds since 1970 instead
# of time string.
# /tsu Time field is number of seconds since 1970 in UTC
# time.
# /ex Use pi send exception instead of putsnapshots.
# /as= E or I Alias tag in point field instead of pi point.
# E for alias tag in extended descriptor
# I for alias tag in instrument tag field.
# /sl=# Specify the number of seconds to pause between
# processing files.
# /sc Scaling will be performed on the data. 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.
# /ta=# Adjust the timestamp by + or – XX number of minutes.
# /oo Enable data to be enterd out of order. Default is
# NOT to allow out of order data. /lb will allow out
# of order data regardless.
# /db Turns on additional debug messages
# /dev Turns on more detailed debug messages
#
# Run string needs a space between arguments, no spaces within argument.
#
echo “Starting Batchfl Interface”
./batchfl /host=dragon:5450 /f=60 /pa=/usr/labdata/*.dat /pu=-1d \
/host=casaba > ../../log/batchfl.log 2>&1 &
Command-line Parameters for VMS
Notes for VMS
For VMS, command file names have a .com extension. The VMS continuation character (-) allows one to use multiple lines in the command file. However, the maximum number of characters in a single or multi-line command is 256 characters. That is, adding continuation characters may make the command file easier to read, but they do not extend the 256-character limitation. The 256-character limitation can be overcome by putting the arguments in a separate argument file.
When the interface is installed, the following parameters in this file should be adjusted.
|Parameter |Description |
|1 |Number of seconds to wait before checking for data files. If less than 1 minute, a default time of |
| |900 seconds will be used. |
|2 |Point source character of the points to search for. |
|3 |Path and mask of data files. Processed files will have 999 added to the end of the file name. Do not |
| |make data files with 999 at the end of the name, they will be ignored and purged. |
| |The path needs to be specified even if in the default dir. |
|4 |Event counter number should match that of a tag in PISysDat:IORates.dat. A range of 1 – 34, 51 – 200.|
| |Default of 20 is used if an invalid counter is specified. |
|5 |How long should processed files be kept after they have been processed? The format for time is |
| |relative format. For example, 2d will delete files 2 days after they were processed. The time must be|
| |in the past, or a default purge time of 2d will be used. |
Note: The parameters for the VMS version of this interface are order-dependent.
Sample File for VMS
You can adjust parameters by editing PISysExe::
$ ! 4/7/89 MMG
$ !
$ ! Command file to read values from a BATCHFL Interface File
$ ! The parameters for the BATCHFL.exe run string must
$ ! be entered in the order below:
$ ! 1 – frequency of check(secs) (300 = 5min)
$ ! 2 – Point source character
$ ! 3 – Path and mask of data files
$ ! 4 – Event counter number (1-34, 51-200)
$ ! 5 – Time for data files to be Purged
$ ! (dd-mmm-yy hh:mm:ss or – n d/h/m)
$ !
$ BATCHFL :== $PISysExe:BATCHFL.exe
$ BATCHFL 900 L [batchfl]*.dat 20 –2D
Interface Node Clock
NT
The correct settings for the time and time zone should be set in the Date/Time control panel. From this control panel, configure the time to be automatically adjusted for Daylight Savings Time for locations that use daylight savings time. The correct local settings should be used even if the interface node runs in a different time zone than the PI Server node.
Make sure that the TZ environment variable is not defined. The currently defined environment variables can be listed by going to Start | Settings | Control Panel, double clicking on the system icon, and selecting the environment tab on the resulting dialog box. Also, make sure that the TZ variable is not defined in an autoexec.bat file. When the TZ variable is defined in an autoexec.bat file, the TZ variable may not appear as being defined in the System control panel even though the variable is defined. Admittedly, autoexec.bat files are not typically used on NT, but this does not prevent a rogue user from creating such a file and defining the TZ variable unbeknownst to the System Administrator.
UNIX
The correct time and time zone must be configured on the interface node. Also, the interface node should be configured to automatically adjust for daylight savings time for locations that use daylight savings time. The correct local settings should be used even if the interface node runs in a different time zone than the PI Server node.
VMS
By default, the system time of a PINet node is synchronized with the system time on the PI Server node once every hour by the PINETSYNC program. Edit the PINet: file to alter he behavior of the PINETSYNC. The synchronization interval can be changed, a time offset between the PINet node and the server node can be applied, and/or time synchronization can be disabled. The command-line parameters for implementing these changes are described in the PINet: file itself.
Security
NT and UNIX
If the home node is a PI 3 Server, the PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Data Archive. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Data Archive Manual.
For PI 3.3 and above the PI Trust Table is used instead of the PI Firewall and Proxy Database.
If the home node is a PI 2 Server, the read/write permissions should be set appropriately in the pisysdat:piserver.dat file on the PI 2 home node. For more information on setting permissions on PI 2, see the pibuild:piserver.txt file on the PI 2 home node.
If the interface cannot write data to a PI 3 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 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.
VMS
If the interface runs on a PINet node and communicates to a PI 3 Server, make sure that the PI Firewall Database and the PI Proxy Database are configured so that the PINet node is allowed to write data to the Archive. For more information, see “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Data Archive manual.
For PI 3.3 and above the PI Trust Table is used instead of the PI Firewall and Proxy Database.
If the interface runs on a PINet node and communicates to a PI 2 Server, make sure that the PINet node has read/write permission to the PI 2 Archive by checking the configuration in the PISysDat:PIServer.dat file on the PI 2 home node. For more information on setting permissions on PI 2, see the PIBuild.PIServer.txt file on the PI 2 Server.
If the interface cannot write data to a PI 2 or PI 3 Server owing to permission problems, error –10401 will be written to the PISysMgr:PIMesslog.txt file.
Starting / Stopping the Interface on NT
This section describes starting and stopping the interface once it has been installed as a service.
Note: If your PI Home node is version 3.3 or greater, you should use the PI-ICU for interface administration.
Starting / Stopping the Interface with PI-ICU
The PI-ICU can be used to start and stop the interface service.
[pic]
To Start or Stop the interface service, use the Start button [pic] and the Stop button [pic] on the toolbar at the top of the PI-ICU. 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]
Starting / Stopping the Interface Manually
If PI-ICU is not used, then the following sections describe how to manage the interface service manually.
Starting Interface as a Service
If the interface was installed a service, it can be started from the services control panel or with the command:
batchfl.exe –start
A message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. Even if the message indicates that the service started successfully, make sure that the service is still running by checking in the services control panel. There are several reasons that a service may immediately terminate after startup. One is that the service may not be able to find the command-line arguments in the associated .bat file. For this to succeed, the root name of the .bat file and the .exe file must be the same, and the .bat file and the .exe file must be in the same directory. If the service terminates prematurely for whatever reason, no error messages will be echoed to the screen. The user must consult the pipc.log file for error messages. See the section “Appendix A: Error and Informational Messages.”
Stopping Interface Running as a Service
If the interface was installed a service, it can be stopped at any time from the services control panel or with the command:
batchfl.exe –stop
The service can be removed by:
batchfl.exe –remove
Starting / Stopping the Interface on UNIX
This section describes starting and stopping the interface as a background process.
Command-Line Syntax for Background Processes
Jobs that are run in the background remain in existence even after the user that has started the process has logged off of the system. The command line in the batchfl1.sh startup command file should begin with nohup and end with &. For example:
nohup batchfl1.exe program_arguments > batchfl1.log 2>&1 &
The & at the end of the command line causes the job to be launched in the background. The nohup at the beginning of the command line causes hang-ups and quits to be ignored. HPUX boxes are notorious for sending hang-up signals to jobs that a user has started when that user logs off. Always execute a background job with nohup, either by incorporating it into the startup command file of the interface or by typing nohup batchfl1.sh or nohup sh batchfl1.sh from the terminal. Unless the job is executed with nohup, the hang-up signal will cause the job to be terminated even if it is run in the background.
A job that is started with nohup will have its standard output redirected to the file nohup.out, unless the standard output is redirected to a different file name. On the command line above, the standard output is redirected with the > director to the file batchfl1.log.
The optional sequence 2>&1 causes the standard error to be redirected to standard output so that the standard error will also appear in batchfl1.log. System commands typically send error messages to the standard error. For example, the command:
cat nonexistentfile
fails with the error message “cat: cannot open nonexistent file: No such file or directory.” This error message is redirected to the standard error, which is normally seen on the screen.
Typically, messages that interfaces write to the standard output are also written to the $PIHOME/dat/pimesslogfile. To avoid this duplication, the user can redirect the standard output to the null device, which discards the messages. For example:
nohup batchfl1.exe program_arguments > /dev/null &
redirects the standard output to the null device. Initially, it is recommended to use the first command-line example, where the output is redirected to the batchfl1.log file.
Terminating Background Processes
First, obtain the process id (pid) of the background job. This is done as follows. First execute the command:
ps –ef | grep batchfl
which produces output similar to:
matzen 12788 12707 2 09:55:27 ttys1 0:00 batchfl1.exe /ps=B …
The second column is the pid of the process. That is, 12788 is the pid of the batchfl1.exe interface in the example above.
The process is then stopped by:
kill 12788
The kill command sends the SIGTERM signal to the interface, causing the exit handler to be invoked.
Unless it cannot be avoided, do NOT stop the interface with kill –9 pid. The option -9 causes the SIGKILL signal to be sent to the interface. The exit handler cannot catch this signal. SIGKILL will immediately terminate the process.
Anomalous Background Job Termination
On some platforms, processes that are started in the background will be terminated if one types “control-c” in the same window that the job was started in. If one closes the window in which the interface was started or if one logs off and logs back on, the user will not be able to accidentally terminate the job in this manner.
Starting / Stopping the Interface on VMS
This section describes starting and stopping the interface as a detached process.
Starting a Detached Process
The interface is started as a detached process with the command file. Typically, the file does not need to be edited, because the command-line parameters are edited in the associated batchfl#.com file. However, in some cases it may be necessary to edit the file to increase quotas such as the page file size. Detached processes continue running after the user who started the process logs off.
The following is an example of a file.
|$! 09-Apr-99 GWM OSI SOFTWARE, INC |
|$! |
|$! starts the batchfl interface as a detached |
|$! Process by detaching the command file batchfl#.com. |
|$! |
|$! The following parameters must be passed to : |
|$! 1 – interface number (1-99) |
|$ if (‘P1’ .eq. “”) then goto BadParameter |
|$! |
|$ if (f$search(“pisysexe:batchfl’’P1’.com”) .nes. “”) then goto Next |
|$ goto BadFile |
|$! |
|$ Next: |
|$ if (f$search(“pisysexe:batchfl’’P1’.out”) .nes. “”) then – |
|purge/keep=3 pisysexe:batchfl’P1’.out |
|$! |
|$ run/detach/uic=[system]/proc=”PI-IFC-‘’P1’”/priority=4 – |
|/input=pisysexe:batchfl’P1’.com – |
|/output=pisysexe:batchfl’P1’.out- |
|/working_set=512/maximum_work=1024/extent=2048 – |
|/pagefile=10000/buffer=20480 sys$system:loginout |
|$ exit |
|$! |
|$ BadParameter: |
|$ write sys$output “The Interface # Must Be Passed” |
|$ exit |
|$! |
|$ BadFile: |
|$ write sys$output “batchfl’’P1’.Com does NOT Exist...” |
|$ exit |
|$! End of File |
|$ |
Assuming that the example command file is used to start the interface, the following command will start instance 1 of the interface as a detached process:
@PISysExe:batchfldetach 1
The name of the process will be “PI-BATCHFL-1” as defined by the /proc flag to the run command in the above command file
The example command file performs the following tasks in the order listed.
1. The command file checks whether the interface number is passed as a command-line parameter to . If it is not passed, the command file will terminate with the error message:
The Interface # must be passed.
2. searches for the existence of the PISysExe: file, which is the file where the command-line parameters for the interface are set. If the file does not exist, the command file will terminate with the error message:
does not exist.
3. searches for the existence of the PISysExe:batchfl1.out interface-specific log file. If the file exits, the command file executes the purge command to eliminate all but the last three versions of this file.
4. The PI-BATCHFL-1 process is started with the run command. Several actions are performed by the run command:
• The name of the process is set to PI-BATCHFL-1 by the /proc flag.
• The UIC of the process is set to the system account by the /uic flag.
• The priority of the process is set to 4 by the /priority flag.
• The input command file for the process is set to PISysExe: by the /input flag.
• The standard output from the interface is redirected to the PISysExe:batchfl1.out file by the /output flag.
• The remaining parameters, /working_set, /maximum_work, /extent, /pagefile, and /buffer, are used to adjust the resources that are available to the interface.
Stopping the Interface
To stop the interface, issue the following command:
@PISysExe:stop PI-BATCHFL-1
Where 1 is the instance number of the process.
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 flag 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 (NT and Unix) or Pisysexe:BATCHFL.out (VMS) 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 NT
On NT, descriptions of system and PI errors can be obtained with the pidiag utility:
\PI\adm\pidiag –e error_number
Error Descriptions on VMS
On VMS, descriptions of system errors can be obtained with the exit command:
exit positive_error_number
1. Revision History
|Date |Author |Comments |
|05-Jun-96 |MMG |Initial draft |
|23-July-96 |MMG |Revised for NT platform |
|12-Sep-96 |MMG |Revised for Unix platforms |
|23-Sep-96 |JFZ |Added tar –xv command for UNIX platforms |
|21-Nov-96 |MMG |Revised for running as a NT service |
|25-Jun-97 |SRG |Minor formatting changes. |
|11-Dec-97 |MMG |Combine vms and nt/unix documents and update nt/unix part to |
| | |version 1.5 |
|14-Feb-98 |JFZ |Added info for installing VMS interface from tape |
|17-Jul-98 |MMG |Add /lb startup parameter for nt/unix. Change installation for NT |
| | |to use new service install commands. Version 1.6.6 |
|23-Oct-98 |MMG |Add new startup parameters for NT/UNIX. Version 1.8.x |
|7-Dec-98 |MMG |Add /tsu startup parameter |
|23-Jul-99 |MMG |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 |MMG |New features for alias tag (match extended descriptor or |
| | |Instrument tag field) for NT or Unix Version 2.3 |
|6-Mar-00 |MMG |Support extended API call for exception reporting /ex. |
|2-May-00 |CG |Standardize format |
|9-June-00 |MMG |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 |MMG |Updated manual for nt/unix version 2.6 or higher. Added a /sc to |
| | |allow for scaling data |
|21-Nov-00 |MMG |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 |MMG |Add description about how out of order data is rejected |
|6-Mar-01 |MMG |Take out comma in install lanworkstation dependency |
|04-Jul-01 |HAB |Added BatchFL ICU Control section. |
|22-Aug-01 |MMG |Clean up, clear up what is in VMS version. Fix startup table. Add|
| | |/oo startup parameter. |
|22-Aug-01 |CG |Formatting |
|05-Sep-01 |HAB |Updated section on ICU Control |
|25-Sep-01 |CG |Continued reformatting; skeleton 1.09 |
|4-Oct-01 |MMG |Fixed typo in point source section |
|12-Feb-02 |MMG |Fix section on starting as a service and accessing a mapped drive.|
| | |Need to depend on workstation, not lanworkstation. |
|26-Aug-02 |MMG |Add /stopstat and /maxstoptime parameters to NT/UNIX startup |
| | |section |
|06-Sep-02 |HAB |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 |CG |Fixed headers & footers, and title for printing |
|20-Sep-02 |MMG |Add /pa=x parameter to chart of startup params |
|13-Jun-03 |CG |Changed the versions; fixed footers |
|03-Dec-03 |HAB |Added a note on multiple instances to the ICU control section |
|4-Feb-05 |MMG |Add MPK comments |
|10-Mar-05 |MMG |Pli#7653OSI8 -> limitations for the mask. |
| | |Pli# 6955OSI8 -> note about exponential expressions supported. |
|11-Mar-05 |MMG |Add /rb startup parameter. |
|18-Apr-05 |MPK |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 |Chrys |Version 2.10.1.0 Rev I: Title page only includes NT because all |
| | |others are on maintenance. |
-----------------------
Status of the ICU
Status of the Interface Service
Status of the Interface Service
Service installed or uninstalled
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related download
Related searches
- 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