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