idlastro / Miscellaneous (Non-Astronomy) Procedures: READFMT

[Source code]

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, 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