ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/PROG/UTILITY/EXEC23.ZIP/EXEC.DOC

Text File | 1990-10-11 | 13.3 KB | 329 lines

              An EXEC function with memory swap
              =================================

Public domain software by

        Thomas Wagner
        Ferrari electronic GmbH
        Beusselstrasse 27
        D-1000 Berlin 21
        Germany

        BIXname: twagner

Version 2.3, released 90-10-11.

The usual disclaimers on warranties and fitness for any purpose
apply. This is public domain software, so there are no restrictions
at all on use (private or commercial), or on distribution by any
media. No royalty or license payments are necessary to use this
software.

Limited support is available via BIX, BIXmail your bug reports
or questions to 'twagner'.


This archive contains the sources for an 'EXEC' function for Turbo C
(versions 1.x, 2.x, and C++ 1.x), Microsoft C (versions 5.1 and 6.0),
Watcom C (version 8.0), and Turbo Pascal (versions 4.x/5.x) that
optionally swaps out the memory image of the calling program to a
temporary file or to EMS, and shrinks down to a minimal core before
executing the program.

This allows chaining or spawning to memory-hungry programs, and it
eases building of DOS menu-systems. The memory used when swapping is
less than 1k, plus the memory needed for a copy of the environment. If
you pass a new environment to the spawned program, space for two
copies of the environment are needed.

EMS (LIM 3.0 or above) 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.


                        INTERFACE
                        =========

Pascal:
        function do_exec (xfn: filename; pars: string128; spwn: integer;
                          needed: word; newenv: boolean): integer;

C:
        extern int do_exec (char *xfn, char *pars, int spwn,
                            unsigned needed, char **envp);


Parameters:
            xfn         is a string containing the name of the file
                        to be executed. If the string is empty,
                        the COMSPEC environment variable is used to
                        load a copy of COMMAND.COM or its equivalent.
                        If the filename does not include a path, the
                        current PATH is searched after the default.
                        If the filename does not include an extension,
                        the path is scanned for a COM or EXE file in
                        that order.

            pars        The program parameters.

            spwn        If 1, the function will return, if necessary
                        after swapping the memory image.
                        If -1, EMS will not be used when swapping.
                        If 0, the function will terminate after the
                        EXECed program returns.
                        NOTE: If the program file is not found,
                        the function will always return
                        with the appropriate error code, even if
                        'spwn' is 0.

            needed      The memory needed for the program in
                        paragraphs. If not enough memory is free, the
                        program will be swapped out. Use 0 to never
                        swap, $ffff to always swap. If 'spwn' is false,
                        this parameter is irrelevant.

Pascal only:
            newenv      If this parameter is FALSE, the environment
                        of the spawned program is a copy of the parent's
                        environment. If it is TRUE, a new environment
                        is created which includes the modifications from
                        previous 'putenv' calls.

C only:
            envp        The environment to be passed to the spawned
                        program. If this parameter is NULL, a copy
                        of the parent's environment is used (i.e.
                        'putenv' calls have no effect). If non-NULL,
                        envp must point to an array of pointers to
                        strings, terminated by a NULL pointer (the
                        standard variable 'environ' may be used).


Return value:

            0000..00FF: The EXECed Program's return code
            (0..255 decimal)
            0100:       Error writing swap file
            (256 decimal)
            0200:       Program file not found
            (512 decimal)
            03xx:       DOS-error-code xx calling EXEC
            (768..1023 decimal)
            0400:       Error allocating environment buffer
            (1024 decimal)
            0500:       No room in low program memory, move spawn
                        module to end of link
            (1280 decimal)



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

The assembler module "spawn" must not be the first module linked.
Either put it into a library, or specify spawn.obj as one of the last
objects in the link command or the Turbo project file. The spawn
module will overwrite about 1k at the start of the program image.
Although the contents of this area will be saved, they may not
contain parts of the spawn module itself, since this would destroy
the code being executed.

The calling program may not have interrupt handlers installed when
calling the do_exec function. This includes handlers for Control C
and critical errors.

All open files will stay open during the EXEC call. This reduces the
number of handles available to the child process. The "C_FILE_INFO"
environment variable created by the standard C spawn is not supported.

BAT-files and internal commands are not automatically processed. You
can execute those by calling the do_exec function twice, for example:

(C)     retcode = do_exec ("dir", "*.*", 1, 0xffff, environ);
        if (retcode == 0x200)
           retcode = do_exec ("", "/c dir *.*", 1, 0xffff, environ);

(P)     retcode := do_exec ('dir', '*.*', 1, $ffff, true);
        if (retcode = $200)
           retcode := do_exec ('', '/c dir *.*', 1, $ffff, true);



                        CAUTIONS
                        ========

