      +-----------------------------------------------------+
      |                                                     |
      |   DDDDD    OOOOO   SSSSS    CCCCC HH   HH KKK  KK   |
      |    DD DDD OO   OO SS   SS  CC   C HH   HH  KK  KK   |
      |    DD  DD OO   OO SSS     CC      HH   HH  KK KK    |
      |    DD  DD OO   OO   SSS   CC      HHHHHHH  KKKK     |
      |    DD  DD OO   OO     SSS CC      HH   HH  KKKK     |
      |    DD DDD OO   OO SS   SS  CC   C HH   HH  KK KK    |
      |   DDDDD    OOOOO   SSSSS    CCCCC HH   HH KKK  KK   |
      |                                                     |
      +-----------------------------------------------------+
      |          Release 2.3 - 1st November 1997            |
      +-----------------------------------------------------+



Author: Bob Stammers, Saphena Computing, Hants, UK

 email: saphena@compuserve.com

   url: http://ourworld.compuserve.com/homepages/saphena/year2000.htm


+---------------+
|   OVERVIEW    |
+---------------+

DOSCHK is a small utility with two main uses both related to the year
2000 problems associated with date handling on computer systems.  The
first use is as a simple demonstration to PC users that the year 2000
issues do affect them.  The second use is in acting as a compliance
tester for PCs.

DOSCHK demonstrates that for the vast majority of PCs the transition
from 1999-12-31 to 2000-01-01 will require manual intervention by their
users.  In short, very few PCs will manage the transition unaided.

This problem has arisen as a direct consequence of the widespread use
of only two decimal digits being used to store and manipulate the year
component of dates.  When the AT class PCs were designed, the year held
in the CMOS RAM was stored as two decimal digits, the century was added
in a separate field at a later date.  When the year is incremented from
99 (as in 1999), it will return to 00 and the century field is NOT
incremented.  This results in the year 1900 rather than 2000 being held
in the CMOS RAM.


+-----------------+
|   LEGAL STUFF   |
+-----------------+

DOSCHK is copyright (c) 1997 Bob Stammers

For personal use, permission is granted to freely copy, distribute and
use this program in its complete, unmodified, form.   For business use,
the program may only be used for evaluation purposes.

A low-cost, Licensed, version is available for business use as well as
customised versions for commercial distribution purposes. Please contact
the author for details.

Every effort has been made to make this software accurately test the
DOS, BIOS and CMOS clocks for correct performance during the transition
from 1999-12-31 to 2000-01-01 and this is its sole purpose.   The 'IBM
compatible PC' is an open and developing standard and no legal liability
is accepted for failure of this function or any of its consequences.

No other warranty of fitness for purpose is expressed or implied.  Each
user is advised to test the software for suitability for his own purpose
including but not restricted to the above instance.



C O N T E N T S
===============
Applying a DOSCHK registration
Forms-mode configuration
Commandline options
Return codes (errorlevels)
Contents of DOSCHK.DBG
Notifiable conditions
How it works



+----------------------------------+
|  APPLYING A DOSCHK REGISTRATION  |
+----------------------------------+

Registered users are supplied by email with a "registration key" (a
large number) which is used to register their copy of DOSCHK.

Having acquired a registration key from the author, any version (1.3
onwards) of DOSCHK may be made registered using the following
commandline syntax:-

    DOSCHK "<registeredname>" <regkey> -Y

eg:-

    DOSCHK "SPURIOUS UNLICENSED USER" 2328318738 -Y

The registered status will be reflected immediately.

Alternatively, users of version 2.0 onwards may use the forms-mode
interface (see below).


+------------------------------+
|   FORMS-MODE CONFIGURATION   |
+------------------------------+

On startup, pressing F1 will open the forms-mode configurer.  This enables
program registration and option selection using an full-screen, intuitive,
keyboard interface.

Text fields with full editing are provided for entry of registration details.

All other options are selected using multiple choice selectors. (See below).

Press F10 to permanently save the configuration.


