SHROOM: Shell Room Utility v2.6a (14jul95).
Copyright (C) Davis Augustine 1990-1995.  All rights reserved.

          ********** NOTES **********

NOTATION:
    'k' is used by Shroom as decimal 1000, not 1024.  E.g., "Swapping 4k"
means swapping 4000 bytes, not 4096 bytes.


PROGRAM LOADING:
    The application must be a .EXE or .COM file.  You can leave off the
file extension and Shroom will try to find a matching .COM or .EXE file.
Shroom searches for the application program first in the current directory,
then in Shroom's home directory, and finally in the directories of the
PATH environment string.


SHROOM SWITCHES AND ARGUMENTS:
    All text surrounded by square brackets, as in "[-hnv]", is optional.
Switches can be given in any order, and can be in upper or lower case,
and may be separated by spaces (or not). The space between a switch and
its argument is optional, ie. you can say "-z800" or "-z 800".
Although all our examples use dashes as the switch character, a slash
can also be used: e.g. "Shroom /v /p ...".


EXTENDING THE COMMAND LINE WITH @SWITCHFILE:
    The DOS command line is normally limited to a paltry 127 characters.
If that's not enough room to say what you want to say, then you can use
the "switch" file to hold additional switches and arguments for Shroom.
Shroom reads the switch file just as if it were part of the command line.

    For example,
      If file FOO contains:  -t shell1, shell2 -p
      Then the DOS command:  shroom -v @foo yourprog
          Is equivalent to:  shroom -v -t shell1, shell2 -p yourprog

    The switch file can contain multiple lines.  End-of-lines are treated
as space characters.  You can use multiple switch files on the command
line (eg Shroom @sf1 @sf2) but you cannot call one switch file from
within another (ie, no nesting).

    Please note: This feature is for extending Shroom's command line, not
your application's.  Unfortunately the application program's command
line is still limited to 127 or so characters (unless it supports its
own method of getting around the limitation).


NOVELL NETWARE:
    If you are using Novell Netware, then you may also need to use the "-w"
switch with Shroom, as in "shroom -w prog".  Many versions of Netware
seem to close files unexpectedly if they see that there is free memory
where there used to be a program.  When Shroom swaps out the appli-
cation, Netware notices the memory is free and closes the network files
that that application had open.  The "-w" switch causes Shroom to make
a special call to Netware that disables the "file cleanup feature"
during shell operations, thus keeping your network files open.


ENVIRONMENT SIZE:
    Many people have run into the following problem: you type the command
"SET MYVAR=WHATEVER" and get back the message "Out of environment space."
This occurs when a TSR is loaded or while a .BAT file is running. You get
around this by adding a line like "SHELL=C:\COMMAND.COM /E:2000" to your
CONFIG.SYS file, thus increasing the minimum environment space to 2000
bytes. However, when you shell out from an application and then run a
.BAT file, you find that the environment size has again been restricted
and the CONFIG.SYS line has no effect.

    What you need is the amazing new "-z #" switch from Shroom. It causes
Shroom to append the string " /E:#" to COMMAND.COM's command line, thus
setting the desired minimum environment space for the new shell. Note
that in DOS 3.0, # is the size in paragraphs. In later versions it is
in bytes.


REDIRECTING STDOUT:
    Unless you give the -q switch, Shroom puts out a "Swapping..." message when
shells occur.  If you give the -v switch, Shroom puts out even more lines.
By default, both Shroom's output and the application's will go to the screen.

    If you say "Shroom -o File App" then the application's output still goes
to the screen but Shroom sends its output to the specified file.  If you say
"Shroom App > File" then both shroom and the application will send their output
to the specified File.  If you want Shroom's output to go to the screen and
the app's to a file, you can say "Shroom -o CON App > File".

    Note: with the "-o File" switch, if the file already exists then Shroom's
output is appended to it.  We do not delete the previous file data.


