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.
Bindings
C
typedef struct _RESULTCODES { /* resc */ USHORT codeTerminate; /* Termination Code */ USHORT codeResult; /* Exit Code */ } RESULTCODES; #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.
#define INCL_DOSPROCESS #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 */