API Install

PI-API Installation Instructions
Version 1.4.0.3
April 2013
How to Contact Us
Phone Fax E-mail World Wide Web Mail (510) 297-5800 (main number) (510) 297-5828 (technical support) (510) 357-8136 techsupport@osisoft.com http://www.osisoft.com OSIsoft P.O. Box 727 San Leandro, CA 94577-0427 USA OSI Software GmbH Hauptstrae 30 D-63674 Altenstadt 1 Deutschland OSI Software, Ltd P O Box 8256 Symonds Street Auckland 1035 New Zealand OSI Software, Asia Pte Ltd 152 Beach Road #09-06 Gateway East Singapore, 189721
Unpublished -- rights reserved under the copyright laws of the United States. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 Trademark 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.
138022636.doc
Table of Contents
How to Contact Us..........................................................................................................iii Table of Contents...........................................................................................................iii Introduction to the PI-API................................................................................................1 Microsoft Windows Installation.....................................................................................3 Installation.....................................................................................................................3 Debug Symbolic Information.......................................................................................4 Initialization files...........................................................................................................4 Node Identifiers............................................................................................................6 Log File Utility...............................................................................................................7 Event Counters.............................................................................................................7 UNIX Installation..............................................................................................................9 UNIX Installation Procedures......................................................................................9 System Configuration..............................................................................................9 Extracting Distribution Files.................................................................................10 Running the Installation Script.............................................................................11 UNIX Post Installation................................................................................................11 Preparing Site-specific Applications....................................................................12 Configuring TCP/IP.................................................................................................12 Configuring the PI Server......................................................................................12 Setting Default PI Home Node...............................................................................12 Event Counters.......................................................................................................13 Starting and Stopping PI........................................................................................13 Purging Log Files...................................................................................................14 Solaris .........................................................................................................................15 Extracting Distribution Files.................................................................................15 Incompatability with Previous PI-API Versions...................................................16 System Files Redistributed...................................................................................17 IBM AIX RS/6000.........................................................................................................17 Extracting Distribution Files.................................................................................17
PI-API Installation Instructions iii
Linking.....................................................................................................................17 System Files Redistributed...................................................................................17 HP-UX 10.x and 11.x...................................................................................................17 Extracting Distribution Files.................................................................................18 Incompatability with Previous PI-API Versions...................................................18 Linking.....................................................................................................................19 System Files Redistributed...................................................................................19 Compaq UNIX (Tru64)................................................................................................19 Extracting Distribution Files.................................................................................20 System Files Redistributed...................................................................................20 Linux............................................................................................................................21 Extracting Distribution Files.................................................................................21 Upgrading an Existing Installation.......................................................................21 PI System Errors............................................................................................................23 System Errors.............................................................................................................23 Point Attribute Access Errors...................................................................................23 EVM Routine Errors....................................................................................................24 Archive Access Errors...............................................................................................25 PI Login Services Errors............................................................................................25 Buffering Errors..........................................................................................................26 PINet Errors.................................................................................................................26 apisnap Utility.............................................................................................................26 PI Server Support for Remote Access.........................................................................27 PI on Windows NT and UNIX.....................................................................................27 PI on OpenVMS...........................................................................................................27 Remote Nodes............................................................................................................27 Network Protocol........................................................................................................27 TCP/IP for PI on OpenVMS........................................................................................27 Listener Installation....................................................................................................28 PI on Windows NT and UNIX.................................................................................28 PI on OpenVMS.......................................................................................................28 PI Server VMS User....................................................................................................28 Server Security...........................................................................................................29 PI on Windows NT and UNIX.................................................................................29 PI on OpenVMS.......................................................................................................29 Configuring PI Interface Node Buffering.....................................................................30
PI-API Installation Instructions iv
Features ......................................................................................................................30 Buffered Functions.................................................................................................30 Server Timestamps ................................................................................................31 Error Reporting.......................................................................................................31 Installation and Configuration..................................................................................31 Operation.....................................................................................................................33 Startup.....................................................................................................................33 Modifying Interface Dependencies.......................................................................34 Stopping Buffering.................................................................................................35 Buffering State........................................................................................................37 Buffer File................................................................................................................37 Buffering Throughput............................................................................................37 Interface Installation...............................................................................................38 Shutdown Events...................................................................................................38 Monitoring the Buffering Process............................................................................41 Error Log..................................................................................................................41 Bufutil.......................................................................................................................42 Unlocking Resources.............................................................................................43 Limitations..................................................................................................................44 Troubleshooting.........................................................................................................45 Unable To Create Buffer File APIBUF.DAT..........................................................45 Trouble Opening or Creating the Shared File Memory Object..........................45 PI-API Programs Hang on UNIX............................................................................45 Bufserv Exits Immediately When Started............................................................45 Running Bufutil With No Arguments Hangs Without Presenting a Menu.......45 Bufutil Hangs When Requesting a Status Display.............................................45 Errors in the Log File about Creating, Opening or Removing Semaphores. . .46 Unable to Put Event into Secondary Buffer: -170...............................................46 Buffering Error Codes................................................................................................46 Appendix A: Microsoft Winsock Errors.............................................................................................49
Introduction to the PI-API

The PI Application Programming Interface (PI-API) is a library of routines that provide a common programmatic interface to PI Systems. The library is available on a number of hardware platforms where client programs execute. OSIsoft programs, (PI-ProcessBook, PI-DataLink, PI-Profiles, PI interfaces, etc.) use the functions in the PI-API library to communicate with the PI home node. This document describes installing the PI-API on various platforms to support client programs such as interfaces communicating to PI Systems. The PI-API can also be used to write new programs that send and receive PI data. If you wish to use the PI-API in this fashion, you should purchase the PI-API for the desired platform. You will receive a programmers manual that explains and documents the calling of over 100 different functions. The first part of this manual contains installation instructions for various platforms. Locate the section for the desired platform and follow the instructions. Note that for UNIX systems you should consult the sections entitled: UNIX Installation Procedures on page 9 and UNIX Post Installation on page 11 plus The section for the UNIX platform you are using. PI System Errors on page 23: This section defines the meaning of error codes returned by the PI-API or the PI home node. When errors are encountered at run time, they are typically logged either in the PI-API log file or in the interfaces log. "PI Server Support for Remote Access" on page 27: This section describes what configuration is required on the PI home node to support access from PI-API client applications. If the home node already supports one or more remote PI-API programs, then further configuration is typically not required. "Configuring PI-Interface Node Buffering on page 30: This section describes how data can be buffered on the PI-Interface node when the PI home node is unavailable and how this behavior is enabled, configured, and managed. Once an interface is installed and running correctly, you may wish to enable buffering to provide this functionality.
The second part of this manual contains three sections of reference material. They are:
Microsoft Windows Installation

The PI-API for Microsoft Windows NT, 2000, XP, 2000 Server, and 2003 Server supports the WinSock TCP/IP protocol stack only. This library is available on both 32 and 64-bit versions of Windows, running on the x86, Itanium and x64 platforms.
Installation
Note: On 32-bit versions of Windows the PI-API can be installed only as part of the PISDK That is, you must run the PI-SDK installation program in order to install the PI-API. On 64-bit versions the API is part of the PI Server installation. Please consult the release notes delivered in electronic format (PIHOME\bin\readme.txt) for the latest information as well as bug fixes and enhancements.
The installation creates a log of all files installed on the system located in PIHOME\dat\setuppiapi.log. Typically, the following programs and files are installed. PIHome\bin apisnap.exe bufserv.exe bufutil.exe pilogsrv.exe uninstall.exe pistart.bat pistop.bat sitestrt.bat sitestop.bat API_install.doc readme.txt PIHome\dat pilogin.ini piclient.ini setuppiapi.log %WINDIR%\system32 piapi32.dll pilog32.dll
Note: The PI-API library is named piapi32.dll even on 64-bit versions of Windows. PI-API Installation Instructions 3
The PI-API DLL version accessed by programs may be located in the system directory, a directory specified in the PATH environment variable, the current directory or paths entered in the registry. If the DLL version that a program is using is not the version just installed, ensure that all of a systems previous DLL copies are found and renamed. The Windows File Manager Search command (under the File menu) can also be used for this purpose. This may also be done from a command prompt using the dir command with the /s option starting at the root of each disk. For example:
c: cd \ dir /s piapi32.dll
bin\crt_old A backup of the previous C run time libraries. %WINDIR%\symbols\dll piapi32.dbg pilog32.dbg %WINDIR%\symbols\exe apisnap.dbg bufserv.dbg bufutil.dbg pilogsrv.dbg
Debug Symbolic Information

Debug symbolic information for Windows NT may be installed for use in Dr. Watson logging. This feature of Dr. Watson is not available on Windows 9x. If a program exception occurs and Dr. Watson is installed as the default debugger, the %WINDIR %\drwtsn32.log file should contain symbolic information usable in identifying the source of the program exception. The drwtsn32.log file should be saved for OSI Technical Support staff to use. To install Dr. Watson as the default debugger, run the command drwtsn32 i.
Initialization Files
An application built with PI-API-NT looks for the initialization file called pilogin.ini and for the file piclient.ini. These files contain server and port information to support default connections and connection to multiple PI Servers. The piclient.ini file is now used to configure PI-API buffering, bufserv. The PI-API library uses several methods to find these files. First it checks the dat subdirectory under the directory defined by PIPCSHARE in the pipc.ini file. Next it checks in a directory up one level and back down into a directory called dat from the current directory. If not found there, the directory specified as PIHOME above is used as the current directory and its dat subdirectory is searched. Other locations are also searched for backward compatibility, but it is advisable to have a single instance of these files in the primary location. The piclient.ini file has historically been used to support the definition of the default server. The pilogin.ini file was introduced with the PI-ProcessBook program to support both default connections and multiple connection management. The file now also supports
PI-API Installation Instructions 4
port definition and node IDs (a numeric mapping of server nodes used to reduce storage and provide server and application mobility). Currently the PI-API will search for either of these files for connection information. The pilogin.ini is preferred, and if found will be used. The piclient.ini file is supported for backward compatibility. Typical .ini files are shown below. During installation, a sample pilogin.ini is installed in the PIHOME\dat subdirectory and may be edited to reflect the users servers and login names as described below. The standard .ini file format is composed of sections (surrounded by brackets), items or keys (to the left of an = sign) and values (to the right of an = sign). All lines beginning with a semicolon (;) are comments only. PIPC.INI
[PIPC] PIHOME=C:\Program Files\PIPC PIPCSHARE=X:\NET\PI MAXPIPCLOGS=20 MAXLOGSIZE=256000
The pipc.ini file defines the directory in which server information, log files and buffering configuration information may be found. The entry PIHOME defines the base directory under which PI-API programs are usually installed. An additional entry (PIPCSHARE) for a network directory may be defined to indicate where a shared pilogin.ini file will reside. If you use this entry, it will override the setting for PIHOME when the PI-API looks for the pilogin.ini file. However, the log file, pipc.log, will still be located in the dat subdirectory of the directory identified by PIHOME. Additionally, log files may be managed by the settings MAXPIPCLOGS and MAXLOGSIZE. These indicate the number of files to retain and the size at which to shift the log file. The numbering of the log files circulates between 0 and MAXPIPCLOGS-1. PILOGIN.INI
[Services] PI1=PI [PINodeIdentifiers] ; PI#= Servername, NodeID, Port# PI1=MYVMSSERVER,34618,545 PI2=MYNTSERVER,85776,5450 [Network] TIMEOUT=60 WRITETIMEOUT=3 [Defaults] ; HELPFILE=C:\PIPC\LIBRARY\PILOGIN.HLP The default server name PISERVER=MYVMSSERVER ; The user names for the servers above PI1USER=newuser PI2USER=newuser DSTMISMATCH1=3600 PI-API Installation Instructions 5
DSTMISMATCH2=3600
The pilogin.ini file must be edited by hand using Notepad or a similar editor if only the PIAPI is installed on a machine. Users who have one of OSIsofts client products, such as PI-ProcessBook or PI-DataLink, can use the Connections dialog in these programs to add, modify, and delete server entries in the file. This approach is preferred, as it will generate compatible node identifiers (node IDs, discussed below) on different PCs connecting to the same server. The pilogin.ini file contains information for multiple connections. Each connection is given a sequential identifier (e.g., PI1, PI2, ... PIn) and this identifier is used across sections to identify different aspects of the same connection. The Services section contains the type of service supported for each connection. Currently only PI is a valid entry here. Only a single entry is required. The PINodeIdentifiers section contains sets of server name, node ID, and port number separated by commas, one entry for each connection. These should be edited to reflect the desired server names, node IDs, and ports as discussed below. In addition, an optional time offset change may be set that can occur between the client and server. This is the time in seconds that the server and client local time offset is allowed to jump. Typically, 3600 if the nodes are in time zones whose DST rules differ. The Network section contains the timeout settings. TIMEOUT indicates how long a PIAPI function may take to read from the PI Server before timing out. WRITETIMEOUT indicates how long a connection attempt to PI, as well as any attempt to write data may take before timing out. The Defaults section contains the name of the default server as the value associated with the PIServer item. This should be modified to reflect the local default server. Following the default server are the default user names for each connection. Again, these should be modified to reflect the local environment. The HELPFILE entry indicates the location of the Login Services help file and should be set to reflect the installed PIHOME location.
Node Identifiers
In the example above two servers are specified, MYNTSERVER and MYVMSSERVER. MYVMSSERVER is at port 545, which is standard for all Open VMS servers. MYNTSERVER is at 5450, which is typical of Windows NT and UNIX servers. Port numbers are used for TCP/IP connections. The node ID (34618 for MYVMSSERVER above) is used to give a numeric alias to the server. This may be used by applications to promote moving applications to different servers or replacing or moving of PI Systems among servers. For example, if an application stores significant points, it will likely need to store a reference to the server where this point resides. Applications that store many such points save significant space and processing time using a numeric representation. In addition, an application that uses the pilogin.ini file to associate server names to stored node IDs, can handle the PI System moving to a new server. Simply edit the pilogin.ini file to reflect the new server mapping and the internal node ID information about the location of the data will resolve to the new server.
Note: It is a good idea to use a consistent set of node IDs throughout a site, only changing them to reflect server changes.
PICLIENT.INI
[PISERVER] PIHOMENODE=MYVMSSERVER DSTMISMATCH=0
The piclient.ini file is used to support buffering configuration and if a pilogin.ini file cannot be found, to define the default PI server. The piclient.ini file above indicates that a PI program under Windows will resolve remote PI function calls with the PI Server named MYVMSSERVER by default. Default connections are made if the PI program calls the piut_connect function, calls the function piut_setservernode with a NULL string or function calls made without calling for a connection first. Again, the piclient.ini file is only used for this purpose if the pilogin.ini file cannot be found or older versions of the PIAPI are being used. Typical entries for a piclient.ini file are used to enable buffering and to allow the PI-API client program to correctly adjust time offsets for PI servers and clients using different Daylight Savings time rules. For example:
[PISERVER] DSTMISMATCH=3600 [APIBUFFER] BUFFERING=1
Log File Utility