REGISTERED USERS
----------------
Registered users are offered a second set of options enabling them to change
the caption appearing on the front screen as well as the text and colour of
the first four lines of text appearing on the front screen.

They can also decide whether or not to show the weekend count and whether or
not to offer the full-screen configuration mode.

An additional DOSCHK.DBG facility is available which will quietly write the
debug file to the drive/directory containing the DOSCHK executable.

An additional commandline option is available which allows for inclusion of
individual machine identification in DOSCHK.DBG output.

Registered users are also able to set an option that will cause a result
of "nearly compliant" to be reported as fully compliant.  This is achieved
by testing only the second set of post-midnight readings.


-----------------------------------------------------------------------------
The rest of this document is aimed at "technical support" personnel who
wish either to understand DOSCHK's workings or to manipulate its
behaviour in some way.
-----------------------------------------------------------------------------


+--------------------------+
|   COMMANDLINE OPTIONS    |
+--------------------------+

DOSCHK accepts several commandline options, each of which must be
preceded by a '-' (ASCII 2D) or a '/' (ASCII 2F) character. The options
are:-

?       Shows DOSCHK identification and brief usage help

!       Shows DOSCHK debug information at the end of a run
        If combined with "  > DOSCHK.DBG ", this may be used to trap
        machine-specific information.

!!      Writes DOSCHK.DBG to disk in the drive/directory holding the
        DOSCHK executable.            ONLY AVAILABLE TO LICENSED USERS

M       Captures a machine identification string either from the rest
        of the commandline, from a diskfile, from an environment
        variable or from user input.  ONLY AVAILABLE TO LICENSED USERS

        Without qualification, any remaining words not prefixed by '-'
        or '/' are gathered into a single line of text reported as the
        Machine ID in the debug output.  If no words are found, then
        the user is prompted to enter a machine identification string.

        For example, the command:-  DOSCHK -M BOB'S MACHINE -!  will
        include the line "Machine ID: BOB'S MACHINE" in the debug text.

        If the 'M' is immediately followed by an 'F', then the next
        word on the commandline (with or without a prefix) is the
        name of a diskfile containing a single line of text used as
        the machine identification.  eg:  DOSCHK -MF MACHINE.ID -!

        If the 'M' is immediately followed by an 'E' then the next
        word is the (case sensitive) name of an environment string
        containing the machine identification.  nb: the command:-
        "doschk -me comspec -!" will usually prompt the user for
        input whereas "doschk -me COMSPEC -!" will capture the string
        "C:\COMMAND.COM" (or whatever).

        In either of these cases (MF/ME), any unprefixed words on the
        commandline will be appended to the text.



Wnn     Sets the number of seconds to wait having set the clock before
        midnight.  The default is 10 and the valid range is 10 to 100

        NB  This parameter must be at least 5 seconds longer than the
        'S' parameter below and will be corrected to this if a smaller
        value is specified.


Snn     Sets the number of seconds before midnight to set the clock.
        The default is 5 and the valid range is 5 to 60

F:n     Controls leap year testing.  By default, DOSCHK will quietly
        test the rollover from 2000-02-28 to 2000-02-29 and will
        report to the user only if the test fails.  If this option is
        used with no ":n", then the test is carried out with a full
        countdown and report.

        The :n parameter is a number comprised of two components.
        1 = Quiet test, 2 = Loud test
        4 = Report on fail, 8 = Always report.
        eg: :n = 9 = Quiet test but always report

        If a full test is specified then it will ONLY be executed if
        the user does not press [Esc] after the first test.

In      Sets the idle calls value.  0 = no idle calls are made.
        1 = DOS idle calls are made, 2 = Windows idle calls are made,
        3 = DOS and Windows idle calls are made.

R[!]    Skip the initial 'OK to proceed' question, assume OK
        If the '!' is included, then when showing the results screen,
        a keypress of CR is assumed rather than waiting for a key.
        Any actual keypress is ignored.

