OSI PINET DECNET

OSI Software, Inc.

How to Contact Us
Phone Fax Internet World Wide Web Bulletin Board (510) 297-5800 (510) 297-5828 (510) 357-8136 techsupport@osisoft.com http://www.osisoft.com (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 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 (main number) (technical support)

Mail

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 statementPI 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. 84314134.doc

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

10/15/2004 10:48:00 AM

ii

Table of Contents
OSI PINET DECNET................................................................................................................i How to Contact Us..................................................................................................................ii Table of Contents...................................................................................................................iii Introduction.............................................................................................................................1 Installation and Upgrades.......................................................................................................2 Directories...............................................................................................................................3 Startup and Shutdown............................................................................................................4 Satellite Node Utilities.............................................................................................................5 IORates Tags..........................................................................................................................6 Shutdown Events....................................................................................................................7 Satellite Node Processes........................................................................................................8 Toolkit.....................................................................................................................................9

January 9, 1997

iii

Introduction
This chapter describes the software that supports distributed applications for a PI System. The distributed applications are usually interface programs which run in a VAX which is connected by DECnet to a PI System. These applications can also be programs developed with the PI Toolkit. The DECnet node with the distributed application program is called the satellite node. The node with the PI System is called the home node. There can be several satellite nodes connected to a PI home node. The software on the satellite node is a subset of a full PI System. Programs on the satellite node can read the following data: Point Attributes (Tag, Description, Zero, Span, etc.) Snapshot Archive Engineering Unit Strings Digital State Strings Point Source Table

The satellite node can also send values and messages to the home node. The previous chapter lists the routines from the PI Toolkit library which are supported on satellite nodes. The satellite node set its system time to match that of the home node. It compares its system time to that of the home node every hour. The satellite node time is updated if it is different from the home node time by more than 10 seconds. Process PINetSync performs this check and writes a message to PINet:PIMessLog.txt whenever it changes the VMS time. The satellite node can buffer data for times when PI is not running on the home node or the network is down. The satellite node can be restarted even if PI is not running on the home node.

January 9, 1997

OSI PINET DECNET

Installation and Upgrades

Installation or upgrade instructions are included with your PI distribution kit. Install PI on the home node before installing PINet. If this is a new PINet System for an existing home node, upgrade PI on the home node before installing PINet. Backup your PINet computer before installing PINet. You may have to Sysgen your computer as part of the installation. Allow 2-3 hours for the installation procedure. The number of free blocks on the target disk should be at least 25000 + 0.7 * the maximum number of points on the home node. Use the System account for the installation. The point database and several smaller files are copied from the home node when the PINet node is installed. Make sure the DECnet connection to the home node is working and the PIServer account is available on the home node before installing PINet. For upgrades, upgrade your PI System before the PINet upgrade. You may have to Sysgen your computer as part of this procedure. Allow 1-2 hours for the upgrade procedure. The number of free blocks should be at least 25000 + 0.2 * the maximum number of points on the home node. PINetStart.com and PINetStop.com are overwritten by the upgrade procedure. PINetNames.com, SiteStart.com, and SiteStop.com are not touched on an upgrade since they contain site-specific configuration information. If you have user-written programs, create a file named PINet:SiteSpecificLink.com with the link commands for those programs. These programs will then be automatically relinked on a PINet upgrade.

OSI Software, Inc.

Directories
There are two pertinent directories on the satellite node, PINet and PINetBuild. These are system logical names that usually translate to global directories [PINet] and [PINetBuild]. The PINet directory includes files that are found in the PISysExe, PISysMgr, and PISysDat directories on the home node. The PINetBuild directory combines the PIBuild and PILink directories of the home node. Directories PINet PISysEx e PISysMg r PISysDa t PINetBuil d PIBuild PILink

January 9, 1997

OSI PINET DECNET

Startup and Shutdown

