function [Dimension, return_status] = nc_getdiminfo ( arg1, arg2 )
% NC_GETDIMINFO:  returns metadata about a specific NetCDF dimension
%
% USAGE:  [Dimension, status] = 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.
%    status:
%        -1 in case the routine fails
%
% This routine purposefully mimics that of Mathwork's hdfinfo.
%
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% $Name:  $
% $Id: nc_getdiminfo.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;
Dimension = [];


% Show usage if too few arguments.
%
if nargin ~= 2
   help nc_getdiminfo;
   return;
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
		fprintf ( 2, '%s:  mexnc:open failed on %s.\n', mfilename, ncfile );
		return
	end

	% Suppress warning messages from netCDF
	[status]=mexnc('setopts',0);
	if status < 0
		fprintf ( 2, '%s:  mexnc:setopts failed.\n', mfilename );
		return
	end

	[dimid, status] = mexnc('DIMID', ncid, dimname);
	if ( status < 0 )
		fprintf ( 2, '%s:  mexnc:dimid failed on file ''%s'', dimension ''%s''.\n', mfilename, ncfile, dimname );
		mexnc('close',ncid);
		return
	end

	
	% 
	% Get the information.
	[Dimension, status] = get_diminfo ( ncid,  dimid );
	if ( status < 0 )
		fprintf ( 2, '%s:  get_diminfo failed on %s, file %s.\n', mfilename, ncfile, dimname );
	end

	%
	% 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, status] = get_diminfo ( ncid,  dimid );
	if ( status < 0 )
		fprintf ( 2, '%s:  get_diminfo failed on dimid %d.\n', mfilename, dimid );
		return
	end


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


return_status = 0;

return





function [Dimension, status] = get_diminfo ( ncid, dimid )

Dimension = [];
status = -1;

[unlimdim, status] = mexnc ( 'inq_unlimdim', ncid );
if status < 0
	fprintf ( 2, '%s:  mexnc:inq_unlimdim failed.\n', mfilename );
	mexnc('close',ncid);
	return
end



	[dimname, dimlength, status] = mexnc('DIMINQ', ncid, dimid);
	if status < 0
		fprintf ( 2, '%s:  mexnc:inquire failed.\n', mfilename );
		mexnc('close',ncid);
		return
	end

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

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


return


