                         #######
                            #     #    #  #####
                            #     #    #  #
                            #     ######  ####
                            #     #    #  #
                            #     #    #  #
                            #     #    #  #####

###
 #   #    #  #####  #####  #      #      #   ####   #####  #    #  #####
 #   ##   #    #    #      #      #      #  #    #  #      ##   #    #
 #   # #  #    #    ####   #      #      #  #       ####   # #  #    #
 #   #  # #    #    #      #      #      #  #  ###  #      #  # #    #
 #   #   ##    #    #      #      #      #  #    #  #      #   ##    #
###  #    #    #    #####  #####  #####  #   ####   #####  #    #    #

      ######
      #     #  #####  #####    ####    ####   #####  #####  #####
      #     #  #      #    #  #    #  #    #    #    #      #    #
      ######   ####   #####   #    #  #    #    #    ####   #    #
      #   #    #      #    #  #    #  #    #    #    #      #####
      #    #   #      #    #  #    #  #    #    #    #      #   #
      #     #  #####  #####    ####    ####     #    #####  #    #



       Copyright (C) 1996 by Fulvio Marino.  All rights reserved.


                             +-----------+
-----------------------------|  PREFACE  |------------------------------
                             +-----------+


   Not freeware!  Please read the legal stuff at the end of this
document.  Thank you.

   Registered programs will not display the copyright notice; this is
the one and only difference between unregistered and registered
versions.


   This document explains the installation and the use of the
Intelligent Rebooter command and describes the operations which may be
performed with it.

   The main part of the manual is aimed at the user of any DOS based
computer, who may or may not have previous experience of a DOS
environment.


               +----------------------------------------+
---------------|  WHAT IS "THE INTELLIGENT REBOOTER" ?  |---------------
               +----------------------------------------+


   Any PC user should check data consistency on her/his system(s)
periodically, with appropriate tools.  A good idea is to perform this
check automatically, for example by inserting it into the AUTOEXEC.BAT
file, but this way is time consuming and, usually, people don't like it.
So, PCs are often checked too late, when the damage is too big to be
recovered.

   The Intelligent Rebooter is the solution: at boot time, it launches
your check-programs only in case of necessity.  At shutdown time, the
Intelligent Rebooter offers a wide range of features to secure you
against data loss: its target is to stop the PC in a reliable way.


   The Intelligent Rebooter is a reliable tool to stop and/or to restart
your computer so to minimize both the possibility of data loss and the
boot time.  It is fully configurable and may be adapted to a wide
variety of user's needs.  In the event of malfunctions, it may stop,
ignore them, or ask for user intervention.  External programs can run
it, thanks to the silent option (no message is displayed).  The std-I/O
option allows to run it also from a remote session (f.e., a modem
connection, or any other way that allows a program to be executed,
interactively or not).  The Intelligent Rebooter may:

        * flush disk caches

        * park the heads of hard disks

        * halt/reboot PC (in 8 different ways)

        * after a PC crash, run (at boot time) your preferred
          diagnostic/recovery procedure (such as SCANDISK)


                       +------------------------+
-----------------------|  HW & SW REQUIREMENTS  |-----------------------
                       +------------------------+


   The Intelligent Rebooter can be run on any DOS based PC.  The DOS
operating system must be 3.1 or greater (however, 6.0 or greater is
recommended).


   The following disk caches are supported:

- SMARTDRV.SYS v3.x (the "SMARTAAR" cache control device -- untested)
- SMARTDRV v4.00 or greater
- NCACHE-F (Norton Utilities v5)
- NCACHE (Norton Utilities v6)
- NCACHE2 (Norton Utilities v7 or greater)
- caches compatible with the above listed ones


   The program is able to detect if one of the following multitaskers is
running:

- MS Windows/386 v2.x
- MS Windows v3.0 or greater (Win95 included)
- DESQview v1.x or greater
- multitaskers supporting INT 2F/AX=1680 (like OS/2 2.0+, Windows 95,
  Windows NT, those using DPMI 1.0+, etc.)


   Heads of hard disk units may be parked if:

