;-------------------------------------------------------------
;+
; NAME:
;        CTM_DIAGINFO
;
; PURPOSE:
;        return information about one or all of the CTM diagnostics
;
; CATEGORY:
;        CTM tools
;
; CALLING SEQUENCE:
;        CTM_DIAGINFO, diagn, diagstru [,keywords]
;
; INPUTS:
;        DIAGN          -> diagnostic number or punch file category name for
;                          which to extract the information. If DIAGN is
;                          numeric, it is interpreted as the diagnostic number.
;                          If it is a string, it will be compared to CATEGORY.
;                          To retrieve information about all
;                          diagnostics, use the /ALL_DIAGS keyword.
;
; KEYWORD PARAMETERS:
;        /ALL_DIAGS     -> Retrieves information about all diagnostics.
;
;        CATEGORY       -> Returns to the calling program the punch
;                          file category name of the requested diagnostic(s)
;
;        FILENAME       -> Name of the diaginfo file (default diaginfo.dat)
;                          The file will be searched in the current
;                          directory first, then in the directory where 
;                          CTM_DIAGINFO.PRO is located.  If not found in
;                          either location, a standard data block is
;                          retrieved from this file.
;
;        /FORCE_READING -> Read from the diaginfo file (specified in
;                          FILENAME) and overwrite the contents of the
;                          common block.
;
;        INDEX          -> Returns to the calling program the number
;                          of the requested diagnostic(s)
;
;        MAXTRACER      -> Returns to the calling program the maximum
;                          number of tracers stored in the requested 
;                          diagnostic(s)
;
;        OFFSET         -> Returns to the calling program the offset
;                          constant that is used to locate tracers in
;                          the tracerinfo file.  This is needed to
;                          so that convert the "old" CTM tracer
;                          indices to the values as found in the
;                          tracerinfo file.  The tracerinfo file is
;                          read by CTM_TRACERINFO.DAT.
;
;        TYPE           -> Returns the type (J-L, I-J, I-L) of the 
;                          requested diagnostics.
;
; OUTPUTS:
;        DIAGSTRU -> returns a structure or structure array with the 
;                    following tags:
;               NDiag   : Diagnostic number
;               CatName : Punch file category name for this diagnostic
;               Type    : Diagnostic type (I-L, I-J, J-L)
;               MaxT    : Max # of tracers stored in this diagnostic
;               Offset  : Offset factor for tracerinfo file for this diagnostic
;
; SUBROUTINES:
;
; REQUIREMENTS:
;        uses file_exist, getdatablock, routine_name
;
; NOTES:
;        At first call, the tracer information structure array is
;        either read from file or retrieved from the
;        DATA block at the end of this program. Thereafter, the information
;        is stored in a common block where it is accessible in subsequent 
;        calls.
;
; EXAMPLE:
;        CTM_DIAGINFO, 46, res
;        print, res.index, ' ', res.category, ' ', res.type, res.maxtracer
;        ; prints    46 BIOGSRCE I-J       3
;
;        CTM_DIAGINFO,'BIOGSRCE' ,res
;        print, res.index, ' ', res.category, ' ', res.type, res.maxtracer
;        ; prints identical results
;
;        CTM_DIAGINFO,[1,3,5], ndiag=ndiag, category=category
;        print, ndiag, category
;        ; reads tracerinfo.dat file (or /DATA/ block) and prints 
;        ;      1       3       5
;        ; UVW-MEAN ZONE-AVG NRTH-SLP
;
;        CTM_DIAGINFO, /all, category=category
;        print, category
;        ;  prints    UVW-MEAN UVW-EXTR ZONE-AVG VERT-SLP ... etc
;
; MODIFICATION HISTORY:
;        bmy  19 May 1998  VERSION 1.00
;                  - developed from CTM_TRACERINFO.PRO v. 2.0 by
;                    Martin Schultz (08 May 1998)
;                    see comments to CTM_TRACERINFO.PRO for 
;                    modification history of that subroutine
;        bmy  20 May 1998
;                  - removed SCALE and UNIT structure tags & keywords
;                    added OFFSET structure tag & keyword
;        bmy  27 May 1998
;                  - changed "tracers" to "diagnostics" in print statement.
;        mgs  13 Aug 1998
;                  - now returns only first diagnostics for a given number
;                    This permits to keep old and new diagnostics in one file
;                    and use the old diagnostics by name.
;                  - introduced extra search one level above current dir.
;        mgs, 17 Aug 1998
;                  - changed defaults vor void return
;                  - diaginfo.dat: MAXTRACER meaning changed!
;
;-
; Copyright (C) 1998, Martin Schultz and Bob Yantosca
; Harvard University
; This software is provided as is without any warranty
; whatsoever. It may be freely used, copied or distributed
; for non-commercial purposes. This copyright notice must be
; kept with any copy of this software. If this software shall
; be used commercially or sold as part of a larger package,
; please contact the author to arrange payment.
; Bugs and comments should be directed to mgs@io.harvard.edu
; or "bmy@io.harvard.edu" with subject "IDL routine ctm_diaginfo"
;-------------------------------------------------------------


