Appendix G
INTERFACING TO THE DOS ENVIRONMENT

This appendix details some of the important functions that DOS provides for an application program.

Program Segment Prefix, Etc.

When DOS hands over control of the CPU to a .EXE program, some of the registers are preset with data. In order for the program to run, it must preset the CS:IP registers to index the start of the application program execution logic. The SS:SP stack area is preset. The data values in DS and ES will be predefined to index the Program Segment Prefix (PSP). Inside the PSP, there are two areas of general importance: the environment pointer at location 2CH and the command line data string starting at location 80H. The byte at location 80H tells how many bytes of command line data follow starting at 81H. The data word at 2CH is a segment offset to index the start of the environment passed by the calling process. The environment data area contains ASCII strings of information like PATH=C:\. The environment can be seen at the DOS prompt by entering the SET command.

Example:

From a DOS command prompt, you enter the following line:

DOS then tries to execute MODE.COM and passes the following ASCII data string in the PSP data area at DS:81H (note that the first character will be a space):

with the value 9 at 80H

DOS Calling

Most DOS calls are made through the INT 21H function calls. With a standard DOS function call, you preset register AH with a DOS function code value and the other registers with the necessary data for the called function. Then you execute an INT 21H instruction to pass control of the CPU to DOS until it finishes the task and returns to your program. In general, if it returns with the carry bit set in the Flag register, then the function failed.

A main function of the DOS is to assist in handling files. When an application program calls the DOS to open or create a file, the DOS returns a file handle to the program. This is a 16-bit data word that the program needs to keep track of. When the application tries to access an open file, DOS will require the file handle to reference the correct file. The basic file functions are:

Create

On entry, AH=3CH, CX=file attributes, DS:DX index ASCIIZ string. The file attribute information is defined as:
bit 0 - file is read only if set,
bit 1 - hidden file if set,
bit 2 - system file if set,
bit 3 - volume label entry if set, only valid in root directory,
bit 4 - subdirectory entry if set.
On exit, if no carry, then AX=file handle data else if carry, then there is an error code in AX: 3 path not found, 4 too many files open, 5 access denied.

Open

On entry, AH=3DH, AL=access code, DS:DX index ASCIIZ string. The access code is defined as: 0 to open for reading, 1 to open for writing, 2 to open for both reading and writing.

On exit, if no carry then AX=file handle else if carry then there is an error code in AX: 2 file not found, 4 there are too many files open, 5 access denied, 12 invalid access code.

Write

On entry, AH=40H, BX=file handle, CX=count of number of bytes to write, DS:DX file buffer index.
On exit, if no carry then AX has count of writing else if carry then there is an error code in AX: 5 invalid handle, 6 access denied.

Read

On entry, AH=3FH, BX=file handle, CX=count, DS:DX=file buffer index.
On exit, if no carry then AX has count of number of bytes read else if carry then there is an error code in AX: 5 invalid handle, 6 access denied.

Close

On entry, AH=3EH, BX=file handle.
On exit, if no carry then function OK else if carry then there is an error code in AX: 6 invalid handle.

Seek

On entry, AH=42H, AL=move type, BX=file handle, CX:DX=move distance. Move type: 0 move from the start of the file, 1 move from the current file position, 2 move from the end of file. Move type 2 can be used to find the end of the file for appending data or to find the file size.
On exit, if no carry then DX:AX=new position else if carry then there is an error code in AX: 1 invalid function, 6 invalid handle.