DosSetSession

Bindings:  C, MASM 

This call sets the status of a child session. 

 DosSetSession     (SessID, StatusData) 
 

 SessID (USHORT) - input 
    ID of the target session.  The value specified for SessID must have 
    been returned on a prior call to DosStartSession. 

 StatusData (PSTATUSDATA) - input 
    Address of the session status data structure: 

    length (USHORT) 
       Length of structure, including length. 

       6         Only valid value. 

    selectind (USHORT) 
       Specifies whether the target session is flagged as selectable or 
       non-selectable: The operator can continue to select a 
       non-selectable (bonded) windowed session by pressing a mouse button 
       within a visible part of the window. 

       Value     Definition 
       0         Leave current setting unchanged. 
       1         Selectable. 
       2         Non-selectable. 

    bondind (USHORT) 
       Specifies which session to bring to the foreground the next time 
       the parent session is selected. The operator may continue to select 
       a non-selectable (bonded) windowed session by pressing a mouse 
       button within a visible part of the window. 

       Value     Definition 

       0         Leave current setting unchanged. 

       1         Establish a bond between parent session and child 
                 session. The child session is brought to the foreground 
                 the next time the parent session is selected, or when the 
                 child session itself is selected. 

       2         Bring either the parent session to the foreground the 
                 next time the parent session is selected, or the child 
                 session if the child session is selected. Any bond 
                 previously established with a child session is broken. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    369       ERROR_SMG_INVALID_SESSION_ID 
    418       ERROR_SMG_INVALID_CALL 
    452       ERROR_SMG_SESSION_NOT_PARENT 
    455       ERROR_SMG_INVALID_BOND_OPTION 
    456       ERROR_SMG_INVALID_SELECT_OPT 
    461       ERROR_SMG_INVALID_DATA_LENGTH 
 
 Remarks 

 DosSetSession sets one or both of the following structure elements 
 related to a child session.  The elements can be set individually by the 
 parent session, and either one can be changed without affecting the 
 current setting of the other: 

 selectind 
           Sets the child session selectable or non-selectable. 
 bondind 
           Bonds the child session to the parent session. If the operator 
           selects the parent session from the Task Manager, the child 
           session is brought to the foreground. 
 

 These elements only affect selections made by the operator from the 
 switch list, not selections made by the parent session. When a parent 
 session selects its own session, the parent session is brought to the 
 foreground even if a bond is in effect.  When a parent session selects a 
 child session, the child session is brought to the foreground even if the 
 parent session had set the child session to be non-selectable. 

 DosSetSession may be issued by a process only for a child session it 
 started with a DosStartSession request, specifying Related=1. Neither the 
 parent session nor any grandchild session may be the target of 
 DosSetSession. 

 A bond established between a parent session and a child session can be 
 broken by reissuing DosSetSession and specifying either: 

 bondind = 2 
           Breaks the bond between the parent session and the child 
           session. 
 bondind = 1 
           Establishes a bond with a different child session.  In this 
           case the bond with the previous child session is broken. 
 

 Assume a bond is established between session A and its immediate child 
 session B.  Assume another bond is established between session B and its 
 immediate child session C.  Now if the operator selects session A, 
 session C is brought to the foreground.  However, if session A selects 
 its own session, session A is brought to the foreground. If session A 
 selects session B, session C is brought to the foreground. In the latter 
 case, the bond between B and C is honored. 

 Assume a bond is established between session A and its immediate child 
 session B, and assume B is non-selectable.  The operator cannot select 
 session B directly.  However, if the operator selects session A, session 
 B is brought to the foreground. 

 A parent session can run in either the foreground or background when 
 DosSetSession is issued.