.help fdump Jan92 ftools.futils
.ih
NAME
fdump -- Convert the contents of a FITS table to ASCII format.
.ih
USAGE
fdump infile[ext#] outfile columns rows	
.ih
DESCRIPTION
This task converts the information in the header and data of a FITS table
extension (either ASCII or binary table) into an ASCII format file which then
may  be
displayed, printed, or edited.  If desired the edited ASCII file may
be converted back into a FITS file using the fcreate task.
By default, fdump will convert all the
rows and columns of the table extension as well as all the header records
to the output ASCII file, but only selected information may be output by
setting the input parameters appropriately.  Fdump will fit as many table
columns
as possible on the output page (the page width can be specified with the
pagewid parameter);  any additional columns will be output onto subsequent
pages of output.  The output format is either a default format or
specified with TDISPn keywords.

This task is primarily designed to display FITS table extensions and currently
it can only output the header records of the primary
array or image extensions.  Use the fimgdmp task to output the data
in a FITS image.
.ih
PARAMETERS
.ls infile [file name]
The name of the FITS file (and extension number in square brackets or 
indicated with a '+' i.e. filename.fits+2) to
be converted.   If an asterisk is supplied for the extension number, or
if no extension number is specified,
then all extensions in the  FITS  file will be listed.
.le
.ls outfile [file name]
The name of the output ASCII file.  If outfile = 'STDOUT' then the
output will be written to the standard output device (usually the users
terminal) rather than to a file.  If the first character of outfile is
!, an existing file of the same name will be overwritten.
.le
.ls columns = "" [string]
The names of all the columns to be listed in the output.  The names may
be either the exact name of the column, or they may contain wildcard
characters (*, ?, or #), or they may contain the integer number of the
desired column (with the first column = 1).  The '*' wild card character
matches any sequence of characters (including zero characters) and the
'?' character matches any single character.  The '#' wildcard will match
any consecutive string of decimal digits (0-9).  If no names
are given, then by default all the columns in the table will be
output.  The column names must be separated by commas or spaces in the
list.  If a column name contains a space, the name must be enclosed in
double quotes (").  If any names in the column list are enclosed in
double quotes, the entire list must be enclosed in single quotes (').
eg '"column 1",column2'

Optionally the list of column names can be placed in an ASCII file, one name
per line, and then the name of the file, proceeded by an "@" character may
be given to the "columns" parameter.
If the first non-white character in the column list is the negation
character then the output file will contain those columns NOT named in the
remainder of the column list.

The 'flcol' task (with the NLIST parameter set to 1) may be used to
generate a list of column names suitable for input to this task.
.le
.ls rows = - [string]
The range of rows to be output.  The default of - means print all rows.
The first ten rows could be specified as ROWS=1-10 or just ROWS=-10.
To print the first ten rows and all rows from 900 through the last
(inclusive), use ROWS=1-10,900-.  ROWS=1,3,7,23 will print only
those four rows. 
.le
.ls (xdisp = " ") [string]
You can have options "D" or "d" (decimal integer), "B" or "b"(bit
string)  and default option. While the default option writes
a bit vector as 8-bit groups with a 'b' prefix, The
"D" option codes 8 bits into a decimal integer, and "B" option
displays bits as a bit string with the length of the vector.
For example, for a bit vector of (1,0,0,0,0,1,0,1,1,1), the
displays are:
.nf
       default option:           b10000101
                                 b11
       D option:                 133
                                 192
       B option:                 b1000010111
.fi
.ls (fldsep = " ") [string]
This parameter would enable the user to define a one character field 
separator between the columns. (The default field separator is space.)
.le
.ls (pagewidth = 80) [integer, min=1, max=256]
The width of the output for dumping the ASCII data.  If the width of all the
columns to
be dumped is wider than PAGEWIDTH, then the columns will be written to
multiple pages of output.
.le
.ls (prhead = yes) [boolean]
Should the header keywords be output?
.le
.ls (prdata = yes) [boolean]
Should the table extension data be output?
.le
.ls (showcol = yes) [boolean]
List the column names at the top of each column in the output?
.le
.ls (showunit = yes) [boolean]
Write the column units (if any) at the top of each column?
.le
.ls (showrow = yes) [boolean]
Write the row number at the left edge of the output page?
.le
.ls (showscale = yes) [boolean]
Whether to show the scaled values, or the actual values in the file.
.le
.ls (align = yes) [boolean]
Align each column (by increasing the column width if necessary) so
that it is underneath the column name?
.le
.ls (skip = 1) [integer]
This option allows the user to display only every nth row.  The default is
for all rows to be shown.
.le
.ls (tdisp = no) [boolean]
The parameter controls whether the program looks for TDISPn keywords for the
format of the output.  If tdisp is true, and no TDISPn keyword exists for the
requested column, the default output format is used.  Note also that if
the column name or units is longer than the specified keyword, the output
format will be widened appropriately.  TDISPn is not supported for 
logical, complex, or double complex columns, nor for ASCII tables.
.le
.ls (wrap = no) [boolean]
If true, each row will be displayed in its entirety.  The display will be
wrapped at pagewidth characters, and take as many lines as necessary.  If
false, the display consists of as many columns as fit in pagewidth characters,
and for all rows.  The remaining columns are displayed in another section.
.le
.ls (page = yes) [boolean]
If true, and if the output is sent to STDOUT, the output will be paged, so
that user is prompted after every 24 lines.
.le
.ls (clobber = no) [boolean]
If true, an existing file with the same name as the requested output file
will be overwritten.
.le
.ls (sensecase = yes) [boolean]
If true, column names will be searched for in a case-sensitive manner.
.le
.ls more = yes [boolean]
Whether to continue paging, or just quit at this point.  This parameter
should not be entered on the command line, and is only used for output
to the screen.
.le
.ih
EXAMPLES
1.  Dump the contents of the FITS table 'junk.fits' to the terminal:
.nf

     ft> fdump junk.fits STDOUT

.fi
2.  Dump 'junk.fits', including only the columns specified in the colnames.lis
file.
.nf

     ft> flcol junk.fits nlist=1 outfile = colnames.lis

     ft> edit colnames.lis
        (Delete or rearrange the order of the column names)

     ft> fdump junk.fits columns=@colnames.lis

.fi
3.  Dump only the first 100 rows of data in the file 'big.fits' to an
output file 'big.dat'; do not output the header keywords.

	ft> fdump big.fits big.dat rows=1-100 prhead=no
.ih
NOTES:
FDUMP truncates trailing blanks.
.ih
BUGS
Fdump cannot display the data in a FITS primary array or image extension.

If the width of a scaled column in an ASCII table is less than 8 characters,
the value cannot be displayed.

.ih
SEE ALSO
ftlist, ftcreate. fv, the interactive FITS file editor, can also be used to
view the contents of a FITS file.
.endhelp
