function [fileinfo, return_status] = nc_info ( ncfile )
% NC_INFO:  information about a NetCDF 2 or 3 file
%
% USAGE:  fileinfo = nc_info ( ncfile );
%
% PARAMETERS:
% Input:
%    ncfile:  
%        a string that specifies the name of the NetCDF file
% Output:
%    fileinfo:
%        A structure whose fields contain information about the contants
%        of the NetCDF file.  The set of fields return in "fileinfo" are:
%
%        Filename:  
%            a string containing the name of the file.
%        Dimension:  
%            an array of structures describing the NetCDF dimensions.
%        DataSet:  
%            an array of structures describing the NetCDF datasets.
%        Attributes:  
%            An array of structures These correspond to the global attributes.
%
%
%        Each "Dimension" element contains the following fields:
%       
%        Name:
%            a string containing the name of the dimension.
%        Length:
%            a scalar value, the size of this dimension
%        Record_Dimension:
%            Set to 1 if the dimension is the record dimension, set to
%            0 otherwise.
%
%
%        Each "DataSet" element contains the following structures.
%
%        Name:  
%            a string containing the name of the variable.
%        Nctype:  
%            a string specifying the NetCDF datatype of this variable.
%        Varid:  
%            a scalar specifying the NetCDF variable id (varid)
%        Dimensions:  
%            a cell array with the names of the dimensions upon which
%            this variable depends.
%        Rank:  
%            Array that describes the size of each dimension upon which 
%            this dataset depends.
%        DataAttributes:  
%            Same as "Attributes" above, but here they are the variable 
%            attributes.
%                         
%        Each "Attribute" or "DataAttribute" element contains the following 
%        fields.
%
%        Name:  
%            a string containing the name of the attribute.
%        Nctype:  
%            a string specifying the NetCDF datatype of this attribute.
%        Attnum:  
%            a scalar specifying the attribute id
%        Value: 
%            either a string or a double precision value corresponding to
%            the value of the attribute
%
%     return_status:
%        -1 in case of failure, 0 if successful
%
% The "DataSet" elements are not populated with the actual data values.
%
% This routine purposefully mimics that of Mathwork's hdfinfo.
%
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% $Name:  $
% $Id: nc_info.m,v 1.1 2005/06/29 16:07:00 brian Exp $
% AUTHOR:  johnevans@acm.org
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%




%
% assume failure until success is known
return_status = -1;
fileinfo = [];


% Show usage if too few arguments.
%
if nargin<1 
   help nc_info;
   return;
end

fileinfo.Filename = ncfile;

%
% Open netCDF file
%
[ncid, status]=mexnc('open', ncfile, nc_nowrite_mode );
if status ~= 0
	fprintf ( 2, '%s:  mexnc:open failed on %s.\n', mfilename, ncfile );
	fileinfo = [];
	return
end

% Suppress warning messages from netCDF
[rcode]=mexnc('setopts',0);


[ndims, nvars, ngatts, record_dimension, status] = mexnc('INQ', ncid);
if status < 0
	fprintf ( 2, '%s:  mexnc:inq failed on %s.\n', mfilename, ncfile );
	mexnc('close',ncid);
    return
end


%
% retrieve the sizes of each dimension
if ndims == 0
	Dimension = struct ( [] );
else
	for dimid = 0:ndims-1
		Dimension(dimid+1)=nc_getdiminfo ( ncid, dimid );
	end
end

fileinfo.Dimension = Dimension;

if nvars == 0
	fileinfo.DataSet = struct([]);
else
	for varid=0:nvars-1
	
		[varname, datatype, ndims, dims, natts, status] = mexnc('VARINQ', ncid, varid);
		if status < 0 
			fprintf ( 2, '%s:  mexnc:varinq failed on varid %d, file %s.\n', mfilename, varid, ncfile );
			mexnc('close',ncid);
		end
	
		[fileinfo.DataSet(varid+1), status] = nc_getvarinfo ( ncid, varid );
		if status < 0 
			fprintf ( 2, '%s:  nc_getvarinfo failed on varid %d, file %s.\n', mfilename, varid, ncfile );
			mexnc('close',ncid);
		end
	
	
	end
end




%
% Do the same for the global attributes
%
% get all the attributes
varname = 'global';
global_atts = [];
if ngatts == 0
	fileinfo.Attribute = struct([]);
else
	for attnum = 0:ngatts-1
		Attribute(attnum+1) = nc_get_attribute_struct ( ncid, 'global', attnum );
	end
	fileinfo.Attribute = Attribute;
end

mexnc('close',ncid);




return_status = 0;

return


