Time is an important part of data acquisition, and an important part of DAQFactory. We have provided some functions to make dealing with time a bit easier for you.
Align(Source, Align To, Threshold):
One of the powers of DAQFactory is the ability to take data at different data rates, or simply different times. This makes it difficult to perform many calculations such as correlation and the like. The Align() function will align the time associated array specified in source to the array given by Align To. Data that is outside of +/- threshold seconds from the times in Align To are set to NaN(). The value returned by this function is the aligned array. Note that many of the built in tools of DAQFactory automatically do an alignment when necessary. This includes X/Y graphs, error bars, trace colorization, logging and exporting, and correlation calculations.
FormatDate(time array)
This function converts a DAQFactory time value into a string representation of the date using your current windows locale setting. For example, with a US locale:
FormatDate(04y2m18d) returns "02/18/04"
FormatDateTime(format specifier string, time array)
This function converts a DAQFactory time value into a string representation using the format specifier provided to the function. The format specifier works a lot like the Format() function, but with different codes. Here are the codes:
%a The abbreviated weekday name (Mon, Tue, etc)
%A The full weekday name (Monday, Tuesday, etc)
%b The abbreviated month name (Jan, Feb etc.)
%B The full month name (January, February, etc.)
%c Date and time representation using the Window's locale settings
%d The day of month as decimal number (01 – 31)
%H The hour in 24-hour format (00 – 23)
%I The hour in 12-hour format (01 – 12)
%j The day of year as decimal number (001 – 366)
%m The month as decimal number (01 – 12)
%M The minute as decimal number (00 – 59)
%p The A.M./P.M. indicator for 12-hour clock as determined by the Window's locale settings
%S The second as decimal number (00 – 59)
%U The week of year as decimal number, with Sunday as first day of week (00 – 53)
%w The weekday as decimal number (0 – 6; Sunday is 0)
%W The week of year as decimal number, with Monday as first day of week (00 – 53)
%x Date representation using the Window's current locale settings
%X Time representation using the Window's current locale settings
%y The year without century, as decimal number (00 – 99)
%Y The year with century, as decimal number
%z, %Z Either the time-zone name or time zone abbreviation, depending on registry settings; nothing if time zone is unknown
%% Percent sign
Examples:
FormatDateTime("The current hour is: %H",12h45m) returns "The current hour is: 12"
FormatDateTime("%c", SysTime()) returns something like "02/20/04 12:14:07" depending on the current time and your locale settings.
FormatDateTime("%B %d, %Y",SysTime()) returns "February 20, 2004" for the above time.
FormatTime(time array)
This function converts a DAQFactory time value (seconds since 1970) into a string representation of the time using your current windows locale setting. For example:
FormatTime(1h2m3) returns "01:02:03" on a system set to display 24hr time.
GetTime(array):
Many of the values in DAQFactory have time arrays or values associated with them. Often these time values are used automatically, but sometimes you may wish to get the time array associated with a value array. The GetTime() function does just that. Alternatively with channels and variables, you can use .Time notation. So GetTime(MyChannel) is the same as MyChannel.Time. However, this does not work for the results of expressions, so (Max(MyChannel[0])).Time won't work, but GetTime(Max(MyChannel[0])) will. This is especially useful with the max/min functions as DAQFactory will actually return the time of the maximum or minimum point using GetTime().
InsertTime(Value, Start, Increment):
If you have an array that does not have time associated with it, you can use the InsertTime() to inject your own time into the array. This function returns the array given by value with a time value inserted for each element in the rows dimension. The time inserted is Start for the first element, then incremented by Increment for each element following. Because most arrays are set up with time backwards (i.e. point 0 has the latest time), you typically will want to use negative numbers for the Increment parameter.
ShiftTime(Value, Offset):
Often there are different latencies in instrumentation which makes intercomparison difficult without the ShiftTime(Value, Offset) function. This function returns Value with the time associated with it shifted by Offset.
SortTime(array):
DAQFactory typically takes care of keeping your data points sorted by time. However, when you perform the Concat function with two arrays with time associated with them, the resulting array will have time out of order unless all the points in the second array have times later than those in the first array. Often times this doesn't matter, but there are many parts of DAQFactory that, for optimization reasons, expect their arrays to be sorted by time. Graphs are the prime example of this. The SortTime(array) will sort an array for you based on time. We didn't automatically sort the array after a concat because often times you don't need to sort and sorting tends to be a relatively slow process.
StrToTime(string array, mask string):
This function allows you to convert a string or an array of strings specify date and time (i.e. "10/22/06 3:12:05") and convert them into DAQFactory time (number of seconds since 1970). If an array of strings is specified, then an array of times is returned. This function is most appropriate when reading in data logged in human readable time format. The mask string determines the order of the year, month, day, hour, minute and second fields. Use the characters "ymdhms" to specify the ordering. For example, for a standard US date / time string, you would put a mask of "mdyhms". For European time, you would put "dmyhms". For example:
StrToTime("10/22/06 3:12:05","mdyhms") returns 1161486725
If any of the date fields are not specified, the current date is assumed, so ("3:12:05","hms") would return the time of 3:12:05 today. If any time fields are missing, then they default to 0, so ("10/22/06","mdy") returns 10/22/06 at midnight. Note that you must specify the hour if you want to specify the minute, and it must be before the minute and after the month (if specified). This is because the "h" in the mask tells DAQFactory that the "m" following is minute and not month.
This function will interpret decimal seconds, so:
StrToTime("10/22/06 3:12:05.123","mdyhms") returns 1161486725.123
The delimiters used to separate the fields of the date and time does not matter and any non-numeric value will work except ".", which is used to specify decimal seconds. There does have to be delimiters, even if they are spaces. This function does not work with fixed field time/date specifications (such as "102206 031205"). For these, you would have to manually insert delimiters using the mid() function, before using this function.
SysTime():
To get the current computer time use the SysTime() function. This returns the number of seconds since January 1st, 1970 (with decimal seconds).
Note: DAQFactory uses the system clock only to retrieve the initial time. Once DAQFactory starts, it uses the high precision counter to determine the current time. In addition to providing much more precise time measurements, this also means that changes to the system clock will NOT affect the DAQFactory time. You have to restart DAQFactory after a change in the system clock.
