File buffers are flushed and any open handles for files or devices owned by the process are closed.Terminates execution of the currently executing program, passing a return code to the parent process, but reserves part or all of the program's memory so that it will not be overlaid by the next transient program to be loaded. MS-DOS then takes the following actions:
File buffers are flushed and any open handles for files or devices owned by the process are closed.
The termination handler vector (Int 22H) is restored from PSP:000AH.
The Ctrl-C handler vector (Int 23H) is restored from PSP:000EH.
[2.0+] The critical-error handler vector (Int 24H) is restored from PSP:0012H.
Control is transferred to the termination handler.
If the program is returning to COMMAND.COM, control transfers to the resident portion, and the transient portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and interpreted; otherwise, a prompt is issued for the next user command.
Call with:
AH = 31H
AL = return code
DX = amount of memory to reserve (in paragraphs)
Returns:
Nothing
Notes:
This function call is typically used to allow user-written utilities, drivers, or interrupt handlers to be loaded as ordinary .COM or .EXE programs and then remain resident. Subsequent entrance to the code is via a hardware or software interrupt.
This function attempts to set the initial memory allocation block to the length in paragraphs specified in register DX. If other memory blocks have been requested by the application using Int 21H Function 48H, they will not be released by this function.
Other methods of performing a final exit are:
Int 20H
Int 21H Function 00H
Int 21H Function 4CH
Int 27H
The return code may be retrieved by a parent process with Int 21H Function 4DH (Get Return Code). It can also be tested in a batch file with an IF ERRORLEVEL statement. By convention, a return code of zero indicates successful execution, and a nonzero return code indicates an error.
This function should not be called by .EXE programs that are loaded at the high end of the transient program area (that is, linked with the /HIGH switch) because doing so reserves the memory that is normally used by the transient part of COMMAND.COM. If COMMAND.COM cannot be reloaded, the system will fail.
[2.0+] This function should be used in preference to Int 27H because it supports return codes, allows larger amounts of memory to be reserved, and does not require CS to contain the segment of the program segment prefix.
[3.0+] If the program is running on a network, it should remove all locks it has placed on file regions before terminating.
Example:
Exit with a return code of 1 but stay resident, reserving 16 KB of memory starting at the program segment prefix of the process.
.
.
.
mov ah,31h ; function number
mov al,1 ; return code for parent
mov dx,0400h ; paragraphs to reserve
int 21h ; transfer to MS-DOS
.
.
.