Identifier   wave_form

 Purpose      convert the wavelength data in an aar to new units

 Synopsis     outaar = wave_form(inaar, unit [,inunit=inunit][,stat=stat]) 

 Arguments    Name   I/O  Type:     Description:
              -------------------------------------------------------------
              inaar   I   AAR       structure with input wavelength
              unit    I   string    output wavelength unit 
                                    (e.g. 'um', 'hz', 'cm') 
              inunit  I   string    optional input unit: If there is no
                                    specification of the input unit in the
                                    header of inaar (i.e. no TUNIT3), the 
                                    default unit 'um' is normally assumed. 
                                    Inunit will overwrite this default value.
              stat   I/O  int       error status, 0 if ok, 1 if fatal

 Returns      aar with wavelength data converted to new units
 
 Description  Routine reads the input wavelength unit from inaar header.
              If absent from header, the default unit 'um' is used (unless
              inunit is given).
              The desired output wavelength unit is specified by giving an
              ASCII string. 
              Checks whether input/output units are one of the allowed set.
              The wavelength unit can be one of the following:
              ['m','cm','um','a','hz','cm^-1'] where a = Angstrom.
              The routine looks up the correct conversion from input to
              output units from a matrix of short conversion algorithms and
              converts the data to the desired units.
              The new units are written into the FITS header keyword of the
              output aar. 

 Comment      ---

 Example      outarr = wave_form(saar, 'hz')
              converts the wavelength scale from the input unit (e.g. um) to
              hz

 Dependencies  CALLS: get_hdrkey, sap_error, sap_keyword_set,
                      update_history, write_hdrkey
               CALLED FROM: GUI, IA

 Category     ISAP

 Filename     wave_form.pro
 
 Author       E. Sturm (ES)

 Version      1.3

 History      definition of requirements - 27.7.95  D. Rigopoulou/E.Wieprecht
              0.1  06-10-95    ES  first version, based on routines from
                                   Iffat Khan (IPAC)
              0.2  24-11-95    ES  corrected conversion hz <--> cm^-1
              1.0  30-11-95    ES  V1 delivery
              1.1  04-01-96    ES  New call to write_fits_key
                   29-01-96    ES  replace read_fits_key with get_hdrkey,
                                   write_fits_key with write_hdrkey
              1.2  10-07-96    ES  stat added
              1.3  16-07-96    ES  treat 'microns' as 'um'
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Copyright (C) 1995, Max-Planck-Institut fuer extraterrestrische Physik (MPE);
                    Garching, Germany                                       ;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;