DosSetSession: Difference between revisions

Latest revision as of 11:33, 12 October 2018

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.

Syntax

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.

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

Usage Explanation

DosSetSession can only be issued on child sessions started with DosStartSession, with Related set to SSF_RELATED_CHILD (=1).

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 INCL_DOSSESMGR
#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 */
}

@@ Line 1: / Line 1: @@
-;DosSetSession
+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.
 ==Syntax==
-rc = DosSetSession( ''ulIDSession'', ''psd'' );
+ 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.
+;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
-      SET_SESSION_UNCHANGED       Leaves current setting unchanged
-      SET_SESSION_SELECTABLE      Makes the target session selectable
-      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
-      SET_SESSION_UNCHANGED  Leaves current setting unchanged
-      SET_SESSION_BOND       The child sesion is brought to the foreground
-      SET_SESSION_NO_BOND    The parent session is brought to the foreground
 ==Returns==
- APIRET  rc
+;APIRET  rc
-      NO_ERROR
+  NO_ERROR
-    ERROR_SMG_INVALID_SESSION_ID
+ERROR_SMG_INVALID_SESSION_ID
-    ERROR_SMG_INVALID_CALL
+ERROR_SMG_INVALID_CALL
-    ERROR_SMG_INVALID_BOND_OPTION
+ERROR_SMG_INVALID_BOND_OPTION
-    ERROR_SMG_INVALID_SELECT_OPT
+ERROR_SMG_INVALID_SELECT_OPT
-    ERROR_SMG_PROCESS_NOT_PARENT
+ERROR_SMG_PROCESS_NOT_PARENT
-    ERROR_SMG_INVALID_DATA_LENGTH
+ERROR_SMG_INVALID_DATA_LENGTH
-    ERROR_SMG_RETRY_SUB_ALLOC
+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).
+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:
+Some bond examples:
   Parent process A
   A's child process B
@@ Line 64: / Line 41: @@
 ==Sample Code==
-  #define DOS_SESMGR
+<code>
+  #define INCL_DOSSESMGR
   #include <os2.h>
@@ Line 88: / Line 66: @@
       /* process is selected */
   }
+</code>
 ==See Also==