READFMT
Name
READFMT
Purpose
Quickly read a fixed format ASCII data file into IDL variables.
Explanation
Lines of data not meeting the specified format (e.g. comments) are
ignored.
To read a free format ASCII data file use the procedures
READCOL or RDFLOAT. To print (formatted or free) columns of data
use the procedure FORPRINT.
Calling Sequence
READFMT, name, fmt, v1,[ v2, v3, v4, ..., v25 ,
/SILENT, /DEBUG, SKIPLINE= , NUMLINE =]
Inputs
NAME - Name of ASCII data file. An extension of .DAT is assumed,
if not supplied.
FMT - scalar string containing a valid FORTRAN read format.
Must include a field length specification. Cannot include
internal parenthesis. A format field must be included for
each output vector. Multiple format fields are allowed, but
the repetition factor must be less than 100, (.i.e. 19X is
allowed but 117X is illegal)
Examples of valid FMT values are
FMT = 'A7,3X,2I4' or FMT = '1H ,5I7,2A7'
Examples of INVALID FMT values are
FMT = 'A7,B3' ;'B' is not a valid FORTRAN format
FMT = 'A7,2(I3,F5.1)' ;Internal parenthesis not allowed
FMT = 'A7,F,I' ;Field length not included
Outputs
V1,V2,V3,V4... - IDL vectors to contain columns of data.
Up to 25 output vectors may be read. The type of the output
vectors are specified by FMT.
Optional Keyword Inputs
/SILENT - If this keyword is set and non-zero, then certain terminal
output is suppressed while reading the file
/DEBUG - Set this keyword to display additional information while
reading the file.
SKIPLINE - Scalar specifying number of lines to skip at the top of
file before reading. Default is to start at first line
NUMLINE - Scalar specifying number of lines in the file to read.
Default is to read the entire file
Examples
Each row in a fixed-format file POSITION.DAT contains a 5 character
star name and 6 columns of data giving an RA and Dec in sexagesimal
format. A possible format for such data might be
IDL> FMT = 'A5,2I3,F5.1,2x,3I3'
and the file could be quickly read with
IDL> READFMT,'POSITION', fmt, name, hr, min, sec, deg, dmin, dsec
NAME will be a string vector,SEC will be a floating point vector, and
the other vectors will be of integer type.
Restrictions
This procedure is designed for generality and not for speed.
If a large ASCII file is to be read repeatedly, it may be worth
writing a specialized reader.
Notes
When reading a field with an integer format I<n>, the output vector is
byte - if n = 1
integer*2 - if 1 < n < 5
integer*4 - in all other cases
Octal ('O') and hexadecimal ('Z') formats are read into longwords
Procedure Calls
GETTOK(), REMCHAR, ZPARCHECK
Revision History
Written W. Landsman November, 1988
Added SKIPLINE and NUMLINE keywords March 92
Allow up to 25 columns to be read June 92
Call NUMLINES() function Feb 1996
Recognize 'O' and 'Z' formats W. Landsman September 1997
Recognize 'G' format, use SKIP_LUN W. Landsman May 2010