gridFiles.README  - help for gridFiles script
	updated 7-11-02

Introduction

   gridFiles is a perl script which will combine data from archived telemetry
   channels in a single, time stamped table from the single channel
   output produced by the extractor tool.  It is specifically designed to
   work with sporadic and irregular telemetry such as the status tags.
   It should be able to handle any files that the extractor produces.

Input	

   The script runs the extractor by default or works
   with previously produced extractor output files (-noExtract
   argument).  The start time to the extractor can be specified,
   otherwise the start of the archive file is  used.  
   The extractor is always run at the full rate, even if gridFiles
   is set with a much larger step size, so the extraction step
   may be slow for long time length requests.
   If the extractor can not find a channel listed in the mapnames.gridFiles
   file, it will not write out a file and gridFiles will stop
   and give the name of the telemetry item.  You should then edit
   the mapnames.gridFiles file accordingly.

   The increment between rows in the output table is either set
   with the -step argument or the -gridChannel argument.	

Output

   The output table will start once every requested channel is
   present.  Sample and hold is used to generate the values and if data
   from a telemetry channel ends before the specified length of the
   output file is reached the last value will be repeated as necessary.

   The output file is called gridFiles.txt and contains space-separated
   columns or for with -csv argument the output is called gridFiles.csv and
   the columns are comma seprated.  The first column is time in seconds 
   (or ticks/hours if the -ticks/-hours argument is used), and the following 
   columns are the extracted data, in the order given by the 
   names in the file specifying which telemetry channels to use.

   A header line (starting with #) is produced if the -header argument
   is used.  Note that status telemetry channels such as servomode and
   trackmode are represented in 2 columns, the first is the integer
   value and the second is the string.

Operation

   If using the extractor, the telemetry channels must be listed in a
   file called mapnames.gridFiles.  It is generally easiest to get
   this file by copying the .mapnames file for the archive file you
   are looking at.  The archive file must either be in the working
   directory, specified in the environment variable ARCHIVEPATH, or
   specified on the command line using the -archive argument.  If
   using previously generated archive files (-noExtract) the files must
   be in the working directory and the telemetry channels listed in
   either mapnames.gridFiles or a file given by the -inputList argument.

Example:

   gridFiles -length 60 -step 0.001 -archive /sdata801/archive/currentdata


Installation:

   Set the extractorDir variable to contain the correct location of
   the extractor executable.  gridFiles can be run in a separate
   directory from the archive file.  

Command line arguments:

-help
  Print short help message.	

-step 
  The output step size in seconds (default = 0.01)

-length 
  The length of the output file in seconds (default = 300).
  Using 0 will process the entire file.

-noExtract 
  Do not call the extractor separately, instead get list of 
  files to be combined from -inputList 

-inputList 
  File containing names of telemetry channels to be combined 
  (default = mapnames.gridFiles) 

-startTime 
  Start time for extractor.  Must be in correct format 
  (ex. "2/28/2001 20:23") surrounded by double quotes.

-ticks
  Output file time in ticks.

-hours
  Output file time in hours.

-archive
  Pathname of archive file to use.  Overrides ARCHIVEPATH environment 
  variable.

-csv 
  Output file columns are comma separated and the file is called 
  gridFiles.csv

-gridChannel
  Specify channel to use for setting time grid of output file.
  Overrides -step argument.  The name used must be the same as
  the short name for the channel (which is after the comma in
  the mapnames.gridFiles file.

-quiet 
  Message from gridFiles and extractor are supressed.

-header
  Print header line at start of output file.
	
-inputTicks
  Use for extractor files using ticks (instead of seconds).

-database
  Formats output with double quotes for Level 0 database insertion.
  Output file is always comma separated (csv format).