P. 1
API Install

API Install

|Views: 29|Likes:
PI Application Programming Interface
PI Application Programming Interface

More info:

Published by: Rama Krishna Mullapudi on Apr 04, 2013
Copyright:Attribution Non-commercial

Availability:

Read on Scribd mobile: iPhone, iPad and Android.
download as DOC, PDF, TXT or read online from Scribd
See more
See less

04/16/2014

pdf

text

original

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 Hauptstraβe 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 statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP-UX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
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

PI-API Installation Instructions

v

The first part of this manual contains installation instructions for various platforms. "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. If you wish to use the PI-API in this fashion. Once an interface is installed and running correctly. If the home node already supports one or more remote PI-API programs. “PI System Errors” on page 23: This section defines the meaning of error codes returned by the PI-API or the PI home node. PI-DataLink. and managed. OSIsoft programs. The PI-API can also be used to write new programs that send and receive PI data. "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. PI-Profiles. (PI-ProcessBook. then further configuration is typically not required. They are: • • PI-API Installation Instructions 1 . they are typically logged either in the PI-API log file or in the interface’s log. you may wish to enable buffering to provide this functionality. This document describes installing the PI-API on various platforms to support client programs such as interfaces communicating to PI Systems. The second part of this manual contains three sections of reference material. You will receive a programmer’s manual that explains and documents the calling of over 100 different functions. you should purchase the PI-API for the desired platform. PI interfaces. configured.) use the functions in the PI-API library to communicate with the PI home node. The library is available on a number of hardware platforms where client programs execute. 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. Locate the section for the desired platform and follow the instructions. etc. When errors are encountered at run time.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.

exe uninstall. 2000 Server. Typically. Please consult the release notes delivered in electronic format (PIHOME\bin\readme.doc readme. On 64-bit versions the API is part of the PI Server installation. 2000.txt PIHome\dat pilogin. This library is available on both 32 and 64-bit versions of Windows.log. XP.log %WINDIR%\system32 piapi32.ini piclient.bat pistop.exe bufserv.exe pistart. and 2003 Server supports the WinSock TCP/IP protocol stack only.dll even on 64-bit versions of Windows.Microsoft Windows Installation The PI-API for Microsoft Windows NT.bat sitestop.dll Note: The PI-API library is named piapi32.bat API_install. the following programs and files are installed. PIHome\bin apisnap. running on the x86. Itanium and x64 platforms.dll pilog32. PI-API Installation Instructions 3 . The installation creates a log of all files installed on the system located in PIHOME\dat\setuppiapi.ini setuppiapi.exe bufutil.exe pilogsrv.bat sitestrt. Installation Note: On 32-bit versions of Windows the PI-API can be installed only as part of the PISDK That is.txt) for the latest information as well as bug fixes and enhancements. you must run the PI-SDK installation program in order to install the PI-API.

Other locations are also searched for backward compatibility. First it checks the dat subdirectory under the directory defined by PIPCSHARE in the pipc. Next it checks in a directory up one level and back down into a directory called dat from the current directory. Initialization Files An application built with PI-API-NT looks for the initialization file called pilogin. If the DLL version that a program is using is not the version just installed.log file should be saved for OSI Technical Support staff to use. The file now also supports PI-API Installation Instructions 4 .log file should contain symbolic information usable in identifying the source of the program exception. This feature of Dr.dbg pilog32. a directory specified in the PATH environment variable. Watson as the default debugger. Watson is not available on Windows 9x.The PI-API DLL version accessed by programs may be located in the system directory. ensure that all of a system’s previous DLL copies are found and renamed. These files contain server and port information to support default connections and connection to multiple PI Servers.dbg Debug Symbolic Information Debug symbolic information for Windows NT may be installed for use in Dr. run the command drwtsn32 –i.dll bin\crt_old A backup of the previous C run time libraries. the %WINDIR %\drwtsn32. The piclient. the current directory or paths entered in the registry. The pilogin. bufserv. For example: c: cd \ dir /s piapi32.dbg %WINDIR%\symbols\exe apisnap. The drwtsn32.ini file was introduced with the PI-ProcessBook program to support both default connections and multiple connection management.ini file. The PI-API library uses several methods to find these files. If not found there. but it is advisable to have a single instance of these files in the primary location. The piclient. the directory specified as PIHOME above is used as the current directory and its dat subdirectory is searched. This may also be done from a command prompt using the dir command with the /s option starting at the root of each disk.ini file is now used to configure PI-API buffering.ini file has historically been used to support the definition of the default server.dbg bufutil.dbg bufserv. Watson logging. To install Dr. Watson is installed as the default debugger. If a program exception occurs and Dr. The Windows File Manager Search command (under the File menu) can also be used for this purpose.dbg pilogsrv.ini and for the file piclient.ini. %WINDIR%\symbols\dll piapi32.

The standard .HLP The default server name PISERVER=MYVMSSERVER . will still be located in the dat subdirectory of the directory identified by PIHOME.ini file format is composed of sections (surrounded by brackets).5450 [Network] TIMEOUT=60 WRITETIMEOUT=3 [Defaults] . The numbering of the log files circulates between 0 and MAXPIPCLOGS-1. Typical . The pilogin. The entry PIHOME defines the base directory under which PI-API programs are usually installed.ini is preferred. HELPFILE=C:\PIPC\LIBRARY\PILOGIN. An additional entry (PIPCSHARE) for a network directory may be defined to indicate where a shared pilogin. Additionally. the log file. However.log.545 PI2=MYNTSERVER.ini is installed in the PIHOME\dat subdirectory and may be edited to reflect the user’s servers and login names as described below.ini file defines the directory in which server information.INI [Services] PI1=PI [PINodeIdentifiers] . The user names for the servers above PI1USER=newuser PI2USER=newuser DSTMISMATCH1=3600 PI-API Installation Instructions 5 .) are comments only. Currently the PI-API will search for either of these files for connection information.port definition and node ID’s (a numeric mapping of server nodes used to reduce storage and provide server and application mobility). If you use this entry. NodeID.ini file will reside.INI [PIPC] PIHOME=C:\Program Files\PIPC PIPCSHARE=X:\NET\PI MAXPIPCLOGS=20 MAXLOGSIZE=256000 The pipc. a sample pilogin. The piclient. pipc.34618. PILOGIN. These indicate the number of files to retain and the size at which to shift the log file. PI#= Servername. log files and buffering configuration information may be found.ini file is supported for backward compatibility. and if found will be used. During installation. PIPC. Port# PI1=MYVMSSERVER. All lines beginning with a semicolon (.ini files are shown below. it will override the setting for PIHOME when the PI-API looks for the pilogin.85776. items or keys (to the left of an = sign) and values (to the right of an = sign). log files may be managed by the settings MAXPIPCLOGS and MAXLOGSIZE.ini file.

