xbd2dba

XBD2DBA  Slocum xbd to ascii file conversion using external program provided by WRC.

  Syntax:
    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE)
    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE, OPTIONS)
    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE, OPT1, VAL1, ...)

  Description:
    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE) converts the binary file(s) 
    named by string or string cell array DBD_FILES (xxx.[smdtne]bd files) 
    to the corresponding text representation in the ascii file named by string
    DBA_FILE, and returns the absolute path of the generated file in string
    DBA_FILE_FULL. The conversion is done invocating the system program 
    'dbd2asc' provided by the Webb Research Company with the contents of 
    DBD_FILES as argument, and capturing its output to DBA_FILE.
    The call is done in the current directory through the function SYSTEM 
    (this may be relevant for the cache directory involved in the conversion).

    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE, OPTIONS) and
    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE, OPT1, VAL1, ...) accept
    the following options given in key-value pairs OPT1, VAL1... or in struct 
    OPTIONS with field names as option keys and field values as option values:
      CMDNAME: conversion program executable.
        String with the conversion program command name, including the path
        if needed. This is useful if the 'dbd2asc' program has been renamed
        or it is not in your system path.
        Default value: 'dbd2asc'.
      CMDOPTS:
        String with extra options to use in the program call.
        It is placed into the command line just before the input file names.
        This is useful for passing options like '-k' or '-o'. 
        Default value: '' (no command options)
      CACHE: cache directory.
        String with the cache directory to use.
        It is passed as the -c option value in the conversion command call.
        If empty the -c option will not be used.
        Default value: '' (do not use -c command option)

  Notes:
    This function is intended to allow Slocum binary file conversion from
    MATLAB/Octave without having to fall back to a system terminal.

    Input file strings are passed to the command line as they are, 
    so they may contain glob patterns to be expanded by the underlying shell.

  Examples:
    % Convert a single file.
    dbd_file = 'happyglider-1970-000-0-0.sbd'
    dba_file = 'happyglider-1970-000-0-0-sbd.dba'
    dba_file_full = xbd2dba(dbd_file, dba_file)
    % Convert all navigation files of the same mission in current directory,
    % using it as cache directory and setting the path of the dbd2asc program.
    dbd_files = 'happyglider-1970-000-0-*.[smd]bd'
    dba_file = 'happyglider-1970-000-0-x-xbd.dba'
    dba_file_full = xbd2dba(dbd_file, dba_file, 'cache', pwd(), ...
                            'cmdname', '~/bin/dbd2asc')

  See also:
    DBACAT
    DBAMERGE

  Authors:
    Joan Pau Beltran  <joanpau.beltran@socib.cat>

