
				 Time and Date

			   Copyright Jason Hood 2004

			     Freeware. Version 2.10


    ===========
    Description
    ===========

    Time and Date (TAD) is a utility to set and/or display the time.  It can
    set the system time from, or independently of, the real-time clock (RTC;
    not available in Windows NT). The time can be automatically adjusted  to
    counter RTC inaccuracies.  Calculations using times and/or durations can
    be performed.


    =====
    Usage
    =====

    The time format is "[hh]:[mm][:ss]" where:

	hh is the hour (0 to 23);
	mm is the minute (0 to 59);
	ss is the second (0 to 59).

    No check is made to determine if the time is valid.  Note that the colon
    is required. If any component is missing it will default to the current;
    if all components are missing (ie: "::") it will be treated as a  format
    string.

    The date format is "[dd][/[mm][/yy[yy]]]" where:

	dd is the day (1 to 31);
	mm is the month (1 to 12);
	yy is the year (1980 to 2099 in DOS/RTC, 1601 to 8907 in Win32).

    Again, no check is made to determine  the  validity  of  the  date	(the
    system  itself  prevents  invalid  dates  and  times  being  set).	 Any
    character can be used in place of "/" (except colon, of course), but the
    order  cannot be changed.  Years 00 to 79 are taken as 2000 to 2079, and
    80 to 99 as 1980 to 1999. If any component is missing it will default to
    the current; if all components are missing (eg: "//") it will be treated
    as a format string.

    An option starts with "-" or "/".  Multiple options can be combined (eg.
    "-nm"  is  the  same  as  "-n  -m",  "/nm"  and "/n/m", but NOT "-n-m").
    Briefly:

	-a	display the "approximate" time
	-y	display the current day of the year
	-w	display the current week of the year
	-b	display the date and time briefly (concisely)
	-f	display the time using a custom format
	-c	display as a clock
	-t	use the real-time clock instead of the system (*)
	-tt	display the difference between RTC and system times (*)
	-k	set system time/date, keep the RTC as is (*)
	-s	set the system time/date from the real-time clock (*)
	-n	start a new calibration
	-r	take the given time/use the current time as reference
	-m	monitor the time for external update
	-d	correct for drift
	-v	view calibration details
	-q	quiet, no display
	-e	select exit code

    Options marked with '*' are ignored in the Windows version and  the  DOS
    version will still use the system clock on an NT/2K/XP system.


    If no options are given, the time, day and date is displayed. Eg:

	17:08:27  Thursday, 21 June, 2001

    The Windows version will use the native names for the days of  the	week
    and the months of the year (but the German version is always in German).


    b - Brief (concise) time

    The date will be displayed using a short format. Eg:

	17:08:27 21/6/01

    A second 'b' will display the date and time as a single string. Eg:

	20010621170827

    This option also effects the calibration/drift duration display.


    a - Approximate time

    The time will be displayed as a five-minute interval,  past  or  to  the
    hour. Eg:

	The time is ten past five.
	It's ten past five.
	Ten past five.


    y - Day of year

    The current day within the year will be displayed. Eg:

	21 June is the 172nd day of 2001.
	Day 172, Year 2001.
	172


    w - Week of year

    The current week within the year will be displayed. Eg:

	It is the 25th week of 2001.
	Week 25, Year 2001.
	25

    Note: the first week always begins on January 1, not the first Sunday or
    Monday.


    f - Format

    Display the time in any  format  you  choose.  "-f?"  will  display  the
    available  format  specifiers;  "-fl" will list the default formats. The
    "-f" is optional - any non-digit will start a format string.  Specifiers
    'b',  'B',  'c', 'C' and 'T' will use the local date and time separators
    (from the COUNTRY  setting	in  "CONFIG.SYS"  or  the  Windows  regional
    settings).	 'b'  and 'B' will use the local date order and 'T' will use
    the local time format  (via  'c'  or  'C').   'b'  and  'B'  also  react
    differently  to  the  prefixes.   Using  '0'  will zero-pad both day and
    month; '1'  will  zero-pad  the  middle  value  (either  day  or  month,
    depending  on  USA or European/Japanese); and 2 will space-pad the first
    value (or last if using Japanese format) and zero-pad the middle.


    c - Clock

    The time will be continuously displayed until a key is pressed.


    t - Real-time clock

    Use the RTC instead of the system.	Note: invalid times will be allowed.


    tt - Test times

    Display the real-time clock and system times, and the difference between
    them.


    k - Keep RTC

    The system time and/or date can be set without affecting the RTC.	This
    option  allows  you  to  temporarily change the time, restoring it again
    with "-s". The Windows version will use a temporary file (TAD.RTC in the
    same  directory  as the executable) to remember the current time. Unlike
    the DOS version, the Windows version cannot handle multiple  -k  options
    (ie: -s should used before using -k again).


    s - System from RTC

    The system time and date will be  set  from  the  real-time  clock.  The
    Windows  version will restore the time from the file created from the -k
    option.


    n - New calibration

    In order to correct the RTC drift, TAD needs to determine the degree  of
    inaccuracy	of  your  clock.   This  option  is  used  to  start  a  new
    calibration measure. It can either take the time as correct, or use  the
    specified  time.   It  is  also  possible to use this in conjuction with
    "-m", below. It'd be a very good idea not to  change  the  clock  during
    calibration.


    r - Reference

    After the calibration has been started, use this option to	specify  the
    new  correct  time.  TAD will then be able to calculate the proper time,
    compensating for the RTC drift. This option should also be used when the
    time has been changed by another program, otherwise the calculation will
    be off. To do this, use "-r" without a time, or "-rr" with a time.


    m - Monitor

    If you use a time server  on  the  net,  this  option  can	be  used  to
    determine  the  change in time without the need to specify it. It can be
    used in conjunction with "-n" (ie. "-nm") or  instead  of  "-r  <time>".
    Just remember to run TAD before the time server.


    d - Drift

    This is the option that actually corrects the time, based on the  values
    given by "-n" and "-r". It should be placed in AUTOEXEC.BAT/Startup.


    v - View

    Displays the details of the calibration.


    q - Quiet

    Prevents the display of the time when it is  set,  or  calibration/drift
    details.   It can also be used with the clock, leaving no output when it
    is finished.


    e - Exit code

    Select what you would like the program to return by  specifying  one  of
    the following values immediately after the 'e':

	h - hour (0..23)		     d - day of month (1..31)
	m - minute (0..59)		     M - month (1..12)
	s - second (0..59)		     y - year (00..99)
	D - day of week (0..6, 0 = Sunday)   Y - century (19, 20)

    The day of the year cannot be returned because it exceeds 255  (although
    this is no longer true on Windows, it is still not yet available).


    You will probably experience a slight delay when  using  options  "-tt",
    "-s" and "-k". It is caused by waiting for the RTC to change to the next
    second.


    ===========
    Calculation
    ===========

    To calculate the duration between two times, separate them with  a	plus
    ('+') or minus ('-') sign.  If either time is left out, the current time
    will be used. An equal sign ('=') followed by a letter can  be  used  to
    choose how the duration will be displayed:

	s - seconds	w - weeks
	m - minutes	M - months
	h - hours	y - years
	d - days

    The default is to use years, months and days; "=y" will  use  years  and
    days.  For example, to find out how old I am:

	C:>tad 15/1/1974 -

	27 years, 5 months and 6 days.

	C:>tad 15/1/1974 - =y

	27 years and 157 days.

	C:>tad 15/1/1974 - =d

	10,019 days.


    Durations can also be specified, by using the  same  letters  as  above.
    For example, when will I be 20000 days old?

    C:>tad 15/1/1974 + 20000d -f "You will be 20,000 days old on $D, $d $M, $Y."

    You will be 20,000 days old on Wednesday, 18 October, 2028.

    C:>tad 15/1/1974 - 18/10/28

    54 years, 9 months and 3 days.

    C:>tad

    20:25:21  Thursday, 21 June, 2001

    C:>tad - 9h "It is $a ($p) in England."

    It is twenty-five past eleven (am) in England.


    Durations can be added and subtracted, too.  For  this  purpose,  months
    alternate between 30 and 31 days, with the twelfth month having 30 days,
    or 31 in a leap year. Years obey the normal rules - 12 months, 365 days,
    366 in a leap year; every fourth year is a leap year, every hundredth is
    not, but every four-hundredth is.


    ============
    Return Value
    ============

    The default return value (ERRORLEVEL)  is  the  current  10-minute	time
    interval.  Hourly quick reference:

	     Midnight	 0	      Noon     72
	      1:00am	 6	     1:00pm    78
	      2:00am	12	     2:00pm    84
	      3:00am	18	     3:00pm    90
	      4:00am	24	     4:00pm    96
	      5:00am	30	     5:00pm   102
	      6:00am	36	     6:00pm   108
	      7:00am	42	     7:00pm   114
	      8:00am	48	     8:00pm   120
	      9:00am	54	     9:00pm   126
	     10:00am	60	    10:00pm   132
	     11:00am	66	    11:00pm   138

    If the help was displayed, no time/date  was  specified  with  "-k",  or
    there was trouble with the calibration file, 255 will be returned.

    Have a look at greet.bat for a simple use of the return value.


    ===============
    Acknowledgments
    ===============

    Ralf Brown's Interrupt List and Bob Stout's C Snippets.
    Waldemar Schultz <schultz@ma.tum.de> for German language support.


    =======
    Contact
    =======

    jadoxa@yahoo.com.au
    http://tad.adoxa.cjb.net/

    Jason Hood
    11 Buckle Street
    North Rockhampton
    Qld 4701
    Australia


    ============
    Distribution
    ============

    The original zipfile can be freely distributed, by any means. However, I
    would  like  to  be  informed if it is placed on a CD-ROM (other than an
    archive compilation).  Modified versions may be distributed, as long  as
    the original zipfile is included (I would prefer to be contacted).


    =============================
    Jason Hood, 23 October, 2004.
