Notification Function 0002h Suspend Session

mov bx, SessionID ;current session identifier

les di, Service ;address of service-function handler

mov ax, 0002h ;Suspend Session

call [Notification] ;client program's notification-function handler

mov [Result], ax ;0 = session switch okay, 1 = do not switch

Suspend Session (Notification Function 0002h) notifies client programs that a session switch is about to take place, providing them a last opportunity to prevent the session switch.

Parameters

SessionID

Identifies the session to be suspended.

Service

Points to the service-function handler for the task switcher. A client program can use this address to call the task switcher's service functions, such as Test Memory Region (Service Function 0001h).

Return Value

The AX register contains 0000h if a session switch can be performed safely or 0001h if it cannot.

All other values are reserved.

Comment

If all client programs return 0000h to Query Suspend (Notification Function 0001h), the task switcher disables interrupts and calls Suspend Session, providing clients with a final chance to prevent the session switch. Client programs must not issue software interrupts or make any calls that might enable interrupts.

If all client programs return with 0000h in the AX register, the task switcher replaces the current interrupt-vector table with a saved copy before enabling interrupts. The saved copy represents the global state present when the task switcher first started. This guarantees that interrupt handlers local to the session being suspended will not be called in the interim between when Suspend Session returns to the task switcher and the next call is made to Activate Session (Notification Function 0003h). This prevents programs in local memory from gaining control on a hardware interrupt and making a call into programs in global memory before the global programs receive the resumed session's identifier.

Client programs in global memory can receive interrupts between the Suspend Session and Activate Session notifications but should not assume the contents of nonglobal memory if they do. Test Memory Region (Service Function 0001h) is used to determine whether a block of memory is local or global.

Before preventing a session switch because of the state of an asynchronous API, a client program should call Query API Support (Service Function 0006h) to determine that the API is not being handled by another client program.

If any client program returns a nonzero value to Suspend Session, all client programs may receive a call to Session Active (Notification Function 0004h), including the client program that returned nonzero. Client programs can ignore a call to Session Active received without a preceding call to Query Suspend (Notification Function 0001h) or Suspend Session.

The task switcher disables interrupts before calling the client program, and the client program must not enable them or call MS-DOS system functions. Although the client program modifies the AX register, it must preserve all other registers.