UNIX Installation Procedures

The PI API library is available on a number of UNIX platforms. Many of the procedures for installing and configuring the software on these different platforms are identical. When installing one of the UNIX versions, consult this topic and also the topic for the particular platform for specific details.

For systems with previous installations of PI API, make a backup of the PI API directory. The UNIX tar command may be used or a separate installation directory may be used. To use the tar command, use the following commands:

  cd $PIHOME
  tar cvf piapi_previous.tar ./*

To use another installation directory, rename the PI API directory and create another PI API directory with the previous name. The shell initialization files will not need to be changed in that case.

  cd $PIHOME
  cd ..
  mv piapi piapi_old
  mkdir piapi

Note: To compile your own PI API programs, you MUST have an ANSI compliant C or C++ compiler. If your compiler uses command line switches to enforce ANSI compliance these should be specified when building applications.

System Configuration

When planning the installation, allocate sufficient disk space for log files created by PI API (pimesslogfile) and the buffer file created by API Buffer Server (apibuf.dat). If log files and buffer file(s) are not managed, they can grow until available disk space is filled, which may adversely affect system operation.

Space requirements for log files depend on the number of interfaces and your site’s normal message volume. Space requirements for buffer file(s) depend on the values defined for one or both of the following parameters: MAXFILESIZE and MAXFILECOUNT. MAXFILECOUNT is used only on UNIX and Linux platforms running PI API 1.6.6 or later. (In PI API version 1.6.4.x on those platforms, the maximum file count was 10,000.) Both parameters are defined in piclient.ini. For more information, see the topic titled "Configuring Buffering using bufserv".

In addition, OSIsoft recommends that you set up a cron task to periodically delete old log files in accordance with your organization’s data retention policy. For more information, see "Purging Log Files" later in this topic.

The PI installation scripts should be run with super-user privileges (root). If the installation of system files is required as determined by the installation script, and another user is used during installation, errors will be logged to install.log.

Some interfaces must be run by a specific user account to collect data. As a general rule, the account used to run the interface should also be used to run PI API. To ensure that the required permissions are available to start these programs, the same user account should also own both the interface and PI API. Refer to the interface documentation to find out whether a specific user account is required for a particular interface.

If your interface does not require a specific user account, a user named piadmin and a group named pigrp may be created for using the PI API software. This should be done using system administration tools provided by the operating system vendor.

Environment Variables

The PI API installation procedure requires the definition of a PI home directory. The PI home directory is typically set to /opt/piapi or /home/piapi, although any directory name in a partition with adequate disk space is suitable. Use the df command to determine the amount of disk space available.

For example:

# mkdir /opt/piapi

If you are also installing or have already installed a full PI System on this machine, it is advisable though not required to define a separate PIHOME directory for the PI API installation. Once the directory is created, the PIHOME environment variable must be defined to point to this directory. From the Korn or Bourne shell the command is:

  # PIHOME=/opt/piapi
  # export PIHOME
  

or using C shell:

  # setenv PIHOME /opt/piapi
  

Shared Library Path

On systems where PI API shared libraries are installed, (Solaris 2, Compaq Tru64, IBM AIX 4.2 and greater, HP UNIX), it is recommended to leave these libraries in their installed directory and set the proper environment variable for the platform to allow run-time access to these libraries. Note that any user running programs linked to these shared libraries must have this variable defined. An alternative is to copy the PI shared library to /usr/lib, which is checked by the dynamic loader at run time. However, this can lead to conflicts with other installations or be overwritten with operating system upgrades.

Platform Library Path Environment Variable
Solaris 2 (SunOS) LD_LIBRARY_PATH
HP Tru64 (OSF1) LD_LIBRARY_PATH
Linux LD_LIBRARY_PATH
IBM AIX (AIX) LIBPATH
HP UNIX (HP-UX) SHLIB_PATH

For example to set the dynamic library path for a Solaris system in the C shell use:

  setenv LD_LIBRARY_PATH /opt/pi/lib
  

or

  setenv LD_LIBRARY_PATH $PIHOME/lib
  

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

  setenv LD_LIBRARY_PATH "/opt/pi/lib:/usr/local/mylibs"
  

Extracting Distribution Files

The PI API directories should be backed up before beginning. The $PIHOME/dat/piclient.ini, iorates.dat, $PIHOME/bin/sitestart, and sitestop files contain information specific to the client program used on this API node and may need to be replaced with the backup versions.

The CD-ROM distribution media should be mounted as a directory (in the instructions below, /cdrom will be used. Substitute the actual pathname if necessary) and the full path to the tar file should be used in the extraction command below. If the file was retrieved as an Internet distribution, the file may be placed in the $PIHOME directory. The distribution files are extracted with the tar command to a temporary directory with the following commands:

# cd /tmp

# zcat piapi133_sol2_tar.Z | tar xf –

or

# zcat /cdrom/sol2/piapi133_sol2_tar.Z | tar xf -

The temporary directory should contain only the directory build after extracting the files. On all UNIX platforms the build directory contains the distribution files and the installation script, pi.install, which is run to complete the installation.

Running the Installation Script

To complete the PI API installation on all UNIX platforms the installation script, pi.install, must be run. To install the example C program and header files need to compile programs, execute the pi.install script with the "-pgm" argument. The root user should run the installation script. For multi-platform compatibility pi.install, and all platform-independent PI scripts, are written for the Bourne shell. If the Bourne shell is not the default shell for the user doing the install, pi.install must be explicitly run from the Bourne shell as shown below.

The following commands will run the pi.install script:

  # cd $PIHOME/build
  # sh pi.install -pgm
  

For all installations and upgrades, the pi.install script prompts for a user name (default user is piadmin, which must exist). Enter the name that should be set for all files in the $PIHOME directory tree. The user name entered must exist. If this is a new installation, pi.install will prompt you for a default PI Node name. The TCP/IP host name of the node running the PI Data Archive should be entered. The script asks whether the default home node is a PI2 (OpenVMS) system or a PI3 (Windows NT or UNIX) system. This script also creates several directories, builds the PI API library, installs system files (if needed) and links PI application and example routines. A listing of the PI home directory should show the following directories:

  bin
  build
  dat
  include
  lib
  src
  

During installation the file $PIHOME/install.log is created. If errors occurred, please review this file to determine what corrective action should be taken. If an obvious solution is not evident, save the file for OSI Tech Support to review.

UNIX Post Installation

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

Preparing Site Specific Applications

Site specific applications, such as interfaces, may need to be linked with the newly installed library. Applications that were linked with the shared PI API library will usually run without relinking. Commands may be added to the sitelink script, which is called by the install script to expedite this process. Launching and terminating site specific applications is accomplished through the sitestart and sitestop scripts which are called by the installed scripts pistart and pistop. Modify the sitestart and sitestop scripts as appropriate for your site’s local applications.

Configuration of TCP/IP

TCP/IP must be configured to allow the UNIX client node to find the PI home node by name. The client node should be able to ping the home node by name and to establish a Telnet session with the home node. The home node should also know the client node by name to support reverse name lookup used to support security.

Configuring the PI Server

PI on OpenVMS systems require the installation of a program on the server to respond to client requests. PI on Windows NT and UNIX systems automatically install a responder program called pinetmgr. See PI Server Support for Remote Access for a discussion of protocol stacks and server program installation on various platforms.

Setting the Default PI Home Node

The environment variable PIHOME, must be set for any user running PI API programs to enable the PI API to locate the default PI home node. During installation, described earlier, PIHOME was set to the base install directory. Under this directory is a subdirectory, $PIHOME/dat, which contains the file piclient.ini which specifies the default server and optionally the connection port. While running pi.install the default home node and port were set in this file. The piclient.ini file may be modified if it was set incorrectly during install or the default home node changes. In any case it should be reviewed during the installation process. A sample file is shown below:

  [PISERVER]
  PIHOMENODE=MYVMSSERVER
  [TCP/IP]
  PORT=545
  

If necessary, edit the file modifying the line PIHOMENODE= to reflect your default PI node. Typically, this is your PI home node or a PINet node. In the example, the node MYVMSSERVER is being used. The default port for all OpenVMS servers is 545. If you will be connecting to OpenVMS servers you may omit the TCP/IP and PORT lines from the file. If you will be connecting instead to a Windows NT or UNIX server, specify 5450 for the PORT. Note that this is used for default connection purposes. Using the API function piut_setservernode you can specify a server name followed by a colon and the port number to explicitly direct the connection.

The file piclient.ini may also contain a section and entries to support configuration of API node buffering. See API Node Buffering for a description of appropriate entries. If you do not intend to use node buffering you do not need any of these entries in this file. The default is to not enable buffering.

Starting and Stopping PI

When starting and stopping PI the environment variable, PIHOME, as well as the shared library path for those platforms using shared libraries, must be set as described in UNIX Installation Procedures. You may wish to add the commands to set these environment variables to the script executed on login (.login, .profile) for users executing PI applications on the UNIX node.

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

mqsrv Message log server.
mqmgr Message log manager.
ioshmsrv I/O rates shared memory server.
iorates I/O rates monitor program.

If buffering is enabled a fifth process, bufserv, is also started; see API Node Buffering.

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

To run the Bourne shell start and stop scripts from a different shell execute the commands preceded by the shell directive, sh:

# sh pistart

You can verify that these processes are running using the apiverify script. This script reads the file $PIHOME/bin/apiprocs by default (You may create other process list files and enter those filenames as arguments to the apiverify script.) and lists process information for each program mqsrv, mqmgr, ioshmsrv, iorates, bufserv, and other processes that may be added to the apiprocs file.

The apiverify script will print out a warning if a listed process is not found or multiple copies are running.

  NAME            PID     TIME            %CPU    %MEM
  WARNING: bufserv is NOT running
  mqmgr           8676    0:03            0.0     0.9
  mqsrv           8671    0:09            0.0     0.9
  ioshmsrv        8682    0:06            0.0     0.4
  iorates         13278   0:05            20.7    4.0
  iorates         8687    0:05            0.0     1.0
  WARNING: multiple instances of iorates are running
  fxbais          8695    304:45          2.2     2.7
  

On some systems, when the process that executed the pistart command exits, the launched processes also are killed. This can be prevented by prepending the launch command with nohup. For example:

# nohup sh pistart

Example Program

$PIHOME/src contains an example program, apisnap.c, and make file, apisnap.mak. This source demonstrates how to build a PI API application. It also is a good test of proper installation. The makefile demonstrates the proper flags for compiling and linking on the installed environment. This example can be built with the following commands:

# cd $PIHOME/src

# make -f apisnap.mak

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

For example:

# apisnap node2

will attempt to connect to node2. The program (and the piut_setservernode function used by the program) also supports the use of an IP address in place of a server name. You can append the desired port with a colon to the name or the address. For example:

# apisnap 204.89.194.36:5450

Purging Log Files

The error logging functions send data to the file $PIHOME/dat/pimesslogfile when the PI API is started using the pistart script. It is possible to run PI API programs without running pistart, in which case error messages are redirected to stdout. When left running, the PI API mqsrv and mqmgr programs will manage sending error messages to the pimesslogfile. Each night they rename the log file to pimesslogfile.mmmxx (where mmm is the three-character month abbreviation and xx is the day of the month) and start a new pimesslogfile.

Using the cron facility and the find command, you can remove old log files from your system automatically. If old log files are not periodically removed, log files will eventually fill the available disk space. OSIsoft recommends periodic removal of old log files to prevent potential disk space issues. The sections that follow describe some of the available tools for this purpose.

Finding and Removing the Files:

The following version of the find command will remove all pimesslogfile.xxxxx files from the directory /usr/piapi/v1.2.0/dat that have not been modified within the last seven days.

find /usr/piapi/v1.2.0/dat \( -name ‘pimesslogfile.*’ \) -mtime +7 -exec rm -f {} \;

In this command, the \ character is an escape character used before the parenthesis and the semi-colon. The file name to match is surrounded with apostrophes (typically on the same key as the quotation marks). The command should be entered on a single line. Substitute the correct directory name and desired number of "days without modification" for your situation. Spaces are significant. The -mtime argument is for last modified, a similar argument -atime can be used for last accessed. Using find on a file subsequently changes its last access time.

Adding a Cron Job

This command can be entered right into the crontab preceded by the designation for when the job should run, for example:

20 4 * * * find /usr/piapi/v1.2.0/dat \( -name ‘pimesslogfile.*’ \) -mtime +7 -exec rm -f {} \;

would run the job at 4:20 AM every day of the week. All text is entered on a single line in the crontab file.

The first five entries in crontab designate a time as follows:

minute (0-59)
hour (0-23)
day of the month (1- 31)
month of the year (1-12)
day of the week (0 - 6, 0 = Sunday)

Users with permission may set up their own cron jobs. The user who owns the directories and in particular the log files should be the one to create the cron entry. A user’s cron entries are stored by the system. To list them, execute

crontab -l

Modifying the cron table varies among systems. Under Solaris, to add to the user’s crontab, first set an environment variable indicating the editor to use:

For C Shell:

setenv EDITOR vi

For Bourne or Korn shell:

EDITOR=vi

export EDITOR

Then execute the command

crontab -e

An editor is then presented where you may modify the existing cron jobs for this user and add any new ones desired. When the editor is exited the cron table is updated. Some systems require you to have a file with all the cron commands the user needs. In this case you would execute

crontab -l > tempfile

Then edit tempfile to contain the additional commands for purging log files. Then add the cron entries with

crontab tempfile

For more information on setting up cron jobs, execute

man crontab

or see your system documentation.

Enabling Operational Intelligence