DosCwait

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.

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

Parameters

 * ActionCode (USHORT) - input : The process whose termination is being waited for.
 * 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.
 * 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.
 * 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:
 * 0 - Any child process.
 * <> 0 - The indicated child process and all its descendants.

Return Code

 * 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.

C
 typedef struct _RESULTCODES { /* resc */ USHORT codeTerminate;       /* Termination Code */ USHORT codeResult;          /* Exit Code */ } RESULTCODES;


 * 1) define INCL_DOSPROCESS

USHORT rc = DosCwait(ActionCode, WaitOption, ReturnCodes, ProcessIDWord,                             ProcessID);

USHORT      ActionCode;    /* Execution options */ USHORT      WaitOption;    /* Wait options */ PRESULTCODES ReturnCodes;  /* Termination Codes (returned) */ PPID        ProcessIDWord; /* Process ID (returned) */ PID         ProcessID;     /* Process ID of process to wait for */

USHORT      rc;            /* return code */ 

MASM
 RESULTCODES struc resc_codeTerminate dw ? ;Termination Code resc_codeResult   dw  ? ;Exit Code RESULTCODES ends

EXTRN DosCwait:FAR INCL_DOSPROCESS    EQU 1

PUSH  WORD    ActionCode    ;Execution options PUSH  WORD    WaitOption    ;Wait options PUSH@ DWORD   ReturnCodes   ;Termination Codes (returned) PUSH@ WORD    ProcessIDWord ;Process ID (returned) PUSH  WORD    ProcessID     ;Process ID of process to wait for CALL  DosCwait

Returns WORD 

Example
This example starts a child session (the program simple.exe) and then waits for the child process's termination. 
 * 1) define INCL_DOSPROCESS
 * 2) define START_PROGRAM "simple.exe"

CHAR       LoadError[100]; PSZ        Args; PSZ        Envs; RESULTCODES ReturnCodes; USHORT     Pid; USHORT     rc;

strcpy(Args, "-a2 -l");           /* Pass arguments '-a2' and '-l' */ if(!DosExecPgm(LoadError,         /* Object name buffer */ sizeof(LoadError), /* Length of object name buffer */ EXEC_ASYNCRESULT,  /* Asynchronous/Trace flags */ Args,              /* Argument string */ Envs,              /* Environment string */ &ReturnCodes,      /* Termination codes */ START_PROGRAM))    /* Program file name */ rc = DosCwait(DCWA_PROCESS,     /* Execution options */                   DCWW_WAIT,         /* Wait options */                   &ReturnCodes,      /* Termination codes */                   &Pid,              /* Process ID */                   ReturnCodes.codeTerminate); /* Process ID of process to wait for */ 