function [gridname,ndrog,nts,tsec,pth]=read_pth(fname,ncol,fmtstr)
%READ_PTH read drogue .pth file output from DROG3D or DROG3DDT.
%
% [gridname,ndrog,ndts,tsec,pth]=read_pth(fname,ncol,fmtstr);
%
% 	   Input:
%		  fname  - path/name of .pth file
%		  ncol   - number of columns in output matrix
%		  fmtstr - format string for PLOTDROG to use in
%		           reading the .pth file (optional)
%          Output:
%                 gridname - domain name of computation
%                 ndrog    - number of drogues at start of run
%                 ndts     - number of time steps in run
%                 tsec     - length of run in seconds
%                 pth      - path data part of the .pth file. 
%
%          READ_PTH takes as required arguments the path/filename of the
%	   .pth file generated by DROG3D(DT), and the number of columns
%          the subroutine OUTPUT (from DROG3D(DT)) used to write the .pth 
%          file.  The filename specified must NOT include the .pth suffix.  
%          This allows READ_PTH to verify that the filetype is correct.
%	   Ex.: if the path/filename is 'results/case1.pth', the name given
%	   to READ_PTH should be 'results/case1'.
%
%          Optional argument comments:
%
%          If fmtstr is NOT specified, READ_PTH makes assumes the following
%          as to the format of the path matrix:
%  
%	   If ncol = 3  -->  real   real   real
%	   If ncol = 4  -->  real   real   real   real 
%	   If ncol = 5  -->  real   real   real   real  integer
%	   If ncol = 6  -->  real   real   real   real  real  integer
%
%          If the above assumption about the format of the output matrix
%          is NOT correct, you must specify, in the C fashion, the correct 
%          format for READ_PTH to use in the C fashion.  See the MATLAB 
%          Reference Guide under FSCANF for more on format specification.  
%
% Call as: [gridname,ndrog,ndts,tsec,pth]=read_pth(fname,ncol,fmtstr);
%
% Written by: Brian O. Blanton
%

% DEFINE ERROR STRINGS
err1=['READ_PTH requires 2 or 3 arguments.'];
err2=['second argument to READ_PTH must be an integer.'];
err3=['format specification to READ_PTH must be a string.'];

% check arguments
if nargin ==2 
   if isstr(ncol),error(err2);,end
   if ncol==3
      fmtstr='%f %f %f';
   elseif ncol==4
      fmtstr='%f %f %f %f';
   elseif ncol==5
      fmtstr='%f %f %f %f %d';
   elseif ncol==6
      fmtstr='%f %f %f %f %f %d';
   end  
elseif nargin==3
    if isstr(ncol),error(err2),end
    if ~isstr(fmtstr),error(err3),end
else
   error(err1);
end


% read path file
pathfile=[fname,'.pth'];
[pfid,message]=fopen(pathfile);
if pfid==-1
   error([fname,'.pth not found. ',message]);
end

% read grid name from top of .pth file
gridname=fscanf(pfid,'%s',1);
gridname=blank(gridname);

% read until 'XXXX' delimiter
test=fscanf(pfid,'%s',1);
while ~strcmp(test,'XXXX')
   test=fscanf(pfid,'%s',1);
   if isempty(test)
      disp(['String XXXX not found in file ',fname]);
      gridname=0;
      return
   end
end

% read number if timesteps, total run time in secs, and number of drogues
a=fscanf(pfid,'%d %f %d',3);
nts=a(1);
tsec=a(2);
ndrog=a(3);

% read entire path 
pth=fscanf(pfid,fmtstr,[ncol inf])';

% If nts==0, then the .pth file was output from DROG3DDT.  Compute
% nts from ndrog and the length of the path matrix, pth
if nts==0,nts=length(pth)/ndrog;,end

return
%
%        Brian O. Blanton
%        Department of Marine Sciences
%        15-1A Venable Hall
%        CB# 3300
%        Uni. of North Carolina
%        Chapel Hill, NC
%                 27599-3300
%
%        919-962-4466
%        blanton@marine.unc.edu
%