
Internet DAYTIME Client v1.0
-----------------------------
Author:  Patrick J. Gleason
Date:  16-Mar-2007
Project:  Bulletron Internet Operating System 12.0
Operating System:  OS/2 Warp 4.0 and later, eComStation
Compiler:  IBM VisualAge C++ 3.0
Phone: (315) 475-5598
Email: ora68@nehemiah.idkcomp.com
Web Site: http://www.idkcomp.com

This program synchronizes the date and time of the local PC with the
atomic clock provided by the United States' National Institute of
Standards and Technology (NIST).  It is intended to supercede and
replace a program named "NISTIME.EXE" for eComStation and IBM OS/2,
which no longer works because it was hard-coded many years ago with an
IP address for the time server that is no longer valid.

If you start this when the system boots, it will execute once every
24 hours, eating up less than one second of CPU time and keep your
clock accurate within one second of NIST.  This is good enough for
distinguishing the age of backups and setting the expiration times for
web pages and cookies.  The NTP protocol is more accurate, but this
eats up a lot less CPU time in overhead.  The daily drift for most
PCs is less than three seconds per day.  You can set this program to
re-sync the clock each hour, eating up less than one second of each
hour in overhead, and have your time accurate to within one second
constantly.

The protocol used by this program is named "SETTIME", which uses
well-known TCP/IP port 13.  A full explanation and specification for the
DAYTIME protocol can be found at "http://tf.nist.gov/service/its.htm",
and in RFC 867.  The home page for the NIST web site is
"http://www.nist.gov".


How it Works:
--------------
This program connects to a time standard server using TCP.  The server
sends back a 51 character message using the same format as ACTS
(Automated Computer Time Service) for direct modem dial-in.  The format
of this message is:

        JJJJJ YR-MO-DA HH:MM:SS TT L H msADV UTC(NIST) OTM

where:

JJJJJ           is the Modified Julian Date (MJD).  The MJD has a
                starting point of midnight on November 17, 1858.  You
                can obtain the MJD by subtracting exactly 2 400 000.5
                days from the Julian Date, which is an integer day
                number obtained by counting days from the starting point
                of noon on 1 January 4713 B.C. (Julian Day zero).

YR-MO-DA        is the date.  It shows the last two digits of the year,
                the month, and the current day of month.

HH:MM:SS        is the time in hours, minutes, and seconds.  The time is
                always sent as Coordinated Universal Time (UTC).  An
                offset needs to be applied to UTC to obtain local time.
                For example, Mountain Time in the U. S. is 7 hours
                behind UTC during Standard Time, and 6 hours behind UTC
                during Daylight Saving Time.

TT              is a two digit code (00 to 99) that indicates whether
                the United States is on Standard Time (ST) or Daylight
                Saving Time (DST).  It also indicates when ST or DST is
                approaching.  This code is set to 00 when ST is in
                effect, or to 50 when DST is in effect.  During the
                month in which the time change actually occurs, this
                number will decrement every day until the change
                occurs.  For example, during the month of October, the
                U. S. changes from DST to ST.  On October 1, the number
                will change from 50 to the actual number of days until
                the time change.  It will decrement by 1 every day until
                the change occurs at 2 a.m. local time when the value is
                1.  Likewise, the spring change is at 2 a.m. local time
                when the value reaches 51.

L               is a one-digit code that indicates whether a leap second
                will be added or subtracted at midnight on the last day
                of the current month.  If the code is 0, no leap second
                will occur this month.  If the code is 1, a positive
                leap second will be added at the end of the month.  This
                means that the last minute of the month will contain 61
                seconds instead of 60. If the code is 2, a second will
                be deleted on the last day of the month. Leap seconds
                occur at a rate of about one per year.  They are used to
                correct for irregularity in the earth's rotation.  The
                correction is made just before midnight UTC (not local
                time).

H               is a health digit that indicates the health of the
                server.  If H=0, the server is healthly. If H=1, then
                the server is operating properly but its time may be in
                error by up to 5 seconds.  This state should change to
                fully healthy within 10 minutes.  If H=2, then the
                server is operating properly but its time is known to be
                wrong by more than 5 seconds. If H=4, then a hardware or
                software failure has occurred and the amount of the time
                error is unknown.

msADV           displays the number of milliseconds that NIST advances
                the time code to partially compensate for network
                delays.  The advance is  currently set to 50.0
                milliseconds.


