Date and Time Conversion Package
IMPORTANT:
The operation of this package has changed significantly. Please
read the revised description carefully. Note in particular that
the Timer and UpdateTimer procedures have been absorbed into the
Operating System, and that DayTime and SetDayTime have been
replaced by ReadCalendar and SetCalendar, which are also in the
Operating System. This version of the Time package functions only
under O.S. version 14 or later.
This package provides facilities for converting date and time between
internal and human-readable forms. Date and time values have three
different representations: packed, unpacked, and text.
The packed representation is a 32-bit integer representing number of
seconds since midnight, January 1, 1901, GMT (Greenwich Mean Time).
The Alto O.S. continuously maintains a date and time clock, whose
current value is available via the ReadCalendar procedure, and which is
used internally for such purposes as time-stamping accesses to files.
The unpacked representation is a 7-word vector UTV, whose structure is
defined in the definition file Time.d. It describes a particular date
and time in terms of separate year, month, day, hour, minute, and
second values, and is hence a more convenient representation for use
during input and output of human-readable date and time strings.
The text representation (either a string or characters passing through
a stream) is one readable by a human being. There is no standard
format for this, though the Time package does define one particular
format.
Procedures dealing with these representations are organized into three
parts. Procedures for obtaining and setting packed times are defined
in the O.S. and are not included as part of the Time package, though
they are described here for convenience. Procedures for converting
between packed and unpacked times are contained in the files
TimeConvB.Br and TimeConvA.Br. Procedures for converting between
unpacked times and text strings are contained in file TimeIO.Br.
TimeIO requires the other two, but the reverse is not true. All three
files are distributed in the dump-format file Time.Dm.
1. Operating System Time Procedures
The following procedures are defined in the Alto Operating System:
ReadCalendar(ptv)
Reads the current packed date and time into the 2-word vector
pointed to by ptv (packed time vector). Returns ptv as its
value.
------------
Copyright Xerox Corporation 1981
Time Conversion May 6, 1981 2
SetCalendar(ptv)
Declares the packed date and time pointed to by ptv to be the
current date and time. (This value might have been
constructed using the PACKDT procedure in the time conversion
package. It is not reasonable to compute packed time values
by hand.) Most programs should have no occasion to call this
procedure; it is intended for use by programs such as the
Executive's SetTime command.
Timer(tv)
Reads a millisecond timer into the 2-word vector pointed to
by tv, and returns tv!1 as its value. This timer is
maintained by the Operating System, but it bears no
particular relation to the date and time clock and has an
arbitrary starting value. It is useful primarily for
interval timing.
The old procedures DayTime and SetDayTime are still included in the
O.S. for backward compatibility, but they are simply aliases for
ReadCalendar and SetCalendar and no longer convert between the old and
new time standards.
2. Time Packing and Unpacking
The procedures in TimeConvB.Br and TimeConvA.Br convert between packed
time vectors (ptv) and unpacked time vectors (utv). The structure UTV
is defined in Time.d. It has the following components:
utv>>UTV.year Actual year (e.g., 1977)
utv>>UTV.month Month (January = 0)
utv>>UTV.day Day of month (first day = 1)
utv>>UTV.hour Hour of day (midnight = 0)
utv>>UTV.minute Minute
utv>>UTV.second Second
utv>>UTV.daylight 1 if Daylight Savings Time is in effect
utv>>UTV.weekday Day of week (Monday = 0, Sunday = 6)
utv>>UTV.zone Local time zone. This has three components: a
sign (0 if west of Greenwich, 1 if east), an
hour value (number of hours east or west of
Greenwich), and a minute value (normally
zero).
Note that a utv describes local time (with Daylight Savings Time
already applied if appropriate) rather than Greenwich Mean Time. The
conversion procedures take care of the necessary time zone and DST
corrections.
UNPACKDT(ptv, utv)
Converts the packed date and time pointed to by ptv into the
corresponding unpacked representation, and stores the result
in the unpacked time vector pointed to by utv. If ptv = 0,
the present date and time are used. The procedure returns
utv as its result.
PACKDT(utv, ptv, flag [false])
Performs the inverse of UNPACKDT, converting the unpacked
Time Conversion May 6, 1981 3
date and time pointed to by utv into packed format at ptv.
Returns zero if successful and the index of an incorrect utv
element if unsuccessful (that is, 1 if the year was illegal,
2 if the month was illegal, etc.) The weekday cell need not
be valid, as it is recomputed by PACKDT.
If flag is false or omitted, the daylight and zone fields are
ignored and values appropriate to the date and time supplied
and to the local time zone are used instead. This is the
correct action in most situations. If flag is true, the
daylight and zone fields are used to control the conversion,
and no check is made of their reasonableness.
WEEKDAY(ptv)
Returns the day of week of the packed time vector ptv (Monday
= 0, Sunday = 6). Note that if you already have a utv, it is
simpler just to extract the weekday field from it.
3. External Time Conversion
The module TimeIO.Br provides facilities for converting between
internal form and external text strings. It requires the presence of
the TimeConvB.Br and TimeConvA.Br modules as well.
WRITEUDT(strm, utv, printZone [false])
Takes an unpacked time vector utv and writes it on the stream
strm in the form "29-Dec-74 18:39:47". If utv = 0, the
current date and time are used.
If printZone is supplied and true, the time zone is appended
to the result, e.g., "29-Dec-74 18:39:47 PST". For time
zones outside North America, the time is written as "29-Dec-
74 18:39:47 +02" (2 hours west of Greenwich), or "29-Dec-74
18:39:47 -05" (5 hours east of Greenwich), or "29-Dec-74
18:39:07 -01:30" (1 hour 30 minutes east of Greenwich).
WRITEUDT does not perform any of the error checks of PACKDT,
so it will produce garbage if given garbage.
CONVUDT(strg, utv, printZone [false])
Performs the same conversion as WRITEUDT, but deposits the
result in the string strg. Returns strg as its result.
FINDMONTH(strg)
Tries to interpret the string strg as the name of a month.
If successful, returns the month number (January = 0,
December = 11); if unsuccessful, returns -1. Strg must be at
least 3 characters long, and must be the prefix of some month
name, ignoring upper/lower case distinctions.
MONTHNAME(mo)
Returns a string which is the name of the month mo (0 to 11),
fully spelled out (e.g., "December"). The caller should not
write into this string.
Time Conversion May 6, 1981 4
4. Implementation
Maintenance of the current date and time and the local time parameters
is performed by several cooperating pieces of software, including the
Operating System.
Locations 570 through 577 in page 1 of Alto memory are reserved for use
by the Time software. They must not be overwritten by any booting or
core image restoration process. Of these, locations 572 through 577
are used by the O.S. to maintain the calendar clock and millisecond
timer. This is accomplished by calling the UpdateTimer procedure
during the display vertical field interrupt routine (60 times second).
UpdateTimer examines the clock maintained by the Alto microcode and
appropriately updates the second and millisecond clocks.
Locations 570 and 571 contain local time parameters required by the
date and time conversion software. These parameters are described by
the structure LTP, defined in AltoDefs.d, which may be used in
constructs such as "timeParams>>LTP.zoneH".
sign Zero if the local time zone is west of Greenwich,
one if east.
zoneH Number of hours east or west of Greenwich, in the
range 0 to 12. The Pacific time zone is 8 hours
west of Greenwich.
zoneM Additional minutes east or west or Greenwich, in
the range 0 to 59. This is usually zero, but there
are a few places in the world whose local time is
not an integer number of hours from Greenwich.
beginDST The day of the year on or before which Daylight
Savings Time takes effect, where 1 = January 1 and
366 is December 31 (the correspondence between
numbers and days is based on a leap year). The
software will adjust this number to the nearest
preceding Sunday. The standard value is 121 =
April 30.
endDST The day of the year on or before which Daylight
Savings Time ends. The standard value is 305 =
October 31. If Daylight Savings Time is not
observed locally, the beginDST and endDST values
should both be set to 366.
The local time parameters are set by the Executive's SetTime command
from information obtained from time servers on the local Ethernet.
These values are also written into magic locations in the O.S. boot
image so as to make them available even if, at some later time, no time
server is available. When the O.S. is booted, it checks to see whether
the in-core values are reasonable, and if not attempts to restore them
from the magic locations in the boot image.