Foxboro AP50 and AP51

Foxboro AP50 and AP51Interface Documentation

Version 1.16.5

How to Contact Us

Phone

(510) 297-5800 (main number)(510) 297-5828 (technical support)

Fax

(510) 357-8136

Internet

techsupport@osisoft.com

World Wide Web

http://www.osisoft.com

Bulletin Board

(510) 895-9423Telebit WorldBlazer modem (Hayes, MNP, or PEP compatible)8 data bits, 1 stop bit, no parity, up to 14400 BPS downloadprotocols: Xmodem, Ymodem, Zmodem, Kermit

Mail

OSI Software, Inc.P.O. Box 727San Leandro, CA 94577-0427USA

OSI Software GmbH Hauptstra(e 30 D-63674 Altenstadt 1Deutschland

OSI Software, LtdP. O. Box 8256Level One, 6-8 Nugent StreetAuckland 3, New Zealand

Unpublished—rights reserved under the copyright laws of the United States.RESTRICTED RIGHTS LEGENDUse, 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.Fx5051.doc

( 1997 OSI Software, Inc. All rights reserved777 Davis Street, Suite 250, San Leandro, CA 94577

Table of Contents

1Introduction

Foxboro IA (AIS) Interface / Sun SPARC2

Introduction2

PI Point Definition3

Two or More SPARC Stations6

Fox IA Utility6

AIS Setup7

Starting and Stopping the OSI Interface7

Installation Checklist for the SPARC9

Installing the Solaris PI-API11

Important Software Requirements12

System Configuration12

Extracting Distribution Files13

Solaris 113

Solaris 213

Installing Files14

Solaris 114

Solaris 214

Configuring the VMS PI Server14

PI Server VMS User15

VAX TCP/IP Configuration15

VMS Security15

PIServer.Dat file15

Node Authentication16

Login Protection17

Post Installation17

Starting and Stopping PI18

Error Logging19

Troubleshooting19

Foxboro AP50 and AP51 Interface Installation21

Extracting Files21

Solaris 121

Solaris 221

Linking the AP51 Interface on-Site22

Modify Startup and Shutdown Scripts22

Automatic Startup22

Troubleshooting Tips23

Introduction

The PI to Foxboro AP50 and AP51 interface provides for the bi-directional transfer of data between Foxboro 50 and 51 series computers running either AIS or the Foxboro API on top of AIS and PI systems. The 51 series computers run on Sun’s SPARC platforms on the Solaris 2.x operating system while the 50 series run under Solaris 1.x. PI systems run on VAX, UNIX, and Windows NT platforms.

To setup the interface, two separate PI modules must be installed on the Sun running the AIS software:

PI Module

Purpose

PI-API

Provides communication between the interface node and the PI system

PI-Foxboro AIS AP51 (or AP50)

Interface software

This document describes installation of both of these modules with installation of the interface discussed first and then the PI-API.

Note The PI-API module should be installed and verified first.

Foxboro IA (AIS) Interface / Sun SPARC

Introduction

The PI - Foxboro IA Interface Program is part of the link that connects a Plant Information (PI) System with a Foxboro IA Series control system. It resides in a Sun SPARC station (Foxboro 50/Solaris 1 or 51/Solaris 2 series) along with the Foxboro Application Interface Software (AIS), OSI’s Application Programming Interface (PI-API), and either Sunlink/DNI or TCP/IP. The DNI or TCP/IP is for a network link. Also, the SPARC may be a PI3 home node. The following is a simplified connection diagram.

VAX

PI (Home or PINet Node)

DECNET or TCP/IP

(

(

Foxboro

Sun SPARC

Sunlink/DNI (DECNET) or TCP/IP

OSI PI-API

OSI Interface Program

Foxboro AIS

|

|

|

|

Foxboro IA

DNBI

INI

|

|

IA Node Bus

The diagram shows a PI home or PINet node connected to a SPARC. Either a VMS DECNET - Sunlink DNI or a TCP/IP - Sun TCP/IP link is required for the Ethernet connection. OSI has a matching interface for each type of link. There is one interface program and one AIS per SPARC for connecting the SPARC to the IA node bus. They can support a combination of DNBI’s and INI’s. The diagram shows one DNBI and one INI although typically one DNBI or several INI’s are used.

The interface receives exception reports along with status bits from AIS and makes PI-API putsnapshot calls with these values if the status is good. Otherwise bad input or time-out digital state values are sent to PI. The interface also can make PI-API getsnapshot calls and send the values to AIS which does the exception reporting. Long PI tag names are used, and timestamps are the current home node times at the time of the putsnapshot calls.

Other documents include:

· Foxboro AIS System Manager’s Guide For Unix Computers

· Foxboro AIS Programmer’s Guides

· Foxboro INI documentation

· Foxboro IA Series documentation

· OSI Software, Inc. manuals and installation documentation for PI and PI-API

PI Point Definition

The following information is necessary for defining a PI point for reading/writing to the Foxboro IA. When the interface is online changes to PI points, including additions and deletions, are automatically incorporated.

PI Point

Definition

ExDesc

For reading from the IA, the Extended Descriptor has the form:

(inputs)

IA_variable_name MSG=IA_string_object_name

TRG=PITag3 BTM=x,y,z... ! comments

IA_variable_name is the Foxboro data object (IA point) name that is being read. It is up to 32 characters long and begins in the left most position. The full Foxboro name in the proper case must be used.

MSG=IA_string_object_name is optional. If used, the string in IA_string_object_name is read when triggered by the IA_variable_name object. IA_string_object_name is a string data object name which is called with the AIS sread() function anytime the IA_variable_name value (real, integer, or digital) goes from 0 to 1. The string is put in PI message log with the PI-API function pilg_putlog(). The string form is:

FXBIAxx> ‘pitag’ event/msg: ‘IA string’

where: xx is the computer number, ‘pitag’ is the PI tag name of the point, ‘IA string’ is the string read from the IA (up to 40 characters) MSG=IA_string_object_name can start any place after the IA_variable_name ends. MSG must be uppercase with no spaces.

TRG=PITag3 is for trigger tags and is optional.With inputs the last Foxboro exception is sent to the PI point when an event is received for the PITag3 from a pisn_evmexceptions() PI-API call. The current time stamp is used.

BTM=x,y,z... is for a bit mask and is optional. The bit mask is x,y,z... where x is the bit location in the source (0-31 for long integers) whose value is put in the low order bit (0) in the target. Then y is the bit location in the source whose value is put in the next bit (1) in the target. Up to 31 bits can be put in the target, and unspecified target bits are set to 0. Only integral Foxboro types can be masked. An example is BTM=31,0,7,8 which puts bit 31 of the source to bit 0 of the target, bit 0 to bit 1, bit 7 to bit 2, and bit 8 of the source to bit 3 of the target.

(outputs)

For writing to the IA the ExDesc form is:

IA_variable_name SRC=PITag1 RTN=PITag2 TRG=PITag3 ! comments

SRC=PITag1 and RTN=PITag2 are optional. SRC=PITag1 and RTN=PITag2 can start any place after the IA_variable_name ends. Both or either option is allowed, and they can be in any order. SRC and RTN must be uppercase with no spaces.

IA_variable_name is the Foxboro data object name that is being written. It is up to 32 characters, begins in the left most position, and is case sensitive. The Foxboro AIS Programmer’s Guide cautions that the read/write access mode secures the object, and the IA cannot writ to it. This mode is required for writing. Also the IA variables must have write permission.

The SRC option allows the primary tag to point to another tag that contains the value to be written. PITag1 is the name of the pointed to PI tag which supplies the value; it can have the same Point Source as interface tags.

The RTN option allows PI to obtain the AIS returned value of the written IA variable. AIS automatically reads any written variables, and the values are available. PITag2 is the name of the PI tag for the returned value; it can not be a tag of this interface, and either the Point Source code must be different or the list number (Location2) must equal ‘-10’.

TRG=PITag3 is for trigger tags and is optional. With outputs the last PI-API getsnapshot value is sent to AIS when an event is received for the PITag3 from a pisn_evmexceptions() PI-API call. AIS still will do exception reporting unless the exception deviation is zero.

Point Source

The code is usually F for Foxboro IA points. It must be defined in the PI Point Source Table (PI2 only). A different character may be used by editing the Point Source Table and the point source parameter in the script file $PIHOME/interfaces/fxbais/fxbais.sh. PIHOME is part of the path and is a SPARC environment variable that should be defined in a ~/.login file.

Point Type

All three-point types may be used. Use R for the IA float values and possibly for the long integer values. Use I or D for character, integer, and Boolean values. In converting D values for the Foxboro the positive value of the offset (PI value minus PI zero) is used.

Source Tag

If SRC=PITag1 is not in ExDesc the Source Tag is checked. It works the same way SRC does which is described above.

Instrument Tag

If the ExDesc is empty or has a space for the first character, the Instrument Tag is checked for the Foxboro tag name.

Location1

This parameter is the result of calculating (n*100 + x ) where n is the computer number in the range 1 to 99 and x is the IA interface number or gateway number. The computer number associates PI tags with an interface and is an arbitrary parameter that is set in the interface script file $PIHOME/interfaces/fxbais/fxbais.sh. The gateway number ranges from 1 to m, the maximum number of gateways set by the Foxboro AIS. A gateway number associates PI tags with a DNBI or an INI and corresponds to a gateway number configured in AIS. For the interface the gateway numbers are configurable parameters in the script file $PIHOME/interfaces/fxbais/fxbais.sh. The two values combine to give a range for Location1 of 101 to 9900+m. The interface does not use the AIS options of load leveling and automatic assignment of gateway numbers.

Location2

This parameter is the gateway data list number. It groups PI tags into lists for AIS calls. This parameter is unique within each gateway; the different gateways within a node and on different nodes can have the same data list number. Read values and write values must be in separate data lists, and typically values in different IA modules are in separate data lists. The range is 1 to the maximum number of data lists per DNBI (100 or more lists and 50 or more points per list) or INI (20 lists and 50 points per list.)

As discussed above in the Extended Descriptor section, a RTN=PITag2 must have a data list number equal to -10 if it has the interface Point Source code.

Location3

This parameter is the IA value type. For read values (PI receiving from IA) they are positive. For write values they are negative.

IATyp

Sun SPARC

1

char

2

short int

3

float

4

string: not used by the interface.

5

Boolean (same as char)

6

long int

As examples: a type 2 would be for int exceptions received by PI, and a type -3 would be for float writes to IA. Writes can be blocked with a configurable parameter in the script file $PIHOME/interfaces/fxbais/fxbais.sh.

Location4

This parameter is a data list (Location2) Fox IA scan rate parameter. The actual rate equals ½ of the parameter, seconds. It is used by the IA and is an argument in the AIS scopen() function call. The range is 1 to 20. A value of 0 defaults to 4. The smallest value of a list member is used. The IA scan rates are not related to the interface cycle time which is a configurable parameter in the script file $PIHOME/interfaces/fxbais/fxbais.sh.

ExcDev

The exception deviation in engineering units is the IA delta value. A data object is reported to PI or sent to the IA when it changes more than or the same as the ExcDev (delta) and the ExcMin time limit is met. The IA delta is set to 0.5 for PI ‘D’ type points that do not use ExcDev.

ExcMin

The exception minimum time in seconds. It is the minimum elapsed time before an exception is reported to PI or sent to the IA no matter how much it changes.

Scan

The scan flag must be on for exceptions to be put in the PI snapshot or sent to AIS for writing.

In addition to the attributes listed above, the following (specified by PIDIFF / piconfig keyword names) apply to the interface points:

TagDescriptorEngUnitsZeroSpanTypicalValueDigStartCodeDigNumber

FilterCodeArchivingCompressingResCompDevCompMinCompMaxStep

These attributes are not used by the interface:

Location5

SquareRoot

TotalCode

Convers

UserInt1, UserInt2

UserReal1, UserReal2

Two or More SPARC Stations

Additional SPARC stations with Foxboro interfaces can be connected to a PI node. They act like separate and independent interfaces. Points in the different interfaces can be configured with different Point Source Codes, with different computer numbers, or with both of these different. The computer number is an arbitrary parameter that is set in the interface script file $PIHOME/interfaces/fxbais/fxbais.sh. For a PI point the computer number is configured with the Location1 parameter.

Fox IA Utility

This is a program that lists PI tags by gateway number and list number and searches interface lists for PI and Foxboro tags. It also lists parameters and values for tags in the interface. The program must be run from the PI-API node servicing the desired PI points. The program is called with:

# $PIHOME/interfaces/fxbais/fxapisup

The options available with this command can be obtained by typing help on the prompt line after the program is started.

Please enter command: f,p,m,i,n,s,t,x,h(elp) h

Fxbais version 1.16.5, Fxapisup version 1.12.5

The commands are:

f Foxboro tag search (Starting indexes for f,p,m

p PI tag search cycle on filling buffer)

m exact pattern match, including spaces and case

i PIPtNbr info

n i/f index info

s lists by i/f {mod(Loc1,100)} and list(Loc2)

t changes mailbox timeout period

x exits

h brings up this help menu

The response should be a single character, it is not case sensitive

Please enter command: f,p,m,i,n,s,t,x,h(elp)

These commands allow viewing of the PI tag information. If the AIS software is unreachable or has not been started the following message will be given before the options are listed.

FIFO error; could not obtain AIS parmameters; use defaults

maxgw 1, maxptpgw 5000, iaptmax 5000

Retn command_code 10207, timout 10, error 6

Error, no mail

AIS Setup

See the Foxboro AIS System Manager’s Guide For UNIX Computers for information on configuring Foxboro AIS.

Starting and Stopping the OSI Interface

Starting and stopping must be done when logged on the SPARC as root. The path to the home PI directory is stored in the environment variable PIHOME. Then $PIHOME puts the PI home path in script files or in prompt commands.

Before starting the interface, Foxboro AIS and OSI PI-API must be online. Usually these programs are called from an edited SPARC startup file. PI-API is started with the Bourne Shell script file:

$PIHOME/bin/pistart

pistart calls the script file $PIHOME/bin/sitestart which calls the interface startup script, fxbais.sh. This call should be added by concatenating the $PIHOME/interfaces/fxbais/add2start to the sitestart script (see the installation section). fxbais.sh starts the interface process fxbais.

PI-API is stopped by an edited SPARC shutdown file that calls the following Bourne Shell script file:

$PIHOME/bin/pistop

pistop calls the script file $PIHOME/bin/sitestop that calls the interface script, fxastop, and then stops the API programs. The fxastop call should be added to the sitestop script by concatenating $PIHOME/interfaces/fxbais/add2stop to sitestop or editing sitestop to add.

/bin/csh $PIHOME/interfaces/fxbais/fxastop

The interface should be stopped before the PI-API or AIS software are shutdown.

Both PI-API and/or the interface can be manually started/stopped by running the above Bourne or C Shell script files.

Messages and errors are logged to $PIHOME/dat/pimesslogfile and $PIHOME/interfaces/fxbais/fxbais.out. Additional startup messages may appear in $PIHOME/dat/fxbais.log. Some of the messages are in both files and others are in only one of the files; check both.

The shell script file for starting the interface, fxbais.sh, starts the background process, fxbais. This shell script combines the two scripts, runfxa and fxadetach, which formerly started the interface. The fxbais.sh script is shown here.

#!/bin/csh

# fxbais.sh

# (C)Copyright Oil Systems,Inc. San Leandro, California 1992-4

# Shell procedure to call runfxa which starts FXBAIS as a background process

#

# Revision

# 1.00 6-23-92 jah original

# 1.01 3-24-93 jah changed from using $PIHOME to $cwd

# 1.02 8-10-94 jah (ver 1.10) change to work with AP51 (Solaris 2)

# 1.02 4-23-97 cah Changed to use PIHOME/interfaces/fxbais directory

# Changed file name to fxbais.sh

# 1.1 7-16-97 cah Added grep -v grep to set fxon. Changed ps -e to ps -ef.

# 1.2 7-21-97 cah Changed redirection to $PIHOME instead of ../..

#

# if PIHOME not in environment, then set for this procedure

if ("$?PIHOME" == "0") then

set workdir=$cwd

echo " PIHOME not defined, use $workdir for PIHOME/interfaces/fxbais"

else

set workdir=$PIHOME/interfaces/fxbais

endif

# jah 8-94

set JSYS=`uname -sr | grep 'SunOS 5'`

if ($#JSYS > 0) then

set fxon=`ps -ef | grep fxbais | grep -v sh | grep -v grep`

else

set fxon=`ps -cxa | grep -e fxbais | grep -v sh | grep -v grep`

endif

if ( "${fxon}" == "" ) then

set outfle="fxbais"

if (-e "$workdir/${outfle}.out") then

echo " Rename ${outfle}.out as ${outfle}.old"

/bin/mv "$workdir/${outfle}.out" "$workdir/${outfle}.old"

endif

#---

# The input parameters are:

# 1 - number of interfaces(gateways) for this node (<0sim)

# 2...a - gateway number component of Location1

# (1 - no i/f)

# a1...b - event counter number for each i/f (1 - 35)

# b1 - main cycle time (sec)

# b2 - point source code defined for IA tags

# b3 - computer number component of Location1 (1 - 99)

# b4 - log file name; if null prints to stdout

# b5 - flag for writing to IA, 1 can write, -1 no write

#

#--- Edit the following line.

$workdir/fxbais 1 1 24 2.0 F 1 $workdir/${outfle}.out 1 > $PIHOME/dat/fxbais.log &

echo " Starting interface (FXBAIS process)"

else

echo " Interface (FXBAIS process) now running. Can not restart."

endif

exit 0

# end

The line in bold following the statement ‘Edit the following line’ (a single line from $workdir to &, though it appears on two lines here) should be edited for the site configuration. The parameter groups for the interface program are:

· 1, the number of IA gateways being used. One here.

· 2, a number for each of the gateways. 1 here.

· An event counter number for each of the gateways. 24 here. They should match tags listed in $PIHOME/dat/iorates.dat. For example,: SY:FXA024,24

· The main cycle time for the interface in seconds. It is 2.0 here. The interface could run slower if all SPARC tasks are not finished in the time entered. The minimum is 0.5. The cycle time is not related to the IA scan rate parameter (Location4).

· The point source code defined for the PI points to be used by the interface. It is F here.

· The computer number for the interface process. It is 1 here. It corresponds to the computer number part of the Location1 parameter of a PI point.

· The interface log file name. Typically it is set to “$PIHOME/interfaces/fxbais/fxbais.out”.

· The flag for writing allows writing to the IA to be disabled. A 1 allows writing, and a -1 prevents writing. It is 1 in this example.

Installation Checklist for the SPARC

· Install the hardware and software for the link (DECNET or TCP/IP).

· Install the Foxboro AIS and start it.

· Install PI-API and the Interface. The interface should be extracted in the $PIHOME directory. The files will be extracted into $PIHOME/interfaces/fxbais.

cd $PIHOME

tar xvf /dev/rdiskette

· For PI 2 home nodes, define the Foxboro IA point source code from the PI Point Source Definition Screen (Point Src).

· Add IORates tags to $PIHOME/dat/iorates.dat. Define these tags in the PI System. If PI-API is running then the IORates process must be restarted to update changes to the iorates.dat file.

· Copy the file fxbais.sh.new to fxbais.sh if the file does not exist and edit the interface parameters in $PIHOME/interfaces/fxbais/fxbais.sh.

· Concatenate add2start to sitestart,

cat $PIHOME/interfaces/fxbais/add2start >> $PIHOME/bin/sitestart

or add

csh $PIHOME/interfaces/fxbais/fxbais.sh

to $PIHOME/bin/sitestart, and add

csh $PIHOME/interfaces/fxbais/fxastop

to $PIHOME/bin/sitestop (concatenate add2stop to sitestop or edit sitestop to add it).

· Define PI tags for the interface on the home node.

If PI-API is not running then start it and the interface with:

sh $PHOME/bin/pistart

If only the interface is not running then start it with:

$PIHOME/interfaces/fxbais/fxbais.sh

Installing the Solaris PI-API

Foxboro systems running AIS come on a variety of platforms and operating systems. When installing the PI-API it is necessary to install a version that is compatible with the existing system and the intended communication protocol.

A table of Foxboro systems and platforms is shown below:

Series

Models

Platform

Operating System

AP-50 WP-50 AW-50

Sparc IPC

SunOS 4.1.1

A

AW-51A WP-51A AP-51A

Sparc Classic

Solaris 2.2 / SunOS 5.2 *

B

AW-51B WP-51B AP-51B

Sparc5

Solaris 2.4 / SunOS 5.4

C

AW-51C WP-51C

Sparc20

Solaris 2.4 / SunOS 5.4

Note Newer releases of these Foxboro models run under Solaris 2.4

You can verify the release of the operating system you are running on by logging in to the Sun and typing:

uname -a

This will show a response such as:

SunOS prune 5.4 Generic_101945-27 sun4c sparc

Where:

SunOS

operating system name

prune

node name

5.4

operating system release

Generic 101945-27

operating system version (kernel)

sun4c

machine hardware name

sparc

processor type

The PI-API versions that support the PI-Foxboro AIS AP50 and AP51 software are:

PI-API module

Solaris / SunOS version

Version

PI-API SOL1 TCP/IP

1.x /4.1.4

1.1

PI-API SOL1 DECNet

1.x /4.1.4

1.0.x

PI-API SOL2.4 TCP/IP

2.4 / 5.4

1.1

PI-API SOL2.2 TCP/IP

2.2 / 5.4

1.1.3

PI-API SOL2 DECNet

2.2 & 2.4 / 5.2 & 5.4

1.1

Important Software Requirements

The PI-API you intend to install needs to support the operating system release of your Foxboro system. You should have received all PI-API products to support the various system configurations. Please refer to the information above in determining which PI-API to install. If you do not have a match, contact OSI Software for the correct version.

The PI-API communicates with the PI home node using either TCP/IP or DECNet. PI3 (UNIX and NT systems) only communicates via TCP/IP. PI2 systems (VAX and Alpha) can use either DECNet or TCP/IP.

To use TCP/IP on a PI2 system, TCP/IP communications software must be purchased for the home node. Several vendors of this software are supported. For details consult the file piserver.txt in the PIBuild directory on the home node.

The TCP/IP version of the PI-API is recommended. Using DECNet on the Sun requires the purchase and installation of SunLink DNI. Experience has shown this package to be difficult to install and the DECNet PI-API is more restrictive.

System Configuration

The PI-API installation procedure requires the definition of a PI home directory and several environment variables. The PI installation scripts should be run either as superuser or a user named piadmin that has write privileges in the PI home directories. The environment variables USER and LOGNAME should be set to this user, either root or piadmin.

Note The command for setting environment variables is shell specific.

In Korn or Bourne shell:

# USER=root

# export USER

# LOGNAME=root

# export LOGNAME

In C Shell:

% setenv USER root

% setenv LOGNAME root

Define the PI home directory. This is typically set to /usr/pi, /opt/pi, or /home/pi, although any path with enough disk space is suitable. Typically the /opt directory has the most space. The command

# df

can be used to examine the available space on each disk partition. Available space is displayed in blocks (512 bytes/block).

For example:

# mkdir /opt/pi

Once the directory is created, the environment variable must be defined to point to this directory; from the Korn shell the command is:

# PIHOME=/opt/pi

# export PIHOME

or using the C Shell

setenv PIHOME /opt/pi

These environment variables are also required when the API is started. Defining these variables in the start up shell (.profile, .login) of the user that will typically start the system is helpful.

To determine the default shell of a user and his home directory (location of .profile and .login files) consult the file /etc/passwd. Each line in this file contains several items separated by colons (:). The first item is the user name. The last two items are the home directory and the default shell.

The installation scripts for the Solaris 1 PI-API uses the make utility which resides in /usr/bin. This directory must be in the PATH of user executing the installation.

Extracting Distribution Files

Solaris 1

The PI-API-SOL1 is distributed on 3.5” floppy disks. The files must be extracted to the PIHOME directory. The following commands will perform this:

# cd $PIHOME

# tar -xvf /dev/rfd0

After extracting the files from the disks, the build directory should exist under PIHOME.

Solaris 2

The PI-API-SOL2 is distributed on a 4mm DAT tape or 3.5” floppy diskettes. The files must be extracted to the PIHOME directory. The following commands will perform this:

# cd $PIHOME# tar -xvf /dev/rmt/<?> (for 4mm DAT Tape; <?> is your tape device number)# tar -xvf /dev/rdiskette (for each 3.5” floppy; eject removes the floppies)

Note If you have trouble running tar on the floppy as described above, see the Troubleshooting tip on accessing Solaris 2 floppy drives later in this document.

After extracting the files these directories should exist under PIHOME.

build bin dat include lib src

Installing Files

Solaris 1

Installing the Solaris 1 distribution is accomplished by the pi.install script. This script builds directories, links executables, creates libraries and copies files. Before running this script, make sure you have set the environment variables described above.

Run this script with the commands.

# cd $PIHOME/build

# sh pi.install

You will be prompted for the name of your default PI server during the execution. Enter the name of the primary PI home node you expect to connect with. If the home node is a PI3 (UNIX, Windows NT) server, follow the name with a colon and the number 5450 to specify the port. (MYSERVER:5450). On completion, the directories bin, dat, include, lib and src should have been created and populated.

Solaris 2

The Solaris 2 distribution comes with pre-built executables and libraries. To complete the installation the default PI server needs to be set and the shared library, libpiapi.so, made accessible to the system, either by moving it to /usr/lib or setting a path to the library for the loader.

To set the default PI server, change to the dat directory and edit the file piclient.ini

cd $PIHOME/dat

vi piclient.ini

Change the value assigned to PIHOMENODE to the PI server to which you expect to connect. Again if the home node is a PI3 (UNIX, Windows NT) server, follow the name with a colon and the number 5450 to specify the port (PIHOMENODE=MYSERVER:5450).

The shared library libpiapi.so must be in a directory where the system can find it at run time. This can be accomplished by setting the environment variable LD_LIBRARY_PATH for any process that needs access to the library or by copying the library to /usr/lib where the system will automatically find it.

To define or extend the LD_LIBRARY_PATH

Bourne and Korn Shell:

# LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/pi/lib

# export LD_LIBRARY_PATH

C Shell

setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/opt/pi/lib

or to copy

cp $PIHOME/lib/libpiapi.so /usr/lib

Configuring the VMS PI Server

The next two sections describe the steps necessary to allow the PI-API to communicate with a PI2 (VMS) server. Connecting to a PI3 (UNIX or Windows NT) server is only supported under TCP/IP but requires no additional configuration. You may skip these sections if you only intend to connect to PI3 servers.

The PI-API-SOL1-TCP and PI-API-SOL2-TCP require TCP/IP to be installed on the VAX node. If you are going to be running DEC TCP/IP Services for VMS, you must have PI version 2.0.6 or greater installed on the VMS PI Home node. Other supported TCP/IP products for VMS require PI version 2.08 or greater.

Several configuration steps are required to establish the server and setup security. The DECNet versions of the PI-API only require the PISERVER user to be created on the VAX node.

PI Server VMS User

Client nodes accessing the PI Home node login under user PISERVER. This user must be added to the VMS user database. The VAX command procedure PIBuild:AddPIServerUser.com will add and configure this user account. The privilege SYSPRV must be added to the PISERVER account for TCP access. This is accomplished by running the VMS Authorize utility and modifying the PISERVER account. The commands are as follows:

$ cd sys$system:

$ run authorize

UAF> modify piserver /defpriv=sysprv

%UAF-I-MDFYMSG, user record(s) updated

VAX TCP/IP Configuration

The following TCP/IP products for VMS are supported.

TCP/IP Product

PIServer Version

DEC TCP/IP Services for VMS, version 2.0

2.0.6

Process Software TCPWare, version 3.1

2.0.8

TGV MultiNet, version 3.2

2.0.8

Wollongong PathWay Runtime, version 1.1

2.0.8

For instructions on configuring these TCP/IP products to work with client products using the PI-API consult the file PIBUILD:piserver.txt on the VMS PI Home node.

VMS Security

PIServer.Dat file

The PI Server version 2.0.6 and later, may be configured to use node authentication and login protection for read and write access to the PI databases. This security is in addition to any authentication mechanisms available through the native transport.

The PI System manager enables node authentication and login protection via the file PISysDat:PIServer.Dat. This file currently contains two sections, [USERDATABASE] and [CLIENTACCESS], with item and entry pairs. All sites receive the following default PIServer.dat file:

[USERDATABASE]

DEFAULT=PI

[CLIENTACCESS]

DEFAULT=RW

Note Incorrect entries in the PIServer.Dat file may prevent existing PINet nodes from accessing the PI System home node. Moreover, the PI-to-PI interface may not function properly.

The default security provides all nodes with both read and write access. This is the same behavior as before security was implemented. The following two sections describe the configuration details.

Node Authentication

The [CLIENTACCESS] section of PIServer.Dat controls the default level of access granted and as well as the access levels for specific nodes. The access levels and their symbols are:

Access Code

Meaning

NONE

access denied

R

read only access

RW

read and write access

RWL

write access if login provided, otherwise read only access

RL

read access if login provided, otherwise access denied

RLWL

read and write access if login provided, otherwise access denied

For DECNet connections, the client names are checked against the NCP database. In TCP/IP connections, the client names are checked against the local hosts table or a Domain Server lookup table. In addition, the TCP/IP client names are case-sensitive. The server may have problem recognizing clients running DHCP (Dynamic Host Configuration Protocol). It is preferable to use assigned IP addresses for clients. A sample PIServer.Dat file is given below. (Note that a semicolon is used for comment lines.)

[USERDATABASE]

DEFAULT=PI

[CLIENTACCESS]

;let anyone have read access

DEFAULT=R

;the following nodes get unconditional access

PINET1=RW

PINET2=RW

;the following nodes need login for write access

WILMA=RWL

BAMBAM=RWL

;the following should not have any accessPEBBLES=NONE

Note In the example above PIServer.Dat, the machines named PINET1 and PINET2 have unconditional read and write access. This level must be supplied to existing PINet nodes.

Nodes that are running a PI-to-PI interface to retrieve data from a PI System home node must have at least unconditional read access. For example, if APPLE is running PI-to-PI to access data from PLUM, the PIServer.Dat file on PLUM must provide APPLE with unconditional read access.

Login Protection

The [USERDATABASE] section is used to specify which database will be used to verify user names and passwords provided through the piut_login() PI-API function. Only those applications which make the piut_login() call support the login authentication option. Contact your applications program provider for more information.

The [USERDATABASE] section currently supports the DEFAULT item with either the PI or VMS login databases.

Note To use the VMS login database, the PIServer account must be modified to have sysprv default privileges. This is not provided by default.

Post Installation

After successful installation of the PI-API several other tasks may be required:

Modify the pistart script. Using an editor open the file $PIHOME/bin/pistart. Find the following line:

PSARG=-e # -cx for solaris 1

Modify this line to look as follows:

PSARG=-cx # -cx for solaris 1

Set a default PI home node. This was described earlier under the installation process. This is done by editing the file $PIHOME/dat/piclient.ini. Simply modify the line shown below to point at you default PI node. This is typically your PI Home node or a PINet node.

PIHOMENODE=casaba

For example if your PI home node is called “pluto”, modify the entry in $PIHOME/dat/piclient.ini to:

PIHOMENODE=pluto

Again, if your default home node is a PI3 system, append :5450 to the server name to specify the correct port.

Starting and Stopping PI

PI has four standard processes running on a UNIX PI-API node:

Process

Purpose

mqsrv

Message log server.

Mqmgr

Message log manager.

Ioshmsrv

I/O rates shared memory server

iorates

I/O rates monitor program. IORates is used to monitor the snapshot rate of the PI client. This utility requires the editing of the configuration file, $PIHOME/dat/iorates.dat. If this file does not exist or is not configured correctly IORates will issue a warning. This will not affect operation of PI-API other than no IORates will be monitored.

See the DA manual for the format of the iorates.dat file. Note the UNIX implementations of PI-API will automatically increment counter number 47 whenever it sends snapshots. By configuring a tag on the default home node and associating counter 47 with that tag in the iorates.dat file, the snapshot rate is periodically sent to that tag as long as the IORates processes are running. .

These processes are started by $PIHOME/bin/pistart and stopped by $PIHOME/bin/pistop. These scripts also run sitestart and sitestop, respectively.

To verify that these processes are running use the ps command and “pipe” the results to grep. If the process is running you should see a line for the process. Ignore lines showing your grep process that is also running when you issue the command.

Solaris 1

# ps -ax | grep mqsrv

Solaris 2

# ps -ef | grep mqsrv

On Solaris 2 when mqsrv is running you will see lines like:

root 525 476 8 19:19:16 console 0:00 grep mqsrv

root 502 1 35 19:18:52 console 0:00 ./mqsrv

Here the first line is the grep process looking for the process and the second line is the process itself.

Example Program

$PIHOME/src contains an example program, apisnap.c, and make file, apisnap.mak. This source demonstrates how to build a PI-API application. It also is a good test of proper installation. The program is shipped or built during the installation process in the $PIHOME/bin directory. This example can be built after installation with the following commands:

# cd $PIHOME/src

# make -f apisnap.mak

This will overwrite the executable file $PIHOME/bin/apisnap. The program apisnap, when executed, will connect to the default PI Home node, and then prompt for a PI tag. If the PI tag is valid the snapshot report of the point will be displayed. Optionally, the PI home node name can be specified as a command line argument.

For example:

# apitest pinode2

will attempt to connect to pinode2.

Or to connect to a PI3 server

# apitest pi3node:5450

Please note that building applications with the PI-API requires an ANSI compatible C/C++ compiler. Solaris 2.x systems do not ship with such a compiler. If your system does not have such a compiler you cannot compile this sample. You can, however, use the shipped executable $PIHOME/bin/apisnap for testing your connection to the home node and proper configuration of the piclient.ini file.

Error Logging

When the PI-API processes are running, errors encountered by programs calling the PI-API are logged in the file $PIHOME/dat/pimesslogfile. This file contains informational and error messages. This file should be consulted if any problems are observed.

The program $PIHOME/bin/shootq will put a message into the log file. This can be used as a test of the logging system.

# cd $PIHOME/bin

# shootq “A test message for the log”

When the API processes are running continuously, the log file will be automatically moved to a file with a date extension at the end of each day and a new file started.

Troubleshooting

1. Can’t connect to PI home node.

· Try running ping to see if the system you installed on can contact the server. If this fails check the file /etc/hosts. It needs to have IP addresses and server names for all the servers with which you expect to connect. Use uppercase in the hosts file. If necessary you may specify multiple names for an address (upper and lowercase). Other name resolution schemes are also possible. Check with your system administrator if you can not get ping to work.

· Try running $PIHOME/bin/apisnap with the server name appended. See the section on “Example Program” on page 18 for arguments. If this connects, examine the $PIHOME/dat/piclient.ini file and make sure the server name is correct (for PI3 servers - NT, UNIX - you must append the port number (:5450) to the server name.

· Examine the log file, $PIHOME/dat/pimesslogfile. You must have started the API processes (run sh pistart) for messages to be logged. New messages are at the bottom of the file. The UNIX tail command is useful. To look at the last 100 lines in the file type:

tail -100 pimesslogfile

The messages in the file often give a strong indication as to the failure mode.

2. Unable to read from the Solaris II floppy drive.

Use ps to look for the vold process

ps -ef | grep vold

If the process is not found, start it by

/etc/init.d/volmgt start

In either case, run volcheck

volcheck

Then stop vold

/etc/init.d/volmgt stop

At this point you should be able to address the device rdiskette. To look at the contents type

tar -tvf /dev/rdiskette

Foxboro AP50 and AP51 Interface Installation

There are three versions of the Foxboro interface, two for the AP51 and one for the AP50 as follows:

Interface Module

Solaris / SunOS

Communications protocol

AP51 DNT

2.x / 5.x

DECNet

AP51 TCP-IP

2.x / 5.x

TCP-IP

AP50

1.x / 4.1.4

DECNet or TCP-IP

Ensure you have received the proper software for your Operating system and communications protocol before starting.

Extracting Files

The interface and support programs are shipped on a 3.5” floppy disk. To extract the files first log on as the superuser. The files are then extracted to the $PIHOME directory:

# cd $PIHOME

# tar -xvf /dev/rdiskette

Use the eject command to remove floppies from the drive.

Solaris 1

The Solaris 1 (AP50 ) distribution requires running the C Shell script fxlink. Before running this script you must define the environment variables PIHOME and FOXAISHOME. PIHOME is the base directory where the PI-API was installed. FOXAISHOME is appended with /lib to locate the Foxboro libraries libfox.so and libais.so. Once this is done you execute the fxlink script. For example:

csh

cd /opt/PI/bin

setenv PIHOME /opt/PI

setenv FOXAISHOME /opt/fox/ais

fxlink

Solaris 2

For Solaris 2 the interface executables are shipped; typically no linking is required for installation.

A directory is created under $PIHOME/interfaces/fxbais called fxlink that contains files to link the executable on site should this be necessary. See Troubleshooting Tips below.

The directory also contains a copy of libC.so.5, the C++ runtime library, which is used by the executables. If you already have a file of this name on your system (typically in /usr/lib) you can ignore this.

If you do not have this library on your system, copy it from the fxlink directory either to /usr/lib, or to the $PIHOME/lib. If you choose the latter be sure that your LD_LIBRARY_PATH environment variable is set to point to the $PIHOME/lib directory so the library is found at run time. (Examples of setting the LD_LIBRARY_PATH are shown in Troubleshooting Tip 3).

Linking the AP51 Interface on-Site

Sometimes the interface may need to be relinked on site. The shipped executables may be incompatible with the local system’s installed shared libraries or with the resident Foxboro libraries. If your system is running Solaris 2.2 or you have release 4.x of the Foxboro libraries you will likely need to relink. If neither of these conditions is true, try the shipped executables before attempting to relink. If you need to relink follow these steps:

1. Make sure the environment variables PIHOME and FOXAISHOME are defined. FOXAISHOME is appended with /lib during linking to find the libfox.so and libais.so libraries.

2. Back up the existing executables to somewhere safe.

3. Change to the link directory.# cd $PIHOME/interfaces/fxbais/fxlink

4. Execute the link script# fxlink

5. When the script finishes, new interface executables are deposited in the fxlink directory. Copy these executables to the $PIHOME/interfaces/fxbais directory, overwriting those backed up in step 2 above.# cp fxbais ..# cp fxforcex ..# cp fxapisup ..Modify Startup and Shutdown Scripts

The startup and shutdown scripts, sitestart and sitestop, as well as the script fxbais.sh should be modified as outlined in the “Starting and Stopping the OSI Interface” on page 7.

Automatic Startup

It may be desirable to have the PI-API and the AP51 interface start up automatically when the Sun is booted. Foxboro provides guidance for this in their Foxboro System Administration II course notes. The file /etc/fox/rc.foxboro runs at bootup and calls a script called /usr/fox/bin/fox_apps which is used to start the standard configured Foxboro applications. This script consults a file called fox_apps.dat in /usr/fox/bin which contains a list of names. These names are prepended with the text “go_” and a Bourne shell script of this name is launched.

To start the PI-API and the interface in this manner:

1. Add a line containing just the word pistartup to the end of the file fox_apps.dat.

2. Then create a Bourne Shell script called go_pistartup.

Note You may need to start the Foxboro AIS first in this script if your system is not already set up to start AIS. The example below does this:

#

# Initialize the PI system startup variables and start AIS

#

setenv FOXAISHOME /opt/fox/ais/bin

#

# Test to see if aisstart routine exists

#

if test -f /opt/fox/ais/bin/aisstart

then # Initialize start it

/opt/fox/ais/bin/aisstart

fi

#

setenv PIHOME /opt/pi

setenv LD_LIBRARY_PATH /opt/pi/lib

#

# Test to see if pistart exists if yes then start it

#

if test -f /opt/pi/bin/pistart

then #

sh /opt/pi/bin/pistart

fi

Make sure the script is executable by root.

For further assistance on this procedure contact your Foxboro representative.

Troubleshooting Tips

1. When starting fxbais.sh, receive the messages “File ais_max.out not found, using default”, “Waiting for central to start”

This generally indicates that the Foxboro AIS software is not running. Try running aistst usually in the directory /opt/fox/ais/bin. If the same messages appear this indicates the AIS system is not behaving properly.

2. When attempting to stop the interface, the process fxbais is not killed.

Ordinarily you should stop the interface with the script fxastop or stop the entire API and interface with pistop. If this doesn’t work you can kill the fxbais process by finding the process number and killing it with a -9.

# ps -ef | grep fxbais // returns process number at left

# kill -9 xxx // xxx = process number from above.

Note that when the process is killed in this way, it has not properly unregistered from the AIS system. You must stop and restart AIS before restarting the interface for the interface to work properly.

3. When starting fxbais, error messages regarding file opening are received from the library loader.

ld.so.1: fxbais: fatal: libPI-API.so: can’t open file: errno=2

Killed

This indicates that the loader cannot find a library. In the above message, when running fxbais the loader cannot find libpiapi.so. Set the environment variable LD_LIBRARY_PATH to point to the $PIHOME/lib directory.

For C shell:

% setenv LD_LIBRARY_PATH {$PIHOME}/lib

or to extend and existing LD_LIBRARY_PATH

% setenv LD_LIBRARY_PATH {$LD_LIBRARY_PATH}:{$PIHOME}/lib

If you are running SunLink DNI, this path must also include the DNI libraries:

% setenv LD_LIBRARY_PATH $PIHOME/lib:/opt/SUNWconn/dni/lib

4. When starting fxbais, loader error messages indicating “unsatisfied externals” or “symbol not found” are received.

This indicates that the shipped executables are incompatible with the system’s installed shared libraries. Relinking the executables usually fixes this. To relink the executables follow the steps outlined in section 3.1.1

5. When starting fxbais error messages concerning not finding libC are displayed.

ld.so.1: ./fxbais: fatal: libC.so.5: can’t open file: errno=2

or

ld.so.1: fxapisup: can’t find file libC.so.5

If you are on a Solaris 2.2 machine (Sun OS 5.2) you will need to relink. See section 3.1.1

Look for a libC.so.5 on your system

# find / -name libC.so.5 -print

You should find one from the installation in $PIHOME/interfaces/fxbais/fxlink/libC.so.5 and possibly one already installed on the system. Make sure the system has a path to the library by either copying it to /usr/lib or adding its location to the LD_LIBRARY_PATH in “Extracting Files” on page 21.

6. Unable to write to files sitestart and sitestop.

Logged in as the owner of these files (typically root) execute the following command

chmod u+w sitestart

chmod u+w sitestop

7. On Solaris 2.2 when relinking receive messages

start fxbuild - build file for Foxboro IA (AIS) interface/Sun SPARC

linking fxbais for AP51 series

Undefined first referenced

symbol in file

thr_keycreate ./libC.so

mutex_lock ./libC.so

thr_self ./libC.so

thr_getspecific ./libC.so

Remove -lC from the link command.

8. Unable to read from the Solaris II floppy drive.

Use ps to look for the vold process

ps -ef | grep vold

If the process is not found, start it by

/etc/init.d/volmgt start

In either case, run volcheck

volcheck

Then stop vold

/etc/init.d/volmgt stop

At this point you should be able to address the device rdiskette. To look at the contents type

tar -tvf /dev/rdiskette

OSI Software, Inc.

1/30/2006 3:06:00 PM23