
                                SSPAWN

                    (c) 1993 4D Interactive Systems, Inc.

                               Written by
                              Paul Penrose


LEGAL STUFF
-----------

The files in this archive (SSPAWN.ZIP) are being released as FREEWARE.  This
means that you may use the programs and functions enclosed (see below for a
complete list) for whatever use you wish, at no cost, with the following
restrictions:

        1.) The 4D Interactive Systems copyright notices are not removed or
            altered in any way.

        2.) The following notice is included in any documentation, printed or
            in electronic form, that accompanies any program or package
            containing any or all of the aformentioned programs and/or
            functions:

                           SSPAWN provided and (c) 1993 by
                             4D Interactive Systems, Inc.


Warranties:
Basically there are none, either expressed or implied.  We do not make any
claims as to the usefulness of the programs and functions included for any
particular purpose.  Niether are we responsible for any loss incurred by
their use.  Any rights not specifically granted in this document are
reserved.

CONTENTS
--------

This archive contains the sspawn function which allows Borland C programs to
to swap most of their code and data out to EMS or a disk file and spawn a DOS
command shell.  Optionally a command may be passed to the shell and the path
for the temporary file may be specified.  It is assumed that the user is
already familar with the C language.  You should have the following files:

        README.TXT
        SSPAWN.ASM

The Function
------------

The C prototype for the sspawn function is:

        unsigned int sspawn(char *command, char *path);

The command string will be passed to the spawned shell for execution.  Any
command that can be executed at a DOS prompt can be used.  If an empty string
or NULL is specified for the command then a standard DOS command shell will be
started.  In this case the user must type EXIT at the command prompt to return
to your program.  The path string is used to specify a valid DOS path where
the function can write the swapped portion of the program, if needed.

When called the function will identify all the memory your program uses that
is higher than itself.  This memory will then be copied into EMS memory, or
if there is not enough EMS it will be written to a temporary file.  Then this
memory is returned to DOS and a command shell is spawned.  When it returns
the memory is restored, the EMS memory freed or the temporary file deleted,
and the function returns to the caller.  The value returned will be one of
the following:

        0x0000 = No errors
        0x8001 = Unable to find the COMSPEC environment variable
        0x8002 = Unable to create the temporary file
        0x8003 = Error encountered while writing data to temporary file
        0x8004 = Unable to release execess memory
        0x8005 = Error encountered trying to spawn command shell

Additionally if the function is unable to restore the swapped portion of the
program an error message is displayed and the program is terminated.  The most
likely sources of these errors is one of the following:

        1.) A TSR was loaded from the spawned shell and the TSR is now using
            memory that the program was using making it impossible to restore
            the program.

        2.) The EMS pages that contained the swapped portion of the program
            was released by some program run from the spawned command shell.

        3.) The temporary file that contained the swapped portion of the
            program was deleted from the spawned command shell.

Note: This function has only been tested with Borland C++ 3.1 and the Borland
heap functions.  It will probably work with older versions of the Borland C
products as well, but we have not tested that.  It should also work with any
C compiler that utilizes only one memory control block for the entire program
and heap.  As I understand, some C compilers (including Microsoft's) will
create new MCB's for the heap.  SSPAWN will NOT work with those products.

Compiling your Programs
-----------------------

SSPAWN was written for TASM's IDEAL mode and the HUGE memory model.  If you
use another memory model you must change the model specified in the source
code.  The SPAWN.ASM module should be placed first in the project list.  For
those of you that use the command line compiler and linker you should place
the sspawn.obj file just after the startup code module.  If you have any ISR's
they should either be disabled before you call sspawn, or the module that
contains the ISR and ALL the data it references should be placed before sspawn
in the project/link file.


Support
-------

Since this is FREEWARE we can't afford to spend much time supporting users.
However, if you do find a bug, I would appreciate it if you would drop me a
note, and we can both benefit.  Have fun.

Paul A. Penrose
4D Interactive Systems, Inc.
1885 University Ave, West
Suite 229
St. Paul, MN  55104
612-646-8104
Compuserve: 72610,3377
Internet: 72610.3377@compuServe.COM