pro CTM_DiagInfo, DiagN, DiagStru,                                  $    
                  All_Diags=All_Diags, Category=Category,           $
                  FileName=FileName,   Force_Reading=Force_Reading, $
                  Index=Index,         MaxTracer=MaxTracer,         $
                  Offset=Offset,       Type=Type,                   $
                  _Extra=e

   ; set-up array of structures with diagnostic information
   ; index information referes to the current state of the diagnostics
 
   ; common block stores pointer to information for future calls
   common DiagCom, PDiagInfo
 
   ; sample structure for void return
   Sample = { DStru, $
              Index  : -1,    Category  : '',  $
              Type   : '',    MaxTracer : 0,   $
              Offset : 0 }

   ; Initialize pointer at first call
   if ( n_elements( PDiagInfo ) eq 0 ) then PDiagInfo = ptr_new()


   ; ============================================================  
   ; if datainfo contains no elements: 
   ; (1) read file datainfo.dat
   ;     (file is searched in current directory, then one level higher
   ;      and finally in directory of this procedure)
   ; (2) if no file datainfo.dat is found get information from
   ;     DATA block at the end of this program
   ; ============================================================  

   if ( keyword_set( Force_Reading ) OR  $
        not ptr_valid( PDiagInfo ) ) then begin
      
      if ( n_elements( FileName ) eq 0 ) then $ 
         FileName = 'diaginfo.dat'

      if ( not File_Exist( FileName, full=full ) ) then begin
         ; try it one level higher
         fpath = extract_path(FileName,filename=fname)
         TestFileName = fpath+'../'+fname
         if ( not File_Exist( TestFileName, full=full ) ) then begin
         
            ; find directory of this procedure
            dum = Routine_name( FileName=ProFileName )
            if ( File_Exist( ProFileName, path=!PATH, full=full) ) then begin
               FileName = Extract_Path( Full ) + extract_filename(FileName)
               if (not File_Exist( FileName, Full=Full)) then FileName = ''
            endif 
         endif
      endif
 
      if ( FileName eq '' ) then begin
         print,'CTM_DIAGINFO: could not find file diaginfo.dat '+ $
               'will use defaults from DATA block.'
 
         ; read DATA block from this file
         GetDataBlock, SData
      endif else begin
         ; read file diaginfo.dat as string array
         print,'reading ' + Full + ' ...'
         openr, ilun, Full, /get_lun
         Line = '#'
         while ( not EOF( Ilun ) AND strmid( Line, 0, 1 ) eq '#') do $
            readf, Ilun, Line
         
         SData = Line
         while ( not EOF( Ilun ) ) do begin
            readf, Ilun, Line

            ; Allow for blank lines or comment lines within the 
            ; diagnostics list section
            if ( strlen( Line ) ne 0 and strmid( Line, 0, 1 ) ne '#' ) $
               then Sdata = [ Sdata, Line ]
         endwhile
         free_lun, Ilun
      endelse
 
      ; extract data from string array sdata   
      if ( SData(0) eq ''  ) then begin
         stop, '** CTM_DIAGINFO: Could not retrieve diagnostic information !'
      endif
 
      DiagStru = replicate( Sample, n_elements( SData ) )
 
      for I = 0, n_elements( SData ) - 1 do begin
         Index     = 0
         Category  = ''
         Type      = ''
         MaxTracer = 0
         Offset    = 0

         ; parse string - all fields are mandatory!
         reads, SData(I), Index, Category, Type, MaxTracer, Offset, $
            format = '(I7, A8, A5, I5, I5)'

         DiagStru(i).Index     = Index      
         DiagStru(i).Category  = strtrim( Category, 2 )          
         DiagStru(i).Type      = strtrim( Type, 2 )
         DiagStru(i).MaxTracer = MaxTracer 
         DiagStru(i).Offset    = Offset
      endfor
 
      print,'retrieved information about ', $
         n_elements( DiagStru ),' diagnostics.'

      ; store as pointer (delete old one)
      if ( ptr_valid( PDiagInfo ) ) then ptr_free, PDiagInfo

      PDiagInfo = ptr_new( DiagStru, /no_copy )
   endif
     

   ; ============================================================  
   ; now process specific user request
   ; ============================================================  

   ; if output is desired for all diagnostic, do it here
   if ( keyword_set( All_Diags ) ) then begin
      DiagStru  = *PDiagInfo
      Index     = DiagStru(*).Index
      Category  = DiagStru(*).Category
      Type      = DiagStru(*).Type
      MaxTracer = DiagStru(*).MaxTracer
      Offset    = DiagStru(*).Offset
      return
   endif

   ; initialize return values for no valid diagnostic
   DiagStru  = Sample 
   Index     = -1
   Category  = ''
   Type      = ''
   MaxTracer = 0
   Offset    = 0

   Ind       = -1
 
   if ( n_elements( DiagN ) eq 0 ) then return ; nothing requested

   ; check if DIAGN is numeric (i.e. index) or string (i.e. name)
   S = size( DiagN )
   S = S[ n_elements( S ) - 2 ]

   if ( S eq 6 OR S gt 7 ) then return ; invalid argument type

   ; loop through all DIAGN arguments and try to find them
   for I = 0, n_elements( DiagN ) - 1 do begin
      
      if ( S eq 7 ) then begin    ; Diagnostic identified by CATEGORY
         
         Tind = where( strupcase( ( *PDiagInfo ).Category ) eq $
                       strupcase( DiagN[i] ) ) 

      endif else begin            ; Diagnostic identified by INDEX

         Tind = where( ( *PDiagInfo ).Index eq fix( DiagN[i] ) )

      endelse
      
      Ind = [ Ind, Tind[0] ]
   endfor

   Ind = temporary( Ind[1:*] )    ; remove dummy
      
   DiagStru = replicate( sample, n_elements( Ind ) )

   ; found desired Diagnostics 
   Tind = where( Ind ge 0 )

   ; return information for each requested Diagnostic
   if ( Tind(0) ge 0 ) then begin
      DiagStru[tind] = ( *PDiagInfo ) [ Ind[Tind] ]

      Index     = DiagStru[*].Index
      Category  = DiagStru[*].Category
      Type      = DiagStru[*].Type
      MaxTracer = DiagStru[*].MaxTracer
      Offset    = DiagStru[*].Offset
   endif

   ; strip array dimensioning if only one Diagnostic requested
   if ( n_elements( Ind ) eq 1 ) then begin

      ; DiagStru = DiagStru[0]
      Index     = Index[0]
      Category  = Category[0]
      Type      = Type[0]
      MaxTracer = MaxTracer[0]
      Offset    = Offset[0]
   endif
      
   return
