fdump HEADAS help file

NAME

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

USAGE

        fdump infile[ext#] outfile columns rows

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.

PARAMETERS

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.

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.

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.

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.

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

                    default option:           b10000101
                                              b11
                    D option:                 133
                                              192
                    B option:                 b1000010111

(fldsep = " ") [string]: This parameter would enable the user to define a one character field separator between the columns. (The default field separator is space.)
(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.
(prhead = yes) [boolean]: Should the header keywords be output?
(prdata = yes) [boolean]: Should the table extension data be output?
(showcol = yes) [boolean]: List the column names at the top of each column in the output?
(showunit = yes) [boolean]: Write the column units (if any) at the top of each column?
(showrow = yes) [boolean]: Write the row number at the left edge of the output page?
(showscale = yes) [boolean]: Whether to show the scaled values, or the actual values in the file.
(align = yes) [boolean]: Align each column (by increasing the column width if necessary) so that it is underneath the column name?
(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. 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.
(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.
(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.
(sensecase = yes) [boolean]: If true, column names will be searched for in a case-sensitive manner.
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. Dump the contents of the FITS table 'junk.fits' to the terminal:

          
               ft> fdump junk.fits STDOUT

2. Dump '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> fdump junk.fits columns=@colnames.lis

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

NOTES:

FDUMP truncates trailing blanks.

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.