DosWaitChild

Syntax

rc = DosWaitChild( ulAction, ulWait, pReturnCodes, ppidOut, pidIn );

Parameters

ULONG ulAction (input): Specifies which process the current thread is waiting for to end. Values are:

Value  Name              Description
0      DCWA_PROCESS      The process indicated by pidIn
1      DCWA_PROCESSTREE  The process indicated by pidIn
                         and all of its child processes

ULONG ulWait (input): Specifies whether to return if no child process ends. Values are:

Value  Name         Description
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

PRESULTDATA pReturnCode (output): 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.
ULONG pReturnCode->codeTerminate (output): A code furnished by the system, describing why the child terminated. Values are:

Value  Name            Description
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

ULONG pReturnCode->codeResult (output): The result code specified by the terminating process on its last DosExit call.
PPID ppidOut (output): Pointer to the process ID of the ending process.
PID pidIn (input): 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;

Gotchas

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 occured */
   if(rc == ERROR_NO_CHILD_PROCESS)
   {
       printf("No child processes left!\n");
   }
   else
   {
       /* Any other error */

   }
}
else
{
   /* Success */
}