function [neg_on_err] = pb_set_scan_segments(num_segments)
% FUNCTION NAME:
%   pb_set_scan_segments
%
% DESCRIPTION:
%   Set the number of data "segments" to be acquired. The default value is 1, 
%   meaning when data is acquired, it will be stored to the RAM starting at 
%   address zero, and continue until the desired number of points are acquired. 
%   Any subsequent data acquisition scans will behave in the same way and thus 
%   overwrite (or average with) the previous data. If num_segments is set to a 
%   value higher than 1, the given number of segments will be acquired before 
%   resetting the ram address to 0. For example if num_points is set to 1000, 
%   and num_segments is set to 3, the first time the acquisition is triggered 
%   (using scan_trigger), data will be written to RAM locations 0-999. The 
%   second time it is triggered, data will be written to locations 1000-1999 
%   (instead of writing again to locations 0-999 as would be the case for 
%   num_segments = 1). On the third trigger data will go to locations 2000-2999. 
%   Finally a fourth trigger would again write to locations 0-999, and the cycle 
%   will continue as desired.
%
% INPUTS:
%   num_segments - Number of segments to acquire. Must be between 1 and 65535.
%
% OUTPUTS:
%   neg_on_err - A negative number is returned on failure, and spinerr is set
%                to a description of the error. 0 is returned on success. 
%
% $Revision: R2017a$ 
% $Author: SpinCore Technologies, Inc.$
% $Date: November 17, 2023$
% ------------------------------------------------------------------------------

global SPINAPI_DLL_NAME;

neg_on_err = calllib(SPINAPI_DLL_NAME, 'pb_set_scan_segments', num_segments);

end