Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►  ◄Changes►               ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSSESMGR
 
USHORT DosStartSession(pstdata, pidSession, ppid)
PSTARTDATA pstdata;    /* pointer to structure with session data     */
PUSHORT pidSession;    /* pointer to variable for session identifier */
PUSHORT ppid;          /* pointer to variable for process identifier */
 
The DosStartSession function starts a session (screen group) and specifies
which program to start in that session. This function creates an independent
session or a child session, depending on the value of the Related field in
the STARTDATA structure.
 
Parameter   Description
────────────────────────────────────────────────────────────────────────────
 
pstdata     Points to the STARTDATA structure that contains data describing
            the session to start.
 
pidSession  Points to the variable that receives the identifier of the child
            session.
 
ppid        Points to the variable that receives the process identifier of
            the child process.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value.
 
Comments
 
The MS OS/2 session manager writes a data element into the specified queue
when the child session created by the DosStartSession function terminates. A
parent session can be notified when a child session has terminated by using
the DosReadQueue function. When the child session terminates, the request
value returned by DosReadQueue is zero, and the data-element format consists
of two unsigned values: the session identifier and the result code.
 
Only the process that calls the DosStartSession function should call the
DosReadQueue function. Only this process can address the notification data
element. After reading and processing the data element, the calling process
must use the DosFreeSeg function to free the segment that contains the data
element.
 
A child session is created when the Related field of the STARTDATA structure
is set to TRUE.
 
The process identifier of the child process cannot be used with MS OS/2
functions, such as DosSetPrty, that require a parent process/child process
relationship.
 
An independent session is created when the Related field of the STARTDATA
structure is set to FALSE. An independent session is not under the control
of the starting session. The DosStartSession function does not copy session
and process identifiers for an independent session to the pidSession and
ppid parameters.
 
New sessions can be started in the foreground only when the caller's session
(or one of the caller's descendant sessions) is currently executing in the
foreground. The new session appears in the shell switch list.
 
See Also
 
DosCreateQueue, DosExecPgm, DosFreeSeg, DosReadQueue, DosSelectSession,
DosSetPrty, DosSetSession, DosStopSession, STARTDATA
 
                                      ♦