EXIT RETURN CODES:
    Shroom exits immediately if it cannot load the application, returning
an ERRORLEVEL of 254, unless you have changed the value with the "-e #"
switch.  If it can load the application, then Shroom exits when the
application does, and returns the application's exit code.


SWAP FILE:
    Shroom stores the application in a temporary swap file during the
shell.  The swap file always has extension ".OOM".  The main part of
its name is derived from the application name followed by some digits.
E.g., "WP_000.OOM".  When you exit from the shell, Shroom reads the
file back in and then deletes it.  Obviously, you should not delete,
rename or otherwise modify the swap file while you are in the shell.
If you crash the system while in the shell, then the swap file will
still be there after you reboot (unless you were using a ram disk),
and it is a good idea to delete it then.  The file is readonly so
you will need to run attrib -r on it first.

    Shroom (among many other programs) looks for the environment variable
TEMP at startup.  If TEMP is defined, then Shroom takes its definition
as the default location of the swap file.  If TEMP is not defined, then
the current directory becomes the default swap file location.  If you
give the -s DRIVE:DIR switch on the command line, then that overrides
the default location.  The swap file location is determined only once,
during Shroom's startup.  Changing your current drive or directory while
in the application or a shell will not affect where the swap file goes.
Finally, if you have a ram disk with enough room, it makes an excellent
home for the Shroom swap file.  It is fast and "self-deleting" if you
crash the PC.


SWAP FILE SIZE:
    By default Shroom attempts to free up all memory "above" it in the
DOS 640K.  Typical swap file sizes are 200K to 500K.  If the swap file
is too big to fit on the disk, Shroom asks whether you want to perform
the Shell operation anyway or cancel it.  Or you can use the "-p" option
which tells Shroom to proceed with all Shell operations even if it can
only do a partial swap.  If you want to limit the swap file size you
can use the -m N switch.  For example, the command "shroom -m 125 prog"
will limit the swap file size to 125000 bytes.


