Time variables of `Time_format = FREE_TIME_FORMAT' enable almost any foreign time series file to be imported into QSAS, or translated by Qtran into a standard format (e.g., qft or qfd with ISO time strings, or cdf). The interpretation and conversion of the time field in each data record is accomplished by specifying its components and format in the `TIME_FORMAT_STRING' metadata for that variable. This string is made up of `key strings' to match EXACTLY the entry in the data record. The first occurence of any single `key string' is used.
There is therefore a restriction that the time field in the record needs to be contained within a single '.qft/.qfd' variable. Thus delimited files in which, for example, the date and time are separated by a delimiter (and thus correspond to two variables) cannot be read using this method. Nor can tabular files with, e.g., the date and time separated by an intervening variable. There is also a restriction, of course, that the set of 'key strings' given below can provide a complete specification of the time field. In practice, none of these restrictions are often encountered.
The basic algorithm simply parses the 'TIME_FORMAT_STRING' and compiles the location of each date/time element. This information is then used to extract the values from the time entry in each record and compute the resulting epoch value. As described in the section on Variable Metadata, any elements, such as the year, month, seconds offset, etc., which are common to all records and not present in each record can be specified by the `All_records_time' and `All_records_format' strings which get appended, respectively, by QIE to the individual `record time string' and `TIME_FORMAT_STRING'. The discussion below uses the terms `record time string' and `TIME_FORMAT_STRING' to mean the result after such appending (if any) has been performed.
In practice, the date and time components are treated differently. The date is initialised to cdf epoch zero, i.e., year= 0AD, month = Jan, and day = 1. The year is sought first, and is reset if given in the `TIME_FORMAT_STRING' or left at default. If the Day of Year (Doy) is available, it is used (together with the year) to derive the month and day. In this case, independent month and/or day specifiers in the `TIME_FORMAT_STRING' are ignored. If Doy is not available, the month and day are individually sought and set if available or left at default. Over-specifying the date components is therefore benign, though the sequence of setting year, month, and day is prescribed and each is set only once, with subsequent repeat specifications ignored. Some (incomplete) checking is performed to ensure that Doy, month, and day values are within expected ranges.
Time components, by contrast, are all accumulated into a milliseconds field (which is initialised to zero), and the width of the input field is not restricted. This enables offsets to be introduced into the time stamp, e.g., by reading in the decimal seconds field from the data record and specifying, say, 2000 milliseconds in the All_records_time. This then effectively adds 2 seconds to each time stamp. It also enables time to be input in any one or a mixture of ways, including decimal days, milliseconds since 0AD, etc. Note, however, that some data archives provide time stamps in more than one way in each data record, e.g., as a decimal fraction of a day and also in hours, minutes, and seconds. Only one of these should be offered to QIE, as specifying both would double the time within the day.
The final cdf time value is generated by converting zero UT on the date into its cdf epoch (milliseconds since 0AD) and then adding the milliseconds calculated from time components.