.help udcif May94 ftools.caltools 
.ih
NAME
UDCIF -- Creates a new entry in a Calibration Index File
.ih
USAGE
udcif infile cif

.ih
DESCRIPTION
UDCIF will search a FITS file for required calibration keywords (see the document cal_gen_92_011 for a complete description of these keywords).  The search is conducted one extension at a time.  When the CCLSxxxx keyword is found, all the required and optional calibration keywords are read.  If a required calibration keyword is not found, an error message is reported and the dataset is ignored.  In addition, if any of the calibration boundary values (CBDnxxxx keyword values) cannot be interpreted, an error message is reported and the dataset ignored.  

When a complete set of calibration keywords is found, the user is prompted for the quality of the dataset being entered.  The quality value is an integer which indicates the reliability of the dataset being indexed.  Currently, the Caldb differentiates between good and bad quality files only.  Good quality datasets are given a value of 0 and bad quality datasets are given a value of 5.

Certain INSTRUME keyword values imply that the dataset is valid for multiple instruments.  If such a value is found for the dataset being indexed, then the special value is translated into its alias values and a separate entry is made in the CIF for each.  For example, the special INSTRUME value "GIS" will cause UDCIF to create an entry for GIS2 and GIS3 in the CIF.  UDCIF accesses the file alias_config.fits to get a list of the special INSTRUME values and their translations.  This file is usually found in /caldb/software/tools on UNIX systems or CALDB:[SOFTWARE.TOOLS] on VMS systems.  A complete list of values can be found in the document cal_gen_93_013.

Before the  new entry is written  to the CIF, all  other CIF entries
are checked to see if  the new entry will duplicate another dataset.
If  a duplicate  is  found  and it  is  in fact  the  same file  and
extension, a  warning will be  printed and a  new entry will  not be
written.  Otherwise, if a duplicate good dataset is found, but it is
a different file, the user is  asked whether he or she wants the new
dataset to  supercede it.  If the  user answers yes  to this prompt,
then the quality value of the old  entry is set to 5 and the new one
written with a quality of 0.   If the user answers no to the "change
conflicting dataset"  prompt, the new  dataset will not be  added to
the CIF.  This ensures that only 1 entry in the CIF will have a good
quality setting for any given set of parameters.

This task assumes that the current directory is beneath the directory pointed at by the CALDB environment variable (logical).  Failure to set this variable properly will cause access problems when retrieving the dataset from the
Caldb.  See the Caldb User's Guide for more information.


.ih
PARAMETERS
.ls infile [string]
The name of the calibration file that is to be searched for calibration keywords.
.le
.ls cif [string]
The name of the Calibration Index File which will contain the new entries.
.le
.ls quality [integer]
The quality value for a dataset found in the calibration file.
.le
.ls editc [bool]
Whether or not any preexisting CIF entries should have their quality value modified.  (only used when a duplicate entry is found)
.le
.ls newentries [integer] (output)
After running udcif, this parameter holds the number of entries
written to the CIF.
.le
.ih
EXAMPLES
1.  Enter all datasets found in the file, cal_file.fits into the Calibration Index File, caldb.indx.

 ca> udcif cal_file.fits caldb.indx
.fi
.ih
BUGS
This task assumes that the Calibration Index File is named caldb.indx even though there is a parameter allowing the user to choose a different name for his or her CIF.

Currently, UDCIF only indexes the first dataset found in any extension.  (i.e the ...0001 dataset.)

.ih
SEE ALSO
QUZCIF
.endhelp

