.help flist Sep93 ftools.futils
.ih
NAME
flist -- Convert the contents of a FITS table to ASCII format.
.ih
USAGE
flist infile[ext#] outfile columns rows	
.ih
DESCRIPTION
This task prints the information in the header and data of a FITS table
extension (either ASCII or binary table) into ASCII format which then
may be displayed or printed.  This task is similar to the XANADU program
DUMPFITS, and
performs much the same function as the FTOOLS FDUMP.  FDUMP is
recommended for output to a file, or for piping into other programs.
By default, flist will print all the
rows and columns of all extensions as well as all the header records
to STDOUT (the terminal screen) or to an output ASCII file, but only 
selected information may be output by
setting the input parameters appropriately.  
The output format is either a default format or
specified with TDISPn keywords.

This task is primarily designed to display FITS table extensions to the
screen 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 by a +) 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 preceeded by a !, 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.  If no names
are given (or a '-'), 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 (prhead = yes) [boolean]
Should the header keywords be output?
.le
.ls (prdata = yes) [boolean]
Should the table extension data be output?
.le
.ls (showscale = yes) [boolean]
Whether to show the scaled values, or the actual values in the file.
.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.
.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 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.  List the contents of the FITS table 'junk.fits' to the terminal:
.nf

     ft> flist junk.fits STDOUT

.fi
2.  List '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> flist junk.fits columns=@colnames.lis

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

	ft> flist big.fits+2 big.dat rows=1-100 prhead=no
.ih
BUGS
FLIST 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.

Complex and Double Complex datatypes 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 table.
.endhelp
