Search:

[Advanced Search]




NAME

UDCIF -- Creates a new entry in a Calibration Index File

VERSION

Version 4.0 (2021-03-26)

Changes in this version:

  • included specification of CALDBVER parameter to uniquely specify the release version (should be of the form 'YYYYMMDD' and the same as used in caldb.indxYYYYMMDD)
  • removes temporary cif.tmp file if it exists before updating
  • if caldbver='NONE' then write a blank value to the CALDBVER keyword


USAGE

% udcif infile cif caldbver='YYMMDD'


DESCRIPTION

UDCIF should be used to add a new calibration file to a caldb.indx file (the "CIF"). UDCIF will search a FITS file for required calibration keywords (see the document cal_gen_92_011 for a complete list of these keywords). The search is conducted one extension at a time. When the CCLS0001 keyword is found (specifying the CALDB "class" of the data in the calibration file extension), the required and optional calibration keywords are read. If a required calibration keyword is not found, or other errors occur, an error message is reported and the data in the file extension is ignored.

The quality value for the new calibration data being added to the caldb.indx is an integer which indicates the validity of the dataset being indexed. New datasets being added tothe CALDB ususally have quality=0. Datasets whicha are no longer valid have quality=0.

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 (whose location should be specified by the $CALDBALIAS to get a list of the special INSTRUME values and their translations.

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. One entry in the CIF is a duplicate of another if all calibration parameters (calibration code, instrument, telescope, filter, detector, and calibration boundaries) are the same. If a duplicate is found the user has the choice to set the quality for the previous entry in the CIF to a value of 5, which means the new entry will be accessed by the CALDB access software in instead of the previous entry. In this way new calibration datasets can replace older, outdated ones in the CIF. Users also have the option of keeping both datasets with a quality value of 0, which is useful is rare circumstances. If the duplicate entry has the same file name and extension number as the file being added, the user is notified and the update is stopped.

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.

caldbver [string]
The release version of the CALDB which includes the updated files. This is a string which is usuall given as the year, month, and day of the release, in 'YYYYMMDD' format

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. To update swift/mis CALDB, version 20200401, to include the new clock correction file swclockcor20041120v200.fits, and update the version to 20210326, a user could run the following c-shell commands: 

setenv CALDBVER "20210326"
setenv NEWCIF $CALDB/data/swift/mis/index/caldb.indx$CALDBVER
 # Copy current CIF to the new release version
cp $CALDB/data/swift/mis/index/caldb.indx20200401 $NEWCIF
cd $CALDB/data/swift/mis/bcf/clock
udcif swclockcor20041120v137.fits $NEWCIF 0 editc=yes caldbver=$CALDBVER chatter=0


Caveats

  • Users are STRONGLY encouraged to specify the caldbver parameter (in YYYYMMDD format) for each new CALDB release. If the caldbverparameter is not specified (the default), a blank CALDBVER keyword will be written to the header of the first extension in the CIF. Users are encouraged to specify a value of the caldbver parameter when using udcif, or to update the blank CALDBVER keyword value using a tool like fthedit after udcif is run.
  • Currently, UDCIF only indexes the first dataset found in any extension. (i.e the ...0001 dataset.)
  • 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

CATEGORY

ftools.caltools (updated March 26, 2021)