- INT 13/AL=10 is able to detect HDUs
- BIOS supports INT 41 (HDU 0) and 46 (HDU 1 to 3), and is compatible
  with the standard retrieving method (HDU 2 and 3); some PS/2 models
  may fail on these requirements


   This program may operate a reliable reboot (INT 19) if the operating
disk cache flushes its buffers on demand (INT 21, DOS function 0Dh: most
caches do it, included those listed above).  Because interrupt vectors
are preserved, INT 19 usually causes a system hang if any TSRs have
hooked vectors from 00h through 1Ch, particularly INT 08; however, the
Intelligent Rebooter preserves the system integrity anyway: by playing
with a few options (mainly: /W), you could bypass this problem.
Malfunctions in cold boots are common while stealthing ROM BIOS (f.e.,
this may happen with QEMM); boot it warm, instead.


                           +----------------+
---------------------------|  INSTALLATION  |---------------------------
                           +----------------+


A. Copying the files
--------------------

   You need both the executable (HALT.EXE) and the configuration
(HALT.CFG) files.  Copy both of them somewhere on your disks.  In case
of conflicting names, you can rename them, but you must conform to the
following rules.

1. The extension of the program must be .EXE.

2. The program searches for its configuration file in the same directory
   where it resides, with the same name and the .CFG extension.  For
   example, if you install HALT.EXE as D:\PGM\LIB\STOP.EXE, then
   HALT.CFG should be installed as D:\PGM\LIB\STOP.CFG, else you have to
   use the /I option with its full path specification.

   From now on, we suppose that you installed the files into C:\DOS\. by
typing something like

        COPY HALT.* C:\DOS\.

in order to install all the Intelligent Rebooter's related files (.EXE
and .CFG, as well as its .TXT manual).


B. Editing AUTOEXEC.BAT
-----------------------

   Now edit your C:\AUTOEXEC.BAT file, by adding the line

        C:\DOS\HALT.EXE /C

at the very beginning of the file.  This line should be executed before
performing any write access to your hard disks, so to stand the best
chances in recovering your data after a system crash. By default, this
line will execute "SCANDISK /ALL /CUSTOM", and you would like to change
it.  If your DOS is not 6.0 or greater, the line could be (for example)

        C:\DOS\HALT.EXE /CC:\DOS\CHKDSK C:

or, if you own Norton Utilities, your line could sound like

        C:\DOS\HALT.EXE /CC:\NU\ndd C: D: E: J: /Q /FRAME

   Please have a look at the description of the /C option: you will
learn how to start almost everything with it, included .BAT files and
batch files specific to your shell (f.e., .BTMs for NDOS and 4DOS).

All done.  It's ready!


C. How to use it
----------------

   REMEMBER: to reboot, or to switch off your PC, enter the command
"HALT" (or whatever you renamed it to).  This ensures you that PC is
halted correctly (it may even be moved: disks' heads are now parked
safely).  At boot time, disk check will be skipped.

   Use /TY option extensively!  It has been conceived to deeply trace
the activity of the Intelligent Rebooter, so you can see what's really
happening inside it; should its behaviour not satisfy your needs, you
can easily change the configuration (by skipping the halt/reboot phase),
until it works well for you.


                      +--------------------------+
----------------------|  THE CONFIGURATION FILE  |----------------------
                      +--------------------------+


   The configuration file allows you to modify the behaviour of the
Intelligent Rebooter.  Specifications inside this file may be overridden
only from the command line.  In case of multiply defined switches, only
last ones will take place.


   You may insert any legal option; however, /I is ignored for obvious
reasons.

   More options can stay on a same line (as command arguments do), or
