DosStopSession can be used by a parent session to stop one or all of its child sessions. If the child session specified in the call to DosStopSession has related sessions, the related sessions are also ended. The parent session can be running in the foreground or the background when it calls DosStopSession. If the child session is running in the foreground when it is ended, the parent session becomes the foreground session.

DosStopSession can only be called by a parent session for a child session. Neither the parent session itself, nor any grandchild, nor any other descendant session beyond a child session, nor any unrelated session, can be the target of this call.

In the following code fragment, the child session specified by the ulSessionID parameter is ended:

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

    ULONG ulSessionID;

    DosStopSession(STOP_SESSION_SPECIFIED,
                   ulSessionID);

An application can end all its child sessions by setting the first parameter to STOP_SESSION_ALL in the call to DosStopSession. If this is specified, the second parameter is ignored.

A process running in a child session can ignore the request to end. If the process has set up its own exception handler, it might not end immediately after the call to DosStopSession. The only way the parent process can be certain that the child session has ended is to wait for notification through the termination queue specified in the call to DosStartSession that started the session. When the child session ends, OS/2 writes a data element into the termination queue, specifying the child process identifier and the termination status.

If the process in the session specified by DosStopSession has not ended, then DosStopSession still returns a normal return code. You can ensure that a process in a session has ended by waiting for notification from the termination queue specified with DosStartSession.