.help fmemsort Nov97 ftools.futils
.ih
NAME
fmemsort -- Sort the contents of a FITS table in memory
.ih
USAGE
fmemsort infile[ext#] outfile columns method 
.ih
DESCRIPTION
This task sorts the rows in a FITS table based on the values in
the specified columns of the table.  The table is sorted in memory to 
maximize the sorting performance. The table may be sorted in ascending 
or descending order. Several sorting algorithms are available. This task
produces a new FITS file containing the sorted table whose structure is 
determined by the parameters described below.

When sorting extremely large files it is recommended that the output FITS
file be located on a different drive than the input FITS file. This is to
minimize disk head seeks and hence improve I/O performance.
.ih
PARAMETERS
.ls infile [file name]
The file name (and extension number in square brackets) of the FITS file. 
The extension number specifies the table to be sorted.
.le
.ls outfile [file name]
Name of the new FITS file to contain the sorted table extension.
By default, the output file will consist of a copied primary array 
followed by the sorted ASCII or binary table extension,
depending on the type of input file extension.  If preceeded by !, an
existing file of the same name will be overwritten.
.le
.ls columns [string list]
A list of column names appearing in the FITS table extension to be
sorted in the order specified.
.le
.ls method = "heap" [string]
Sorting algorithm to be used. Currently supported algorithms are the
"heap"(NlogN), "shell"(N**1.5) and "insert"(N**2) sort. The shell gives
better performance with midsize data sets.  The heap sort 
gives the best speed when dealing with large random datasets. The 
insertion sort works best when the dataset is very nearly sorted,
 i.e., one value out of place.
.le
.ls (ascend = yes) [boolean, yes=ascend, no=descend]
An optional boolean flag used to determine if sorting is to be done 
in ascending or descending order. This flag applies to all columns 
sorted.
.le
.ls (load2mem = yes) [boolean, yes=load, no=don't load]
An optional boolean flag used to determine if the whole FITS table containing 
the columns to be sorted should be loaded into system memory. This can speed 
up sorting times if the system resources are large enough.
.le
.ls (copyprime = yes) [boolean]
If true, the primary header and array of the input file will be
copied to the output file.
.le
.ls (copyall = yes) [boolean]
Copy all other extensions (and the primary array) from input FITS file
to the output FITS file?  If true, the value of copyprime is ignored.
.le
.ls (unique = no) [boolean, yes=keep unique, no=keep all]
An optional boolean flag used to determine if rows with identical sort
keys should be purged, keeping one unique row.  Columns not included
in the sort are not tested for uniqueness.
.le
.ls (history=yes) [boolean]
When this parameter is true, FMEMSORT will add a history record to 
indicate that it acted on the file.
.le
.ls (clobber = no) [boolean]
If true, an existing file with the same name as the requested output file
will be overwritten.
.le
.ih
EXAMPLES
1.  Sort the time column found in the second table extension in
ascending order in the FITS file test.fits
.nf

	ft> fmemsort test.fits[2] out.fits time
.fi

2. Sort using the X and Y columns found in the first extension in
descending order with the insert method in the FITS file test.fits
.nf

	ft> fmemsort test.fits out.fits "X Y" method = "insert" ascend=no
.fi
.ih
BUGS
.ih
SEE ALSO
ftsort. fv, the interactive FITS file
editor, can also be used to sort a FITS table.
.endhelp
