Source Files

Release Notes

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 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.
    
    
    
    
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.)
    
    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.
    
    
    
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.
    
    
    
SEE ALSO
    QUZCIF