On the home node, PISysMgr:PIStop.com renames PISysExe:PIServer.com to PIServer1.com during shutdown. PISysMgr:PIStart.com also renames the file after a system crash. After the PI data blocks have been loaded into memory, PIStart.com renames the file back to PIServer.com. If the PI System is shut down on the home node, tasks on satellite nodes periodically try to connect to a PIServer task. Since the PIServer program cannot run (because the shareable images are not installed), the connect requests fail. There is a NetServer.log file in directory PISysExe on the home node for each connect attempt. These files are purged by PIServer.exe On the satellite node, PINet:PINetStart.com and PINet:PINetStop.com are the startup and shutdown command files. The home node PI System must be running the first time the satellite PI System is started. After that, the satellite PI System can be started when the home PI System is not running. The startup command file executes PINet:PINetNames.com. This command file defines the logical names for the satellite system. The file contains a symbol for the DECnet name of the home node. The startup command file also installs the PITables, PICRTShare, and PIELShare shareable images. These are the same as the shareable images on the home node. The startup command file starts the batch job which creates a new version of the PI log file every midnight. The PI log file, PIMessLog.txt, is in directory PINet. PINetStart.com and PINetStop.com are generic procedures that should not be edited. Put site specific instructions (such as interface start and stop commands) in PINet:SiteStop.com and PINet:SiteStop.com.

OSI Software, Inc.

Satellite Node Utilities

Four utility programs and a utility command file run on the satellite node at the DCL prompt. Program PINet:IOMonitor displays the value of the counters for every tag in PINet:IORates.dat. It then displays rates in events per second at the user specified update interval. Program PINet:Snap runs as a DCL command. Type $ Set Command PINet:Snap to add "Snap" to your command set. Then type $ Snap tagname where "tagname" is the name of a tag. This program displays the snapshot value for that tag. If the data for the tag are being collected on the satellite node, the snapshot is retrieved from the local snapshot. Otherwise, the snapshot is retrieved from the home node. Program PINet:QWatch shows the status of the snapshot event queue on the satellite node. The display is the same as the one on the home node Queue Watch program QPtr = 207 QEnd = 208 OverPtr = 759 OverEnd = 759 OFlag = 0 UseFlag = 0 Events in memory = 1, 0.050 percent full No values on disk QPtr, QEnd, OverPtr, and OverEnd are pointers to the beginning and end of the two memory-resident segments of the queue. OFlag is 0 or 1 if the queue is entirely in memory. OFlag is 2 if the queue has overflowed onto disk. The name of the disk file is PINet:EventQ.dat. Program PINet:EVMDump displays the status of the Event Manager. The Event Manager is used by some interface programs plus any programs which use the EVM toolkit routines. The command file PINet:PINetVerify.com shows the status of the PINet node. Run this utility as a first step in debugging PINet problems. Along with a display of some status information, it displays warnings if some of the necessary PINet processes are not running if the home node is unavailable if the PINet protocol version of the home node is not compatible.

January 9, 1997

OSI PINET DECNET

IORates Tags
The IORates tag for an interface program works the same as on a home node. The only difference is that the tag should be put in PINet:IORates.dat on the satellite node instead of PISysDat:IORates.dat on the home node. Three other rate tags can be defined which have to do with satellite nodes. On the home node, a tag can be added to IORates.dat to record the rate of events from all the satellite nodes. This tag uses counter number 42. Add a line to IORates.dat that looks like: SY:SRV001,42 On the satellite node, tags can be added to IORates.dat to record the snapshot rate (event counter 47) and the rate that the Event Manager is sending events to programs using the EVM routines (event counter 46). These are the same counter numbers that are used on the home node but the tag names must be different.

OSI Software, Inc.

