DosSetSession

This call sets the status of a child session.

DosSetSession

(SessID, StatusData)

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.
rc (USHORT) - return
Return code descriptions are:
• 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.

  ---

  [Back: DosSetPrty]
  [Next: DosSetSigHandler]