home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c220 / 4.ddi / INC / EXEC.CF < prev    next >
Encoding:
Text File  |  1990-12-16  |  6.4 KB  |  150 lines
  1. /*
  2.  *   exec.cf -- non-ANSI
  3.  *
  4.  *   Facilities for executing subprocesses.
  5.  *
  6.  *   These routines have been superceeded by the _spawn series of functions.
  7.  *   It is recommended that all programs use the _spawn functions instead of
  8.  *   the facility described here. Also, some of the notes here about initializer 
  9.  *   modifications apply to the 80x86 compiler, but not the 80386.
  10.  *
  11.  *           Copyright (c) 1990, MetaWare Incorporated
  12.  */
  13.  
  14. #ifndef _EXEC_CF
  15. #define _EXEC_CF
  16.  
  17. #include <implemen.cf>
  18. #include <language.cf>
  19. #pragma Global_aliasing_convention(_Private_routine_prefix "%r");
  20. #pragma Calling_convention(PASCAL);
  21.  
  22. /* Progname is a nul-terminated string naming the program to be executed.  */
  23.  
  24. int c_exec(char *Progname, void *Commandstring);
  25.  
  26. /* Progname is a nul-terminated string, and the length of
  27.  * the environment must be passed in.
  28.  */
  29. int c_exec_env
  30.    (char *Progname, char *Commandstring, char *Environment, unsigned Envlen);
  31.  
  32. #pragma Global_aliasing_convention();
  33. #pragma Calling_convention();
  34.  
  35. #if 0
  36.                   How to EXEC subprocesses in MetaWare High C.
  37.  
  38. There are two parts to this documentation:  an explanation of how the
  39. functions work, and an explanation of memory requirements.  Be sure to
  40. read the latter, no matter which function you intend to use.
  41.  
  42. You can use the library functions c_exec, c_exec_env, and system for executing
  43. subprocesses (to completion), and obtaining their return code.  (On DOS this
  44. is the return code from COMMAND.COM; unfortunately it-s only whether or not the
  45. program loaded.)  system is ANSI-standard; the other two are not.  To use the
  46. first two you MUST include the "exec.cf" header file.  To use system you can
  47. include stdlib.h to obtain type-checking protection, but you need not include
  48. anything.
  49.  
  50. system takes an arbitrary string S and passes it to COMMAND.COM for execution.
  51. For example:
  52.  
  53.     system("ls *.p");
  54.  
  55. is the same as if you had typed
  56.  
  57.     command -C ls *.p
  58.  
  59. at a DOS prompt.  This only works if the COMSPEC environment variable is
  60. properly set to the path for COMMAND.COM.
  61.  
  62. c_exec takes a program name to execute (you must specify the program
  63. name completely; no searching of the environment variable PATH is done) and
  64. a parameter string.
  65.  
  66. The parameter string S is at most 129 bytes long.  The first byte is the
  67. number of characters following the first byte.  For example:
  68.  
  69.    c_exec("/bin/ls.exe","\5*.asm");
  70.  
  71. c_exec_env is the same as c_exec except it also takes an environment string.
  72. The environment string is of the form
  73.     S* 0               (S* means zero or more Ss)
  74. where each S is a C string (nul-terminated) of the form
  75.     somename=sometext
  76. "somename" is the name of the environment variable; sometext is its value.
  77. See the "set" command in your DOS manual, and the description of the
  78. environment in the DOS technical reference manual.
  79. For example:
  80.  
  81.    #define ENV "VAR1=a b\0VAR2=xyz\0COMSPEC=c:\\command.com\0\0"
  82.    c_exec_env("c:/command.com",
  83.            "\x9/C set\xd ",
  84.            ENV, sizeof(ENV));
  85.  
  86. executes command.com with the instruction to print out the environment
  87. ("set").  The environment printed will contain just VAR1, VAR2, and COMSPEC
  88. (variables should be in upper case to conform to DOS conventions).
  89. Note also that the length of the enviroment must be passed in since
  90. embedded 0s prevent "strlen" from being used.
  91. Also, if you omit COMSPEC from the environment, COMMAND.COM will hang.
  92. This appears to be a DOS bug.
  93.  
  94.  
  95. MEMORY REQUIREMENTS FOR EXEC-ing PROGRAMS:
  96.  
  97. For EXEC to work in small-data memory models (small and medium) nothing
  98. need be done.  However, note that by default 64K of stack and heap
  99. will be consumed by a small-data-model program, and the rest freed to
  100. DOS for use in EXECing subprograms.  To reduce the 64K to less, you must
  101. use the CPARMAXALLOC parameter to the Microsoft linker when linking the
  102. program.  CPARMAXALLOC is the number of paragraphs you want to use
  103. for both heap and stack in your program.
  104. For example, -CPARMALLOC:100 specifies only 100 paragraphs
  105. (= 1600 bytes) of memory to be made available; the default is FFFF
  106. (= 1 megabyte), so that the maximum memory is allocated.  You can
  107. also change this value at a late date by modifying locations C and D (hex)
  108. of the .exe file; therein is stored CPARMAXLLOC.
  109.  
  110. For EXEC to work in non-small-data memory models (compact, big, large),
  111. you must provide that some memory is given back to DOS.  Again, you
  112. can use CPARMAXLLOC to reduce the memory requirements.  If your program-s
  113. memory requirements don-t vary much, this is an acceptable solution.
  114. However, if your program could effectively use all of memory sometimes,
  115. then you need a solution that allows use of all of memory but takes that
  116. memory only as it needs it, leaving the rest for EXECing programs.
  117. This second solution is obtained by specifying that
  118. the run-time system should
  119.     (a) allocate a stack of fixed size,
  120.     (b) free all other memory back to DOS, and finally
  121.     (c) allocate any heap by calling DOS to get the memory.
  122. To do this you will need
  123. the Microsoft MASM assembler to re-assemble the initializer, and you
  124. will need to link in an alternative memory allocation routine rather
  125. than the default one supplied in the library.  Do the following to
  126. the initiliazer source init.asm in the lib/src subdirectory:
  127.  
  128.    a. Set variable STACK_SIZE to whatever size you want the stack.
  129.       (Normally the stack size is dependent only upon available memory
  130.       and the architecture-imposed restriction of 64K max.)
  131.       For example, "STACK_SIZE = 2000" bytes.
  132.       (For more information on STACK_SIZE, see initializer source.)
  133.    b. Set variable USE_DOS_ALLOC (to anything).  For example,
  134.       "USE_DOS_ALLOC = 1".
  135.       (For more information on USE_DOS_ALLOC, see initializer source.)
  136.    c. Assemble the initializer from the appropriate model subdirectory
  137.       so that the memory model information is set properly.
  138.    d. Link your program with "dosalloc.obj" included (the Pascal source to
  139.       dosalloc.p is provided, and for the C compiler, a version of
  140.       dosalloc.obj is provided for the compact, big, and large models),
  141.       and with the newly-assembled initializer.
  142.  
  143. The primary disadvantage of using DOS to allocate memory is that
  144. if your program erroneously writes out of bounds of allocated memory,
  145. you will clobber DOS-s memory links and it will print out
  146. "memory allocation error" and HALT THE OS, requiring a reboot, with
  147. no chance of debugging your program.
  148. #endif
  149. #endif /* _EXEC_CF */
  150.