home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 31 / CDASC_31_1996_juillet_aout.iso / internet / rnr214.zip / EXEC23P.ZIP / EXEC.DOC < prev    next >
Text File  |  1990-10-11  |  14KB  |  329 lines
  1.  
  2.               An EXEC function with memory swap
  3.               =================================
  4.  
  5. Public domain software by
  6.  
  7.         Thomas Wagner
  8.         Ferrari electronic GmbH
  9.         Beusselstrasse 27
  10.         D-1000 Berlin 21
  11.         Germany
  12.  
  13.         BIXname: twagner
  14.  
  15. Version 2.3, released 90-10-11.
  16.  
  17. The usual disclaimers on warranties and fitness for any purpose
  18. apply. This is public domain software, so there are no restrictions
  19. at all on use (private or commercial), or on distribution by any
  20. media. No royalty or license payments are necessary to use this
  21. software.
  22.  
  23. Limited support is available via BIX, BIXmail your bug reports
  24. or questions to 'twagner'.
  25.  
  26.  
  27. This archive contains the sources for an 'EXEC' function for Turbo C
  28. (versions 1.x, 2.x, and C++ 1.x), Microsoft C (versions 5.1 and 6.0),
  29. Watcom C (version 8.0), and Turbo Pascal (versions 4.x/5.x) that
  30. optionally swaps out the memory image of the calling program to a
  31. temporary file or to EMS, and shrinks down to a minimal core before
  32. executing the program. 
  33.  
  34. This allows chaining or spawning to memory-hungry programs, and it
  35. eases building of DOS menu-systems. The memory used when swapping is
  36. less than 1k, plus the memory needed for a copy of the environment. If
  37. you pass a new environment to the spawned program, space for two
  38. copies of the environment are needed.
  39.  
  40. EMS (LIM 3.0 or above) is used automatically if there is enough space
  41. left, otherwise a temporary file is created. If the "TEMP=" or "TMP="
  42. environment variable is present, the temporary file is created in the
  43. directory specified by this variable, otherwise it is created in the
  44. current directory.
  45.  
  46.  
  47.                         INTERFACE
  48.                         =========
  49.  
  50. Pascal:
  51.         function do_exec (xfn: filename; pars: string128; spwn: integer;
  52.                           needed: word; newenv: boolean): integer;
  53.  
  54. C:
  55.         extern int do_exec (char *xfn, char *pars, int spwn, 
  56.                             unsigned needed, char **envp);
  57.  
  58.  
  59. Parameters:
  60.             xfn         is a string containing the name of the file
  61.                         to be executed. If the string is empty,
  62.                         the COMSPEC environment variable is used to
  63.                         load a copy of COMMAND.COM or its equivalent.
  64.                         If the filename does not include a path, the
  65.                         current PATH is searched after the default.
  66.                         If the filename does not include an extension,
  67.                         the path is scanned for a COM or EXE file in
  68.                         that order.
  69.  
  70.             pars        The program parameters.
  71.  
  72.             spwn        If 1, the function will return, if necessary
  73.                         after swapping the memory image. 
  74.                         If -1, EMS will not be used when swapping.
  75.                         If 0, the function will terminate after the 
  76.                         EXECed program returns. 
  77.                         NOTE: If the program file is not found, 
  78.                         the function will always return
  79.                         with the appropriate error code, even if 
  80.                         'spwn' is 0.
  81.  
  82.             needed      The memory needed for the program in 
  83.                         paragraphs. If not enough memory is free, the
  84.                         program will be swapped out. Use 0 to never
  85.                         swap, $ffff to always swap. If 'spwn' is false,
  86.                         this parameter is irrelevant.
  87.  
  88. Pascal only:
  89.             newenv      If this parameter is FALSE, the environment
  90.                         of the spawned program is a copy of the parent's
  91.                         environment. If it is TRUE, a new environment
  92.                         is created which includes the modifications from
  93.                         previous 'putenv' calls.
  94.  
  95. C only:
  96.             envp        The environment to be passed to the spawned
  97.                         program. If this parameter is NULL, a copy
  98.                         of the parent's environment is used (i.e.
  99.                         'putenv' calls have no effect). If non-NULL,
  100.                         envp must point to an array of pointers to
  101.                         strings, terminated by a NULL pointer (the
  102.                         standard variable 'environ' may be used).
  103.  
  104.  
  105. Return value:
  106.  
  107.             0000..00FF: The EXECed Program's return code
  108.             (0..255 decimal)
  109.             0100:       Error writing swap file
  110.             (256 decimal)
  111.             0200:       Program file not found
  112.             (512 decimal)
  113.             03xx:       DOS-error-code xx calling EXEC
  114.             (768..1023 decimal)
  115.             0400:       Error allocating environment buffer
  116.             (1024 decimal)
  117.             0500:       No room in low program memory, move spawn
  118.                         module to end of link
  119.             (1280 decimal)
  120.  
  121.  
  122.  
  123.                         RESTRICTIONS
  124.                         ============
  125.  
  126. The assembler module "spawn" must not be the first module linked.
  127. Either put it into a library, or specify spawn.obj as one of the last
  128. objects in the link command or the Turbo project file. The spawn
  129. module will overwrite about 1k at the start of the program image.
  130. Although the contents of this area will be saved, they may not
  131. contain parts of the spawn module itself, since this would destroy
  132. the code being executed.
  133.  
  134. The calling program may not have interrupt handlers installed when
  135. calling the do_exec function. This includes handlers for Control C
  136. and critical errors.
  137.  
  138. All open files will stay open during the EXEC call. This reduces the
  139. number of handles available to the child process. The "C_FILE_INFO"
  140. environment variable created by the standard C spawn is not supported.
  141.  
  142. BAT-files and internal commands are not automatically processed. You
  143. can execute those by calling the do_exec function twice, for example:
  144.  
  145. (C)     retcode = do_exec ("dir", "*.*", 1, 0xffff, environ);
  146.         if (retcode == 0x200)
  147.            retcode = do_exec ("", "/c dir *.*", 1, 0xffff, environ);
  148.  
  149. (P)     retcode := do_exec ('dir', '*.*', 1, $ffff, true);
  150.         if (retcode = $200)
  151.            retcode := do_exec ('', '/c dir *.*', 1, $ffff, true);
  152.  
  153.  
  154.  
  155.                         CAUTIONS
  156.                         ========
  157.  
  158. The functions should be compatible with DOS versions down to DOS
  159. 2.21, but they have been tested under DOS 3.3 and DOS 4.0 only.
  160.  
  161. Spawning a command that exits and stays resident (TSR), like PRINT or
  162. Sidekick, will fragment memory and prevent a return to the calling
  163. program. This should, however, not crash the system. Allocated EMS
  164. pages are released, but a swap file is not deleted.
  165.  
  166. The memory image of the calling program should be contiguous. This is
  167. always guaranteed if you use the standard Turbo C/Pascal allocation
  168. routines only. The swapper is able to swap non-contiguous blocks such
  169. as those created by the Microsoft far allocation routines. However,
  170. to do this, the swapper has to use undocumented fields in the memory
  171. control blocks, and modify DOS memory control blocks directly. This
  172. may lead to incompatibilities in later versions of DOS, or in DOS
  173. substitutes or emulators.
  174.  
  175. When debugging the assembler module, take care not to set breakpoints
  176. in the code while it is being swapped out. Those breakpoints (INT 3
  177. instructions) will be swapped back in later without the debugger
  178. knowing about it, and cause quite strange results when you run through
  179. the code for the second time.
  180.  
  181. Note that Turbo Pascal kills all debugging info when loading external
  182. assembler modules, so you can't step through SPAWN with TD in source
  183. mode.  You will have to open the CPU window to step through SPAWN if
  184. required. Turbo C does not have this problem.
  185.  
  186.  
  187.                         CONTENTS
  188.                         ========
  189.  
  190. This archive contains the following files:
  191.  
  192.     SPAWN.ASM       The main swap/exec function
  193.  
  194.         This file is common to the C and Pascal versions.
  195.         It must be assembled with Turbo-Assembler for use with
  196.         Pascal. The C version can be assembled with TASM (specify 
  197.         /JMASM51 on the command line) or MASM 5.1.
  198.  
  199.         To assemble:
  200.             tasm /DPASCAL spawn;            For Turbo Pascal, near calls
  201.             tasm /DPASCAL /DFARCALL spawn;  For Turbo Pascal, far calls
  202.             ?asm spawn;                     For C (default small model)
  203.             ?asm /DMODL=xxx spawn;          For C (model 'xxx')
  204.          Example:
  205.             masm /DMODL=large spawn;            Large model C
  206.             tasm /DMODL=medium /JMASM51 spawn;  Medium model C
  207.  
  208.     SPAWNPN.OBJ     SPAWN assembled for use with Pascal, near calls
  209.     SPAWNCS.OBJ     SPAWN assembled for use with C (small model)
  210.         
  211.         Rename the appropriate file to 'SPAWN.OBJ' for use with your
  212.         compiler. The CS file has been assembled with the /MX switch
  213.         for case-sensitive external linking.
  214.  
  215.         Note for Turbo Pascal: You can use the near call version of
  216.         SPAWN even when compiling with "force far calls" by enclosing
  217.         the external definition of do_spawn with {$F-} and {$F+}.
  218.  
  219.     EXEC.PAS        Interface routines for Turbo Pascal (5.x)
  220.     EXEC.C          Interface routines for Turbo C / MS-C
  221.     COMPAT.H        MS-C/TC Compatibility definitions for C
  222.  
  223.         These files prepare the parameters for the main spawn
  224.         function, and handle the file search and environment 
  225.         processing.
  226.  
  227.     EXTEST.C        Turbo C Test program for EXEC
  228.     EXTEST.PRJ      Turbo C 2.0 Project file for test program
  229.     EXTEST.PAS      Turbo Pascal Test program for EXEC
  230.  
  231.         The EXTEST program tests the functionality of the do_exec
  232.         function. It expects you to input a DOS-command and its
  233.         parameters, separated by a comma. Entering an empty line
  234.         will spawn a copy of COMMAND.COM without parameters.
  235.  
  236.  
  237. The Turbo Pascal version of EXEC.PAS includes replacement functions
  238. for the environment access functions 'envcount', 'envstr', and
  239. 'getenv', plus an additional function, 'putenv'. This function allows
  240. you to add strings to the environment for the spawned process. The
  241. definition is
  242.  
  243.         procedure putenv (envvar: string);
  244.  
  245. with 'envstr' containing a string of the form 'ENVVAR=value'. The '='
  246. is required. To delete an environment string, use 'ENVVAR='. Please
  247. use the environment functions from the EXEC unit only, do not mix them
  248. with calls to the DOS unit functions.
  249.  
  250.  
  251.                         Revision History
  252.                         ================
  253.  
  254. Changes from version 1.0 to 2.0:
  255.  
  256. 1) Problem fixes
  257.  
  258. - Problems with EMS drivers that return handles above 255 have been
  259.   fixed.
  260.  
  261. - Bug that prevented deletion of temporary file has been fixed.
  262.  
  263. - The Division by Zero interrupt vector is patched to an IRET and
  264.   restored when swapping back in.
  265.  
  266. - The /DFARCALL define has been added to the assembler module to
  267.   allow assembling for Turbo Pascal with "Force Far Calls" set.
  268.  
  269.  
  270. 2) Enhancements
  271.  
  272. - The TMP/TEMP environment string is checked for validity, and
  273.   is ignored if it points to a non-existent directory.
  274.  
  275. - For DOS versions 3.0 and above, the temporary file is created using
  276.   the special DOS function. This eliminates the extra overhead for
  277.   generating a unique filename.
  278.  
  279. - The C version is now compatible with Microsoft C 5.x.
  280.  
  281. - Non-contiguous memory blocks can be swapped.
  282.  
  283. - The 'spwn' parameter to the do_exec function has been changed to
  284.   allow EMS usage to be controlled. It can now have the values -1, 0,
  285.   and 1. For Pascal, the type of the parameter has been changed from
  286.   boolean to integer. The internal assembler routine takes an additional 
  287.   method parameter, it no longer uses the first byte of the swap-filename 
  288.   to determine swapping method.
  289.  
  290.  
  291. Changes from version 2.0 to 2.1/2.2:
  292.  
  293.   Several bugs in spawn.asm were fixed, no other changes.
  294.  
  295. Changes from version 2.1/2.2 to 2.3:
  296.  
  297. - When swapping to a file, the swap file is now closed before
  298.   spawning. This frees another file handle, and avoids problems
  299.   with programs (for example chkdsk) falsely claiming lost clusters.
  300.  
  301. - If the program consisted of multiple memory blocks (MS-C large
  302.   model, or blocks allocated with farmalloc), only the first (main
  303.   program/data) block was swapped out completely. All other blocks
  304.   in the MCB chain were swapped short if their length was not a
  305.   multiple of 16k bytes. This could cause problems on return.
  306.  
  307. - If the spawn module was linked as one of the first modules in a
  308.   program, the code in the module itself could get clobbered by
  309.   moving the code and setting up the data at the start of the 
  310.   program image. The spawn module now checks that it is located high
  311.   enough in memory.
  312.  
  313. - An unnecessary "offset" operator was removed from several statements 
  314.   in the assembler module to avoid spurious warnings when assembling
  315.   with MASM /W2. You will still get warnings when assembling with
  316.   /W2, but those warnings can not be eliminated (or at least I don't
  317.   know how). A symbol name was fixed to allow assembling with /ml.
  318.  
  319. - A pragma for Watcom C 8.0 was added to compat.h (supplied by T.
  320.   Frost).
  321.  
  322.  
  323.                            ACKNOWLEDGEMENTS
  324.                            ================
  325.  
  326. Thanks to H. Qualls, H. Gubler, J. Clinton, M. Adler, T. Frost, and
  327. other BIXen, for pointing out bugs and suggesting enhancements.
  328.  
  329.