0001 function dba_file_full = xbd2dba(dbd_files, dba_file, varargin)
0002 %XBD2DBA  Slocum xbd to ascii file conversion using external program provided by WRC.
0003 %
0004 %  Syntax:
0005 %    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE)
0006 %    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE, OPTIONS)
0007 %    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE, OPT1, VAL1, ...)
0008 %
0009 %  Description:
0010 %    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE) converts the binary file(s)
0011 %    named by string or string cell array DBD_FILES (xxx.[smdtne]bd files)
0012 %    to the corresponding text representation in the ascii file named by string
0013 %    DBA_FILE, and returns the absolute path of the generated file in string
0014 %    DBA_FILE_FULL. The conversion is done invocating the system program
0015 %    'dbd2asc' provided by the Webb Research Company with the contents of
0016 %    DBD_FILES as argument, and capturing its output to DBA_FILE.
0017 %    The call is done in the current directory through the function SYSTEM
0018 %    (this may be relevant for the cache directory involved in the conversion).
0019 %
0020 %    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE, OPTIONS) and
0021 %    DBA_FILE_FULL = XBD2DBA(DBD_FILES, DBA_FILE, OPT1, VAL1, ...) accept
0022 %    the following options given in key-value pairs OPT1, VAL1... or in struct
0023 %    OPTIONS with field names as option keys and field values as option values:
0024 %      CMDNAME: conversion program executable.
0025 %        String with the conversion program command name, including the path
0026 %        if needed. This is useful if the 'dbd2asc' program has been renamed
0027 %        or it is not in your system path.
0028 %        Default value: 'dbd2asc'.
0029 %      CMDOPTS:
0030 %        String with extra options to use in the program call.
0031 %        It is placed into the command line just before the input file names.
0032 %        This is useful for passing options like '-k' or '-o'.
0033 %        Default value: '' (no command options)
0034 %      CACHE: cache directory.
0035 %        String with the cache directory to use.
0036 %        It is passed as the -c option value in the conversion command call.
0037 %        If empty the -c option will not be used.
0038 %        Default value: '' (do not use -c command option)
0039 %
0040 %  Notes:
0041 %    This function is intended to allow Slocum binary file conversion from
0042 %    MATLAB/Octave without having to fall back to a system terminal.
0043 %
0044 %    Input file strings are passed to the command line as they are,
0045 %    so they may contain glob patterns to be expanded by the underlying shell.
0046 %
0047 %  Examples:
0048 %    % Convert a single file.
0049 %    dbd_file = 'happyglider-1970-000-0-0.sbd'
0050 %    dba_file = 'happyglider-1970-000-0-0-sbd.dba'
0051 %    dba_file_full = xbd2dba(dbd_file, dba_file)
0052 %    % Convert all navigation files of the same mission in current directory,
0053 %    % using it as cache directory and setting the path of the dbd2asc program.
0054 %    dbd_files = 'happyglider-1970-000-0-*.[smd]bd'
0055 %    dba_file = 'happyglider-1970-000-0-x-xbd.dba'
0056 %    dba_file_full = xbd2dba(dbd_file, dba_file, 'cache', pwd(), ...
0057 %                            'cmdname', '~/bin/dbd2asc')
0058 %
0059 %  See also:
0060 %    DBACAT
0061 %    DBAMERGE
0062 %
0063 %  Authors:
0064 %    Joan Pau Beltran  <joanpau.beltran@socib.cat>
0065 
0066 %  Copyright (C) 2013-2016
0067 %  ICTS SOCIB - Servei d'observacio i prediccio costaner de les Illes Balears
0068 %  <http://www.socib.es>
0069 %
0070 %  This program is free software: you can redistribute it and/or modify
0071 %  it under the terms of the GNU General Public License as published by
0072 %  the Free Software Foundation, either version 3 of the License, or
0073 %  (at your option) any later version.
0074 %
0075 %  This program is distributed in the hope that it will be useful,
0076 %  but WITHOUT ANY WARRANTY; without even the implied warranty of
0077 %  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0078 %  GNU General Public License for more details.
0079 %
0080 %  You should have received a copy of the GNU General Public License
0081 %  along with this program.  If not, see <http://www.gnu.org/licenses/>.
0082 
0083   error(nargchk(2, 8, nargin, 'struct'));
0084   
0085   
0086   %% Set options and default values.
0087   options.cmdname = 'dbd2asc';
0088   options.cmdopts = '';
0089   options.cache = [];
0090   
0091   
0092   %% Parse optional arguments.
0093   % Get option key-value pairs in any accepted call signature.
0094   argopts = varargin;
0095   if isscalar(argopts) && isstruct(argopts{1})
0096     % Options passed as a single option struct argument:
0097     % field names are option keys and field values are option values.
0098     opt_key_list = fieldnames(argopts{1});
0099     opt_val_list = struct2cell(argopts{1});
0100   elseif mod(numel(argopts), 2) == 0
0101     % Options passed as key-value argument pairs.
0102     opt_key_list = argopts(1:2:end);
0103     opt_val_list = argopts(2:2:end);
0104   else
0105     error('glider_toolbox:xbd2dba:InvalidOptions', ...
0106           'Invalid optional arguments (neither key-value pairs nor struct).');
0107   end
0108   % Overwrite default options with values given in extra arguments.
0109   for opt_idx = 1:numel(opt_key_list)
0110     opt = lower(opt_key_list{opt_idx});
0111     val = opt_val_list{opt_idx};
0112     if isfield(options, opt)
0113       options.(opt) = val;
0114     else
0115       error('glider_toolbox:xbd2dba:InvalidOption', ...
0116             'Invalid option: %s.', opt);
0117     end
0118   end
0119 
0120   
0121   %% Check for a single input file.
0122   if ischar(dbd_files)
0123     input_file_list = cellstr(dbd_files);
0124   else
0125     input_file_list = dbd_files;
0126   end
0127   input_str = [sprintf('%s ', input_file_list{1:end-1}) input_file_list{end}];
0128  
0129   
0130   %% Build command and execute it.
0131   % Note that shell redirection could be used here to produce the file inplace
0132   % from the command line. However, on errors (e.g. missing .cac files) this
0133   % would produce an empty file that should be removed afterwards. To prevent
0134   % this, capture the output of the dbd2asc in a string and write it to a file
0135   % only when conversion succeeds.
0136   cmd_name = options.cmdname;
0137   cmd_opts = options.cmdopts;
0138   cac_path = options.cache;
0139   if isempty(cac_path)
0140     cmd_str = [cmd_name ' ' cmd_opts ' ' input_str];
0141   else
0142     cmd_str = [cmd_name ' -c ' cac_path ' ' cmd_opts ' ' input_str];
0143   end
0144   [status, cmd_out] = system(cmd_str);
0145   if status ~= 0
0146     error('glider_toolbox:xbd2dba:SystemCallError', ...
0147           'Error executing call: %s\n%s.', cmd_str, cmd_out);
0148   end
0149   
0150   
0151   %% Create directory of target file if needed.
0152   % This seems to be the better way to check if a relative path points to
0153   % an existing directory (EXIST checks for existance in the whole load path).
0154   [dba_dir, ~, ~] = fileparts(dba_file);
0155   [status, attrout] = fileattrib(dba_dir);
0156   if ~status
0157     [success, message] = mkdir(dba_dir);
0158     if ~success
0159       error('glider_toolbox:xbd2dba:AsciiDirectoryError', ...
0160             'Could not create directory %s: %s.', dba_dir, message);
0161     end
0162   elseif ~attrout.directory
0163     error('glider_toolbox:xbd2dba:AsciiDirectoryError', ...
0164           'Not a directory: %s.', attrout.Name);
0165   end
0166 
0167   
0168   %% Write output of conversion command to the file.
0169   [fid, fid_msg] = fopen(dba_file, 'w');
0170   if fid < 0
0171     error('glider_toolbox:xbd2dba:WriteFileError', ...
0172           'Could not create file %s: %s.', dba_file, fid_msg);
0173   end
0174   fprintf(fid, '%s', cmd_out);
0175   fclose(fid);
0176   
0177    
0178   %% Return the absolute name of the produced file.
0179   [status, attrout, ~] = fileattrib(dba_file);
0180   if status==0
0181     % We should never get here (if conversion succeed, ascii file must exist).
0182     error('glider_toolbox:xbd2dba:AsciiFileError', ...
0183           'Conversion call succeed but problems with output file %s: %s.', ...
0184           dba_file, attrout);
0185   end
0186   dba_file_full = attrout.Name;  
0187   
0188 end