GETDEPLOYMENTINFODB Get deployment information from database.
Syntax:
DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME)
DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME, OPTIONS)
DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME, OPT1, VAL1, ...)
Description:
DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME) executes the query given by
string QUERY on the database named by string DBNAME and returns a struct
DATA with fields given by corresponding columns in the query result.
DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME, OPTIONS) and
DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME, 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:
USER: database user name.
String with the name of the user of the database.
Default value: '' (user name not required by database)
PASS: database user password.
String with the password of the user of the database.
Default value: '' (user name not required by database)
SERVER: database server url.
String with the URL of the database server.
Default value: [] (do not specify a URL when connecting to database)
DRIVER: database driver.
String with the name of the driver to access the database.
Default value: [] (do not specify a driver when connecting to database)
FIELDS: database column renaming.
String cell array with alternative field names for output structure.
It should have the same number of elements than selected columns.
If empty, no renaming is done and column names are used as field names.
Default value: [] (do not rename columns)
TIME_FIELDS: timestamp fields.
String cell array with the name of the output fields to be converted to
from timestamp string to serial date number.
Default value: {'deployment_start' 'deployment_end'}
TIME_FORMAT: timestamp field format.
String with the format of the timestamp columns returned by the query.
Default value: 'yyyy-mm-dd HH:MM:SS' (ISO 8601 format)
The returned struct DATA should have the following fields to be considered
a deployment structure:
DEPLOYMENT_ID: deployment identifier (invariant over time).
DEPLOYMENT_NAME: deployment name (may eventually change).
DEPLOYMENT_START: deployment start date (see note on time format).
DEPLOYMENT_END: deployment end date (see note on time format).
GLIDER_NAME: glider platform name (present in Slocum file names).
GLIDER_SERIAL: glider serial code (present in Seaglider file names).
GLIDER_MODEL: glider model name (like Slocum G1, Slocum G2, Seaglider).
The returned structure may include other fields, which are considered to be
global deployment attributes by functions generating final products like
GENERATEOUTPUTNETCDF.
Notes:
Time columns selected in the query should be returned as UTC timestamp
strings in ISO 8601 format ('yyyy-mm-dd HH:MM:SS') or other format accepted
by DATENUM, and are converted to serial date number format.
Null entries are set to invalid (NaN).
Examples:
db_access = configDBAccess()
[query, fields] = configDTDeploymentInfoQuery()
deployment_info = getDeploymentInfoDB(...
query, db_access.name, 'fields', fields,
'user', db_access.user, 'pass', db_access.pass, ...
'server' db_access.server, 'driver', db_access.driver)
See also:
GENERATEOUTPUTNETCDF
DATABASE
FETCH
DATENUM
Authors:
Joan Pau Beltran <joanpau.beltran@socib.cat>0001 function data = getDeploymentInfoDB(query, dbname, varargin) 0002 %GETDEPLOYMENTINFODB Get deployment information from database. 0003 % 0004 % Syntax: 0005 % DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME) 0006 % DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME, OPTIONS) 0007 % DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME, OPT1, VAL1, ...) 0008 % 0009 % Description: 0010 % DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME) executes the query given by 0011 % string QUERY on the database named by string DBNAME and returns a struct 0012 % DATA with fields given by corresponding columns in the query result. 0013 % 0014 % DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME, OPTIONS) and 0015 % DATA = GETDEPLOYMENTINFODB(QUERY, DBNAME, OPT1, VAL1, ...) accept the 0016 % following options given in key-value pairs OPT1, VAL1... or in struct 0017 % OPTIONS with field names as option keys and field values as option values: 0018 % USER: database user name. 0019 % String with the name of the user of the database. 0020 % Default value: '' (user name not required by database) 0021 % PASS: database user password. 0022 % String with the password of the user of the database. 0023 % Default value: '' (user name not required by database) 0024 % SERVER: database server url. 0025 % String with the URL of the database server. 0026 % Default value: [] (do not specify a URL when connecting to database) 0027 % DRIVER: database driver. 0028 % String with the name of the driver to access the database. 0029 % Default value: [] (do not specify a driver when connecting to database) 0030 % FIELDS: database column renaming. 0031 % String cell array with alternative field names for output structure. 0032 % It should have the same number of elements than selected columns. 0033 % If empty, no renaming is done and column names are used as field names. 0034 % Default value: [] (do not rename columns) 0035 % TIME_FIELDS: timestamp fields. 0036 % String cell array with the name of the output fields to be converted to 0037 % from timestamp string to serial date number. 0038 % Default value: {'deployment_start' 'deployment_end'} 0039 % TIME_FORMAT: timestamp field format. 0040 % String with the format of the timestamp columns returned by the query. 0041 % Default value: 'yyyy-mm-dd HH:MM:SS' (ISO 8601 format) 0042 % 0043 % The returned struct DATA should have the following fields to be considered 0044 % a deployment structure: 0045 % DEPLOYMENT_ID: deployment identifier (invariant over time). 0046 % DEPLOYMENT_NAME: deployment name (may eventually change). 0047 % DEPLOYMENT_START: deployment start date (see note on time format). 0048 % DEPLOYMENT_END: deployment end date (see note on time format). 0049 % GLIDER_NAME: glider platform name (present in Slocum file names). 0050 % GLIDER_SERIAL: glider serial code (present in Seaglider file names). 0051 % GLIDER_MODEL: glider model name (like Slocum G1, Slocum G2, Seaglider). 0052 % The returned structure may include other fields, which are considered to be 0053 % global deployment attributes by functions generating final products like 0054 % GENERATEOUTPUTNETCDF. 0055 % 0056 % Notes: 0057 % Time columns selected in the query should be returned as UTC timestamp 0058 % strings in ISO 8601 format ('yyyy-mm-dd HH:MM:SS') or other format accepted 0059 % by DATENUM, and are converted to serial date number format. 0060 % Null entries are set to invalid (NaN). 0061 % 0062 % Examples: 0063 % db_access = configDBAccess() 0064 % [query, fields] = configDTDeploymentInfoQuery() 0065 % deployment_info = getDeploymentInfoDB(... 0066 % query, db_access.name, 'fields', fields, 0067 % 'user', db_access.user, 'pass', db_access.pass, ... 0068 % 'server' db_access.server, 'driver', db_access.driver) 0069 % 0070 % See also: 0071 % GENERATEOUTPUTNETCDF 0072 % DATABASE 0073 % FETCH 0074 % DATENUM 0075 % 0076 % Authors: 0077 % Joan Pau Beltran <joanpau.beltran@socib.cat> 0078 0079 % Copyright (C) 2013-2016 0080 % ICTS SOCIB - Servei d'observacio i prediccio costaner de les Illes Balears 0081 % <http://www.socib.es> 0082 % 0083 % This program is free software: you can redistribute it and/or modify 0084 % it under the terms of the GNU General Public License as published by 0085 % the Free Software Foundation, either version 3 of the License, or 0086 % (at your option) any later version. 0087 % 0088 % This program is distributed in the hope that it will be useful, 0089 % but WITHOUT ANY WARRANTY; without even the implied warranty of 0090 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0091 % GNU General Public License for more details. 0092 % 0093 % You should have received a copy of the GNU General Public License 0094 % along with this program. If not, see <http://www.gnu.org/licenses/>. 0095 0096 error(nargchk(2, 16, nargin, 'struct')); 0097 0098 0099 %% Set options and default values. 0100 options.user = ''; 0101 options.pass = ''; 0102 options.driver = ''; 0103 options.server = ''; 0104 options.fields = {}; 0105 options.time_fields = {'deployment_start' 'deployment_end'}; 0106 options.time_format = 'yyyy-mm-dd HH:MM:SS'; 0107 0108 0109 %% Parse optional arguments. 0110 % Get option key-value pairs in any accepted call signature. 0111 argopts = varargin; 0112 if isscalar(argopts) && isstruct(argopts{1}) 0113 % Options passed as a single option struct argument: 0114 % field names are option keys and field values are option values. 0115 opt_key_list = fieldnames(argopts{1}); 0116 opt_val_list = struct2cell(argopts{1}); 0117 elseif mod(numel(argopts), 2) == 0 0118 % Options passed as key-value argument pairs. 0119 opt_key_list = argopts(1:2:end); 0120 opt_val_list = argopts(2:2:end); 0121 else 0122 error('glider_toolbox:getDeploymentInfoDB:InvalidOptions', ... 0123 'Invalid optional arguments (neither key-value pairs nor struct).'); 0124 end 0125 % Overwrite default options with values given in extra arguments. 0126 for opt_idx = 1:numel(opt_key_list) 0127 opt = lower(opt_key_list{opt_idx}); 0128 val = opt_val_list{opt_idx}; 0129 if isfield(options, opt) 0130 options.(opt) = val; 0131 else 0132 error('glider_toolbox:getDeploymentInfoDB:InvalidOption', ... 0133 'Invalid option: %s.', opt); 0134 end 0135 end 0136 0137 0138 %% Retrieve data from database as a structure. 0139 if isempty(options.driver) && isempty(options.server) 0140 access_params = {options.user options.pass}; 0141 else 0142 access_params = {options.user options.pass options.driver options.server}; 0143 end 0144 conn = database(dbname, access_params{:}); 0145 if (~isconnection(conn)) 0146 error('glider_toolbox:db_tools:ConnectionError', ... 0147 'Error connecting to database: %s.', conn.Message); 0148 end 0149 dbprefs = setdbprefs(); 0150 setdbprefs({'NullNumberRead', 'NullStringRead', 'DataReturnFormat'}, ... 0151 {'NaN', 'null', 'structure'} ); 0152 try 0153 data = fetch(conn, query); 0154 catch exception 0155 close(conn); 0156 setdbprefs(dbprefs); 0157 rethrow(exception); 0158 end 0159 close(conn); 0160 setdbprefs(dbprefs); 0161 0162 0163 %% Convert to cell array for postprocessing. 0164 % MATLAB is not consistent when the DataReturnFormat is structure. 0165 % If no rows match the selected query, an empty array is returned instead. 0166 if isstruct(data) 0167 if isempty(options.fields) 0168 fields = fieldnames(data); 0169 else 0170 fields = cellstr(options.fields(:)); 0171 end 0172 data = struct2cell(data); 0173 for i = 1:size(data, 1) 0174 if isnumeric(data{i}) 0175 data{i} = num2cell(data{i}); 0176 end 0177 end 0178 data = horzcat(data{:}); 0179 else 0180 fields = cellstr(options.fields); 0181 data = cell(0, numel(fields)); 0182 end 0183 0184 0185 %% Convert time fields from timestamp string to serial date number. 0186 time_format = options.time_format; 0187 time_fields = cellstr(options.time_fields); 0188 time_field_columns = ismember(fields, time_fields); 0189 time_data = data(:,time_field_columns); 0190 if iscellstr(time_data) 0191 % DATENUM does not handle empty date string cell arrays properly. 0192 time_data_null = strcmp('null', time_data); 0193 if any(~time_data_null(:)) 0194 time_data(~time_data_null) = ... 0195 num2cell(datenum(time_data(~time_data_null), time_format)); 0196 end 0197 time_data(time_data_null) = {NaN}; 0198 else 0199 error('glider_toolbox:db_tools:TimeFieldError', ... 0200 'Wrong time data type (not a timestamp string).'); 0201 end 0202 data(:, time_field_columns) = time_data; 0203 0204 0205 %% Convert back to structure array with new field names. 0206 data = cell2struct(data, fields, 2); 0207 0208 end