UDCIF (May94)                ftools.caltools               UDCIF (May94)

NAME
    UDCIF -- Creates a new entry in a Calibration Index File
    
    
USAGE
    udcif infile cif
    
    
    
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.
    
    
    
    
PARAMETERS
    
    infile [string]
        The  name  of  the  calibration  file that is to be searched for
        calibration keywords.
    
    cif [string]
        The name of the Calibration Index File which  will  contain  the
        new entries.
    
    quality [integer]
        The quality value for a dataset found in the calibration file.
    
    editc [bool]
        Whether  or  not  any  preexisting CIF entries should have their
        quality value modified.  (only used when a  duplicate  entry  is
        found)
    
    newentries [integer] (output)
        After  running udcif, this parameter holds the number of entries
        written to the CIF.
    
    
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
    
    
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.)
    
    
    
SEE ALSO
    QUZCIF