T       Suppress both the 'Simple Fix' text on failure messages and
        the 'story display' at the end of the run.

T:n     Selectively display texts.   1 = DO show story, 2 = DO show
        'simple fix', 3 = show both texts.

P       Suppress the print feature.

DST     Suppress the Daylight Savings Time notices.  In wintertime,
        the DST adjust feature of Win95 does not interfere with the
        rollover testing and, consequently, there is no need for the
        user to alter the system settings.


If the LAST argument on the commandline is  -X, then all the preceding
commandline options are saved as the default settings for future runs.
eg: If you want DOSCHK always to suppress the story by default then

    DOSCHK -T:2 -X

The story may still be shown on future runs by adding the commandline
option  -T:3


+--------------------------------+
|   RETURN CODES (ERRORLEVELS)   |
+--------------------------------+

DOSCHK returns one of the following return codes on termination:-

0 = ALL DATES OK, system is year 2000 compliant to CL4
1 = DOS ok, BIOS ok, CMOS bad (CL3)
2 = DOS ok, BIOS/CMOS bad (CL2/BF)
3 = Run invalidated by suspected daylight savings option
4 = All dates bad
5 = Nearly compliant (see below)

These codes may be useful in batchfile procedures.

DOSCHK checks for true compliance (within a small tolerance) of the RTC
as well as the BIOS and DOS itself. Many machines achieve RTC compliance
by means of the BIOS updating the RTC during a readclock request. If no
readclock instruction is processed by the BIOS, the RTC is not compliant

In checking the various settings at the end of a rollover test, DOSCHK
issues a readclock instruction to the BIOS thereby initiating the RTC
correction.  DOSCHK obtains two complete sets of readings at the end of
the run and, if the first shows "1900" but the second shows "2000", it
will report a status of "nearly compliant".


+----------------+
|   DOSCHK.DBG   |
+----------------+

The output from a debug run (with -!) on the commandline looks like the
following:-


** DOSCHK DEBUGGING INFORMATION **  mailto: saphena@compuserve.com

 Operating System: MS-DOS v6.22         DOS BOX                    :1
   BIOS Copyright: (C)1985-1994,American Megatrends Inc.,All Rights:2
     BIOS Version: 10/10/94                                        :3
        Processor: 80486                  (fc,1,0)                 :4
        CMOS Date: 1996-11-28 1999-12-31 1900-01-01 2000-01-01 [3] :5
        CMOS Time:  00:18:21   23:59:55   00:00:05   00:00:05      :6
        BIOS Date: 1996-11-28 1999-12-31 2000-01-01 2000-01-01     :7
        BIOS Time:  00:18:21   23:59:55   00:00:05   00:00:05      :8
         DOS Date: 1996-11-28 1999-12-31 2000-01-01 2000-01-01     :9
         DOS Time:  00:18:21   23:59:55   00:00:05   00:00:05      :0
   CMOS Status(B): 2   (D) ok  Conditions: 0   BiosCFlag: 0        :A
          Results: ExitStatus: 5;  RTC 0     BIOS OK               :B
      Wait Params: 5       10       Dos   Win                      :C
         Feb CMOS: 1997-03-01  2000-02-28  2000-02-29              :D
         Feb BIOS: 1997-03-01  2000-02-28  2000-02-29              :E
         Feb  DOS: 1997-03-01  2000-02-28  2000-02-29              :F
  Program Version: 2.3  Oct 30 1997, 21:47:17      #CE44;          :G

To save these details to disk, rerun as:-     DOSCHK -! > DOSCHK.DBG


This text contains 17 lines containing significant information noted
above as :1 .. :G.  The lines are:-

:1 Shows which version of DOS is being used and whether or not DOSCHK
   was run inside a Windows DOS box rather than from naked DOS

:2 Shows the BIOS copyright string located within the ROM area

:3 Shows the BIOS version date in the format mm/dd/yy.  If YEAR2000.EXE
   is detected during the run, this line will contain "YEAR2000 Detected".

