DosSetSession

DosSetSession

Syntax

rc = DosSetSession( ulIDSession, psd );

Parameters

ULONG ulIDSession (input)

The ID of the child session to set the status for.

PSTATUSDATA psd (input)

Pointer to a STATUSDATA structure.

USHORT psd->Length (input)

Length of STATUSDATA in bytes. Always 6(=sizeof(STATUSDATA)).

USHORT psd->SelectInd (input)

Specifies whether the target session should be selectable or non-selectable, ie not selectable from the Shell switch, nor can the user jump to it via the system hot key. It is though still possible to select a windowed session by pressing the mouse button within the window. Values are:

Value  Name                        Description
0      SET_SESSION_UNCHANGED       Leaves current setting unchanged
1      SET_SESSION_SELECTABLE      Makes the target session selectable
2      SET_SESSION_NON_SELECTABLE  Makes the target session non-selectable

USHORT psd->BondInd (input)

Specifies which session to bring to the foreground the next time the parent session is selected, the child session or the parent session. Values are:

Value  Name                   Description
0      SET_SESSION_UNCHANGED  Leaves current setting unchanged
1      SET_SESSION_BOND       The child sesion is brought to the foreground
2      SET_SESSION_NO_BOND    The parent session is brought to the foreground

Returns

APIRET  rc
0       NO_ERROR
369     ERROR_SMG_INVALID_SESSION_ID
418     ERROR_SMG_INVALID_CALL
455     ERROR_SMG_INVALID_BOND_OPTION
456     ERROR_SMG_INVALID_SELECT_OPT
460     ERROR_SMG_PROCESS_NOT_PARENT
461     ERROR_SMG_INVALID_DATA_LENGTH
463     ERROR_SMG_RETRY_SUB_ALLOC

Include Info

#define INCL_DOSSESMGR
#include <os2.h>

Usage Explanation

DosSetSession can set two status fields of a child session; selectable/non-selectable which specifies whether the child session will appear in the task list, and bond/no bond which specifies whether the parent or the child session will come to the foreground when the parent session is selected, this does not affect the parent sessions selections of foreground session. DosSetSession can only be issued on child sessions started with DosStartSession, with Related set to SSF_RELATED_CHILD (=1).

Relevant Structures

typedef struct _STATUSDATA
{
  USHORT Length;
  USHORT SelectInd;
  USHORT BondInd;
} STATUSDATA, *PSTATUSDATA;

Gotchas

Some bond examples:
Parent process A
A's child process B
B's child process C
<-> bond
-X- no bond

A<->B<->C
A is selected => C is in the foreground

A-X-B<->C
A selects B => C is in the foreground

A<->B
B is non-selectable.
A is selected => B is in the foreground

Sample Code

#define DOS_SESMGR
#include <os2.h>

ULONG ulIDSession;
STATUSDATA sd;

/* Start child session with DosStartSession */
/* psd->Related = SSF_RELATED_CHILD; */
/* DosStartSession(psd,&ulIDSession,..); */

sd.Length = 6;                         /* = sizeof(STATUSDATA) */
sd.SelectInd = SET_SESSION_UNCHANGED;  /* Do not change the selectability  */
sd.BondInd = SET_SESSION_BOND;         /* Want to establish a bond between */
                                       /* the parent and the child session */

if(DosSetSession(ulIDSession, &sd))    /* Establish the bond */
{
    /* Problems */
}
else
{
    /* The child session will now appear in the foreground when the parent */
    /* process is selected */
}

See Also

• DosStartSession, DosStopSession, DosSelectSession