The functions should be compatible with DOS versions down to DOS
2.21, but they have been tested under DOS 3.3 and DOS 4.0 only.

Spawning a command that exits and stays resident (TSR), like PRINT or
Sidekick, will fragment memory and prevent a return to the calling
program. This should, however, not crash the system. Allocated EMS
pages are released, but a swap file is not deleted.

The memory image of the calling program should be contiguous. This is
always guaranteed if you use the standard Turbo C/Pascal allocation
routines only. The swapper is able to swap non-contiguous blocks such
as those created by the Microsoft far allocation routines. However,
to do this, the swapper has to use undocumented fields in the memory
control blocks, and modify DOS memory control blocks directly. This
may lead to incompatibilities in later versions of DOS, or in DOS
substitutes or emulators.

When debugging the assembler module, take care not to set breakpoints
in the code while it is being swapped out. Those breakpoints (INT 3
instructions) will be swapped back in later without the debugger
knowing about it, and cause quite strange results when you run through
the code for the second time.

Note that Turbo Pascal kills all debugging info when loading external
assembler modules, so you can't step through SPAWN with TD in source
mode.  You will have to open the CPU window to step through SPAWN if
required. Turbo C does not have this problem.


                        CONTENTS
                        ========

This archive contains the following files:

    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;            For Turbo Pascal, near calls
            tasm /DPASCAL /DFARCALL spawn;  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

    SPAWNPN.OBJ     SPAWN assembled for use with Pascal, near calls
    SPAWNCS.OBJ     SPAWN assembled for use with C (small model)

        Rename the appropriate file to 'SPAWN.OBJ' for use with your
        compiler. The CS file has 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 definition of do_spawn with {$F-} and {$F+}.

    EXEC.PAS        Interface routines for Turbo Pascal (5.x)
    EXEC.C          Interface routines for Turbo C / MS-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        Turbo C Test program for EXEC
    EXTEST.PRJ      Turbo C 2.0 Project file for test program
    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.


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 (envvar: 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.


                        Revision History
                        ================

Changes from version 1.0 to 2.0:

1) Problem fixes

- Problems with EMS drivers that return handles above 255 have been
  fixed.

- Bug that prevented deletion of temporary file has been fixed.

- The Division by Zero interrupt vector is patched to an IRET and
  restored when swapping back in.

- The /DFARCALL define has been added to the assembler module to
  allow assembling for Turbo Pascal with "Force Far Calls" set.


2) Enhancements

- The TMP/TEMP environment string is checked for validity, and
  is ignored if it points to a non-existent directory.

- For DOS versions 3.0 and above, the temporary file is created using
  the special DOS function. This eliminates the extra overhead for
  generating a unique filename.

- The C version is now compatible with Microsoft C 5.x.

- Non-contiguous memory blocks can be swapped.

- The 'spwn' parameter to the do_exec function has been changed to
  allow EMS usage to be controlled. It can now have the values -1, 0,
  and 1. For Pascal, the type of the parameter has been changed from
  boolean to integer. The internal assembler routine takes an additional
  method parameter, it no longer uses the first byte of the swap-filename
  to determine swapping method.


Changes from version 2.0 to 2.1/2.2:

  Several bugs in spawn.asm were fixed, no other changes.

Changes from version 2.1/2.2 to 2.3:

- When swapping to a file, the swap file is now closed before
  spawning. This frees another file handle, and avoids problems
  with programs (for example chkdsk) falsely claiming lost clusters.

- If the program consisted of multiple memory blocks (MS-C large
  model, or blocks allocated with farmalloc), only the first (main
  program/data) block was swapped out completely. All other blocks
  in the MCB chain were swapped short if their length was not a
  multiple of 16k bytes. This could cause problems on return.

- If the spawn module was linked as one of the first modules in a
  program, the code in the module itself could get clobbered by
  moving the code and setting up the data at the start of the
  program image. The spawn module now checks that it is located high
  enough in memory.

- An unnecessary "offset" operator was removed from several statements
  in the assembler module to avoid spurious warnings when assembling
  with MASM /W2. You will still get warnings when assembling with
  /W2, but those warnings can not be eliminated (or at least I don't
  know how). A symbol name was fixed to allow assembling with /ml.

- A pragma for Watcom C 8.0 was added to compat.h (supplied by T.
  Frost).


                           ACKNOWLEDGEMENTS
                           ================

Thanks to H. Qualls, H. Gubler, J. Clinton, M. Adler, T. Frost, and
other BIXen, for pointing out bugs and suggesting enhancements.