; NAME: read_rcm_file
;   
; PURPOSE: reads rcm* output files (not rcmggcm* files)
;   
; Inputs:
;   file - path to data file
;   dims - number of data dimensions (USE KEYWORDS BELOW INSTEAD)
;            1 - f[phi]
;            2 - f[phi,theta] (default)
;            3 - f[phi,theta,lambda]
;
; Keywords:
;   theta  - if set, theta is a dimension of the variable
;   phi    - if set, phi is a dimension of the variable
;   lambda - if set, lambda (energy invariant) is a dimension of the variable
;
; Outputs:
;   data - array of structures containing data (data.itime, data.var)
;            (itime is in rcm simulation seconds)
;
; Notes:
;   See rcm_grid file for grid and energy channels
;   I'm pretty sure that this works - but use with caution! ;)
;
; Author:
;   W. Douglas Cramer
;
pro read_rcm_file, file, data, dims, $
  theta=theta, phi=phi, lambda=lambda, max_it=max_it

  if (n_elements(max_it) eq 0) then max_it=999999

  intg=lonarr(20)
  real=lonarr(20)
  name=bytarr(80)
  lsize=60

  fsize=(file_info(file)).size/4

  openr,fileid,file,/get_lun

  readu,fileid,intg
  irdw=intg[0]
  it=intg[5]
  ntheta=intg[7]
  nphi=intg[8]
  maxfl=intg[9]
  readu,fileid,real
  readu,fileid,name

  if (n_elements(dims) ne 0) then begin
    ndims=n_elements(dims)
    case (ndims) of
      1: var=fltarr(dims[0])
      2: var=fltarr(dims[0],dims[1])
      3: var=fltarr(dims[0],dims[1],dims[2])
      default: stop,'only up to three dimensions is allowed'
    endcase
  endif else begin
    if (keyword_set(theta)) then begin
      if (keyword_set(phi)) then begin
        if (keyword_set(lambda)) then begin
          var=fltarr(ntheta,nphi,maxfl)
        endif else begin
          var=fltarr(ntheta,nphi)
        endelse
      endif else begin
        if (keyword_set(lambda)) then begin
          var=fltarr(ntheta,maxfl)
        endif else begin
          var=fltarr(ntheta)
        endelse
      endelse
    endif else begin    
      if (keyword_set(phi)) then begin
        if (keyword_set(lambda)) then begin
          var=fltarr(nphi,maxfl)
        endif else begin
          var=fltarr(nphi)
        endelse
      endif else begin
        if (keyword_set(lambda)) then begin
          var=fltarr(maxfl)
        endif
      endelse
    endelse
  endelse

  if (n_elements(var) eq 0) then begin
    stop,'ERROR: specify dims OR theta, phi, and/or lambda'
  endif

  len=n_elements(var)
  ntime=fsize/(len+lsize)

  readu,fileid,var

  data_str={itime:it, var:var}
  data=replicate(data_str,ntime)
  data.itime=-1
  data[0].itime=it
  data[0].var=var

  for i=1,ntime-1 do begin
    readu,fileid,intg
    readu,fileid,real
    readu,fileid,name
    readu,fileid,var
    data[i].itime=intg[5]
    data[i].var=var
  
    if (intg[5] gt max_it) then break
  endfor

  if (n_elements(max_it) eq 1) then begin
    f=where(data.itime gt max_it)
    if (f[0] ne -1) then begin
      f=where(data.itime ge 0 and data.itime le max_it)
      if (f[0] ne -1) then data=data[f]
    endif
  endif

  close,fileid
  free_lun,fileid
end