function Dimension = nc_getdiminfo ( arg1, arg2 )
% NC_GETDIMINFO:  returns metadata about a specific NetCDF dimension
%
% USAGE:  Dimension = nc_getdiminfo ( file_id, dim_id );
%
% PARAMETERS:
% Input:
%    file_id:  
%        either a string that specifies the name of the NetCDF file, or
%        the already opened NetCDF file id
%    dim_id:  
%        either a string that specifies the name of the NetCDF variable,
%        or the already accessed NetCDF variable id
%
%    If the filename and dimension name are given, then the file will
%    be closed upon either successful completion of the routine or also
%    in the case of an error.  If the NetCDF IDs are given, then the
%    file is not closed (the calling routine has to take care of that).
%
% Output:
%    Dimension:
%        A structure whose fields metadata about the NetCDF dimension.
%        The set of fields returned in Dimension are:
%
%        Name:  
%            a string containing the name of the dimension.
%        Length:  
%            a scalar equal to the length of the dimension
%        Dimid:  
%            a scalar specifying the NetCDF dimension id 
%        Record_Dimension:  
%            Flag, either 1 if the dimension is an unlimited dimension
%            or 0 if not.
%
% In case of an error, an exception is thrown.
%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% $Id: nc_getdiminfo.m 1870 2006-10-09 12:08:53Z johnevans007 $
% $LastChangedDate: 2006-10-09 08:08:53 -0400 (Mon, 09 Oct 2006) $
% $LastChangedRevision: 1870 $
% $LastChangedBy: johnevans007 $
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



%
% Check for proper inputs.
if nargin ~= 2
	error ( '%s:  two input arguments are required.\n', mfilename );
end


%
% If we are here, then we must have been given something local.
if ischar(arg1) & ischar(arg2)

	ncfile = arg1;
	dimname = arg2;


	%
	% Open netCDF file
	%
	[ncid,status ]=mexnc('open', ncfile, nc_nowrite_mode );
	if status ~= 0
		error ( '%s:  OPEN failed, ''%s''.\n', mfilename, mexnc('strerror', status) );
	end


	[dimid, status] = mexnc('INQ_DIMID', ncid, dimname);
	if ( status ~= 0 )
		mexnc('close',ncid);
		fmt = '%s:  INQ_DIMID failed on ''%s'', imension ''%s''.\n';
		error ( fmt, mfilename, dimname, mexnc('strerror',status) );
	end

	
	% 
	% Get the information.
	Dimension = get_diminfo ( ncid,  dimid );

	%
	% close whether or not we were successful.
	mexnc('close',ncid);


elseif isnumeric ( arg1 ) & isnumeric ( arg2 )

	ncid = arg1;
	dimid = arg2;

	%
	% Ok, we were passed the file id and variable id.
	Dimension = get_diminfo ( ncid,  dimid );


else
	fmt = '%s:  cannot have mixed input types.  Either specify the filename and dimension name, or give the NetCDF file id and dimid.\n';
	error ( fmt, mfilename );
end



return





function Dimension = get_diminfo ( ncid, dimid )


[unlimdim, status] = mexnc ( 'inq_unlimdim', ncid );
if status ~= 0
	mexnc('close',ncid);
	error ( '%s:  INQ_UNLIMDIM failed, ''%s''.\n', mfilename, mexnc('strerror',status) );
end



[dimname, dimlength, status] = mexnc('INQ_DIM', ncid, dimid);
if status ~= 0
	mexnc('close',ncid);
	error ( '%s:  INQ_DIM failed, ''%s''.\n', mfilename, mexnc('strerror',status) );
end

Dimension.Name = dimname;
Dimension.Length = dimlength;
Dimension.Dimid = dimid;

if dimid == unlimdim
	Dimension.Record_Dimension = 1;
else
	Dimension.Record_Dimension = 0;
end


return
