Important Notice
The pages on this site contain documentation for very old MS-DOS software,
purely for historical purposes.
If you're looking for up-to-date documentation, particularly for programming,
you should not rely on the information found here, as it will be woefully
out of date.
DosExitList (1.2)
◄Function Group► ◄Overview► ◄Changes► ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
#define INCL_DOSPROCESS
USHORT DosExitList(fFnCode, pfnFunction)
USHORT fFnCode; /* function code */
PFNEXITLIST pfnFunction(USHORT); /* pointer to address of function */
The DosExitList function specifies a function that is executed when the
current process ends. This "termination function" can define additional
termination functions. The DosExitList function can be called one or more
times: each call adds or subtracts a function from an internal list
maintained by the system. When the current process terminates, MS OS/2
transfers control to each function in the list.
Parameter Description
────────────────────────────────────────────────────────────────────────────
fFnCode Specifies whether a function's address is added to or removed
from the list. If the function is added, the high byte of this
parameter specifies the order in which the function should be
called. The exit-list routines with a low-order high byte will
be called before those with a high-order high byte. The low
byte of this parameter can be one of the following values:
Value Meaning
───────────────────────────────────────────────────────────────
EXLST_ADD Adds the function to the termination list. If
this flag is specified, the high byte of the
parameter specifies the order in which the
function is called. It can be a value from 0
through 255. A value of 0 specifies that this
function is to be called first. In the event of
duplicate order numbers, the last function added
with the duplicate order number is called before
the first function added with the duplicate order
number.
EXLST_EXIT Termination processing is complete. Calls the
next function on the termination list.
EXLST_REMOVE Removes the function from the termination list.
pfnFunction Points to the termination function to be added to the list. For
a full description, see the following "Comments" section.
Return Value
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
ERROR_INVALID_DATA
ERROR_NOT_ENOUGH_MEMORY
Comments
When adding an exit-list function, it is important that the exit-list
function not call any system functions with a lower exit-list order. The
order is determined by the high-byte of the fFnCode parameter. The following
list defines the orders of the various system components:
Order Component
────────────────────────────────────────────────────────────────────────────
0x80-0x88 Extended Edition Database Manager
0x90-0x98 Extended Edition Communication Manager
0xA0-0xA8 Presentation Manager
0xB0 KBD component
0xC0 VIO component
0xD0 IPC Queues component
Dynamic-link-library modules often use the DosExitList function. It allows
dynamic-link-library modules to free resources or clear flags and semaphores
if the client process terminates without notifying them.
The termination function has one parameter and no return value. The function
should have the following form:
VOID PASCAL FAR FuncName(usTermCode)
USHORT usTermCode;
{
.
.
.
DosExitList(EXLST_EXIT, (PFNEXITLIST) NULL);
}
The usTermCode parameter of the termination function specifies the reason
the process ended. This parameter can be one of the following values:
Value Meaning
────────────────────────────────────────────────────────────────────────────
TC_EXIT Normal exit
TC_HARDERROR Hard-error abort
TC_KILLPROCESS Unintercepted DosKillProcess
TC_TRAP Trap operation
Before transferring control to the termination function, MS OS/2 resets the
stack to its initial value. MS OS/2 then passes control to the function by
using a jmp instruction. The termination function should carry out its tasks
and then call the DosExitList function with the fFnCode parameter set to
EXLST_EXIT. This parameter setting directs the system to call the next
function on the termination list. When all functions on the list have been
called, the process ends.
Termination functions should be as short and fail-safe as possible. Before
the termination functions are executed, all threads except for the one
executing the DosExitList function are destroyed. Note that a termination
function must call the DosExitList function to end; otherwise, the process
"hangs" because MS OS/2 cannot terminate it.
A termination function can call most MS OS/2 system functions; however, it
must not call the DosCreateThread or DosExecPgm function.
Example
This example calls DosExitList, which then adds the locally defined function
CleanUp to the list of routines to be called when the process terminates.
The CleanUp function displays a message that it is cleaning up, and then
calls DosExitList, reporting that it has finished and that the next function
on the termination list can be called.
/* Add the function, and have it be called last. */
DosExitList(EXLST_ADD | 0xFF00, CleanUp);
.
.
.
DosExit(EXIT_PROCESS, 0);
}
VOID PASCAL FAR CleanUp(usTermCode)
USHORT usTermCode;
{
VioWrtTTY("Cleaning up...\r\n", 16, 0);
.
.
.
DosExitList(EXLST_EXIT, /* termination complete */
(PFNEXITLIST) NULL);
}
See Also
DosCreateThread, DosExecPgm, DosExit, DosKillProcess
♦