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"