may be split on multiple lines (f.e., on one-per-line basis). If you
have a long specification to enter in the configuration file (for /C,
presumibly), you must enter it all on one line.  Options cannot be
"continued" to a second line.


   Blank lines are ignored in the .CFG file and can be used to separate
groups of options.  You can place comments in the file by beginning a
line with a semicolon [;].  You can also place comments at the end of
any line except one containing a /C specification.  To do so, enter at
least one space or tab after the specification, a semicolon, and your
comment, like this:

        /WN       ; on boot request, do it cold (instead of warm)

   If you try to place a comment at the end of a /C specification, the
comment will become part of the /C... string and will probably cause an
error.


   When the Intelligent Rebooter detects an error while processing the
.CFG file, it displays a message containing the line number where the
error is.  This allows you to note any error and to correct it.  A
syntax error causes the program termination.


   NOTE: /C behaves in a slight different way, depending if it comes
from the command line or the .CFG file.  Please read the section
pertinent to this option.


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


   The Intelligent Rebooter is adaptable to every kind of need.  This is
achieved by using options to change its built-in defaults.

   Options may be used on the command line as well as into a
configuration file (seen above).  Built-in defaults are overridden by
the .CFG-level specifications, that in turn may be changed at command
line level.  If an option is defined more than once, only the last
specification on that level will take place.

   A slash (or a minus sign) followed by a letter, like /X (or -X), is
an "option" or "switch" which controls the effect of the command.  The
Intelligent Rebooter has several switches, and you are usually free to
use none, one, or several to make it behave as you wish.  All the
options must be attached to a "value" (mandatory): "/TY" is valid, but
"/T Y" is not.  To avoid ambiguity in case of multi-letter switches (/C,
/H and /I), it is convenient to separate switches with blanks.

   Inside a .CFG file, you can specify all the options (but /I is
ignored, of course).  On the command line, only /T, /H and /I are
compatible with /C, that is always the last option, because the
subsequent characters will become part of the /C specification.

   Here is the description of all the legal options, alphabetically
ordered.


+-------------------+
|  /C[cmd arg ...]  | Default: /CSCANDISK /ALL /CUSTOM
+-------------------+

   This is the most powerful switch: it appears on the command line only
when you need to indicate that your system has to be checked.  Usually
it have to be used only inside your AUTOEXEC.BAT file.

   If the Intelligent Rebooter has not been used to stop (or reboot)
your PC, the line

        C:\DOS\HALT.EXE /C

inside AUTOEXEC.BAT will start the command

        SCANDISK /ALL /CUSTOM

or anything else you specified at command (or .CFG) level.

   There is a fundamental difference on how this program is executed,
depending on where it has been specified: on the command line, or inside
the .CFG file.  In the first case, HALT is replaced in memory by the new
program; in the latter one, HALT is replaced by a copy of your command
interpreter (COMMAND.COM, maybe) that will execute the new program.

   Besides this, you should be aware of the effect on a command line of
the command interpreter: things like redirections and variable
expansions are performed differently, depending on the choosen method.
For example, redirected output on the command line acts for the whole
line (also the messages of the Intelligent Rebooter are redirected),
because the immediate interpretation of the current active shell; inside
the configuration file, on the contrary, only the /C specification will
be subject to redirection (performed by the spawned shell).

   Here we are going to describe in more detail these two methods: you
have to choose the better one, depending on your needs.

Method A - On the command line
--------
   This way is faster and requires less memory: in fact, the specified
command is loaded and executed immediately.  The command is attached to
the switch (for example, to run C:\PGM\MYCMD.EXE you have to specify
/CC:\PGM\MYCMD.EXE).  The following rules are used when parsing
arguments given after the command.

*  Arguments are delimited by white space, which is either a space or a
   tab.

*  A string surrounded by double quotation marks is interpreted as a
   single argument, regardless of white space contained within. A quoted
   string can be embedded in an argument.  Note that the caret (^) is
   not recognized as an escape character or delimiter.

