
				 Time and Date

			   Copyright Jason Hood 2001

			     Freeware. Version 2.00


 ===========
 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). 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 after
 the hour is required. If the minutes or seconds are left out, they will be set
 to zero.

 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).

 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 the
 month and/or year is left out, they are taken as current.

 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
	-s	set the system time/date from the real-time clock
	-k	set system time/date, keep the RTC as is
	-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


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

 17:08:27  Thursday, 21 June, 2001


 b - Brief (concise) time

 The date will be displayed using the 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 has an effect on 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 that the week is taken from 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"). '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
 COUNTRY setting); 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 that invalid times will be allowed.


 tt - Test times

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


 s - System from RTC

 The system time and date will be set from the real-time clock.


 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".


 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.


 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.


 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@hotmail.com
 http://adoxa.tsx.org/

 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, 30 June, 2001.