:4 Shows what kind of processor, 386, 486, etc and the machine ident
   bytes returned from the BIOS

:5 .. :0 Show for each of CMOS, BIOS and DOS, the dates and times
   returned at BOJ, after setting the clock to just before midnight
   and when checking the clock after the rollover.

   The [3] shown on line :5 only appears on the listing of a CL4 machine
   and indicates the number of clock ticks elapsed between the year
   change and the century change.

:A Shows the contents of CMOS status register (B), whether or not the
   CMOS battery was reported as ok, any DOSCHK notifiable conditions and
   the state of the carry flag on return from a BIOS read.

:B Shows the results:- DOS ERRORLEVEL returned, RTC addr   BIOS status.

:C Shows DOSCHK run parameters:- S, W, I

:D..:F Show the dates read during leap year tests for CMOS, BIOS and DOS

:G Identifies the version of DOSCHK

RTC=0=No RTC detected, 1=CMOS RTC, other=base address of external card
BIOS status is either OK or NG meaning BIOS RTC not implemented


+---------------------------+
|   NOTIFIABLE CONDITIONS   |
+---------------------------+

There are one or two conditions which DOSCHK can detect which OUGHT not
to happen.  In order to ensure that such conditions are identified and
reported, DOSCHK will force on its debug display if such a condition is
detected.  Currently only two conditions fall into this category being:

1) The CMOS checksum failed but the system is neither a PS/2 nor an XT
2) The CMOS clock settings are stored in binary rather than BCD


+------------------+
|   HOW IT WORKS   |
+------------------+

Until the arrival of the AT class machines the system clock was set by
the user at bootup time and maintained by DOS thereafter. These systems
will roll correctly to 2000-01-01 if they're left running and will need
to be told the date and time on bootup in any event.

The AT class machines have a small area of battery backed CMOS memory
which is used by the real-time clock chip to maintain the date and time
when the machine is switched off.  The date is held in three separate
BCD (Binary Coded Decimal) fields for year, month and day.  A fourth
field is used to hold the century and is not normally updated by clock
ticks in the same way as the other three.

The BIOS provides APIs for accessing this real-time clock information
and the CMOS locations of the various fields are also in the public
domain.  Most versions of DOS maintain the date separately from this
real-time clock based information and this gives rise to the situation
in which there are actually three sources of clock data.

DOSCHK starts by saving the current date and time as reported by DOS.
It then sets the date and time using DOS interrupt 0x21, 0x2B/0x2D to
five seconds before midnight on 1999-12-31.  The clock settings are
then read back for debugging purposes using:-

        DOS     interrupt 0x21, 0x2A/0x2C
        BIOS    interrupt 0x1A, 0x04/0x02
        CMOS    direct port addressing

It then waits ten seconds, re-executes the three reads and reports its
findings.  DOS is then instructed to reset the date and time using the
saved settings as adjusted by the number of recorded ticks during the
run.  The tick count is achieved by hooking vector 0x1C.

On pre-AT machines (with no CMOS/RTC), DOSCHK will go through the steps
and will report BATTERY! for the CMOS readings. The BIOS calls are made
and the readings reported although these will be garbage.

In practice, the BIOS readings may differ from the CMOS readings because
some BIOS manufacturers have inserted code into the readclock logic to
"correct" bad readings from the CMOS.  This means that, particularly in
new machines, the BIOS will report the new date as 2000-01-01 when the
CMOS values actually state 1900-01-01.

Some BIOSes also have code built into their bootup logic to correct the
bad clock setting. This means that carrying out the well known reboot
test will not demonstrate the problem.

Some versions of DOS reload the DOS clock at the point of rollover
rather than waiting for a reboot.  In these cases, when DOS is given a
'bad' date such as 1900-01-01 its response is to reset its clock to the
DOS "day 0", usually 1980-01-04.  In some cases, however, DOS appears
to have chosen an alternate course which is to NOT update its clock,
leaving it instead at 1999-12-31.