Shutdown Events
The satellite node should add shutdown events for tags for which it collects data. Modify PINet:ShutdownEvents.com and PINet:CheckForCrash.com to add shutdown events for those tags. All satellite nodes add shutdown events for the tags in IORates.dat. Most satellite nodes also add shutdown events for tags with the point source code for the distributed interface program. The last non-comment line in each command file looks like: $ ShutDownEvents 'TimeDate',PINet:IORates.dat,F On the home node, modify PISysExe:ShutdownEvents.com and PISysExe:CheckForCrash.com to avoid adding shutdown events for tags from the satellite node. The PI System on the home node can shutdown and restart without losing data from the distributed interface.

January 9, 1997

OSI PINET DECNET

Satellite Node Processes

Several processes run on the satellite node to support the distributed interface program. The interface program puts events into the event queue with routine PutSnapshot. An exception report server process retrieves events from the event queue and sends them to the home node. The PIServer process on the home node puts the events in the snapshot and archive on the home node. The process name of the exception report server process is "ExceptServ". An event queue manager process maintains the event queue as a virtual queue. This process shuffles events to disk when the memory portion of the event queue fills up. It moves the events from disk to memory when the memory portion of the queue contains enough free space. This process has the same name as the analogous process on the home node: "QManager". The "IORates" process calculates ten minute averages of the rates specified in PINet:IORates.dat. This process is the same as the one on the home node. The satellite node has its own set of event counters for use by interfaces on this node. Counter number 47 is used for the rate of PutSnapshot calls on this node. (On the home node, counter 47 is also used for the snapshot rate.) The "SaveSnapshot" process writes the local copy of the snapshot value for each tag to a file. This is the same as the process on the home node. The "PINetSync" process maintains accurate copies of the point attribute file, engineering unit string file, digital state string file, and point source file on the satellite node. This process also synchronizes the time with the home node. The "PIEVManager" process maintains queues of exception reports for programs which sign up for them. This is the same as the process on the home node. This process retrieves exception reports from the home node if necessary. The satellite PI System talks to the home PI System via transparent DECnet task-to-task communication. The format of the messages passed between the nodes is referred to as the PINet protocol. According to this protocol, the processes on the satellite node send commands. PIServer processes on the home node reply to those commands. With DECnet transparent task-to-task communication, there is one PIServer process on the home node for each satellite process which sends commands. The PIServer process starts on a DECnet connect request from the satellite process. The network access uses a PIServer user account. This account is restricted to network logins only (see PIBuild:AddPIServerUser.com on the home node). PIServer processes wait for commands from the satellite node and send the appropriate replies. They exit if they do not receive any commands for 30 minutes. The process name of each PIServer process on the home node is NNNNNN:SSSSIIII where NNNNNN is the node name of the satellite node, SSSS is a name passed from the satellite node (defaults to "Serv" if the program does not use routine PIConnect to declare a name), and IIII is the hexadecimal process identification number of the process on the satellite node (least significant digits).

OSI Software, Inc.

Toolkit
The Interface Standard chapter of this manual lists the PI Toolkit routines which work on PINet nodes. Also, the PI Toolkit manual shows with each routine whether or not it is supported on PINet nodes. PINet nodes keep track of which points are being collected on that node. The first time a value is sent to PI for a tag (with PutSnapshot or PISendExceptions), a flag is set. This flag is reset only when PINet is restarted. Routine GetSnapshot uses this flag to determine whether to retreive the snapshot value locally or whether to make a network read to retrieve a snapshot value from the home node. This prevents unnecessary network traffic for applications which use only points collected on the PINet node. This may cause a problem if a point is updated both from the PINet node and from the home node. When routine GetSnapshot is used with one of these points, the value returned will be the most recent value entered from the PINet node. Routine PINetGetSnapshot has the same calling sequence as GetSnapshot but always makes a network read from the home node to ensure that it is returning the most recent value for a tag. This routine should be used only in programs which run on a PINet node look at snapshot values for tags with GetSnapshot are using tags which are receiving values from the PINet node and some other node.

If some tags are collected locally and some tags are updated from the home node, GetSnapshot works fine. PINetGetSnapshot is necessary only when tags receive values from multiple sources.

January 9, 1997