*  A double quotation mark preceded by a backslash, \", is interpreted
   as a literal double quotation mark (").

*  Backslashes are interpreted literally, unless they immediately
   precede a double quotation mark.

*  If an even number of backslashes is followed by a double quotation
   mark, one \ is placed in the argument for every \\ pair, and the " is
   interpreted as a string delimiter.

*  If an odd number of backslashes is followed by a double quotation
   mark, one is placed in the argument for every \ pair, and the " is
   escaped by the \ remaining, causing a literal " to be placed in the
   argument.

   The following list shows the interpreted result passed to the first
three arugents for several examples of command-line arguments.

        Command-Line Input      arg #1     arg #2     arg #3

        "a b c" d e             a b c      d          e
        "ab\"c" "\\" d          ab"c       \          d
        a\\\b d"e f"g h         a\\\b      de fg      h
        a\\\"b c d              a\"b       c          d
        a\\\\"b c" d e          a\\b c     d          e

For example,

        HALT /CCOMMAND /C ECHO "a   " "b\"c" "\\\"d"      e

will produce on output:

        a    b"c \"d e

   The started command may be an .EXE, .COM, or .BAT file; in the latter
case, a command interpreter is spawned in order to execute the batch
file: the Intelligent Rebooter refers to the COMSPEC and PATH
environment variables that locate the command-interpreter file (the file
named COMMAND.COM in MS-DOS), so be sure of their correctness before
using this feature.

Method B - Inside the .CFG file
--------
   This method spawns a copy of the command interpreter: if compared to
the previous method, it is slower (.EXE and .COM are not loaded
directly) and requires more memory (because of the new command
interpreter). On the other hand, argument specifications are simpler,
and it is also possible to run batch files specific to a command
interpreter (like .BTM files for NDOS and 4DOS).

   The COMSPEC and PATH environment variables (that locate the
command-interpreter file and the command to execute) must allow the
Intelligent Rebooter to find both of them.

   Arguments to the command must be written literally: what you type (up
to the end of line) is passed as is to your shell.

   To obtain the same output result of the example shown above, you
should add the following line

        /CECHO a    b"c \"d e

to the .CFG file, then run the command

        HALT /C

The result may differ if your command interpreter is not COMMAND.COM,
because a (possible) different behaviour of a not standard interpreter.


+-------------+
|  /F{Y|N|A}  | Flush cache. Default: /FY
+-------------+

   By default, the Intelligent Rebooter tries do detect any running DOS
disk cache, then flushes any not-empty, write-ahead buffer.  In case of
error, the program terminates immediately.

   By specifying /FA (Ask mode), if any error occurs while flushing
buffers, the program asks you about continuation.

   In very special situations, you may disable this feature (/FN).


+-----------+
|  /Hfname  | Halt sentinel name. Default: /HC:\HALT.!!!
+-----------+

   This is the name of the file that is created by the program before
rebooting or halting your PC.  At boot time, the /C... command is
executed only if this file does not exist, otherwise it is removed.


+-----------+
|  /Ifname  | Init file. Default: /I<full-qualified-pgm-name>.CFG
+-----------+

   Use this option to specify a different configuration file than the
default one.  Mainly, the switch has been conceived to be used on PCs
with several different system configurations in CONFIG.SYS.

   /INUL will ignore any configuration file (as well as any registration
key stored herein, of course).


+-----------+
|  /K{Y|N}  | Keyboard monitoring. Default: /KY
+-----------+

   By default, the program ignores Ctrl-C, Ctrl-Break and Ctrl-Alt-Del
by monitoring the keyboard controller.  If the standard input is not the
PC keyboard, you must specify /KN, so to run the Intelligent Rebooter
from any type of remote connection.

   PLEASE NOTE: with /KN, input is line buffered, so, after having typed
a key, you need to send a carriage-return-line-feed pair by pressing the
Enter key (or its equivalent) on the (possibly) remote keyboard.  This
unpleasant side effect is required to warrant the compatibility with
every kind of remote access.  Please note also that Ctrl-Alt-Del is no
longer ignored!


+-----------+
|  /M{Y|N}  | Message at end. Default: /MY
+-----------+

   Depending on your configuration (see the /O switch), the program will
show you a specific message, indicating the allowed action(s) (switch
off the PC, reboot, continue).  With /MN, this message is not printed:
the program will operate silently.  This behaviour allows you to put
your own messages before calling the Intelligent Rebooter from any
driving program.

   Errors and queries for continuation (if enabled) cannot be blacked
out.


+------------+
|  /O{0..7}  | On-exit behaviour. Default: /O0
+------------+

   Once the program has stopped the PC successfully, it will allow you
only few actions (or none at all), depending on this option.

/O0 Switch off PC, or type R to reboot, or C to continue.

/O1 Switch off PC, or type C (continue).

/O2 Switch off PC, or type R (reboot).

/O3 Switch off PC, hit any key to continue.

/O4 Switch off PC, hit any key to reboot.

/O5 Terminate the program (go back to the caller)

/O6 Reboot immediately.

/O7 Force to switch off PC (locked keyboard).


+-------------+
|  /P{Y|N|A}  | Park heads. Default: /PY
+-------------+

   By default, the program parks disk heads to a safe zone (the landing
zone, if any, or the last cylinder).  On few HDU types, this may be not
possible: use /PN to disable parking (because any error causes the
program to exit immediately).  The asking mode (/PA) forces the program
to prompt you for continuing in case of error: this is useful if not all
HDUs can be parked successfully (f.e., because a defective unit).


+-------------+
|  /S{Y|N|A}  | Stop on multitasking. Default: /SY
+-------------+

   The program won't run in multitasking environments (like Windows),
because disk multi-activities cannot be controlled.  However, you may
want to try to run it anyway for some valid reason.  /SN disable the
multitasker detection, and /SA asks you if the program must be continued
in case a multitasker is running.

   Be very careful with this switch: you are on your own, and you should
use it only if you are sure of what you're doing.


+-----------+
|  /T{Y|N}  | Test configuration. Default: /TN
+-----------+

   This option is very useful: it allows you to see, debug and test the
Intelligent Rebooter's activity, depending on your specific
configuration. With testing enabled (/TY), the program displays all its
job in depth:

        * the type of a (possibly) running multitasker

        * disk cache type, if any, and its flushing

        * which, how and where disk heads are parked

        * keyboard management

        * other useful tracing messages

   At the very end, there will be no reboot anyway, so you can quickly
modify your configuration if it does not match your needs.


+-----------+
|  /W{Y|N}  | Warm boot. Default: /WY
+-----------+

   Here you decide if boots performed by the Intelligent Rebooter have
to be warm or cold.  Warm boots are similar to Ctrl-Alt-Del boots, cold
boots are more likely hardware resets, but this is not always true, and
may vary, depending on both the specific HW and SW platforms used.
Usually, warm boots are faster and more reliable.


                         +-------------------+
-------------------------|  AKNOWLEDGEMENTS  |--------------------------
                         +-------------------+


1. Ralf Brown's MSDOS Interrupt List

   The DOS Programmer's Bible: nothing more, nothing less.

        ftp://ftp.simtel.net/pub/simtelnet/msdos/info/inter*.zip
        http://www.simtel.net/pub/simtelnet/msdos/info/inter*.zip


2. Bob Stout's C-snippets Collection

   The best C-programmer's Survival Code, maybe.

        ftp://ftp.simtel.net/pub/simtelnet/msdos/c/snip*.zip
        http://www.simtel.net/pub/simtelnet/msdos/c/snip*.zip


3. XPACK, An Executable and DiskImageFile Compressor (public domain)

   By JauMing Tseng, IMHO it's the best public-available compressor.

        ftp://ftp.simtel.net/pub/simtelnet/msdos/execomp/xpack*.zip
        http://www.simtel.net/pub/simtelnet/msdos/execomp/xpack*.zip


                         +--------------------+
-------------------------|  ABOUT THE AUTHOR  |-------------------------
                         +--------------------+


   You can contact Fulvio Marino (the author) at

        Internet address: fulvio@ico.olivetti.com
        X-400 address:
                Marino Fulvio (DIV.S.S - C.C. AB2 e Visual)
                fulvio$$ivrea-systest$olivetti$eolico$master400$it

   Here is a short summary of its travel inside the world of computers.

'79-'81 Realization (Apple, BASIC) of a store-bookkeeping program
'82     Faculty of Economy and Commerce: simulation of economics models
        (PDP-11, Fortran IV)
'83     Co-ordination of the project group for the global informational
        system in an italian company. (VAX/VMS, Fortran 77)
'84     Analist in a business management project (IBM 370 TSO/ROSCOE,
        COBOL) and in an Analogic/Digital conversion of prototipal
        data collection (PDP-11 VAX/710 w/VMS, Fortran IV & TOTAL-IMS)
