Session manager API

This file describes the entries available through SESMGR.DLL. This file is not an official IBM document, and there is no warranty, neither by the author, nor by IBM that the information given here is correct or will apply to certain former, current, or future versions of OS/2. In other words: take this information, and don't ask.

General

The SESMGR.DLL is nowadays basically a forwarder DLL which propagates certain entries to the kernel. Maybe in former times this was a separate DLL, but today its functions are provided by OS2KRNL ("DOSCALLS.DLL").

The SESMGR API is pretty old, probably existing in OS/2 1.0 already, and thus most functions are 16 bit APIs. What you see and what you get through SESMGR.DLL is only the top of the iceberg; the kernel symbol table shows a lot of more SESMGR related functions; however these are not exported (by means of DOSCALLS entry points), so they are not usable, effectively. It appears that this API has been reduced to provide exactly the functions only that are required in certain programs, like TSHELL.EXE, PMMERGE.DLL, and HARDERR.EXE.

The general idea is the following: a single program, called the session shell or below, the shell owning the session manager will perform all session handling for the system. It will call DOSSMINITIALIZE and create a few notification threads (see Tshell description - to be published in the future) that control the way sessions will switched between foreground and background.

The session shell typically has a menue or alike to control how to dispatch sessions. In normal PM, this is what you can do with ALT-ESC and CTRL-ESC keys.

For switching between fullscreen sessions, as well as switching between FS and windowed mode of a DOS session, the session manager allows drivers to intercept the process before and after doing screen save/restore (this is actually what is needed for proper handling of switching between XFree86 and PM---in XFree86 it is emulated without SESMGR; thus it sometimes fails).

SESMGR also serializes error popups using screen locks, i. e. a process can ask the session manager to block change of sessions as long as it is displaying a modal box, for instance.

Exports

SESMGR exports the following entries:

SESMGR Ordinal	Name	DOSCALLS Ordinal	Type
1	DOSSMSGDOPOPUP	686	16bit
2	DOSSMSWITCH	687	16bit
3	DOSSMSERVEAPPREQ	688	16bit
4	DOSGETTIMES	689	16bit
5	DOSSMSETTITLE	690	16bit
6	DOSSCRUNLOCK	691	16bit
7	DOSSMDOAPPREQ	692	16bit
8	DOSSTOPSESSION	693	16bit
9	DOSSELECTSESSION	694	16bit
10	DOSSCRLOCK	695	16bit
11	DOSSAVREDRAWWAIT	696	16bit
12	DOSSAVREDRAWUNDO	697	16bit
13	DOSSMSGENDPOPUP	698	16bit
14	DOSSETSESSION	699	16bit
15	DOSSETMNLOCKTIME	700	16bit
16	DOSMODEUNDO	701	16bit
17	DOSSTARTSESSION	702	16bit
18	DOSSMGETSTATUS	703	16bit
19	DOSMODEWAIT	704	16bit
20	DOSSMTERMINATE	705	16bit
21	DOSSMGETAPPREQ	706	16bit
22	unused	--	--
23	DOSSMINITIALIZE	707	16bit
24	DOSSMSTART	708	16bit
25	DOSSMPARENTSWITCH	709	16bit
26	DOSSMPAUSE	710	16bit
27	DOSSMHDEINIT	711	16bit
28	DOSSMPMPRESENT	712	16bit
29	DOSSMREGISTERDD	713	16bit
30	DOSSMSYSINIT	855	offset
31	DOSSMNOTIFYDD	714	16bit
32	DOSSMNOTIFYDD2	715	16bit
33	DOSSMOPENDD	716	16bit
34	QHKEYBDHANDLE	856	offset
35	QHMOUSEHANDLE	857	offset
36	DOSSMSETSESSIONTYPE	717	16bit
37	DOS32STARTSESSION	669	32bit
38	DOS32SELECTSESSION	670	32bit
39	DOS32SETSESSION	671	32bit
40	DOS32STOPSESSION	672	32bit
41	DOSREGISTERNOTIFICATION	673	16bit

The following reflects the available knowledge about the API.

DOSSMSGDOPOPUP

Synopsis

APIRET16 Pascal far DOSSMSGDOPOPUP(short proc,short type,short pid,short scrn)

Description

Tell the session manager that some session wants to perform a popup.

Parameters

proc: process type (like with DosStartSession)
type: =0 clear screen before popup.
!=0 don't clear screen
pid: process id
scrn: screen group

DOSSMSWITCH

Synopsis

APIRET16 Pascal far DOSSMSWITCH(short cmd,short sessid,ULONG unknown)

Description

Request the session manager to switch to another foreground session. If PM is present, also internally call WinSetExtIdFocus. This can only be called by the shell that owns the Session Manager.