UTC(NIST)       is a label contained in every time code.  It indicates
                that you are receiving Coordinated Universal Time (UTC)
                from the  National Institute of Standards and Technology
                (NIST).

OTM             (on-time marker) is an asterisk (*). The time values
                sent by the time code refer to the arrival time of the
                OTM.  In other words, if the time code says it is
                12:45:45, this means it is 12:45:45 when the OTM
                arrives.  Because of the phase synchronization of bits
                transmitted over a 1200 Baud analog modem, ACTS can be
                guaranteed synchronization accuracy within one hundredth
                of a second by triggering update on the trailing edge of
                the stop bit for this character.  This feature is lost
                by internet packetization, but synchronization with one
                second can usually be achieved.


Set Up Details:
----------------
This program expects to find an environment variable named "TZ".  This
would typically be defined in your "CONFIG.SYS" file by a line that
looks like:

        SET TZ=est5edt

Inside the program is a table of commonly used time zone abbreviations
used for "TZ=".  If the abbreviation you use is not in this table, or
you choose not to define "TZ=", then there is also an override.  This
table is:

       NOTE:  For the spring of 2007, the U.S.  Congress changed
       the start and end days for daylight savings time from the
       first sunday in April and the last sunday in October, to
       the second sunday in March and the first sunday in
       November.  Older OS/2 systems do not attempt to
       automatically adjust for daylight savings time.  If your
       system does attempt to automatically adjust and you find
       the time off by an hour during a few weeks in the spring
       and fall, then set "TZ=" to an abbreviation for standard
       time for your zone and let this program compute the
       adjustment.


         Minutes to  Daylight
Abbrv.   Add to GMT  Savings   Common Name
------------------------------------------------------------------------
A        +60          0        Alpha Time Zone (military) UTC + 1 hour
ACDT     +570         +60      Australian Central Daylight Time (Australia) UTC + 10:30 hours
ACST     +570         0        Australian Central Standard Time (Australia) UTC + 9:30 hours
ADT      -240         +60      Atlantic Daylight Time (North America) UTC - 3 hours
AEDT     +600         +60      Australian Eastern Daylight Time (Australia) UTC + 11 hours

AEST     +600         0        Australian Eastern Standard Time Australia UTC + 10 hours
AKDT     -540         +60      Alaska Daylight Time (North America) UTC - 8 hours
AKST     -540         0        Alaska Standard Time (North America) UTC - 9 hours
AST      -240         0        Atlantic Standard Time (North America) UTC - 4 hours
AWDT     +480         +60      Australian Western Daylight Time (Australia) UTC + 9 hours

AWST     +480         0        Australian Western Standard Time (Australia) UTC + 8 hours
B        +120         0        Bravo Time Zone (Military) UTC + 2 hours
BST      0            +60      British Summer Time (Europe) UTC + 1 hour
C        +180         0        Charlie Time Zone (Military) UTC + 3 hours
CDT      -360         +60      Central Daylight Time (North America) UTC - 5 hours

CEDT     +60          +60      Central European Daylight Time (Europe) UTC + 2 hours
CEST     +60          +60      Central European Summer Time (Europe) UTC + 2 hours
CET      +60          0        Central European Time (Europe) UTC + 1 hour
CST      -360         0        Central Standard Time (North America) UTC - 6 hours
CST6CDT  -360         +60      Central Daylight Time (North America) UTC - 6 hours

CXT      +420         0        Christmas Island Time (Australia) UTC + 7 hours
D        +240         0        Delta Time Zone (Military) UTC + 4 hours
E        +300         0        Echo Time Zone (Military) UTC + 5 hours
EDT      -300         +60      Eastern Daylight Time (North America) UTC - 4 hours
EEDT     +120         +60      Eastern European Daylight Time (Europe) UTC + 3 hours

EEST     +120         +60      Eastern European Summer Time (Europe) UTC + 3 hours
EET      +120         0        Eastern European Time (Europe) UTC + 2 hours
EST      -300         0        Eastern Standard Time (North America) UTC - 5 hours
EST5EDT  -300         +60      Eastern Daylight Time (North America) UTC - 5 hours
F        +360         0        Foxtrot Time Zone (Military) UTC + 6 hours

G        +420         0        Golf Time Zone (Military) UTC + 7 hours
GMT      0            0        Greenwich Mean Time (Europe) UTC
H        +480         0        Hotel Time Zone (Military) UTC + 8 hours
HAA      -240         +60      Heure Avance de l'Atlantique (North America) UTC - 3 hours
HAC      -360         +60      Heure Avance du Centre (North America) UTC - 5 hours