'85-'86 Senior programmer ("C") in the realization of an emulated Unix
        system over an existing OS (MOS, Unix)
'87-'89 Porting of Unix on new hw platforms ("C")
'90-'93 Development, integration, support and maintenance of a Unix
        system (analist and programmer).  Fire-fighter on communication
        (LANs) and security problems.  Unix internals (BSD, SVR4).
'94-'96 Development, system test and tuning of hybrid solutions (DOS,
        Windows 3.11/95/NT, Unix) for European customers and/or partners


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


License agreement
-----------------

   "The Intelligent Rebooter" Copyright (C) 1996 by Fulvio Marino.  All
rights reserved.

   Permission to use, copy, and distribute the Intelligent Rebooter (the
"program") for any non-commercial and non-profit purpose is hereby
granted without fee, subject to the following license:

1. Any copy of the program must include the above copyright notice and
   this license.

2. Fulvio Marino (the "author") makes no warranty or representation that
   the operation of the software in this program will be error-free, and
   the author is under no obligation to provide any services, by way of
   maintenance, update, or otherwise.  THE SOFTWARE AND ANY
   DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED
   WARRANTY INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
   MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
   WILL THE AUTHOR OR ANY OTHER CONTRIBUTOR BE LIABLE FOR DIRECT,
   INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF THE AUTHOR HAS BEEN
   ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

