Time selection parameters in the Request SAPI call

Terry Weymouth from UMich figured this out, this is a re-post of his findings.

Definitions

Request(channelMap, time, duration, mode)

Where...
recTime is the time stamp on record,
lastTime is the greatest time ring buffer for a channel,
firstTime is the smallest time in the ring buffer for a channel,
maxLastTime is the greatest lastTime over all channels,
minFirstTime is the smallest firstTime over all channels
(for all duration >= 0 is required)

absolute
return records for which time <= recTime <= time+duration
duration=0 is a special case, returns the single record with
recTime <= time

newest
return records for which lastTime-(time+duration) <= recTime <=
lastTime-time; duration = 0 is a special case, returns the single closest
record to lastTime-time such that recTime <= lastTime-time

oldest
return records for which firstTime+time <= recTime <=
firstTime+time+duration; duration = 0 is a special case, returns the single
closest record to firstTime+time such that firstTime+time <= recTime

aligned (e.g. newestAlligned)
return records for which maxLastTime-(time+duration) <= recTime <=
maxLastTime-time

[did you-all ever consider oldestAlligned that is: minFirstTime+time <=
recTime <= minFirstTime+time+duration???]

after
given baseTime is the max of lastTime-duration and time
return records such that baseTime <= recTime <= baseTime+duration

modified
if time < lastTime, compute baseTime is lastTime-duration
return records such that baseTime <= recTime <= baseTime+duration
if time >= lastTime no data is returned

next
given that baseTime is the least recTime such that time <= baseTime
return records for which baseTime <= recTime <= bastTime+duration

previous
given that baseTime is the greatest recTime such that baseTime <= time
return records for which baseTime-duration <= recTime <= baseTime

Anomalies

'Next' with time < minFirstTime, duration > 0 

and

'Previous' with maxLastTime < time, duration >0

both return a list an array of times/data with duplicates in each
position but the first and the last
'Previous' with time <= maxListTime and duration = 0

only returned data on channel 0

Comments and more information

See the SAPI page on Request for more information.