DosWaitChild

Syntax

DosWaitChild( ulAction, ulWait, pReturnCodes, ppidOut, pidIn )

Parameters

ulAction (ULONG)

Specifies which process the current thread is waiting for to end. Values are:

0 - DCWA_PROCESS - The process indicated by pidIn

1 - DCWA_PROCESSTREE - The process indicated by pidIn and all of its child processes

ulWait (ULONG)

Specifies whether to return if no child process ends. Values are:

0 - DCWW_WAIT - Wait if no child process ends or until no child processes are outstanding.

1 - DCWW_NOWAIT Do not wait for child processes to end

pReturnCode (PRESULTDATA)

Pointer to a RESULTDATA structure holding exit information from the ending process. If no processes furnish a result code, the system provides the value -1.

pReturnCode->codeTerminate (ULONG)

A code furnished by the system, describing why the child terminated. Values are:

0 - TC_EXIT - Normal exit

1 - TC_HARDERROR - Hard-error halt

2 - TC_TRAP - Trap operation for a 16-bit child process

3 - TC_KILLPROCESS - Unintercepted DosKillProcess

4 - TC_EXCEPTION - Exception operation for a 32-bit child process

pReturnCode->codeResult (ULONG)

The result code specified by the terminating process on its last DosExit call.

ppidOut (PPID)

ointer to the process ID of the ending process.

pidIn (PID)

Process ID of the child process (and all its descendants) whose termination is being waited for. If 0 then any child process that was executed with a return code, or until there are no more child processes of any type to wait for.

Returns

APIRET rc

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

Include Info

#define INCL_DOSPROCESS
#include <os2.h>

Usage Explanation

DosWaitChild waits for an asynchronous child process to end and gets its process identifier, termination code and result code. It is also possible to check if the child process has already ended and get information about already ended child processes.

Relevant Structures

typedef struct _RESULTCODES
{
  ULONG codeTerminate;
  ULONG codeResult;
} RESULTCODES, *PRESULTCODES;

Sample Code

#define INCL_DOSPROCESS
#include <os2.h>
#include <stdio.h>

APIRET rc;             /* return code from tha API's          */
RESULTCODES rcResult;  /* Result code for the child process   */
PID pidChild;          /* The process ID of the child process */ 

/* Start a child process with DosExecPgm */
if(rc=DosWaitChild(DCWA_PROCESS, /* Wait for a child process            */
               DCWW_WAIT,        /* Wait for a process to end           */
               &rcResult,        /* Result code                         */
               &pidChild,        /* The process ID of the child process */
                                 /* that ended                          */
               0))               /* Wait  for any child process to end  */
{
   /* An error occurred */
   if(rc == ERROR_NO_CHILD_PROCESS)
   {
       printf("No child processes left!\n");
   }
   else
   {
       /* Any other error */
   }
}
else
{
   /* Success */
}

See Also

• DosExecPgm
• DosKillProcess