Parameters

cmd: =0 do a normal session switch
=1 switch to the next queued session
=2 don't save state of the current fg session
=3 don't restore state of current fg session
=4 ???
=5 similar to 4 ???
sessid: requested session id
unknown: must be 0

DOSSMSERVAPPREQ

Synopsis

APIRET16 Pascal far DOSSMSERVEAPPREQ()

Description

Process some application's request to start,stop,terminate,set a session. This can only be called by the shell that owns the Session Manager.

Parameters

No parameters.

DOSGETTIMES

Synopsis

APIRET16 Pascal far DOSGETTIMES(USHORT* time)

Description

Return the time value that has been set by DOSSETMNLOCKTIME. This can be called by any code.

Parameters

time: 16:16 pointer to the time value (short)

DOSSMSETTITLE

Synopsis

APIRET16 Pascal far DOSSMSETTITLE(char* title)

Description

This will set the title for the current screen group. This can be called by any code.

Parameters

title: 16:16 pointer to ASCIZ string.

DOSSCRUNLOCK

Synopsis

APIRET16 Pascal far DOSSCRUNLOCK()

Description

This is the complement of DOSSCRLOCK. See there.

Parameters

No Parameters. Can be called by any code.

DOSSMDOAPPREQ

Synopsis

APIRET16 Pascal far DOSSMDOAPPREQ(APPREQ* appreq)

Description

Perform an application request to start,stop, etc. a child session. This can only be called by the shell that owns the Session Manager.

Parameters

appreq

16:16 pointer to an appreq structure:

    struct APPREQ {
        short unknown;
        short length;       /* length of structure */
        short type;         /* request type */
        short rc;           /* return code */
        short sessid;       /* session id */
        short pid;          /* process id */
        short tid;          /* thread id */
        short flgs1;        /* flags 1 */
        long sema1;         /* semaphore 1 ? */
        long sema2;         /* semaphore 2 ? */
        long sema3;         /* semaphore 3 ? */
        short qstatus;      /* internal queueing status */
        short flgs2;        /* flags 2 */
        char param[1];      /* variable length data */
    };

whereas:

type: =0 start
=1 select
=2 set
=3 stop
flgs1: bit 0 called from 32 bit code
bit 1-6 seamless session bits ?
bit 7 VDM start session
bit 8 ?
flgs2: =0 terminate child
=1 terminate all children
param: variable length field to store different parameters depending on DosStart/Stop/Set/SelectSession

DOSSTOPSESSION

Synopsis

APIRET16 Pascal far DOSSTOPSESSION(short cmd,short sessid)

Description

This API is described in the 16 bit Control Program Reference

DOSSELECTSESSION

Synopsis

APIRET16 Pascal far DOSSELECTSESSION(short sessid)

Description

This API is described in the 16 bit Control Program Reference

DOSSCRLOCK

Synopsis

APIRET16 Pascal far DOSSCRLOCK(short wait,UCHAR* rc)

Description

This allows a process to lock the screen exclusively for itself, until it is DOSSCRUNLOCKed again. Other sessions will be sent into background, if they also request the screen.

Parameters

wait: =0 return directly
=1 wait until screen is available
rc: =0 lock succeeded
=1 lock failed

DOSSAVREDRAWWAIT

Synopsis

APIRET16 Pascal far DOSSAVREDRAWWAIT(short viohdl,short* ptr,short flag)

Description

This is a helper for performing screen save/restore operations. This will be called by the session manager to signal the thread that does save/restore what operation is to be done.

Parameters

viohdl: VIO Handle of the screen group
ptr: a pointer to an address (to signal save/restore thread what to do?)
flag: =0 do save and restore
=1 do only restore

DOSSAVREDRAWUNDO

Synopsis

APIRET16 Pascal far DOSSAVREDRAWUNDO(short viohdl,short kill, short flag)

Description

This will allow some code that originally called DOSSAVREDAWWAIT to stop save/restore operation, and/or kill the save/restore thread.

Parameters

viohdl: VIO Handle of the screen group
kill: =0 send an error code to save/restore thread
=1 terminate the save/restore thread
flag: =0 remain owner of the save/restore thread
=1 give up save/restore thread

DOSSMSGENDPOPUP

Synopsis

APIRET16 Pascal far DOSSMSGENDPOPUP(short sgid)

Description

Tell the session manager that some popup is pending.

Parameters

sgid: screen group

DOSSETSESSION

Synopsis

APIRET16 Pascal far DOSSETSESSION(short sessid, STATUSDATA* data)

Description

This API is described in the 16 bit Control Program Reference

DOSSETMNLOCKTIME

