A process can end the execution of a descendant process by calling DosKillProcess. This causes OS/2 to send a XCPT_SIGNAL_KILLPROC exception to the target process. The child processes of the target process can also be ended.

The following code fragment ends the specified process and all child processes belonging to that process:

    #define INCL_DOSPROCESS       /* Process and thread values */
    #include <os2.h>

    PID pidProcess;

    DosKillProcess(DKP_PROCESSTREE,
                   pidProcess);

In this example, the pidProcess parameter specifies which descendant process to end. The process identifier is returned by DosExecPgm in the codeTerminate field of the RESULTCODES structure when you start the child process.

The parameter DKP_PROCESSTREE in the example indicates that the specified process, pidProcess, and all of its descendant processes are to be ended.

If you specify DKP_PROCESS in a call to DosKillProcess, only the specified process is ended. Its child processes, if any, continue to run.

The process to be ended must either be the current process, or it must have been directly created by the current process with DosExecPgm for asynchronous execution. That is, a process can end itself and its descendants.

The process to be ended need not still be executing. If it has started its own child processes, but has stopped executing, its children can still be flagged for termination.

Obtaining the Termination Status of a Child Process

OS/2 saves the termination status for a process if the process was started by using the EXEC_ASYNCRESULT constant in the call to DosExecPgm.
You can retrieve the termination status of the most recently ended process by using the DCWW_NOWAIT constant with DosWaitChild and setting the child process identification parameter to 0. The DCWW_NOWAIT constant directs the function to return immediately, without waiting for a process to end. Instead, the function retrieves the termination status from the process that most recently ended. If you specify a child process identification with DCWW_NOWAIT, DosWaitChild returns ERROR_CHILD_NOT_COMPLETE if the child process has not ended. Once the specified process has ended, DosWaitChild returns its termination code.

The following code fragment starts a child session (the program SIMPLE.EXE), and then retrieves the termination status from the process that most recently ended.

    #define INCL_DOSPROCESS         /* Process and thread values */
    #include <os2.h>
    #include <stdio.h>

    #define START_PROGRAM "SIMPLE.EXE"

    CHAR         szLoadError[100];
    PSZ          pszArgs;
    PSZ          pszEnvs;
    RESULTCODES  rcReturnCodes;
    ULONG        ulPid;           /* Process ID (returned)             */
    ULONG        ulTarget;        /* Process ID of process to wait for */
    APIRET       ulrc;            /* Return code                       */

    strcpy(pszArgs,
           "-a2 -l");   /* Pass arguments "-a2" and "-l"                         */

    ulTarget = 0;       /* Process ID for the most recently ended process   */

    ulrc = DosExecPgm(szLoadError,            /* Object name buffer                */
                      sizeof(szLoadError),    /* Length of object name buffer      */
                      EXEC_ASYNCRESULT,       /* Asynchronous/Trace flags          */
                      pszArgs,                /* Argument string                   */
                      pszEnvs,                /* Environment string                */
                      &rcReturnCodes,         /* Termination codes                 */
                      START_PROGRAM);         /* Program file name                 */

    if (ulrc != 0) {
        printf("DosExecPgm error: return code = %ld",
               ulrc);
        return;
    }

    ulrc = DosWaitChild(DCWA_PROCESS,         /* Execution options                 */
                        DCWW_NOWAIT,          /* Wait options                      */
                        &rcReturnCodes,       /* Termination codes                 */
                        &ulPid,               /* Process ID (returned)             */
                        ulTarget);            /* Process ID of process to wait for */

    if (ulrc != 0) {
        printf("DosWaitChild error: return code = %ld",
               ulrc);
        return;
    }