NAME
     dataseeker.pl - DataSeeker command line tool

SYNOPSIS
     dataseeker.pl [ -nPbh ] [ -i file input ] < -o output file >
          [ -s search criteria ] [ -c CCDM lookup file ] 
          [ -p PCAD lookup file ] [ -d DB server ] [ -f DB loginFile ]
          [ -r avg DB file ] [ -g config DB file ] [ -R repository ]

DESCRIPTION
     The dataseeker.pl perl script queries the MTA average databases using
     user-supplied search criteria to formulate a query.  The output
     is returned as a FITS file.

OPTIONS
     The following options are supported:

     -n          Don't prompt for DB userid and password.  Just exit if
                 they aren't supplied by the -u and -w options.

     -P          Print the output filename to standard output when done.
                 Could be useful in automated processes using dataseeker.pl.

     -b          Don't clobber.

     -h          Print help then exit.

     -i          Input file containing dataseeker search criteria.

     -o          Output FITS filename.

     -s          Extra search criteria.

     -c          CCDM lookup file.  Used for DataSeeker primary search.

     -p          PCAD lookup file.

     -d          Database server.

     -f          Database login file.  Username on one line,
                 password on second line.  Make sure ONLY
                 user has read/write access on file!

     -r          Average DB lookup file.

     -g          Config database lookup file.

     -R          RDB repository.

PARAMETER INTERFACE
     DataSeeker also takes advantage of the IRAF-style parameter interface.
     Every argument except for DB password can also be set using dataseeker's
     parameter file.  Values specified as arguments override values set
     in the parameter file.  Values specified as arguments do NOT set parameter
     values.  

     To get parameter values use 
     "pget dataseeker <param>", where <param> is the name of a parameter. 
     To set parameter values, 
     "pset dataseeker <param>=<value>", where <param> is a parameter name and
     <value> is the parameter value.

     The allowed parameters are listed below along with their equivalent 
     arguments.

     Param        Arg  Description

     infile       -i   Specify input file containing dataseeker search 
                       criteria.

     outfile      -o   Specify output FITS filename.

     search_crit  -s   Extra search criteria.

     ccdmfile     -c   CCDM lookup file.  Used for DataSeeker primary search.

     pcadfile     -p   PCAD lookup file.

     server       -d   Database server.

     loginFile    -f   Database login file.  Username on one line,
                       password on second line.  Make sure only 
                       user has read/write access on file!

     prompt       -n   yes = prompt for userid and passwd if unspecified.
                       no  = don't prompt, just exit.

     avgrdb       -r   Average database lookup file.

     configrdb    -g   Config database lookup file.

     repository   -R   RDB repository.

     print        -P   yes = Print the output filename to standard output when
                             done.
                       no  = Don't print output filename.

     clobber      -b   yes = Clobber output file if it already exists.
                       no  = Don't clobber.

SEARCH CRITERIA
     Search criteria can be specified using either a file or using the -a
     argument on the command line.

     The file format is:  <MSID>=<VALUE> (no whitespace buffering the '=' 
     sign).  With each msid/value pair being seperated by a newline.  The 
     argument format is <MSID>=<VALUE> with each msid/value pair being 
     seperated by a whitespace.  If <VALUE> is a string value, be sure to
     surround it by single quotes (').  ie. CCSDSTMF='FMT6'.

     Time search range is set using a Time Start/Time Stop pair.  The
     beginning of the range is 'timestart' the end is 'timestop'.  Both
     may be specified in any of the following formats:
     SECS    Elapsed seconds since 1998-01-01T00:00:00
     DATE    YYYY:DDD:hh:mm:ss.ss...
     CALDATE YYYYMonDD at hh:mm:ss.ss...
     FITS    FITS date/time format YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.ss...

     DataSeeker automatically determines which time format is being.
     eg. timestart=2001:301:10:30:29 is the same as 
     timestart=2001Oct28 at 10:30:29 is the same as
     timestart=120652229.

     There are three levels of search criteria called primary, secondary,
     and tertiary.  Primary search criteria represents observational status
     of the observatory.  Seconday search criteria represents physical aspects
     of the observatory.  And Tertiary search criteria defines the columns
     in the final output FITS file.

     Primary Search Criteria is made up of the following:

     COBSRQID    The Observation ID.
     AOATTRAS>   Right ascension.  The lower value of a range.
                 Specify either as decimal degrees, hh:mm:ss, 
                 or hh mm ss. ie. 180 is the same as 12:00:00 
                 is the same as 12 00 00.
     AOATTRAS<   Right ascension.  The upper value of a range. 
                 Rules for specification are the same as rafrom.
     AOATTDEC>   Declination.  The lower value of a range.
                 Rules for specification are the same as rafrom.
     AOATTDEC<   Declination.  The upper value of a range. 
                 Rules for specification are the same as rafrom.
     AOATTROL>   Roll.  The lower value of a range. Specify in 
                 degrees.
     AOATTROL<   Roll.  The upper value of a range.  Specify in 
                 degrees.
     SCIINS      Science Instrument.  Possible values are 'ACIS-I', 'ACIS-S', 
                 'HRC-I', and 'HRC-S'.
     GRATING     Grating.  Possible values are 'HETG', 'LETG', and 'NONE'.
     AOPCADMD    PCAD mode.  Possible values are 'STBY', 'NULL', 'RMAN',
                 'PWRF', 'NSUN', 'NPNT', and 'NMAN'.
     CCSDSTMF    Format.  Possible values are 'FMT1', 'FMT2', 'FMT3',
                 'FMT4', 'FMT5', and 'FMT6'.
     CORADMEN    Radiation monitor.  Possible values are 'ENAB' and 'DISA'.

     Format for primary criteria is <msid>=<value>.
     
     Secondary search criteria are based on values in the MTA configuration
     databases.  See configdb.rdb for a description of all mnemonics and 
     corresponding values.  The format for secondary criteria is 
     <database>..<table>.<msid>=<value> or just <msid>=<value> and dataseeker
     will expand the full database path..
     ie.  mtaconfig..mta_ccdm_config._ctufmtsl='FMT3'
          is the same as _ctufmtsl='FMT3'
     
     Tertiary criteria maps msids in the MTA average databases to columns in
     the output FITS file.  The format for tertiary criteria is:
     columns=<value>, where value is a comma seperated list of mnemonics
     and/or tables from the MTA average databases.  Mnemonics are specified
     as <database>..<table>.<msid>, and tables as <database>..<table>, or
     just specify <msid> for mnemonics and <table> for tables and dataseeker
     will expand the database pathname.
     
EXAMPLES
    This is an example DataSeeker criteria specification file:

columns=mtaacis..aciseleca_avg,mtapcad..pcadftsgrad_avg._ohrthr27_avg,_ohrthr42_avg
mtaconfig..mta_acis_config._1daboaon='ON'
mtaconfig..mta_ccdm_config._ctufmtsl='FMT2'
COBSRQID=1635
timestart=70000000
timestop=15/5/2001

    Example DataSeeker invocation:


dataseeker.pl -i query.txt -P -o myout.fits -s"COBSRQID=1635 mtaconfig..mta_acis_config._1daboaon='ON' ter-columns=mtaacis..aciseleca_avg,mtapcad..pcadftsgrad_avg._ohrthr27_avg" -R/data/repository

    This invocation of dataseeker will query the average databases
    using the criteria in query.txt and the extra search criteria specified 
    with the -s option.  /data/repository will be used as the 
    RDB repository.  The output filename is myout.fits, and the
    output filename will be printed to standard out upon dataseeker's
    completion.