home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c221 / 5.ddi / MWHC.005 / 33 < prev    next >
Encoding:
Text File  |  1992-12-09  |  7.8 KB  |  176 lines
  1. { (C) Copyright  1986-1992 MetaWare Incorporated;  Santa Cruz, CA 95060. }
  2.  
  3. pragma C_include('implement.pf');
  4. package Exec;
  5.    pragma Routine_aliasing_convention(Implement.RTE_aliasing);
  6.    with Loopholes:[Address];
  7.    
  8.    -- This package defines both the Pascal and C version of the exec
  9.    -- routines.  The Pascal libraries contain all but c_command.
  10.    -- The C libraries contain only the c_xxx routines.
  11.    -- For instructions on how to use these routines, see the end of this file.
  12. #ifdef CDOS
  13.    type Exec_return = Longint;
  14. #else
  15.    type Exec_return = Integer;
  16. #endif      
  17.    
  18.    function Exec  (const Progname, Commandstring:String):Exec_return;   external;
  19.  
  20. #ifndef CDOS
  21.    function Exec_env
  22.       (const Progname, Commandstring, Environment: String):Exec_return; external;
  23. #endif
  24.  
  25.    -- Execute "command -C S" where S is an arbitrary string you supply.
  26.    -- We use -C or /C depending upon the setting of the switch character.
  27.    -- We determine where command is by obtaining comspec from the environment.
  28.    -- For MS-DOS:
  29.    -- UNFORTUNATELY MS-DOS's command does NOT propagate the return code
  30.    -- of the command executed, so that the return code is that of command.com,
  31.    -- not of the command executed.
  32.    function Command(const S:String):Exec_return;        External;
  33.  
  34. #ifndef CDOS
  35.    -- C versions.  The first parameter is a nul-terminated string.   
  36.    -- For C_exec_env, the length of the environment must be passed in.
  37.    function C_exec_env
  38.       (Progname, Commandstring, Environment: Address; Envlen:Cardinal):Exec_return;
  39.                                        external;
  40.    function C_exec(Progname, Commandstring: Address):Exec_return;    External;
  41.    -- "C_command" in C is known as "System" and is in the standard library.
  42.    -- Internally used function ExecX.  Prog is a nul-terminated string,
  43.    -- and Envseg:0 points to the environment.
  44.    function ExecX(Prog,Parms:Address; Envseg:Cardinal):Exec_return; External;
  45. #endif
  46.    end;
  47.    
  48. #if 0 
  49.                   How to EXEC subprocesses in MetaWare Pascal.
  50.  
  51. There are two parts to this documentation:  an explanation of how the
  52. functions work, and an explanation of memory requirements.  Be sure to
  53. read the latter, no matter which function you intend to use.
  54.  
  55. You can use the library functions Exec, Exec_env, and Command for executing
  56. subprocesses (to completion), and obtaining their return code.  (On DOS this
  57. is the return code from COMMAND.COM; unfortunately it't only whether or not
  58. the program loaded.)
  59.  
  60. Command takes an arbitrary string S and passes it to COMMAND.COM for execution.
  61. For example:
  62.  
  63.     Command('ls *.p');
  64.     
  65. is the same as if you had typed 
  66.  
  67.     command -C ls *.p
  68.     
  69. at a DOS prompt.  This only works if the COMSPEC environment variable is
  70. properly set to the path for COMMAND.COM.
  71.     
  72. Exec takes a program name to execute (you must specify the program
  73. name completely; no searching of the environment variable PATH is done) and
  74. a parameter string.
  75.  
  76. The parameter string S is at most 129 bytes long.  The first byte is the 
  77. number of characters following the first byte.  For example:
  78.  
  79.    var S:String(10); Rtn:Exec_return;
  80.    begin
  81.    S := chr(5) || '*.asm';
  82.    Rtn := Exec('/bin/ls.exe',S);
  83.    -- Rtn holds whatever ls.exe returned at termination.
  84.    end;
  85.    
  86. Exec_env is the same as Exec except it also takes an environment string.
  87. The environment string is of the form
  88.     S* 0              (S* means zero or more S's)
  89. where each S is of the form
  90.     character-string 0
  91. and each character-string of the form
  92.     somename=sometext
  93. "somename" is the name of the environment variable; sometext is its value.
  94. See the "set" command in your DOS manual, and the description of the
  95. environment in the DOS technical reference manual.
  96. For example:
  97.  
  98.    var Env:string(50); Rtn:Exec_return;
  99.    begin
  100.    Env := 'VAR1=a b' || chr(0) || 'VAR2=xyz' || chr(0) 
  101.        || 'COMSPEC=c:\command.com' || chr(0) || chr(0);
  102.    Rtn := 
  103.       Exec_env('c:\command.com',
  104.            chr(9) || '/C set' || chr(#0d) || ' ' || chr(0)),
  105.            Env);
  106.    end;
  107.    
  108. executes command.com with the instruction to print out the environment
  109. ("set").  The environment printed will contain just VAR1, VAR2, and COMSPEC
  110. (variables should be in upper case to conform to DOS conventions).
  111. Also, if you omit COMSPEC from the environment, COMMAND.COM will hang.
  112. This appears to be a DOS bug.
  113.  
  114. Note the extra characters chr(#0d) || ' ' || chr(0).  Apparently command.com
  115. has a bug in it in that it expects those characters to be there; it won't
  116. work without them.  We have found this to be the case with some other
  117. software as well -- in one particular case, a networking program net.exe.
  118. If you have trouble using Exec or Exec_env directly, try appending those
  119. three characters to see if the program being exec-ed suffers from the
  120. same bug.
  121.  
  122.    
  123. MEMORY REQUIREMENTS FOR EXEC-ing PROGRAMS:
  124.  
  125. For EXEC to work in small-data memory models (small and medium) nothing
  126. need be done.  However, note that by default 64K of stack and heap
  127. will be consumed by a small-data-model program, and the rest freed to
  128. DOS for use in EXECing subprograms.  To reduce the 64K to less, you must
  129. use the CPARMAXALLOC parameter to the Microsoft linker when linking the
  130. program.  CPARMAXALLOC is the number of paragraphs you want to use
  131. for both heap and stack in your program.
  132. For example, /CPARMAXALLOC:100 specifies only 100 paragraphs
  133. (= 1600 bytes) of memory to be made available; the default is FFFF
  134. (= 1 megabyte), so that the maximum memory is allocated.  You can
  135. also change this value at a late date by modifying locations C and D (hex)
  136. of the .exe file; therein is stored CPARMAXALLOC.
  137.  
  138. For EXEC to work in non-small-data memory models (compact, big, large),
  139. you must provide that some memory is given back to DOS.  Again, you
  140. can use CPARMAXALLOC to reduce the memory requirements.  If your program's
  141. memory requirements don't vary much, this is an acceptable solution.
  142. However, if your program could effectively use all of memory sometimes,
  143. then you need a solution that allows use of all of memory but takes that
  144. memory only as it needs it, leaving the rest for EXECing programs.
  145. This second solution is obtained by specifying that
  146. the run-time system should 
  147.     (a) allocate a stack of fixed size, 
  148.     (b) free all other memory back to DOS, and finally 
  149.     (c) allocate any heap by calling DOS to get the memory.  
  150. To do this you will need
  151. the Microsoft MASM assembler to re-assemble the initializer, and you
  152. will need to link in an alternative memory allocation routine rather
  153. than the default one supplied in the library.  Do the following to 
  154. the initiliazer source init.asm in the lib/src subdirectory:
  155.  
  156.    a. Set variable STACK_SIZE to whatever size you want the stack.
  157.       (Normally the stack size is dependent only upon available memory
  158.       and the architecture-imposed restriction of 64K max.)
  159.       For example, "STACK_SIZE = 2000" bytes.  
  160.       (For more information on STACK_SIZE, see initializer source.)
  161.    b. Set variable USE_DOS_ALLOC (to anything).  For example,
  162.       "USE_DOS_ALLOC = 1".
  163.       (For more information on USE_DOS_ALLOC, see initializer source.)
  164.    c. Assemble the initializer from the appropriate model subdirectory
  165.       so that the memory model information is set properly.   
  166.    d. Link your program with "dosalloc.obj" included (the Pascal source to
  167.       dosalloc.p is provided, and for the C compiler, a version of
  168.       dosalloc.obj is provided for the compact, big, and large models), 
  169.       and with the newly-assembled initializer.
  170.       
  171. The primary disadvantage of using DOS to allocate memory is that
  172. if your program erroneously writes out of bounds of allocated memory,
  173. you will clobber DOS's memory links and it will print out
  174. "memory allocation error" and HALT THE OS, requiring a reboot, with
  175. no chance of debugging your program.
  176.