.help quzcif July1994 ftools.caltools 
.ih
NAME
QUZCIF -- Returns the location of calibration files
.ih
USAGE
   quzcif mission instrument detector filter codename date time expr
.ih
DESCRIPTION
This task is an interface to the Calibration Database access software.
It writes to the standard output all datasets in the Database which meet 
the selection criteria as specified by the input parameters.

Each dataset is printed in two fields, the filename field and the extension
number field.  The filename field contains the complete directory path to the
file containing the calibration data, and the extension number field contains
an integer indicating the FITS extension where the data resides.  (All 
calibration files in the Calibration Database are in FITS format.)  Each 
field is separated by spaces.  

Datasets which are stored in an off-line media (e.g. magnetic tape)
will be displayed in the same way except that the word 'OFFLINE' and
the off-line media will appear before the filename and extension
number.

Datasets which are located on the HEASARC server can be accessed if the
user's CALDB environment variable is set to
ftp://heasarc.gsfc.nasa.gov/FTP/caldb and optionally downloaded to the user's
current working directory.

If no datasets are found, then the message "No datasets found matching 
selection criteria" is displayed.

The detector, filter, and expr parameters may be removed from the selection
process by entering a string value of "-" when prompted.

The value "now" can be entered for the date and time parameters.  This
value will cause quzcif to use the current system date and time for the
date and time parameters.

The expr parameter provides a boolean selection expression for Calibration 
Boundary parameters.  A Calibration Boundary parameter is similar to the 
other selection parameters mentioned above, but may not necessarily be 
present for every dataset.  Thus, the expr expression provides a flexible 
way of specifying a varying number of selection criteria.  Currently, the 
boolean expression syntax only contains the arithmetic operator ".eq." and 
the logical operator ".and.".  A typical selection expression might look like:

.nf
   theta.eq.10.and.energy.eq.5
.fi

If no expr selection is required, a "-" character should be input at the 
prompt.

Before using this task, the 'CALDB' and 'CALDBCONFIG' environment variables (logicals) must be set.  See the Caldb User's Guide for details:
https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/install.html

.ih
PARAMETERS
.ls mission [string]
The name of the mission for which selected datasets should be valid.
.le
.ls instrument [string]
The name of the instrument for which the selected datasets should be valid.
.le
.ls detector [string]
The name of the detector for which the selected datasets should be valid.
If a "-" character is input, this parameter will not be used in the
selection process.
.le
.ls filter [string]
The name of the filter for which the selected datasets should be valid.
If a "-" character is input, this parameter will not be used in the 
selection process. 
.le
.ls codename [string]
The OGIP codename for the requested data.  The value input for this 
parameter corresponds to the CCNM0001, CCNM0002, ... keyword values found in
all Caldb calibration files.  Also, the NASA OGIP Memo CAL/GEN/92-011 
contains a list of valid codenames and their meanings.  This memo can be
obtained from anonymous ftp to legacy.gsfc.nasa.gov:/caldb/docs/memos.
.le
.ls date  [string]
The date for which the selected datasets should be valid.  This value
should be entered in yyyy-mm-dd format (although dd/mm/yy format will
also work, with 19yy assumed).  LEADING ZEROS *ARE* NOW REQUIRED.  If
the value "now" is entered, the current system date is used in the
selection process.
.le
.ls time  [string]
The time for which the selected datasets should be valid.  This value
should be entered in hh:mm:ss format.  Single digits may be used, but
at least a 0 in each value is required.  (However, this may change in
the future, so using both digits is recommended.)  If the value "now"
is entered, the current system time is used in the selection process.
.le
.ls expr  [string]
A boolean selection expression for Calibration Boundary parameters.  
If no expr selection is required, a "-" character should be input at the 
prompt.
.le
.ls (maxret=50) [integer]
An integer indicating the maximum number of datasets to print to the screen.
Currently this parameter cannot be greater than 50.
.le
.ls (quality=0) [integer]
An integer giving the desired value of the CAL_QUAL flag of the caldb files. A
value of quality = 0 will return the standard "good" calibration files for the
specified search. A list of other quality values that have been used
historically is available in Section 3 of the Calibration Index Files document
(Calibration Memo CAL/GEN/92-008) available at
https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_doc.html
.le
.ls (retrieve) [boolean]
If set to "yes", and the user is accessing the caldb remotely (as opposed to
accessing the caldb from a locally mounted disk) then, if any calibration
data files are found, they are downloaded to the user's current working
directory.  If set to "no", files are not downloaded. This parameter has no
effect if the user is accessing a local version of the caldb.
.le
.ls (nfound) [integer]
An integer, returned after the successful completion of this task, which 
indicates the number of datasets found matching the selection criteria.
If this parameter is greater than maxret, the warning message, 
"Warning: More files were found than are shown here" will be displayed.
.le
.ih
EXAMPLES
1.  Find the location of the ASCALIN dataset for the SIS0 instrument of
the ASCA mission valid for Jun 20, 1994.
.nf
   % quzcif asca sis0 - - ascalin 1994-06-20 12:00:00 -
