;docformat='rst'
;+
;   Find the time tags for the first item less than and greater than
;     an specified interval from a time range for a given telemetry item
;     from the AIM_L1A TManalog table.
;
; :Author:
;    Chris Jeppesen, Bill Barrett
;
; :Params:
;   externalelement : in, required, type=String
;     The external element string from which the telemetry item
;     originates. This is always 'ac' for official AIM data
;   item_name : in, required, type=String
;     The item name of the telemetry item requested.
;   start_time : in, required, long64 or double
;     The beginning of the interval
;   stop_time : in, required, long64 or double
;     The end of the interval
;   rows_to_return : in, required, int
;     The number of rows from the interval to examine
;   sid : in, required, int
;     1 for all official AIM data
;   cycle : in, required, int
;     1 for all official AIM data
;
; :Keywords:
;   verbose : in, optional, type=boolean
;     If set prints additional information to the console when this
;     routine is running.
;
; :Returns:
;   An array of two doubles, the first of which is the minimum time given the
;     constraints; the second the maximum time.
;
;
; :Examples:
;    min_and_max=minmaxtimes(external_element, item_name, start_time, stop_time, $
;      rows_to_return, sid, cycle)
;-

function minmaxtimes, external_element, item_name, start_time, stop_time, $
  rows_to_return, sid, cycle, verbose=verbose

  ; Get the telemetry id for the named element, typically one of the four quaternions
  case item_name of
    'aqinr2bdyest0' : tmid = 7983
    'aqinr2bdyest1' : tmid = 7984
    'aqinr2bdyest2' : tmid = 7985
    'aqinr2bdyest3' : tmid = 7986
    else: begin
      get_itemname_item_definition, external_element, item_name, info
      ; tmid is the telemetry id column name in AIM_L1A.TMananlog
      tmid=info.tlmid
    end
  endcase

  database = 'AIM_L1A'
  get_database_login, database, user=user, password=password, url=url

  ; Normally there should be 5 seconds (5000000LL usec) between quaternion records
  nominal_time_between_records = 5000000LL
  ; The minimum search time window for a search window should be large
  ; enough to find the requisite number of records
  base_query_time = rows_to_return * nominal_time_between_records
  ; One second in microseconds
  one_minute_usec = 60LL * 1000000LL

  ; The part of the query common to both the lower and and upper bound queries
  query_core = 'select SCT_VTCW from ' + database + '.TManalog where SID=' + strtrim(STRING(sid), 2) + $
    ' and SCT_Cycle=' + strtrim(STRING(cycle), 2) + ' and TMID='+  strtrim(STRING(tmid), 2)

  ; First find the timestamp of the nth to last item before the beginning of the interval
  ; Then find the timestamp of the nth item after the end of the interval
  minmax = dblarr(2)
  asc_desc = [ 'desc', 'asc' ]
  direction = [ '<', '>']
  start_stop = [ start_time, stop_time]
  for j = 0, 1 do begin
    ; Limit the search to a maximum of eight minutes from the start time
    for i = -1, 3 do begin
      ; Generate the sequence 0, 1, 2, 4, 8
      multiplier = i ge 0 ? 2^i : 0
      if multiplier gt 0 then print, get_routine_name() + $
        're-querying for '  + strtrim(string(multiplier), 2) + ' minute window'
      time_delta = base_query_time + (multiplier * one_minute_usec)
      if j eq 0 then time_delta = -time_delta
      sql = query_core + ' and SCT_VTCW ' + direction[j] + ' ' + strtrim(string(long64(start_stop[j])), 2) + $
        ' and SCT_VTCW ' + direction[j eq 0 ? 1 : 0] + ' ' + $
        strtrim(string(long64(start_stop[j] + time_delta)), 2) + $
        ' order by SCT_VTCW ' + asc_desc[j]
      if KEYWORD_SET(verbose) then PRINT, get_routine_name() + $
        strtrim(string(i), 2) + ' ' + sql
      query_database, sql, data, nrows, user=user, password=password, dburl=url, $
        limit_rows=rows_to_return, /dbConnect
      ; If the data has been found or there is more than a ten minute gap
      if nrows ge rows_to_return then break
    endfor

    if nrows eq 0 then minmax[j] = 0. $
    else minmax[j] = double(j eq 0 ? MIN(data.sct_vtcw) : MAX(data.sct_vtcw))
  endfor
  RETURN, minmax

end