DosCwait

Legacy Function Warning
It is recommended to use a newer replacement for this function.
Replacement:	DosWaitChild
Remarks:	This function was renamed on DosWaitChild on OS/2 2.0.

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.

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.

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.

Example Code

C Binding

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

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

MASM Binding

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