Print String to Standard Output Registers: ah = 9

ds:dx = Pointer to string to print

Returns: None

The character string at ds:dx is printed to the standard output device (which is usually the screen). The string must be terminated by a “$”

character, and may contain carriage returns, line feeds, etc.

Function 1AH: Set Disk Transfer Area Address Registers: ah = 1AH

ds:dx = New disk transfer area address

Returns: None

This function sets the Disk Transfer Area (DTA) address to the value given in ds:dx. It is meaningful only within the context of a given program.

When the program is terminated, etc., its DTA goes away with it. The default DTA is at offset 80H in the Program Segment Prefix (PSP).

Function 2FH: Read Disk Transfer Area Address

Registers: ah = 2FH

Returns: es:bx = Pointer to the current DTA

This is the complement of function 1A. It reads the Disk Transfer Area address into the register pair es:bx.

Function 31H: Terminate and Stay Resident Registers: ah = 31H

al = Exit code

dx = Memory size to keep, in paragraphs

Returns: (Does not return)

Function 31H causes a program to become memory resident (a TSR), remaining in memory and returning control to DOS. The exit code in al will be zero if the program is terminating successfully, and something else (programmer defined) to indicate that an error occurred. The register dx must contain the number of 16 byte paragraphs of memory that DOS should leave in memory when the program terminates. For example, if one wants to leave a 367 byte COM file in memory, one must save 367+256 bytes, or 39 paragraphs.(That doesn’t leave room for a stack, either.) Function 3DH: Open File

Registers: ah = 3DH

ds:dx = Pointer to an ASCIIZ path/file name al = Open mode

Returns: c = set if open failed

ax = File handle, if open was successful ax = Error code, if open failed

This function opens the file specified by the null terminated string at ds:dx, which may include a specific path. The value in al is broken out as follows:

Bit 7: Inheritance flag, I.

I=0 means the file is inherited by child processes I=1 means it is private to the current process.

Bits 4-6: Sharing mode, S.

S=0 is compatibility mode S=1 is exclusive mode S=2 is deny write mode S=3 is deny read mode S=4 is deny none mode.

Bit 3: Reserved, should be 0 Bit 0-2: Access mode, A.

A=0 is read mode A=1 is write mode A=2 is read/write mode

In this book we are only concerned with the access mode. For more information on sharing, etc., see IBM’s Disk Operating System Technical Reference or one of the other books cited in the references. The file handle returned by DOS when the open is successful may be any 16 bit number.

It is unique to the file just opened, and used by all subsequent file operations to reference the file.

Function 3EH: Close File Registers: ah = 3EH

bx = File handle of file to close Returns: c = set if an error occurs closing the file

ax = Error code in the event of an error

This closes a file opened by Function 3DH, simply by passing the file handle to DOS.

Function 3FH: Read from a File Registers: ah = 3FH

bx = File handle

cx = Number of bytes to read

ds:dx = Pointer to buffer to put file data in

Returns: c = set if an error occurs

ax = Number of bytes read, if read is successful ax = Error code in the event of an error

Function 3F reads cx bytes from the file referenced by handle bx into the buffer ds:dx. The data is read from the file starting at the current file pointer. The file pointer is initialized to zero when the file is opened, and updated every time a read or write is performed.

Function 40H: Write to a File Registers: ah = 40H

bx = File handle

cx = Number of bytes to write

ds:dx = Pointer to buffer to get file data from Returns: c = set if an error occurs

ax = Number of bytes written, if write is successful ax = Error code in the event of an error

Function 40H writes cx bytes to the file referenced by handle bx from the buffer ds:dx. The data is written to the file starting at the current file pointer.

Function 41H: Delete File Registers: ah = 41H

ds:dx = Pointer to ASCIIZ string of path/file to delete Returns: c = set if an error occurs

ax = Error code in the event of an error

This function deletes a file from disk, as specified by the path and file name in the null terminated string at ds:dx.

Function 42H: Move File Pointer Registers: ah = 42H

al = Method of moving the pointer bx = File handle

cx:dx = Distance to move the pointer, in bytes Returns: c = set if there is an error

ax = Error code if there is an error dx:ax = New file pointer value, if no error

Function 42H moves the file pointer in preparation for a read or write operation. The number in cx:dx is a 32 bit unsigned integer. The methods of moving the pointer are as follows: al=0 moves the pointer relative to the beginning of the file, al=1 moves the pointer relative to the current location, al=2 moves the pointer relative to the end of the file.

Function 43H: Get and Set File Attributes Registers: ah = 43H

al = 0 to get attributes, 1 to set them cl = File attributes, for set function

ds:dx = Pointer to an ASCIIZ path/file name Returns: c = set if an error occurs

ax = Error code when an error occurs cl = File attribute, for get function

The file should not be open when you get/set attributes. The bits in cl correspond to the following attributes:

Bit 0 - Read Only attribute Bit 1 - Hidden attrubute Bit 2 - System attribute Bit 3 - Volume Label attribute Bit 4 - Subdirectory attribute Bit 5 - Archive attribute Bit 6 and 7 - Not used

