An EXEC function with memory swap
                   Version 3.3a, released 93-06-22

                      Public Domain Software by
                            Thomas Wagner
                       Ferrari electronic GmbH
                  (NOTE: Address change, see below)


This archive contains the sources for an 'EXEC' function that allows
calling external programs, while optionally swapping out the memory
image to EMS, XMS, or file. When swapping out, only a few K of main
memory remain resident. The code and data stub is about 1k, the actual
memory usage depends on memory fragmentation, and especially on the
size of the environment variables. The resident memory usage
typically ranges from 2K to 7K.

The Routines are compatible with 
   Turbo C (Versions 1.x, 2.x, and C++ 1.0)
   Borland C++ (Version 2.0 and above),
   Microsoft C (Versions 5.1 and above), 
   Watcom C (Version 8.0), 
   Turbo Pascal (Versions 4.x to 6.x).

EMS (LIM 3.0 or above) or XMS is used automatically if there is
enough space left, otherwise a temporary file is created. If the
"TEMP=" or "TMP=" environment variable is present, the temporary file
is created in the directory specified by this variable, otherwise it
is created in the current directory.

For detailed usage and parameter information, see the file "exec.h" (C) 
or "exec.pas" (Pascal).

The general format is

   retcode = do_exec (filename to execute,
                      program parameter and redirection string,
                      spawn options,
                      memory needed (0xffff to always swap, 0 to never swap),
                      environment pointer/flag)

for example:

   rc = do_exec ("cl", "-c -Od exec.c >&errout", USE_ALL, 0xffff, NULL);

or, for Pascal:

   rc := do_exec ('tpc', '/$D+ exec >&errout', USE_ALL, $ffff, false);

Redirection for standard input, standard output, and standard error
is optionally handled by parsing the command parameter string for the
standard redirection combinations:

   stdin:   <file
   stdout:  >file    or >>file   to append
   stderr:  >&file   or >&>file  to append

Redirection is supported by default, to disable it you must change
the define in both spawn.asm and exec.c/exec.pas.

If the command to be executed is a BAT file, the command processor
will be invoked automatically. The command processor will also be
invoked if the command is empty. The COMSPEC environment variable is
used to locate the command processor, any parameters present on the
COMSPEC line are inserted into the parameter string.

An example:

   Given   COMSPEC=C:\DOS\COMMAND.COM /E:960
           PATH=C:\DOS;C:\CMD
           File B.BAT resides in C:\CMD
           do_exec is called with ('b', 'one two >out', ...)

   Then the command executed is
           C:\DOS\COMMAND.COM
   with the parameter string
           /E:720 /C C:\CMD\B.BAT one two
   and standard output redirected to file 'out'.



                        CONTENTS
                        ========

This archive contains the following files:

    README.DOC      This file
    LIESMICH.DOC    German version of this file

    GETLANG.EXE     A helper program to extract a single-language
                    version from the dual-language source. All C and
                    Assembler sources (Pascal sources only partially)
                    are commented in both English and German,
                    which makes the code hard to read. For easier
                    reading, you can use GETLANG to eliminate one
                    of the languages.

         Usage:   GETLANG language compiler <infile >outfile
            Where    language is 'E' for English or 'D' for German
                     compiler is 'C' for C files, 'A' for Assembler,
                     or 'P' for Pascal.

         Samples: GETLANG e a <spawn.asm >spawne.asm
                  GETLANG e c <extest.c >exteste.c

    DEUTSCH.BAT     Batch-File to execute GETLANG for all source
                    files, German version
    ENGLISH.BAT     Batch-File to execute GETLANG for all source
                    files, English version

    SPAWN.ASM       The main swap/exec function

        This file is common to the C and Pascal versions.
        It must be assembled with Turbo-Assembler for use with
        Pascal. The C version can be assembled with TASM (specify 
        /JMASM51 on the command line) or MASM 5.1.

        To assemble:
            tasm /DPASCAL spawn,spawnp;     For Turbo Pascal, near calls
            tasm /DPASCAL /DFARCALL spawn,spawnp;  
                                            For Turbo Pascal, far calls
            ?asm spawn;                     For C (default small model)
            ?asm /DMODL=xxx spawn;          For C (model 'xxx')
         Example:
            masm /DMODL=large spawn;            Large model C
            tasm /DMODL=medium /JMASM51 spawn;  Medium model C

    SPAWNP.OBJ      SPAWN assembled for use with Pascal, near calls
    SPAWNCS.OBJ     SPAWN assembled for use with C (small model)
    SPAWNCL.OBJ     SPAWN assembled for use with C (large model)
        
        The C files have been assembled with the /MX switch
        for case-sensitive external linking.

        Note for Turbo Pascal: You can use the near call version of
        SPAWN even when compiling with "force far calls" by enclosing
        the external definitions of do_spawn and prep_swap in file
        exec.pas with {$F-} and {$F+}.
        To avoid confusion when generating multiple language
        versions, the Pascal OBJ-File was named "spawnp.obj".

    CHECKPAT.ASM   Utility function to check and resolve a path 

        This file is common to the C and Pascal versions.
        It must be assembled with Turbo-Assembler for use with
        Pascal. The C version can be assembled with TASM (specify 
        /JMASM51 on the command line) or MASM 5.1.

        To assemble:
            tasm /DPASCAL checkpat,checkpap;  For Turbo Pascal, near calls
            tasm /DPASCAL /DFARCALL checkpat,checkpap;  
                                              For Turbo Pascal, far calls
            ?asm checkpat;                    For C (default small model)
            ?asm /DMODL=xxx checkpat;         For C (model 'xxx')
         Example:
            masm /DMODL=large checkpat;            Large model C
            tasm /DMODL=medium /JMASM51 checkpat;  Medium model C

    CHECKPAP.OBJ    CHECKPAT assembled for use with Pascal, far calls
    CHECKPCS.OBJ    CHECKPAT assembled for use with C (small model)
    CHECKPCL.OBJ    CHECKPAT assembled for use with C (large model)
    CHECKPAT.PAS    Wrapper unit for checkpat (Pascal only)   

        The C files have been assembled with the /MX switch
        for case-sensitive external linking.
        The Pascal version must be assembled with the FARCALL switch
        when used with the CHECKPAT.PAS unit. At least Turbo Pascal
        version 5.5 seems to automatically generate a far call if an
        external routine is defined in the interface part of the unit.

    EXEC.PAS        Interface routines and documentation for Turbo Pascal
    EXEC.C          Interface routines for C
    EXEC.H          Interface definitions and documentation for C
    COMPAT.H        MS-C/TC Compatibility definitions for C

        These files prepare the parameters for the main spawn
        function, and handle the file search and environment 
        processing.

    EXTEST.C        C Test program for EXEC
    EXTEST.PAS      Turbo Pascal Test program for EXEC

        The EXTEST program tests the functionality of the do_exec
        function. It expects you to input a DOS-command and its
        parameters, separated by a comma. Entering an empty line
        will spawn a copy of COMMAND.COM without parameters.

   MAKEPAS          Make-file for Turbo Pascal (Borland Make) 
   MAKETC           Make-file for Borland C++ (Borland Make) 
   MAKEMS           Make-file for Microsoft C (MS NMAKE) 


