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.