Synopsis

APIRET16 Pascal far DOSSETMNLOCKTIME(shorttime,short unknown)

Description

This allows the session shell to set a time for screen lock. during this time, screen groups can't be switched into background.

Parameters

time: time in seconds
unknown: does not seem to be used

DOSMODEUNDO

Synopsis

APIRET16 Pascal far DOSMODEUNDO(short viohdl,short kill, short flag)

Description

This function is similar to DOSSAVREDRAWUNDO, but does not control a save/restore thread, but the thread to change video modes.

Parameters

viohdl: VIO Handle of the screen group
kill: =0 send an error code to mode save/restore thread
=1 terminate the mode save/restore thread
flag: =0 remain owner of the mode save/restore thread
=1 give up mode save/restore thread

DOSSTARTSESSION

Synopsis

APIRET16 Pascal far DOSSTARTSESSION(...)

Description

This API is described in the 16 bit Control Program Reference

DOSSMGETSTATUS

Synopsis

APIRET16 Pascal far DOSSMGETSTATUS(short func,void far* data)

Description

Return status of screen groups. This can only be called by the shell that owns the Session Manager.

Parameters

func

function code
=0: return complete data
=1 return complete data (different ordering)
=2: return header data only (query how much space is needed)
=3: return specified screen group only

data

structure to return data

    struct header {
        short length_of_header; /*8 bytes*/
        short screen_group;     /*function 3*/
        short next_active_screengroup;
        short length_of_entry;
    };

    struct entry { /*for each screengroup one structure*/
        short screen_group_number;
        char screen_group_title[32];
        short is_selected;
        short child_screengroup;
        short type_of_screengroup;
        short parent_of_child;
        short next_child;
        short parent_screengroup;
        short type_of_group (FS/VIO/PM);
    };

DOSMODEWAIT

Synopsis

APIRET16 Pascal far DOSMODEWAIT(short viohdl,short*ptr,short flag)

Description

This is a helper for performing video mode save/restore operations. This will be called by the session manager to signal the thread that does save/restore what operation is to be done.

Parameters

viohdl: VIO Handle of the screen group
ptr: a pointer to an address (to signal save/restore thread what to do?)
flag: =0 do only restore
=1 do save and restore

DOSSMTERMINATE

Synopsis

APIRET16 Pascal far DOSSMTERMINATE(short sessionid,void* unknown)

Description

Call the session manager to terminate a session. This can only be called by the shell that owns the Session Manager.

Parameters

sessionid: session to terminate

DOSSMGETAPPREQ

Synopsis

APIRET16 Pascal far DOSSMGETAPPREQ(void far* reqblock)

Description

This is a callbackroutine to be called by the shell to receive requests to start/stop/set a session. It returns a request block for the request. This can only be called by the shell that owns the session manager.

Parameters

reqblock: address of a 16:16 pointer variable where the req will be returned.
structure see struct APPREQ above.

DOSSMINITIALIZE

Synopsis

APIRET16 Pascal far DOSSMINITIALIZE(void* args)

Description

This will initialize the session manager shell. The first process to call this will become the shell that owns the session manager. Further calls will fail.

Parameters

args

a structure

    struct initargs {
        short length; /*length of structure*/
        long* sem1;   /*address of a semaphore to notify
                        shell of a screen redraw*/
        long* sem2;   /*address of a semaphore to notify
                        that a FG session is terminated*/
        long unknown;
        short flag;   /*=0 no PM, =1 PM exists*/
    };

DOSSMSTART

Synopsis

APIRET16 Pascal far DOSSMSTART(short flag,short mode,short type,
char far* null1,char far* null2,
char far* args, short* sessid,
long unknown)

Description

This allows the shell to start a new session. This can only be called by the shell that owns the session manager. I am not sure about the parameter 'type': this seems to be missing in some cases.

Parameters

flag: save parent session
=0, yes
=1, no
mode: =0, start in foreground
=1, start in background
type: =0, normal session
=1, vio session
=2, windowed session
=3, VDM session
null1: must be null
null2: must be null
args: program arguments
sessid: the newly generated session id is returned
unknown: ?

DOSSMPARENTSWITCH

Synopsis

APIRET16 Pascal far DOSSMPARENTSWITCH(CX)

Description

This will switch to the parent session if a child terminates. The argument seems to be passed in the register CX:

Parameters

CX: session id of terminated session.

DOSSMPAUSE

Synopsis

APIRET16 Pascal far DOSSMPAUSE(short sgid)

Description

Process a CTRL-Numlock event (PAUSE).

Parameters

sgid: session id where the pause event occurred. I think this is just half of the actual code to which an internal thread handler named DOSSMPAUDAEMON belongs. There is no access to that code, though.