.fi

2.  Find the BKGRND dataset for the GIS2 instrument of the ASCA mission
valid for today and for a cut-off rigidity value of 7.
.nf
   % quzcif asca gis2 - - bkgrnd now now cor.eq.7
.fi

3.  Return the BKGRND dataset for the GIS2 instrument of the ASCA mission
valid for today and for a cut-off rigidity value of 7 from the HEASARC Caldb:
.nf
   % setenv CALDB http://heasarc.gsfc.nasa.gov/FTP/caldb
   % quzcif asca gis2 - - bkgrnd now now cor.eq.7 retrieve+
.fi

4.  Return the files which have CAL_QUAL value of 5 for the Swift XRT MATRIX files
.nf
% quzcif/quzcif swift xrt - - matrix now now - chatter = 1 quality = 5
gtcalf 1.2.1  : Searching CALDB for quality values =  5
ftp://heasarc.gsfc.nasa.gov/caldb/data/swift/xrt/cpf/rmf/swxwt0s0_20070901v011.rmf   1
ftp://heasarc.gsfc.nasa.gov/caldb/data/swift/xrt/cpf/rmf/swxwt0s6_20070901v011.rmf   1
ftp://heasarc.gsfc.nasa.gov/caldb/data/swift/xrt/cpf/rmf/swxwt0to2s0_20070901v011.rmf   1
ftp://heasarc.gsfc.nasa.gov/caldb/data/swift/xrt/cpf/rmf/swxwt0to2s6_20070901v011.rmf   1
ftp://heasarc.gsfc.nasa.gov/caldb/data/swift/xrt/cpf/rmf/swxpc0s0_20070901v011.rmf   1
ftp://heasarc.gsfc.nasa.gov/caldb/data/swift/xrt/cpf/rmf/swxpc0s6_20070901v011.rmf   1
ftp://heasarc.gsfc.nasa.gov/caldb/data/swift/xrt/cpf/rmf/swxpc0to12s0_20070901v011.rmf   1
ftp://heasarc.gsfc.nasa.gov/caldb/data/swift/xrt/cpf/rmf/swxpc0to12s6_20070901v011.rmf   1
ftp://heasarc.gsfc.nasa.gov/caldb/data/swift/xrt/cpf/rmf/swxwt0s6_20070901v012.rmf   1
ftp://heasarc.gsfc.nasa.gov/caldb/data/swift/xrt/cpf/rmf/swxwt0to2s6_20070901v012.rmf   1
.fi
.ih
BUGS
The current expr parser cannot precheck the expression well.  Subexpressions
such as "cor.eq.7.and.and.energy.eq.5" will be incorrectly interpreted as
"cor=7" and "and.energy=5".  A lex &  yacc parser is planned for this task
which will work much better.
.ih
SEE ALSO
udcif, crcif, caldb
.endhelp