end
 
 
; ========================================================
; /DATA/ BLOCK (DEFAULT VALUES FOR TRACERINFO)
; 01     UVW-MEAN  J-L    3  500
; 02     UVW-EXTR  J-L    3  600 
; 03     ZONE-AVG  J-L   24    0 
; 04     VERT-SLP  J-L   24    0 
; 05     NRTH-SLP  J-L   24    0 
; 06     WET CONV  J-L   24    0 
; 07     DRY CONV  J-L   24    0 
; 08     PROD-AVG  J-L   24    0
; 09     LOSS-AVG  J-L   24    0
; 10     NRTH-TOT  J-L   24    0
; 11     NRTH-EDD  J-L   24    0
; 12     NRTH-DFF  J-L   24    0
; 13     VERT-TOT  J-L   24    0
; 14     VERT-DFF  J-L   24    0
; 15     ID15-AVG  J-L   24    0
; 16     ID16-AVG  J-L   24    0
; 17     ID17-AVG  J-L   24    0
; 18     ID18-FLX  J-L   24    0
; 19     ID19-FLX  J-L   24    0
; 22     JV-MAP-$  I-J   14    0
; 23     CH3CCl3   I-J    1    0
; 24     EW-FLX-$  I-J   24    0
; 25     NS-FLX-$  I-J   24    0
; 26     UP-FLX-$  I-J   24    0
; 27     STRT-FLX  I-J    3    0
; 28     BIOBSRCE  I-J    6  100
; 29     CO--SRCE  I-J    3  100
; 30     LANDMAP   I-J    1  700
; 31     PRESS-AV  I-J    1  800
; 32     NOX-SRCE  I-J   39  100
; 33     TROPO-AV  I-J   24    0
; 34     SRF-AVRG  I-J   25    0
; 35     500-AVRG  I-J   24    0
; 36     ANTHSRCE  I-J    7  100
; 37     CHEMS -L  I-J   24    0
; 38     RAIN  -L  I-J   24    0 
; 39     INST-L=$  I-J   24    0
; 40     TOT-INST  I-J   24    0
; 41     FLUX-L=$  I-J   24  100
; 42     FLUX-L=$  I-J   24  100  
; 43     CHEM-L=$  I-J    5  900
; 44     DRYDEP-D  I-J   52 1000
; 45     IJ-AVG-$  I-J   25    0
; 46     BIOGSRCE  I-J    3  100
; 48     TIME-SER none   24 1100
; 50     EQSM-FLX  I-L   24  100
; 51     JD51-FLX  I-L   24  100  
; 52     JD52-FLX  I-L   24  100  
; 53     JD53-AVG  I-L   24    0  
; 54     JD54-AVG  I-L   24    0
; 55     MERI-AVG  I-L   24    0
; 67     A3--FLDS  I-J   15 1200