OGIP1 Calibration Memo CAL/SW/2006-001

Length Limits In Calibration Database Software and Files
Michael F. Corcoran
Code 662,
NASA/GSFC,
Greenbelt, MD 20771
Version: January 19, 2006





SUMMARY

Here we document limits on the length of filenames, header keywords and other metadata used in the HEASARC Calibration Database (CALDB).

LOG OF SIGNIFICANT CHANGES


Release Sections Changed Brief Notes
Date
2006 Jan 19 All Original Version
2006 Jan 23 § 3 added

Contents

1  Introduction
2  Length Limits on Calibration File Metadata
3  Case Sensitivity

1  Introduction

The only sin is limitation.
Emerson, "Circles," Essays, First Series (1841, repr. 1847)
The HEASARC Calibration Database (CALDB) uses file metadata in order to identify files in the calibration archive uniquely. Software uses this metadata to retrieve calibration files from the archive. Since the CALDB software is largely written in FORTRAN, and because calibration files use FITS formats for data storage, there are implicit limitations to these metadata. Exceeding these limits can provoke unwanted results by, for example, truncating values. These limits are documented here.

2  Length Limits on Calibration File Metadata

The limits on Calibration file metadata are given in table 1. Calibration file metadata are both stored in individual calibration file extensions as FITS header keywords and/or given in calibration index files as column names for each indexed FITS file extension. CALDB users and creators and managers of calibration databases using the HEASoft package should be aware of these limits.
In table 1, column 1 gives the name of the metadata column in the calibration index file, while column 2 gives the name of the corresponding keyword to be used in the FITS file extension header. Note that some of the columns in the calibration index file (like CAL_DIR, CAL_FILE, etc) are only populated when the FITS extension is indexed and do not correspond to extension header keywords.
The mandatory calibration file extension header keywords are defined in CAL/GEN/92-011, "Required and Recommended FITS keywords for Calibration Files", while calibration index files are discussed in CAL/GEN/92-008, "Calibration Index Files"
Table 1: Limits in CALDB Keywords and Calibration Index File Metadata
CALDB Index Column Data File KEYWORD Data Type Description CRCIF Limit
TELESCOP TELESCOP character Telescope or mission name 10
INSTRUME INSTRUME character Instrument name 10
FILTER FILTER character Filter Name 10
CAL_DEV character Calibration Device 20
CAL_DIR character Calibration File Directory 70
CAL_FILE character Name of Cal File 40
CAL_CLAS CCLS0001 character Cal File Class 3
CAL_DTYP CDTP0001 character Cal File Data Type
CAL_CNAM CCNM0001 character Calibration data codename 20
CAL_CBD CBD1000n character Calibration Boundary 70 (per boundary)
CAL_XNO Integer*2 Calibration extension number 32768
CAL_VSD CVSD0001 character validity start date 10
CAL_VST CVST0001 character validity start time 8
REF_TIME Double Precision reference time
CAL_QUAL Integer*2 data quality 0−5
CAL_DATE character date of ingest 10
CAL_DESC CDES000n character description 70

3  Case Sensitivity

The HEASARC CALDB is not case-sensitive. Metadata values can be entered either as lower or upper case in a calibration index file, but the calibration data retrieval software (the subroutine gtcalf) converts all such values into upper case. Similarly the calibration data retrieval software converts user input into upper case before comparing to the calibration index file metadata in order to determine the appropriate calibration file.

Footnotes:

1Office of Guest Investigator Programs

File translated from TEX by TTH, version 3.67.
On 23 Jan 2006, 10:42.