flist HEADAS help file

NAME

flist -- Convert the contents of a FITS table to ASCII format.

USAGE

        flist infile[ext#] outfile columns rows

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.

PARAMETERS

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

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.

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.

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.

(prhead = yes) [boolean]

Should the header keywords be output?

(prdata = yes) [boolean]

Should the table extension data be output?

(showscale = yes) [boolean]

Whether to show the scaled values, or the actual values in the file.

(skip = 1) [integer]

This option allows the user to display only every nth row. The default is for all rows to be shown.

(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.

(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.

(clobber = no) [boolean]

If true, an existing file with the same name as the requested output file will be overwritten.

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.

EXAMPLES

1. List the contents of the FITS table 'junk.fits' to the terminal:

     
          ft> flist junk.fits STDOUT

2. List 'junk.fits', including only the columns specified in the colnames.lis file.

     
          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

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

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.