-----------------------------------------------------------------------
DB3_Safe -- Quick & dirty shell for DiamondBack 3    (v1.1 of Jun17/94)
-----------------------------------------------------------------------

Some folks on GEnie have found out the hard way that data can be
damaged on their hard drives if the ICD write cache is left On when
DiamondBack 3 is run (at least in versions up to 3.03).  This is evid-
ently due to SCSI contention between the ICD driver and DiamondBack 3.

As a temporary measure, until Bob at ORA and Howard at ICD have an
opportunity to sort things out, I've written a simple wrapper utility
called DB3_Safe, that will automatically disable the ICD write caches
during the execution of DiamondBack 3.

When you double-click DB3_Safe, it reads a sequence of programs to run
from a script file (DB3_SAFE.DAT).  The script will look something like:

    c:\icd\cacheOff.prg x    {disable}
    d_back3.prg
    c:\icd\cacheOn.prg x     {re-enable}

Note that I don't actually have DiamondBack 3 myself, so I don't know
what the actual name of the file might be.  You will need to modify the
supplied script file to match the proper name, and adjust for wherever
you have the two ICD cache utilities (not supplied) located on your system.
(It's a normal text file that can be altered with almost any text editor.)

[NOTE: The purpose of the 'x' parameters on the cacheXXX.prg lines is
to speed things up.  When they are present, the utilities exit _immed-
iately_, rather than pausing for several seconds to allow you to admire
their status messages.  :~} ]

The net effect is that by running DB3_Safe, you simply run DiamondBack 3
with the ICD write caches disabled, and automatically re-enable them when
you finish.  If you don't use ICD driver software, or don't run with the
ICD write caches enabled, then you have no need for DB3_Safe.

DB3_Safe is small (only about 5kB resident) and fast, leaving no files
or system resources open during execution of DiamondBack 3.  The full
source code in HighSpeed Pascal is included, for the terminally curious.

I've tested DB3_Safe with a dummy GEM mode program on my systems, and
confirmed that the ICD caches were disabled/enabled at the proper times,
and that the behavior of the GEM program was not altered by the pre-
sence of the DB3_Safe shell.  However, I can't guarantee that it will
work flawlessly on all possible system configurations.  You will need
to test it out and make that determination for yourself.

Error detection and recovery is limited, but at least it makes sure
that each file that is needed is available, notifying you and halting
if anything goes wrong.  Thus it is conceivable, if files are missing
or improperly located, for DB3_Safe to exit with the caches turned Off.
If this occurs, it's up to you to re-enable them.

There are several limitations in version 1.1 of DB3_Safe that could be
rectified with more effort, but I wasn't sure it was worthwhile for a
temporary band-aid.  Let me know if you feel otherwise.

Limitations:
------------

1) DB3_Safe (.PRG and .DAT) must be located in the same folder as Diamond-
   Back 3, to find it's RSC files, etc.  (i.e., there's no default direct-
   ory path handling)

2) You get (annoying) white screens with ICD messages (briefly) at startup
   and shutdown.  Some people might actually like to see what's going on,
   but I'd prefer the process to be transparent (which is why there are no
   identifying messages in DB3_Safe).

   It's possible to redirect these messages into a dummy file somewhere
   (yuck), but I couldn't manage to just ship them silently to a NUL device.
   [I can't mess with the xConout vectors, because they're not available
   in TOS 1.0.  And I can't redirect standard out to AUX: (which I could
   stifle), because it too is a standard file handle).]
   
   Opening and closing files for this also slows things down.  And even
   with redirection, the white flash as the CACHE utilities clear the
   screen can not be suppressed (it uses the VDI, not Bios or GemDos).

   A quicker option would be to let the CACHE On/Off messages appear, then
   immediately wipe them with the background fill pattern.  This is fast,
   but still leads to a white flash on entry and exit.
   
Legal Mumbo Jumbo:
------------------

DB3_Safe is Copyright (c) 1994, by Mark O'Bryan.  Free and unrestricted
distribution is permitted, so long as proper attribution is made.
DISCLAIMER: No warranty is made regarding fitness for any purpose.

Note that any trademarks mentioned herein are the property of their
respective owners, and that I am in no way connected with either ICD
or Oregon Research Associates.  I don't even use write caching or DB3,
but thought I'd take a few minutes to help out those people who do.