SANE
====

Overview:
--------
This is an all-in-one reboot and shutdown program for DOS that works on any 
PC, even on ancient 8088 XT and, of course, on a modern ATX one, where it 
actually powers down the system. It also has a few extras like BIOS password 
resetting and attempts to stabilize DOS when chaos ensues.

If ran without any parameters, SANE will attempt to stabilize DOS by 
performing the following actions: normalizing text screen mode and resetting 
its video attributes, switching to the default video page, restoring the 
cursor to normal shape, flushing the keyboard buffer, silencing the internal 
audio speaker, muting any AdLib/OPL2 at port 388h, and finally resetting 
the 8253 timer.

Before any shutdown or reboot occurs, SANE will first notify Microsoft 
Network Client and Novell NetWare. Afterwards, it will flush DOS cache 
programs, and then perform a DOS file system and disk reset routine on all 
available drives.  

Partial list of DOS Cache programs that get to be flushed before any shutdown 
or reboot:
          CD Blitz, Norton Cache, Novell NWCACHE, PC-Cache, PC Tools, QCache, 
QuickCache, SmartDrive, Super PC Kwik, and plenty others that have a routine 
checking interrupt 13h.

In any case, by default, SANE will display text messages that allows users 
to follow each internal process as it is being carried out. Redirect to NUL if 
you don't want them displayed (Example: SANE /Y >NUL).

Built-in help can be accessed by entering SANE with any of these parameters:
/?, /h, -?, -h or any non-existent parameter. 

Buitin help:
-----------

SANE - Powers off, reboots, resets system values, and stabilizes DOS.
Version 2.34 - Copyright (C) Ignacio F. Gully

Syntax:
  SANE [/Y] [/S] [/R] [/W] [/F] [/B] [/X] [/Z] [/C] [/V] [/D] [/E] [/K] [/H]

Options:
  [/Y] Shuts down the system.
  [/S] Shuts down the system for long term storage. This option includes
       drive parking and Dallas RTC battery preservation.       
  [/R] Cold system reboot.
  [/W] Warm system reboot (Not recommended).
  [/F] Fast DOS restart (May crash your computer!).
  [/B] Removes BIOS password and sets CMOS values to default (Expert use only).
  [/X] Performs a DOS stabilization process using a 40x25 text mode.
  [/Z] Forces to stabilize the current DOS system using an 80x25 text mode.
  [/C] Only flushes all drive caches (without performing any other action).
  [/V] VGA card BIOS re-initialization (font and gamma to default values).
  [/D] Disables VGA video card output.
  [/E] Re-enables VGA video card output.
  [/K] Disables any video card output until a keyboard key is pressed.                             
  [/H] Hibernates your PC, suspending CPU execution to preserve the most power. 
       Requires APM (Advanced users only!).
       
                             ----------------
  
Note that SANE without any option will attempt to stabilize the current DOS 
system. It will use a default text screen mode of 80x25. Use /X for 40x25 mode.
 
SANE /Y performs what can be considered a safe shutdown for DOS, powering off 
your computer automatically if it is supported by hardware. If not, it will 
prompt you to manually switch your computer off.

Please be aware that there is now an external executable module included, 
called ACPITOOL.BIN, that must be present in the same directory as SANE.COM in 
order for it to perform the newer ACPI power down operations which are useful 
if you are using a motherboard/bios combination manufactured after 1996, which 
supports this newer ACPI technology. The absence of ACPITOOL.BIN will not 
prevent SANE from working, just that only its ACPI features won't be 
available for use.
                             
For long term PC storage you also now have SANE /S which performs all of 
the same prevention methods described above, but also makes sure to park very 
old drive heads (this only applies to antique drives). Furthermore, it extends 
Dallas RTC battery life by powering it down too (if available). This last 
action, will of course imply that the system clock will stop. So whenever you 
switch your computer on again, you will have wrong date/time, literally from 
the point where you shut it down. But this, in exchange, will make the life of 
a built-in battery in a Dallas module last much longer. A word of caution: 
please ensure this stop clock function is called very late in your DOS session 
or batch file to avoid a possible re-activation of the clock.
                             
With SANE /R you may achieve a cold reboot, which is a complete restart, much 
like cutting power and pulling it back on. It is the safest reboot procedure.
                             
A warm reboot can be achieved with SANE /W, it should be slightly faster than 
a cold reboot since it skips some hardware initialization procedures.

SANE /F is a fast reboot option which is just a documented DOS restart 
procedure (interrupt 19h). It is extremely dangerous as it does not clear 
any memory. I added it because I could, not because I should. Only expect that 
it might work under some specific systems, but mostly crash or produce another 
reboot type. This is because you have every DOS structure alive and kicking 
and yet you are forcing DOS to rebuild its structures on top. This is 
certainly not a good thing and results will most likely follow that route.

SANE /B will attempt to set your BIOS CMOS values to factory defaults, which 
should reset your BIOS password and of course, require you to set up new 
BIOS values whenever you restart your machine. A few manufacturers do not use 
common industry standards, so this feature may unfortunately not work under 
all motherboards and BIOS combinations.

