Liren Large Software Subsidy 7/07.iso/c/c221/6.ddi/MWHC.006/7

Text File | 1992-12-09 | 6.2 KB | 146 lines

/*
 *   exec.cf -- extra-ANSI
 *
 *   Facilities for executing subprocesses.
 *
 *           Copyright (c) 1990, MetaWare Incorporated
 */

#ifndef _EXEC_CF
#define _EXEC_CF

#include <implemen.cf>
#include <language.cf>
#pragma Global_aliasing_convention(_Private_routine_prefix "%r");
#pragma Calling_convention(PASCAL);

/* Progname is a nul-terminated string naming the program to be executed.
 */
int c_exec(char *Progname, void *Commandstring);

/* Progname is a nul-terminated string, and the length of
 * the environment must be passed in.
 */
int c_exec_env
   (char *Progname, char *Commandstring, char *Environment, unsigned Envlen);

#pragma Global_aliasing_convention();
#pragma Calling_convention();

#if 0
                  How to EXEC subprocesses in MetaWare High C.

There are two parts to this documentation:  an explanation of how the
functions work, and an explanation of memory requirements.  Be sure to
read the latter, no matter which function you intend to use.

You can use the library functions c_exec, c_exec_env, and system for executing
subprocesses (to completion), and obtaining their return code.  (On DOS this
is the return code from COMMAND.COM; unfortunately it-s only whether or not the
program loaded.)  system is ANSI-standard; the other two are not.  To use the
first two you MUST include the "exec.cf" header file.  To use system you can
include stdlib.h to obtain type-checking protection, but you need not include
anything.

system takes an arbitrary string S and passes it to COMMAND.COM for execution.
For example:

    system("ls *.p");

is the same as if you had typed

    command -C ls *.p

at a DOS prompt.  This only works if the COMSPEC environment variable is
properly set to the path for COMMAND.COM.

c_exec takes a program name to execute (you must specify the program
name completely; no searching of the environment variable PATH is done) and
a parameter string.

The parameter string S is at most 129 bytes long.  The first byte is the
number of characters following the first byte.  For example:

   c_exec("/bin/ls.exe","\5*.asm");

c_exec_env is the same as c_exec except it also takes an environment string.
The environment string is of the form
    S* 0               (S* means zero or more Ss)
where each S is a C string (nul-terminated) of the form
    somename=sometext
"somename" is the name of the environment variable; sometext is its value.
See the "set" command in your DOS manual, and the description of the
environment in the DOS technical reference manual.
For example:

   #define ENV "VAR1=a b\0VAR2=xyz\0COMSPEC=c:\\command.com\0\0"
   c_exec_env("c:/command.com",
           "\x9/C set\xd ",
           ENV, sizeof(ENV));

executes command.com with the instruction to print out the environment
("set").  The environment printed will contain just VAR1, VAR2, and COMSPEC
(variables should be in upper case to conform to DOS conventions).
Note also that the length of the enviroment must be passed in since
embedded 0s prevent "strlen" from being used.
Also, if you omit COMSPEC from the environment, COMMAND.COM will hang.
This appears to be a DOS bug.


MEMORY REQUIREMENTS FOR EXEC-ing PROGRAMS:

For EXEC to work in small-data memory models (small and medium) nothing
need be done.  However, note that by default 64K of stack and heap
will be consumed by a small-data-model program, and the rest freed to
DOS for use in EXECing subprograms.  To reduce the 64K to less, you must
use the CPARMAXALLOC parameter to the Microsoft linker when linking the
program.  CPARMAXALLOC is the number of paragraphs you want to use
for both heap and stack in your program.
For example, -CPARMALLOC:100 specifies only 100 paragraphs
(= 1600 bytes) of memory to be made available; the default is FFFF
(= 1 megabyte), so that the maximum memory is allocated.  You can
also change this value at a late date by modifying locations C and D (hex)
of the .exe file; therein is stored CPARMAXLLOC.

For EXEC to work in non-small-data memory models (compact, big, large),
you must provide that some memory is given back to DOS.  Again, you
can use CPARMAXLLOC to reduce the memory requirements.  If your program-s
memory requirements don-t vary much, this is an acceptable solution.
However, if your program could effectively use all of memory sometimes,
then you need a solution that allows use of all of memory but takes that
memory only as it needs it, leaving the rest for EXECing programs.
This second solution is obtained by specifying that
the run-time system should
    (a) allocate a stack of fixed size,
    (b) free all other memory back to DOS, and finally
    (c) allocate any heap by calling DOS to get the memory.
To do this you will need
the Microsoft MASM assembler to re-assemble the initializer, and you
will need to link in an alternative memory allocation routine rather
than the default one supplied in the library.  Do the following to
the initiliazer source init.asm in the lib/src subdirectory:

   a. Set variable STACK_SIZE to whatever size you want the stack.
      (Normally the stack size is dependent only upon available memory
      and the architecture-imposed restriction of 64K max.)
      For example, "STACK_SIZE = 2000" bytes.
      (For more information on STACK_SIZE, see initializer source.)
   b. Set variable USE_DOS_ALLOC (to anything).  For example,
      "USE_DOS_ALLOC = 1".
      (For more information on USE_DOS_ALLOC, see initializer source.)
   c. Assemble the initializer from the appropriate model subdirectory
      so that the memory model information is set properly.
   d. Link your program with "dosalloc.obj" included (the Pascal source to
      dosalloc.p is provided, and for the C compiler, a version of
      dosalloc.obj is provided for the compact, big, and large models),
      and with the newly-assembled initializer.

The primary disadvantage of using DOS to allocate memory is that
if your program erroneously writes out of bounds of allocated memory,
you will clobber DOS-s memory links and it will print out
"memory allocation error" and HALT THE OS, requiring a reboot, with
no chance of debugging your program.

#endif
#endif /* _EXEC_CF */