--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/m-toolbox/classes/+utils/@mysql/getAOsInTimeSpan.m	Wed Nov 23 19:22:13 2011 +0100
@@ -0,0 +1,196 @@
+% GETAOSINTIMESPAN performs high-level queries to retrieve AOs from an LTPDA repository.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% DESCRIPTION: GETAOSINTIMESPAN performs high-level queries to retrieve AOs
+%              from an LTPDA repository. The AOs for that channel in that time-span
+%              are joined together and then split on the requested
+%              interval. The resulting AO covers the requested interval,
+%              assuming that the repositoy contains a contiguos set of AOs
+%              spanning the requested time.
+%
+% CALL:        b = getAOsInTimeSpan(pl)
+%
+% INPUTS:      pl - a plist containing parameters as described below
+%
+% OUTPUTS:     b  - a vector of AOs resulting from the query
+%
+% PARAMETERS:
+%
+%     choose from
+%              'hostname'       - hostname/IP address of LTPDA Repository
+%              'database'       - the name of the database to query
+%          or
+%              'conn'           - a database connection object
+%
+%    in addition, we need
+%              'binary'         - retrieve binary data (true or false)
+%              'channels'       - a cell array of AO names
+%              'timespan'       - a timespan object to specify the
+%                                 time-interval of interest
+%
+% The timespan is applied start <= data < end.
+%
+% OPTIONAL PARAMETERS:
+%
+%    further restrict the search with the following conditions
+%
+%               'username'   - specify the username of the person who
+%                              submitted the AO
+%               'submitted'  - specify the date the AO was submitted
+%
+% EXAMPLES:
+%
+% 1) Find all AOs which are called 'ChannelX' submitted after 1st May 2007
+%
+%    pl = plist('hostname', 'localhost', 'database', 'ltpda_test', ...
+%               'channels', {'channelX'}, ...
+%               'timespan', timespan('2007-05-01 00:00:00', '3000-01-01 12:34:50', ...
+%               );
+%
+%    a = getAOsInTimeSpan(pl);
+%
+% 2) Find all AOs for ChannelX and ChannelY on 1st May 2007 submitted by
+%    hewitson
+%
+%    pl = plist('hostname', 'localhost', 'database', 'ltpda_test', ...
+%               'channels', {'channelX'}, ...
+%               'timespan', timespan('2007-05-01 00:00:00', '2007-05-02 00:00:00', ...
+%               'username', 'hewitson');
+%
+%    a = getAOsInTimeSpan(pl);
+%
+% VERSION:     $Id: getAOsInTimeSpan.m,v 1.3 2010/01/22 12:46:08 ingo Exp $
+%
+% HISTORY:     25-02-08 M Hewitson
+%                 Creation
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+function varargout = getAOsInTimeSpan(varargin)
+
+  error('### Obsolete as of LTPDA version 2.2. Replaced my AO model retrieve_in_timespan');
+  % Collect input ao's, plist's and ao variable names
+  in_names = {};
+  for ii = 1:nargin
+    in_names{end+1} = inputname(ii);
+  end
+  [pl, pl_invars] = utils.helper.collect_objects(varargin(:), 'plist', in_names);
+
+  % Process the input plist
+  conn     = find(pl, 'conn');
+  hostname = find(pl, 'hostname');
+  database = find(pl, 'database');
+  channels = find(pl, 'channels');
+  tspan    = find(pl, 'timespan');
+  useBinary = find(pl, 'binary');
+
+  % Check inputs
+  if isempty(hostname) || ~ischar(hostname)
+    if isempty(conn) || ~isa(conn, 'database')
+      error(sprintf('### Plist should contain ''hostname'' and ''database'' parameters,\n or a ''conn'' parameter.'));
+    end
+  end
+  if isempty(database) || ~ischar(database)
+    if isempty(conn) || ~isa(conn, 'database')
+      error(sprintf('### Plist should contain ''hostname'' and ''database'' parameters,\n or a ''conn'' parameter.'));
+    end
+  end
+  if isempty(channels)
+    error('### Plist should contain a ''channels'' parameter.');
+  end
+  if isempty(tspan) || ~isa(tspan, 'timespan')
+    error('### Plist should contain a ''timespan'' parameter.');
+  end
+
+  % Check the channels value is a cell
+  if ~iscell(channels)
+    channels = {channels};
+  end
+
+  % Get a connection to the database
+  iConnected = 0;
+  if ~isa(conn, 'database')
+    % then we connect
+    try
+      conn = utils.mysql.connect(hostname, database);
+      iConnected = 1;
+    catch
+      error('### Failed to connect to server: %s/%s', hostname, database);
+    end
+  end
+
+  % Collect the data
+  try
+    aout =  hlq(conn, channels, tspan, useBinary);
+  catch
+    lasterr
+    % Do we need to close database connection?
+    if iConnected
+      close(conn);
+    end
+    error('### Error retrieving objects.');
+  end
+
+  % Do we need to close database connection?
+  if iConnected
+    close(conn);
+  end
+
+  % set outputs
+  varargout{1} = aout;
+end
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% A prototype for the kind of high-level query functions we might need
+function objsOut = hlq(conn, channels, ts, useBinary)
+
+  % prepare output
+  objsOut = [];
+
+  % Loop over the channels
+  for j=1:length(channels)
+
+    % this channel
+    channel = channels{j};
+
+    % the query
+    q =      ['select objmeta.obj_id from objmeta,ao,tsdata ' ...
+      'where objmeta.obj_id=ao.obj_id ' ...
+      'and ao.data_id=tsdata.id ' ...
+      sprintf('and objmeta.name=''%s''', channel) ...
+      sprintf('and tsdata.t0+INTERVAL tsdata.nsecs SECOND  >= ''%s''', char(ts.startT)) ...
+      sprintf('and tsdata.t0 <= ''%s''', char(ts.endT))];
+
+    % execute query
+    info = utils.mysql.dbquery(conn, q);
+
+    % collect objects
+    if useBinary
+      objs = ltpda_uo.retrieve(conn, 'binary', [info{:}]);
+    else
+      objs = ltpda_uo.retrieve(conn, [info{:}]);
+    end
+    
+    % join these up
+    ojn = join([objs{:}]);
+
+    % split out the bit we want
+    os = split(ojn, plist('split_type', 'interval', 'timespan', ts));
+
+    % add to outputs
+    objsOut = [objsOut os];
+  end % end loop over channels
+end
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Returns the default plist
+function pl = getDefaultPlist(varargin)
+
+  pl = plist('hostname', 'localhost', ...
+    'database', 'ltpda_test',  ...
+    'channels', {'chan1', 'chan2'}, ...
+    'timespan', timespan('1970-01-01 00:00:00', '2010-10-12 12:45:32') ...
+    );
+end
+
+