idlastro / FITS ASCII & Binary Table I/O: FTPUT

[Source code]

NAME

FTPUT

PURPOSE

Procedure to add or update a field in an FITS ASCII table

CALLING SEQUENCE

FTPUT, htab, tab, field, row, values, [ nulls ]

INPUTS

htab - FITS ASCII table header string array
tab - FITS ASCII table array (e.g. as read by READFITS)
field - string field name or integer field number
row -  either a non-negative integer scalar giving starting row to 
        update, or a non-negative integer vector specifying rows to 
        update.   FTPUT will append a new row to a table if the value 
        of 'row' exceeds the number of rows in the tab array    
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

htab,tab will be updated as specified.

EXAMPLE

One has a NAME and RA  and Dec vectors for 500 stars with formats A6,
F9.5 and F9.5 respectively.   Write this information to an ASCII table 
named 'star.fits'.
IDL> FTCREATE,24,500,h,tab       ;Create table header and (empty) data
IDL> FTADDCOL,h,tab,'RA',8,'F9.5','DEGREES'   ;Explicity define the
IDL> FTADDCOL,h,tab,'DEC',8,'F9.5','DEGREES'  ;RA and Dec columns
IDL> FTPUT,h,tab,'RA',0,ra       ;Insert RA vector into table
IDL> FTPUT,h,tab,'DEC',0,dec       ;Insert DEC vector into table
IDL> FTPUT, h,tab, 'NAME',0,name   ;Insert NAME vector with default
IDL> WRITEFITS,'stars.fits',tab,h ;Write to a file
ote that (1) explicit formatting has been supplied for the (numeric)
A and Dec vectors, but was not needed for the NAME vector, (2) A width
f 24 was supplied in FTCREATE based on the expected formats (6+9+9),
hough the FT* will adjust this value as necessary, and (3) WRITEFITS
ill create a minimal primary header  

NOTES

(1) If the specified field is not already in the table, then FTPUT will
create a new column for that field using default formatting.   However,
 FTADDCOL should be called prior to FTPUT for explicit formatting.

PROCEDURES CALLED

FTADDCOL, FTINFO, FTSIZE, SXADDPAR, SXPAR()

HISTORY

version 1  D. Lindler July, 1987
Allow E format         W. Landsman          March 1992
Write in F format if E format will overflow    April 1994
Update documentation W. Landsman   January 1996
Allow 1 element vector  W. Landsman   March 1996
Adjust string length to maximum of input string array   June 1997
Work for more than 32767 elements August 1997
Converted to IDL V5.0   W. Landsman   September 1997
Updated call to the new FTINFO   W. Landsman   May 2000
Fix case where header does not have any columns yet W.Landsman Sep 2002
Assume since V5.2, omit fstring() call  W. Landsman April 2006