ax register contains one of the following error codes:7- Memory control blocks destroyed 8- Insufficient memory 9- Invalid memory block address
Additional notes about these errors will be discussed as appropriate.
Function (ah): 48h
Entry parameters: bx- Requested block size (in paragraphs)
Exit parameters: If no error (carry clear):
ax:0 points at allocated memory block
If an error (carry set):
bx- maximum possible allocation size
ax- error code (7 or 8)
This call is used to allocate a block of memory. On entry into DOS, bx contains the size of the requested block in paragraphs (groups of 16 bytes). On exit, assuming no error, the ax register contains the segment address of the start of the allocated block. If an error occurs, the block is not allocated and the ax register is returned containing the error code. If the allocation request failed due to insufficient memory, the bx register is returned containing the maximum number of paragraphs actually available.
Function (ah): 49h Entry parameters: es:0- Segment address of block to be deallocated Exit parameters: If the carry is set, ax contains the error code (7,9)
This call is used to deallocate memory allocated via function 48h above. The es register cannot contain an arbitrary memory address. It must contain a value returned by the allocate memory function. You cannot use this call to deallocate a portion of an allocated block. The modify allocation function is used for that operation.
Function (ah): 4Ah
Entry parameters: es:0- address of block to modify allocation size
bx- size of new block
Exit parameters: If the carry is set, then
ax contains the error code 7, 8, or 9
bx contains the maximum size possible (if error 8)
This call is used to change the size of an allocated block. On entry, es must contain the segment address of the allocated block returned by the memory allocation function. Bx must contain the new size of this block in paragraphs. While you can almost always reduce the size of a block, you cannot normally increase the size of a block if other blocks have been allocated after the block being modified. Keep this in mind when using this function.
| Function # (AH) | Input Parameters | Output Parameters | Description |
|---|---|---|---|
| 58h | al-0
|
ax- strategy
|
Get Allocation Strategy: Returns the current allocation strategy in ax (see table below for details). |
| 58h | al-1
bx- strategy
|
- | Set Allocation Strategy: Sets the MS-DOS allocation strategy to the value specified in bx (see the table below for details). |
| 58H | al- 2
|
al- link flag
|
Get Upper Memory Link: Returns true/false (1/0) in al to determine whether a program can allocate memory in the upper memory blocks. |
| 58h | al- 3
bx- link flag (0=no link, 1=link okay).
|
- | Set Upper Memory Link: Links or unlinks the upper memory area. When linked, an application can allocate memory from the UMB (using the normal DOS allocate call). |
| Value | Name | Description |
|---|---|---|
| 0 | First Fit Low | Search conventional memory for the first free block of memory large enough to satisfy the allocation request. This is the default case. |
| 1 | Best Fit Low | Search conventional memory for the smallest block large enough to satisfy the request. |
| 2 | Last Fit Low | Search conventional memory from the highest address downward for the first block large enough to satisfy the request. |
| 80h | First Fit High | Search high memory, then conventional memory, for the first available block that can satisfy the allocation request. |
| 81h | Best Fit High | Search high memory, then conventional memory for the smallest block large enough to satisfy the allocation request. |
| 82h | Last Fit High | Search high memory from high addresses to low, then conventional memory from high addresses to low, for the first block large enough to satisfy the request. |
| 40h | First Fit Highonly | Search high memory only for the first block large enough to satisfy the request. |
| 41h | Best Fit Highonly | Search high memory only for the smallest block large enough to satisfy the request. |
| 42h | Last Fit Highonly | Search high memory only, from the end of memory downward, for the first block large enough to satisfy the request. |
These different allocation strategies can have an impact on system performance. For an analysis of different memory management strategies, please consult a good operating systems theory text.
Function (ah): 4Ch Entry parameters: al- return code Exit parameters: Does not return to your program
This is the function call normally used to terminate your program. It returns control to the calling process (normally, but not necessarily, DOS). A return code can be passed to the calling process in the al register. Exactly what meaning this return code has is entirely up to you. This return code can be tested with the DOS "IF ERRORLEVEL return code" command in a DOS batch file. All files opened by the current process will be automatically closed upon program termination.
Note that the UCR Standard Library function "ExitPgm" is simply a macro which makes this particular DOS call. This is the normal way of returning control back to MS-DOS or some other program which ran the currently active application.
Function (ah): 31h
Entry parameters: al- return code
dx- memory size, in paragraphs
Exit parameters: does not return to your program
This function also terminates program execution, but upon returning to DOS, the memory in use by the process is not returned to the DOS free memory pool. Essentially, the program remains in memory. Programs which remain resident in memory after returning to DOS are often called TSRs (terminate and stay resident programs).
When this command is executed, the dx register contains the number of memory paragraphs to leave around in memory. This value is measured from the beginning of the "program segment prefix", a segment marking the start of your file in memory. The address of the PSP (program segment prefix) is passed to your program in the ds register when your program is first executed. You'll have to save this value if your program is a TSR[6].
Programs that terminate and stay resident need to provide some mechanism for restarting. Once they return to DOS they cannot normally be restarted. Most TSRs patch into one of the interrupt vectors (such as a keyboard, printer, or serial interrupt vector) in order to restart whenever some hardware related event occurs (such as when a key is pressed). This is how "pop-up" programs like SmartKey work.
Generally, TSR programs are pop-ups or special device drivers. The TSR mechanism provides a convenient way for you to load your own routines to replace or augment BIOS' routines. Your program loads into memory, patches the appropriate interrupt vector so that it points at an interrupt handler internal to your code, and then terminates and stays resident. Now, when the appropriate interrupt instruction is executed, your code will be called rather than BIOS'.
There are far too many details concerning TSRs including compatibility issues, DOS re-entrancy issues, and how interrupts are processed, to be considered here. Additional details will appear in a later chapter.
Function (ah): 40h
Entry parameters: ds:dx- pointer to pathname of program to execute
es:bx- Pointer to parameter block
al- 0=load and execute, 1=load only, 3=load overlay.
Exit parameters: If carry is set, ax contains one of the following error codes:
1- invalid function
2- file not found
5- access denied
8- not enough memory
10- bad environment
11- bad format
The execute (exec) function is an extremely complex, but at the same time, very useful operation. This command allows you to load or load and execute a program off of the disk drive. On entry into the exec function, the ds:dx registers contain a pointer to a zero terminated string containing the name of the file to be loaded or executed, es:bx points at a parameter block, and al contains zero or one depending upon whether you want to load and execute a program or simply load it into memory. On return, if the carry is clear, then DOS properly executed the command. If the carry flag is set, then DOS encountered an error while executing the command.
The filename parameter can be a full pathname including drive and subdirectory information. "B:\DIR1\DIR2\MYPGM.EXE" is a perfectly valid filename (remember, however, it must be zero terminated). The segmented address of this pathname is passed in the ds:dx registers.
The es:bx registers point at a parameter block for the exec call. This parameter block takes on three different forms depending upon whether a program is being loaded and executed (al=0), just loaded into memory (al=1), or loaded as an overlay (al=3).
If al=0, the exec call loads and executes a program. In this case the es:bx registers point at a parameter block containing the following values:
Offset Description 0 A word value containing the segment address of the default environment (usually this is set to zero which implies the use of the standard DOS environment). 2 Double word pointer containing the segment address of a command line string. 6 Double word pointer to default FCB at address 5Ch 0Ah Double word pointer to default FCB at address 6Ch
The environment area is a set of strings containing default pathnames and other information (this information is provided by DOS using the PATH, SET, and other DOS commands). If this parameter entry contains zero, then exec will pass the standard DOS environment on to the new procedure. If non-zero, then this parameter contains the segment address of the environment block that your process is passing on to the program about to be executed. Generally, you should store a zero at this address.
The pointer to the command string should contain the segmented address of a length prefixed string which is also terminated by a carriage return character (the carriage return character is not figured into the length of the string). This string corresponds to the data that is normally typed after the program name on the DOS command line. For example, if you're executing the linker automatically, you might pass a command string of the following form:
CmdStr byte 16,"MyPgm+Routines /m",0dh
The second item in the parameter block must contain the segmented address of this string.
The third and fourth items in the parameter block point at the default FCBs. FCBs are used by the obsolete DOS filing commands, so they are rarely used in modern application programs. Since the data structures these two pointers point at are rarely used, you can point them at a group of 20 zeros.
Example: Format a floppy disk in drive A: using the FORMAT.EXE command
mov ah, 4Bh
mov al, 0
mov dx, seg PathName
mov ds, dx
lea dx, PathName
mov bx, seg ParmBlock
mov es, bx
lea bx, ParmBlock
int 21h
.
.
.
PathName byte 'C:\DOS\FORMAT.EXE',0
ParmBlock word 0 ;Default environment
dword CmdLine ;Command line string
dword Dummy,Dummy ;Dummy FCBs
CmdLine byte 3,' A:',0dh
Dummy byte 20 dup (?)
MS-DOS versions earlier than 3.0 do not preserve any registers except cs:ip when you execute the exec call. In particular, ss:sp is not preserved. If you're using DOS v2.x or earlier, you'll need to use the following code:
;Example: Format a floppy disk in drive A: using the FORMAT.EXE command
<push any registers you need preserved>
mov cs:SS_Save, ss ;Save SS:SP to a location
mov cs:SP_Save, sp ; we have access to later.
mov ah, 4Bh ;EXEC DOS opcode.
mov al, 0 ;Load and execute.
mov dx, seg PathName ;Get filename into DS:DX.
mov ds, dx
lea dx, PathName
mov bx, seg ParmBlock ;Point ES:BX at parameter
mov es, bx ; block.
lea bx, ParmBlock
int 21h
mov ss, cs:SS_Save ;Restore SS:SP from saved
mov sp, cs:SP_Save ; locations.
<Restore registers pushed onto the stack>
.
.
.
SS_Save word ?
SP_Save word ?
.
.
.
PathName byte 'C:\DOS\FORMAT.EXE',0
ParmBlock word 0 ;Default environment
dword CmdLine ;Command line string
dword Dummy,Dummy ;Dummy ;FCBs
CmdLine byte 3,' A:',0dh
Dummy byte 20 dup (?)
SS_Save and SP_Save must be declared inside your code segment. The other variables can be declared anywhere.
The exec command automatically allocates memory for the program being executed. If you haven't freed up unused memory before executing this command, you may get an insufficient memory error. Therefore, you should use the DOS deallocate memory command to free up unused memory before attempting to use the exec command.
If al=1 when the exec function executes, DOS will load the specified file but will not execute it. This function is generally used to load a program to execute into memory but give the caller control and let the caller start that code. When this function call is made, es:bx points at the following parameter block:
Offset Description
0 Word value containing the segment address of the environment block for the
new process. If you want to use the parent process' environment block set
this word to zero.
2 Dword pointer to the command tail for this operation. The command tail is the
command line string which will appear at location PSP:80.
6 Address of default FCB #1. For most programs, this should point at a block of
20 zeros (unless, of course, you're running a program which uses FCBs.).
0Ah Address of default FCB #2. Should also point at a block of 20 zeros.
0Eh SS:SP value. You must load these four bytes into SS and SP before starting
the application.
12h CS:IP value. These four bytes contain the starting address of the program.
The SSSP and CSIP fields are output values. DOS fills in the fields and returns them in the load structure. The other fields are all inputs which you must fill in before calling the exec function with al=1.
When you execute the exec command with al=-3, DOS simply loads an overlay into memory. Overlays generally consist of a single code segment which contains some functions you want to execute. Since you are not creating a new process, the parameter block for this type of load is much simpler than for the other two types of load operations. On entry, es:bx must point at the following parameter block in memory:
Offset Description
0 Word value containing the segment address of where this file is going
to be loaded into memory. The file will be loaded at offset zero within
this segment.
2 Word value containing a relocation factor for this file.
Unlike the load and execute functions, the overlay function does not automatically allocate storage for the file being loaded. Your program has to allocate sufficient storage and then pass the address of this storage block to the exec command (though the parameter block above). Only the segment address of this block is passed to the exec command, the offset is always assumed to be zero. The relocation factor should also contain the segment address for ".EXE" files. For ".COM" files, the relocation factor parameter should be zero.
The overlay command is quite useful for loading overlays from disk into memory. An overlay is a segment of code which resides on the disk drive until the program actually needs to execute its code. Then the code is loaded into memory and executed. Overlays can reduce the amount of memory your program takes up by allowing you to reuse the same portion of memory for different overlay procedures (clearly, only one such procedure can be active at any one time). By placing seldom-used code and initialization code into overlay files, you can help reduce the amount of memory used by your program file. One word of caution, however, managing overlays is a very complex task. This is not something a beginning assembly language programmer would want to tackle right away. When loading a file into memory (as opposed to loading and executing a file), DOS does not scramble all of the registers, so you needn't take the extra care necessary to preserve the ss:sp and other registers.
The MS-DOS Encyclopedia contains an excellent description of the use of the exec function.