NAME: FTADDCOL PURPOSE: Routine to add a field to a FITS ASCII table CALLING SEQUENCE: ftaddcol, h, tab, name, idltype, [ tform, tunit, tscal, tzero, tnull ] INPUTS: h - FITS table header. It will be updated as appropriate tab - FITS table array. Number of columns will be increased if neccessary. name - field name idltype - idl data type (as returned by SIZE function) for field, For string data (type=7) use minus the string length. OPTIONAL INPUTS: tform - format specification 'qww.dd' where q = A, I, E, or D tunit - string giving physical units for the column. tscal - scale factor tzero - zero point for field tnull - null value for field Use '' as the value of tform,tunit,tscal,tzero,tnull if you want the default or no specification of them in the table header. OUTPUTS: h,tab - updated to allow new column of data HISTORY: version 1 D. Lindler July, 1987
(See /usr/local/idl/lib/zastron/fits_table/ftaddcol.pro)
NAME: FTCREATE PURPOSE: Procedure to create a new (blank) FITS ASCII table and header with the specified size. CALLING SEQUENCE: ftcreate, maxcols, maxrows, h, tab INPUTS: maxcols - number of character columns allocated, integer scalar maxrows - maximum number of rows allocated, integer scalar OUTPUTS: h - FITS header, string array tab - empty table, byte array HISTORY: version 1 D. Lindler July. 87 21-Sep-88: Because the degenerative dimension is deleted in Sun IDL, this procedure has been modified to create table with at least two rows. If this isn't done, the other FT routines choke on a table of one row. 24-Oct-88: Changed length of header strings from 81 to 80. This conforms to the latest format for FITS header strings. The 81 character format was dropped due to problems it caused when data was transferred back to the VAX.
(See /usr/local/idl/lib/zastron/fits_table/ftcreate.pro)
NAME: FTDELCOL PURPOSE: Delete a column of data from a FITS table CALLING SEQUENCE: ftdelcol, h, tab, name INPUTS-OUPUTS h,tab - FITS table header and data array. H and TAB will be updated with the specified column deleted INPUTS: name - Either (1) a string giving the name of the column to delete or (2) a scalar giving the column number to delete EXAMPLE: Suppose it has been determined that the F7.2 format used for a field FLUX in a FITS table is insufficient. The old column must first be deleted before a new column can be written with a new format. flux = FTGET(h,tab,'FLUX') ;Save the existing values FTDELCOL,h,tab,'FLUX' ;Delete the existing column FTADDCOL,h,tab,'FLUX',8,'F9.2' ;Create a new column with larger format FTPUT,h,tab,'FLUX',0,flux ;Put back the original values REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Adapted for IDL Version 2, J. Isensee, July, 1990
(See /usr/local/idl/lib/zastron/fits_table/ftdelcol.pro)
NAME: FTDELROW PURPOSE: Delete a row of data from a FITS table CALLING SEQUENCE: ftdelrow, h, tab, rows INPUTS-OUPUTS h,tab - FITS table header and data array. H and TAB will be updated on output with the specified row(s) deleted. rows - scalar or vector, specifying the row numbers to delete This vector will be sorted and duplicates removed by FTDELROW EXAMPLE: Compress a table to include only non-negative flux values flux = FTGET(h,tab,'FLUX') ;Obtain original flux vector bad = where(flux lt 0) ;Find negative fluxes FTDELROW,h,tab,bad ;Delete rows with negative fluxes PROCEDURE: Specified rows are deleted from the data array, TAB. The NAXIS2 keyword in the header is updated. REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Checked for IDL Version 2, J. Isensee, July, 1990
(See /usr/local/idl/lib/zastron/fits_table/ftdelrow.pro)
NAME:
FTDIR
PURPOSE:
Provide a brief description of the disk FITS ASCII tables on a
directory. The # of columns and rows, and the extension name are
displayed for each table found. Use TBDIR to display FITS binary
tables.
CALLING SEQUENCE:
FTDIR, [ directory, TEXTOUT = ]
INPUT PARAMETERS:
DIRECTORY - String giving the disk or directory to be searched.
Wildcard directory values are allowed.
If not given FTDIR searches the default directory.
In VMS: Examples of valid strings include 'LINEAR:',
'UIT$USER2:', 'S*', or '[...]'.
In Unix: Valid strings must include trailing slash for
a directory specification. EX: '/tables'
OUTPUT PARAMETERS:
The following dev/file is opened for output (see TEXTOPEN for more
info).
textout=1 TERMINAL using /more option
textout=2 TERMINAL without /more option
textout=3 .prt
textout=4 laser.tmp
textout=5 user must open file
textout = filename (default extension of .prt)
RESTRICTIONS:
Only files with header extensions *.hhh and with an XTENSION
keyword are searched.
Fields may be truncated on the output display if they are too long.
METHOD:
FINDFILE is used to find all *.HHH files on directory. Each
header is searched for the XTENSION keyword and then the values
of the FITS parameters NAXIS1, NAXIS2, TFIELDS and EXTNAME are printed
PROCEDURES USED:
SXHREAD, TEXTOPEN,TEXTCLOSE
Also uses non-standard system variables !TEXTUNIT and !TEXTOUT
MODIFICATION HISTORY:
Written, W. Landsman, ST Systems Corporation February 1988
Rewritten for Unix compatibility, use EXTNAME keyword
W. Landsman August 1991
(See /usr/local/idl/lib/zastron/fits_table/ftdir.pro)
NAME: FTGET PURPOSE: function to return value(s) from specified column CALLING SEQUENCE values = ftget( h, tab, field, [ rows, nulls ] ) INPUTS: h - FITS header returned by FTREAD tab - FITS table array returned by FTREAD field - field name or number OPTIONAL INPUTS: rows - scalar or vector giving row number(s) Row numbers start at 0. If not supplied or set to -1 then values for all rows are returned OUTPUTS: the values for the row are returned as the function value. Null values are set to 0 or blanks for strings. OPTIONAL OUTPUT: nulls - null value flag of same length as the returned data. It is set to 1 at null value positions and 0 elsewhere. If supplied then the optional input, rows, must also be supplied. HISTORY: coded by D. Lindler July, 1987 Always check for null values to prevent conversion errors W. Landsman August 1990
(See /usr/local/idl/lib/zastron/fits_table/ftget.pro)
NAME:
FTHELP
PURPOSE:
Routine to print a description of a disk ASCII FITS table
CALLING SEQUENCE:
FTHELP, H, [ TEXTOUT = ]
INPUTS:
H - FITS header for table, string array
OPTIONAL INPUT KEYWORD
TEXTOUT - scalar number (1-6) or string (file name) controling
output device (see TEXTOPEN). Default is TEXTOUT=1, output
to the user's terminal
NOTES:
FTHELP checks that the keyword XTENSION equals 'TABLE' in the FITS
header.
SYSTEM VARIABLES:
Uses non-standard system variable !TEXTOUT and !TEXTUNIT
PROCEDURES USED:
ZPARCHECK, SXPAR, TEXTOPEN, TEXTCLOSE, REMCHAR
HISTORY:
version 1 W. Landsman Jan. 1988
Add TEXTOUT option, cleaner format W. Landsman September 1991
(See /usr/local/idl/lib/zastron/fits_table/fthelp.pro)
NAME: FTHMOD PURPOSE: Procedure to modify header information for a specified field in a FITS table. CALLING SEQUENCE: fthmod, h, field, parameter, value INPUT: h - FITS header for the table field - field name of number parameter - string name of the parameter to modify. Choices include: TTYPE - field name TUNIT - physical units for field (eg. 'ANGSTROMS') TNULL - null value (string) for field, (eg. '***') TFORM - format specification for the field TSCAL - scale factor TZERO - zero offset User should be aware that the validity of the change is not checked. Unless you really know what you are doing, this routine should only be used to change field names, units, or another user specified parameter. value - new value for the parameter. Refer to the FITS table standards documentation for valid values. METHOD: The header keywordis modified with the new value. HISTORY: version 1, D. Lindler July 1987
(See /usr/local/idl/lib/zastron/fits_table/fthmod.pro)
NAME: FTINFO PURPOSE: Procedure to return information on the specified field in a FITS ASCII table. CALLING SEQUENCE: ftinfo,h,field,tbcol,width,idltype,tunit,tscal,tzero,tnull, tform,ttype INPUTS: h - FITS ASCII table header field - field name or field number (beginning at 1) OUTPUTS: tbcol - starting column position in bytes width - width of the field in bytes idltype - idltype of field. 7 - string, 4- real*4, 3-integer, 5-real*8 tunit - string unit numbers tscal - scale factor tzero - zero point for field tnull - null value for the field tform - format for the field ttype - field name SIDE EFFECTS: !err is set to the field number. If the specified field is not in the table then !err is set to -1. HISTORY: D. Lindler July, 1987
(See /usr/local/idl/lib/zastron/fits_table/ftinfo.pro)
NAME: FTKEEPROW PURPOSE: Subscripts (and reorders) a FITS table. A companion piece to FTDELROW. CALLING SEQUENCE: ftkeeprow, h, tab, subs INPUT PARAMETERS: h = FITS table header array tab = FITS table data array subs = subscript array of FITS table rows. Works like any other IDL subscript array (0 based, of course). OUTPUT PARAMETERS: h and tab are modified MODIFICATION HISTORY: Written by R. S. Hill, ST Sys. Corp., 2 May 1991.
(See /usr/local/idl/lib/zastron/fits_table/ftkeeprow.pro)
NAME:
FTPRINT
PURPOSE:
Procedure to print specified columns and rows of a FITS table
CALLING SEQUENCE:
ftprint, h, tab, columns, [ rows, TEXTOUT = ]
INPUTS:
h - Fits header for table, string array
tab - table array
columns - string giving column names, or vector giving
column numbers (beginning with 1). If string
supplied then column names should be separated by comma's.
rows - (optional) vector of row numbers to print. If
not supplied or set to scalar, -1, then all rows
are printed.
OUTPUTS:
None
OPTIONAL INPUT KEYWORDS:
TEXTOUT controls the output device; see the procedure TEXTOPEN
SYSTEM VARIABLES:
Uses nonstandard system variables !TEXTOUT and !TEXTOPEN
Set !TEXTOUT = 3 to direct output to a disk file. The system
variable is overriden by the value of the keyword TEXTOUT
EXAMPLES:
ftprint,h,tab,'STAR ID,RA,DEC' ;print id,ra,dec for all stars
ftprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for
;first 100 stars
ftprint,h,tab,text="STARS.DAT" ;Convert entire FITS table to
;an ASCII file named STARS.DAT
PROCEDURES USED:
TEXTOPEN,TEXTCLOSE,FTSIZE,FTINFO
RESTRICTIONS:
(1) Program does not check whether output length exceeds output
device capacity (e.g. 80 or 132).
(2) Column heading may be truncated to fit in space defined by
the FORMAT specified for the column
(3) Program does not check for null values
HISTORY:
version 1 D. Lindler Feb. 1987
(See /usr/local/idl/lib/zastron/fits_table/ftprint.pro)
NAME: FTPUT PURPOSE: Procedure to add or update a field in an FITS table CALLING SEQUENCE: ftput, h, tab, field, row, values, [ nulls ] INPUTS: h - FITS ASCII table header string array tab - table array read by FTREAD or created by FTCREATE field - string field name or integer field number row - scalar giving starting row to update, or vector specifying rows to update values - value(s) to add or update. If row is a vector then values must contain the same number of elements. OPTIONAL INPUT: nulls - null value flag of same length as values. It should be set to 1 at null value positions and 0 elsewhere. OUTPUTS: h,tab will be updated as specified. HISTORY: version 1 D. Lindler July, 1987 Allow E format W. Landsman March 1992
(See /usr/local/idl/lib/zastron/fits_table/ftput.pro)
NAME: FTREAD PURPOSE: Procedure to read an internal FITS table file CALLING SEQUENCE: ftread, name, h, tab, [ unit ] INPUTS: name - name of table header file (if qualifier not supplied then .hhh is assummed) OUTPUTS: h - FITS ASCII table header, string array tab - table array (2-D byte array of ascii characters) OPTIONAL INPUTS: unit - unit number (1 to 9) to use for I/O (default=1) PROCEDURES CALLED: ZPARCHECK, SXREAD, SXPAR, SXOPEN HISTORY: Coded by D. Lindler July 1987 21-Sep-88: Because of the deletion of the degenerative dimension in Sun IDL, this program has been modified to allocate a table of greater number of rows than required if only one row is required.
(See /usr/local/idl/lib/zastron/fits_table/ftread.pro)
NAME: FTSIZE PURPOSE: Procedure to return the size of a FITS ASCII table. CALLING SEQUENCE: ftsize,h,tab,ncols,rows,tfields,ncols_all,nrows_all INPUTS: h - FITS ASCII table header tab - FITS table array OUTPUTS: ncols - number of characters per row in table nrows - number of rows in table tfields - number of fields per row ncols_all - number of characters/row allocated (size of tab) nrows_all - number of rows allocated HISTORY D. Lindler July, 1987
(See /usr/local/idl/lib/zastron/fits_table/ftsize.pro)
NAME: FTSORT PURPOSE: Sort a FITS ASCII table according to a specified field CALLING SEQUENCE: FTSORT,H,TAB,[FIELD] ;Sort original table header and array or FTSORT,H,TAB,HNEW,TABNEW,[FIELD] ;Create new sorted header INPUTS: H - FITS header (string array) TAB - FITS table (byte array) associated with H. If less than 4 parameters are supplied, then H and TAB will be updated to contain the sorted table OPTIONAL INPUTS: FIELD - Field name used to sort the entire table. Character fields are sorted using the ASCII collating sequence. If omitted, the user will be prompted for the field name. OPTIONAL OUTPUTS: HNEW,TABNEW - Header and table containing the sorted tables RESTRICTIONS: FTSORT always sorts in order of increasing magnitude. To sort in decreasing magnitude, type TAB = REVERSE(TAB,2) after running FTSORT. SIDE EFFECTS: A HISTORY record is added to the table header. REVISION HISTORY: Written W. Landsman June, 1988
(See /usr/local/idl/lib/zastron/fits_table/ftsort.pro)
NAME: FTWRITE PURPOSE: Procedure to write an FITS table to disk CALLING SEQUENCE: ftwrite, name, h, tab, unit INPUTS: name - file name. If an extension is supplied it must be 3 char. ending in H. h - FITS ASCII header tab - table array OPTIONAL INPUT: unit - disk unit number (1 to 9). If not supplied 1 is used. SIDE EFFECTS: Two files are created with the given name and extensions. xxH and xxD. If no extension is supplied then .HHH is assumed. HISTORY: version 1 D. Lindler July, 1987
(See /usr/local/idl/lib/zastron/fits_table/ftwrite.pro)