DosStopSession

From EDM2
Jump to: navigation, search
DosStopSession

Syntax

rc = DosStopSession( ulScope, ulIDSession );

Parameters

ULONG ulScope (input)
Specifies whether a given child session or all child sessions should be ended. Values are:
Value  Name                    Description
0      STOP_SESSION_SPECIFIED  End the child session specified in ulIDSession
1      STOP_SESSION_ALL        End all child sessions.
                               ulIDSession is ignored
ULONG ulIDSession (input)
Specifies which child session to stop. ulScope must be STOP_SESSION_SPECIFIED (=0).

Returns

APIRET  rc
0       NO_ERROR
369     ERROR_SMG_INVALID_SESSION_ID
418     ERROR_SMG_INVALID_CALL
458     ERROR_SMG_INVALID_STOP_OPTION
459     ERROR_SMG_BAD_RESERVE
460     ERROR_SMG_PROCESS_NOT_PARENT
463     ERROR_SMG_RETRY_SUB_ALLOC

Usage Explanation

DosStopSession ends one or all child sessions. Only a child session started with DosStartSession, with Related set to SSF_RELATED_CHILD (=1), can be ended with DosStopSession. If the child session has related child sessions these are also ended. If the child process is executed in the foreground when it is ended the parent session becomes the foreground session. Since a process in the specified session may refuse to end, the only way to guarantee that the target session has ended is to wait for notification through the termination queue specified with DosStartSession.

Sample Code

#define DOS_SESMGR
#include <os2.h>

ULONG ulIDSession;
STATUSDATA sd;

/* Start child session with DosStartSession */
/* psd->Related = SSF_RELATED_CHILD; */
/* DosStartSession(psd,&ulIDSession,..); */

if(DosStopSession(STOP_SESSION_SPECIFIED, ulIDSession))   /* Establish the bond */
{
    /* Problems */
}
else
{
   /* The child session will end, unless it refuses, */
   /* check the termination queue from DosStartSession to be sure */
}

See Also