The Turbo Pascal version of EXEC.PAS includes replacement functions
for the environment access functions 'envcount', 'envstr', and
'getenv', plus an additional function, 'putenv'. This function allows
you to add strings to the environment for the spawned process. The
definition is

        procedure putenv (envstr: string);

with 'envstr' containing a string of the form 'ENVVAR=value'. The '='
is required. To delete an environment string, use 'ENVVAR='. Please
use the environment functions from the EXEC unit only, do not mix them
with calls to the DOS unit functions.


                        SUPPORT
                        =======

This software is in the Public Domain. This means that there is no
restriction whatsoever on private or commercial use. No registration
fees have to be paid, and no licenses are necessary for use. It also
means that the author can not be held liable for any damages caused
by the use of this software. You have the source, please check it out
before use.

I will try my best to eliminate any bugs reported to me, and to 
incorporate suggested enhancements and changes. However, my spare 
time is limited, so I can not guarantee continued or individual 
support. Please address all reports or questions to my business 
address: 

        Ferrari electronic GmbH
        attn: Thomas Wagner
        Ruhlsdorfer Strasse 138
        D-14513 Teltow
        Germany

        Phone: (+49 3328) 474 626
        Fax:   (+49 3328) 438 04-0

        BBS:   (+49 3328) 438 04-8 (from 8/15/93)
               please don't try to call before 8/15!

        Internet:    twagner@bix.com
        BIX:         twagner
        Compuserve:  100023,2042

But, please, if at all possible, do it in writing. Please do not 
phone unless it is absolutely vital (or you have a business 
proposal). I like to hear about any applications for EXEC, and 
if you are visiting Berlin, I also invite you to drop by for a 
talk. But I am usually not that happy when I am interrupted in my 
paid work by a phone call requesting support for a free product. 

I will try to answer all letters and Faxes I receive. However, I am
usually not the fastest in this respect, so please be patient. If you
don't hear for me for a while, send me a short reminder. The
preferred, and the fastest, method to reach me is through BIX, where
I daily check my mailbox. Send mail to 'twagner' from BIX, or to
'twagner@bix.com" through the Internet. The second best way is
CompuServe e-mail, which I usually check several times, but at least
once, a week.

BIX (tm) is an electronic conferencing system. BIX can be (and is)
accessed from all parts of the world. Although accessing BIX from
outside the US isn't exactly cheap (don't ask me what I have to pay
each month), the wealth of information available there, and the fast
and extensive help the other members can give you on all kinds of 
hard- and software problems, makes it worth every Mark, Peseta, 
Franc, or Ruble you have to spend. New versions and updates of EXEC
will first appear on BIX. 

To get more info on joining BIX, call the BIX Customer Service at 
800-695-4775 (U.S.), or 617-354-4137 (elsewhere) from 12:00 to 23:00
EDT (-4 GMT). BIX access currently is $39 for three months (flat
fee), plus the applicable telecomm charges (Tymnet in the U.S. and
Canada, your local PTT's Packet Net charges from outside the U.S.).
International users living near a BT Tymnet node can access BIX
through international Tymnet at special low rates. Call the BIX
helpline for Tymnet access points and charges. Other international
users will need an account (NUI) with their local packet net. Please
enquire at your post/telecomm office for details.


                        RESTRICTIONS
                        ============