HADT     -600         +60      Hawaii-Aleutian Daylight Time (North America) UTC - 9 hours
HAE      -300         +60      Heure Avance de l'Est (North America) UTC - 4 hours
HAP      -480         +60      Heure Avance du Pacifique (North America) UTC - 7 hours
HAR      -420         +60      Heure Avance des Rocheuses (North America) UTC - 6 hours
HAST     -600         0        Hawaii-Aleutian Standard Time North America UTC - 10 hours

HAT      -210         +60      Heure Avance de Terre-Neuve (North America) UTC - 2:30 hours
HAY      -540         +60      Heure Avance du Yukon (North America) UTC - 8 hours
HNA      -240         0        Heure Normale de l'Atlantique (North America) UTC - 4 hours
HNC      -360         0        Heure Normale du Centre (North America) UTC - 6 hours
HNE      -300         0        Heure Normale de l'Est (North America) UTC - 5 hours

HNP      -480         0        Heure Normale du Pacifique (North America) UTC - 8 hours
HNR      -420         0        Heure Normale des Rocheuses (North America) UTC - 7 hours
HNT      -210         0        Heure Normale de Terre-Neuve (North America) UTC - 3:30 hours
HNY      -540         0        Heure Normale du Yukon (North America) UTC - 9 hours
I        +540         0        India Time Zone (Military) UTC + 9 hours

IST      0            +60      Irish Summer Time (Europe) UTC + 1 hour
K        +600         0        Kilo Time Zone (Military) UTC + 10 hours
L        +660         0        Lima Time Zone (Military) UTC + 11 hours
M        +720         0        Mike Time Zone (Military) UTC + 12 hours
MDT      -420         +60      Mountain Daylight Time (North America) UTC - 6 hours

MESZ     +60          +60      Mitteleuropische Sommerzeit (Europe) UTC + 2 hours
MEZ      +60          0        Mitteleuropische Zeit (Europe) UTC + 1 hour
MST      -420         0        Mountain Standard Time (North America) UTC - 7 hours
MST7MDT  -420         +60      Mountain Daylight Time (North America) UTC - 7 hours
N        -60          0        November Time Zone (Military) UTC - 1 hour

NDT      -210         +60      Newfoundland Daylight Time (North America) UTC - 2:30 hours
NFT      +690         0        Norfolk (Island) Time (Australia) UTC + 11:30 hours
NST      -210         0        Newfoundland Standard Time (North America) UTC - 3:30 hours
O        -120         0        Oscar Time Zone (Military) UTC - 2 hours
P        -180         0        Papa Time Zone (Military) UTC - 3 hours

PDT      -480         +60      Pacific Daylight Time (North America) UTC - 7 hours
PST      -480         0        Pacific Standard Time (North America) UTC - 8 hours
PST8PDT  -480         +60      Pacific Daylight Time (North America) UTC - 8 hours
Q        -240         0        Quebec Time Zone (Military) UTC - 4 hours
R        -300         0        Romeo Time Zone (Military) UTC - 5 hours

S        -360         0        Sierra Time Zone (Military) UTC - 6 hours
T        -420         0        Tango Time Zone (Military) UTC - 7 hours
U        -480         0        Uniform Time Zone (Military) UTC - 8 hours
UTC      0            0        Coordinated Universal Time (Europe) UTC
V        -540         0        Victor Time Zone (Military) UTC - 9 hours

W        -600         0        Whiskey Time Zone (Military) UTC - 10 hours
WEDT     0            +60      Western European Daylight Time (Europe) UTC + 1 hour
WEST     0            +60      Western European Summer Time (Europe) UTC + 1 hour
WET      0            0        Western European Time (Europe) UTC
WST      +480         +60      Western Summer(Daylight) Time (Australia) UTC + 9 hours

WST      +480         0        Western Standard Time (Australia) UTC + 8 hours
X        -660         0        X-ray Time Zone (Military) UTC - 11 hours
Y        -720         0        Yankee Time Zone (Military) UTC - 12 hours
Z        0            0        Zulu Time Zone (Military) UTC


