;   $Id: df_make_name.pro,v 1.17 2014/01/27 14:14:15 nash Exp $

function  df_make_name,quantity,source,date,avespec=avespec,fin=fin, $
          forecast=forecast,format=format,fout=fout,gridspec=grid, $
          nowarn=nowarn,sequence=sequence,special=special,time=time
;+
; NAME:  
;   df_make_name
; PURPOSE:
;   Creates a df file name from keywords or a df file structure.
; CATEGORY: 
;   df
; CALLING SEQUENCE:
;   filename = df_make_fname(quantity,source,date)
;   filename = df_make_fname(fin=fin)
; FUNCTION RETURN VALUE:
;   string:scalar
;    returns the file name
; INPUT PARAMETERS:
; OPTIONAL INPUT PARAMETERS:
;   quantity = (any) quantity code.
;              This or the fin field must be specified. Overrides the fin field.
;   source   = (any) source code.
;              This or the fin field must be specified. Overrides the fin field.
;   date     = (any) date in any form. This is NOT checked (except to remove
;              blanks), so be sure you pass the date exactly as you wish.
;              This or the fin field must be specified. Overrides the fin field.
; INPUT/OUTPUT PARAMETERS:
; OPTIONAL INPUT/OUTPUT PARAMETERS:
; OUTPUT PARAMETERS:
; OPTIONAL OUTPUT PARAMETERS:
; INPUT KEYWORDS:
;   avespec  = (char) character code in the file name representing the
;              time averaging of data in the file. Overrides the fin field.
;              Default is "I" for instantaneous.
;   fin      = (structure: df_file_struct) input file structure to copy to the
;              output structure. Contains the following fields:
;       quantity = (string) 4-character quantity code.
;                    This or the parameter quantity must be specified.
;       avespec  = (char) character code in the file name representing the
;                    time averaging of data in the file.
;                    Default is "I" for instantaneous.
;       date     = (string) date in the format "YYMMDDHH" or "YYMMDD"
;                    This or the parameter date must be specified.
;       grid     = (string) grid code.
;                    Default is no gridding.
;       forecast = (string) forecast time string.
;                    Default is no forecast.
;       sequence = (string) sequence code string.
;                    Default is no sequence field.
;       format   = (string) format code string.
;                    Default is 'X' for xdr format.
;       special  = (string) special code string.
;                    Default is no special field.
;       time     = (string) time string in form "MMMMSS".
;                    Default is no time field.
;       source   = (string) 3-character source code.
;                    This or the paramater source must be specified.
;   forecast = (any) forecast time. "F" will be prepended if not specified. 
;              "FH" will be prepended if no format is specified.
;              Default is no forecast. Overrides the fin field.
;   format   = (string) format code string. "X" will be prepended if not 
;              specified.
;              Default is 'X' for xdr format. Overrides the fin field.
;   gridspec = (string) grid code. "G" will be prepended if not specified. 
;              Default is no gridding. Overrides the fin field.
;   nowarn =   (flag) Set this keyword to suppress the warning message if the 
;              quantity is not found.
;   sequence = (any) sequence code string. "E" will be prepended if not 
;              specified. 
;              Default is no sequence field. Overrides the fin field.
;   special  = (string) special code string. "S" will be prepended if not 
;              specified. 
;              Default is no special field. Overrides the fin field.
;   time     = (any) time in form "MMMMSS". "T" will be prepended if not 
;              specified. 
;              Default is no time field. Overrides the fin field.
; INPUT/OUTPUT KEYWORDS:
; OUTPUT KEYWORDS:
;   fout = (structure: df_file_struct) output file structure with all fields
;          filled in. Contains the following fields:
;       quantity = (string) 4-character quantity code.
;       avespec  = (char) character code in the file name representing the
;                    time averaging of data in the file.
;       date     = (string) date in the format "YYMMDDHH" or "YYMMDD"
;       grid     = (string) grid code.
;       forecast = (string) forecast time string.
;       sequence = (string) sequence code string.
;       format   = (string) format code string.
;       special  = (string) special code string.
;       time     = (string) time string in form "MMMMSS".
;       source   = (string) 3-character source code.
; COMMON BLOCKS:
; REQUIRED ROUTINES:
;   convert_date, dfhead, df_site_dep, df_trans_source, df_trans_var
; @ FILES:
; RESTRICTIONS:
;   quantity, date, and source must be specified in some form.
; SIDE EFFECTS:
; DIAGNOSTIC INFORMATION:
; PROCEDURE:
; EXAMPLES:
; REFERENCE:
; FURTHER INFORMATION:
; RELATED FUNCTIONS AND PROCEDURES:
; MODIFICATION HISTORY:
;   $Log: df_make_name.pro,v $
;   Revision 1.17  2014/01/27 14:14:15  nash
;   added NOWARN keyword flag
;
;   1991-05-01:nash:wrote
;   1991-05-09:lrlait:modified
;   1991-05-23:nash:changed n_elements to keyword_set
;   1991-06-20:newman:added sequence correction so that 'E' will
;              not be prefixed to a sequence string that begins with 'E'
;   1991-06-20:nash:fixed newman's addition to be within IF loop.
;   1991-07-01:lrlait:added the special keyword
;   1996-02-17:nash:total rewrite to add df_file_struct
;   1996-02-25:nash:added test of forecast for '0'
;   1996-02-25:nash:temporarily turned off the check for the source name
;   1996-02-29:nash:make sure that no whitespace gets into output file name
;   1999-11-15:nash:date input can be in any form
;   1999-11-17:nash:date is specified exactly as provided
;   2002-03-12:nash:rewrote to be sure that input keywords are NOT set
;                   restored the check for the source name
;   2002-03-12:nash:removed the check for the source name again. It looks like
;                   not all source names are included where they should be
;   2002-03-14:nash:added strupcase to all 
;-

