;------------------------------------------------------------------------------
; NAME: HEADPDS
;
; PURPOSE: To read a PDS label into an array variable
;
; CALLING SEQUENCE: Result = HEADPDS (filename [,/SILENT,/FILE])
;
; INPUTS:
;    Filename: Scalar string containing the name of the PDS file to read
; OUTPUTS:
;    Result: PDS label array constructed from designated record
;
; OPTIONAL INPUT:
;    SILENT: suppresses any messages from the procedure
;    FILE: to be indicated if the file does not contain the label
;          [for purposes other than reading a label]
;
; EXAMPLES:
;    To read a PDS file TEST.PDS into a PDS header array, lbl:
;       IDL> lbl = HEADPDS('TEST.PDS',/SILENT)
;    To read a PDS file that may not contain a header:
;       IDL> lbl = HEADPDS('TEST2.TXT',/FILE)
;
; PROCEDURES USED:
;    Functions: POINTPDS, PDSPAR, CLEAN
;
; MODIFICATION HISTORY:
;    Written by Puneet Khetarpal, January 24, 2003
;------------------------------------------------------------------------------

function HEADPDS, filename, SILENT=silent, FILE=file
   ; error protection:
   On_error, 2
   On_ioerror, SIGNAL

   ; check for correct number of inputs:
   params = N_params()
   if (params[0] LT 1) then begin
      print, 'Syntax - result = HEADPDS ( filename [,/SILENT,/FILE] )'
      return, -1
   endif

   silent = keyword_set (SILENT)
   file = keyword_set (FILE)

   ; check whether the file exists and can be opened:
   openr, unit, filename, ERROR = err, /GET_LUN
   if err LT 0 then begin
      print, 'Error opening file ' + filename
      return, -1
   endif

   ; check for correct PDS label file:
   if NOT (FILE) then begin
      temp = bytarr(160)   
      readu, unit, temp
      if strpos(string(temp), 'PDS_VERSION_ID') LT 0 AND $
         strpos(string(temp), 'SFDU_LABEL') LT 0 then begin
         print, 'ERROR: label must contain PDS_VERSION_ID keyword'
         return, -1
      endif
   endif
   
   ; determine if detached label or not:
   if strpos(strlowcase(filename),'.l') GT -1 then begin
      detach_flag = 1
      status = fstat(unit)
      nbytes = status.size
      lines = nbytes/80
      if (nbytes MOD 80) NE 0 then begin
         print, 'Invalid record length - record length must be 80 bytes'
         detach_flag = -1
      endif else GOTO, READ_HEADER
   endif else detach_flag = -1

   ; read the file:
   READ_HEADER:
   lbl = ''
   if NOT (SILENT) then begin
      print, "Now reading header: ", filename
   endif
   point_lun, unit, 0
   readf, unit, lbl
   flag = 0
   while (flag NE -1) AND NOT(EOF(unit)) do begin
      ln = ''
      readf, unit, ln
      ln = ln+string(10b)+string(13b)
      lbl = [lbl,ln]
      ln2 = CLEAN(ln,/SPACE)
      if (ln2 EQ 'END') then flag = -1
   endwhile

   close, unit
   free_lun, unit

   if detach_flag EQ -1 then begin
      lines = n_elements(lbl)
      for i = 0, lines-1 do begin
         length = 78 - (strlen(lbl[i])-2)
         str = ''
         for j = 0, length-1 do str = str + ' '
         temp = strmid (lbl[i],0,strlen(lbl[i])-2)
         lbl[i] = temp+str+string(10b)+string(13b)
      endfor
   endif

   struct = PDSPAR (lbl, '^STRUCTURE')
   if !ERR NE -1 then begin
      pointer = POINTPDS (lbl,filename,'STRUCTURE')
      datafile = pointer.datafile
      fmtlabel = headpds (datafile,/FILE)
      lbl = [lbl, fmtlabel]
   endif

   return, lbl

   ; error processing:
   SIGNAL: 
      On_ioerror, NULL
      print, 'ERROR reading file'
      return, -1
end