Identifier     ascii2yaaar

 Purpose        Create an IDL structure from an ASCII table of 
                [wave, flux(, stdev)] of arbitrary units

 Synopsis       YAAAR = ascii2yaaar( filename, wunit, funit[, stdev=stdev]
                                     [, skip=skip][,stat=stat])

 Arguments      Name       I/O     Type     Description
                ----------------------------------------------------------
                filename    I      String   ASCII table filename
                wunit       I      String   Wavelength unit (e.g., 'um')
                funit       I      String   Flux unit (e.g., 'Jy')
                stdev       I      Switch   Flux standard deviation array, 
                                            assumed to be in units of funit
                skip        I      Switch   To skip lines for reading      
                stat       I/O     integer  error status; 1 if fatal, 0 if ok

 Returns        YAAAR IDL structure 

 Description    - Create an IDL structure from either 2 or 3 column
                  ASCII tables of [wave, flux(, stdev)] for manipulation
                  by IA and ISAP software.
 
 Comment        - Top structure of the output consists of AAR tags [type,
                  header, history, data].  The data record structure 
                  consists only of [wave, flux, stdev, flag], where flag
                  (required for the GUI) has been set to 0.  This
                  record structure is defined in DEFINE_YAAAR.
                - Input units are required, and are entered into the
                  header record.  ANY units may be input, but only
                  the units specified in the conversion routines WAVE_FORM
                  and SPECT_FORM can be later read out of the header and
                  converted.
                - Flux standard deviation values may be read from the
                  ASCII table, or input as an array at the command line.
                - RESTRICTIONS:  
                  Wavelength standard deviations are presently not allowed. 
                  Flux standard deviation units are hard-wired to funit.
                  No ASCII header text is read.

 Example        YAAAR = ascii2yaaar('HD90429.SED', 'um', 'Jy', /stdev)
                  Open the file HD90429.SED, read wave, flux, and flux 
                  standard deviation columns with units um, Jy, Jy.

                YAAAR = ascii2yaaar('HD5980.dat', 'A', 'erg/cm^2/s/A')
                  Open file HR5980.dat, read wave and flux columns in units 
                  of Angstroms (A) and erg/cm^2/s/A, and set the flux
                  standard deviations to constant value 1e-10.

                YAAAR = ascii2yaaar('HD50896.dat', 'um', 'Jy')
                sdarray = [sd1, sd2, ..., sdn]
                YAAAR.data.stdev = sdarray
                  Open file HD50896.dat, read wave and flux in the specified
                  units, and then reset the flux standard deviations = sdarray.
 
 Dependencies   CALLS: define_yaaar, makeyaaarhead, sap_error, 
                       sap_keyword_set, update_history, write_hdrkey
                CALLED FROM: GUI, IA

 Category       UTIL, I/O

 Filename       ascii2yaaar.pro

 Author         P. Morris 
                p.morris@sron.ruu.nl

 Version        1.4

 History        0.1 31-10-95  PM 
                0.2 02-11-95  ES modified read loop, minor changes
                0.3 22-11-95  ES added update_history (but inactive)
                0.4 24-11-95  PM modified units input to header for
                                 minimum necessary string length
                0.5 04-01-96  PM redefine stdev as a switch; if not set,
                                 stdev = 1e-10; activate update_history
                1.1 29-01-96  ES replaced write_fits_key with write_hdrkey 
                1.2 20-03-96  IRK include keyword "skip" to skip header lines
                                  (irk@ipac.caltech.edu)
                1.3 09-05-96  ES added wavelength sorting
                1.4 09-07-96  ES added error status
                    22-07-96  IRK corrected keyword "stat" into "errstat"