a_intro_time


	1. It has been more common than we would like to find times that
	   are off by an hour, 5 hours, or 6 hours within the control
	   system.  These errors are related to confusion about timezones:
	   Coordinated Universal Time (UTC)
	   Greenwich Mean Time (GMT) - obsolete (more on this later)
	   Central Standard Time (CST)
	   Central Daylight Time (CDT)
	   a. Confusion about CST vs. CDT - Many older date formats did
	      not provide an explicit timezone.  Therefore, with such
	      formats one can not distinguish the repeated local times
	      that occur in the first hour after the transistion back to
	      standard time each Fall.  With a timezone one can tell the
	      the difference because the first occurence is in CDT but
	      the second is in CST.   Nearly all clib routines for date
	      conversion use ":" vs. ";" to make this distinction. 
	      See date_to_clinks.
	   b. Historical use of local time - The VAX/VMS machines
	      used local time pervasively not just for user interface
	      aspects.   This includes the semantics of the time_t
	      values.   Because of the volume of software much software
	      still expects such local time_t semantics.  Such time_t
	      values don't increase uniformly by 1 each second.  See
	      convert_seconds_c for a discussion of local time_t vs.
	      UTC time_t.   The Sybase database also used local time
	      historically.   See intro_database for more details and
	      techniques to use UTC times for new DB fields.
	
	2. Time systems used within the ACNET Control System
	   a. broken down time systems - years, months, days, etc.
	      a. Central Standard Time (CST)
	         A timezone 6 hours behind UTC.  Stated another way CST's t=0 moment
	         is 6 hours later than UTC's t=0 moment.  UTC will be discussed later.
	      b. Central Daylight Time (CDT)
	         A timezone 5 hours behind UTC.  Stated another way CST's t=0 moment
	         is 5 hours later than UTC's t=0 moment.
	      c. Coordinated Universal Time (UTC)
	         The definition of UTC is somewhat complicated (see
	         systems-of-time). It is a replacement for Greenwich Mean Time
	         (GMT) which is considered obsolete by time experts, e.g., the
	         individuals at the U.S. Naval Observatory (USNO) and the
	         National Institute of Standards (NIST). But in the ACNET
	         Control System and Linux in general the distinction between UTC
	         and GMT is hard to understand, keep, or notice.  E.g., Linux has a
	         gmtime_r() which despite its name claims according to the man page
	         to convert time to UTC but the value it actually places in tm_zone
	         is "GMT" anyway.  In addition, by experiment neither Java nor
	         C/C++ on our Linux systems handles UTC's leap seconds correctly.
	         This experimental determination was made using the code in
	         services/time_experiments. So the error bars on our operating
	         system's conception of time exceeds the distinction between UTC
	         and GMT.  For our purposes both are a timezone 6 hours ahead of
	         CST and 5 hours ahead of CDT. Of course, since CST and CDT were
	         defined above in terms of UTC this is quite circular.  UTC is
	         really defined in terms of atomic clocks, the Earth's rotation,
	         and other complexitities that we don't really need to understand.
	      d. Local Time at FNAL
	         A combination of CST and CDT.  CST and CDT are reasonably sensibly ways
	         to specify time when used consistently.  The difficulty comes from
	         switching back and forth between them.  It is of particular difficulty
	         that the date of the transistions are a subject of ever-changing
	         legistation and as a result depend on the year.
	   b. single unit time systems - elapsed seconds/milliseconds
	      a. Elapsed time since the Epoch (1/1/1970 midnight UTC)
	         a. Both Java, e.g., java.util.Date, and Linux C/C++, e.g.,
	            ctime(3), define "the Epoch" to be 1/1/1970 midnight UTC/GMT.
	         b. Java and C/C++ agree on "the Epoch" but use different units.
	            a. Java  uses milliseconds since the Epoch.
	            b. C/C++ uses seconds since the Epoch.  C/C++ also has time structures
	               that augment seconds with milliseconds, microseconds, or
	               nanoseconds since the last second.
	               a. time_t          just seconds since Epoch
	               b. struct timeb    time_t plus milliseconds since increment of time_t
	                  Please don't use struct timeb it is associated with the obsolete
	                  ftime() routine.  It includes undefined members pertaining to
	                  timezone and DST that might be assumed incorrectly to have
	                  accurate values.  See man ftime(3).
	               c. struct timeval  time_t plus microseconds since increment of time_t
	               d. struct timespec time_t plus nanoseconds  since increment of time_t
	               The actual resolution beyond seconds depends on the system. On our
	               Linux systems nanoseconds is just microseconds times 1000.
	      b. "ctime", i.e., time_t values
	         a. This unit of measure is named after the function of the same name, which
	            takes a time_t as its only argument.  However, many routines on Linux
	            expect a time_t argument not just ctime.  In addition the semantics of
	            ctime(), etc. changed.  On VAX/VMS ctime was non-linear, but on Linux it
	            is linear, see comments under old choices.  This difference leads to
	            individuals not all meaning the same thing when they use the term
	            "ctime".  In addition the t=0 moment for "ctime" on the VAX/VMS machines
	            was 1 Jan 1970 midnight CST, but on the Linux it is 1 Jan 1970 midnight UTC.
	         b. As a result the following terminology is established:
	            Local ctime - reflects semantics of the now retired VAX/VMS machines
	            UTC ctime - reflects semantics of the current Linux machines
	            Local ctime is very common for historical reasons, but UTC ctime is
	            prefered for new uses.  See convert_seconds_c for detailed explanation
	            of the difference between the two.
	      c. Clinks (ACNET time)
	         a. The time of an event in clinks is the total elapsed seconds between the
	            event and 1 Jan 1972 midnight CST.  Note that differs from seconds since the
	            Epoch because the year has changed from 1970 to 1972 and timezone from
	            UTC to CST.
	         b. Because of VAX/VMS's use of local time, clinks on the VAX/VMS was not
	            actually linear.  (See discussion above about "ctime".)  This was noticed
	            during the VMS to Linux migration and was as far was one can tell fixed
	            except perhaps for persistent data.   The historical clinks_handle_dst_c
	            routine was removed from clib's clinklib.cpp on 1 June 2009.

	3. Of particular importance is using date and time well within the database.  Please
	   see intro_database for how to use UTC for DB datetime fields.

	4. References
	   Official US Time from NIST
	   Orgin of UTC and demise of GMT
	   UTC, UT1, and the demise of GMT
	   Leap seconds and years from NIST
	   Screen capture of leap second from www.time.gov in Central timezone
	   Leap seconds when present are at midnight UTC.
	   Subscribe to leap second notifications
	   USNO leap second data