The Cassandra Project banner
by Darryl Bond <>

#  Copyright (c) 2000 NRG Gladstone Operating Services.               |
#  All Rights Reserved.                                               |
#                                                                     |
#                            |
#                                                                     |
#  This is free software; you can redistribute it and/or modify it    |
#  under the terms of the GNU General Public License as published by  |
#  the Free Software Foundation; either version 2 of the License, or  |
#  (at your option) any later version.                                |
#                                                                     |
#  This software is distributed in the hope that it will be useful,   |
#  but WITHOUT ANY WARRANTY; without even the implied warranty of     |
#  merchantability or fitness for a particular purpose. See the GNU   |
#  General Public License (    |
#  more details.                                                      |
#                                                                     |
#  To obtain the GNU General Public License, write to:                |
#                                                                     |
#      Free Software Foundation, Inc.                                 |
#      59 Temple Place - Suite 330                                    |
#      Boston, MA  02111-1307                                         |
#      USA                                                            |


The program gethist is a C program which retrieves historian data from the Foxboro Historian using standard Foxboro API calls and outputs the data in a variety of text formats. The data can retrieved from ARCHIVES and REDUCTION GROUPS. gethist is, in itself, not very useful as it takes Unix time as its time arguments (although it defaults to the last 8 hours). Unix time is the number of seconds from 1/1/1970. gethist is generally used as a back-end processing engine for other programs.

Note that Perl is required to be installed for these utilities to work. If you haven't installed Perl you should anyway. It beats shell scripts hands down. Go to for your copy of Perl.

A Perl wrapper program,, performs the time format changes and calls gethist. Refer to further in this file for information. is a Perl program which takes a file list in the format:

      comp:block.param  historian  #Comment

one per line. It then outputs a comma-separated variable (csv) list of the data contained in the file. The data can then be imported into MS Excel or any other program that handles csv. The output produces a pseudo scan rate so that there appears to be a sample at each nominated inteval. Refer to further in this file for information. is a Perl CGI script to allow access to Foxboro historian data via a web interface. gethist.html is the front end file for Refer to further in this file for information.


compressed source code and documentation (38 KB)

Building & Installing gethist


gcc (Not tested with Sun C compiler)
GNU make
Foxboro AW/AP51

Untar the archive:

      uncompress -c gethist.tar.Z | tar xvf -

make and compile:

      cd gethist

specify the historian and test run gethist:

      HISTORIAN=hist11; export HISTORIAN
      ./gethist CCC:BBB.PPP (a valid point in the historian set above)

gethist should return the last 8 hours of data stored for the point.

Copy gethist to your bin directory (/usr/local/bin ?)

Edit the first line of and to point to your Perl executable. Documentation

Function: Retrieve data from the Foxboro historian as a text output.

Where: The program must be run from a Foxboro AP/AW/WP. It is recommended to be located in /usr/fox/wp/bin

Based on: gethist


   gethist COMPOUND:BLOCK.PARAM start_unixtime
or gethist COMPOUND:BLOCK.PARAM start_unixtime finish_unixtime
or gethist COMPOUND:BLOCK.PARAM -sec (last sec seconds)

Description:: can retrieve data from the sample, archive, or reduction groups. The relevant source is set by the use of environment variables. The default source is 'sample'. The default format retrieved is YYYY/MM/DD HH:MM:SS Value Status.

The Following Environment Variables must be set before using gethist or


Additional environment variables are:

  1. To retrieve archive data:
    ARCHIVE=archive group name
  2. To retrieve reduction data:
    GROUP_NAME=group name
    COL_NAME=operation name

Remember to export the environment variables, eg.:


Usage: C:B.P [start time] [finish time]

Note: If no start/finish time is given then will return the last 8 hours. If a start time is supplied the the last sample is assumed. Time format is "YYYY/MM/DD HH:MM:SS" (must be quoted.)

Example usage:

Last 8 hours from Current Data:

$ HISTORIAN=xxxxxx; export HISTORIAN

Supplied start time to now from Current Data:

$ HISTORIAN=xxxxxx; export HISTORIAN
$ XXXXX:XXXXXXXX.OUT "1997/7/8 0:0:0"

Supplied start time to finish time from Current Data:

$ HISTORIAN=xxxxxx; export HISTORIAN
$ XXXXX:XXXXXXXX.OUT "1997/7/8 0:0:0" "1997/7/8 10:0:0"

Output data can be redirected to a file for import into Excel etc


Additional formats provided for compatibility with sample_gmt use the SAMPLE_GMT environment variable.

SAMPLE_GMT=0 (default)
YYYY/MM/DD HH:MM:SS Value Status

unix_time YYYY/MM/DD HH:MM:SS Value Status

unix_time Value

Note unix_time is the number of seconds from 1/1/1970. Documentation creates a comma-separated variable output based on a file list of historian points and a sample period. The start time and finish time of the data must be supplied.


./ period(in secs) start finish -f file 
./ 60 "1996/01/17 10:30:00" "1996/01/18 00:00:00" -f file
where file is a text file containing C:B.P HISTORIAN # COMMENT
one entry per line, white space is ignored, comment is optional,
C:B.P and historian is case sensitive
eg: X_XXX:XXX_XXXX.OUT xxxxxx # Unit 3 Load


  1. Date/Time format is "YYYY/MM/DD HH:MM:SS".
  2. Quotes are required around each of the start and finish times.
  3. The environment variable ARCHIVE must be setup prior to running this program if the data source is either of the archive or playback subdirectories. (eg.: ARCHIVE=sam3a1112k; export ARCHIVE)

The output is stdout so the output should be redirected to a file:

./ 60 "1996/01/17 10:30:00" "1996/01/18 00:00:00" \
     -f file > outputfile.csv

gethist.html and Documentation

gethist.html is a HTML file suitable for installation on Apache installed on a Foxboro Sun box. It calls the CGI program to return the data from the historian. One data point at a time can be retieved.


Apache web server (
Perl (
Perl CGI module. Refer to the CPAN archive (Comprehensive Perl Archive Network) for the CGI module. (
Foxboro WP/AW/AP

To get it to work:

  1. Install Apache on the Foxboro box.
  2. Edit the Apache config files and start the http server
  3. Install Perl on the Foxboro box
  4. Install the Perl CGI module
  5. Copy to the Apache cgi-bin directory
  6. Edit the first line of to point to the Perl executable
  7. Copy gethist.html to the Apache htdocs (html) directory.
  8. Edit the gethist.html file to set the historian list to the correct historian names (case sensitive)
  9. Point your browser at gethist.html and voilą.


Darryl Bond <>
Stephen Thefs <>
Specialist Computer Support
NRG Gladstone Operating Services

Copyright ©2000 The Cassandra Project
web posted: 16 March 2000
last updated: 19 March 2000
Contact the webmaster for comments and/or questions.