◄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
 
                                      ♦