SIEMENS TELEPERM-XP
Interface to the PI System
Version 1.01 and greater
OSI Software, Inc.
How to Contact Us
Phone
(510) 297-5800
(510) 297-5828
(main number)
(technical support)
Fax
(510) 357-8136
Internet
[email protected]
World Wide
Web
http://www.osisoft.com
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
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland
OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand
Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of 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.
STELPMXP.DOC
 1997 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction ............................................................................................................................ 1
PI Point Configuration ............................................................................................................ 2
I/O rate counter ...................................................................................................................... 4
Interface Files......................................................................................................................... 5
Installation .............................................................................................................................. 6
Linking the program ............................................................................................................... 7
Startup ................................................................................................................................... 8
Shutdown ............................................................................................................................. 10
Error and information messages .......................................................................................... 12
How the TXP via OM650 to PI Interface operates ................................................................ 13
The control program ompictrl ............................................................................................... 15
Hints for PI System Manager................................................................................................ 16
Before reboot of HP-UX: .................................................................................................. 16
Test Environment ................................................................................................................. 18
January 9, 1997
iii
Introduction
The TXP via OM650 to PI Interface (OM Interface) provides the read transfer of data between
an TXP process control system and the Plant Information (PI) System across a OM-Gateway
using a special data collect process on OM-Gateway.
The from SIEMENS AG makes available data collect process transforms all TXP events into
ASCII-format and write the data on a named pipe. The PI Interface running on HP-Gateway
reads the event string from the named pipe and makes internal use of the PI-API in order to
keep a standard way of interfacing from a client node to the PI Home node System.
Data are processed using TXP events these are converted from a process on OM-Gateway into
strings. The interface supports the following event types:
Event Types
Analog Input
AI
Counter Input
CI
Digital Input
DI
The data will transmit continual. The timestamps from TXP will take over by interface and will
converted into PI servertime for sending to archive.
The demands of transfer are described in detail in:

SIEMENS report to DIDCOT B, connection of a VAX IS-System to OM 650, Karlsruhe
14.06.95; author Enneker

SIEMENS report to DIDCOT B, specification of VAX interface, „Data acquisition - data
transformation“, Erlangen 27.09.95; author Gruen
Supported Features
January 9, 1997
Sign up for Updates
yes
Exception Reporting
yes
PI API Support
yes
Outputs
yes
Vendor Software Required
yes
Number of Points
unlimited
1
SIEMENS TELEPERM-XP Interface Documentation
PI Point Configuration
The following database details are necessary to configure a PI tag for use with the OM650 to
PI Interface.
Tag Name
The tag name can be chosen according to the normal PI tag naming conventions. It is favorable
to use the TXP address, shorted to 10 characters :
function region
2 characters
instance number
4 characters
I/O number
4 characters
Extended Descriptor
The Extended Descriptor is free for additional information of the tag.
Zero, Span
The values should be the same as the corresponding fields in TXP. Especially there are the
attributes RANGE_MIN and RANGE_MAX for analog objects zero and span should
correspond with.
Point Source
The point source is a single character, for example O (OM), but according to startup parameter
and point source settings in PI. The point source must be defined in the point source library
before point configuration.
Point Type
The Interface supports the PI point types R (real), I (integer) and D (digital). For points of type
R high precision storing is supported, i.e. 32 bit floating point data and integers in the range up
to 16,000,000.
Engineering Units
The Engineering Units should be used according to the meaning of the measured values.
Scan Flag
This is usually ON for all points of this interface. If you edit this point attribute to OFF while
the interface is running, the tag becomes OFFLINE (no
values are exchanged for this
tag). In this case a “OFFSCANSTAT” event will be sent to the archive.
2
OSI Software, Inc.
Instrument Tag
This is the object address used in TXP. It is the only information needed to address the OM
tag. This name is exact 12 characters long and will therefore always fit into the Instrument tag
field with its length of 32 characters. The name consists of three parts:
function region:
4 characters
instance number:
4 characters
I/O number:
4 characters
Between these parts are not delimiters. All parts of address represents an hexadecimal integer
filled with zeros.
Examples for OM Instrument tagname:
00FF0B16000A
000E1FFE00FF
Location 1
Location 1 contains the interface number. If multiple Interfaces are used, this is the way to
group tags to get values from a specific OM-Gateway via a specific pipe.
The Interface does not use the following tag attributes
January 9, 1997

