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.