Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSPROCESS
 
USHORT DosCwait(fScope, fWait, prescResults, ppidProcess,
    pidWaitProcess)
USHORT fScope;             /* flag scope                                  */
USHORT fWait;              /* wait/no-wait flag                           */
PRESULTCODES prescResults; /* pointer to structure receiving result codes */
PPID ppidProcess;          /* pointer to variable for process identifier  */
PID pidWaitProcess;        /* process identifier of process to wait for   */
 
The DosCwait function waits for a child process to terminate, then retrieves
the result codes from that process. The function copies the process
identifier of the terminated process to the variable pointed to by the
ppidProcess parameter and copies a termination code to the structure pointed
to by the prescResults parameter.
 
Parameter       Description
────────────────────────────────────────────────────────────────────────────
 
fScope          Specifies how many processes to wait for. If the value of
                this parameter is DCWA_PROCESS, the thread waits until the
                specified process ends. If it is DCWA_PROCESSTREE, the
                thread waits until the specified process and all its child
                processes end.
 
fWait           Specifies whether or not to wait for child processes. If
                this parameter is DCWW_WAIT, the thread waits while child
                processes are running. If it is DCWW_NOWAIT, the thread does
                not wait. This option is used to retrieve the result codes
                of a child process that has already ended.
 
prescResults    Points to the RESULTCODES structure that receives the
                termination code and result code for the child process's
                termination.
 
ppidProcess     Points to the variable that receives the process identifier
                of the ending process.
 
pidWaitProcess  Specifies which process to wait for. If this parameter is a
                process identifier, the thread waits for that process to
                end. If it is zero, the thread waits until any child process
                ends.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_CHILD_NOT_COMPLETE
     ERROR_INVALID_PROCID
     ERROR_WAIT_NO_CHILDREN
 
Comments
 
The DosCwait function may wait for a child process and any processes started
by the child process to end before it returns, but it will not report the
status of the processes that were started by the child process.
 
When the function is waiting for more then one child process, the
ppidProcess variable is used to determine which child process has
terminated.
 
Do not call the DosCwait function before starting a child process. When this
happens, the process calling DosCwait waits indefinitely, since a child
process cannot start asynchronously.
 
Example
 
This example runs the cmd.exe program as a child process, then calls the
DosCwait function to wait until cmd.exe terminates:
 
UCHAR szFailName[CCHMAXPATH];
RESULTCODES rescResults;
PID pidProcess;
DosExecPgm(szFailName, sizeof(szFailName),
    EXEC_ASYNC, "cmd\0", 0, &rescResults, "cmd.exe");
    .
    .
    .
DosCwait(DCWA_PROCESS,          /* execution flag                */
    DCWW_WAIT,                  /* wait option                   */
    &rescResults,               /* address for result codes      */
    &pidProcess,                /* address of process identifier */
    rescResults.codeTerminate); /* process to wait for           */
 
See Also
 
DosExecPgm, DosExit, DosKillProcess, RESULTCODES
 
                                      ♦