DosExecPgm

DosExecPgm creates a child process which can be either synchronous, asynchronous or detached. The child process must of the same type as the parent process (i.e. a PM process can only start another PM process, unless the non-PM process doesn't perform any I/O). If a non-PM process wants to start a PM process, or a PM process wants to start a non-PM process which does I/O, DosStartSession must be used.

Syntax
rc = DosExecPgm( pchProcName, lProcName, ulExecFlag, pszArg, pszEnv, prcRes, pszName );

Parameters

 * PCHAR pchProcName (output)
 * This is the address of the buffer which contains the name of the process that is responsible if the DosExecPgm failure is returned. For instance, if the parent process tries to running an program which doesn't exist, the inexistent file name will be put into this buffer.


 * LONG lProcName (input)
 * This is the length, in bytes, of the buffer pchProcName


 * ULONG ulExecFlag (input)
 * This is the flag which will lead the child process. There are the possible values:

Warning : unless using EXEC_SYNC and EXEC_ASYNC, result codes should be retrieved with DosWaitChild in order to avoid wasting memory, even if the result codes won't be used later.
 * PSZ pszArg (input)
 * This is the address of the argument string passed to the process. Example of a such argument string:
 * "UNZIP\0-l MYARCHIVE.ZIP *.BMP\0"
 * By default, the file name is searched in the default directory and through the PATH variable. If the program name isn't present into the PATH variable, the comprehensive access path must be present.
 * There are always a '\0' between the program name and the parameters. Moreover, a second '\0' must also be placed at the end of the argument string.


 * PSZ pszEnv (input)
 * This is the address of the environment string passed to the process. When a NULL value is passed into pszEnv, the child process will inherit the environment of its parent.


 * PSZ pszRes (output)
 * This is a pointer to the RESULTCODES structure.


 * PSZ pszName (input)
 * This is the address of the string which contains the file name of the child process with its extension which must be present.

Returns

 * APIRET rc: The following values can be returned:

Relevant Structures
typedef struct _RESULTCODES { /* Termination code or process identifier. */  ULONG codeTerminate; /* Exit code. */  ULONG codeResult; } RESULTCODES, *PRESULTCODES;

Gotchas
Do NOT launch a synchronous PM child process from a single-threaded PM process! It will choke the system messaging queue and you will have to do Ctrl-Esc to kill the process. I don't know if this problem will also appear from a multi-threaded PM process.

Sample Code
UCHAR pchProcName[CCHMAXPATH] = {0} ;	/* Error info from DosExecPgm */ UCHAR pszArgString[CCHMAXPATH+41] ;	/* Argument string */ RESULTCODES ChildRC = {0} ;		/* Results from child process */ PID pidChild = 0 ;			/* PID for child process */ APIRET rc = NO_ERROR ; 			/* Return code */ /* creating the argument string */ sprintf(pszArgString, "UNZIP MYARCHIVE.ZIP %s\0", 	       pszWhichFilesToBeExtracted) ; /* if the 2nd parameter of the sprint would be like : */ /* "UNZIP\0MYARCHIVE.ZIP %s\0" */ /* so the %s will never be filled ! */ 	/* It is why that we have to set the '\0' after the sprintf */ pszArgString[5] = '\0' ; rc = DosExecPgm(pchProcName, sizeof pchProcName, EXEC_SYNC, 	               pszArgString, NULL, &ChildRC, "UNZIP.EXE") ; if (rc != NO_ERROR) { 		/* handle the error */ } 	else { 		/* The extraction is successful ! */ 		/* Handle the resulted files */ }
 * 1) define INCL_DOSPROCESS
 * 2) include 