POD documentation for "perl/reader.plx"

Outline

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
ARGUMENTS
SCRIPT LAYOUT
SEE ALSO
KNOWN BUGS
AUTHOR
COPYRIGHT AND LICENSE
Source Code

NAME

reader.plx - Executes commands and logs the results in .cdf format

SYNOPSIS

reader.plx [--interval "seconds"] [--write "minutes"] [--filename "string"] [--directory "string"] [-v|-vb|--verbose] [-gmt|-GMT] [--make "file"] [--read "file"] [arg1 arg2 arg3...]
reader.plx -m filename.txt Makes a helpful file.
reader.plx -r filename.txt Reads arguments in from a file.
reader.plx -f "_run01" -d ~/data/ -r filename.txt Reads arguments in from a file, and outputs to ~/data/YYYYMMDD_run01.cdf (where YYYY is the year, MM is the month, and DD is the date from the system), as opposed to the default YYYYMMDDdevice.cdf in the current working working directory
reader.plx -i 30 -w 60 -r filename.txt Changes the sleep between getting data from 1 second to 30 seconds and the wait between writing out from 1 minute to 60.
reader.plx "thermocouple.plx" Temperature "^{o}F" "Trial 1" "Omega DPi8" 1 Runs the command "thermocouple.plx", and outputs the data to a .cdf variable "Temperature" with units of ^{o}F, x-axis label of "Omega DPi8" priority 1 and info "Trial 1". For more help, use the -v option, or look at the perldoc. Program uses Getopt::Long, so short versions of options are accepted. Supports standerd meta-options --help, --usage, --man, --version as well.

DESCRIPTION

This program is given a series of commands and information and it runs the commands and logs the results in .cdf format. It runs through the list of commands every second (-interval option controls this). It then writes the device to a file every minute (-write option controls this). By default it writes to a file like 20060713device.cdf. The year, month, and dayfields are set by the system clock, however the filename field can be changed by the -filename option. Close the program by sending an interrupt signal to it. This will cause the program to save the active cdf file then exit. Note: when running correctly, nothing will be printed to the screen.

OPTIONS

--interval "seconds" = the length of time, to 10**(-6) seconds that the program sleeps before running through it's command list again.
--write "minutes" the aproximate length of time between writing out data to .cdf format which saves the current data.
--filename "string" a string that goes between the date code and the .cdf part of the .cdf file. Use this to better identify your files.
--directory "string" this is a string that is appened to the begining of the filename so you can place it in any desired directory (so you aren't limited to the current working directory)
-v,-vb,--verbose more information is printed to screen. Such as the \OPTIONS and \ARGUMENTS when used with help. Can be handed an interger, else increments the amount of text supplied.
--GMT,--gmt use gmt time rather than local time. What time you are using is noted in the .cdf file.
--read "file" reads arguments from file specifed insted of from command line. See \ARGUMENTS or -make for more info.
--make "file" makes a file to read arguments from. This option is never required. Using this to make file is recomended, as it provides a handy refrence as to expected format.
--help, --usage, --man, --version --version is not supported in windows. Help uses --verbose to determine amount to print to screen.
DEFAULTS: --interval = 1 (second) --write = 1 (minute) --filename = "device" --directory= "" (current working directory)

ARGUMENTS

Arguments must be given to the program in the order "command" "device" "unit" "info" "label" "priority". Single arguments can be skipped by typing "skip" in, resulting in the defaults (works, but isn't pretty). You can also skip to the next command by typing "next" (as ugly as skip!).

command system command to be executed. This is supposed to be a program that would normally print to screen a single floating point number from some device.
device the name for the variable in the .cdf file. This has to be a unique name becuase of the way .cdf files work. The defaults are 'device[0-9]* '.
unit the unit of data (aka. K or ^{o}F for temperature). Defaults to 'unit'.
info anything goes here. Does not appear if default is used.
label plot axis label such as "O EM Signal". Defaults to "Unknown"
priority is independence of variable. Must be either 0, 1, or 2 else program dies. 0 means independent variable (usually reserved for time), 1 means dependent variable, and 2 means other. If you use 0 the program will warn you, and change time to 2. If you have more than one 0 variable you will be warned. Defaults to 2.

SCRIPT LAYOUT

This program has long main loop where the program flows somewhat like a waterfall (just down the page, with some spinning at the bottom), and seven subroutines.

Main The program first reads the arguments given to it. First it determines if it should print a file for the -m option, then it checks the -r option. It then it uses the subroutine
fill_arrays() to put all information in the proper spot. It then updates the signal hash and enters an infinite loop. Inside the infinite loop it first determines what the current time is, and what file name it ought to be reading/writing to. It then invokes the subroutine to read that file. Once it has opened a file to read to, it enters a second loop. In this inner loop, the program establishes the time (which it writes the current time in CDFepoch), calls the various system commands it was given and puts all that information in a CDF variable. It it then sleeps for the designated interval. The program exits this inner loop after a predetermined number of loops, the program executes the subroutine to close the .cdf file.
Read File Subroutine This subroutine
generate_read_file() opens up a file (handed to it) and writes a script explaining the format for files accessed by the -r option.
Fill Arrays Subroutine This subroutine
fill_arrays() takes two refrences (a refrence to an array filled with refrences, and a refrence to an array) and steps through them both, determining when to skip arguments (calls
skip_argument() ) or to copy information.
Skip Argument Subroutine This subroutine is called by
fill_array() and contains all of the default information used when the program is handed a "skip" or "next" argument.
Open .CDF Subroutine The program uses the
CDF::CDFopen() function with the filename that it is handed to try to open up any existing file with that filename (see Known Bugs). If the function returns an error code (such as the file not existing due to the filename changing becuase of a change in time), the subroutine calls the function to make a new .cdf file.
New .CDF Subroutine This subroutine does all of the work involved in opening a new .cdf file. It first opens the file, creates the time and temperature vari-ables, creates the global metavariables (when the .cdf was first opened, and when it will be last written too), and then creates the metavariables for the variables. It adds some data for the metavariables and then exits.
Close .CDF Subroutine This subroutine closes out the CDF variables, gets the current time, adds that to a global metavariable on the .cdf, and then invokes the
CDF::CDFclose() function.
Interrupt Signals Since the hash which deals with signals is updated to use this, whenever an interrupt signal is used, this subroutine is used. This subroutine invokes the Close .CDF Subroutine and then forces the program to
exit(0), aka. exit with success.

KNOWN BUGS

If you give it the wrong arguments, there is insufficient error checking. If there is a pre-existing file with the same name as the one assigned by this program there is no error checking to ensure that the files open up the proper variables.

AUTHOR

MegaSIMS group, UCLA, <megasims@ess.ucla.edu>. Written by Miles McCammon, <miles86@ucla.edu>.

COPYRIGHT AND LICENSE

reader.plx - reads any number of devices and saves data in .cdf Copyright © 2006 MegaSIMS, University of California Regents This program 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 version 2. This program 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 for more details. To receive a copy of the GNU General Public License, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Source Code

Source code for this version (10/24/08, 11:38) can be downloaded here.

POD documentation for perl/reader.plx