gethist
by Darryl Bond <dbond@nrggos.com.au>
#---------------------------------------------------------------------+ # Copyright (c) 2000 NRG Gladstone Operating Services. | # All Rights Reserved. | # | # http://thecassandraproject.org/ | # | # 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 (http://www.fsf.org/copyleft/gpl.htm)for | # 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 | #---------------------------------------------------------------------+
Overview:
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 sunfreeware.com for your copy of Perl.
A Perl wrapper program, gethist.pl, performs the time format changes and calls gethist. Refer to further in this file for information.
cbp2csv.pl 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.
texthist.pl is a Perl CGI script to allow access to Foxboro historian data via a web interface. gethist.html is the front end file for texthist.pl. Refer to further in this file for information.
Download
compressed source code and documentation (38 KB)
Building & Installing gethist
Requirements:
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
make
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 cbp2csv.pl and gethist.pl to point to your Perl executable.
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
Usage:
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:: gethist.pl 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 gethist.pl:
HISTORIAN=histname
Additional environment variables are:
- To retrieve archive data:
ARCHIVE=archive group name
- To retrieve reduction data:
GROUP_NAME=group name
COL_NAME=operation name
Remember to export the environment variables, eg.:
export HISTORIAN ARCHIVE
Usage: gethist.pl C:B.P [start time] [finish time]
Note: If no start/finish time is given then gethist.pl 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
$ gethist.pl XXXXX:XXXXXXXX.OUT
Supplied start time to now from Current Data:
$ HISTORIAN=xxxxxx; export HISTORIAN
$ gethist.pl XXXXX:XXXXXXXX.OUT "1997/7/8 0:0:0"
Supplied start time to finish time from Current Data:
$ HISTORIAN=xxxxxx; export HISTORIAN
$ gethist.pl 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
$ gethist.pl XXXXX:XXXXXXXX.OUT >filename
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 SAMPLE_GMT=1 unix_time YYYY/MM/DD HH:MM:SS Value Status SAMPLE_GMT=2 unix_time Value
Note unix_time is the number of seconds from 1/1/1970.
bp2csv.pl 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.
Usage:
./cbp2csv.pl period(in secs) start finish -f file ./cbp2csv.pl 60 "1996/01/17 10:30:00" "1996/01/18 00:00:00" -f filewhere 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
Notes:
- Date/Time format is "YYYY/MM/DD HH:MM:SS".
- Quotes are required around each of the start and finish times.
- 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:
./cbp2csv.pl 60 "1996/01/17 10:30:00" "1996/01/18 00:00:00" \
-f file > outputfile.csvgethist.html and texthist.pl Documentation
gethist.html is a HTML file suitable for installation on Apache installed on a Foxboro Sun box. It calls the CGI program texthist.pl to return the data from the historian. One data point at a time can be retieved.
Requirements:
Apache web server (http://sunfreeware.com)
Perl (http://sunfreeware.com)
Perl CGI module. Refer to the CPAN archive (Comprehensive Perl Archive Network) for the CGI module. (http://www.cpan.org/)
Foxboro WP/AW/AP
To get it to work:
- Install Apache on the Foxboro box.
- Edit the Apache config files and start the http server
- Install Perl on the Foxboro box
- Install the Perl CGI module
- Copy texthist.pl to the Apache cgi-bin directory
- Edit the first line of texthist.pl to point to the Perl executable
- Copy gethist.html to the Apache htdocs (html) directory.
- Edit the gethist.html file to set the historian list to the correct historian names (case sensitive)
- Point your browser at gethist.html and voilą.
Authors
Darryl Bond <dbond@nrggos.com.au>
Stephen Thefs <sthefs@nrggos.com.au>
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.