Function 47H: Get Current Directory Registers: ah = 47H

dl = Drive number, 0=Default, 1=A, 2=B, etc.

ds:si = Pointer to buffer to put directory path name in Returns: c = set if an error occurs

ax = Error code when an error occurs

The path name is stored in the data area at ds:si as an ASCIIZ null terminated string. This string may be up to 64 bytes long, so one should normally allocate that much space for this buffer.

Function 4EH: Find First File Search Registers: ah = 4EH

cl = File attribute to use in the search ds:dx = Pointer to an ASCIIZ path/file name

Returns: ax = Error code when an error occurs, or 0 if no error The ASCIIZ string at ds:dx may contain the wildcards * and ?. For example, “c:\dos\*.com” would be a valid string. This function will return with an error if it cannot find a file. No errors indicate that the search was successful. When successful, DOS formats a 43 byte block of data in the current DTA which is used both to identify the file found, and to pass to the Find Next function, to tell it where to continue the search from. The data in the DTA is formatted as follows:

Byte Size Description

0 21 Reserved for DOS Find Next

21 1 Attribute of file found

22 2 Time on file found

24 2 Date on file found 26 4 Size of file found, in bytes 30 13 File name of file found

The attribute is used in a strange way for this function. If any of the Hidden, System, or Directory attributes are set when Find Next is called, DOS will search for any normal file, as well as any with the specified attributes.

Archive and Read Only attributes are ignored by the search altogether. If the Volume Label attribute is specified, the search will look only for files with that attribute set.

Function 4FH: Find Next File Search

Registers: ah = 4FH

Returns: ax = 0 if successful, otherwise an error code

This function continues the search begun by Function 4E. It relies on the information in the DTA, which should not be disturbed between one call and the next. This function also modifies the DTA data block to reflect the next file found. In programming, one often uses this function in a loop until ax=18, indicating the normal end of the search.

Function 57H: Get/Set File Date and Time Registers: ah = 57H

al = 0 to get the date/time al = 1 to set the date/time bx = File Handle

cx = 2048*Hour + 32*Minute + Second/2 for set dx = 512*(Year-1980) + 32*Month + Day for set Returns: c = set if an error occurs

ax = Error code in the event of an error

cx = 2048*Hour + 32*Minute + Second/2 for get dx = 512*(Year-1980) + 32*Month + Day for get

This function gets or sets the date/time information for an open file. This information is normally generated from the system clock date and time when a file is created or modified, but the programmer can use this function to modify the date/time at will.

Inside the PC

——-, IBM Personal Computer AT Technical Reference (IBM Corpora-tion, Racine, WI) 1984. Chapter 5 is a complete listing of the IBM AT BIOS, which is the industry standard. With this, you can learn all of the intimate details about how the BIOS works. You have to buy the IBM books from IBM or an authorized distributor. Bookstores don’t carry them, so call your local distributor, or write to IBM at PO Box 2009, Racine, WI 53404 for a list of publications and an order form.

——-, IBM Disk Operating System Technical Reference (IBM Corpora-tion, Racine, WI) 1984. This provides a detailed description of all PC-DOS functions for the programmer, as well as memory maps, details on disk formats, FATs, etc., etc. There is a different manual for each version of PC-DOS.

——-, System BIOS for IBM PC/XT/AT Computers and Compatibles (Addison Wesley and Phoenix Technologies, New York) 1990, ISBN 0-201-51806-6 Written by the creators of the Phoenix BIOS, this book details all of the various BIOS functions and how to use them. It is a useful complement to the AT Technical Reference, as it discusses how the BIOS works, but it does not provide any source code.

Peter Norton, The Programmer’s Guide to the IBM PC (Microsoft Press, Redmond, WA) 1985, ISBN 0-914845-46-2. This book has been through several editions, each with slightly different names, and is widely available in one form or another.

Ray Duncan, Ed., The MS-DOS Encyclopedia (Microsoft Press, Red-mond, WA) 1988, ISBN 1-55615-049-0. This is the definitive encyclo-pedia on all aspects of MS-DOS. A lot of it is more verbose than necessary, but it is quite useful to have as a reference.

Michael Tischer, PC Systems Programming (Abacus, Grand Rapids, MI) 1990, ISBN 1-55755-036-0.

Andrew Schulman, et al., Undocumented DOS, A Programmer’s Guide to Reserved MS-DOS Functions and Data Structures (Addison Wesley, New York) 1990, ISBN 0-201-57064-5. This might be useful for you hackers out there who want to find some nifty places to hide things that you don’t want anybody else to see.

——-, Microprocessor and Peripheral Handbook, Volume I and II (Intel Corp., Santa Clara, CA) 1989, etc. These are the hardware manuals for most of the chips used in the PC. You can order them from Intel, PO Box 58122, Santa Clara, CA 95052.

Ralf Brown and Jim Kyle, PC Interrupts, A Programmer’s Reference to BIOS, DOS and Third-Party Calls (Addison Wesley, New York) 1991, ISBN 0-201-57797-6. A comprehensive guide to interrupts used by everything under the sun, including viruses.