SANE /X exists for users of very old PCs that have a default text screen mode 
of 40x25. It will perform the same DOS stabilization procedure as SANE does 
when it is issued without parameters, but takes into consideration this 
vintage screen mode. Common examples of devices that used this screen mode, 
were the so called Palmtop PC, several Data Collection Terminals that were 
used for data inventory and as laser bar code scanners, and Industrial/Embedded 
Single Board Controllers (SBC). 

SANE /C only flushes all drive caches without performing any other activity. 
This obviously includes resetting the BIOS 13h disk handler, so that other 
caching programs may notice. This option may come handy for those who are into 
hot-swapping drives and don't want to risk their data integrity.

SANE /V performs a video card BIOS re-initialization which is useful for 
refreshing the character set and also defaults gamma values. If no VGA card is 
being used, a suitable error message will be displayed, and this operation 
will be aborted, quitting the program.

SANE /D Disables VGA video card output.

SANE /E Re-enables VGA video card output.

SANE /K Disables any video card output until a keyboard key is pressed. This 
option also works on non-VGA video cards. Useful as a simple screen blanker, 
even to prevent the infamous screen burn.

SANE /H Hibernates your PC, suspending CPU execution to preserve the most 
power. Requiures APM (Advanced users only!).

The PC in Suspend mode will be set at its lowest level of power operation. It 
still maintains operational data and parameters but execution is halted. 

To a standard DOS application, this "hibernation" period effectively looks 
like a massive gap in the system clock, but the execution simply continues 
from where it was left off. 

On most vintage hardware, the resume operation is triggered by a hardware 
event (like pressing the power button, pressing a special key, or opening a 
laptop lid, etc.). But there should be available other different power up 
methods that can be tweaked via its BIOS configuration settings.

The APM BIOS and its matching motherboard are responsible for saving and 
restoring the CPU registers and system state. 

Be aware that in some cases, there are implementations of APM that may be 
incomplete or non-functional, and vary greatly from manufacturer to 
manufacturer, from one computer model to another. It is best to perform a test 
before-hand, to ensure proper functioning of your hardware in such events. It 
is also paramount to consult the reference manual that came with your 
motherboard to properly understand and configure your particular hardware for 
your own special needs in this regard. 

On the other hand, an unsupported system will simply continue operating as if
nothing happened when this Suspend/Hibernation mode is tried on.

As a facility for users to better integrate SANE within their DOS system by 
using batch files, SANE provides return codes (which is what we call 
ERRORLEVELS in DOS terminology). The following are the ERRORLEVELS that SANE 
provides:

  0  -  Displayed built-in help and eventually quitted.
  1  -  Attempted a removal of BIOS password and set CMOS values to 
        default (Option /B) 
  2  -  Performed a DOS stabilization process using a 40x25 text 
        mode (Option /X)
  3  -  Performed a DOS stabilization process using a 80x25 text 
        mode.
  4  -  Flushed all drive caches (Option /C)
  5  -  Procedure was aborted. This operation required a VGA video card.       
  6  -  VGA card BIOS re-initialized (font and gamma set to default 
        values) (Option /V)
  7  -  Disabled VGA video card output (Option /D)
  8  -  Re-enabled VGA video card output (Option /E)
  9  -  Disabled any video card output until a keyboard key was 
        pressed. (Option /K)
  10 -  Suspend/Hibernation was previously attempted (Option /H)
  
Usage Examples:
--------------
An 80's game you were playing decided not to quit cleanly, leaving you a 
garbled screen with annoying high pitch tone coming out of the speaker. To fix 
this mayhem, just enter: SANE

You have just installed a new driver for your hardware, and want it to become 
active by rebooting, just enter: SANE /R

It is late at night and you want to shut down your computer to resume work 
tomorrow, just enter: SANE /Y 

You tested the system one last time before shipping it or storing for a long 
time, just enter: SANE /S

Techno Bable and Trivia:
-----------------------
Be aware that there cannot technically be a safe 100% perfect way to stabilize 
a DOS system for a proper shutdown or reboot, as interrupts may have been 
captured and or be monitored by resident programs that no one can predict 
what they might be doing or how to address them. However, SANE attempts 
to follow common good practices that can "almost always" lead you to a safe 
path. SANE is indeed much better than pulling the power cord and praying 
for the best outcome when it comes to your precious data!

In total, seven individual programs I have made in the past had their code 
integrated into SANE.

The entire SANE program code is written in real mode x86 assembler, and is 
compiled under Borland TASM. The current single source file is about 30 KB 
long and has more or less 900 lines of commented code.   

Licenses:
--------  
SANE is Public Domain software.
Binary release only.

ACPITOOL.BIN is under GLP-2 license.
Binary and source release.

Authors:
-------
Ignacio F. Gully
SANE's author

Eric Auer
ACPITOOL.BIN's author
Modifications by Ignacio F. Gully

ignacio gully at gmail   .com
