.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 user will be given the option of
including the new dataset in the CIF.  This option is useful if the
new dataset differs from the older dataset in the values of the
calibration boundary (CBDn0001) keywords.

This task assumes that the current directory is under 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
.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.)

If UDCIF is stopped before completion, a temporary file (called
cif.tmp) may be left in the same directory as the caldb.indx file.
This file should be deleted before UDCIF is run again for this same
MISSION/INSTRUME combination.

.ih
CAVEATS
if the first calibration boundary keyword (CBD10001) in the extension
being indexed has the value "NONE", UDCIF assumes all other
calibration boundary keywords in that extension header have the value
"NONE" as well.

.ih
SEE ALSO
QUZCIF
.endhelp