Square root code

Totalization code

Conversion factor

Location 2-5
3
SIEMENS TELEPERM-XP Interface Documentation
I/O Rate Counter
The I/O rate counter measures the rate of exchanged data between the PI Interface process and
the OM process. Configure the rate counter as PI tag, using SY:SNP001 as a template. Then
insert the line
SY:OM001,n1
in the file $PIHOME/dat/iorates.dat, where n1 is the counter number passed via the “/ec=...”
parameter in the command line described below (section „Startup“). Use a free number
between 1 and 34.
SY:OM001 reflects the rate of exchanged data.
4
OSI Software, Inc.
Interface Files
The file for the interface reside in the ./om650/bin directory.
Interface Files
om650pi
interface
ompictrl
control program
The files to link the Interface reside in ./om650/bin directory

om650pi.o

ompictrl.o
and in . /om650/etc directory
January 9, 1997

ompictrl.mak

ompictrl.mak
5
SIEMENS TELEPERM-XP Interface Documentation
Installation
Before installing the interface itself, you must install the PI-API for the HP-UX operating
system. Refer to the PI-API-HP-UX Installation manual for more information.
To prepare PI for interface:
6
1.
Use you must define a point source code
2.
Select one I/O rate counter (in iorates.dat) and
3.
Modify the PI startup and shutdown command files. You can optionally specify one
performance monitoring tag as shown in section „I/O rate counter“.
4.
Modify the following settings using the PI System Point Source Editor:
Point Source Code: O
Point Source Descriptor: TXP across OM Gateway
Loc 1
Loc 2
Loc 3
Loc 4
Loc 5
Location Minimum
1
0
0
0
0
Location Maximum
3
0
0
0
0
OSI Software, Inc.
Linking the Program
The interface program should be relinked whenever the PI-API-HP-UX is relinked by
executing the sitelink script $PIHOME/build/pi.install. To relink just the OM 650 Interface,
execute
cd /om650/bin
make -f /om650/etc/om650.mak
make -f /om650/etc/omctrl.mak
if the API is not available, link will fail. All files will be moved to the according directories.
Make sure the PI-API is running when you perform the link procedure.
# (#)om650pi.mak 1.1 13-nov-95
#
#
#
ROOT
= /
SHELL
= /bin/sh
PIHOME = /pi
USER
= /om650
EXEC
= $(USER)/bin/om650pi
CC
= cc
LIBS
= -L$(PIHOME)/lib
EXTLIBS = -lpiapi -lm
OBJECTS = $(USER)/bin/om650pi.o
$(EXEC): $(OBJECTS)
$(CC) $(OBJECTS) $(LIBS) $(EXTLIBS) -o$(EXEC)
# (#)ompictrl.mak
1.1 13-nov-95
# ompictrl.mak
#
#
ROOT
= /
SHELL
= /bin/sh
PIHOME = /pi
USER
= /om650
EXEC
= $(USER)/bin/ompictrl
CC
= cc
LIBS
= -L$(PIHOME)/lib
EXTLIBS = -lpiapi -lm
OBJECTS = $(USER)/bin/ompictrl.o
$(EXEC): $(OBJECTS)
$(CC) $(OBJECTS) $(LIBS) $(EXTLIBS) -o$(EXEC)
January 9, 1997
7
SIEMENS TELEPERM-XP Interface Documentation
Startup
To start the interface manually, log in as SUPER USER and enter this command:
cd /om650/bin
om650pi P1 P2 [P3] P4 [ P5 P6 P7 P8] &
where:
P1= /nn=PI Home node name
required
P2= /ps=point source
required, (O)
P3= /in=Interface number
optional,
default: 1
P4= /fifo=complete pipe name (path/name)
required,
P5= /recnum= number of records, that will be readoptional,
from pipe with one reading call
default: 1000
P6= /ec=input rate counter number (1 - 34)
optional,
default: 23
P7= /so=„Scan Off“ number Digital State Table
optional,
default: 238
P8= /deb=debug level
optional,
default: 0
PI Points
8
P1
Node Name. Parameter P1 is required to specify the PI Home node the PI system runs on.
P2
Point Source. Specify the point source of the tags the interface will operate on here.
P3
Interface Number. It is possible to run multiple interfaces on one node. The interface
corresponds to location 1 of a tag. All tags with location 1 = P3 will be serviced by that
interface.
P4
Fifo Name. Parameter P4 is required to specify the named pipe for reading data from HPGateway.
P5
Number of records that will be read from pipe with one reading call. The reading function is
waiting for these number of strings in pipe.
P6
Event counter. This is the number of a free slot in iorates.dat.
P7
A Scan Off digital state should be defined in the Digital State Table. P7 informs the interface
about the corresponding number in the Digital State Table so that it could make use of this
number. The recommended value (fits with other interfaces) is 238.
P8
Debug. This is the optional debug level (0-5). It defaults to a value of 0 which means no
additional output to be sent to the output device. Greater values result in more output
information.
OSI Software, Inc.
The connection from pipe, which is defined in P4, with a pipe on OM-Gateway must be started
with the remsh command:
remsh host [-l username] command
remsh connects to the specified host and executes the specified command. The host name can
be either the official name or an alias. The remote account name used is the same as your local
account name, unless you specify a different remote name with the -l option. This remote
account name must be equivalent to the originating account.
remsh otherhost -l otheruser "cat remotepipe" > localpipe &
appends the output of remotepipe to the local pipe localpipe.
otherhost
hostname of OM-Gateway
otheruser
user of remotepipe
remotepipe
name of pipe on OM-Gateway (complete path)
localpipe
name of pipe on HP-Gateway (complete path)
An example of a script with a special call of remsh is /om650/etc/writepipe.
To automate startup, you may edit $PIHOME/bin/sitestart . An example for starting an
interface can be found in /om650/etc .
###############################################################################
# File: sitestart
#
# This file is provided to allow site specific applications to be started
# whenever the pistart is executed. An appropriate application stop script
# should be inserted into the sitestop file.
#
##############################################################################
echo "Start om650 to PI Interface"
CURRENTDIR=$PWD
cd /om650/etc
# start an interface
sh piifcstart0
# connect with pipe on remote node (OM-Gateway)
sh writepipe
echo "TXP via OM650 to PI interface started"
cd $CURRENTDIR
January 9, 1997
9
SIEMENS TELEPERM-XP Interface Documentation
Shutdown
To shutdown one certain interface, use the following command:
kill PID
where PID is the identification number of the interface process. This number can be found out
using the command
ps -ef
You can also use the control program ompictrl. Start the program and input 3 for shutdown
interface. The control program activate a call of kill command. End the control program with q
(quit). The kill command will send the SIGTERM signal to the process. The interface will
handle this signal properly, so all necessary operations such as canceling requested
subscriptions for transfer, giving a SHUTDOWN state to all tags etc. are performed.
To automate startup, you may edit $PIHOME/bin/sitestart . An example for stopping an
interface can be found in /om650/etc .
################################################################################
# @(#)sitestop 1.2 09/05/95
# File: sitestop
#
# This file is provide to allow site specific applications to be stopped
# whenever the pistop is executed. An appropriate applications start script
# should be inserted into the sitestart file.
#
################################################################################
echo "Stopping PI Interfaces..."
#
# Set ps arguments
PSARG=-ef # -cx for solaris 1
#
# Remember Current Directory and Change to $PIHOME/bin
#
CURRENTDIR=$PWD
cd $PIHOME/bin
#
# Stop Applications
#
pid=`ps $PSARG | grep 'om650pi' | grep -v grep | awk '{ print $1 }'`
if [ "$pid" != "" ]; then
echo "Stopping TXP via OM650 Interface"
kill $pid
else
echo "The om650pi NOT Found"
fi
10
OSI Software, Inc.
pid=`ps $PSARG | grep 'writepipe' | grep -v grep | awk '{ print $1 }'`
if [ "$pid" != "" ]; then
echo "Stopping TXP via OM650 Interface"
kill $pid
else
echo "The writepipe NOT Found"
fi
cd $CURRENTDIR
echo "Interface Shutdown is Complete"
January 9, 1997
11
SIEMENS TELEPERM-XP Interface Documentation
Error and Information Messages
You can find messages from the interface in three places:
The PI message log, $PIHOME/dat/pimesslogfile. The interface puts its error and information
messages into this file except for messages from fatal errors that prevented the interface from
starting up.
The interface output file, /om650/log/om650pi.logn (n correspond with interface number =
parameter P3). All fatal error messages are copied to this file. The interface also copies
selected messages and debug information to this file.
The interface output file, /om650/log /ompictrl.msg. All TXP-addresses these not correspond
with a PI tag. You can create this file with the control program ompictrl. (Start the program and
input 2 for transfer the list of TXP tags without correspond PI tags to the file).
Errors related to tag values will also be reported by giving the tag a BAD INPUT state. This
happens, if the status of a value derived from TXP is BAD. The table describes the handle of
TXP quality status. PI status will send to archive.
12
TXP Quality Codes
Bit of Status Value
PI Status
DEFAULT_VALUE
1,
valid value
UNCALIBRATED
2,
valid
MANUALLY ENTERED
3,
valid value
TEST_MODE
4,
valid value
INTERPOLATED
9,
valid value
OUT_OF_RANGE
0,
BADDATASTAT
UNKNOWN_ADDR
8,
BADDATASTAT
NO_DATA
5,
NODATASTAT
UNDEFINED_ERROR
7,
BADSTAT
HARDWARE_ERROR
6,
ERRORSTAT
OSI Software, Inc.
How the TXP via OM650 to PI Interface
Operates
At startup, the Interface checks all command line parameters. If one of them is out of range and
cannot be filled with a default value, the interface generates an error message and stops. If the
parameters are all right, the interface runs the initialization part. Here it assigns the specified
named pipe. If a connection is not establish immediately, the interface will terminate them self.
A list of all tags with the interface point source and configured for this special interface number
is collected. Event counters are initialized and finally, a sign-up-for-updates operation is
performed to recognize changes in the point database.
Data Acquisition
Data are exchanged between TXP process objects and the corresponding PI tags by performing
attribute operations.
Input
Data are delivered via named pipe. The pipe provides a lot of strings witch contain the
information of TXP event. The length of strings is constant 41 characters include end sign \0.
string[0]
% as begin sign
string[1...11]
timestamp of TXP event
string[1...8]
number of seconds since
0:00:00.000 (UTC)
string[9...11]
number of milliseconds not used from
interface
01.01.1970
string[12...23] TXP address (corresponds with tagname)
string[12...15] number function region
(hexadecimal)
string[16...19] Instance number (hexadecimal)
string[20...23] I/O number (hexadecimal)
string[24...27] quality code of TXP event (hexadecimal)
string[28]
signal type 1 for analog; 2 for
counter; 3 for digital, other values
will recognize as failure and leads to
turning away of value
string[29...39] value of TXP event
string[29]
sign of mantissa; ‘ ‘ means positive
string[30]
integer part of mantissa (decimal)
string[31]
‘.’
signal type = 1
string[32...35] broken part of mantissa (decimal)
string[36]
January 9, 1997
‘E’
13
SIEMENS TELEPERM-XP Interface Documentation
string[37]
sign of exponent; ‘+’ means positive
string[38...39] exponent to base 10 (decimal)
string[29]
sign; ‘ ‘ means positive
string[30...39] integer value (decimal) <= 32767
string[29]
signal type = 2
‘1’ for TRUE;
signal type = 3
‘0’ for false
string[30...39] blank
The interface tests the signal type. Values with a other signal type as 1,2,3 are not transmitted
to PI system. A information will write to logfile. If more then 200 times one after the other the
signal type is false will suppose a shift of while writing or reading strings. An additional
information will write to logfile.
The signal type of TXP event and PI tag should correspond, but it is not required. Interface
transmits analog, digital and counter values to a PI tag that is configured as real. If a analog
TXP value correspond with a integer or digital PI tag, the interface writes to PI archive a
BADINPUTSTAT. The interface also transmits digital and counter (not analog) values to
digital and integer PI tags. Note, that the value of a as integer configured PI tag must be <=
32767. Counter values > 32767 can only transmit to a as real configured PI tag.
Evaluate the TXP quality code, see 9. Error and information messages.
Output
Output of data in direction OM-Gateway is not supported on the interface
Timestamps
All values are sent to the archive using the received timestamps of TXP system. Hours of this
UTC timestamps will transformed to the (local) PI servertime if UTC timestamp is greater then
the local timestamp of PI system. Minutes and seconds of TX
Sign-up for Updates
The interface program periodically checks alterations of the point database and performs the
necessary operations such as adding, editing and deleting of tags. The period of the check is
about one minute.
14
OSI Software, Inc.
The Control Program ompictrl
The control program ompictrl can run simultaneous with the interface for manage some
additional information from interface. ompictrl builds a connection via message box with the
interface and sends the selected message to interface.
Start control program
cd /om650/bin
ompictrl [ /IN=n ]
where n = Interface number of interface with which
Default is interface number 1.
For selection a message will be output :
1 Delete all missed tags
2 Transmit missed tags to file
3 Shutdown interface
q Quit
om650ctrl build a connection.
The interface collects all TXP addresses without a corresponding tag in PI database. That
means the expression „missed tag“. With message 2 the actual list of this missed tags will be
written to the logfile /om650/log/ompictrl.msg. With message 1 the list of this tags will be
deleted in interface. The interface begins to collect a new list, without the tags, which
configured meanwhile. Message 3 has the same effect like kill command. Leave ompictrl with
q.
January 9, 1997
15
SIEMENS TELEPERM-XP Interface Documentation
Hints for the PI System Manager
Before Reboot of HP-UX
Stop the PI-API with $PIHOME/bin/pistop.
If file /pi/bin/sitestop is actualized (see 8.) interface also will be stopped.. The shutdown of pi
API and the interface can automate:
Create a file /etc/shutdown.d/runpistop
################################################################################
# @(#) runpistop 1.1 17/11/95
# File: runpistop
#
#
###############################################################################echo
"Stopping the PI API"
echo
USER=root
export USER
PIHOME=/pi
export PIHOME
cd $PIHOME/bin
./pistop
All files in directory /etc/shutdown.d will be executed while shutdown system.
After Reboot of HP-UX
1.
Check if PIServer is alive
e.g. apisnap tagname
2.
Startup PIClient
USER=root
Export USER
PIHOME=/pi
export PIHOME $PIHOME/bin/pistart
If file /pi/bin/sitestart is actualized (see 7.) interface also will be started. The startup of pi API
and the interface can automate:
16
OSI Software, Inc.
Create a file /etc/rc.pi
################################################################################
# @(#) rc.pi 1.1 17/11/95
# File: rc.pi
#
#
###############################################################################
echo "start pi routines"
USER=root
export USER
PIHOME=/pi
export PIHOME
nohup $PIHOME/bin/pistart &
Edit /etc/rc and input in function localrc() the line
/etc/rc.pi &
January 9, 1997
17
SIEMENS TELEPERM-XP Interface Documentation
Test Environment
PIHome
VMS 5.5-2
UCX
PI 2.0.7
HP-Gateway
HP-UX 9.0
HP-UX Debugger XDB 09.01
HP C HP 92453-01 A.09.69
TCP/IP
OM-Gateway
SCO-Unix
18
TCP/IP
OSI Software, Inc.
Revision History
Date
Author
Comments
Apr 96
DBS
First version for Beta release
1 Jul 96
LFM
Modified installation section. Add information about
SEMapi linking. Changed link option to SC and DA instead
of VAX and ALPHA. Add description of link warning
messages related to UCX.
7 Oct 96
January 9, 1997
LFM
Added fail over description, new extended attributes for
analog points and station status. Removed time alias
discussion. Editing station points is no longer a problem.
19