;------------------------------------------------------------------------------
; NAME: OBTAIN [subroutine to GET_VIABLE]
;
; PURPOSE: To select viable objects from a list of objects
;
; CALLING SEQUENCE: Result = OBTAIN (param, objarray, objcount, objindex)
;
; INPUTS:
;    Param: the object parameter to search for
;    Objarray: the list of object names
;    Objcount: the number of objects in objarray
;    Objindex: the index of where the objects are in the label
; OUTPUTS
;    Result: a structure of viable objarray, objcount, and objindex.
;
; OPTIONAL INPUT: none
;
; PROCEDURES USED: none
;
; MODIFICATION HISTORY:
;     14 February, 2003, P. Khetarpal: Program written
;------------------------------------------------------------------------------ 

function OBTAIN, param, objarray, objcount, objindex
   ; error protection
   On_error, 2

   length = strlen(param)
   struct = {object_struct, array: strarr(10), count: 0, index: lonarr(10)}

   index = 0
   if NOT(param EQ 'ALL') then begin
      for i = 0, objcount-1 do begin
         pos = strpos (objarray[i], param)
         len = strlen (objarray[i])
         if (pos GT -1) AND (abs(len-pos) EQ length) then begin
            struct.count = struct.count + 1
            struct.array[index] = objarray[i]
            struct.index[index] = objindex[i]
            index = index + 1
         endif
      endfor
   endif else if (param EQ 'ALL') then begin
      name_arr = ['ARRAY','COLLECTION','TABLE','SERIES','PALETTE',$
                  'SPECTRUM','IMAGE','QUBE','WINDOW']

      temparray = ''
      tempcount = 0
      tempindex = ''

      for i = 0, 8 do begin
         temp = OBTAIN (name_arr[i], objarray, objcount, objindex)
         if temp.count NE 0 then begin
            temparray = [temparray,temp.array]
            tempcount = tempcount+temp.count
            tempindex = [tempindex,temp.index]
         endif
      endfor
      struct.array[0:tempcount-1] = temparray[1:tempcount]
      struct.count = tempcount
      struct.index[0:tempcount-1] = tempindex[1:tempcount]
   endif

   fcount = struct.count
   if fcount GT 1 then begin
      farray = struct.array[0:fcount-1]
      findex = struct.index[0:fcount-1]
   endif else if struct.count EQ 1 then begin
      farray = struct.array[0]
      findex = struct.index[0]
   endif else begin
      farray = ''
      findex = 0
   endelse
   
   final = {array: farray, count: fcount, index: findex}

   return, final
end

;------------------------------------------------------------------------------
; NAME: GET_VIABLE
;
; PURPOSE: To obtain viable data objects from a PDS label
;
; CALLING SEQUENCE: Result = GET_VIABLE (label, param)
;
; INPUTS:
;    Label: String array containing object header information
;    Param: The object parameter to search for
; OUTPUTS:
;    Result: A structure containing the viable object names, object count, 
;            and the object indicies.
;
; OPTIONAL INPUT: none
;
; EXAMPLES:
;    To obtain all image objects:
;       IDL> label = HEADPDS ('TEST.LBL')
;       IDL> objects = GET_VIABLE (label, 'IMAGE')
;       IDL> help, /STRUCTURE, objects
;            ARRAY         STRING        ARRAY[1]
;            COUNT           INT                1
;            INDEX          LONG         ARRAY[1]
;    To obtain all viable objects:
;       IDL> label = HEAPDS ('TEST.LBL')
;       IDL> objects = GET_VIABLE (label, 'ALL')
;       IDL> help, /STRUCTURE, objects
;            ARRAY         STRING        ARRAY[3]
;            COUNT           INT               3
;            INDEX          LONG         ARRAY[3]
;
; PROCEDURES USED:
;    Functions: PDSPAR, CLEAN, OBTAIN [subroutine]
;
; MODIFICATION HISTORY:
;    14 February, 2003, P. Khetarpal: Program written
;------------------------------------------------------------------------------

function GET_VIABLE, label, param
   ; error protection
   On_error, 2

   objarray = PDSPAR (label,'OBJECT',COUNT=objcount,INDEX=objindex) 
   if !ERR EQ -1 then message, $
      'ERROR: file missing required OBJECT keyword.'

   ; clean the array:
   for i = 0, objcount-1 do begin
      objarray[i] = CLEAN (objarray[i], /SPACE)
      objarray[i] = strupcase (objarray[i])
   endfor

   ; process the array:
   param = strupcase (param)

   objects = OBTAIN (param,objarray,objcount,objindex)

   return, objects
end