A plain ASCII text file, named "SETTIME.INI" controls the operation of
this program.  This configuration file defines three parameters, all of
which are optional.  Blank lines and lines beginning with a semicolon in
the configurattion file are ignored as comments.  Each parameter line
consists of a label, followed by a colon, then a space, then a value.
The parameters are:

        Label           Value
        --------------------------------------------------------
        Server:         specifies the Internet of the time standard
                        server.  If this is not specified, then the
                        default is "time.nist.gov".  A current list of
                        servers is published by NIST at
                        "http://tf.nist.gov/service/time-servers.html".

        Add-to-GMT:     By default, this program looks at your "TZ"
                        environment variable, which has an abbreviaton
                        identifying your local time zone, to figure out
                        how to set your local time.  Inside the program,
                        there is a table of commonly used time zone
                        abbreviations, giving their offsets relative to
                        GMT and whether or not they use daylight savings
                        time.  If you do not find your time zone
                        abbreviation in that table, or want to override
                        it manually, you can write to me and I will add
                        it in the next release, or you can manually
                        override it by setting the "Add-to-GMT"
                        parameter here.  The "Add-to-GMT" parameter
                        specifies the number of minutes to add to GMT to
                        get your local time.  Leave this blank, comment
                        it out or delete it to use your "TZ=" enviroment
                        variable and the program's internal table.  As
                        an example, for Eastern Standard Time, I might
                        set this to -300 because when it is midnight in
                        London, it is 7:00 PM of the previous day here.
                        I would also set this to -300 for Eastern
                        Daylight Savings Time, and use the three
                        parameters below to enable and define define the
                        daylight savings time adjustment.

        DST:            Set the "DST" parameter to "YES" to enable
                        automatic daylight savings time adjustment.  Put
                        "NO" to disable automatic daylight savings time
                        adjustment.  Leave this blank, comment it out or
                        delete it to use the program's internal table.
                        If "YES", then daylight savings time
                        automatically subtracts one hour from the local
                        time between 2:00 AM on the second Sunday in
                        March and 2:00 AM on the first Sunday in
                        November.  For my time zone (EST5EDT), this
                        would cause 240 minutes to be subtracted from
                        GMT to get my local time during the summer.  The
                        basic time zone offset is still determined by
                        the "TZ" environment variable, unless you
                        overide it by using the "Add-to-GMT" parameter.
                        Specifying "DST" just affects whether or not a
                        daylight savings time adjustment is performed.

        DST-Start:      Daylight savings time traditionally adds one
        DSE-End:        hour to the local time between 2:00 AM on the
                        first Sunday in April and 2:00 AM on the last
                        Sunday in October.  This year, the United States
                        Congress has changed those dates to the second
                        Sunday in March and the first Sunday in
                        November.  You can set the "DST-Start" and
                        "DST-End" parameters to change the dates on
                        which the daylight savings time adjustment
                        starts and ends.  As these start and end points
                        are always at 2:00 AM on a sunday, you need to
                        tell the program which sundays those are.  For
                        each parameter, specify two numbers separated by
                        a space.  The first number specifies the month
                        (1 to 12) and the second number specifies which
                        sunday in that month (-4 to 4).  A negative
                        number means sundays from the end of the
                        specified month.  For example, to use the old
                        standard, you would specify:

                           DST-Start: 4 1
                           DST-End: 10 -1

                        This would get you the first Sunday in April and
                        the last Sunday in October.  The new standard
                        could be specified as:

                           DST-Start: 3 2
                           DST-End: 11 1

                        for the second Sunday in March and the first
                        Sunday in November.

                        You can leave either or both of these parameters
                        blank, comment them out or delete them to begin
                        on the second Sunday in March and end on the
                        first Sunday in November.  The use of
                        "DST-Start" and/or "DST-End" does not affect
                        whether or not daylight savings time adjustment
                        is performed, just when it starts and ends.

        Period:         specifies the number of hours between
                        synchronizations.  If this is not specified,
                        then the program synchronizes the date and time
                        at 24 hour intervals.  If you want to just do
                        one synchronization, then exit, perhaps as part
                        of a "CRON" batch job, then specify 0 for the
                        period.

        Verbose:        specifies the amount of information recorded
                        in the progam execution log:

                        0 = log date and time updates and errors only

                        1 = also include all protocol details

                        2 = also include DEBUG style (hexadecimal
                            and ASCII) dump of all data received




Running the Program:
---------------------
You can execute this program from any OS/2 or eCS command line prompt
by entering:

        SETTIME

There are no command line parameters.

You can call it from "STARTUP.CMD", put an object for it in your System
Startup folder, or whatever.

