function [new_data, return_status] = nc_archive_buffer ( input_buffer, ncfile, record_variable, unlimited_dimension )
% NC_ARCHIVE_BUFFER:  Tacks on new data from simple matlab structure to an unlimited-dimension netcdf file
% 
% This function is deprecated.  Please use nc_addnewrecs.m instead.  All 
% this function really does is call nc_addnewrecs anyway.
%
% If a field is present in the structure, but not in the netcdf file, then that
% field is ignored.  Only data that is more recent than the last record currently
% in the NetCDF file is written.  This routine is written with time series data in mind.
%
% USAGE:  [new_data, status] = nc_archive_buffer ( buffer, ncfile, record_variable, unlimited_dimension )
% 
% PARAMETERS:
%   Input:
%      buffer:  
%          structure of (hopefully) time series data.  
%      ncfile:  
%          netcdf file that we write information to
%      record_variable:
%          hopefully this is something like "time".  In ROMS, it is "ocean_time".
%      unlimited_dimension:
%          Optional.  This should be a coordinate variable.  If not supplied, 
%          the default value is "time".  In ROMS, it is "time".
%   Output:
%      new_data:  
%          Matlab structure of data corresponding in structure to "buffer", but
%          consisting only of those records which were actually written to file.
%      status:  
%          -1 if the routine fails
%           0 if the routine succeeds
%
%  
%   The dimensions of the data should match that of the target netcdf file.  For example, 
%   suppose an ncdump of the
%   NetCDF file looks something like
%
%       netcdf a_netcdf_file {
%       dimensions:
%       	lat = 1 ;
%       	lon = 2 ;
%       	depth = 2 ; 
%       	time = UNLIMITED ; // (500 currently)
%       variables:
%       	double time(time) ;
%       	float var1(time, depth) ;
%       	float var2(time, depth, lat, lon) ;
%       	float var3(time, depth, lat) ;
%       
%       // global attributes:
%       }
% 
%   The "input_buffer" should look something like the following:
%
%       >> input_buffer
%
%       input_buffer =
%
%           time: [3x1 double]
%           var1: [3x2 double]
%           var2: [4-D double]
%           var3: [3x2 double]
%
%   The reason for the possible size discrepency here is that matlab will
%   ignore trailing singleton dimensions (but not interior ones, such as
%   that in var2.
%
%   If a variable is not present, then the corresponding NetCDF variable will
%   populate with the appropriate _FillValue.
%          
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% $Name:  $
% $Id: nc_archive_buffer.m,v 1.1 2005/06/29 16:07:00 brian Exp $
% AUTHOR:  johnevans@acm.org
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

new_data = [];
return_status = -1;

if nargin < 2 | nargin > 4
	fprintf ( 2, '%s:  must have at least two input arguments, no more than 4.\n', mfilename );
	return;
end

switch nargin
case 2
	[new_data, status] = nc_addnewrecs ( ncfile, input_buffer );
case { 3, 4 }
	[new_data, status] = nc_addnewrecs ( ncfile, input_buffer, record_variable );
end
if ( status < 0 )
	fprintf ( 2, '%s:  nc_addnewrecs failed.\n', mfilename );
	return
end


return_status = 0;
return;
