DosCwait

Bindings:  C, MASM 

This call places the current thread in a wait state until an asynchronous 
child process ends.  When the process ends, its process ID and termination 
code are returned to the caller. 

 DosCwait    (ActionCode, WaitOption, ReturnCodes, ProcessIDWord, 
             ProcessID) 
 

 ActionCode (USHORT) - input 
    The process whose termination is being waited for. 

    Value     Definition 
    0         The child process indicated by ProcessID. 
    1         The last descendant of the child process indicated by 
              ProcessID. 

 WaitOption (USHORT) - input 
    Return if no child process ends. 

    Value     Definition 
    0         Wait if no child process ends or until no child processes 
              are outstanding. 
    1         Do not wait for child processes to end. 

 ReturnCodes (PRESULTCODES) - output 
    Address of the structure containing the termination code and the 
    result code indicating the reason for the child's termination. 

    codeTerminate (USHORT) 
       The termination code furnished by the system describing why the 
       child terminated. 

       Value     Definition 
       0         EXIT (normal) 
       1         Hard error abort 
       2         Trap operation 
       3         Unintercepted DosKillProcess 

    codeResult (USHORT) 
       Result code specified by the terminating process on its last 
       DosExit call. 

 ProcessIDWord (PPID) - output 
    Address of the process ID of the ending process. 

 ProcessID (PID) - input 
    ID of the process whose termination is being waited for: 

    Value     Definition 
      0       Any child process. 
    <> 0      The indicated child process and all its descendants. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    13        ERROR_INVALID_DATA 
    128       ERROR_WAIT_NO_CHILDREN 
    129       ERROR_CHILD_NOT_COMPLETE 
    184       ERROR_NO_CHILD_PROCESS 
    303       ERROR_INVALID_PROCID 
 
 Remarks 

 DosCwait waits for completion of a child process, whose execution is 
 asynchronous to that of its parent process. The child process is created 
 by a DosExecPgm request with ExecFlags=2 specified. If the child process 
 has multiple threads, the result code returned by DosCwait is the one 
 passed to it by the DosExit request that terminates the process. 

 DosCwait can also wait for the descendant processes of a child process to 
 complete before it returns. However, it does not report status for 
 descendant processes. 

 To wait for all child processes and descendant processes to end, issue 
 DosCwait repeatedly, with ActionCode=1 andProcessID=0 specified, until 
 ERROR_NO_CHILD_PROCESS is returned. The contents of ProcessIDWord can be 
 examined to determine which child the termination codes are from. 

 If no child processes were started, DosCwait returns with an error. If no 
 child processes terminate, DosCwait can wait until one terminates before 
 returning to the parent, or it can return immediately if it specifies 
 WaitOption=1. This parameter is used to return the result code of a child 
 process that has already ended.