PRO read_ascii_file, filename, nheader, nlines_in, lines, nlines_out, status

; Description: This module reads in a set of lines from an ASCII file. The module
;              will skip the first "nheader" lines, and then read in the next
;              "nlines_in" lines, storing each line in a string array called "lines".
;              The actual number of lines read in is recorded in "nlines_out",
;              corresponding to the number of elements in the module output "lines".
;
; Input Parameters:
;
;   filename - STRING - The full directory path and filename of the ASCII file to
;                       be read in.
;   nheader - INTEGER/LONG - The number of header lines to be skipped when reading in
;                            the ASCII file (Default value = 0).
;   nlines_in - INTEGER/LONG - The number of data lines to be read in and stored. If
;                              set to "0", then all lines after the header line(s)
;                              will be read in and stored (Default value = 0).
;
; Output Parameters:
;
;   lines - STRING VECTOR - A vector of strings where each element stores a line from
;                           the ASCII file.
;   nlines_out - LONG - The number of data lines actually read in and stored.
;   status - INTEGER - If the file reading operation was successful, then "status" is
;                      returned with a value of "1", otherwise it is returned with a
;                      value of "0".
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
;   18/05/2008 - Module created (dmb)

;Check that "filename" is a variable of STRING type

;Check that "nheader" and "nlines_in" are numbers of the correct type, and reset their
;values if they are out of range.

;Determine if the ASCII file exists. If the ASCII file does not exist, then return without
;doing anything.

;Determine the number of lines in the ASCII file

;If the number of header lines to be skipped is greater than or equal to the number of
;lines in the ASCII file, then return without doing anything

;If the number of lines to be read in was specified as zero, then set it to the number of
;lines in the ASCII file minus the number of header lines to be skipped

;If the number of lines to be read in is greater than those in the ASCII file after the
;header lines, then set it to the maximum number of lines that can be read in

;Open the ASCII file

;Read in but ignore the first "nheader" lines

;Read in and store the remaining "nlines_out" lines

;Close the ASCII file

;After reading in the ASCII file successfully, set the value of "status" to "1"