Subject: Appendix C to BINTABLE definition document

From: [email-masked] (William Pence)
Date: Mon, 12 Apr 93 10:27:49 EDT

Dear WGAS FITS Committee members,

Attached below is the proposed Appendix C to the 'Binary Table Extension to FITS'
document.  Since Don Wells will be calling for a vote on the 3 pending FITS proposals
later this week,  please circulate any comments or objections to this proposal
as soon as possible.

-Bill Pence

-----  Latex document follows;  cut here ------------------------------------------
\documentstyle{article}
\begin{document}
\appendix{}
\begin{center}
   {\LARGE\bf Appendix C \par}
   \vskip 1em
   {\large\bf ``Substring Array'' Convention}
\end{center}
\vskip 20pt

This appendix describes a layered convention for specifying that a
character array field (TFORMnnn = 'rA') consists of an array of either
fixed-length or variable-length substrings within the field.  This
convention utilizes the option described in the basic binary table
definition document to have additional characters following the
datatype code character in the TFORMnnn value field.  The full form for
the value of TFORMnnn within this convention is 'rAw/nnn' where,

\begin{verse}
{\it r} is an integer giving the total length (in characters) of the field, \\
{\it A} signifies that this is a character array field, \\
{\it w}  is an integer $\leq $ r giving the (maximum) number of characters in an
individual substring (not including the delimiter), and \\
{\it /nnn} if present, indicates that the substrings 
have variable-length and are delimited by an ASCII text character with decimal
value nnn in the range 032 to 126 decimal, inclusive.
\end{verse}

To illustrate this usage:
\begin{verse}
'40A8' signifies that the field is 40 characters wide and consists of
an array of 5 8-character fixed-length substrings. 

'100A8/032' signifies that the field is 100 characters wide and consists
of an array of variable-length substrings where each substring has a
maximum length of 8 characters and is terminated by an ASCII SPACE (decimal
32) character.
\end{verse}

Note that simple FITS readers that do not understand this substring
convention can ignore the TFORM characters following the {\it rA} and
can interpret the field simply as a single long string as described in
the basic binary table definition document.

The following rules complete the full definition of this convention:

\begin{enumerate}

\item 
In the case of fixed-length substrings, if {\it r} is not an integer
multiple of {\it w}  then the remaining odd characters are undefined and
should be ignored.   For example if TFORMnnn = '14A3', then the field
contains 4 3-character substrings followed by 2 undefined characters.

\item  
Fixed-length substrings must always be padded with blanks if
they do not otherwise fill the fixed-length subfield. 
The ASCII NUL character must not be used to terminate a
fixed-length substring field.  

\item  
If an array of variable-length substrings does not completely
fill the binary table field, then the last substring must be
terminated with an ASCII NUL character (value 000), rather than the substring
delimiter character.  

\item 
The method of signifying an undefined or null substring within a
fixed-length substring array is not explicitly defined by this
convention (note that there is no ambiguity if the variable-length format
is used).  In most cases it is recommended that a completely blank
substring be used for this purpose.  In cases where it is necessary to
make a distinction between a blank substring and an undefined
substring, then any other suitable string may be used to designate the
undefined substrings (e.g., 'INDEF' or 'NULL').

\item 
Undefined or null variable-length substrings are designated by a
zero-length substring, i.e., by a delimiter character (or an ASCII NUL
if it is the last substring in the table field) in the first position
of the substring.  An ASCII NUL in the first character of the table
field indicates that the field contains no defined variable-length
substrings.

\item  
The ``Multidimensional Array''convention described in Appendix A of
this document provides a syntax using the TDIMnnn keyword for
describing multidimensional arrays of any datatype which can also be
used to represent arrays of fixed-length substrings.  To minimize
confusion it is recommended that the substring convention and the TDIM
convention not be used for two character columns in the same table.
The substring convention should be considered the preferred method for
storing arrays or lists of strings in a character field of a table
record.

\item  
This substring convention may be used in conjunction with
the ``Variable Length Array'' facility described in Appendix B of
this document.  In this case, the full form for the value of the
TFORM keyword is:

\begin{verbatim}
TFORMnnn= 'rPAw/nnn(maxelem)'   / for variable-length substrings
TFORMnnn= 'rPAw(maxelem)'       / for fixed-length substrings
\end{verbatim}

\end{enumerate}

\vskip 1em
This convention is optional and will not preclude other conventions.
This convention is not part of the proposed binary table definition.

\end{document}