DosSetSession (OS/2 1.x)

This call sets the status of a child session.

Syntax
DosSetSession (SessID, StatusData)

Parameters

 * 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

Return Code

 * 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.

C
 typedef struct _STATUSDATA {  /* stsdata */ USHORT Length;              /* length of this data structure */ USHORT SelectInd;           /* 0=leave setting unchanged, 1=selectable 2=non-selectable */ USHORT BondInd;             /* which session to bring to foreground */ } STATUSDATA;


 * 1) define INCL_DOSSESMGR

USHORT rc = DosSetSession(SessID, StatusData);

USHORT          SessID;        /* Session ID */ PSTATUSDATA     StatusData;    /* Session status data */

USHORT          rc;            /* return code */ 

MASM
 STATUSDATA struc stsdata_Length   dw  ? ;length of this data structure stsdata_SelectInd dw ? ;0=leave setting unchanged, 1=selectable ;2=non-selectable stsdata_BindInd  dw  ? ;which session to bring to foreground STATUSDATA ends

EXTRN DosSetSession:FAR INCL_DOSSESMGR     EQU 1

PUSH  WORD    SessID        ;Session ID PUSH@  OTHER   StatusData    ;Session status data CALL  DosSetSession

Returns WORD 