TARGET LIST:
    (Most people don't need to worry about this.)  When Shroom notices
that a program is being shelled, it checks the name of that program
against the target list. If it is in the list, then Shroom goes ahead
and does its thing, swapping the application and freeing its memory.
If the shelled program is not in the target list, then Shroom lets the
program load and execute normally without any swapping.

    The purpose of the target list is to prevent unwanted swapping.  There
are a few applications which "shell" their own overlays, and if Shroom
swapped them then the overlays wouldn't have anyone to talk to!

    The default target list contains just your command shell, as defined
by the COMSPEC environment string.  The -t switch is used to change the
target list.  It takes a list of filenames separated by commas.  The file
names are case independent and should not have drive or directory paths.
The ~ (tilde) string can be used to refer to the COMSPEC definition.
For example, "shroom -t ~, SUBPROG.EXE ..." would cause swappping on
the default shell and when SUBPROG.EXE is spawned.  Typical shells are
COMMAND.COM, 4DOS.COM, NDOS.COM and SH.EXE.

    Another special string is * (asterisk).  It is the wildcard target
list, which causes Shroom to spawn on all shell operations.  It should
be the only -t argument, as in: "shroom -p -t * -v ...".

    If the -x switch is given, then the target list is used to exclude
rather than to include.  Eg, "shroom -xt myshell.exe myprog" tells
Shroom to swap on all shell programs except myshell.exe.


COMMAND LINE TARGET:
    This switch is similar to (and even more complicated than) the -t
switch.  It allows you to enable swapping based on the contents of the
shelled program's command line, rather than on the program's name.
When you give Shroom the switch "-c xyz", then swapping will occur only
if the shelled program has the string "xyz" in its command line.  If you
give Shroom the switch "-xc xyz", then swapping will occur only if the
command line does NOT contain the string "xyz".

    The purpose of the -c and -xc switches is to handle the case where
your app shells a program by passing it to COMMAND.COM.  For instance
if the app needs to spawn the program CHILD.EXE, it can do it in two ways.
It can spawn CHILD.EXE, or it can spawn COMMAND.COM with the command
line "/c child".  When the latter method is used, there are actually
two shell operations: the app spawns COMMAND.COM, which then spawns
CHILD.EXE.  You can use "-xt child.exe" to prevent swapping on the
second shell, but it won't prevent swapping on the first one.  To do
that, you need to add the "-xc child" switch.  This causes Shroom to
scan the command line of the spawned programs.  It would find "child"
in the command line "/c child" and would thus not swap.

    The -c and -xc switches take a list of words as their argument.
For example, "-xc fee,fie,foo" tells Shroom not to swap if the command
line contains any of the words "fee", "fie" or "foo".  In addition,
the pattern matching of the strings is case independent.  It will also
not swap if the command line contains "Fee", "FIE" or "fOo".

    You can see what command lines are being passed to shelled programs
by using Shroom's "-v" switch.  Look for messages like:
          SHROOM:  Execing shell "CL.EXE" with " -c foo.c".
    

APPLICATIONS THAT DO "BACKGROUND PROCESSING":
    You may have a communications package which allows you to initiate a
file transfer and then shell out to do other things.  This will probably
not work if the package was Shroom'ed, because the application is actually
unloaded from memory (and from the interrupt vector table) during the
shell.  The background processing code will not be there anymore!


ENVIRONMENTAL IMPACT:
    Shroom is processor (8086, 286, 386, etc) independent.  It does not do
any floating point.  It doesn't care about or use expanded or extended
memory (a future version will be able to swap to extended mem).  It works
with DOS Extender (e.g. Pharlap) based applications.  It may work in the
Windows, Desqview and other pseudo or real multi-tasking environments, but
you're basically on your own (caveat sharer).


LOADING TSR'S INSIDE SHELLS:
    In general, it is not safe to load a TSR while shelled out of an
application, unless you delete the TSR before exiting the shell.  A
variety of memory and interrupt handling problems can occur.  This
is true even when you are not using Shroom.  If you are using Shroom,
then any TSR's that were loaded during the shell will be automatically
unloaded when you return to the application.  If a TSR was loaded "high",
then it will stay loaded high but may cause problems if it uses any
interrupts that the application uses.  Shroom displays the message:
"WARNING: Interrupt ## used by application, changed in shell." if that
occurs.


UNLOADING TSR'S INSIDE SHELLS:
    The sequence in mind is: You Load a TSR, enter an application,
shell out, then unload the TSR.  The main danger in doing this is that
unloading the TSR may restore interrupt vectors that the application
had remapped.  The chain would be changed from TABLE->APP->TSR->SYSTEM
to TABLE->SYSTEM, thus "cutting out" the app.  Fortunately, Shroom is
able to detect when this occurs.  If you see the message "WARNING: 
Interrupt ## used by application, changed in shell", then that is what
happened.  You should probably save your changes to a new temp file if
possible, and exit the application.  You're not guaranteed to be able
to do this, so be sure to hold your breath.

    You don't really need to know what interrupts are or understand any
of the above.  The bottom line is: don't play with TSR's when shelled
out of an application.  If you can't resist the urge to, then at least
Shroom will provide some insurance by catching and attempting to deal
with conflicts when they occur.


REPORTING BUGS:
    If Shroom is not working as advertised for you, please tell me about
it and I'll try to fix it.  Shroom problems are usually due to conflicts
with other software packages.  You should send a problem report via
regular or electronic mail with a description of the malfunction and
a listing of your CONFIG.SYS and AUTOEXEC.BAT files.  Use the switches
"-v -o FILE" to create a log of the malfunctioning session.  You may
also be asked to send a copy of the misbehaving application so that I
can debug with it.  (It usually takes more time to obtain the software
and/or reproduce the bug than it does to fix it.)
