;+
; @file_comments
;
;
; @categories
;
;
; @param FILENAME
; The file's name
; 
; @keyword NODATA
;
;
; @keyword NOATTRIBUTES
; 
;
; @returns
;
;
; @restrictions
;
;
; @examples
; 
; 
; @history
;
;
; @version
; $Id$
;
;-
FUNCTION ncdf_struct,filename,nodata=nodata,noattributes=noattributes
;
; Read entire netcdf file into a structure.
;
; (Structure contains metadata; actual array contents are on heap, with
; pointers contained in the structure.  Heap variables not created if
; "nodata" specified.)
;
; Use ncdf_struct_free to free heap memory.
;
; (Some data is duplicated for ease of access, in particular if there is
; a variable name matching a dimension name, then a pointer to the variable
; contents is accessible via the substructures corresponding to the dimension
; and every other variable that uses it.)
;
; Alan Iwi 27/6/02
;
;
  compile_opt idl2, strictarrsubs
;

id=ncdf_open(filename)

g=ncdf_inquire(id)
ndim=g.ndims
nvar=g.nvars
natt=g.ngatts

if ndim gt 0 then begin
    dnames=strarr(ndim)
    dsizes=lonarr(ndim)
    for idim=0,ndim-1 do begin
        ncdf_diminq,id,idim,dname,dsize
        dnames[idim]=dname
        dsizes[idim]=dsize
    endfor
endif

if natt gt 0 and not keyword_set(noattributes) then begin
    anames=strarr(natt)
    for iatt=0,natt-1 do begin
        aname=ncdf_attname(id,/global,iatt)
        ainq=ncdf_attinq(id,/global,aname)
        ncdf_attget,id,/global,aname,aval
        if (ainq.datatype eq 'CHAR') then aval=string(aval)
        if iatt eq 0 then begin
            atts=create_struct(aname,aval)
        endif else begin
            atts=create_struct(atts,aname,aval)
        endelse
        anames[iatt]=aname
    endfor
    g=create_struct(g,'gatts',atts,'gattnames',anames)
endif

if nvar gt 0 then begin
    vnames=strarr(nvar)
    for ivar=0,nvar-1 do begin
        v=ncdf_varinq(id,ivar)
        
        vname=v.name
        vndim=v.ndims
        vnatt=v.natts
        vname=v.name
        
        if vnatt gt 0 and not keyword_set(noattributes) then begin
            vanames=strarr(vnatt)
            for iatt=0,vnatt-1 do begin
                aname=ncdf_attname(id,ivar,iatt)
                ainq=ncdf_attinq(id,ivar,aname)
                ncdf_attget,id,ivar,aname,aval
                if (ainq.datatype eq 'CHAR') then aval=string(aval)
                if iatt eq 0 then begin
                    atts=create_struct(aname,aval)
                endif else begin
                    atts=create_struct(atts,aname,aval)
                endelse
                vanames[iatt]=aname
            endfor
            v=create_struct(v,'atts',atts,'attnames',anames)
        endif
        
        vdnames=dnames[v.dim]
        vdsizes=dsizes[v.dim]
        v=create_struct(v,'dimnames',vdnames,'dimsizes',vdsizes)
        
        if not keyword_set(nodata) then begin
            ncdf_varget,id,ivar,vdata
            v=create_struct(v,'data',ptr_new(vdata), $
                            'dimdata',replicate(ptr_new(),vndim))
        endif
        
        if ivar eq 0 then begin
            vars=create_struct(vname,v)
        endif else begin
            vars=create_struct(vars,vname,v)
        endelse
        
        vnames[ivar]=vname    
    endfor
endif

if ndim gt 0 then begin
    for idim=0,ndim-1 do begin
        dname=dnames[idim]
        d={name:dname,size:dsizes[idim]}
        
        if not keyword_set(nodata) and nvar gt 0 then begin
            matchvar=-1
            for ivar=0,nvar-1 do begin
                if vnames[ivar] eq dname then matchvar=ivar
            endfor
            if matchvar ne -1 then  $
              d=create_struct(d,'data',vars.(matchvar).data)
        endif
        
        if idim eq 0 then begin
            dims=create_struct(dname,d)
        endif else begin
            dims=create_struct(dims,dname,d)
        endelse
        
    endfor
    g=create_struct(g,'dims',dims,'dimnames',dnames,'dimsizes',dsizes)
endif

if nvar gt 0 then begin
    if not keyword_set(nodata) then begin
        for ivar=0,nvar-1 do begin
            for idim=0,vars.(ivar).ndims-1 do begin
                vars.(ivar).dimdata[idim]=dims.(vars.(ivar).dim[idim]).data
            endfor
        endfor
    endif
    g=create_struct(g,'vars',vars,'varnames',vnames)
endif
    

ncdf_close,id

return,g

end