DOSSMHDEINIT

Synopsis

APIRET16 Pascal far DOSSMHDEINIT(?)

Description

I think this is the initialization routine for the HARDERR.EXE program which will interact with the session manager in some way.

DOSSMPMPRESENT

Synopsis

APIRET16 Pascal far DOSSMPMPRESENT(short* flag)

Description

Returns 1 into flag if Presentation Manager is present in the system.

Parameters

flag: variable to receive the result.

DOSSMREGISTERDD

Synopsis

APIRET16 Pascal far DOSSMREGISTERDD(void* data)

Description

This is the same entry as DOSREGISTERNOTIFICATION. This allows some driver (init!) to install a notification hook into the session manager to get events when some save/restore occurs. When the session manager is initialized, calls to this routine will be disabled.

Parameters

data

data structure

    struct notify {
        short length_of_struct;
        short flag;
          /* bitmap:
             0x0001 notification before save
             0x0002 notification after save
             0x0004 notification after restore
             0x0008 notification of termination of screengroup
             0x0010 notification of creation of screengroup
             0x0020 notification before switch of group
             0x0040 notification after switch of group
             0x0080 before ?
             0x0100 after ?
          */
        char far* name; /*name of device or DLL (ASCIZ)*/
    };

DOSSMSYSINIT

Synopsis

OFFSET DOSSMSYSINIT

Description

This is the offset to the DOSSMSYSINIT semaphore. I have no idea what code will need this. Probably synchronization between HARDERR and the session shell.

DOSSMNOTIFYDD

Synopsis

APIRET16 Pascal far DOSSMNOTIFYDD(short type,short newsgroup,short currsgroup)

Description

This will call HARDERR.EXE to issue an ioctl to the registered DDs for an incoming screen event. The IOCTL that will be called is category 0x0b, function 0x41.

Parameters

type: type of event. corresponds to the bitmap of DOSSMREGISTERDD.
newsgroup: screen group to be active next (after save)
currsgroup: current screen group

DOSSMNOTIFYDD2

Synopsis

APIRET16 Pascal far DOSSMNOTIFYDD2(short type,short newsgroup,short currsgroup)

Description

This will issue an ioctl to the registered DDs for an incoming screen event. The IOCTL that will be called is category 0x0b, function 0x41. In contrast to DOSSMNOTIFYDD, this is called directly (basically it will be called by the HARDERR.EXE daemon).

Parameters

type: type of event. corresponds to the bitmap of DOSSMREGISTERDD.
newsgroup: screen group to be active next (after save)
currsgroup: current screen group

DOSSMOPENDD

Synopsis

APIRET16 Pascal far DOSSMOPENDD()

Description

This is called by the session manager or HARDERR.EXE to open the registered drivers or DLLs for later notifications. If there is some other driver than the keyboard or mouse driver to receive notification, the HARDERR daemon seems to do the notifications. This function is exported for the HARDERR.EXE mainly.

QHKEYBDHANDLE

Synopsis

OFFSET QHKEYBDHANDLE

Description

This exports the offset to the handle for the keyboard (Kbd$)

QHMOUSEHANDLE

Synopsis

OFFSET QHMOUSEHANDLE

Description

This exports the offset to the handle for the mouse (mou$)

DOSSMSETSESSIONTYPE

Synopsis

APIRET16 Pascal far DOSSMSETSESSIONTYPE(short sessid,short type)

Description

This allows the shell to change the session type. It allows to change windowed VDM sessions to FS sessions and vice versa. This can be only called by the shell that owns the session manager.

Parameters

sessid: the session id to be changed
type: the new type
=4 FS VDM session
=7 windowed VDM session

DOS32STARTSESSION

Synopsis

APIRET APIENTRY32 DOS32STARTSESSION()

Description

This API is described in the 32 bit Control Program Reference

DOS32SELECTSESSION

Synopsis

APIRET APIENTRY32 DOS32SELECTSESSION()

Description

This API is described in the 32 bit Control Program Reference

DOS32SETSESSION

Synopsis

APIRET APIENTRY32 DOS32SETSESSION(ULONG sessid,STATUSDATA* data)

Description

This API is described in the 32 bit Control Program Reference

DOS32STOPSESSION

Synopsis

APIENTRY32 DOS32STOPSESSION(ULONG type,ULONG sessid)

Description

This API is described in the 32 bit Control Program Reference

DOSREGISTERNOTIFICATION

Synopsis

APIRET16 Pascal far DOSREGISTERNOTIFICATION(void* data)

Description

See DOSSMREGISTERDD

Don't ask me

Last modified: Mon Mar 12 11:06:15 MET 2001