%++++++++
%.IDENTIFICATION tdat.tex
%.AUTHOR         Francois Ochsenbein, Steve Drake
%.VERSION   0.1	 27-Jun-1997: C-shell version(mods 1.1 to 1.9 deleted)
%----------

\def\pgm{{\bf tdat}\ }
\def\file{{\em file}}
\def\fih{{\em $\ast$.fih }}
\def\CDSdoc{{\em CDS Standards for Astronomical Catalogues},
	e.g. http://vizier.u-strasbg.fr/doc/catstd.htx}
\def\ffile{{\em Documentation File ({\tt ReadMe}) }}
\def\TDATdoc{{\em Transportable Database Aggregate Table (TDAT) Format},
	e.g. http://heasarc.gsfc.nasa.gov/docs/software/dbdocs/tdat.html}

\begin{manpage} {1}{tdat}{Transform a documentated file into TDAT}
	{Jun-1997}{TDAT}
\syntax{ \pgm [{\bf--v}] 
	[{\bf --m} {\em max\_records}]
	[{\bf --d} {\em data\_directory}]
	[{\bf --i} {\em description\_file}]
	[{\bf --h}]
	[{\bf --o} {\em output\_file}]
	[{\bf --}]
	[{\em input\_file}] }

\mansec{ Description }
The \pgm command translates a file described according to the
CDS Standards (see the \CDSdoc\ document) into TDAT (see \TDATdoc\ documents).

The trasnformation is normally made in 2 steps:
\begin{enumerate}
\item	Create the header part (extension {\bf.hdr})
\item	Create the full {\em tdat} file from the (eventually modified)
	header part.
\end{enumerate}

Note that {\em only the files described} in the {\tt ReadMe} can be converted to TDAT format.

\mansec{Options}

\option{--d {\em data\_directory}}
	indicates the directory containing the relevant files
	(data files, \fih files, the {\tt ReadMe} if not specified
	by the {\bf--i} option).
	The default {\em data\_directory} is the current directory.
\option{--help}
	displays a detailed help.
\option{--i {\em description\_file}}
	provides the non-standard ({\tt Intro} or {\tt ReadMe}) name
	of the {\em Description file};
\option{--m {\em max\_records}}
	asks to limit the generated {\em TDAT} file to the specified
	number of records.
	By default, all records are converted to {\em TDAT} format.
\option{--o {\em output\_file}}
	designates the file replacing the default {\em stdout} (terminal).
\option{--v}
	is a verbose option.

\mansec{Files}
The \file\ specified on the command line represents
\begin{itemize}
\item	in phase 1 (creation of a header): the name of a data file
	which exists in the {tt ReadMe} file.
\item	in phase 2 (creation of a full {em TDAT} file): the name 
	a file contaning the header part generated in phase 1.
\end{itemize}
%If a \file\ was preceded
%by a {\bf--t} option, \file\ is assumed to have the same structure
%as the {\bf--t} {\em table\_structure} argument ({\bf--} stands
%for the standard input).

%The default is to convert 
%{\em all described files}, i.e. all files included in the
%{\em File Summary} section of the {\tt ReadMe} file, with the
%exception of the non-convertable files.

%A dash {\bf--} or a dollar sign {\bf\$} 
%as a file name asks to stop the conversion;
%this is useful if one wants to generate only the {\em top header},
%as in
%
%\begin{verbatim}
%tofits -nodata -i DescriptionFile - > SIMPLE.fih
%\end{verbatim}
%
%Note that if the  \file\ argument is a directory, it has the same
%effect as it were preceded by the{\bf--d} flag.

%\mansec{Non-converted files}
%The extension of filenames is used to decide that a file should not
%be converted into TDAT. Files with names ending by {\tt.fih}, {\tt.fis}, 
%{\tt.tex}, {\tt.dvi}, {\tt.ps}, {\tt.pdf}, {\tt.doc}, {\tt.sty},
%{\tt.htm}, {\tt.html}, {\tt.tar} and {\tt.tgz}
%are not converted.

%\mansec{.MakeTDAT script}
%When a {\tt.MakeTDAT} file exists, it is called from \pgm (via the
%{\em Bourne shell} {\tt/bin/sh}) to generate {\em all} TDAT files:
%this can be executed only when \pgm\ is called without any
%\file\ argument.
%
%This script may use (and change) the following numeric environment variables
%which are set by \pgm before calling {\tt.MakeTDAT}:
%\begin{itemize}
%\item	{\tt toTDAT}=0 \quad to generate only the headers (option 
	%{\bf--nodata})
%\item	{\tt toTDAT}=0 \quad to skip the SIMPLE header
	%(option {\bf--noh})
%\item	{\tt toTDAT}=1 \quad to use the {\tt FILEMARK} extension
	%(which separates two TDAT files)
%\item	{\tt toTDAT}=1 \quad is the recursivity count, incremented
	%each time \pgm is called. 
%\end{itemize}
%
%The {\tt.MakeTDAT} script may (recursively) call \pgm.

\mansec{Returned Status}
The \pgm command returns 0 in case of success, and
non-zero when errors are found.

\mansec{Examples}
\begin{itemize}
\item	Convert the {\tt solar\_hp.dat} file of catalogue I/239 into a single compressed 
	TDAT file: \\
	{\tt tdat solar\_hp.dat > solar\_hp.hdr} \qquad {\em(phase 1)} \\
	{\tt tdat solar\_hp.hdr > solar\_hp.hdat} \qquad {\em(phase 2)}
\end{itemize}

\seealso{anafile(1)    ``\CDSdoc''  ``\TDATdoc'' tofits}
\end{manpage}
