%
%     Usage: 
%     	     [M,R,G,S] = hbin(fn)
%
%     Input Parameters:
%            fn = the name of the file that contains the Harwell-Boeing 
%                 format matrix.  hbin() tries to conform to the 1992 
%                 specification of the format 
%
%     Output Parameters:
%            M = the sparse matrix [required]
%            R = the right hand side(s), if present [optional]
%            G = a guess vector, if present [optional]
%            S = a solution vector, if present [optional]
%
%     Unsupported features of hbin(): 
%            Sparse RHS's and unassembled matrices aren't really
%            handled that well..
%
%     Version: 1/27/95 at 17:00, Indiana Standard Time
%
%     At least M must be specified.
%
%     If R,G, and/or S are specified, but not present in the matrix,
%     warning messages will be output.  However, if there are RHS and
%     solution vectors both specified without a guess vector, a guess
%     vector must be passed to hbin() and it will complain that no
%     guess was specified, but that message can be ignored.
%
%     Example Calling Sequences:
%            M = hbin('file');
%                 This call will return only the matrix stored in file.  No RHS
%                 data, even if present, will be retrieved.
%
%            [M,R] = hbin('file');
%                 This call will return the matrix and any RHS vectors, but 
%                 not any guess or solution vectors, data, stored in file.  
%                 A warning will be given if there is no RHS input data.
%
%            [M,R,G,S] = hbin('file')
%                 This call is required if any solution vectors are in the
%                 input, REGARDLESS of the presence of guess vectors.  It
%                 will also retrieve the HB-format-required RHS vectors.
%                 Any vectors not specified in 'file' will be give warnings.
% 
function [M,R,G,S] = hbin(fn)
	if (nargin ~= 1)
		error('hbin only takes 1 input argument');
	end

	if ((nargout < 1) | (nargout > 4))
		error('hbin only takes between 1 and 4 arguments');
	end

	if (nargout == 1)
		[M] = chbin(fn);
	elseif (nargout == 2)
		[M,R] = chbin(fn);
	elseif (nargout == 3)
		[M,R,G] = chbin(fn);
	elseif (nargout == 4)
		[M,R,G,S] = chbin(fn);
	end
	[m,n] = size(M);
	M = M + sparse(m,n);
end