Date: Thu, 20 Jun 1996 20:14:00 -0400
Here's a cut at the documentation for the time/date reformatting stuff. Please let me know about any problems that you see and/or what needs clarification, etc. I think I can do it by the October meeting... Tnx. [approx 150 lines follow] timedateparams The presence of this file indicates that some time and/or date fields are to be created as reformatted versions of various input fields. Up to 5 output variables can be created. They will contain year, month, day, time and displacement from prime meridian. The year format is 4 digits including century. The month and day formats are 2 digit with leading zero if necessary. The time format is 4 digit hour/minute (24 hour clock with leading zeros if necessary). If input specifies sub-minute data, it is appended to hour/minute output as decimal minutes (with approximately the same precision as the input). The displacement is a 4 digit hour/minute, prefixed with a sign, which, when added to UTC time, gives local time. Unfortunately, inner cannot easily create variables, so the result must be stored over some other data, destroying it. If you don't want to replace existing data, room for the output variables must be made in the dataset by adding dummy names at the levels where you want the variables to appear (and, therefore, also adding the dummy names to the level 0 list). The levels must be the same or lower than the levels of the input variables used to generate them. If you DO replace existing data, you may well wish to change the variable name of that data to reflect the new format. This can be done via the transvar optional file. Similarly, you may need to change other output variable attributes such as output field width. Output variables may replace their source input variables if the replaced variable is not used as a source for other output variables. (Note that unnecessary input variables can be removed via the removals optional file, as well as by being replaced). The input required to produce the requested output may come from one or more input variables. Values needed to fill in the output variables should appear exactly once in one of the input variables. If a required value does not appear, the corresponding output variable will be considered missing data. If it appears more than once, an error will be issued. The content and format of each input variable is specified in this optional file by providing a template for each variable. The template consists of repeated strings of format conversion specification characters (the number of repeated characters representing the maximum width of the field), interspersed with punctuation characters, if any. White space characters will terminate a field. Punctuation characters will terminate numeric fields. Leading white space characters are ignored within a field. Note that if white space characters are considered data field separators by defgb, time/date values that contain white space will be treated as separate variables and therefore there will be no embedded white space characters (unless the significant_embedded_separators_in_fixed_field switch is specified; see the datafieldopts optional file documentation). Similarly, punctuation characters may be considered data field separators by some methods The format conversion specification characters (case sensitive) are: Specifier Description Field values b abbreviated month name 3 characters (Jan, Feb, etc) B full month name d day of month 1-31 f daylight savings time offset 0-120 (minutes) F daylight savings time flag True/False (see common format, above) h fraction of an hour H hour (24 hour clock) 0-23 I hour (12 hour clock) 1-12 j day of the year 1-366 J day of the year 0-365 m month 1-12 M minute 0-59 p am/pm a, am, p, pm q fraction of a day r displacement from prime meridian -12 to 12 (hours) s fraction of a second S second 0-59 y year 0-99; 1800-2100 Y year with century 1800-2100 z time zone -12 to 12, west positive Z time zone name 3 characters Character field values are considered case-insensitively. Notes: 1) an F value of true is the same as an f value of 60. 2) the only difference between y and Y format is the allowable range 3) many possible errors are not checked for. For example, a day-of-the-year of 366 is accepted whether or not the year is a leap year 4) The format conversion specification characters and the field values generally match the C library routine strftime specification Example 1-input field consists of year immediately followed by a Julian date (eg, 19951.5 for noon, Jan 2, 1995). Format could be YYYYJJJ.qqq since the . would terminate the date portion, and the end of the variable would terminate the fraction of day portion. Example 2-input field consists of full month, day & year in "normal English" format (eg, January 1, 1995). Format could be BBBBBBBBBBdd,YYYYY The 10 Bs allow for the longest month, while each month will be terminated by the blank. Note that in general, B format cannot be used without some punctuation or white space to indicate the end of the month. Example 3-input field consists of month/day/year:hr:min:sec (eg, 1/2/95:12:00:00:00.00 for noon, Jan 2, 1995). Format could be mm/dd/yy:HH:MM:SS.ss The timedateparams optional file is in common format. Its descriptor accepts the optional pre-translation- and post-translation- prefixes. Its data consists of 2 types of pairs. The first type of pair names input and output variables. The first element of each pair is a keyword and the second element of each pair is a variable name. For output variables, the keywords are: outyearname, outmonthname, outdayname, outtimename, and outdisplacementname. Each specifies the name of an existing variable to be replaced by the corresponding generated output data. Any or all of the output variables may be requested. For input variables, the keywords are of the form invarNname, where N is an integer starting from 1 and increasing by 1 for each input variable to be used in the reformatting. The variables can be supplied in any order. No gaps in the integer sequence are allowed. The second type of pair specifies the template of the input variables. The first element of each pair is a keyword of the form invarNtemplate, indicating that the pair describes variable invarNname. The second element of each pair is a template as described above. A template must appear for each input variable. Sample file: # Take time information from variables called time and ampm to produce # a standard output time, to be stored over the original time data. Take # information from a variable called date and reformat it into the 3 output # variables year, month, and day. # The format of the input time data is hour, minutes and seconds, separated # by colons. The maximum number of characters in each field is 2. # A sample time of this type is 9:11:58. The hour data is from a 12 hour # clock; the character in the ampm variable will be included to determine # the 24 hour time. # The format of the input date format is abbreviated month, day of month # (followed by a comma) and year (including the century). A sample # date of this type is Jan 15, 1996 # The output time resulting from the sample time will be 0911.97. The # output year, month & day from the sample date will be 1996, 01 and 15, # respectively. # # Notes: 1) The ampm variable in this example has become redundant, so # it might be specified in the removals optional file. The input variable # date might or might not be retained. The 3 output variables year, month, # and day must appear in the level 0 variable list. They must appear on # the same or lower level as the input variable date. # invar1name=time; invar1template=II:MM:SS invar2name=date; invar2template=bbbdd,YYYY invar3name=ampm; invar3template=p outtimename=time outyearname=year; outmonthname=month; outdayname=day Note: timedateparams replaces gmtparams from defgb versions 2.4 and older. To convert: 1) replace gmtparams with timedateparams in the indirect file 2) in the file pointed to by the timedateparams indirect file entry a) replace hrname with invar1name b) replace mnname with invar2name c) replace gmtname with outtimename d) add the 2 data pairs "invar1template=HH" and "invar2template = MM"