3. Users will not use the name of the author nor any adaptation thereof
   in any publicity or advertising, without prior written consent from
   the author in each case.


Cardware Status and Registration
--------------------------------

   The Intelligent Rebooter is not shareware, nor freeware: it is a
cardware program.

   Nobody works free in exchange for something, but the author wants
very little. To use this program in some way and not send him a postcard
is as unethical as not paying money when taking a newspaper from a gas
station.

   To register this program, please send a *postcard* to the author.
This gives you full rights to use all functions of the program, with the
only restriction being that you cannot charge other people for the
program and you cannot use it on (or from) computers having commercial
and/or profit functions.  The user can *freely* give a copy of the
program to anybody, and they must register themselves if they decide to
use the Intelligent Rebooter.  Send all postcards to:

                        Fulvio MARINO
                        via San Rocco 30/E
                  10090 Romano Canavese (TO)
                        Italy

   Registered users who send an e-mail (electronic) address in the
postcard will receive by Email their own registration key.

   Public domain and shareware distribution companies may charge a
little fee to distribute this program with other programs in CD-ROM,
disk, or any other media.  People who obtain the Intelligent Rebooter
from these sources should still register with a postcard.

Restrictions on Commercial Use
------------------------------

   The cardware version of the Intelligent Rebooter is for personal,
non-commercial use.  For commercial use, contact the author.  If you
want to turn this program into a commercial product and make money
selling it, then you must agree with the author on a way for him to also
make money on it.
