DosSetSession (OS/2 1.x)

Description

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:

length (USHORT) : Length of structure, including length.

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.

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.

Example Code

C Binding

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 Binding

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

Related Functions