FITS Table Writing Under Dervish

FITS ASCII and Binary Table can be written from Dervish. The TBLCOL Table can be one that was read in, accessed and possibly modified, or it can be generated from scratch.

There are very few limitations placed on Tables when used in the Dervish environment. But, there are some restrictions that need to be adhered to if the Table is to be written out as a FITS Header and Data Unit (HDU). In general, the writing out of a FITS HDU is the reverse of reading and HDU into a Table.

The following interfaces are provided for writing out FITS files:

  • ANSI C
  • Tcl
  • Platform-specific Floating Point Values

    The FITS Table writer does not convert between the native machine's floating point number representation and the FITS Standard floating point format (IEEE). This poses no problems when writing ASCII Tables. But, for Binary Tables, if the platform on which the FITS Table writer runs does not use the IEEE format, the resulting FITS HDU will not comply with the FITS Standard. Currently, the FITS Table writer does not convert from the native machine format to IEEE format. It simply copies the native format values to the FITS HDU.

    Dervish Headers

    The Dervish header associated with the TBLCOL Table being written is converted to a FITS header. This conversion basically adds FITS keywords needed to describe the FITS ASCII or Binary Table. Some Dervish header keywords associated with the TBLCOL, namely those which should not be available from the Dervish header, will not be written to the FITS header. Instead, these keywords are generated based on TBLCOL information.

    FITS keywords are generate from information in the different Table structures. Keywords describing the entire Table come from the TBLCOL structure. Per-field keywords are also generated. They are 1-indexed, namely the Table field position (0-indexed) plus 1. The generation of keyword values is dependent upon whether an ASCII Table or Binary Table HDU is being written. Their values are taken from the ARRAY and optional TBLFLD structures associated with the field.

    If the Dervish header contains unknown indexed keywords (for example, TMINEn), these are not guaranteed to correspond accurately with Table fields. The addition or removal of Table fields after these keywords were inserted into the Dervish header can cause this `misalignment.'

    Writing a TBLCOL Table out to a FITS HDU

    When data from a TBLCOL Table is written to a FITS HDU, the in-memory data type and the type of FITS HDU (ASCII or Binary Table) is used to determine how Table data is written out. For any FITS HDU type (ASCII or Binary Table)

    When writing an ASCII Table, all data in the Dervish Table is converted to its ASCII representation. Futhurmore

    When writing Binary Tables, data is copied directly from the Dervish Table to the FITS HDU. This direct copying can result in an invalid FITS HDU if the machine running Dervish does not use the IEEE floating point number format.

    Generating FITS-compliant HDUs

    Some integer data types supported by TBLCOL Tables are not directly supported by the FITS Standard (for example, unsigned 16-bit integers). For Binary Tables, the FITS community's convention is to use particular values for TSCALn and TZEROn to indicate that the "signedness" of the integer data type is to be flipped, along with the sign bit of the data associated with the Table field.

    When writing Binary Tables from a TBLCOL Table, the Binary Table field data type will be "flipped" and TSCALn is set to 1.0 and TZEROn is set to one of the following values based on the TBLCOL field data type (object schema):

    The TZEROs correspond to
              7-1            16-1                 32-1
       128 = 2      32768 = 2       2147483648 = 2
    

    This flipping of "signedness" only occurs when

    This last condition prevents the overriding of any explicit TSCALn or TZEROn values for the field, unless those values do not effectively affect the Table data. If these conditions are not met when requesting a FITS-compliant Table, the Table writing will not be done.

    If a FITS-compliant Table is not requested, then the unsupported integer data types are written to the Binary Table using Dervish's extension data types.

    Limitations and Quirks

    Complete flexibility with Dervish Tables is not available. There are some features of FITS ASCII and Binary Tables which cannot be attained:

    Invalid Conditions and How They are Handled

    Most conditions that would result in an invalid FITS file result in aborting the writing of the FITS file.