; *****local delimiters
  df_site_dep,delims=delims
  delim0 = delims[0]
  delim1 = delims[1]
  delims = 0

; *****start with output same as input
  if  (n_elements(fin) ne 0)  then  fout = fin $
  else  begin
    dfhead
    fout = {DF_FILE_STRUCT}
  endelse

; *****quantity
  if  (n_elements(quantity) ne 0)  then  fout.quantity = quantity
  if  (size(fout.quantity,/type) ne 7)  then $
    df_trans_var,num=fout.quantity,short=fout.quantity,err=res,direct=0 $
  else  begin
    fout.quantity = strmid(strupcase(strcompress(fout.quantity,/rem))+ $
      delim1+delim1+delim1+delim1,0,4)
    df_trans_var,short=fout.quantity,err=res,direct=1
  endelse
  if  (res eq 1)  then  begin
    if  (~keyword_set(nowarn))  then $
      message,/cont,'Unknown quantity type: '+strcompress(fout.quantity,/rem)
    return,''
  endif

; *****avespec
  if  (n_elements(avespec) ne 0)  then  fout.avespec = avespec
  if  (fout.avespec eq '')  then  fout.avespec = 'I' $
  else  fout.avespec = strupcase(strmid(fout.avespec,0,1))

; *****date
  if  (n_elements(date) ne 0)  then  fout.date = date
  fout.date = strupcase(strcompress(fout.date,/rem))
  if  (fout.date eq '')  then  begin
    message,/cont,'Date must be specified.'
    return,''
  endif

; *****first part of file name
  fname = fout.quantity+fout.avespec+fout.date

; *****grid
  if  (n_elements(grid) ne 0)  then  fout.grid = grid
  if  (fout.grid ne '')  then  begin
    fout.grid = strupcase(strcompress(fout.grid,/rem))
    if  (strmid(fout.grid,0,1) ne 'G')  then  fout.grid = 'G'+fout.grid
    fname = temporary(fname)+delim1+fout.grid
  endif

; *****forecast
  if  (n_elements(forecast) ne 0)  then $
    fout.forecast = strcompress(forecast,/rem)
  if  ((fout.forecast ne '') and  (fout.forecast ne '0')) then  begin
    fout.forecast = strupcase(fout.forecast)
    stype = strmid(fout.forecast,0,1)
    if  (stype eq 'F')  then  begin
      fout.forecast = strmid(fout.forecast,1,100)
      stype = strmid(fout.forecast,0,1)
    endif
    if  ((where(['0','1','2','3','4','5','6','7','8','9'] eq stype))[0] ne -1) $
      then  fout.forecast = 'H'+fout.forecast
    fout.forecast = 'F'+fout.forecast
    fname = temporary(fname)+delim1+fout.forecast
  endif

; *****format
  if  (n_elements(format) ne 0)  then  fout.format = format
  if  (fout.format eq '')  then  fout.format = 'X' $
  else  begin
    fout.format = strupcase(strcompress(fout.format,/rem))
    if  (strmid(fout.format,0,1) ne 'X')  then  fout.format = 'X'+fout.format
  endelse
  fname = temporary(fname)+delim1+fout.format

; *****sequence
  if  (n_elements(sequence) ne 0)  then  fout.sequence = sequence
  if  (fout.sequence ne '')  then  begin
    fout.sequence = strupcase(strcompress(fout.sequence,/rem))
    if (strmid(fout.sequence,0,1) ne 'E')  then $
      fout.sequence = 'E'+fout.sequence
    fname = temporary(fname)+delim1+fout.sequence
  endif

; *****special
  if  (n_elements(special) ne 0)  then  fout.special = special
  if  (fout.special ne '')  then  begin
    fout.special = strupcase(strcompress(fout.special,/rem))
    if (strmid(fout.special,0,1) ne 'S')  then  fout.special = 'S'+fout.special
    fname = temporary(fname)+delim1+fout.special
  endif

; *****time
  if  (n_elements(time) ne 0)  then  fout.time = time
  if  (fout.time ne '')  then  begin
    fout.time = strupcase(strcompress(fout.time,/rem))
    if (strmid(fout.time,0,1) ne 'T')  then  fout.time = 'T'+fout.time
    fname = temporary(fname)+delim1+fout.time
  endif

; *****source
  if  (n_elements(source) ne 0)  then  fout.source = source
  if  (fout.source eq '')  then  begin
    message,/cont,'Source must be specified.'
    return,''
  endif
  if  (size(fout.source,/type) ne 7)  then $
    df_trans_source,num=fout.source,short=fout.source,err=res,direct=0 $
  else  begin
    fout.source = strupcase(strmid(fout.source,0,3))
;    df_trans_source,short=fout.source,err=res,direct=1
  endelse
  if  (res eq 1)  then  begin
    message,/cont,'Unknown source: '+fout.source
    return,''
  endif
  fname = temporary(fname)+delim0+fout.source

  return,fname
end