3.6.2 Reserved Keywords for Binary Table Extension Header

These keywords are optional in a binary table extension but may be used only with the meanings specified below. They may appear in any order between the TFIELDS and END keywords. Note that some of these keywords are the same as those for an ASCII table extension. The reason is that they are used for a binary table in a way analogous to their use for an ASCII table. However, the allowed values and their meaning may differ somewhat from those for an ASCII table, as the rows of an ASCII table are composed of characters and those of a binary table are composed of bytes.

• TTYPEn (character) has a value giving the label or heading for field n. While the rules do not further prescribe the value, following the recommendations for the TTYPEn keyword of ASCII tables is a good practice: using letters, digits, and underscore but not hyphen; also, string comparisons involving the values should be case insensitive. HEASARC has made this practice one of their internal standards (section 5.6.1.1).
• TUNITn (character) has a value giving the physical units of field n. The rules should follow the prescriptions given in section 3.1.1.4.
• TSCALn (floating) has a value providing a scale factor for use in converting stored table values for field n to physical values. The default value is 1.
• TZEROn (floating) has a value providing the offset for field n. The default value is 0.
  

  (Physical_value) = (Stored_value) × TSCALn + TZEROn   (3.12)

  As is the case for arrays, care should be taken to avoid overflows when scaling floating point numbers.

  For L, X, and A format fields, the TSCALn and TZEROn keywords have no meaning and should not be used. The meaning has not been formally defined for P format fields, but the general understanding is that the scaling should apply to the heap data pointed to by the array descriptors.

• TNULLn (integer) has the value that signifies an undefined value for the integer data types B, I, and J. It should not be used if the value of the corresponding TFORMn specifies any other data type. Null values for other data types are discussed in section 3.6.3.
• TDISPn (character) has a value giving the Fortran 90 format recommended for display of the contents of field n. (If Fortran 90 formats are not available to the software printing a table, FORTRAN-77 formats may be used instead.) All entries in a single field are displayed with the same format. If the field data are scaled, the physical values, derived by applying the scaling transformation, are displayed. For bit and byte arrays, each byte is considered to be an unsigned integer for purposes of display. Characters and logical values may be null (zero byte) terminated. The following formats are allowed:

  Lw

  Logical

  Aw

  Character

  Iw.m

  Integer

  Bw.m

  Binary, integers only

  Ow.m

  Octal, integers only

  Zw.m

  Hexadecimal, integers only,

  Fw.d

  Single precision real, no exponent

  Ew.dEe

  Single precision real, exponential notation

  ENw.d

  Engineering format - single precision real, exponential notation with exponent a multiple of 3

  ESw.d

  Scientific format - single precision real, exponential notation with exponent a multiple of 3, nonzero leading digit (unless value is zero)

  Gw.dEe

  General - appears as F format if significance will not be lost; otherwise appears as E

  Dw.dEe

  Double precision real, exponential notation

  In these formats, w is the number of characters in the displayed values, m is the minimum number of digits (leading zeroes may be required), d is the number of digits following the decimal point, and e is the number of digits in the exponent of an exponential form. Usage of this keyword in some ways parallels that of the TFORMn keyword of ASCII tables, in that it provides a formatted value for the number. However, the format given by the TFORMn keyword in an ASCII table describes the format of the number in the FITS file, but the format given by the TDISPn keyword of a binary table is different from that of the number in the file.

The following keywords are reserved for proposed binary table conventions:

• TDIMn (character) is used by the multidimensional array convention (section 5.2.3). For that convention, it has a value giving the number of dimensions of field n in the table, when those dimensions are two or more. The value is of form '(i,j,k,...)', where i,j,k,...are the dimensions of the array stored in field n. This size must be consistent with the repeat count specified by the value of TFORMn.
• THEAP (integer) is used by the variable length array convention (section 5.2.1). For that convention, its value gives the location of the start of the heap used to store variable length arrays. The value is equal to the number of bytes of extension data preceding the start of the heap, including the main table and any gap between the main table and the heap.

All keywords reserved under the generalized extensions agreement (section 3.3.2) apply to binary tables.