Batch File NT, VAX and UNIX



Batch File NT, VAX and UNIX

Interface to the PI System

VMS: version 1 and greater

NT and UNIX: version 2.4.x and greater

How to Contact Us

|Phone |(510) 297-5800 (main number) |

| |(510) 297-5828 (technical support) |

|Fax |(510) 357-8136 |

|Internet |techsupport@ |

|World Wide Web | |

|Bulletin Board |(510) 895-9423 |

| |Telebit WorldBlazer modem (Hayes, MNP, or PEP compatible) |

| |8 data bits, 1 stop bit, no parity, up to 14400 bps download |

| |protocols: Xmodem, Ymodem, Zmodem, Kermit |

|Mail |OSI Software, Inc. | |

| |P.O. Box 727 | |

| |San Leandro, CA 94577-0427 | |

| |USA | |

| | | |

| |OSI Software GmbH |OSI Software, Ltd |

| |Hauptstrabe 30 |P. O. Box 8256 |

| |D-63674 Altenstadt 1 |Level One, 6-8 Nugent Street |

| |Deutschland |Auckland 3, New Zealand |

Unpublished—rights reserved under the copyright laws of the United States.

RESTRICTED RIGHTSRESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph ©(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 OSI Software, 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.

batchfl.doc

Ó 2000 OSI Software, Inc. All rights reserved

777 Davis Street, Suite 250, San Leandro, CA 94577

Table of Contents

Introduction 1

PI Point Configuration 2

Tag 3

PointSource 3

PointType 4

ExcMin, ExcMax, ExcDev and ExcDevPercent 5

Compressing 6

CompDev, CompMin, CompMax, CompDevPercent 6

Scan 6

Zero, Span 7

TypicalValue 7

Shutdown 8

DigitalSet 8

DigStartCode and DigNumber 8

Data Files 9

VMS Data Files 9

NT and UNIX Data Files 9

Startup for NT and UNIX 12

Shutdown for NT and UNIX 17

Principles of Operation 2

Troubleshooting on NT and UNIX 18

Installation for NT and UNIX 19

Startup for VMS 22

Messages on VMS 24

Installation Checklist for VMS 25

Introduction

The Batchfl Interface:

• Processes data from files to a Plant Information (PI) System.

• Is designed to conform to the PI Instrument and Computer Interfacing Standard.

• Requires the PI-API.

• Runs on all platforms on which the PI-API is available; this includes the PI Data Archive platforms, including OpenVMS, NT, and UNIX, and PI clients.

This document applies to NT, UNIX and VMS platforms.

|Supported Features | |

|Platforms |VMS / VMS Alpha / NT-Intel / NT-Alpha / Unix |

|PI Point Types |Float16 / Float32 / Float64 / Int16 / Int32 / Digital |

| |/ String |

|Sub-second Timestamps |Yes |

|Sub-second Scan Classes | No |

|Automatically Incorporates PI Point Attribute Changes |Yes – on NT and UNIX in Alias Mode (/as) |

|Exception Reporting |Done by Interface 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 |

|SDK |No |

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

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 a PI Tagname does not exist, a single error message will be written to the log file.

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 up, the data files will then be processed. The record that was being read at the time of a communication failure will be reprocessed once communication has resumed.

Extended API calls for string tag support and sub-second data support are used by default if the PI server is a PI 3.1 or higher. The command line parameters /lb for piar_putvalue and /ex for pisn_sendexceptionqx support the extended API calls if the PI server is PI 3.2 SR1 or higher and PI-API 1.3.0 or higher. If both /lb and /ex are passed, /lb takes precedence.

The maximum tagname size is 255 characters. The maximum string value size is 1024 characters.

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 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 now supports checking for point updates when running in alias mode. It is imperative that the user pass 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.

PI Point Configuration

The PI point is the basic building block for controlling data flow to and from the PI Data Archive. Whereas a point in geometry has coordinates associated with it that define its position in space, a PI point has attributes associated with it that determine the source and destination of data, the means by which the data is transmitted, how the data is stored in PI, etc. A single point is configured for each measurement value that needs to be archived. For example, one would configure a single point to store temperature readings from a thermocouple. One would configure a second point to store temperature readings from a second thermocouple, and so on.

Configuration of these points is discussed below.

Tag

One will frequently see the word “point” and “tag” used interchangeably, but there is a difference. 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. For example, one may choose the letter L to identify points that belong to the Batch File interface. To implement this, one would set the Point Source attribute to L for every PI Point that is configured for the Batch File interface. Then, if one uses /ps=L 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 Point Source of L. 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. See the /ps argument for additional information.

If the interface is running on a PI 2 PINet node and if the server node is a PI 3 system, one should use a capital letter (or a case-insensitive character such as a number, a question mark, etc.) for the PointSource attribute when defining the point. For all other scenarios, one does not need to be careful with the case of the PointSource when defining the point. In all cases, the point source character that is supplied with the /ps command-line argument is not case sensitive. That is, /ps=P and /ps=p are equivalent. Once again, one only needs to be careful with the case of the PointSource during point definition, and, then, only when the interface will be running on a PI 2 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, and T. 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 P is not defined in the PI 2 point source table, a point with a point source of P cannot be created. This prevents the user from accidentally creating a point with an incorrect point source character. No corresponding 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.

To define a point source character in the PI 2 point source table, do the following:

• Enter PI by typing the following command from a VMS command prompt:

@pisysexe:pi

• Select the “PointSrc” option from the menu.

• Select “New” from the menu.

• Assign a point source next to the “Code:” field. Also, assign minimum and maximum values for the Location1 to Location5 attributes. The minimum and maximum values for the Location codes are interface-specific, with the exception of unused Location codes, which should always have their minimum and maximum values set to -20000000 and 20000000, respectively.

| |Location1 |Location2 |Location3 |Location4 |Location5 |

|Minimum |-20000000 |-20000000 |-20000000 |0 |-20000000 |

|Maximum |20000000 |20000000 |20000000 |20000000 |20000000 |

• Select “Save” from the menu.

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.

PI 3 Server Nodes

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 @, and PI Performance Equations uses C. One should either not use these point source characters or change the default point source characters for these applications.

PointType

PI 2 Server Node

Scaled real, full-precision real, integer, and digital point types are supported on PI 2 servers. See the Data Archive (DA) section of PI System Manual I for more information on the individual point types.

Unix or NT Interface Node Connected to a PI 3 Server Node

Float16, float32, int16, int32, digital, and string point types are supported on PI 3 servers. See the PI Data Archive Manual for NT and UNIX for more information on the individual point types. 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.

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.

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.

ExcMin, ExcMax, ExcDev and ExcDevPercent

These are the exception-specification attributes. Note that there is no ExcDevPercent attribute for PI 2 servers. Instead, the units of ExcDev are determined by the DeviationUnits attribute.

The exception-specification attributes are used to define exception-reporting specifications. Exception reporting is basically a filter. Raw values that the interface receives are filtered if they do not pass the exception-reporting specifications. If the raw values pass exception, they are sent to the snapshot, where they can be viewed by client applications such as ProcessBook.

ExcMin is the exception minimum time, ExcMax is the exception maximum time, and ExcDev is the exception deviation dead band. For PI 2, ExcDev is defined in terms of engineering units or in terms of percent of the Span attribute, depending on how the DeviationUnits attribute is set. For PI 3, ExcDev is always defined in terms of engineering units.

For PI 3, ExcDev is related to ExcDevPercent by:

ExcDev = ExcDevPercent * Span / 100

where Span is defined by the Span PI point attribute. If either ExcDev or ExcDevPercent is changed, the other is automatically updated to be compatible. If both are changed at once, ExcDevPercent takes precedence.

Raw values are said to “pass exception” if:

• The difference between the new value and the last value that passed exception is greater than ExcDev

and

the difference between the times of the new value and the last value that passed exception is greater than ExcMin.

or

• The difference between the times of the new value and the last value that passed exception is greater than ExcMax.

The last value that passed exception is called the “old value.” The next value that passes exception is called the “new value.” The last value that was received by the interface before the new value is called the “previous value.” There will not be a “previous value” if the interface did not receive a value between the “old value” and the “new value.” When a new value passes exception, the previous value and the new value will be sent to the snapshot. The new value will then become the old value, and the cycle continues.

The time between exceptions can be greater than the ExcMax if no new values are received by the interface for a point.

Note that the “previous value” will be sent to PI even if it was received before ExcMin seconds had expired. ExcMin applies only to the “new value.”

Compressing

If the compressing attribute is set to 1 (ON), then the compression specifications below are used to filter the data that is passed from the snapshot to the archive.

The compression algorithm is executed in the snapshot subsystem, not in interfaces.

CompDev, CompMin, CompMax, CompDevPercent

These are the compression specifications. CompDev is the compression deviation, CompMin is the compression minimum time, and CompMax is the compression maximum time. CompDevPercent and CompDev are related by:

CompDev = CompDevPercent * Span / 100

where Span is defined by the Span PI point attribute.

The swinging-door algorithm is used to filter the data. For PI 3 servers, the algorithm is described in the PI Data Archive for Windows NT and UNIX manual. For PI 2 servers, the algorithm is described in the Data Archive (DA) section of PI System Manual I.

Scan

This attribute is not used.

Zero, Span

PI 2 Server Nodes

For a PI 2 server, the Zero and Span attributes are required for scaled integers and scaled floating points because the value of the Zero and Span attributes affects the data representation in the archive for these point types. The Zero and Span attributes do not affect the data representation of full-precision floating points. See the Data Archive (DA) section of PI System Manual I for more information.

PI 3 Server Nodes

For PI 3 servers, the Zero and Span attributes are required for PI point types of Int16 and Float16 because the value of the Zero and Span attributes affects the data representation in the archive for these point types. The Zero and Span attributes do not affect the data representation of points of any other type. See the PI Data Archive for Windows NT and UNIX manual more information.

For digital PI points, one must not define the Zero and Span attributes because they are set internally by PI when a digital point is created. Zero will be set to 0 and the Span will be set to the number of digital states in the set.

TypicalValue

Although the TypicalValue is only used to document a reasonable value for the PI point, it must be specified if its default value will not fall between the Zero and Zero plus Span. Otherwise, creation of the PI Point will fail. For a numeric tag, it must be greater than or equal to the Zero attribute and less than or equal to the Zero attribute plus the Span attribute.

PI 2 Server Nodes

For digital tags, the TypicalValue must be between DigStartCode and DigStartCode plus DigNumber. For all other tags, the TypicalValue must be between the Zero and Zero plus Span.

PI 3 Server Nodes

The TypicalValue must be between Zero and Zero plus Span. For digital points, the Zero and Span are set internally by PI. See the description of the Zero and Span attributes above for more information.

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. See data archive (DA) section 4.2.3 of PI System Manual I for information on configuring shutdown events for PI 2.

PI 3 Server Nodes

The shutdown attribute is used only if the server node is a PI 3 system.

The Shutdown attribute is 1 (true) by default. The default behavior of the pishutev 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, the reader is referred to the PI Data Archive for NT and UNIX manual.

One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the pishutev subsystem to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. One can change the default behavior by editing the \PI\dat\Shutdown.dat file, as discussed in the PI Data Archive Manual 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.

It is undesirable to write shutdown events when Bufserv is being used or if Bufserv is not being used. Bufserv is a utility program that provides the capability to store and forward events to a PI server, allowing continuous data collection when the server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shutdown, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface. Refer to the Bufserv manual for additional information.

DigitalSet

This is a PI 3 Point attribute only. It is not used for PI2. The DigitalSet attribute is used to assign a digital state set to a PI Point. For standard usage, see the PI Data Archive for NT and UNIX manual.

DigStartCode and DigNumber

These attributes are used only with PI 2. They are not used with PI 3. These attributes are used when defining a digital tag on a PI 2 server. For standard usage, see the Data Archive (DA) section of PI System Manual I.

Data Files

VMS Data Files

Batchfl Data records consist of PI Tag name, Time stamp for the data when put in the database, and value.

The following is an example of a file:

au1311.01,29-MAR-1990 07:30:00,234.3

au1321.02,29-MAR-1990 08:00:00,1.2

au1331.03,29-MAR-1990 08:30:50,34

au1301.01,29-MAR-1990 07:30:00,BAD DATA

au1302.02,29-MAR-1990 07:00:50,OFF

au1303.03,29-MAR-1990 07:00:50,ON

au1304.04,29-MAR-1990 17:00:00,RUNNING

Note: The fields are separated by commas. The first field is the PI Tag name.

The next field is the time stamp, i.e. (format: dd-mmm-yyyy hh:mm:ss)

The last field is the value (float, integer, or digital state).

NT and UNIX Data Files

The Batchfl 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

An Alias tag name can be used by passing a command line parameter /as=I or /as=E. The interface will match the Alias tag with PI Points that have the alias tag in the Instrument tag field (I), or the Extended Descriptor (E).

Delimiter -- Required

The delimiter between the fields defaults to a comma ‘,’. This can be changed by passing a different character in the startup parameters Passing a command line paramter 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 subsecond 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.

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 in the fifth field. 1 for questionable bit being set, 0 for not set.

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 for NT and UNIX

On the NT and UNIX platforms, the Batchfl interface is started automatically by the PI Data Archive startup procedure. Program activation and command line parameters are the same for both NT and UNIX in the batchfl.bat and batchfl.sh respectively

The following is an NT example:

REM batchfl.bat

REM

REM this command procedure passes required -default parameters to

REM process batchfl.

REM

REM

REM command line arguments:

REM /f= required - frequency in seconds to check for new data files

REM /pa= required - path and mask to data files

REM /pu= required - relative purge time to delete processed data files -xh,-xd. -xm

REM /ps= optional - point source character. Default is none.

REM /host= optional - name of PI home node:port number Default is localhost:5450

REM For a PI2 server, port is 545, For a PI3 server, port is 5450

REM /fs= optional - character to separate fields in data line. default is comma

REM /tn optional - read point number instead of tag name in data line.

REM default is read tag name.

REM /lb optional - use putlabvalue instead of putsnapshot. Allows data to be replaced

REM default is to use putsnapshot.

REM /ts optional - time field is number of seconds since 1970 instead of time string

REM /tsu optional – time field is number of seconds since 1970 in UTC time.

REM /ex optional - use pi send exception instead of putsnapshots

REM /as= optional – 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= optional - specify the number of seconds to pause between processing files.

REM /db optional - turns on additional debug messages

REM /dev optional – turns on more detailed debug messages

REM

REM Run string needs a space between arguments, no spaces within

REM argument.

REM

..\interfaces\batchfl\batchfl /host:dragon:5450 /f=60 /pa=c:\batchfl\*.dat /pu=-1d

REM

REM end of batchfl.bat

There are three ways to enter data into a PI 3 server. The default is to use the Extended API that supports string tags and sub-second data. By passing a /lb, the extended API call is used which will allow values to be replaced, including string tags and sub-second data. By passing, a /ex, pisn_sendexceptionq is used which supports exception reporting.

NOTE: You must have a PI 3.2 SR1 or higher server and PI-API version 1.3.0 or higher for string values and sub-second data to be supported with the /lb and /ex parameter .

If both a /ex and a /lb is passed, /lb will be used.

The following is a UNIX example:

#

# @(#)batchfl.sh 1.0 07/29/96

#

#

# this command procedure passes required -default parameters to

# process batchfl.

#

#

# command line arguments:

# /f= required - frequency in seconds to check for new data files

# /pa= required - path and mask to data files

# /pu= required - relative purge time to delete processed data

# files (-Xh,-Xd,-Xm)

# /ps= optional - point source character. Default is none.

# /host= optional - 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

# /fs= optional - character to separate fields in data line.

# default is comma

# /tn optional - read point number instead of tag name in data line.

# default is read tag name.

# /lb optional - use putlabvalue instead of putsnapshot. Allows data to be replaced

# default is to use putsnapshot.

# /ts optional - time field is number of seconds since 1970 instead of time string

# /tsu optional – time field is number of seconds since 1970 in UTC time.

# /ex optional - use pi send exception instead of putsnapshots

# /as= optional – 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= optional - specify the number of seconds to pause between processing files.

# /db optional - turns on additional debug messages

# /dev optional - 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 &

#

#

The startup options are:

/ps=L

specifies the point source. This is an optional parameter. If no point source is passed, no point source checking is done. If a point source is passed, only points with this point source will be processed.

/f=60

specifies the cycle time, in seconds, for the checking for data files.

/pa=c:\labdata\*.dat

specifies the data file path and 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: for Unix, the data file mask only supports *.

/pu=-2d

specifies the age of processed data files to be deleted. In this example, processed data files older than 2 days are deleted.

/host=xxxxxx

specifies the PI home node where xxxxxx can be localhost:5450 if the interface is running on the PI3 server node. If the interface is sending data to a PI 3 server, /host=name of PI 3 server:5450. e.g.: /host=rasin:5450. If the interface is sending data to a PI 2 server, /host=rasin:545. This is an optional parameter. If not specified, localhost:5450 is used.

/fs=|

specifies the field separator between tagname and timestamp, and timestamp and value. This is an optional parameter. If not specified a comma(‘,’) is used.

/tn

specifies that the data line has a tag number instead of the tagname. If not specified, the tagname is used.

/lb

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

/ts

use number of seconds since 1970 (local time) in time field instead of time string.

/tsu

use number of seconds since 1970 in UTC time in time field instead of time string.

/ex

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

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

/sl=xx

specify the number of seconds to pause between processing files. This can be used to throttle the rate that the data files get processed.

/db

specifies that debug messages be written to the log files.

/dev

specifies that more detailed debug messages should be written to the log file.

Shutdown for NT and UNIX

On the UNIX platform, the Batchfl interface is normally stopped automatically by the PI Data Archive shutdown procedure. Killing the UNIX process can also stop it. On the NT platform, typing C in the appropriate Command Prompt window stops the Batchfl interface. On an NT system running the interface as a service, edit the PI/adm/pisrvsitestop.bat file to add batchfl -stop. This way the Batchfl interface will automatically be stopped whenever PI is stopped.

Troubleshooting on NT and UNIX

The Batchfl interface records status and error messages in the pipc\dat\pipc.log file. If the pipc directory does not exist, the interface goes to the temp directory of the root drive. e.g.: c:\temp\pipc.log.

If you are having problems with the Batchfl interface, this is the first place to look for indications of the source of the trouble.

Messages will be written to the pipc.log file at the following times:

1. At Startup

2. When invalid parameters are found in the command line

3. When a file has not been processed for more than 24 hours

4. When a file has been processed and the last file that has been processed was done more than 24 hours ago

5. When a digital state is not found

6. When a PI point is not found, a single message will be written.

7. When an error occurs while adding data to PI

8. When there is a successful connection to the PI Server

9. When there is not a successful connection to the PI Server

Installation for NT and UNIX

The Batchfl interface is installed separately from the installation of the PI Data Archive installation. Installations consist of the following steps:

1. Create the directory PI\interfaces\batchfl.

10. On NT systems, copy the executable (batchfl.exe) and its startup procedure (batchfl.bat or batchfl.sh) into the newly created directory. The interface requires the MSVCRT*.DLL. If this DLL is NOT in your Windows System directory (for most NT systems this will be the C:\WINNT\SYSTEM32), copy the MSVCRT*.DLL file provided to your Windows System directory.

11. On UNIX systems, go to the directory PI\interfaces\batchfl and issue the command:

$ tar -xv

12. The files batchfl and batchfl.sh will be copied to that directory.

2. Edit the startup file batchfl.bat on NT or batchfl.sh for UNIX..

2. Edit the PI\adm\pisitestart.bat or PI/adm/pisitestart.sh file to add batchfl.bat or batchfl.sh. This way, the Batchfl interface will automatically be started whenever PI is started.

To run as a NT service, complete steps 4 ,5,6 and 7:

3. One can get help for installing the interface as a service at any time by typing the following:

Batchfl -help

Note: the –query flag that is described when help is invoked is not implemented at this time.

The batchfl service can be installed either as a manual or an automatic service. Automatic services are started automatically when the NT operating system is rebooted. This feature is useful in the event of a power failure. To install the interface as a manual service, execute the following command from the batchfl\ directory:

batchfl -install -depend tcpip

To install the interface as an automatic service, execute the following command from the batchfl\ directory:

batchfl -install –auto -depend tcpip

Check the Microsoft Windows NT services control panel to verify that the service has been successfully added. One can use the services control panel at any time to change the batchfl service from an automatic service to a manual service or vice versa.

If the interface is reading files from a mapped drive, the interface should also depend on lanworkstation so the drives will be mapped before the interface starts.

batchfl -install –auto -depend “tcpip,lanworkstation”

The batchfl service can be started from the services control panel or by executing the following command from the batchfl\ directory:

batchfl -start

A message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. If the service is successfully started, the interface will attempt to read the command-line arguments from the batchfl.bat file. For this to succeed, the root name (the part of the file name before the .exe and .bat extensions) of the batch file must be the same as the root name of the executable. Also, the batch file and the executable file must be in the same directory. If the interface is unable to read the command-line arguments or if the command-line arguments that the interface reads are invalid, the service will terminate with no error messages echoed to the screen. For this reason, the user MUST check the pipc.log file to verify that the interface is running correctly. In the pipc.log file, messages pertaining to the batchfl interface will be prepended by Batchfl>. The location of the pipc.log file is determined by the PIHOME entry in the pipc.ini file. The pipc.ini file is located in the Winnt directory. Usually, the pipc.log file will reside in the c:\pipc\dat\ directory.

If the service was successfully started, the user can verify that the service is still running from the services control panel. If the service has been terminated, the reason for its termination will be given in the pipc.log file. If the service is still running, the user can use c:\PI\bin\apisnap.exe or Processbook to verify that data is being successfully transferred to the PI Data Archive.

The batchfl service can be stopped at any time by issuing the following command:

batchfl -stop

The batchfl service can be removed by:

batchfl -remove

5. If the batchfl service is installed as a manual service on the PI home node, the user may wish to edit the c:\PI\adm\pisrvsitestart.bat and the c:\PI\adm\pisrvsitestop.bat command files. These command files are invoked only when the PI data archive is started and stopped as a manual service with the c:\PI\adm\pisrvstart.bat and the c:\PI\adm\pisitestop.bat command files.

In the c:\PI\adm\pisrvsitestart.bat file, make sure that the second to last line ends in:

& wait 5000

If not, append “& wait 5000” to the end of the line. In the same file, add the following command just above “:theend”:

C:\PI\interfaces\batchfl\batchfl -start & wait 5000

Add the following command to the c:\PI\adm\pisrvsitestop.bat file just above “:theend”:

C:\PI\interfaces\batchfl\batchfl -stop

Note: the full path name to the batchfl executable must be given in both the c:\PI\adm\pisrvsitestart.bat and the c:\PI\adm\pisrvsitestop.bat command files.

To run in interactive mode, complete steps 6 and 7:

6. Execute the following command from an MsDos prompt:

cd c:\PI\interfaces

start “batchfl” batchfl\batchfl.bat

A new MsDos window will appear, and the user will see several messages echoed to the screen. Then the messages will simply stop. The user will not regain a command prompt on the MsDos window until the interface has been stopped. Typing CONTROL-C while the MsDos window is selected stops the interface. The user can use c:\PI\bin\apisnap.exe or Processbook to verify that data is being successfully transferred to the PI Data Archive.

Check whether there are any error messages to verify successful execution of the interface. Messages that are sent to the screen are also sent to the pipc.log file but some messages are written to this file that are not echoed to the screen when the interface is started up so be sure to check the pipc.log file. Messages in the pipc.log file that pertain to the batchfl interface will be prepended by Batchfl >. The location of the pipc.log file is determined by the PIHOME entry in the pipc.ini file. The pipc.ini file is located in the Winnt directory. Usually, the pipc.log file will be placed in the c:\pipc\dat\ directory.

7. If you plan to start both the PI Data Archive and the Batchfl interface manually, you may wish to start the Batchfl interface along with the PI data archive. To do this you must edit the c:\PI\adm\pisitestart.bat command file (there is no such thing as a c:\PI\adm\pisitestop.bat command file). Make sure that the last line of the c:\PI\adm\pisitestart.bat file ends in:

& wait 5000

If not, append “& wait 5000” to the end of the line. In the same file, add the following two commands:

echo Starting Batchfl Interface

start “Batchfl” /min ..\interfaces\batchfl\batchfl.bat & wait 5000

The Batchfl interface should now be started in interactive mode. The /min flag minimizes the MsDos window that is created when the Batchfl interface is executed.

Startup for VMS

At the PI System startup, the interface program starts automatically. When the PI System is stopped, the interface program stops automatically.

Use a privileged account for the following steps.

1. If there is a need to restart the interface, stop the interface program by executing:

@PISysExe:STOP PI-BATCHFL

2. When the program stops as determined by verifying that the PI-BATCHFL process no longer shows up on a “Show System” display, restart the interface by typing the command:

@PISysExe:BATCHFLDetach.

The output file for the detached process is PISysExe:BATCHFL.out.

The program writes messages to this output file and the PI message log.

You can adjust parameters by editing PISysExe:.

$ ! 4/7/89 MMG

$ !

$ ! Command file to read values from a BATCHFL Interface File

$ ! command file should be run as a detached process. The parameters

$ ! for the BATCHFL.exe runstring are:

$ !

$ ! 1 - frequency of check(secs) (300 = 5min)

$ ! 2 - Point source character

$ ! 3 - Path and mask of data files

$ ! 4 - Event counter number (1-45)

$ ! 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

When the interface is installed, the following parameters in this file should not need adjusting.

|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 - 45. Default of 20 is |

| |used if an invalid counter is specified. |

|5 |Purge time is when the processed files will be deleted from when they were 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. |

Messages on VMS

Messages are written to Pisysexe:BATCHFL.out and PI message log.

They are written at the following times:

13. At Start Up.

14. For invalid parameters and defaults used.

15. The number of points found for the BATCHFL interface.

16. When a file has not been processed for more than 24 hours.

17. When a file has been processed and the last file that has been processed was done more than 24 hours ago.

18. When more than one point is found for a record.

19. When a Digital state is not found.

20. When a PI-Point is not found for data.

21. For an error when putting a Lab Value in the archive.

22. = 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.

Installation Checklist for VMS

If a separate tape contains the interface distribution the following instructions must be followed for interface installation. These instructions should be followed after PI or PINet has been upgraded or installed. The enclosed tape contains the backup save set Batchfl.bck, which contains the PI-Batch File Interface.

1. Unpack the saveset to a “safe” directory.

go to the safe directory

mount the tape by: mount/over=id mua0: or whatever the name of your tape drive is

copy mua0:*.* .

unpack the saveset by: backup/verify/log batchfl.bck/sav .

2. Copy the files contained in batchfl.bck to PIBuild: and go to that directory.

2. Execute the file @pibuild:makepilinksymbols; this will ensure that the batchfl.exe is automatically copied to the pisysexe: directory when it is created.

Link the interface by executing @ batchfllink. The executable batchfl.exe will then get copied to pisysexe:.

Please verify that the interface version number in batchfl.out matches the version shown on the tape containing the interface.

After the interface has been installed, the remaining tasks must be completed.

1. To add the interface to a running PI System, execute the command procedure:

$ @Pibuild:batchfllink

2. Edit PISysExe: to indicate:

23. Desired frequency of checks

24. Point source character, path and mask to search for data files

25. I/O rate counter

26. Purge time of data files

2. Add a point source of x to the PI Point Source display.

Set the minimum and maximum values for each location parameter:

Loc No 1 2 3 4 5

Loc Min -200000000 -200000000 -200000000 -200000000 -200000000

Loc Max 2000000000 2000000000 2000000000 2000000000 2000000000

4. Add a tag to IORates.dat to record the data rate from the interface.

Use the event counter specified in PISysExe:.

Define this tag in the PI System.

4. Add PISysExe: to PISysMgr:

5. Add PISysExe:stop PI-BATCHFL to PISysMgr:.

6. Add Digital State, NO SAMPLE for blank results, and add all other Digital States to the table.

7. Define the PI tags for the interface.

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 t0 |

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

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download