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.

Binding

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;

#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