Applications that store many such points save significant space and processing time using a numeric representation. The Network section contains the timeout settings. PI1.ini file must be edited by hand using Notepad or a similar editor if only the PIAPI is installed on a machine. MYVMSSERVER is at port 545. Only a single entry is required. which is standard for all Open VMS servers. it will likely need to store a reference to the server where this point resides. these should be modified to reflect the local environment. 6 . Port numbers are used for TCP/IP connections. discussed below) on different PCs connecting to the same server.g. For example. The Services section contains the type of service supported for each connection. such as PI-ProcessBook or PI-DataLink. 3600 if the nodes are in time zones whose DST rules differ. modify. This should be modified to reflect the local default server. Typically. if an application stores significant points.ini file to associate server names to stored node IDs. which is typical of Windows NT and UNIX servers. The pilogin. . as well as any attempt to write data may take before timing out. In addition..ini file contains information for multiple connections. MYNTSERVER is at 5450.. PIn) and this identifier is used across sections to identify different aspects of the same connection. The Defaults section contains the name of the default server as the value associated with the PIServer item. and delete server entries in the file. This may be used by applications to promote moving applications to different servers or replacing or moving of PI Systems among servers. and port number separated by commas. The PINodeIdentifiers section contains sets of server name. Each connection is given a sequential identifier (e. can handle the PI System moving to a new server. Currently only PI is a valid entry here. Note: It is a good idea to use a consistent set of node IDs throughout a site. The node ID (34618 for MYVMSSERVER above) is used to give a numeric alias to the server.Microsoft Windows Installation DSTMISMATCH2=3600 The pilogin.. Users who have one of OSIsoft’s client products. Again. as it will generate compatible node identifiers (node IDs. WRITETIMEOUT indicates how long a connection attempt to PI. an application that uses the pilogin. node ID. This approach is preferred. This is the time in seconds that the server and client local time offset is allowed to jump. The HELPFILE entry indicates the location of the Login Services help file and should be set to reflect the installed PIHOME location. one entry for each connection. In addition. PI2. TIMEOUT indicates how long a PIAPI function may take to read from the PI Server before timing out.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. and ports as discussed below. Node Identifiers In the example above two servers are specified. Following the default server are the default user names for each connection. Simply edit the pilogin. These should be edited to reflect the desired server names. can use the Connections dialog in these programs to add. an optional time offset change may be set that can occur between the client and server. MYNTSERVER and MYVMSSERVER. node IDs. only changing them to reflect server changes.

Event counters are used on UNIX and VMS nodes to track the number of events sent to PI or retrieved from PI.ini file cannot be found or older versions of the PIAPI are being used. Default connections are made if the PI program calls the piut_connect function.log file and back this file up when it exceeds a predefined size. These are configured in the pipc. the pilogsrv process may be installed to run as a service that will monitor the size of the pipc.ini as the path to the PI-API such as D:\Program Files\PIPC). For example: [PISERVER] DSTMISMATCH=3600 [APIBUFFER] BUFFERING=1 Log File Utility Under Windows NT/2000 only. Event counters as used in UniInt-based interfaces for Windows are implemented by creating a file PIHOME\dat\iorates. to define the default PI server.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. 20).PICLIENT. Every 10 PI-API Installation Instructions 7 . When the maximum number is reached.ini file by using the following section and keyname entries. Again. 256 kb) and keep up to 9999 log files (by default.dat in which PI rate counter tags (event tags) are associated to counter numbers (PIHOME is defined in pipc. The piclient. numbering restarts at ‘0000’.ini file is used to support buffering configuration and if a pilogin. The counter number is usually specified on the interface command line as “/ec=#” where “#” is a number in the range 1-200. Event Counters The PI-API for Windows does not have support for event counters (sometimes called I/O rate counters).ini file is only used for this purpose if the pilogin. [PIPC] MAXPIPCLOGS=20 MAXLOGSIZE=256000 The pilogsrv service renames pipc. 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. The service may be configured to rename the log file at a user defined size between 1 kb and 4 MB (by default. The install program installs this service to automatically start on reboot. the piclient. calls the function piut_setservernode with a NULL string or function calls made without calling for a connection first.log to pipcxxxx.log where ‘xxxx’ ranges from ‘0000’ up to the maximum specified number of files. The commands pilogsrv –start and pilogsrv –stop or the Control Panel> Services utility may also be used to start and stop pilogsrv.ini file cannot be found.ini file above indicates that a PI program under Windows will resolve remote PI function calls with the PI Server named MYVMSSERVER by default. Typical entries for a piclient.INI [PISERVER] PIHOMENODE=MYVMSSERVER DSTMISMATCH=0 The piclient.

Microsoft Windows Installation minutes the interface will write a value for the average events per minute for the 10 minute range. 8 .

PA-RISC and Itanium OSF1 V4. If the installation of system files is required as determined by the installation script. When installing one of the UNIX versions. Red Hat Enterprise Linux 3. mv piapi piapi_old mkdir piapi System Configuration The PI installation scripts should be run with super-user privileges (root). and another user is used during installation. use the following commands: cd $PIHOME tar cvf piapi_previous.3 and newer HPUX 10. The PI home directory is typically set to /opt/piapi or /home/piapi. cd $PIHOME cd .log. 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. Environment Variables The PI-API installation procedure requires the definition of a PI home directory. rename the PI-API directory and create another PIAPI directory with the previous name.5 and newer AIX 4. The UNIX tar command may be used or a separate installation directory may be used..0D and newer (DUX or Tru64) Linux (Red Hat Linux 9. Typically. For systems with previous installations of PI-API. or any Linux Standard Base 2 compliant distro) Many of the procedures for installing and configuring the software on these different platforms are identical.20 and newer. The shell initialization files will not need to be changed in that case./* To use another installation directory. To use the tar command. This should be done using system administration tools provided by the operating system vendor. a user named piadmin and a group named pigrp may be created for using the PI-API software. errors will be logged to install. See the Linux section below.UNIX Installation UNIX Installation Procedures The PI-API library is available on a number of UNIX platforms. where instead of a tar file a RPM installation kit is provided. although any PI-API Installation Instructions 9 . make a backup of the PI-API directory. including: • • • • • Solaris 2.tar .

Once the directory is created.ini . 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. For example: # mkdir /opt/piapi If you are also installing or have already installed a full PI System on this machine. the PIHOME environment variable must be defined to point to this directory. 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.dat.2. (SOLARIS. An alternative is to copy the PI shared library to /usr/lib. /cdrom will be used. HPUX). AIX 4. 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. if necessary. Substitute the actual pathname. However. $PIHOME/bin/sitestart . OSF1. The $PIHOME/dat/piclient. iorates. which is checked by the dynamic loader at run time. The CD-ROM distribution media should be mounted as a directory (In the instructions below. Note that any user running programs linked to these shared libraries must have this variable defined. 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. 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.) and the full PI-API Installation Instructions 10 .directory name in a partition with adequate disk space is suitable. it is advisable though not required to define a separate PIHOME directory for the PI-API installation. this can lead to conflicts with other installations or be overwritten with operating system upgrades. Use the df command to determine the amount of disk space available.

which is run to complete the installation. On all UNIX platforms the build directory contains the distribution files and the installation script.Z | tar xf - The temporary directory should contain only the directory build after extracting the files. If this is a new installation. must be run. which must exist). The installation script should be run by the root user.install For all installations and upgrades.path to the tar file should be used in the extraction command below. The TCP/IP host name of the node running the PI Data Archive should be entered. save the file for OSIsoft Technical Support to review. A listing of the PI home directory should show the following directories: bin build dat lib During installation the file $PIHOME/install. If the file was retrieved as an Internet distribution. builds the PI-API library. installs system files (if needed) and links PI application and example routines. the pi. If an obvious solution is not evident. pi. pi.install script: # cd build # sh pi.install must be explicitly run from the Bourne shell. and all platform-independent PI scripts.install. please review this file to determine what corrective action should be taken. If the Bourne shell is not the default shell for the user doing the install.install will prompt you for a default PI Node name. The distribution files are extracted with the tar command to a temporary directory with the following commands: # cd /tmp # zcat piapi133_sol2_tar. the file may be placed in the $PIHOME directory.install. If errors occurred.Z | tar xf – or # zcat /cdrom/sol2/piapi133_sol2_tar. that is. Running the Installation Script To complete the PI-API installation on all UNIX platforms the installation script. This script also creates several directories.install. The script asks whether the default home node is a PI2 (OpenVMS) system or a PI3 (Windows NT or UNIX) system.install script prompts for a user name (default user is piadmin.log is created. pi. 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 PI-API Installation Instructions . UNIX Post Installation After successful installation of the PI-API. The user name entered must exist.install The following commands will run the pi. Enter the name that should be set for all files in the $PIHOME directory tree. For multiplatform compatibility pi. are written for the Bourne shell. pi. sh pi.

which contains the file piclient. For a description of appropriate entries. 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. this is your PI home node or a PINet node. the default home node and port were set in this file. described earlier. While running pi. Under this directory is a subdirectory. Applications that were linked with the shared PI-API library will usually run without relinking. you may omit the TCP/IP and PORT lines from the file. which specifies the default server and optionally the connection port. Typically. For a discussion of protocol stacks and server program installation on various platforms. These scripts are called by the scripts pistart and pistop. such as interfaces. which is called by the install script to expedite this process.ini. Note that this is used for default connection purposes. Commands may be added to the sitelink script. A sample file is shown below: [PISERVER] PIHOMENODE=MYVMSSERVER [TCP/IP] PORT=545 If necessary. it should be reviewed during the installation process. Launching and terminating site-specific applications is accomplished through the sitestart and sitestop scripts. The home node should also know the client node by name to permit reverse name lookup used to support security. PI on Windows NT and UNIX systems automatically install a responder program called pinetmgr. edit the file modifying the line PIHOMENODE= to reflect your default PI node. If you will be connecting instead to a Windows NT or UNIX server. During installation. $PIHOME/dat. The file piclient.ini file may be modified if it was set incorrectly during install or the default home node changes. The piclient. PIHOME was set to the base install directory. The client node should be able to ping the home node by name and to establish a Telnet session with the home node. may need to be linked with the newly installed library.UNIX Installation Preparing Site-specific Applications Site-specific applications. Configuring TCP/IP TCP/IP must be configured to allow the UNIX client node to find the PI home node by name. Configuring the PI Server PI on OpenVMS systems requires the installation of a program on the server to respond to client requests.ini may also contain a section and entries to support configuration of PIInterface node buffering. the node MYVMSSERVER is being used. see “PI Server Support for Remote Access” on page 26. you can specify a server name followed by a colon and the port number to explicitly direct the connection. In the example. Modify the sitestart and sitestop scripts as appropriate for your site’s local applications. respectively. In any case. specify 5450 for the PORT. Using the PI-API function piut_setservernode. If you will be connecting to OpenVMS servers. Note: The format for PIHOMENODE should not be "MYVMSSERVER:545" The default port for all OpenVMS servers is 545. see “Configuring PI12 .install.

"UNIX Installation Procedures" on page 9.9 ioshmsrv 8682 0:06 0. a fifth process.7 4. (USER.ini. respectively. sh: # sh pistart You can verify that these processes are running using the apiverify script. You may wish to add the commands to set these environment variables to the script executed on login (. NAME PID TIME %CPU %MEM WARNING: bufserv is NOT running mqmgr 8676 0:03 0. This can be prevented by pre-pending the launch command with nohup. PI typically has four standard processes running on a UNIX PI-Interface node (If buffering is enabled.) and lists process information for each program mqsrv. Message log manager. start and stop scripts from a different shell execute the commands preceded by the shell directive. as well as the shared library path for those platforms using shared libraries. a counter number is associated with a PI tag to which the event rates are written. iorates.0 0. PIHOME).7 On some systems.profile) for users executing PI applications on the UNIX node. For example: PI-API Installation Instructions 13 . the launched processes also are killed. you do not need these entries in piclient.): • • • • mqsrv mqmgr Message log server. LOGNAME. To run the Bourne shell. the environment variables. The default is to not enable buffering.4 iorates 13278 0:05 20. These scripts also run sitestart and sitestop. bufserv. Starting and Stopping PI When starting and stopping PI.0 0. ioshmsrv.0 WARNING: multiple instances of iorates are running fxbais 8695 304:45 2. mqmgr.Interface Node Buffering. The counter number is associated with a tag in the $PIHOME/dat/iorates. when the process that executed the pistart command exits.0 1. Typically. . The apiverify script will print out a warning if a listed process is not found or multiple copies are running.login.” on page 30.0 iorates 8687 0:05 0. If you do not intend to use node buffering. bufserv. Event Counters Event counters are used on UNIX nodes to track the number of events sent to PI or retrieved from PI. is also started. These processes are started by $PIHOME/bin/pistart and stopped by $PIHOME/bin/pistop. must be set as described in the section.2 2. ioshmsrv I/O rates shared memory server.9 mqsrv 8671 0:09 0. and other processes that may be added to the apiprocs file.dat file. iorates I/O rates monitor program. 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.0 0.

All text is entered on a single line in the crontab file. the \ character is an escape character used before the parenthesis and the semi-colon. To list them. 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. In this command. would run the job at 4:20 AM every day of the week. Using find on a file subsequently changes its last access time. The file name to match is surrounded with apostrophes (typically on the same key as the quotation marks). Adding a Cron Job This command can be entered right into the crontab preceded by the designation for when the job should run. find /usr/piapi/dat -name pimesslogfile\* -mtime +7 -exec rm -f {} \. A user’s cron entries are stored by the system. the PI-API mqsrv and mqmgr programs will manage sending error messages to the pimesslogfile.6. a similar argument -atime can be used for last accessed.xxxxx files from the directory /usr/piapi/dat that have not been modified within the last seven days. in which case error messages are redirected to stdout.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. execute crontab -l Modifying the cron table varies among systems. 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. Under Solaris. Each night they rename the log file to pimesslogfile. The user who owns the directories and in particular the log files should be the one to create the cron entry. The -mtime argument is for last modified.*’ \) –mtime +7 –exec rm –f {} \. first set an environment variable indicating the editor to use: 14 . 0 = Sunday) Users with permission may set up their own cron jobs. It is possible to run PI-API programs without running pistart. The command should be entered on a single line. Substitute the correct directory name and desired number of “days without modification” for your situation. to add to the user’s crontab.31) (1-12) (0 . When left running. for example: 20 4 * * * find /usr/piapi/dat \( -name `pimesslogfile.mmmxx (where mmm is the three character month abbreviation and xx is the day of the month) and start a new pimesslogfile. Spaces are significant.

run the pi. "UNIX Post Installation" on page 11. On this platform the PI-API programs and libraries are delivered already linked. # cd $PIHOME/build PI-API Installation Instructions 15 . the PI home directory should contain the directory build.Z | tar xf - After restoring the files. CD-ROM To extract from CD-ROM. Extracting Distribution Files The PI-API-SOL2 is distributed on CD-ROM or by Internet download. To configure the default home node and install system files. The files on the CD must be extracted to the PI home directory. When the editor is exited the cron table is updated. In this case you would execute crontab -l > tempfile Next. execute man crontab or see your system documentation. Solaris For installation procedures common to all UNIX platforms. Some systems require you to have a file with all the cron commands the user needs.install procedure answering the prompts as described in the UNIX installation sections. 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. see: • • "UNIX Installation Procedures” on page 9.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. mount the CD drive and use the commands: # cd $PIHOME # zcat /cdrom/solaris/piapi136_sol_tar.

4 as well as a program built with PI-API v1.4/lib.install Incompatability with Previous PI-API Versions On Solaris. respectively.9.9.4/dat/piclient. respectively.3.9.3.3. Similarly.UNIX Installation # sh pi.4 compatibility. programs that need PI-API v1.4 to the directory /opt/piapi_1.4 would have their PIHOME and LD_LIBRARY_PATH environment variables set to.ini: [APIBUFFER] BUF1NAME=PIAPI136_BUFFER1MEM BUF2NAME=PIAPI136_BUFFER2MEM BUF1MUTEXNAME=PIAPI136_BUF1MUTEX BUF2MUTEXNAME=PIAPI136_BUF2MUTEX FILEBUFNAME=PIAPI136_FILEBUF FILEMUTEXNAME=PIAPI136_FILEMUTEX 16 .3.4/lib.9.3.install /opt/piapi_1. /opt/piapi_1.9.3.9.3.3. install PI-API v1. /opt/piapi_1.3.3.3.install Programs that need PI-API v1.3.3.4 and /opt/piapi_1. programs built with previous versions of the PI-API may not be compatible with PI-API v1. In order for PI Interface node buffering to work for each of these two instances of the PIAPI. In /opt/piapi_1. For example.4. you may need to install two copies of the PI-API.3.4. you will need to create the following entries in their respective piclient.4 to the directory by # # # # # PIHOME=/opt/piapi_1.4 which is available as a separate installation. install PI-API v1.9.4 Also.9.9. you should install PI-API v1.4 export PIHOME LD_LIBRARY_PATH=$PIHOME/lib export LD_LIBRARY_PATH sh pi.3.4 by # # # # # PIHOME=/opt/piapi_1.4 would have their PIHOME and LD_LIBRARY_PATH environment variables set to. If you want to run a program built with PI-API v1.3. PI-Interfaces) do not mention ANSI C++ compiler compatibility or PI-API v1. This PI-API distribution contains a version compatible with the Sun SC5 compiler and ANSI streams.3.3.4 and /opt/piapi_1. If your PI-API programs (for example.9.4 export PIHOME LD_LIBRARY_PATH=$PIHOME/lib export LD_LIBRARY_PATH sh pi.ini files.

5 IBM AIX RS/6000 For installation procedures common to all UNIX platforms.Z | tar xvf - The PI home directory should contain the directory build after extracting the files.x and 11. see one of the following sections: • • "UNIX Installation Procedures" on page 9 "UNIX Post Installation" on page 11 PI-API Installation Instructions 17 .4/dat/piclient. Linking The C++ linker files are installed if not found on the system.a /usr/lpp/xlC/lib/crt0.so.o /usr/lpp/xlC/exe/munch /usr/lpp/xlC/bin/c++filt /usr/lpp/xlC/bin/linkxlC HP-UX 10. The build directory contains the distribution files and installation script.And in /opt/piapi_1. Extracting Distribution Files The PI-API-AIX is distributed on CD-ROM. pi. The files on the CD must be extracted to the PI home directory.3. The following commands will perform this: # cd $PIHOME # zcat /cdrom/aix/piapi136_aix_tar.x For installation procedures common to all UNIX platforms.ini: [APIBUFFER] BUF1NAME=PIAPI134_BUFFER1MEM BUF2NAME=PIAPI134_BUFFER2MEM BUF1MUTEXNAME=PIAPI134_BUF1MUTEX BUF2MUTEXNAME=PIAPI134_BUF2MUTEX FILEBUFNAME=PIAPI134_FILEBUF FILEMUTEXNAME=PIAPI134_FILEMUTEX System Files Redistributed /usr/lib/libC. "UNIX Post Installation" on page 11. see: • • "UNIX Installation Procedures” on page 9.install . System Files Redistributed /usr/lpp/xlC/lib/libC.

/opt/piapi_1.3. Incompatability with Previous PI-API Versions On HP-UX.4 to the directory /opt/piapi_1.3.3.3.3.4/lib.Z | tar xvf - Note your tape drive may be configured as a different device. programs that need PI-API v1. PI-Interfaces) do not mention ANSI C++ compiler compatibility or PI-API v1.3. /opt/piapi_1.3.3. you will need to install two copies of the PI-API.3.install.3. 18 .4 would have their PIHOME and SHLIB_PATH environment variables set to.4/lib.4 by # # # # # PIHOME=/opt/piapi_1.9.4 and /opt/piapi_1. The PI home directory should contain the directory build.4 export PIHOME SHLIB_PATH=$PIHOME/lib export SHLIB_PATH sh pi. Similarly.9.3. The files on the CD must be extracted to the PI home directory.install Programs that need PI-API v1.9.9.install Also. install PI-API v1.UNIX Installation Extracting Distribution Files The PI-API-HPUX is distributed on CD-ROM. respectively.4 to the directory /opt/piapi_1. The following commands will perform this: # cd #PIHOME # zcat /cdrom/hpux/piapi136_hpux_tar. The build directory contains the distribution files and installation script.4 and /opt/piapi_1. For example.3.4 as well as a program built with PI-API v1.9. respectively. pi.3. This PI-API distribution contains a version compatible with the ANSI C++ compiler and ANSI streams If your PI-API programs (for example. programs built with previous versions of the PI-API are not compatible with PI-API v1.4.9.4 would have their PIHOME and SHLIB_PATH environment variables set to.3. you should install PI-API v1.3.3.4 by # # # # # PIHOME=/opt/piapi_1.4 export PIHOME SHLIB_PATH=$PIHOME/lib export SHLIB_PATH sh pi.9.4 compatibility. install PI-API v1. in which case the device argument needs to be altered to conform to your local UNIX system.9.3.4. Consult your System Administrator if you have trouble accessing the tape device.4 which is available as a separate installation.9. If you want to run a program built with PI-API v1.

o /usr/lib/nls/C/CC.ini files.1 Compaq UNIX (Tru64) For installation procedures common to all UNIX platforms.ini: [APIBUFFER] BUF1NAME=PIAPI134_BUFFER1MEM BUF2NAME=PIAPI134_BUFFER2MEM BUF1MUTEXNAME=PIAPI134_BUF1MUTEX BUF2MUTEXNAME=PIAPI134_BUF2MUTEX FILEBUFNAME=PIAPI134_FILEBUF FILEMUTEXNAME=PIAPI134_FILEMUTEX Linking The C++ linker files are installed if not found on the system.ini: [APIBUFFER] BUF1NAME=PIAPI136_BUFFER1MEM BUF2NAME=PIAPI136_BUFFER2MEM BUF1MUTEXNAME=PIAPI136_BUF1MUTEX BUF2MUTEXNAME=PIAPI136_BUF2MUTEX FILEBUFNAME=PIAPI136_FILEBUF FILEMUTEXNAME=PIAPI136_FILEMUTEX And in /opt/piapi_1.3.1 /usr/lib/libstream. System Files Redistributed Cfront compiled version: /usr/lib/libC.ansi.4/dat/piclient.4/dat/piclient.cat ANSI C++ compiled version: /usr/lib/libstd.9.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. see one of the following sections: • • "UNIX Installation Procedures" on page 9 "UNIX Post Installation" on page 11 PI-API Installation Instructions 19 .1 /usr/lib/libCsup.o /opt/langtools/lib/end. you will need to create the following entries in their respective piclient. In /opt/piapi_1.3.In order for PI Interface node buffering to work for each of these two instances of the PIAPI.a /opt/langtools/lib/crt0.

20 .a On OSF1 3. cxxshrdae01307. one additional subset.2. or DEC UNIX. As the PI-API library is built with this compiler. is now required for programs compiled with the latest release of the C++ compiler.so /usr/lib/cmplrs/cc/crt0. this subset is distributed with the OSF PI-API and can be found in the PIHOME/lib directory after installation. The files on the CD must be extracted to the PI home directory.Z | tar xvf - Your tape drive may be configured as a different device. System Files Redistributed Most of the required files come on the base system CD-ROM.so /usr/shlib/libm. the operating system command “uname” will echo “OSF1” to the screen. Previous version were called DUX. The subset provides runtime support for this new compiler. in which case the device argument needs to be altered to conform to your local UNIX system.o /usr/lib/cmplrs/cxx/demangle /usr/shlib/libcxx. Extracting Distribution Files The PI-API-DUX is distributed on CD-ROM. For the purpose of this document. The files required and their subsets are listed below: Subset CXXBASEA132 CXXBASEA132 CXXSHRDA305 OSFBASE320 OSFCMPLRS320 OSFCMPLRS320 File /usr/lib/cmplrs/cxx/_main. The following commands will perform this: # cd $PIHOME # zcat /cdrom/osf1/piapi136_osf1_tar. OSF1 will be used. Consult your System Administrator if you have trouble accessing the tape device.o /usr/lib/cmplrs/cc/libexc_init.UNIX Installation Compaq UNIX for the alpha architecture is now called Tru64 UNIX. The proper subsets need to be installed to support C++ linking. Also.

4. run the following command: rpm -Uvh piapi-1.0.i386.i386.4. 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 Extracting Distribution Files The PI-API-LINUX is distributed on CD-ROM or by Internet download. 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.1. Upgrading an Existing Installation To upgrade an existing installation.1.0.2.Linux For installation procedures common to all UNIX platforms.rpm. The files are distributed as an RPM which typically has a name like: piapi-1.4.1.rpm .i386. On Linux. rpm -ivh piapi-1.rpm PI-API Installation Instructions 21 .

use the section [NETWORK] and key TIMEOUT to change the number of seconds for the timeout. such as –1. Often the best the program can do is trap for these errors and typically.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. local errors are related to the network layer system calls and to privilege and quota problems. To interpret these errors under VMS use the DCL command write sys$output f$message(#) where # is replaced with the returned error value. This indicates a communication failure. To interpret these run the command located in the $PIHOME/bin directory. Typically. The function argument is useful for error numbers that have multiple meanings. Remote errors are more difficult to address. use the [NETWORK] section and TIMEOUT key to change the timeout. system errors are usually even numbers greater than 6 (six) and can range from quota to file system problems.ini file. System Errors When communicating with PI on OpenVMS systems. When developing applications over a distributed environment. 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. On Windows. Calls to PI Systems on UNIX or Windows NT typically return system errors that are less than or equal to -10000. 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 PI-API Installation Instructions . For calls to PI on Open VMS. in the piclient. in the pilogin. On UNIX. 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.ini file. which can be returned when communicating with any PI server. Typically. errors returned which are greater than zero usually indicate a system fault. Most of these errors will have an accompanying message in the local message log. 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. The default timeout is 60 seconds but is configurable in the PI-API initialization files. the server node message log must be consulted to resolve persistent problems. Of particular note is the system error 2.

< 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 PI-API Installation Instructions .-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. 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. edited.

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 Can’t write the login initialization data PIPC initialization data not found Can’t find Windows directory Can’t find PIHOME or PIPCSHARE definition Server already exists 25 PI-API Installation Instructions . This section does not apply to interfaces.-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.

If one argument is given. apisnap [server[:port]] [tagname or \PointId. In order to test communication to the server. 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. the apisnap program will exit after giving the report for the tag specified. and provide a utility to test the values that reach the server. the first argument is the servername and the second is a tagname. . Also. 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. the apisnap utility is provided. the tagname prompt may be replaced by a backslash to indicate the following number is a point number.PI System Errors -113 Illegal server type Buffering Errors Buffering errors are reproduced in the section on PI Interface node buffering on page 46. If both arguments are specified.. This is useful for looking up tag names when only a point number is available. If two arguments are specified. Additionally. multiple tagnames may be entered if a list of snapshots is desired. the server to that you desire to connect must be specified.] 26 ..

TCP/IP for PI on OpenVMS The following VMS TCP/IP products (minimum required versions are listed) are supported by PI on OpenVMS. and several different UNIX platforms. distributed application support is provided by the PIServer program. Windows NT. Windows NT. referred to as a “listener. These systems are typically delivered with network support already included. and UNIX machines. In addition. Sun workstations using SunLink DNI) though TCP/IP is quickly becoming the predominant protocol and is delivered with Windows 9x. 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). DECNet is typically provided with the system. This server-side software is responsible for monitoring client connection requests and establishing and maintaining a session with each client. PI on Windows NT and UNIX Windows NT and UNIX PI Systems implement a single process. Product PI-API Installation Instructions Version 27 . and PI-Interface nodes are available for Microsoft Windows 3. pinetmgr. Some remote nodes can be configured to use either TCP/IP or DECNet (Windows 3. 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. Remote Nodes Currently two types of remote nodes are available: PINet nodes are available for VAX VMS platforms.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. Windows 9x. VMS PI Systems support communication using both TCP/IP and DECNet protocols.1. The PINet protocol is implemented on top of the network protocol. Windows NT and UNIX PI Systems support only TCP/IP. Not all remote nodes support the same set of features. This software.1 using DEC Pathworks. There is one PIServer process for each remote node connection. This section describes those differences and outlines what is required to enable client application support on the PI home node. Details of supported protocol stacks are provided below.” is implemented differently under PI on OpenVMS than under PI on Windows NT and UNIX. PI on OpenVMS When communicating with PI on OpenVMS. which is responsible for handling communication with remote nodes. but TCP/IP support must be purchased separately.

The command procedure PIBuild:AddPIServerUser. This user must be added to the VMS user database. PI System version 2. Listener Installation PI on Windows NT and UNIX The pinetmgr application comes pre-built with each system.1. For instructions on installing the PI Server see the publication. This is accomplished by running the VMS Authorize utility and modifying the PISERVER account. Once installed.7 is necessary if PI Server security is desired. Internally PI-API client nodes access the PI home node using the privileges and resources of the PISERVER account. It is started automatically with the PI Data Archive and does not require extra installation or configuration steps to enable communication with remote nodes.e. 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.0. user record(s) updated 1 2 Better known as UCX 28 Required for OpenVMS/AXP (i. PI Server security may be implemented via client node authentication and/or username/password login. The commands are as follows: $ cd sys$system: $ run authorize UAF> modify piserver /defpriv=sysprv %UAF-I-MDFYMSG.0.0.8 Programs which communicate using DECNet require version 2.Product Process Software TCPWare v3. the PI Server will support connections from many clients.dat file is VMS.1 is necessary if support for PI-ODBC or the batch (piba_) calls are needed.8 PI 2. spawning a new instance of the application for each connection.4 2 Attachmate Pathway release 1.com will add and configure this user account.6 or higher of the PI Server program on the VAX. Alpha) PI-API Installation Instructions . Note: PI System version 2.0.1 Version PI 2.0.1.8 PI 2. PI System Installation/Update Instructions . PI on OpenVMS The PI Server application must be installed on any home node where PI-API access is required.0 PI 2.1 Process Software MultiNet v3. Adding new clients does not require modification of this component.2 Process Software MultiNet v3. 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.

PI-API Installation Instructions 29 . PI Data Archive for Windows NT and UNIX for instructions on creating and managing users. It is also possible to set up proxy accounts for particular client nodes. The PI System Manager enables node authentication and login protection via the file PISysDat:PIServer. PI System Installation/Update Instructions. This security is in addition to any authentication mechanisms available through the native transport. See the publication. groups and proxies. Users and groups are defined on the server using the program piconfig. 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.Server Security PI on Windows NT and UNIX 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. For details on the format and use of this file see the publication. The file contains a default set of protections for nodes not mentioned in the file and explicit protection information on a per node basis.Dat. This security is in addition to any authentication mechanisms available through the native transport.

sending data directly to the home node. When enabled. Buffered data is maintained in First-In. 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. 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. Unless this file is modified to explicitly enable buffering.ini. Buffering is enabled through the use of a configuration file. First-Out (FIFO) order to avoid Archive inefficiencies and restrictions with out of order data. the PI-API will not buffer data. which stores and forwards events to the home node. This feature is available on UNIX. PI-API Installation Instructions 30 . piclient.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. the following calls will buffer all data sent to the default home node. Features PI Interface Node buffering consists of a buffering process which runs continuously on the local node. Windows NT and Windows 2000 platforms.

g. This file follows the conventions of Microsoft Windows initialization files with sections. Instead the buffered PIAPI detects the 0 timestamp and makes a call to pitm_fastservertime.Data is stored initially in memory until the allocated buffers are filled. it is recommended to disable buffering when installing. The following files are installed for buffering support: File Name UNIX bufserv bufutil isbuf piclient. illegal timestamp. /opt/piapi/dat). …) are logged by the buffering process when the data is forwarded to the Archive. Error Reporting When data is buffered. The delivered PI-API library supports both buffered and unbuffered calls. upgrading.exe N/A piclient. When the buffering process is shutdown. and configuring PI-API programs on an PI Interface node. For this reason. The file is found in the dat subdirectory of the PIHOME directory (typically c:\Program Files\pipc\dat) under Windows NT. Multiple interfaces on a single PI Interface node share the same buffering process and store data to the same buffers. keywords within sections. Errors logged by the buffering process are not propagated back to the program that originally inserted the data in the buffers.exe bufutil.ini file.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. All buffering settings are entered in a section PI-API Installation Instructions 31 . This allows interpretation of a 0 timestamp even when the server is down. all calls to the listed buffered functions that send data to the default home node are buffered. When the software is working satisfactorily.ini Windows NT bufserv. Errors typically detected on the home node (bad point number. (See the section below for possible errors returned by the buffering process and buffered API functions). re-enable buffering. and values for keywords. This function makes use of a server time and local time retrieved and stored on the local machine during the initial connection. the error messages returned by the standard PI-API calls represent the success or failure of moving the data to the buffering process. the file is found in the dat subdirectory of the PIHOME directory (e.. Buffered data may sit on the PI Interface node for an indefinite period before being sent to the home node. 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. Installation and Configuration There are no additional steps needed to install buffering after installing the PI-API. This makes storing a zero timestamp impractical. When buffering is configured to be on. 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. On UNIX systems. The difference between these times is applied to the current local time to calculate the current server time without calls to the server. Data is then stored in a file whose maximum size is configurable.

000.000 12. keywords PIHOMENODE DSTMISMATCH Values string 02.000. To modify settings. On Windows NT this information should be stored in the pilogin.000 12.000.000.000. 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. DSTMISMATCH=0 [TCP/IP] PORT=5450 [APIBUFFER] BUFFERING=1 MAXFILESIZE=100000 . OFF = 0.000 Default none 0 Description Default server for UNIX.ini file.ini file might look like: [PISERVER] PIHOMENODE=MYNTSERVER .000 Default 0 2 Description Turn off/on buffering.ini would only have the [APIBUFFER] section.Configuring PI Interface Node Buffering called [APIBUFFER]. 3600 if the nodes are in timezones whose DST rules differ (seconds) Under UNIX a piclient.000 500 32768 32768 100 On UNIX. so the piclient.000 64 2. the PI-API connection routines have 1 minute default timeout 32 . Primary memory buffer size. (bytes) Secondary memory buffer size.000. The following settings are available for buffering configuration: keywords BUFFERING PAUSERATE Values 0. in addition to the [APIBUFFER] section. simply edit the piclient. (bytes) The time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds) RETRYRATE 120 MAXFILESIZE MAXTRANSFEROBJS BUF1SIZE BUF2SIZE SENDRATE 100.000 02.000.ini The time that the server and client local time offset is allowed to jump. and an optional time offset change that may occur between the client and server. Typically.000 64 2. (Kbytes) Maximum number of events to send between each SENDRATE pause. the [PISERVER] section may be used to define the default PI Server. Windows default server is in pilogin.000. vi on UNIX) to the desired values.ini file in a text editor (Notepad on Windows. ON = 1.000 02.1 02.

Otherwise. so that these programs can access the shared buffering resources. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a connection before retrying. users who are part of the Administrator group). Comment lines begin with a semicolon. 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”. to determine if the piclient. Under Windows NT. the bufserv process must be started before other programs using the PI-API.RETRYRATE=600 The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. The [PISERVER] and [TCP/IP] sections are used to define the default connection. pistart will run bufutil with a -u argument to clean up any outstanding resources and then start the buffering process. Note When buffering is configured to be on. 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 script runs a small program. The buffering process. This is done by the installation program if bufserv has not previously been installed as a service. The installation program on Windows allows the service to be configured to automatically start upon reboot dependent upon the successful startup of TCP/IP. is responsible for initially creating these resources and making them available to the PI-API functions. Do not use commas or other separators in the numeric entries. Startup On UNIX platforms. the service must be given a username and password that has permissions to create and delete shared memory (for example. awareness of buffering has been built into the pistart script delivered with the PI-API. When the bufserv process is installed. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI. bufserv. If this is true. On Windows NT the default server information is stored in the pilogin. implemented by the bufserv program. Fill in a user name and password that have the appropriate Administrative privileges.ini would only have the [APIBUFFER] section.ini file so the piclient. the buffering process is installed to run as a service by the installation program. isbuf. PI-API Installation Instructions 33 .ini file contains instructions to turn buffering on.

If bufserv is not installed with a StopPriority. The most common occurrence being that "Intf Shut" will not be written to the Interface points when Windows is shut down.9.bat or pistop. highlight the service name and use the Start or Stop button. The installation kit under Windows NT installs the bufserv service with a StopPriority of 0. If for any reason the bufserv service needs to be uninstalled and reinstalled.2 of the PI-API and later. this insures that when Windows is shut down.bat scripts. Alternately. StopPriority is a feature supported in version 1.3. services which depend on bufserv will get shut down first. To modify the dependency list of a service that is already installed. interfaces are installed to be dependent on bufserv.bat files provided with this distribution. To complete the configuration for using the pistart. Dependencies are defined during installation of each service. some data loss may occur. 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. 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. This set of options is displayed by typing bufserv –help.bat and pistop. Just as bufserv is configured to be dependent on tcp/ip.Configuring PI Interface Node Buffering The bufserv program may be started or stopped using the pistart. To use the Control Panel> Services utility. You can install interfaces from the command line or in some cases there may be a preexisting 34 . the Control Panel> Services utility may be used to start and stop bufserv manually. If bufserv and the interfaces are started "automatically" the service installation must include this dependency. the scripts must be configured as in the examples provided for your particular client program.

They are waiting for the resources to become available. enclose the dependency list in quotation marks with the individual dependencies separated by spaces. On Windows. trying to make a connection. In this case. the buffering process exits. When the process shuts down. To set an interface’s dependencies. The control panel may be used to stop the interfaces and buffer server. Stopping Buffering To stop the buffering process. open a command window and change the current working directory to the directory where the interface executable resides. PI-API programs will hang. it tries to create the resource and fails because the resource already exists. Then remove the interface: intfc –remove where intfc is the interface executable without the . creates the resource itself. manifests itself differently under UNIX and Windows NT. first stop all programs that use the PI-API. they must stop first before the buffer server will stop. Install the interface specifying the desired dependency list.bat file should be modified to contain the interface stop commands. if the interface services have been made dependent on the buffer server. When the buffering process is started.installation script that will need to be modified. 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 buffering is configured to be on. In this case the bufutil program. On UNIX. including bufserv. ############################################################################### # @(#)sitestop1. and optionally the automatic startup flag. bufserv. the first program trying to obtain the resource.bat file may be used. PI-API programs will run.exe extension. intfc –install –depend bufserv [-auto] To include multiple dependencies. An appropriate application start script # should be inserted into the sitestart file or the verify_stopped() # routine below may be used. the pistop. To rectify this situation. On Windows NT. described below. Again the program(s) must be stopped and the buffering process started. should be run with a -u parameter to unlock and remove the created resources before attempting to start the buffering process. the program(s) should be stopped and the buffering process started. but attempts to subsequently start the buffering process will fail.3 2000/07/25 # File: sitestop # # This file is provided to allow site specific applications to be stopped # whenever the pistop is executed. it will forward or store the contents of its memory buffers so that data is not lost. The sitestop. Also. For example: … -depend “bufserv tcpip” Failure to start the buffering process before running PI-API programs. PI-API Installation Instructions 35 . Then use the bufutil program to stop the buffering process. An example of a script that checks to see that an interface is stopped on UNIX nodes is given here. The procedure is to remove the interface as a service and reinstall it with the dependency on bufserv.

kill $pid lcount=0 dcount=0 while [ ${pid:-0} -gt 0 ] do if [ ${lcount} -gt 300 ] then break. 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.\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 .Configuring PI Interface Node Buffering # ############################################################################### ## Boure shell script to check process shutdown. fi sleep 1 echo '.

It contains a section [PIPC] with an entry for PIHOME which identifies the location of the PIHOME directory. a typical process can generate 1500 exception events/day. memory buffers fill and events begin to be written to this file. If you typically have much less data throughput. either increase MAXTRANSFEROBJS or decrease SENDRATE. When data arrives faster than it is forwarded (data burst. a maximum of 5000 events per second will be sent to the PI server (500 events times 10 per second. This buffer file is not initially installed but will be created when needed by the PI-API. this may be used to limit the rate at which any one node adds data to the PI server. For example. PI-API Installation Instructions 37 . this file is located in the dat subdirectory of the PI home directory as defined in the pipc. When that fills. 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. the file still contains 16 bytes of header information. Buffer File During operation. the buffering process can be in one of three states corresponding to the buffers it is using. the buffering process writes data to a file called APIBUF. Initially it uses a single memory buffer. A typical event uses 23 bytes in the file buffer (a float32 point). server down). 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. it switches to using dual memory buffers. Buffer File Maximum Size The maximum size of the buffer file may be adjusted by the MAXFILESIZE parameter. If the pipc. estimate the number of events generated by the interface. 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. When truncated. Do not fill the disk. but slightly less because of network transfer time and moving the data from buffers to the TCP/IP port). If the default configuration is used. it switches to using dual memory buffers and a file. When these buffers become full.DAT.ini file is not available or does not contain an appropriate entry.ini file. The current state of buffering as well as the status of each buffer can be examined with the bufutil program discussed below.ini file is found in the WINDOWS directory (note the name may vary from system to system). Depending on the amount of data being buffered. Under Windows NT. 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. and a file buffer.} # EXAMPLE: # verify_stopped buftest Buffering State Three buffers are used to process events: a primary memory buffer. If a higher throughput rate is needed. when memory buffers become full. To estimate the value for this parameter. the file is written to the Windows temp directory. a secondary memory buffer. The pipc.

dat file should use a tag attribute mask of shutdown. which can be misleading. or the PI server may be stopped while the API continues to buffer data. The program collecting the data is responsible for writing the status indicating that the PI Interface node was shut down. when the server comes back up. the buffered data is forwarded and there is no data loss.1 This will ensure that the points collected by the remote PI Interface node will never have shutdown written by the PI server.ignored. The shutdown event can also cause buffered and subsequently forwarded data to be out of order. 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. server error messages from buffered functions are logged rather than being returned to the calling program. In fact.no longer used . Without buffering. localhost ! tag mask * ! tag attribute selection (logical AND for all attrib) ! point attributes. For this reason. In the case in which the PI server node must be rebooted most points should receive a shutdown status. only those points for which the PI server generates data should receive shutdown. The calling program instead receives an indication of the success or failure of the buffering process. ! shutdown.Configuring PI Interface Node Buffering Interface Installation During initial installation. configuration. inserting shutdown events in points that are buffered gives an erroneous picture of the data. When the PI server is stopped. Shutdown Events Shutdown events are typically written into points to indicate when the PI server is taken off-line. Without shutdown events. 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. such as “Intf shut” or “I/O timeout”.1 as shown here. As described under Features. ! login info . A shutdown event is irrelevant. that every point which is collected on that system should receive a shutdown event. These two situations are handled differently on UNIX and Windows PI server nodes. The interface documentation will 38 . points that are buffered on a PI Interface node or PI home node should not have shutdown events written by the home node. it is clear when the PI server stops running (shutdown or system crash). With buffering running. Disabling buffering during shakedown provides more immediate indication of problems. 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).value to select points receiving shutdown shutdown. causing undue load on the PI server and slowing down forwarding. This allows an end user to recognize the discontinuity of the data. and testing of an interface it is advisable to disable buffering. the data looks like it has been interpolated over the time the PI server was unavailable.dat: Shutdown for server points.

rem rem $Archive: /PI/3. It only uses the shutdown..\bin\%%i -start & pidiag -w 5000 ) set piss=piupdmgr pibasess pisnapss piarchss for %%i in (%piss%) do ( .\bin\pishutev -f shutdown_C. Note that time-based calculations are not performed when the base system is down.dat file when starting as a service. Event-driven calculations are likely to be wrong when the system has been shutdown and the triggering events have been buffered.dat .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 . G.dat file should be the same as shown under the remote PI Interface node section above. the shutdown.. .have specific instructions on implementing shutdown. set piss=pinetmgr pimsgss for %%i in (%piss%) do ( . totalized. @) are examples of locally collected tags that should be listed in shutdown.. The section between the “Change this section” comments below has been changed..2/nt/scripts/pisrvstart. and alarm points. PINet nodes (VMS clients) currently support sending shutdown events for interfaces collected on the node when the PINet node is shut down. the PI service pishutev will run automatically.. Windows NT PI Home Node Shutdown Events On Windows NT.\bin\pishutev -f shutdown_AT..\bin\pishutev -f shutdown_G. All tags with the shutdown attribute set to TRUE will receive shutdown events. On reboot of the NT node.. rem === Change this section (below) >>>>>> rem Do pishutev separately. both PI server tags and those which are buffered on the local node should have shutdown=TRUE. A shutdown event in this case alerts the end user to invalid data. Calculated and alarm tags (pointsource C..\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. calculated.dat .bat $ rem rem Non-Interactive PI Startup as NT Services rem rem Start the Base PI Services rem echo Starting Base PI System Services. 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. For the case when the PI server is rebooted.. This should include locally buffered points.bat file needs to be modified so that the shutdown.dat file is not run by pishutev.dat files.

.\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. if (( flag_reboot == 1 )) then echo Adding PI Shutdown Events if [ -r `./piparams -pl`pishutev.value to select points receiving shutdown shutdown.dat: Shutdown for Calculated server points. ! shutdown_C... 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 .Configuring PI Interface Node Buffering for %%i in (%piss%) do ( . Add a new flag option of -reboot..dat file copy should be made to include only those points that are not buffered.dat file for each point source as shown here.. *) print "Unknown Command Argument" $CMDARG . ! login info . *stdout ) flag_standardout=1 .sh script should be modified to switch behavior between a system reboot and a PI server stop and start with buffering still running.ignored. *reboot ) flag_reboot=1 . *base ) flag_basestart=1 . localhost ! tag mask * ! tag attribute selection (logical AND for all attrib) ! point attributes. esac done Then add conditional behavior for pishutev later in the script. M ) flag_minimal=1 .C* UNIX PI Home Node Shutdown Events The pistart..1 pointsource.. This may require a separate shutdown.log ] 40 .bat :theend A separate shutdown.no longer used .

sh ] ./piparams -pl`pishutevC. the starting and stopping of the buffering process is logged./piparams -pl`pishutev. #!/bin/ksh # # Filename: Pistart # if [ -f /opt/PI/adm/pistart. the automatic startup scripts for the PI server need to be modified to pass the -reboot flag to the pistart./piparams -pl`pishutevG./piparams -pb`pishutev -f shutdownG. These errors can be translated using the pilogsrv utility file delivered with the PI-API. Winsock errors are listed in the file winsock./piparams -pb`pishutev -f shutdownAT.dat > `. In particular systems using WINSOCK implementations can receive errors in the range 10000 to 11005./piparams -pl`pishutev. Errors may be written to this file at any time and periodic inspection is recommended.log. Under UNIX the log file is called pimesslogfile and is found in the $PIHOME/dat directory. receive. It is also possible to receive errors from the protocol layer.old fi `. error logs and the buffering utility bufutil.then mv `. The log file should be examined whenever the buffering process is started to ensure correct startup.dat > `./piparams -pl`pishutevAT. PI-API Installation Instructions 41 .log and is located either in the PIHOME\dat directory or in the WINDOWS temp directory. These errors are associated in the log with messages describing socket connection.sh script.log 2>&1 & `.sh -reboot fi Monitoring the Buffering Process Two methods are used to monitor the health of buffering. Specification of the PIHOME directory is discussed earlier under the discussion of the buffer file.log 2>&1 & else `./piparams -pb`pishutev > `.log 2>&1 & `.000 and growing downwards. In addition to errors. Error numbers found in this log correspond to messages that may be found in several sources. For a list of common errors.dat > `. Positive error values represent system errors and may be VMS errors (PI2 Servers) or communication errors.log `. or send errors and are thus discernible from the PI3 messages./piparams -pb`pishutev -f shutdownC./piparams -pl`pishutev. see "PI System Errors" on page 21. When working with PI3 Servers. large negative error numbers are returned starting at -10. Under WINDOWS this file is called pipc.h provided by the protocol stack vendor. Error Log The PI-API writes error messages to the log file on each system. then cd /opt/PI/adm nohup ksh pistart.log 2>&1 & endif Finally.

Running bufutil with no arguments brings up a menu of choices. the Mode. Events in the file are moved to the primary buffer as space becomes available. The program when run without arguments presents a simple text menu of choices. enable buffering in piclient.ini. buffering is using a single memory buffer in this display. Server status and the Unprocessed entries are the most significant for monitoring the buffering process. In Dual Memory mode. To enable buffering. buffering has not been enabled in the piclient. The server status may indicate “Connected”.2. 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. 42 . When the status is disconnected. The mode shows the current buffering state.ini file by entering BUFFERING=1. In Dual Memory and File mode. The presentation is the same on all platforms. In other buffers. bufutil. events in the secondary buffer are moved to the file when the buffer becomes full. Choices 1. events in the secondary buffer are moved to the primary buffer when space is available. The Unprocessed entries shows the number of items in the buffer that have yet to be handled. the destination of the Unprocessed events depends on the mode. In the display above. and restart the buffer server before starting other PI-API programs. “Disconnected” or “Connected [Buffering OFF]”. Other options are “Dual Memory” and “Dual Memory and File”. If “[Buffering OFF]” is indicated. the buffer server will buffer events until the server is once again connected. stop all programs that use the PI-API. Certain functions in bufutil can be run in non-interactive mode through the use of command switches. is provided to examine the current state of buffering and to shut down the buffering process. In the primary buffer Unprocessed entries refers to items not sent to the server.Configuring PI Interface Node Buffering Bufutil A utility program.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.

Entering bufutil -k to a command prompt shuts down the buffering process. a program may lock the resources to add event data to the PI-API Installation Instructions 43 . The position shown above. As described earlier. to assess the current buffering mode and the amount of data stored in buffers. you can watch it change. is used to stop the buffering process cleanly. 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. The Version item reports the version of buffering being used. In a typical session. and then exit. “Quit”. 16. like the file size will then move from a large number to a small one. The Current read position marks how far through the file the buffering process has progressed. It will then lock the resources. for future compatibility issues. the read location moves forward. the buffering resources become locked. represents the file header. move memory information to file. Interfaces and other programs utilizing the PI-API on this node should be stopped prior to killing the buffering process. 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. These buffers wrap around so the write location can be behind the read location. As events are buffered. The display does not update dynamically because querying the information requires a brief locking of the buffering resources. As events are removed.By observing the Mode and selecting the desired buffer you can watch the buffers grow and shrink. Item 5. the write location moves forward. This method is used in the pistop script under UNIX when stopping the API. is used to exit bufutil. The size is the size of the memory buffer and will remain constant. Item 4 on the bufutil menu. much like selecting item 4 in the bufutil menu. 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. Instead. Bufutil also supports two command line switches which bypass the normal interactive interface. For example. 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. bufutil is invoked and several buffers are examined. The write and read locations are used to handle inserting and removing values from the buffers. The Count contains the number of unprocessed events in the file buffer. The read position. Selecting this item will send a message to the buffering process that it needs to shutdown. Unlocking Resources The other interactive command: bufutil -u is used when due to problems during startup or program crashes. by repeatedly selecting a buffer. perhaps repeatedly. As the buffer is a fixed size and the event size can vary. “Kill server and quit”. Alternately. Then “ Quit” is selected to exit the monitoring utility.

as well as other nodes. not what is currently in the buffers. bad point number. 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.ini (UNIX) or pilogin. Limitations As described under Features. Errors with the contents of those events (e.ini (Windows) file.Configuring PI Interface Node Buffering buffers and then crash before it unlocks the resources. In most cases. Typically semaphores can only be removed by the user that created them. Only data sent to the default home node are buffered. are not detected until the event is forwarded to the home node. Other programs and the buffering process are then prevented from accessing these resources. Error returns from buffered functions return the success or failure of buffering the events. 44 . illegal timestamp) are written to the PI Interface node log when encountered. Other PI-API calls continue to be processed through the program’s connection to the home node. 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. Data stored in the PI Interface node buffers is not accessible to retrieval calls until it is forwarded to the home node. and then the buffer server and other API processes restarted. all talking to the same PI server. the home node must be available. PINet nodes store a copy of the point database and snapshots for points that are collected locally (by interfaces on the PINet node). or if different users start different PI-API programs on a UNIX system. The pistart script uses this command when it starts to ensure that it can cleanly start the buffering process. This is similar to the operation on a PINet node when requesting values for points that are not collected locally. Calls on the PI Interface node. The default home node is set in the piclient. slow or a burst of input data on the PI Interface node. you may run into this problem. Under UNIX this would typically be accomplished by running the pistop script followed by the pistart script.. as discussed earlier. Until events leave the input queue and go to the snapshot they are not visible to retrieval calls. An interface starting on a PINet node can query this local information during startup and succeed even when the home node is down. a PI Interface node will support a small number of interfaces. these processes should be stopped. 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. only a subset of functions make use of the buffering process. This limitation is a difference between PI Interface nodes with buffering and PINet nodes. the majority of server communication involves sending data to the home node that is handled with buffering. Errors generated by bad event data. Once an interface is started. This performance is also seen on a home node when input events are being buffered. “su” to root and run bufutil -u. Occasional requests for home node data will time out if the home node is down. for recent data will return the most current snapshot on the server. This situation may be due to the home node being down. though a well written interface will survive these time-outs and continue to send events. If a different user tries to stop PI than the one who started it. The information retrieval calls continue to be processed through connection to the home node and are ignored by the buffering process. To recover cleanly. Under certain error conditions. it may be necessary to become root before running bufutil-u to succeed in removing the resources. bufutil run with the -u command (unlock). For these requests to succeed.g.

Under certain conditions. run bufutil -u to unlock the resources.DAT file is accessible by the process reporting the error. This problem can also occur if a program which had these resources locked has abnormally terminated. run bufutil -u to unlock any locked resources and restart the server and associated processes. stop any PI-API programs running. and retry bufutil. Under UNIX.ini file to turn buffering off and retry the program. If you find a zero-length buffer file.ini file but the buffering process. Under UNIX this is $PIHOME/dat. a PI-API program. The resources have not been created and bufutil. Unable To Create Buffer File APIBUF. or from logged error codes shown in the next section. is patiently waiting for the resources to become available. Under Windows NT this is the dat subdirectory under the PIHOME directory specified in the pipc.Troubleshooting The following section details some common problems that may be encountered with PIAPI programs when buffering is turned on. Bufserv Exits Immediately When Started You can detect that the process has exited by searching for it in the process list. remove the zerolength file. one or more error messages found in the log file. Stop the program.DAT file. Waiting a few moments is advisable to allow the process to release its PI-API Installation Instructions 45 . Also verify that any existing APIBUF. restart bufserv. PI-API Programs Hang on UNIX This occurs when buffering has been indicated in the piclient. bufserv. Such a file is invalid and will defeat startup. Alternately change the piclient. The file should be 16 bytes (the header data) or larger if present. double-click on the background to bring up the task list and look for the bufserv process.DAT Verify that the buffer file directory is writeable by the offending process. The solution is generally to stop any other PI-API programs if they are running and run bufutil -u to unlock the resources. Start the buffering process and retry the program that was hanging. Then when bufserv is started again it can create the resources. was not started before other PI-API applications which make connections. an earlier startup failure can generate a zero length APIBUF. Also check the log file for messages about inability to create buffers. In this case. use ps -ef | grep bufserv Under Windows NT. stop all PI-API programs. Trouble Opening or Creating the Shared File Memory Object Check file and directory permissions as described above. The descriptive text identifies the condition that may be indicated by program performance. Running Bufutil With No Arguments Hangs Without Presenting a Menu This is typically the same condition as “PI-API programs hang on UNIX” above.ini file or the WINDOWS temp directory if this entry is not found. Bufutil Hangs When Requesting a Status Display This condition usually indicates that the buffering resources are currently locked by another process.

Opening or Removing Semaphores Stop all PI-API applications. and retry bufutil. This allows approximately 1200 events maximum per putsnapshot call. it is likely that a program has abnormally terminated while holding a lock on these resources. stopping the buffer server last. a shared memory object was found already created. It was not found. restart bufserv. run bufutil -u. the buffer server uses 32768 bytes of shared memory for each of the memory buffers. Then run pistart (UNIX) or restart bufserv (Windows NT). 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. 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 . Unable to Put Event into Secondary Buffer: -170 The buffer full error. become root (“su”) and run bufutil -u again.ini . Stop all PIAPI programs. If problems persist in UNIX. may indicate that a program attempted to insert an array of events bigger than the memory buffer can hold. Errors in the Log File about Creating. Run bufutil -u. By default. Buffering Error Codes Functions which implement buffering internal to the PI-API return error codes in the range -150 to -190. On UNIX run pistop.Configuring PI Interface Node Buffering locks when it is done accessing the shared resources. When creating shared memory. Increase the memory buffer sizes using the BUF1SIZE and BUF2SIZE entries in piclient. The majority of these errors will not be returned to calling routines. -170. Error obtaining a memory handle for a shared memory region. If the hang continues. 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.

INI file was not found.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.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. 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 PI-API Installation Instructions 47 .

A partial table is included here for reference.Appendix A: Microsoft Winsock Errors Windows socket errors do not currently have a routine to translate error numbers to text. or unsupported option or level was specified in a getsockopt or setsockopt call The requested protocol has not been configured into the system. invalid. 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 PI-API Installation Instructions 49 . 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. 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.

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. 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 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 PI-API Installation Instructions .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. 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.

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 PI-API Installation Instructions 51 .

...........................37 monitoring the process.......................................... LIBPATH...26 Home node......................................................15 UNIX............. 42 communication...........................................................................DAT..........................................37 buffered functions..7 Cron Job....35 throughput...............................................................................................................................................................................................................17 52 ..26 apisnap utility................................................................ 21 Solaris...............13 Windows.....................................................24 Point Attribute Access......................................................................................................................................................................10 Dr...Index AIX...................................26 apiverify.....23 Event Counters......5 HP-UX......................31 System........33 startup............................9................................................ buffering...................................................................UNIX................................................................27 default debugger................................46 errors............................................4 Distribution Files......................................... remote nodes..............................30 buffering state............44 maximum file size..........................................................31 immediate exits.............................................................................................................................................................................ini files.......... Archive Access......23 Reporting...................38 limitations.................................................................................................................................................................................................45 bufutil.........31........4 logging....................20................................4 installation..............................................13 buffering................................................................7 file format...................................... .......................45 apisnap................................................37 bufserv.................................. UNIX....................................................................................37 configuration of..... 21 Environment Variables...........................................41 EVM Routine....4 DUX..............................17 APIBUF.................................................................................................12 PI Interface Node Buffering.....................14 debug symbols...........30 TCP/IP.................4 DECNet.....................................................................31 Open VMS.......................... AIX.....................................................................17 HP-UX................................ drwtsn32...................................10 AIX ..log...................................................................33 stopping..................................................... UNIX.........................................................................19...4 not on Windows 9x..............................................................27 Configuring...................................................................... 21 Errors.............................41 operation. Watson............30 buffer file..........................31 Error Codes.......................................................................................................................................25 Error Log.........................18 OSF1............................................................................. TCP/IP.....12 PI-API Installation Instructions Control Panel> Services utility................

.................................................................12............................ default timeout.......................................................................................................................................... mqmgr..................................................................................................................7........................................................................................................................................................................34 iorates..................................................................11 installation log...................................................................................28 PI-API nodes.. 31 APIBUFFER.............23 version 2.32 BUF1SIZE..........................4.........................................................32 Limitations..........................................................................................install..... 37 NETWORK..... AIX.......................................dat.....19 listener.......................ini......... 32 RETRYRATE..........32 MAXFILESIZE...............................................9 UNIX Script.......................................... 46 BUF2SIZE.......................................32 TIMEOUT..... 7....................................... Windows...........................................................................SHLIB_PATH...........31 HP-UX.......................3 Installation log............................................. installation... dependencies...................1................... 42 Default node............14...........4 Installation...32......44 DSTMISMATCH....11 interface............................ 5................................................................................................................................... remote.......................................................23 pilogin................log...................................................6 nodes......................................6 NETWORK.................17 HP-UX.........................................32 MAXTRANSFEROBJS...............................28 software.........32..........27 organization of documentation..................................32.............................6 HELPFILE...............................................................41 Purging..............................................12 piclient.......................38 UNIX.............. 37 TCP/IP..............................44 Defaults............... buffering..................................... 41 pipc.................... Errors................................................32 SENDRATE.............................................................. LD_LIBRARY_PATH.......................................... 46 BUFFERING...........................................................23 PAUSERATE....14 pilogsrv.....4 Initialization Files................14 mqsrv.........................................................14 Login Services errors...................................... 32 PORT....................................................31 keywords.........10 initialization Files............................ pinetmgr.......................................23 53 ......................... UNIX..0........3 Node buffering........................................................................................... Disable Buffering.............28 version 2................7 pimesslogfile......................................................................................................................................................................32....................1 OSF1..................................................................................7................................10 PI Home Node.........................................................27 pi.........27 PI System.................................... 6 Default node................................................ 13 isbuf..............44 Linking....................................................................................................30 PI-API Installation Instructions Node Identifiers.................................... of the buffering process.....................32 PIHOMENODE........32......................................................................25 Microsoft Operating Systems.............................17 Interface...............................................27 PI Server..................27 Log files..............................................23 location..........ini...12..............................................................................................................................1..12 PI server.........................................4...........................

......... 44..............................10 Shutdown events....43 Winsock errors....................5 MAXPIPCLOGS..5 PIPC........6 TIMEOUT... buffering.................................................................................................................................................................................................................................................................................................................................... server....26 nodes......5 pipc...............45 Shared Library Path......................................................................................39....27 root............................................41 WinSock TCP/IP protocol stack................................................................................................................................................. 23...............................................17 HP-UX.....................28 pipc........................................................................5 PIHOME.................. 545...............27 Troubleshooting....11 remote nodes................ 40 PI Interface node............................4 ....3 System Configuration.............................................................................7............39..............................12 %WINDIR%\symbols........................................................................................27 pinetmgr.................. 46 security.............................Dat................................h.........10 Stopping PI............................. 39 protocol.6 SERVICES............................................... 41 MAXLOGSIZE.....................................................................................................................................44 server..................bat......................................................15 LD_LIBRARY_PATH.......................................................................................7 MAXPIPCLOGS.......................................................................5 PIServer........................................................................dat......... AIX.29 port........... Errors... 5 MAXLOGSIZE..................................4..............38 54 pishutev.................................27.......................................................6 5450..............9 unlocking resources............................... PI Server Support for........................................ UNIX Installation..log.............................31 Shared File Memory Object..38 home node..................................................................................39 Solaris........................13 subdirectories.......................................................................................................................................6 Post Installation...................9.....................................................................................19 OSF1...Index PINodeIdentifiers......................... winsock.......................................................................29 semaphores....................6 PIServer.... UNIX.......................................9 System Files Redistributed............................................................................................................................................................................40 shutdown...45 UNIX Installation Procedures.............................sh...................................... 40 pisrvstart.....................7 PINet...........................................................................................................................23 pilogsrv.....................20 Solaris......5 PIPCSHARE.......... created during installation...............................................................................................17 TCP/IP.................................................... Timestamps.39 pistart......ini...3 site-specific applications.........

PI-API Installation Instructions 55 .

You're Reading a Free Preview

Download
scribd
/*********** DO NOT ALTER ANYTHING BELOW THIS LINE ! ************/ var s_code=s.t();if(s_code)document.write(s_code)//-->