Under Windows NT/2000 only, the pilogsrv process may be installed to run as a service that will monitor the size of the pipc.log file and back this file up when it exceeds a predefined size. The install program installs this service to automatically start on reboot. The commands pilogsrv start and pilogsrv stop or the Control Panel> Services utility may also be used to start and stop pilogsrv. The service may be configured to rename the log file at a user defined size between 1 kb and 4 MB (by default, 256 kb) and keep up to 9999 log files (by default, 20). These are configured in the pipc.ini file by using the following section and keyname entries.
[PIPC] MAXPIPCLOGS=20 MAXLOGSIZE=256000
The pilogsrv service renames pipc.log to pipcxxxx.log where xxxx ranges from 0000 up to the maximum specified number of files. When the maximum number is reached, numbering restarts at 0000.
Event Counters
The PI-API for Windows does not have support for event counters (sometimes called I/O rate counters). Event counters are used on UNIX and VMS nodes to track the number of events sent to PI or retrieved from PI. Some programs do provide support for event counters such as those which are simulated by UniInt-based interfaces. The interface documentation will describe if counters are supported and the setup procedures. Event counters as used in UniInt-based interfaces for Windows are implemented by creating a file PIHOME\dat\iorates.dat in which PI rate counter tags (event tags) are associated to counter numbers (PIHOME is defined in pipc.ini as the path to the PI-API such as D:\Program Files\PIPC). The counter number is usually specified on the interface command line as /ec=# where # is a number in the range 1-200. Every 10
minutes the interface will write a value for the average events per minute for the 10 minute range.
UNIX Installation
UNIX Installation Procedures
The PI-API library is available on a number of UNIX platforms, including: Solaris 2.5 and newer AIX 4.3 and newer HPUX 10.20 and newer, PA-RISC and Itanium OSF1 V4.0D and newer (DUX or Tru64) Linux (Red Hat Linux 9, Red Hat Enterprise Linux 3, or any Linux Standard Base 2 compliant distro)
Many of the procedures for installing and configuring the software on these different platforms are identical. When installing one of the UNIX versions, consult this section for general installation instructions and then the section for the specific operating system platform for additional details. The exception is the Linux platfo rm, where instead of a tar file a RPM installation kit is provided. See the Linux section below. For systems with previous installations of PI-API, make a backup of the PI-API directory. The UNIX tar command may be used or a separate installation directory may be used. To use the tar command, use the following commands:
cd $PIHOME tar cvf piapi_previous.tar ./*
To use another installation directory, rename the PI-API directory and create another PIAPI directory with the previous name. The shell initialization files will not need to be changed in that case.
cd $PIHOME cd .. mv piapi piapi_old mkdir piapi
System Configuration
The PI installation scripts should be run with super-user privileges (root). If the installation of system files is required as determined by the installation script, and another user is used during installation, errors will be logged to install.log. Typically, a user named piadmin and a group named pigrp may be created for using the PI-API software. This should be done using system administration tools provided by the operating system vendor. Environment Variables The PI-API installation procedure requires the definition of a PI home directory. The PI home directory is typically set to /opt/piapi or /home/piapi, although any
directory name in a partition with adequate disk space is suitable. Use the df command to determine the amount of disk space available. For example:
# mkdir /opt/piapi
If you are also installing or have already installed a full PI System on this machine, it is advisable though not required to define a separate PIHOME directory for the PI-API installation. Once the directory is created, the PIHOME environment variable must be defined to point to this directory. From the Korn or Bourne shell the command is:
# PIHOME=/opt/piapi # export PIHOME
or using C shell:
# setenv PIHOME /opt/piapi
Shared Library Path On systems where PI-API shared libraries are installed, (SOLARIS, OSF1, AIX 4.2, HPUX), it is recommended to leave these libraries in their installed directory and set the proper environment variable for the platform to allow run-time access to these libraries. Note that any user running programs linked to these shared libraries must have this variable defined. An alternative is to copy the PI shared library to /usr/lib, which is checked by the dynamic loader at run time. However, this can lead to conflicts with other installations or be overwritten with operating system upgrades.
Platform SOLARIS OSF1 (DUX or Tru64) AIX HP-UX Linux Library Path Environment Variable LD_LIBRARY_PATH LD_LIBRARY_PATH LIBPATH SHLIB_PATH None (libraries are installed in /usr/lib)
For example to set the dynamic library path for a Solaris system in the C shell use:
setenv LD_LIBRARY_PATH /opt/piapi/lib
or
setenv LD_LIBRARY_PATH $PIHOME/lib
Multiple directories can be defined separated by colons. For example:

setenv LD_LIBRARY_PATH /opt/piapi/lib:/usr/local/mylibs
Extracting Distribution Files

The PI-API directories should be backed up before beginning. The $PIHOME/dat/piclient.ini , iorates.dat, $PIHOME/bin/sitestart , and sitestop files contain information specific to the client program used on this PI Interface node and may need to be replaced with the backup versions. The CD-ROM distribution media should be mounted as a directory (In the instructions below, /cdrom will be used. Substitute the actual pathname, if necessary.) and the full
path to the tar file should be used in the extraction command below. If the file was retrieved as an Internet distribution, the file may be placed in the $PIHOME directory. The distribution files are extracted with the tar command to a temporary directory with the following commands:
# cd /tmp # zcat piapi133_sol2_tar.Z | tar xf
or
# zcat /cdrom/sol2/piapi133_sol2_tar.Z | tar xf -
The temporary directory should contain only the directory build after extracting the files. On all UNIX platforms the build directory contains the distribution files and the installation script, pi.install, which is run to complete the installation.
Running the Installation Script

To complete the PI-API installation on all UNIX platforms the installation script, pi.install, must be run. The installation script should be run by the root user. For multiplatform compatibility pi.install, and all platform-independent PI scripts, are written for the Bourne shell. If the Bourne shell is not the default shell for the user doing the install, pi.install must be explicitly run from the Bourne shell, that is,
sh pi.install
The following commands will run the pi.install script:

# cd build # sh pi.install
For all installations and upgrades, the pi.install script prompts for a user name (default user is piadmin, which must exist). Enter the name that should be set for all files in the $PIHOME directory tree. The user name entered must exist. If this is a new installation, pi.install will prompt you for a default PI Node name. The TCP/IP host name of the node running the PI Data Archive should be entered. The script asks whether the default home node is a PI2 (OpenVMS) system or a PI3 (Windows NT or UNIX) system. This script also creates several directories, builds the PI-API library, installs system files (if needed) and links PI application and example routines. A listing of the PI home directory should show the following directories:
bin build dat lib
During installation the file $PIHOME/install.log is created. If errors occurred, please review this file to determine what corrective action should be taken. If an obvious solution is not evident, save the file for OSIsoft Technical Support to review.
UNIX Post Installation

After successful installation of the PI-API, several other tasks may be required: Preparing Site-Specific Applications Configuration of TCP/IP Configuring the PI Server Setting the default PI home node
11
UNIX Installation
Preparing Site-specific Applications

Site-specific applications, such as interfaces, may need to be linked with the newly installed library. Applications that were linked with the shared PI-API library will usually run without relinking. Commands may be added to the sitelink script, which is called by the install script to expedite this process. Launching and terminating site-specific applications is accomplished through the sitestart and sitestop scripts. These scripts are called by the scripts pistart and pistop, respectively. Modify the sitestart and sitestop scripts as appropriate for your sites local applications.
Configuring TCP/IP
TCP/IP must be configured to allow the UNIX client node to find the PI home node by name. The client node should be able to ping the home node by name and to establish a Telnet session with the home node. The home node should also know the client node by name to permit reverse name lookup used to support security.
Configuring the PI Server

PI on OpenVMS systems requires the installation of a program on the server to respond to client requests. PI on Windows NT and UNIX systems automatically install a responder program called pinetmgr. For a discussion of protocol stacks and server program installation on various platforms, see PI Server Support for Remote Access on page 26.
Setting Default PI Home Node

The environment variable PIHOME must be set for any user running PI-API programs to enable the PI-API to locate the default PI home node. During installation, described earlier, PIHOME was set to the base install directory. Under this directory is a subdirectory, $PIHOME/dat, which contains the file piclient.ini, which specifies the default server and optionally the connection port. While running pi.install, the default home node and port were set in this file. The piclient.ini file may be modified if it was set incorrectly during install or the default home node changes. In any case, it should be reviewed during the installation process. A sample file is shown below:
[PISERVER] PIHOMENODE=MYVMSSERVER [TCP/IP] PORT=545
If necessary, edit the file modifying the line PIHOMENODE= to reflect your default PI node. Typically, this is your PI home node or a PINet node. In the example, the node MYVMSSERVER is being used.
Note: The format for PIHOMENODE should not be "MYVMSSERVER:545"
The default port for all OpenVMS servers is 545. If you will be connecting to OpenVMS servers, you may omit the TCP/IP and PORT lines from the file. If you will be connecting instead to a Windows NT or UNIX server, specify 5450 for the PORT. Note that this is used for default connection purposes. Using the PI-API function piut_setservernode, you can specify a server name followed by a colon and the port number to explicitly direct the connection. The file piclient.ini may also contain a section and entries to support configuration of PIInterface node buffering. For a description of appropriate entries, see Configuring PI12
Interface Node Buffering, on page 30. If you do not intend to use node buffering, you do not need these entries in piclient.ini. The default is to not enable buffering.
Event Counters
Event counters are used on UNIX nodes to track the number of events sent to PI or retrieved from PI. Typically, a counter number is associated with a PI tag to which the event rates are written. The counter number is associated with a tag in the $PIHOME/dat/iorates.dat file.
Starting and Stopping PI

When starting and stopping PI, the environment variables, (USER, LOGNAME, PIHOME), as well as the shared library path for those platforms using shared libraries, must be set as described in the section, "UNIX Installation Procedures" on page 9. You may wish to add the commands to set these environment variables to the script executed on login (.login, .profile) for users executing PI applications on the UNIX node. PI typically has four standard processes running on a UNIX PI-Interface node (If buffering is enabled, a fifth process, bufserv, is also started.):
mqsrv mqmgr
Message log server. Message log manager.
ioshmsrv I/O rates shared memory server. iorates
I/O rates monitor program.
These processes are started by $PIHOME/bin/pistart and stopped by $PIHOME/bin/pistop. These scripts also run sitestart and sitestop, respectively. To run the Bourne shell, start and stop scripts from a different shell execute the commands preceded by the shell directive, sh:
# sh pistart
You can verify that these processes are running using the apiverify script. This script reads the file $PIHOME/bin/apiprocs by default (You may create other process list files and enter those filenames as arguments to the apiverify script.) and lists process information for each program mqsrv, mqmgr, ioshmsrv, iorates, bufserv, and other processes that may be added to the apiprocs file. The apiverify script will print out a warning if a listed process is not found or multiple copies are running.
NAME PID TIME %CPU %MEM WARNING: bufserv is NOT running mqmgr 8676 0:03 0.0 0.9 mqsrv 8671 0:09 0.0 0.9 ioshmsrv 8682 0:06 0.0 0.4 iorates 13278 0:05 20.7 4.0 iorates 8687 0:05 0.0 1.0 WARNING: multiple instances of iorates are running fxbais 8695 304:45 2.2 2.7
On some systems, when the process that executed the pistart command exits, the launched processes also are killed. This can be prevented by pre-pending the launch command with
nohup.
For example:
UNIX Installation # nohup sh pistart
Purging Log Files

The error logging functions send data to the file $PIHOME/dat/pimesslogfile when the PIAPI is started using the pistart script. It is possible to run PI-API programs without running pistart, in which case error messages are redirected to stdout. When left running, the PI-API mqsrv and mqmgr programs will manage sending error messages to the pimesslogfile. Each night they rename the log file to pimesslogfile.mmmxx (where mmm is the three character month abbreviation and xx is the day of the month) and start a new pimesslogfile. Using the cron facility and the find command you can remove old log files from your system automatically. Finding and Removing the Files The following version of the find command will remove all pimesslogfile.xxxxx files from the directory /usr/piapi/dat that have not been modified within the last seven days.
find /usr/piapi/dat -name pimesslogfile\* -mtime +7 -exec rm -f {} \;
In this command, the \ character is an escape character used before the parenthesis and the semi-colon. The file name to match is surrounded with apostrophes (typically on the same key as the quotation marks). The command should be entered on a single line. Substitute the correct directory name and desired number of days without modification for your situation. Spaces are significant. The -mtime argument is for last modified, a similar argument -atime can be used for last accessed. Using find on a file subsequently changes its last access time. Adding a Cron Job This command can be entered right into the crontab preceded by the designation for when the job should run, for example:
20 4 * * * find /usr/piapi/dat $ -name `pimesslogfile.* $ mtime +7 exec rm f {} \;
would run the job at 4:20 AM every day of the week. All text is entered on a single line in the crontab file. The first five entries in crontab designate a time as follows:
minute hour day of the month month of the year day of the week (0-59) (0-23) (1- 31) (1-12) (0 - 6, 0 = Sunday)
Users with permission may set up their own cron jobs. The user who owns the directories and in particular the log files should be the one to create the cron entry. A users cron entries are stored by the system. To list them, execute
crontab -l
Modifying the cron table varies among systems. Under Solaris, to add to the users crontab, first set an environment variable indicating the editor to use:
14
For C Shell:
setenv EDITOR vi
For Bourne or Korn shell:

EDITOR=vi export EDITOR
Then execute the command

crontab -e
An editor is then presented where you may modify the existing cron jobs for this user and add any new ones desired. When the editor is exited the cron table is updated. Some systems require you to have a file with all the cron commands the user needs. In this case you would execute
crontab -l > tempfile
Next, edit tempfile to contain the additional commands for purging log files. Then add the cron entries with
crontab tempfile
For more information on setting up cron jobs, execute

man crontab
or see your system documentation.
Solaris
For installation procedures common to all UNIX platforms, see: "UNIX Installation Procedures on page 9. "UNIX Post Installation" on page 11.

The PI-API-SOL2 is distributed on CD-ROM or by Internet download. The files on the CD must be extracted to the PI home directory. CD-ROM To extract from CD-ROM, mount the CD drive and use the commands:
# cd $PIHOME # zcat /cdrom/solaris/piapi136_sol_tar.Z | tar xf -
After restoring the files, the PI home directory should contain the directory build. On this platform the PI-API programs and libraries are delivered already linked. To configure the default home node and install system files, run the pi.install procedure answering the prompts as described in the UNIX installation sections.
# cd $PIHOME/build PI-API Installation Instructions 15
UNIX Installation # sh pi.install
Incompatability with Previous PI-API Versions

On Solaris, programs built with previous versions of the PI-API may not be compatible with PI-API v1.3.9.4. This PI-API distribution contains a version compatible with the Sun SC5 compiler and ANSI streams. If your PI-API programs (for example, PI-Interfaces) do not mention ANSI C++ compiler compatibility or PI-API v1.3.9.4 compatibility, you should install PI-API v1.3.4 which is available as a separate installation. If you want to run a program built with PI-API v1.3.9.4 as well as a program built with PI-API v1.3.4, you may need to install two copies of the PI-API. For example, install PI-API v1.3.9.4 to the directory
/opt/piapi_1.3.9.4
by
# # # # # PIHOME=/opt/piapi_1.3.9.4 export PIHOME LD_LIBRARY_PATH=$PIHOME/lib export LD_LIBRARY_PATH sh pi.install /opt/piapi_1.3.4
Also, install PI-API v1.3.4 to the directory by

# # # # # PIHOME=/opt/piapi_1.3.4 export PIHOME LD_LIBRARY_PATH=$PIHOME/lib export LD_LIBRARY_PATH sh pi.install
Programs that need PI-API v1.3.9.4 would have their PIHOME and LD_LIBRARY_PATH environment variables set to, respectively, /opt/piapi_1.3.9.4 and /opt/piapi_1.3.9.4/lib. Similarly, programs that need PI-API v1.3.4 would have their PIHOME and LD_LIBRARY_PATH environment variables set to, respectively, /opt/piapi_1.3.4 and /opt/piapi_1.3.4/lib. In order for PI Interface node buffering to work for each of these two instances of the PIAPI, you will need to create the following entries in their respective piclient.ini files. In /opt/piapi_1.3.9.4/dat/piclient.ini:
[APIBUFFER] BUF1NAME=PIAPI136_BUFFER1MEM BUF2NAME=PIAPI136_BUFFER2MEM BUF1MUTEXNAME=PIAPI136_BUF1MUTEX BUF2MUTEXNAME=PIAPI136_BUF2MUTEX FILEBUFNAME=PIAPI136_FILEBUF FILEMUTEXNAME=PIAPI136_FILEMUTEX
16
And in /opt/piapi_1.3.4/dat/piclient.ini:
System Files Redistributed

/usr/lib/libC.so.5
IBM AIX RS/6000

For installation procedures common to all UNIX platforms, see: "UNIX Installation Procedures on page 9. "UNIX Post Installation" on page 11.

The PI-API-AIX is distributed on CD-ROM. The files on the CD must be extracted to the PI home directory. The following commands will perform this:
# cd $PIHOME # zcat /cdrom/aix/piapi136_aix_tar.Z | tar xvf -
The PI home directory should contain the directory build after extracting the files. The build directory contains the distribution files and installation script, pi.install .
Linking
The C++ linker files are installed if not found on the system.

/usr/lpp/xlC/lib/libC.a /usr/lpp/xlC/lib/crt0.o /usr/lpp/xlC/exe/munch /usr/lpp/xlC/bin/c++filt /usr/lpp/xlC/bin/linkxlC
HP-UX 10.x and 11.x

For installation procedures common to all UNIX platforms, see one of the following sections: "UNIX Installation Procedures" on page 9 "UNIX Post Installation" on page 11
17
UNIX Installation

The PI-API-HPUX is distributed on CD-ROM. The files on the CD must be extracted to the PI home directory. The following commands will perform this:
# cd #PIHOME # zcat /cdrom/hpux/piapi136_hpux_tar.Z | tar xvf -
Note your tape drive may be configured as a different device, in which case the device argument needs to be altered to conform to your local UNIX system. Consult your System Administrator if you have trouble accessing the tape device. The PI home directory should contain the directory build. The build directory contains the distribution files and installation script, pi.install.
Incompatability with Previous PI-API Versions

On HP-UX, programs built with previous versions of the PI-API are not compatible with PI-API v1.3.9.4. This PI-API distribution contains a version compatible with the ANSI C++ compiler and ANSI streams If your PI-API programs (for example, PI-Interfaces) do not mention ANSI C++ compiler compatibility or PI-API v1.3.9.4 compatibility, you should install PI-API v1.3.4 which is available as a separate installation. If you want to run a program built with PI-API v1.3.9.4 as well as a program built with PI-API v1.3.4, you will need to install two copies of the PI-API. For example, install PI-API v1.3.9.4 to the directory
/opt/piapi_1.3.9.4
by
# # # # # PIHOME=/opt/piapi_1.3.9.4 export PIHOME SHLIB_PATH=$PIHOME/lib export SHLIB_PATH sh pi.install
Also, install PI-API v1.3.4 to the directory

/opt/piapi_1.3.4
by
# # # # # PIHOME=/opt/piapi_1.3.4 export PIHOME SHLIB_PATH=$PIHOME/lib export SHLIB_PATH sh pi.install
Programs that need PI-API v1.3.9.4 would have their PIHOME and SHLIB_PATH environment variables set to, respectively, /opt/piapi_1.3.9.4 and /opt/piapi_1.3.9.4/lib. Similarly, programs that need PI-API v1.3.4 would have their PIHOME and SHLIB_PATH environment variables set to, respectively, /opt/piapi_1.3.4 and
/opt/piapi_1.3.4/lib.
18
In order for PI Interface node buffering to work for each of these two instances of the PIAPI, you will need to create the following entries in their respective piclient.ini files. In /opt/piapi_1.3.9.4/dat/piclient.ini:
And in /opt/piapi_1.3.4/dat/piclient.ini:
Linking
The C++ linker files are installed if not found on the system.

Cfront compiled version:
/usr/lib/libC.ansi.1
The following are installed only if needed for relinking.

/opt/CC/bin/c++filt /opt/CC/lbin/c++patch /opt/CC/bin/CC /opt/CC/lib/libcxx.a /opt/langtools/lib/crt0.o /opt/langtools/lib/end.o /usr/lib/nls/C/CC.cat
ANSI C++ compiled version:

/usr/lib/libstd.1 /usr/lib/libstream.1 /usr/lib/libCsup.1
Compaq UNIX (Tru64)

For installation procedures common to all UNIX platforms, see one of the following sections: "UNIX Installation Procedures" on page 9 "UNIX Post Installation" on page 11
19
UNIX Installation
Compaq UNIX for the alpha architecture is now called Tru64 UNIX. Previous version were called DUX, or DEC UNIX. Also, the operating system command uname will echo OSF1 to the screen. For the purpose of this document, OSF1 will be used.

The PI-API-DUX is distributed on CD-ROM. The files on the CD must be extracted to the PI home directory. The following commands will perform this:
# cd $PIHOME # zcat /cdrom/osf1/piapi136_osf1_tar.Z | tar xvf -
Your tape drive may be configured as a different device, in which case the device argument needs to be altered to conform to your local UNIX system. Consult your System Administrator if you have trouble accessing the tape device.

Most of the required files come on the base system CD-ROM. The proper subsets need to be installed to support C++ linking. The files required and their subsets are listed below:
Subset CXXBASEA132 CXXBASEA132 CXXSHRDA305 OSFBASE320 OSFCMPLRS320 OSFCMPLRS320 File /usr/lib/cmplrs/cxx/_main.o /usr/lib/cmplrs/cxx/demangle /usr/shlib/libcxx.so /usr/shlib/libm.so /usr/lib/cmplrs/cc/crt0.o /usr/lib/cmplrs/cc/libexc_init.a
On OSF1 3.2, one additional subset, cxxshrdae01307, is now required for programs compiled with the latest release of the C++ compiler. As the PI-API library is built with this compiler, this subset is distributed with the OSF PI-API and can be found in the PIHOME/lib directory after installation. The subset provides runtime support for this new compiler.
20
Linux
For installation procedures common to all UNIX platforms, see the following section: "UNIX Post Installation" on page 11
Environment Variables The PI-API installation procedure requires the definition of a PI home directory. On Linux, the PI home directory is set to /opt/piapi From the Korn or Bourne shell the command is:
# PIHOME=/opt/piapi # export PIHOME
or using C shell:
# setenv PIHOME /opt/piapi

The PI-API-LINUX is distributed on CD-ROM or by Internet download. The files are distributed as an RPM which typically has a name like: piapi-1.4.0.1.i386.rpm.
rpm -ivh piapi-1.4.0.1.i386.rpm
Upgrading an Existing Installation

To upgrade an existing installation, run the following command:
rpm -Uvh piapi-1.4.2.1.i386.rpm
21
PI System Errors
This section lists some common PI-API function error return values and their meanings as well as discusses system errors that may play a part in PI-API programming.
System Errors
When communicating with PI on OpenVMS systems, errors returned which are greater than zero usually indicate a system fault. When developing applications over a distributed environment, the system errors that may be encountered include both those errors derived from the home node or server and those derived on the local node or client. Typically, local errors are related to the network layer system calls and to privilege and quota problems. Most of these errors will have an accompanying message in the local message log. Remote errors are more difficult to address. For calls to PI on Open VMS, system errors are usually even numbers greater than 6 (six) and can range from quota to file system problems. To interpret these errors under VMS use the DCL command
write sys$output f$message(#)
where # is replaced with the returned error value. Calls to PI Systems on UNIX or Windows NT typically return system errors that are less than or equal to -10000. To interpret these run the command located in the $PIHOME/bin directory,
pilogsrv -e # [function]
where # is replaced with the returned error value and function is an optional argument which specifies which API call received the error number. The function argument is useful for error numbers that have multiple meanings, such as 1. Often the best the program can do is trap for these errors and typically, the server node message log must be consulted to resolve persistent problems. Of particular note is the system error 2, which can be returned when communicating with any PI server. This indicates a communication failure. Typically, the program is unable to send a message to the server or it has sent a message to the server and timed out waiting for a response. The default timeout is 60 seconds but is configurable in the PI-API initialization files. On Windows, in the pilogin.ini file, use the section [NETWORK] and key TIMEOUT to change the number of seconds for the timeout. On UNIX, in the piclient.ini file, use the [NETWORK] section and TIMEOUT key to change the timeout.
Point Attribute Access Errors

-1 -2 -3 -4 -5 -6 -7 Point # out of range or point not defined Blank tag Point data base full Memory data base full Tag not found Illegal characters in tag Tag already exists 23
-8 -9 -10 -11 -12 -13 -15 -20 -21 -22 -23 -24 -25 -26 -27 -33 -34 -35 -36 -37 -38 -39 -40 -41 -42 -43 -44 -45 -46 -49 -50 -51 -52 -60 -61 -62 -63 -64 -65 -66 -67 -68 -69
Time is after current time and date or time is < 0 Illegal status value or integer value Cannot create tag because another process is creating tags Digital code out of range (<1 or >NumbDigStates) Digital state string not found Digital state code out of range for this tag Source tag not found Bad zero or span for integer point (<0 or >32767) Span not greater than 0 Typical value not between zero and top of range Bad digital state code Bad number of digital states Illegal point type Illegal point source Illegal engineering unit code Point type of totalized point is not Real Rate point type must be Real or Integer Illegal resolution code Bad archiving on/off value Bad compressing on/off value Illegal compression deviation specification Illegal compression minimum time specification Illegal compression maximum time specification Illegal exception deviation specification Illegal exception minimum time specification Illegal exception maximum time specification Illegal filter code Illegal totalization code Illegal totalization conversion factor Bad square root code Bad scan on/off value Cannot change resolution code Bad time and date string (must be vms absolute or delta time) No more PID slots for retrieving point update lists No more tags created, edited, or deleted Not signed up for point updates Display digits < -20 or > 10 Bad clamping code (< 0 or > 3) Bad scheduling code (< 0 or > 2) Natural scheduling not allowed for post-processed tags Bad group size for moving average (< 2) Bad period (< 1 or > 86400 for perf eqns, < 300 or > 86400 for totals) Bad offset (< 0 or > 86399)
EVM Routine Errors

-70 -71 -72 -73 Number of points Point number out No room for more No room for this less than 1 of range programs requesting exceptions many points for this list 24
-74 -75 -76 -78 -79
No room for more points No points established Some points not disestablished Timed out Bad timeout value
Archive Access Errors

-101 -102 -103 -105 -106 -107 -108 -109 -110 -111 -112 -113 Date not on-line Record not found (empty) No data for this point for this time End time not after start time or start time <= 0 No good data for this point for this time Calc error: square root of negative number Time is before the editing time limit Value already exists at this time Archive program not keeping up with events Event not processed by archive program within 30 seconds Point not created because archive #1 not on-line Number of values argument to archive retrieval routine is too small
PI Login Services Errors

Note These errors are dependent on the particular pilg_xxx call being made. This section does not apply to interfaces. 23 22 1 0 -1 -2 -3 -4 -5 -6 -7 -8 -9 -100 -101 -102 -103 -104 -105 -106 -107 -108 -109 -110 -111 -112 Invalid DLL registered DLL already loaded Passed end of selection list Not enough memory GETFIRST not issued Already logged on Unknown server Allocation error Server not connected Invalid server Invalid node ID String truncated Bad status Invalid DLL Invalid window handle Login cancelled pilg_registerapp not called Login unsuccessful User not found Login initialization data not found Define connection dialog cancelled Cant write the login initialization data PIPC initialization data not found Cant find Windows directory Cant find PIHOME or PIPCSHARE definition Server already exists 25
PI System Errors -113 Illegal server type
Buffering Errors
Buffering errors are reproduced in the section on PI Interface node buffering on page 46.
PINet Errors
-981 Table id specified is not supported -982 Specified table code is not supported -983 Requested transaction mode was not valid -991 PINET function code is not valid -992 Specified length is not consistent -993 Specified count is not valid -994 Incompatible PINET version -995 Bad PINET message sequence -996 Message too big for PINET -998 Memory allocation error -999 Request not permitted without Login -1000 Bad grid (batch or sql error) -1001 No default host
apisnap Utility
A reliable network connection to the PI Server is required for client programs (especially interfaces) to function properly. In order to test communication to the server, and provide a utility to test the values that reach the server, the apisnap utility is provided. This program checks the server for the snapshot and most recent archive value for a tag that you specify. Executing apisnap with no arguments initiates a connection to the default server and prompts for a tag name. If one argument is given, the server to that you desire to connect must be specified. If two arguments are specified, the first argument is the servername and the second is a tagname. If both arguments are specified, the apisnap program will exit after giving the report for the tag specified. Additionally, the tagname prompt may be replaced by a backslash to indicate the following number is a point number. This is useful for looking up tag names when only a point number is available. Also, multiple tagnames may be entered if a list of snapshots is desired.
apisnap [server[:port]] [tagname or \PointId, ...]
26
PI Server Support for Remote Access

Server Support for Remote nodes sending data to the PI Data Archive requires software on the archive server to support remote data collection. This server-side software is responsible for monitoring client connection requests and establishing and maintaining a session with each client. This software, referred to as a listener, is implemented differently under PI on OpenVMS than under PI on Windows NT and UNIX. This section describes those differences and outlines what is required to enable client application support on the PI home node.
PI on Windows NT and UNIX

Windows NT and UNIX PI Systems implement a single process, pinetmgr, which is responsible for handling communication with remote nodes.
PI on OpenVMS
When communicating with PI on OpenVMS, distributed application support is provided by the PIServer program. PIServer is an application that runs on VMS PI home nodes and provides remote nodes (PINet and PI Interface nodes) with an interface to the PI System. There is one PIServer process for each remote node connection.
Remote Nodes
Currently two types of remote nodes are available: PINet nodes are available for VAX VMS platforms; and PI-Interface nodes are available for Microsoft Windows 3.1, Windows 9x, Windows NT, and several different UNIX platforms. Not all remote nodes support the same set of features. In addition, the version of the server program providing remote support affects the feature set available to the remote node.
Network Protocol
Remote nodes communicate with the PI System using the PINet protocol (a proprietary messaging standard). The PINet protocol is implemented on top of the network protocol. VMS PI Systems support communication using both TCP/IP and DECNet protocols. DECNet is typically provided with the system, but TCP/IP support must be purchased separately. Details of supported protocol stacks are provided below. Windows NT and UNIX PI Systems support only TCP/IP. These systems are typically delivered with network support already included. Some remote nodes can be configured to use either TCP/IP or DECNet (Windows 3.1 using DEC Pathworks, Sun workstations using SunLink DNI) though TCP/IP is quickly becoming the predominant protocol and is delivered with Windows 9x, Windows NT, and UNIX machines.
TCP/IP for PI on OpenVMS

The following VMS TCP/IP products (minimum required versions are listed) are supported by PI on OpenVMS.
Product PI-API Installation Instructions Version 27
Product Process Software TCPWare v3.1 Process Software MultiNet v3.2 Process Software MultiNet v3.4 2 Attachmate Pathway release 1.1
Version PI 2.0.8 PI 2.0.8 PI 2.1.0 PI 2.0.8
Programs which communicate using DECNet require version 2.0.6 or higher of the PI Server program on the VAX. PI System version 2.0.7 is necessary if PI Server security is desired. PI Server security may be implemented via client node authentication and/or username/password login.
Note: PI System version 2.1.1 is necessary if support for PI-ODBC or the batch (piba_) calls are needed.
Listener Installation
The pinetmgr application comes pre-built with each system. It is started automatically with the PI Data Archive and does not require extra installation or configuration steps to enable communication with remote nodes.
PI on OpenVMS
The PI Server application must be installed on any home node where PI-API access is required. Once installed, the PI Server will support connections from many clients, spawning a new instance of the application for each connection. Adding new clients does not require modification of this component. For instructions on installing the PI Server see the publication, PI System Installation/Update Instructions .
PI Server VMS User

PI Server versions using DECNet or DEC TCP/IP Services (UCX) require the PISERVER user to be created on the VAX node. Internally PI-API client nodes access the PI home node using the privileges and resources of the PISERVER account. This user must be added to the VMS user database. The 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 if the security is enabled and the default user database in the piserver.dat file is VMS. 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
1 2
Better known as UCX 28
Required for OpenVMS/AXP (i.e. Alpha) PI-API Installation Instructions
Server Security
These systems offer security down to the individual tag and can be configured to manage read and write access for both data and tag attributes independently. This security is in addition to any authentication mechanisms available through the native transport. Users and groups are defined on the server using the program piconfig. It is also possible to set up proxy accounts for particular client nodes. See the publication, PI Data Archive for Windows NT and UNIX for instructions on creating and managing users, groups and proxies.
PI on OpenVMS
The PI Server 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. The file contains a default set of protections for nodes not mentioned in the file and explicit protection information on a per node basis. For details on the format and use of this file see the publication, PI System Installation/Update Instructions.
29
Configuring PI Interface Node Buffering

PI Interface Node buffering refers to functionality in the PI-API that supports continuous collection of data on a PI Interface Node regardless of the status of the home node server or the network link to the server. This feature is available on UNIX, Windows NT and Windows 2000 platforms.
Features
PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI-API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process. Buffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI-API will not buffer data, sending data directly to the home node. When enabled, the following calls will buffer all data sent to the default home node.
Buffered Functions

piar_putarcvaluesx piar_putarcvaluex piar_putvalue pisn_putsnapshot pisn_putsnapshots pisn_putsnapshotq pisn_putsnapshotqx pisn_putsnapshotsx pisn_putsnapshotx pisn_sendexceptionq pisn_sendexceptionqx pisn_sendexceptionsx pisn_sendexcepstruc pisn_sendexcepstrucq pisn_sendexceptqx pisn_sendexceptions
Data sent through these calls is redirected to the buffering process, which stores and forwards events to the home node. Buffered data is maintained in First-In, First-Out (FIFO) order to avoid Archive inefficiencies and restrictions with out of order data.
30
Data is stored initially in memory until the allocated buffers are filled. Data is then stored in a file whose maximum size is configurable. When the buffering process is shutdown, the memory buffers and file buffers are combined into a new file that contains all data not yet sent to the server in FIFO order. When buffering is configured to be on, all calls to the listed buffered functions that send data to the default home node are buffered. Multiple interfaces on a single PI Interface node share the same buffering process and store data to the same buffers.
Server Timestamps
Many interfaces calling pisn_putsnapshot(s) use a timestamp of 0 to indicate that the PI-API should use the current server time as the timestamp for the event being recorded. Buffered data may sit on the PI Interface node for an indefinite period before being sent to the home node. This makes storing a zero timestamp impractical. Instead the buffered PIAPI detects the 0 timestamp and makes a call to pitm_fastservertime. This function makes use of a server time and local time retrieved and stored on the local machine during the initial connection. The difference between these times is applied to the current local time to calculate the current server time without calls to the server. This allows interpretation of a 0 timestamp even when the server is down.
Error Reporting
When data is buffered, the error messages returned by the standard PI-API calls represent the success or failure of moving the data to the buffering process. (See the section below for possible errors returned by the buffering process and buffered API functions). Errors typically detected on the home node (bad point number, illegal timestamp, ) are logged by the buffering process when the data is forwarded to the Archive. Errors logged by the buffering process are not propagated back to the program that originally inserted the data in the buffers. For this reason, it is recommended to disable buffering when installing, upgrading, and configuring PI-API programs on an PI Interface node. When the software is working satisfactorily, re-enable buffering.
Installation and Configuration

There are no additional steps needed to install buffering after installing the PI-API. The delivered PI-API library supports both buffered and unbuffered calls. The following files are installed for buffering support:
File Name UNIX bufserv bufutil isbuf piclient.ini Windows NT bufserv.exe bufutil.exe N/A piclient.ini Purpose Buffering process Utility for managing buffering process Program to determine if buffering is requested Buffering configuration file
Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the dat subdirectory of the PIHOME directory (typically c:\Program Files\pipc\dat) under Windows NT. On UNIX systems, the file is found in the dat subdirectory of the PIHOME directory (e.g., /opt/piapi/dat). This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section
called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows, vi on UNIX) to the desired values. The following settings are available for buffering configuration:
keywords BUFFERING PAUSERATE Values 0,1 02,000,000 02,000,000 12,000,000 12,000,000 64 2,000,000 64 2,000,000 02,000,000 Default 0 2 Description Turn off/on buffering. OFF = 0, ON = 1, When buffers are empty the buffering process will wait for this long before attempting to send more data to the home node (seconds) When the buffering process discovers the home node is unavailable it will wait this long before attempting to reconnect (seconds) Maximum buffer file size before buffering fails and discards events. (Kbytes) Maximum number of events to send between each SENDRATE pause. Primary memory buffer size. (bytes) Secondary memory buffer size. (bytes) The time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds)
RETRYRATE
120
MAXFILESIZE MAXTRANSFEROBJS BUF1SIZE BUF2SIZE SENDRATE
100,000 500 32768 32768 100
On UNIX, in addition to the [APIBUFFER] section, the [PISERVER] section may be used to define the default PI Server, and an optional time offset change that may occur between the client and server. On Windows NT this information should be stored in the pilogin.ini file, so the piclient.ini would only have the [APIBUFFER] section.
keywords PIHOMENODE DSTMISMATCH
Values string 02,000,000
Default none 0
Description Default server for UNIX. Windows default server is in pilogin.ini The time that the server and client local time offset is allowed to jump. Typically, 3600 if the nodes are in timezones whose DST rules differ (seconds)
Under UNIX a piclient.ini file might look like:

[PISERVER] PIHOMENODE=MYNTSERVER ; DSTMISMATCH=0 [TCP/IP] PORT=5450 [APIBUFFER] BUFFERING=1 MAXFILESIZE=100000 ; the PI-API connection routines have 1 minute default timeout
32
RETRYRATE=600
The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a connection before retrying. The [PISERVER] and [TCP/IP] sections are used to define the default connection. On Windows NT the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. Comment lines begin with a semicolon.
Operation
The buffering feature makes use of shared resources in the operating system as a means of providing communication between the PI-API functions and the buffering process. The buffering process, implemented by the bufserv program, is responsible for initially creating these resources and making them available to the PI-API functions.
Note When buffering is configured to be on, the bufserv process must be started before other programs using the PI-API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.
Startup
On UNIX platforms, awareness of buffering has been built into the pistart script delivered with the PI-API. The script runs a small program, isbuf, to determine if the piclient.ini file contains instructions to turn buffering on. If this is true, pistart will run bufutil with a -u argument to clean up any outstanding resources and then start the buffering process, bufserv. Under Windows NT, the buffering process is installed to run as a service by the installation program. The installation program on Windows allows the service to be configured to automatically start upon reboot dependent upon the successful startup of TCP/IP. When the bufserv process is installed, the service must be given a username and password that has permissions to create and delete shared memory (for example, users who are part of the Administrator group). This is done by the installation program if bufserv has not previously been installed as a service. Otherwise, assigning a user name and password is accomplished in the Control Panel> Services utility by selecting the Startup button and picking the radio button indicating This Account. Fill in a user name and password that have the appropriate Administrative privileges.
33
The bufserv program may be started or stopped using the pistart.bat or pistop.bat files provided with this distribution. To complete the configuration for using the pistart.bat and pistop.bat scripts, the scripts must be configured as in the examples provided for your particular client program. Alternately, the Control Panel> Services utility may be used to start and stop bufserv manually. To use the Control Panel> Services utility, highlight the service name and use the Start or Stop button. StopPriority is a feature supported in version 1.3.9.2 of the PI-API and later. The installation kit under Windows NT installs the bufserv service with a StopPriority of 0; this insures that when Windows is shut down, services which depend on bufserv will get shut down first. If bufserv is not installed with a StopPriority, some data loss may occur. The most common occurrence being that "Intf Shut" will not be written to the Interface points when Windows is shut down. If for any reason the bufserv service needs to be uninstalled and reinstalled, the following command lines should be used:
bufserv remove bufserv install depend tcpip -stoppriority 0 [-auto]
The StopPriority flag is stored in the Windows registry:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\bufserv\StopPriori ty
Modifying Interface Dependencies

Interfaces running as services on the node where bufserv is installed are dependent on bufserv starting first. If bufserv and the interfaces are started "automatically" the service installation must include this dependency. Just as bufserv is configured to be dependent on tcp/ip, interfaces are installed to be dependent on bufserv. Dependencies are defined during installation of each service. To modify the dependency list of a service that is already installed, it should be uninstalled and then reinstalled with the proper dependency list. OSI supplied interfaces and bufserv support the same set of command line options for controlling the service. This set of options is displayed by typing bufserv help. You can install interfaces from the command line or in some cases there may be a preexisting
34
installation script that will need to be modified. The procedure is to remove the interface as a service and reinstall it with the dependency on bufserv. To set an interfaces dependencies, open a command window and change the current working directory to the directory where the interface executable resides. Then remove the interface:
intfc remove where intfc is the interface executable without the .exe extension. Install the interface
specifying the desired dependency list, including bufserv, and optionally the automatic startup flag.
intfc install depend bufserv [-auto]
To include multiple dependencies, enclose the dependency list in quotation marks with the individual dependencies separated by spaces. For example:
-depend bufserv tcpip
Failure to start the buffering process before running PI-API programs, when buffering is configured to be on, manifests itself differently under UNIX and Windows NT. On UNIX, PI-API programs will hang, trying to make a connection. They are waiting for the resources to become available. To rectify this situation, the program(s) should be stopped and the buffering process started. On Windows NT, PI-API programs will run, but attempts to subsequently start the buffering process will fail. In this case, the first program trying to obtain the resource, creates the resource itself. When the buffering process is started, it tries to create the resource and fails because the resource already exists; the buffering process exits. Again the program(s) must be stopped and the buffering process started. In this case the bufutil program, described below, should be run with a -u parameter to unlock and remove the created resources before attempting to start the buffering process, bufserv.
Stopping Buffering
To stop the buffering process, first stop all programs that use the PI-API. On Windows, if the interface services have been made dependent on the buffer server, they must stop first before the buffer server will stop. The control panel may be used to stop the interfaces and buffer server. Also, the pistop.bat file may be used. The sitestop.bat file should be modified to contain the interface stop commands. Then use the bufutil program to stop the buffering process. This can be done either by running bufutil interactively and selecting the option to shutdown the server or by running bufutil from the command prompt with a -k argument. When the process shuts down, it will forward or store the contents of its memory buffers so that data is not lost. An example of a script that checks to see that an interface is stopped on UNIX nodes is given here.
############################################################################### # @(#)sitestop1.3 2000/07/25 # File: sitestop # # This file is provided to allow site specific applications to be stopped # whenever the pistop is executed. An appropriate application start script # should be inserted into the sitestart file or the verify_stopped() # routine below may be used. PI-API Installation Instructions 35
Configuring PI Interface Node Buffering # ############################################################################### ## Boure shell script to check process shutdown. verify_stopped() { pid=`ps -e | grep $1 | grep -v grep | awk '{ print $1 }'` if [ ${pid:-0} -gt 0 ] then # Change the following line a signal besides SIGTERM is used to stop # the interface. kill $pid lcount=0 dcount=0 while [ ${pid:-0} -gt 0 ] do if [ ${lcount} -gt 300 ] then break; fi sleep 1 echo '.\c' pid=`ps -e | grep $1 | grep -v grep | awk '{ print $1 }'` lcount=`expr $lcount+1` dcount=`expr $dcount+1` if [ ${dcount} -ge 60 ] then echo $lcount dcount=0 fi done if [ ${dcount} -gt 0 ] then echo ' ' fi if [ ${pid:-0} -gt 0 ] then echo "ERROR: Unable to stop $1 (pid = $pid)" $PIHOME/bin/shootq "ERROR: Unable to stop $1 (pid = $pid)" else echo "Program $1 stopped" $PIHOME/bin/shootq "Program $1 stopped" fi else echo "Program $1 not found" $PIHOME/bin/shootq "Program $1 not found" fi
36
} # EXAMPLE: # verify_stopped buftest
Buffering State
Three buffers are used to process events: a primary memory buffer, a secondary memory buffer, and a file buffer. Depending on the amount of data being buffered, the buffering process can be in one of three states corresponding to the buffers it is using. Initially it uses a single memory buffer. When that fills, it switches to using dual memory buffers. When these buffers become full, it switches to using dual memory buffers and a file. The current state of buffering as well as the status of each buffer can be examined with the bufutil program discussed below.
Buffer File
During operation, when memory buffers become full, the buffering process writes data to a file called APIBUF.DAT. Under Windows NT, this file is located in the dat subdirectory of the PI home directory as defined in the pipc.ini file. The pipc.ini file is found in the WINDOWS directory (note the name may vary from system to system). It contains a section [PIPC] with an entry for PIHOME which identifies the location of the PIHOME directory. If the pipc.ini file is not available or does not contain an appropriate entry, the file is written to the Windows temp directory. Under UNIX this file is located in the $PIHOME/dat directory. PIHOME is an environment variable defined to be the base directory where the PI-API was installed. This buffer file is not initially installed but will be created when needed by the PI-API. When data arrives faster than it is forwarded (data burst, server down), memory buffers fill and events begin to be written to this file. The file will continue to grow as events are added to the end of the file even as the events in the front of the file are processed. Once the file is completely processed it will be truncated. When truncated, the file still contains 16 bytes of header information. Buffer File Maximum Size The maximum size of the buffer file may be adjusted by the MAXFILESIZE parameter. To estimate the value for this parameter, estimate the number of events generated by the interface. For example, a typical process can generate 1500 exception events/day. A typical event uses 23 bytes in the file buffer (a float32 point). The number of kilobytes per day would be (# tags collected) x (1500 events/day) x (23/1024 kb) = # kb/day The disk space available for the buffer file will be the maximum. Do not fill the disk.
Buffering Throughput
The buffering process will take the number of events defined in MAXTRANSFEROBJS from the buffers and send the events to the server with a pause of SENDRATE after each MAXTRANSFEROBJS. If the default configuration is used, a maximum of 5000 events per second will be sent to the PI server (500 events times 10 per second, but slightly less because of network transfer time and moving the data from buffers to the TCP/IP port). If you typically have much less data throughput, this may be used to limit the rate at which any one node adds data to the PI server. If a higher throughput rate is needed, either increase MAXTRANSFEROBJS or decrease SENDRATE.
Interface Installation
During initial installation, configuration, and testing of an interface it is advisable to disable buffering. As described under Features, server error messages from buffered functions are logged rather than being returned to the calling program. The calling program instead receives an indication of the success or failure of the buffering process. Disabling buffering during shakedown provides more immediate indication of problems.
Shutdown Events
Shutdown events are typically written into points to indicate when the PI server is taken off-line. This allows an end user to recognize the discontinuity of the data. Without shutdown events, the data looks like it has been interpolated over the time the PI server was unavailable, which can be misleading. Without buffering, it is clear when the PI server stops running (shutdown or system crash), that every point which is collected on that system should receive a shutdown event. With buffering running, inserting shutdown events in points that are buffered gives an erroneous picture of the data. In fact, when the server comes back up, the buffered data is forwarded and there is no data loss. A shutdown event is irrelevant. The shutdown event can also cause buffered and subsequently forwarded data to be out of order, causing undue load on the PI server and slowing down forwarding. For this reason, points that are buffered on a PI Interface node or PI home node should not have shutdown events written by the home node. Buffering on a PI Interface Node The tag attribute shutdown should be modified to be FALSE for remotely collected and buffered points and the default home node PI\dat\shutdown.dat file should use a tag attribute mask of shutdown,1 as shown here.
! shutdown.dat: Shutdown for server points. ! login info - no longer used - ignored. localhost ! tag mask * ! tag attribute selection (logical AND for all attrib) ! point attributes,value to select points receiving shutdown shutdown,1
This will ensure that the points collected by the remote PI Interface node will never have shutdown written by the PI server. The program collecting the data is responsible for writing the status indicating that the PI Interface node was shut down, such as Intf shut or I/O timeout. Buffering on the PI Home Node Buffering on the PI server must deal with two situations. The node on which the PI server runs may be rebooted, or the PI server may be stopped while the API continues to buffer data. In the case in which the PI server node must be rebooted most points should receive a shutdown status. When the PI server is stopped, only those points for which the PI server generates data should receive shutdown. These two situations are handled differently on UNIX and Windows PI server nodes. Note it would be appropriate for the interface itself to send shutdown events to the home node when it is stopped (UNIINT-based interfaces use I/O timeout or Intf shut to indicate shutdown to differentiate between server and client shutdown with the /stopstat=Intf shut command line parameter). The interface documentation will
38
have specific instructions on implementing shutdown. PINet nodes (VMS clients) currently support sending shutdown events for interfaces collected on the node when the PINet node is shut down. Calculated and alarm tags (pointsource C, G, @) are examples of locally collected tags that should be listed in shutdown.dat files. Note that time-based calculations are not performed when the base system is down. Event-driven calculations are likely to be wrong when the system has been shutdown and the triggering events have been buffered. A shutdown event in this case alerts the end user to invalid data. Windows NT PI Home Node Shutdown Events On Windows NT, both PI server tags and those which are buffered on the local node should have shutdown=TRUE. On reboot of the NT node, the PI service pishutev will run automatically. It only uses the shutdown.dat file when starting as a service. For the case when the PI server is rebooted, the shutdown.dat file should be the same as shown under the remote PI Interface node section above. All tags with the shutdown attribute set to TRUE will receive shutdown events. This should include locally buffered points, calculated, totalized, and alarm points. For the case when the PI system is restarted the PI server tags should receive shutdown events but not the locally buffered interface tags. The pisrvstart.bat file needs to be modified so that the shutdown.dat file is not run by pishutev. The section between the Change this section comments below has been changed.
rem rem $Archive: /PI/3.2/nt/scripts/pisrvstart.bat $ rem rem Non-Interactive PI Startup as NT Services rem rem Start the Base PI Services rem echo Starting Base PI System Services... set piss=pinetmgr pimsgss for %%i in (%piss%) do ( ..\bin\%%i -start & pidiag -w 5000 ) set piss=piupdmgr pibasess pisnapss piarchss for %%i in (%piss%) do ( ..\bin\%%i -start & piartool -block %%i -verbose) if "%1" == "-base" (goto theend) rem rem Start the Extended PI Services rem echo Starting Extended PI System Services... rem === Change this section (below) >>>>>> rem Do pishutev separately. ..\bin\pishutev -f shutdown_C.dat ..\bin\pishutev -f shutdown_G.dat ..\bin\pishutev -f shutdown_AT.dat rem set piss=pishutev pisqlss pitotal pibatch pialarm pipeschd set piss=pisqlss pitotal pibatch pialarm pipeschd rem <<<<<< Change this section (above) === PI-API Installation Instructions 39
Configuring PI Interface Node Buffering for %%i in (%piss%) do ( ..\bin\%%i -start & pidiag -w 5000 ) rem rem Check for No Site Startup Flag rem if "%1" == "-nosite" (goto theend) pidiag -w 10000 call pisrvsitestart.bat :theend
A separate shutdown.dat file copy should be made to include only those points that are not buffered. This may require a separate shutdown.dat file for each point source as shown here.
! shutdown_C.dat: Shutdown for Calculated server points. ! login info - no longer used - ignored. localhost ! tag mask * ! tag attribute selection (logical AND for all attrib) ! point attributes,value to select points receiving shutdown shutdown,1 pointsource,C*
UNIX PI Home Node Shutdown Events The pistart.sh script should be modified to switch behavior between a system reboot and a PI server stop and start with buffering still running. Add a new flag option of -reboot.
flag_sitestart=1 flag_minimal=0 flag_standardout=0 flag_basestart=0 flag_reboot=0 for CMDARG in $* do case $CMDARG in I | *nosite ) flag_sitestart=0 ;; M ) flag_minimal=1 ;; *stdout ) flag_standardout=1 ;; *base ) flag_basestart=1 ;; *reboot ) flag_reboot=1 ;; *) print "Unknown Command Argument" $CMDARG ;; esac done
Then add conditional behavior for pishutev later in the script.

if (( flag_reboot == 1 )) then echo Adding PI Shutdown Events if [ -r `./piparams -pl`pishutev.log ]
40
then mv `./piparams -pl`pishutev.log `./piparams -pl`pishutev.log.old fi `./piparams -pb`pishutev > `./piparams -pl`pishutev.log 2>&1 & else `./piparams -pb`pishutev -f shutdownC.dat > `./piparams -pl`pishutevC.log 2>&1 & `./piparams -pb`pishutev -f shutdownG.dat > `./piparams -pl`pishutevG.log 2>&1 & `./piparams -pb`pishutev -f shutdownAT.dat > `./piparams -pl`pishutevAT.log 2>&1 & endif
Finally, the automatic startup scripts for the PI server need to be modified to pass the -reboot flag to the pistart.sh script.
#!/bin/ksh # # Filename: Pistart # if [ -f /opt/PI/adm/pistart.sh ] ; then cd /opt/PI/adm nohup ksh pistart.sh -reboot fi
Monitoring the Buffering Process

Two methods are used to monitor the health of buffering, error logs and the buffering utility bufutil.
Error Log
The PI-API writes error messages to the log file on each system. Under WINDOWS this file is called pipc.log and is located either in the PIHOME\dat directory or in the WINDOWS temp directory. Specification of the PIHOME directory is discussed earlier under the discussion of the buffer file. Under UNIX the log file is called pimesslogfile and is found in the $PIHOME/dat directory. Errors may be written to this file at any time and periodic inspection is recommended. In addition to errors, the starting and stopping of the buffering process is logged. The log file should be examined whenever the buffering process is started to ensure correct startup. Error numbers found in this log correspond to messages that may be found in several sources. For a list of common errors, see "PI System Errors" on page 21. Positive error values represent system errors and may be VMS errors (PI2 Servers) or communication errors. When working with PI3 Servers, large negative error numbers are returned starting at -10,000 and growing downwards. These errors can be translated using the pilogsrv utility file delivered with the PI-API. It is also possible to receive errors from the protocol layer. In particular systems using WINSOCK implementations can receive errors in the range 10000 to 11005. These errors are associated in the log with messages describing socket connection, receive, or send errors and are thus discernible from the PI3 messages. Winsock errors are listed in the file winsock.h provided by the protocol stack vendor.
Bufutil
A utility program, bufutil, is provided to examine the current state of buffering and to shut down the buffering process. The program when run without arguments presents a simple text menu of choices. The presentation is the same on all platforms. Certain functions in bufutil can be run in non-interactive mode through the use of command switches. Running bufutil with no arguments brings up a menu of choices.
Choices 1,2,3 may take optional arguments ( 1) Show Primary buffer header ( 2) Show Secondary buffer header ( 3) Show file buffer header ( 4) Kill server and quit ( 5) Quit ( 6) Display this menu Enter choice: of [ #repeats #seconds]
Items 1 and 2 display the state of the memory buffers described earlier. The format of the display is:
Primary Buffer Header Data ------------------------------------Version: 1 Mode: Single Server status: Connected [Buffering OFF] ------------------------------------Size: 32768 Next write location: 36 Next read location: 36 Write ptr before wrap: 0 Unprocessed entries: 0 -------------------------------------
Of the various items shown, the Mode, Server status and the Unprocessed entries are the most significant for monitoring the buffering process. The server status may indicate Connected, Disconnected or Connected [Buffering OFF]. When the status is disconnected, the buffer server will buffer events until the server is once again connected. If [Buffering OFF] is indicated, buffering has not been enabled in the piclient.ini file by entering BUFFERING=1. To enable buffering, stop all programs that use the PI-API, enable buffering in piclient.ini, and restart the buffer server before starting other PI-API programs. The mode shows the current buffering state. In the display above, buffering is using a single memory buffer in this display. Other options are Dual Memory and Dual Memory and File. The Unprocessed entries shows the number of items in the buffer that have yet to be handled. In the primary buffer Unprocessed entries refers to items not sent to the server. In other buffers, the destination of the Unprocessed events depends on the mode. In Dual Memory mode, events in the secondary buffer are moved to the primary buffer when space is available. In Dual Memory and File mode, events in the secondary buffer are moved to the file when the buffer becomes full. Events in the file are moved to the primary buffer as space becomes available.
42
By observing the Mode and selecting the desired buffer you can watch the buffers grow and shrink. The display does not update dynamically because querying the information requires a brief locking of the buffering resources. Instead, by repeatedly selecting a buffer, you can watch it change. Alternately, you may enter two numbers indicating the number of times (# repeats) to display the given buffer information with a delay {# seconds) between refreshing the numbers. The Version item reports the version of buffering being used, for future compatibility issues. The size is the size of the memory buffer and will remain constant. The write and read locations are used to handle inserting and removing values from the buffers. As events are buffered, the write location moves forward. As events are removed, the read location moves forward. These buffers wrap around so the write location can be behind the read location. As the buffer is a fixed size and the event size can vary, there may be unused bytes at the end of the buffer. The write ptr before wrap entry refers to this condition and shows the last position of the write pointer before it wrapped to the top of the buffer. Selecting item 3 from the menu displays information about the file buffer in the following format:
File Header Data Version: 1 Count : 0 Current read position: 16
The Version number in this display is the same as for memory buffers. The Count contains the number of unprocessed events in the file buffer. The Current read position marks how far through the file the buffering process has progressed. As described earlier, the file and therefore this pointer into the file will continue to grow until the buffer process catches up and processes every event in the file. The read position, like the file size will then move from a large number to a small one. The position shown above, 16, represents the file header. Item 4 on the bufutil menu, Kill server and quit, is used to stop the buffering process cleanly. Selecting this item will send a message to the buffering process that it needs to shutdown. It will then lock the resources, move memory information to file, and then exit. Interfaces and other programs utilizing the PI-API on this node should be stopped prior to killing the buffering process. Item 5, Quit, is used to exit bufutil. In a typical session, bufutil is invoked and several buffers are examined, perhaps repeatedly, to assess the current buffering mode and the amount of data stored in buffers. Then Quit is selected to exit the monitoring utility. Bufutil also supports two command line switches which bypass the normal interactive interface. Entering
bufutil -k
to a command prompt shuts down the buffering process, much like selecting item 4 in the bufutil menu. This method is used in the pistop script under UNIX when stopping the API.
Unlocking Resources
The other interactive command:
bufutil -u
is used when due to problems during startup or program crashes, the buffering resources become locked. For example, a program may lock the resources to add event data to the
buffers and then crash before it unlocks the resources. Other programs and the buffering process are then prevented from accessing these resources. To recover cleanly, these processes should be stopped, bufutil run with the -u command (unlock), and then the buffer server and other API processes restarted. Under UNIX this would typically be accomplished by running the pistop script followed by the pistart script. The pistart script uses this command when it starts to ensure that it can cleanly start the buffering process. Under certain error conditions, or if different users start different PI-API programs on a UNIX system, it may be necessary to become root before running bufutil-u to succeed in removing the resources. Typically semaphores can only be removed by the user that created them. If a different user tries to stop PI than the one who started it, you may run into this problem. If you get errors regarding accessing semaphores in the log file after trying to restart PI and ps -ef shows the bufserv application is not running, su to root and run bufutil -u.
Limitations
As described under Features, only a subset of functions make use of the buffering process. Other PI-API calls continue to be processed through the programs connection to the home node. Interfaces usually request a list of tags from the PI Server and may register when starting for exceptions if they support output points from PI. For these requests to succeed, the home node must be available. Once an interface is started, the majority of server communication involves sending data to the home node that is handled with buffering. Occasional requests for home node data will time out if the home node is down, though a well written interface will survive these time-outs and continue to send events. This limitation is a difference between PI Interface nodes with buffering and PINet nodes. PINet nodes store a copy of the point database and snapshots for points that are collected locally (by interfaces on the PINet node). An interface starting on a PINet node can query this local information during startup and succeed even when the home node is down. Only data sent to the default home node are buffered. In most cases, a PI Interface node will support a small number of interfaces, all talking to the same PI server. The default home node is set in the piclient.ini (UNIX) or pilogin.ini (Windows) file. Data stored in the PI Interface node buffers is not accessible to retrieval calls until it is forwarded to the home node. Calls on the PI Interface node, as well as other nodes, for recent data will return the most current snapshot on the server, not what is currently in the buffers. This situation may be due to the home node being down, slow or a burst of input data on the PI Interface node. The information retrieval calls continue to be processed through connection to the home node and are ignored by the buffering process. This is similar to the operation on a PINet node when requesting values for points that are not collected locally. This performance is also seen on a home node when input events are being buffered. Until events leave the input queue and go to the snapshot they are not visible to retrieval calls. Errors generated by bad event data, as discussed earlier, are not detected until the event is forwarded to the home node. Error returns from buffered functions return the success or failure of buffering the events. Errors with the contents of those events (e.g., bad point number, illegal timestamp) are written to the PI Interface node log when encountered. This is why it is recommended to suppress buffering when installing a new interface until data is being collected without problems for the desired points.
44
Troubleshooting
The following section details some common problems that may be encountered with PIAPI programs when buffering is turned on. The descriptive text identifies the condition that may be indicated by program performance, one or more error messages found in the log file, or from logged error codes shown in the next section.
Unable To Create Buffer File APIBUF.DAT

Verify that the buffer file directory is writeable by the offending process. Under UNIX this is $PIHOME/dat. Under Windows NT this is the dat subdirectory under the PIHOME directory specified in the pipc.ini file or the WINDOWS temp directory if this entry is not found. Also verify that any existing APIBUF.DAT file is accessible by the process reporting the error.
Trouble Opening or Creating the Shared File Memory Object

Check file and directory permissions as described above. Under certain conditions, an earlier startup failure can generate a zero length APIBUF.DAT file. Such a file is invalid and will defeat startup. The file should be 16 bytes (the header data) or larger if present. If you find a zero-length buffer file, stop any PI-API programs running, remove the zerolength file, run bufutil -u to unlock any locked resources and restart the server and associated processes.
PI-API Programs Hang on UNIX

This occurs when buffering has been indicated in the piclient.ini file but the buffering process, bufserv, was not started before other PI-API applications which make connections. Stop the program. Start the buffering process and retry the program that was hanging. Alternately change the piclient.ini file to turn buffering off and retry the program.
Bufserv Exits Immediately When Started

You can detect that the process has exited by searching for it in the process list. Under UNIX, use
ps -ef | grep bufserv
Under Windows NT, double-click on the background to bring up the task list and look for the bufserv process. Also check the log file for messages about inability to create buffers. The solution is generally to stop any other PI-API programs if they are running and run bufutil -u to unlock the resources. Then when bufserv is started again it can create the resources.
Running Bufutil With No Arguments Hangs Without Presenting a Menu

This is typically the same condition as PI-API programs hang on UNIX above. The resources have not been created and bufutil, a PI-API program, is patiently waiting for the resources to become available. This problem can also occur if a program which had these resources locked has abnormally terminated. In this case, stop all PI-API programs, run bufutil -u to unlock the resources, restart bufserv, and retry bufutil.
Bufutil Hangs When Requesting a Status Display

This condition usually indicates that the buffering resources are currently locked by another process. Waiting a few moments is advisable to allow the process to release its
locks when it is done accessing the shared resources. If the hang continues, it is likely that a program has abnormally terminated while holding a lock on these resources. Stop all PIAPI programs, run bufutil -u, restart bufserv, and retry bufutil.
Errors in the Log File about Creating, Opening or Removing Semaphores

Stop all PI-API applications, stopping the buffer server last. On UNIX run pistop. Run bufutil -u. If problems persist in UNIX, become root (su) and run bufutil -u again. Then run pistart (UNIX) or restart bufserv (Windows NT).
Unable to Put Event into Secondary Buffer: -170

The buffer full error, -170, may indicate that a program attempted to insert an array of events bigger than the memory buffer can hold. By default, the buffer server uses 32768 bytes of shared memory for each of the memory buffers. This allows approximately 1200 events maximum per putsnapshot call. Increase the memory buffer sizes using the BUF1SIZE and BUF2SIZE entries in piclient.ini .
Buffering Error Codes

Functions which implement buffering internal to the PI-API return error codes in the range -150 to -190. The majority of these errors will not be returned to calling routines, though some may appear in the log files. The errors are reproduced here along with their symbolic definition that gives an indication to the possible cause of problems encountered. To resolve the error number to a string use the command:
PIHOME\bin> pilogsrv -e -170 [-170] APIBUFFER: Buffer is full Error Code -150 -151 Description Unable to create shared memory under NT Failure to open shared memory that should already have been created by the server. It was not found. When creating shared memory, a shared memory object was found already created. Error obtaining a memory handle for a shared memory region. Error opening or creating a mutex Error opening file String buffer to small to hold directory path Directory name exceeds buffer length Error writing to a file Error reading from a file Error transfering data from memory to file Error creating a stream Error activating an object Error passivating an object Unrecognized event type Symbolic Name APIBUFERR_CREATEFILEMAPPING APIBUFERR_DOESNOTEXIST
-152 -153 -154 -155 -156 -157 -158 -159 -160 -161 -162 -163 -164
46
APIBUFERR_ALREADYEXISTS APIBUFERR_MAPVIEW APIBUFERR_MUTEXOPEN APIBUFERR_FILEOPEN APIBUFERR_FILEBUFDIR APIBUFERR_DIRTOOLONG APIBUFERR_FILEWRITE APIBUFERR_FILEREAD APIBUFERR_TRANSFERTOFILE APIBUFERR_NEWISTRSTREAM APIBUFERR_ACTIVATE APIBUFERR_PASSIVATE APIBUFERR_BADEVENTTYPE
Error Code -165 -166 -167 -168 -169 -170 -171 -172 -173 -174 -175 -176 -177 -178 -179 -180 -181 -182 -183 -184 -185
Description Unable to obtain a value from an event Server was disconnected Snapshot returned a system error Snapshot returned a function error Buffer is empty Buffer is full An invalid file location was found An unrecognized buffer status was encountered Problem reading piclient.ini file Error creating shared memory Error opening shared memory Insufficient space on disk to create a file of the maximum buffer size Error creating a file PIPC.INI file was not found. Windows NT Attempt to add an event to a full event block Out of memory Error obtaining the PIHOME directory Buffer file would exceeded its specified limit Error setting a value in an object The memory server is not running An event was processed whose function source is not recognized
Symbolic Name APIBUFERR_EVENTGETVAL APIBUFERR_DISCONNECTED APIBUFERR_SNAPSYSERR APIBUFERR_SNAPERR APIBUFERR_EMPTY APIBUFERR_FULL APIBUFERR_BADLOC APIBUFERR_BADBUFFERSTATUS APIBUFERR_INIFILE APIBUFERR_SHMEMCREATE APIBUFERR_SHMEMOPEN APIBUFERR_FILESPACE APIBUFERR_FILECREATE APIBUFERR_PIPCINI APIBUFERR_BLOCKFULL APIBUFERR_OUTOFMEMORY APIBUFERR_TEMPDIR APIBUFERR_FILEFULL APIBUFERR_SETVALUE APIBUFERR_SERVERNOTRUNNING APIBUFERR_UNKNOWNEVENTSOURCE
47
Appendix A: Microsoft Winsock Errors

Windows socket errors do not currently have a routine to translate error numbers to text. A partial table is included here for reference.
Error Code 10004 10013 10014 10022 10024 10035 10036 10037 10038 10039 10040 Description A blocking operation was interrupted by a call to WSACancelBlockingCall An attempt was made to access a socket in a way forbidden by its access permissions The system detected an invalid pointer address in attempting to use a pointer argument in a call An invalid argument was supplied Too many open sockets A non-blocking socket operation could not be completed immediately A blocking operation is currently executing An operation was attempted on a non-blocking socket that already had an operation in progress An operation was attempted on something that is not a socket A required address was omitted from an operation on a socket A message sent on a datagram socket was larger than the internal message buffer or some other network limit, or the buffer used to receive a datagram into was smaller than the datagram itself A protocol was specified in the socket function call that does not support the semantics of the socket type requested An unknown, invalid, or unsupported option or level was specified in a getsockopt or setsockopt call The requested protocol has not been configured into the system, or no implementation for it exists The support for the specified socket type does not exist in this address family The attempted operation is not supported for the type of object referenced The protocol family has not been configured into the system or no implementation for it exists Symbolic Name WSAEINTR WSAEACCES WSAEFAULT WSAEINVAL WSAEMFILE WSAEWOULDBLOCK WSAEINPROGRESS WSAEALREADY WSAENOTSOCK WSAEDESTADDRREQ WSAEMSGSIZE
10041 10042 10043 10044 10045 10046
WSAEPROTOTYPE WSAENOPROTOOPT WSAEPROTONOSUPPORT WSAESOCKTNOSUPPORT WSAEOPNOTSUPP WSAEPFNOSUPPORT
49
10047 10048 10049 10050 10051 10052 10053 10054 10055
An address incompatible with the requested protocol was used Only one usage of each socket address (protocol/network address/port) is normally permitted The requested address is not valid in its context A socket operation encountered a dead network. A socket operation was attempted to an unreachable network The connection has been broken due to keep-alive activity detecting a failure while the operation was in progress An established connection was aborted by the software in your host machine An existing connection was forcibly closed by the remote host An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full A connect request was made on an already connected socket A request to send or receive data was disallowed because the socket is not connected and (when sending on a datagram socket using a sendto call) no address was supplied A request to send or receive data was disallowed because the socket had already been shut down in that direction with a previous shutdown call A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond No connection could be made because the target machine actively refused it A socket operation failed because the destination host was down. A socket operation was attempted to an unreachable host A Windows Sockets implementation may have a limit on the number of applications that may use it simultaneously WSAStartup cannot function at this time because the underlying system it uses to provide network services is currently unavailable The Windows Sockets version requested is not supported Either the application has not called WSAStartup, or WSAStartup failed Graceful shutdown in progress Class type not found Host not found
WSAEAFNOSUPPORT WSAEADDRINUSE WSAEADDRNOTAVAIL WSAENETDOWN WSAENETUNREACH WSAENETRESET WSAECONNABORTED WSAECONNRESET WSAENOBUFS
10056 10057
WSAEISCONN WSAENOTCONN
10058
WSAESHUTDOWN
10060
WSAETIMEDOUT
10061 10064 10065 10067 10091
WSAECONNREFUSED WSAEHOSTDOWN WSAEHOSTUNREACH WSAEPROCLIM WSASYSNOTREADY
10092 10093 10101 10109 11001
WSAVERNOTSUPPORTED WSANOTINITIALISED WSAEDISCON WSATYPE_NOT_FOUND WSAHOST_NOT_FOUND 50
11002 11003 11004
Nonauthoritative host not found This is a nonrecoverable error Valid name, no data record of requested type
WSATRY_AGAIN WSANO_RECOVERY WSANO_DATA
51
Index
AIX.................................................................... LIBPATH...................................................10 AIX ...............................................................17 APIBUF.DAT.................................................45 apisnap..........................................................26 apisnap utility................................................26 apiverify........................................................13 buffering........................................................30 buffer file...................................................37 buffered functions.....................................30 buffering state...........................................37 configuration of.........................................31 Error Codes...............................................46 errors.........................................................26 Home node................................................38 limitations..................................................44 maximum file size.....................................37 monitoring the process..............................41 operation...................................................33 startup.......................................................33 stopping.....................................................35 throughput.................................................37 bufserv..........................................................31 immediate exits.........................................45 bufutil......................................................31, 42 communication.................................................. remote nodes............................................27 Configuring........................................................ buffering....................................................31 Open VMS, TCP/IP...................................12 PI Interface Node Buffering.......................30 TCP/IP,UNIX.............................................12 PI-API Installation Instructions Control Panel> Services utility........................7 Cron Job........................................................14 debug symbols................................................4 DECNet.........................................................27 default debugger.............................................4 Distribution Files............................................... AIX............................................................17 HP-UX.......................................................18 OSF1...................................................20, 21 Solaris.......................................................15 UNIX..........................................................10 Dr. Watson........................................................ drwtsn32.log................................................4 installation...................................................4 logging.........................................................4 not on Windows 9x......................................4 DUX.........................................................19, 21 Environment Variables...................................... UNIX......................................................9, 21 Errors................................................................ Archive Access..........................................25 Error Log...................................................41 EVM Routine.............................................24 Point Attribute Access...............................23 Reporting...................................................31 System......................................................23 Event Counters................................................. UNIX..........................................................13 Windows......................................................7 file format.......................................................... .ini files........................................................5 HP-UX...........................................................17 52
SHLIB_PATH............................................10 initialization Files.............................................4 Initialization Files.............................................. default timeout..........................................23 location........................................................4 Installation......................................................... buffering....................................................31 HP-UX.......................................................17 Interface, Disable Buffering.......................38 UNIX............................................................9 UNIX Script...............................................11 installation log................................................... Windows......................................................3 Installation log................................................... UNIX..........................................................11 interface............................................................ dependencies............................................34 iorates.dat.................................................7, 13 isbuf...............................................................31 keywords.......................................................32 Limitations......................................................... of the buffering process.............................44 Linking............................................................... AIX............................................................17 HP-UX.......................................................19 listener............................................................... installation.................................................28 software.....................................................27 Log files............................................................. mqmgr.......................................................14 mqsrv........................................................14 pilogsrv........................................................7 pimesslogfile.......................................14, 41 pipc.log......................................................41 Purging......................................................14 Login Services errors....................................25 Microsoft Operating Systems..........................3 Node buffering..............................................30 PI-API Installation Instructions
Node Identifiers...............................................6 nodes................................................................ remote.......................................................27 organization of documentation........................1 OSF1................................................................. LD_LIBRARY_PATH.................................10 PI Home Node...............................................12 PI server............................................................ pinetmgr....................................................27 PI Server.......................................................27 PI System.......................................................... Errors.........................................................23 version 2.0.7..............................................28 version 2.1.1..............................................28 PI-API nodes.................................................27 pi.install.........................................................12 piclient.ini..............................................4, 7, 31 APIBUFFER..............................................32 BUF1SIZE...........................................32, 46 BUF2SIZE...........................................32, 46 BUFFERING.......................................32, 42 Default node..............................................44 DSTMISMATCH........................................32 MAXFILESIZE...........................................32 MAXTRANSFEROBJS........................32, 37 NETWORK................................................23 PAUSERATE............................................32 PIHOMENODE....................................12, 32 PORT..................................................12, 32 RETRYRATE............................................32 SENDRATE.........................................32, 37 TCP/IP.......................................................32 TIMEOUT..................................................23 pilogin.ini.................................................4, 5, 6 Default node..............................................44 Defaults.......................................................6 HELPFILE...................................................6 NETWORK................................................23 53
Index PINodeIdentifiers.........................................6 PIServer......................................................6 SERVICES..................................................6 TIMEOUT..................................................23 pilogsrv................................................7, 23, 41 MAXLOGSIZE.............................................7 MAXPIPCLOGS..........................................7 PINet................................................................. Errors.........................................................26 nodes...................................................27, 39 protocol.....................................................27 pinetmgr........................................................28 pipc.ini.........................................................4, 5 MAXLOGSIZE.............................................5 MAXPIPCLOGS..........................................5 PIHOME......................................................5 PIPC............................................................5 PIPCSHARE...............................................5 pipc.log............................................................5 PIServer.Dat.................................................29 port.................................................................... 545..............................................................6 5450............................................................6 Post Installation................................................. UNIX..........................................................11 remote nodes.................................................... PI Server Support for................................27 root......................................................9, 44, 46 security.............................................................. server........................................................29 semaphores...................................................44 server................................................................ Timestamps...............................................31 Shared File Memory Object..........................45 Shared Library Path......................................10 Shutdown events...........................................38 home node..........................................39, 40 PI Interface node.......................................38
54
pishutev...............................................39, 40 pisrvstart.bat..............................................39 pistart.sh....................................................40 shutdown.dat.............................................39 Solaris...........................................................15 LD_LIBRARY_PATH.................................10 Stopping PI....................................................13 subdirectories.................................................... created during installation...........................3 System Configuration........................................ UNIX Installation.........................................9 System Files Redistributed............................... AIX............................................................17 HP-UX.......................................................19 OSF1.........................................................20 Solaris.......................................................17 TCP/IP..........................................................27 Troubleshooting................................................ buffering....................................................45 UNIX Installation Procedures..........................9 unlocking resources......................................43 Winsock errors.................................................. winsock.h...................................................41 WinSock TCP/IP protocol stack......................3 site-specific applications..............................12 %WINDIR%\symbols......................................4
55

API Install

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

API Install

Uploaded by

Copyright:

Available Formats

PI-API Installation Instructions

PI-API Installation Instructions

Introduction to the PI-API

PI-API Installation Instructions

Microsoft Windows Installation

Debug Symbolic Information

Microsoft Windows Installation

Log File Utility

Microsoft Windows Installation

Multiple directories can be defined separated by colons. For example:

Extracting Distribution Files

Running the Installation Script

The following commands will run the pi.install script:

UNIX Post Installation

PI-API Installation Instructions

Preparing Site-specific Applications

Configuring the PI Server

Setting Default PI Home Node

Starting and Stopping PI

Message log server. Message log manager.

ioshmsrv I/O rates shared memory server. iorates

I/O rates monitor program.

UNIX Installation # nohup sh pistart

Purging Log Files

For Bourne or Korn shell:

Then execute the command

For more information on setting up cron jobs, execute

or see your system documentation.

Extracting Distribution Files

UNIX Installation # sh pi.install

Incompatability with Previous PI-API Versions

Also, install PI-API v1.3.4 to the directory by

System Files Redistributed

IBM AIX RS/6000

Extracting Distribution Files

System Files Redistributed

HP-UX 10.x and 11.x

PI-API Installation Instructions

Extracting Distribution Files

Incompatability with Previous PI-API Versions

Also, install PI-API v1.3.4 to the directory

System Files Redistributed

The following are installed only if needed for relinking.

ANSI C++ compiled version:

Compaq UNIX (Tru64)

PI-API Installation Instructions

Extracting Distribution Files

System Files Redistributed

Extracting Distribution Files

Upgrading an Existing Installation

PI-API Installation Instructions

Point Attribute Access Errors

PI-API Installation Instructions

EVM Routine Errors

PI-API Installation Instructions

-74 -75 -76 -78 -79

Archive Access Errors

PI Login Services Errors

PI-API Installation Instructions

PI System Errors -113 Illegal server type

PI Server Support for Remote Access

PI on Windows NT and UNIX

TCP/IP for PI on OpenVMS

Version PI 2.0.8 PI 2.0.8 PI 2.1.0 PI 2.0.8